engine/generator library

The theme generator (spec §5.2; research theme-engine.md Recommendations 5–8, 11 and §12; motion brief §2.5).

ThemeGenerator.generate(seed, family, engineVersion, accessible:) is a pure function: every draw comes from a named Rng sub-stream of the seed, every colour is computed with the bit-exact maths in oklab.dart, and the result passes validateTheme on its final ARGB. If a candidate fails and cannot be repaired, the generator retries with palette sub-streams palette/retry/1… and finally falls back to a hero.

Pipeline (one attempt):

  1. palette stream: brightness, harmony scheme, base hue h0 (tenths of a degree) and per-role hue offsets with ±10° jitter.
  2. Per-role OKLCH lightness and chroma from the family's role ranges, chroma as a fraction of maxChroma(L, h) where the range is relative; dark digit faces stay ≥ background + 0.10; operator and = share-hue schemes keep ≥ 0.08 lightness between them; bile hues (88–110°, C > 0.05, L < 0.70) rotate out of the band; the Accessible lock moves mid-tone faces to where 7:1 labels exist.
  3. Faces → ARGB; labels solved with repairPair (4.5:1, or 7:1 under the Accessible lock; 7:1 on dark faces when reachable).
  4. background stream: solid / gradient / pattern; then display, preview, error and accent colours solved against every backdrop.
  5. shape, style, type, motion and name streams.

Engine v4 adds steering: a ThemeIntent narrows the palette draws of the steerable families (steering.dart) without removing any draw.

Classes

ThemeGenerator
Generates ThemeSpecs. Stateless and const; two instances always produce identical output.

Constants

currentEngineVersion → const int
The newest generator version. Share codes and persisted themes carry the version they were made with.
steeredDrawFamilies → const Set<ThemeFamily>
Families whose own draws steering narrows (brightness, chroma and harmony) before their colours turn to the intent.
supportedEngineVersions → const Set<int>
Generator versions this build can reproduce exactly.

Exceptions / Errors

UnsupportedEngineVersion
Thrown for an engineVersion this build cannot reproduce (newer than currentEngineVersion): show "update the app to open this theme".