engine/paper_ink library

The Paper & ink family (spec §5.3 #11; motion brief §2.3 "Paper & ink"): stationery and editorial print. Pure Dart: part of the generator, so every constant here is part of the family's engine-v3 definition and must not change once a build ships it.

  • Sheet (the background, BackgroundKind.paperSheet): cream laid, white bond, newsprint, kraft or blue engineering paper, or for dark themes indigo-black ink paper and a slate blackboard (PaperSheet). Plain, ruled, graph or dot-grid, with a static, hash-derived grain of flecks and fibres (paper_ink_scene.dart). colors = [paper, rule ink]; pattern = the layout (none / stripes = ruled / grid / dots); patternScaleCdp = the line pitch; patternOpacityPermille = the line alpha (minor lines of a grid); angleTenths = the grain strength g (0–1000 ‰); patternColor is always 0 (the rule colour is colors[1], which lerps).
  • Ink: one near-neutral ink (blue-black, carbon, sepia or green- black on light sheets; cream gel or chalk on dark ones) for every key's hand-drawn outline (KeyColors.edge, ≥ 3:1 on every sheet sample), the labels, the display text, the focus ring and the operator hatching. palette.shadow is the ink (opaque; never painted as a shadow), palette.highlight the ink wash's tide-line colour at its peak alpha.
  • Keys: paper slips a shade whiter than the sheet (cream card on kraft; a shade lighter than the sheet on dark ones), pale blue-grey function slips, operators washed with the stamp ink (or its ±30° neighbour; never olive or brown on the dark sheets, where 30°–70° turns wine) inside a hatched ink frame — the recorded non-colour cue, OperatorCue.pattern — and a = rubber stamp in one accent ink (vermilion, crimson, ultramarine, Prussian blue, viridian, methyl violet, madder; peacock and burnt sienna on dark sheets) whose label is knocked out to the slip / sheet colour.
  • Display: an opaque ledger panel (ruled sheets) or a torn index card (palette.surface) with the paper grain, feint rules in its upper part and a red-pen margin rule; its text is checked against the panel and the panel's grain and rule composites (paperInkDisplayBackdrops).

Every draw comes from the generator's named sub-streams (palette and its retry streams, background, shape, style, type, motion, name), each a fixed number of draws whatever the sheet, so a theme is a pure function of (seed, engineVersion, accessible).

Enums

PaperInkType
The inks.
PaperSheet
The paper sheets (light ones first). The palette stream draws the brightness, then the sheet, then the tone of the dark sheets.
PaperStampInk
The stamp inks (the = face, the accent, the seed colour and the name accent).

Constants

paperDisplayRuleAlpha → const int
Feint-rule alpha (of 255) on the display panel; none under the Accessible lock.
paperFaceGrainPermille → const int
The paper grain on key slips and the display panel, ‰ of g.
paperFibreMaxPermille → const int
paperFleckMaxPermille → const int
Grain tile ceilings: black flecks and fibres are drawn at ≤ 20 % and white fibres / chalk dust at ≤ 14 % (each scaled by g), every primitive with BlendMode.src, so no texel ever exceeds them.
paperHatchRatio → const double
Hatch lines must reach this contrast against the operator face at their opacity (visible in greyscale and under every CVD).
paperInkAccessibleDarkInkMinL → const int
paperInkAccessibleDarkStampMinL → const int
paperInkAccessibleLightInkMaxL → const int
Accessible lock: light inks no lighter, dark inks no darker (× 1000).
paperInkAccessibleLightStampMaxL → const int
Accessible lock: light stamps no lighter, dark stamps no darker.
paperInkBlackboardInkWeights → const List<int>
paperInkDarkBrownHues → const IntRange
Dark sheets: a wash hue in 30°–70° (chocolate brown at L 0.3, C 0.045) is mapped onto wine through maroon, 345°–20° (after the olive flip).
paperInkDarkOliveHues → const IntRange
Dark sheets: a wash hue landing in 70°–135° (olive at L 0.3) takes the other ±30° neighbour instead (same draws).
paperInkDarkRanges → const RoleRanges
Dark ranges (documentary unions).
paperInkDarkSheetWeights → const List<int>
paperInkDarkStampCapMilli → const int
paperInkDarkStampL → const IntRange
Dark-sheet (pastel gel) stamp lightness × 1000.
paperInkDarkStampWeights → const List<int>
paperInkDarkTone1Papers → const List<PaperLchRange>
Tone 1 of the dark sheets: charcoal ink paper, slate grey blackboard.
paperInkDarkWineSpan → const int
paperInkDarkWineStart → const int
Where paperInkDarkBrownHues land (tenths, linear; wraps past 360°).
paperInkDefinition → const FamilyDefinition
Paper & ink (spec §5.3 #11; motion brief §2.3 "Paper & ink"): outlined paper slips (rounded-rect fills, 2–6 % corners, under a hand-drawn fineliner outline). Press: the outline "boils" to an alternate stroke in frame 1 (tint), an ink wash spreads from the fingertip to its peak and dries on effectsSlow (releaseAlt), the slip drops 1 dp (release 1400/0.9, seeded × {0.9, 1, 1.1}); display glyphs bleed in from 104 %; sound typewriter, haptic soft · 0.6. The palette is built by buildPaperInkCandidate.
paperInkGrain → const List<IntRange>
Grain strength g (‰) by sheet.
paperInkGridMajorEvery → const int
A graph grid's major line every this many minor squares.
paperInkHatchPermille → const IntRange
Operator hatch ink opacity × 1000, on 0.05 steps.
paperInkInkPaperInkWeights → const List<int>
Ink weights [creamGel, chalk] on ink paper and on the blackboard.
paperInkInks → const List<PaperLchRange>
Ink colour by PaperInkType (carbon takes the paper hue).
paperInkLayouts → const List<BackgroundPattern>
The BackgroundPattern of each layout index.
paperInkLayoutWeights → const List<List<int>>
Scene layouts [none, ruled, grid, dots] weights by sheet.
paperInkLightInkWeights → const List<int>
Ink weights on light sheets [blueBlack, carbon, sepia, greenBlack].
paperInkLightRanges → const RoleRanges
Light ranges (documentary unions; the builder reads the sheet tables).
paperInkLightSheetWeights → const List<int>
Light sheets [cream, ivory, newsprint, kraft, graph] and dark sheets [inkPaper, blackboard] weights.
paperInkLightStampCapMilli → const int
paperInkLightStampL → const List<IntRange>
Light-sheet stamp lightness (× 1000) by ink: as light as the knocked-out label allows (≈ 4.5:1), so vermilion reads vermilion, not maroon.
paperInkLightStampWeights → const List<int>
Stamp weights on light and dark sheets: peacock and burnt sienna go grey / chocolate at the lightness a light-sheet stamp needs, so they appear only as pastel gel stamps on dark sheets.
paperInkLineAlphas → const List<List<IntRange>>
Line alpha (‰) by layout for light sheets, ink paper and the blackboard.
paperInkOutlineWidthCdp → const IntRange
Outline (fineliner) widths, dp × 100, on 0.25 dp steps: 1.25–1.75 dp, always thinner than Neo-brutalism's 2 dp minimum.
paperInkPapers → const List<PaperLchRange>
Paper colour by sheet (dark sheets: tone 0, then tone 1).
paperInkPitches → const List<List<int>>
Line pitch (dp × 100) by layout: real stationery pitches (ruled 40–48 dp; graph minor squares and dot grids 28–32 dp).
paperInkRules → const List<PaperLchRange>
Rule ink (colors[1]): feint blue on writing paper, stronger blue on graph paper, brown on kraft, the paper hue on ink paper, chalk on the blackboard (sheet order; ink paper takes the paper hue).
paperInkStampHues → const List<IntRange>
Stamp hue ranges (tenths) by PaperStampInk. No ink sits in 70°–115° (a dark gold reads as olive).
paperInkStampRel → const IntRange
Stamp chroma as a fraction of the gamut × 1000, capped at 0.200 (light) or 0.170 (dark).
paperInkToneWeights → const List<int>
Tone of the dark sheets: [0, 1] weights — indigo ink paper and slate green board are favoured; charcoal ink paper sits near Neo-brutalism's dark sheets (cross-review).
paperInkWashOffsets → const List<int>
paperInkWashOffsetWeights → const List<int>
Operator wash hue offset from the stamp: [0, +30°, −30°] weights.
paperMajorCapPermille → const int
Grid major lines: 1.6 × the minor alpha, capped (‰).
paperStampRatio → const double
The = stamp must reach this contrast against the digit slips.
paperTextMargin → const double
How far past its floor the red-pen error text is solved.
paperWashRimFactor → const double
paperWashRimMaxAlpha → const int
Peak alpha (of 255) of the ink wash's tide line (palette.highlight); the wash fill is this ÷ paperWashRimFactor.

Functions

buildPaperInkCandidate(int seed, FamilyDefinition def, int engineVersion, {int attempt = 0, bool accessible = false}) → ThemeSpec
Builds one unvalidated Paper & ink candidate (the generator repairs and validates it, retries with palette/retry/n and finally falls back to a Paper & ink hero).
fitPaperWash(Palette p, int rim, GuardrailLimits lim) → int
rim with its alpha lowered in steps of 2 until every label keeps GuardrailLimits.labelRatio under it (0 at worst).
paperAlpha(int permille) → int
Alpha (of 255) for permille.
paperDarkWashHue(int washH) → int
The dark-sheet wash hue for washH (tenths): brown → wine.
paperFibreAlpha(int g) → int
Alpha (of 255) of the lightest white grain texel at grain g ‰.
paperFleckAlpha(int g) → int
Alpha (of 255) of the darkest black grain texel at grain g ‰.
paperGrainBases(int base, int g) → List<int>
base with the extreme grain texels at grain g ‰ over it: the base, the darkest fleck over it, the lightest fibre over it.
paperGrainOf(BackgroundSpec bg) → int
The grain strength g (‰, 0–1000) of a paper sheet bg.
paperHatchContrast(KeyColors op, int edgeShadePermille) → double
Contrast of the operator hatch (the operator edge ink at edgeShadePermille) against the operator face.
paperInkDisplayBackdrops(ThemeSpec spec, List<int> surfaces, List<int> bgs) → List<int>?
Display text sits only on the opaque panel (the face draws it, with the grain and the feint rules; the red margin rule stays left of the text): the panel samples are the only backdrops.
paperInkSceneSamples(BackgroundSpec bg) → List<int>?
Guardrail background samples of a paper sheet, in painter order (paper, grain, lines): the grain bases, then each line ink over each base (ruled / dots: the rule; grid: minor and major lines). These are ceilings: rasterising only lowers a texel's coverage.
paperPanelSamples(int panel, BackgroundSpec bg, {required bool accessible}) → List<int>
The display panel's colours under text: panel with the panel grain (half the sheet's) and, outside the Accessible lock, the feint rules over each.
paperWashLabelContrast(Palette p, int rim) → double
The lowest label contrast of p's four key groups under the wash tide line rim (any alpha) laid over the face.
repairPaperInkExtras(Palette p, ThemeSpec spec, GuardrailLimits lim, List<int> bgs) → Palette?
The Paper & ink repairs (after labels and display texts): the ink re-solved to ≥ 3:1 on every sheet sample (outlines, hatch, shadow), the stamp darkened (light) / lightened (dark) until it stands 3:1 off the digit slips, the operator face moved away from the ink until its hatch shows, and the wash refitted. Null when unreachable.
validatePaperInk(ThemeSpec spec, GuardrailLimits lim, List<int> bgs) → List<GuardrailViolation>
The Paper & ink rules (on top of the generic ones):

Typedefs

PaperLchRange = ({IntRange c, IntRange h, IntRange l})
An OKLCH range in engine integers (L and C × 1000, h in tenths).