@zakkster/lite-ui-fx 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -5,6 +5,55 @@ All notable changes to `@zakkster/lite-ui-fx` are documented here.
 The format follows Keep a Changelog; this project adheres to Semantic
 Versioning.
 
+## [1.4.0] -- 2026-09-07
+
+The theming pass (U3b), completing U3's third finding (U-06). One option
+convention across all 50 recipes; `themeable` is true for the first time. Every
+default renders byte-for-byte as 1.3.0. Reduced motion (`motionSafe`) stays a
+later pass.
+
+### Fixed
+
+- U-06 (theming): all 50 recipes honour one reserved option set
+  `{ seed, colors, theme: { light, mid, dark }, text, font }`, resolved once in the
+  factory / `init`, never per frame. `theme` maps light/mid/dark onto each recipe's
+  accent/dim/surface roles; `colors` overrides positionally and wins over `theme`;
+  the array-palette recipes (Confetti, Firework, Aurora, RadioOrbit,
+  PasswordStrength, ReactionPicker) keep reading `colors` as their palette and are
+  seeded by `theme`. Hardcoded canvas labels (`'MAGNETIC'`, ...) became `text`,
+  resolved as `text ?? label ?? default`, so a mount that sets only the accessible
+  `label` drives the visible string (WCAG 2.5.3 label-in-name); fonts became the
+  `font` option. Every default is byte-identical to 1.3.0 (recording-context
+  draw-signature diff over all 50 recipes).
+
+### Added
+
+- `RecipeOptions` (UIFXRecipes.d.ts) plus the shared cold helpers `resolveTheme`,
+  `pickText`, `pickFont`, `rgbaOf`, `rgbTriplet`; `MountOptions` gains the five
+  reserved keys.
+- `test/theme.test.mjs`: 70 boundary tests (themeable flags, every recipe recolours
+  under a theme, colors-wins-over-theme, the legacy `colors`/`color` aliases, the
+  fail-closed validator matrix, label-in-name).
+- t3 torture gates each recipe under a THEMED mount as well as its default
+  (`t3-scan.mjs` adds `tgrad`/`tcdist`; `t3-frame-alloc.mjs` judges both), proving
+  palette resolution stayed cold; t2 gains a label-in-name assertion.
+- `tools/palettes.mjs` (not shipped): audits the shipped label colours for APCA
+  0.1.9 contrast and emits example theme triples via `@zakkster/lite-hueforge`
+  (a dev-only tool, never a runtime dependency). Recorded in
+  `decisions/0002-recipe-options.md`.
+
+### Changed
+
+- Controller: `KNOWN_OPTIONS` admits `seed` / `colors` / `theme` / `text` / `font`,
+  each validated fail closed -- a partial or extra-key `theme`, a non-array
+  `colors`, a non-string `text` / `font`, or a non-finite `seed` throws; an unknown
+  key still returns a did-you-mean.
+- `RECIPE_META.themeable` is `true` for all 50 recipes; `motionSafe` stays `false`.
+- The recording `Ctx2DStub` logs `fillText` / `strokeText` with their text argument.
+- `UIFX-RECIPE-GUIDE.md`: the per-frame performance rules retire the pre-U3
+  "`splice()` is fine for < 100 particles" advice (it contradicts the t3 gate) and
+  add a rule to resolve theming in the factory / `init`, never in `tick`.
+
 ## [1.3.0] -- 2026-09-07
 
 The recipe sweep (U3), first pass: zero per-frame allocation across all 50

package/UIFX-RECIPE-GUIDE.md

@@ -181,8 +181,9 @@ if (state.focused) {
 
 ## Performance Rules
 
-1. **Never allocate in `tick()`** -- pre-allocate TypedArrays in the factory closure or `init()`
-2. **Use `splice()` sparingly** -- for small particle arrays (< 100) it's fine. For larger pools, use a dead-flag pattern
+1. **Never allocate in `tick()`** -- pre-allocate TypedArrays / fixed object pools in the factory closure or `init()`. This is not a guideline: the `t3-frame-alloc` torture tier FAILS any built-in recipe that assigns a fresh colour string, builds a gradient, or grows a pool on a hot frame (idle OR under interaction churn), and re-runs the same budget under a themed mount.
+2. **No `push`/`splice` on the hot path** -- a particle pool is a fixed-size array (or `Float64Array` lanes) with a `live`/`life` flag; spawn scans for a dead slot, death clears the flag. `splice()` allocates and shifts elements; it is a cold-path tool (mount/destroy) only, never per frame. (The pre-U3 "splice is fine for < 100 particles" advice is retired -- it contradicts the gate.)
 3. **Reset composite operation** -- if you set `ctx.globalCompositeOperation = 'screen'`, reset to `'source-over'` before returning
 4. **Reset shadow** -- `ctx.shadowBlur = 0` after drawing glowing elements
 5. **Use the `dt` parameter** -- all motion must be `value * dt`, not `value` per frame. This ensures consistent speed regardless of frame rate.
+6. **Resolve theming in the factory / `init()`, never in `tick()`** -- read `options.theme` / `colors` / `text` / `font` ONCE at construction (the built-ins use the shared `resolveTheme` / `pickText` / `pickFont` helpers), producing const colour strings and any value-LUT the hot body then reads. Alpha varies via `ctx.globalAlpha` over a const colour; a `rgba(...,${x})` or `` `${color}` `` built per frame trips t3. Defaults must reproduce the pre-theming output byte-for-byte.

package/UIFXController.d.ts

@@ -59,6 +59,19 @@ export interface MountOptions {
     checked?: boolean;
     /** Disables the native element and sets state.disabled for recipes. */
     disabled?: boolean;
+    // -- Reserved recipe theming options (decisions/0002). Validated fail-closed,
+    //    then forwarded to the recipe factory. All optional; omitting them keeps
+    //    the recipe's shipped look byte-for-byte.
+    /** Seed for a recipe's deterministic RNG. */
+    seed?: number;
+    /** Positional palette override; wins over `theme`. */
+    colors?: string[];
+    /** Named theme roles: light -> accent, mid -> dim/muted, dark -> surface. */
+    theme?: { light: string; mid: string; dark: string };
+    /** Visible canvas label; falls back to `label`, then the recipe default. */
+    text?: string;
+    /** Canvas font string; falls back to the recipe's historical font. */
+    font?: string;
 }
 
 export interface UIFXInstance {

package/UIFXController.js

@@ -22,7 +22,7 @@ import { Ticker } from '@zakkster/lite-ticker';
 
 // Three-place version sync: this constant, package.json "version", and the
 // VERSION line in llms.txt must always match. /release keeps them locked.
-export const VERSION = '1.3.0';
+export const VERSION = '1.4.0';
 
 // ---------------------------------------------------------
 //  SHARED TICKER (ref-counted, one RAF for all UI components)
@@ -84,7 +84,7 @@ function releaseSliderStyle() {
 // ---------------------------------------------------------
 
 const KNOWN_HOOKS = ['init', 'tick', 'onHover', 'onLeave', 'onClick', 'onToggle', 'onDrag', 'destroy'];
-const KNOWN_OPTIONS = ['width', 'height', 'padding', 'label', 'value', 'checked', 'disabled'];
+const KNOWN_OPTIONS = ['width', 'height', 'padding', 'label', 'value', 'checked', 'disabled', 'seed', 'colors', 'theme', 'text', 'font'];
 
 // Levenshtein edit distance. Cold: only reached on the error path.
 function _editDistance(a, b) {
@@ -206,6 +206,33 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
     const padding = options.padding === undefined ? 40 : options.padding;
     const label = options.label === undefined ? '' : options.label;
 
+    // Reserved theming options (decisions/0002): all optional, validated fail
+    // closed here, then forwarded to the recipe factory which resolves them in
+    // init. This is cold mount code -- closures/allocation are fine here.
+    const _theme = options.theme;
+    if (_theme !== undefined) {
+        if (_theme === null || typeof _theme !== 'object' ||
+            typeof _theme.light !== 'string' || typeof _theme.mid !== 'string' ||
+            typeof _theme.dark !== 'string' || Object.keys(_theme).length !== 3) {
+            throw new Error('mountUIFX: option "theme" must be { light, mid, dark } of color strings');
+        }
+    }
+    const _colors = options.colors;
+    if (_colors !== undefined &&
+        (!Array.isArray(_colors) || _colors.some((c) => typeof c !== 'string'))) {
+        throw new Error('mountUIFX: option "colors" must be an array of color strings');
+    }
+    if (options.text !== undefined && typeof options.text !== 'string') {
+        throw new Error('mountUIFX: option "text" must be a string');
+    }
+    if (options.font !== undefined && typeof options.font !== 'string') {
+        throw new Error('mountUIFX: option "font" must be a string');
+    }
+    if (options.seed !== undefined &&
+        (typeof options.seed !== 'number' || !Number.isFinite(options.seed))) {
+        throw new Error('mountUIFX: option "seed" must be a finite number');
+    }
+
     // 3. recipeFactory
     if (typeof recipeFactory !== 'function') {
         throw new Error('mountUIFX: recipeFactory must be a function');

package/UIFXRecipes.d.ts

@@ -1,92 +1,118 @@
 import type { UIFXRecipe, UIFXInstance, MountOptions } from './UIFXController';
 
 // ===========================================================
-//  RECIPE FACTORIES (all 50)
+//  RECIPE OPTIONS + FACTORIES (all 50)
 // ===========================================================
 
+/**
+ * The reserved theming options every recipe factory accepts (decisions/0002).
+ * All optional; omitting them reproduces the recipe's shipped look byte-for-byte.
+ */
+export interface RecipeOptions {
+    /** Seed for a recipe's deterministic RNG (particle bursts, jitter). */
+    seed?: number;
+    /**
+     * Positional palette override; wins over `theme`. For most recipes it maps
+     * over the role order (accent, dim, surface, ...); for an array-palette recipe
+     * (Confetti, Firework, Aurora, RadioOrbit, PasswordStrength, ReactionPicker)
+     * it IS the palette.
+     */
+    colors?: string[];
+    /** Named theme roles: `light` -> accent, `mid` -> dim/muted, `dark` -> surface. */
+    theme?: { light: string; mid: string; dark: string };
+    /**
+     * Visible canvas label. Falls back to the mount `label`, then the recipe's
+     * default string -- so setting only `label` keeps the visible text equal to the
+     * accessible name (WCAG 2.5.3 label-in-name). Ignored by recipes painting no text.
+     */
+    text?: string;
+    /** Canvas font string; falls back to the recipe's historical font literal. */
+    font?: string;
+}
+
 // -- Vol.1: Toggles --
-export declare function SwarmToggle(options?: { seed?: number; count?: number }): UIFXRecipe;
-export declare function LiquidToggle(): UIFXRecipe;
-export declare function NeonPulseToggle(): UIFXRecipe;
+export declare function SwarmToggle(options?: RecipeOptions & { count?: number }): UIFXRecipe;
+export declare function LiquidToggle(options?: RecipeOptions): UIFXRecipe;
+export declare function NeonPulseToggle(options?: RecipeOptions): UIFXRecipe;
 
 // -- Vol.1: Buttons --
-export declare function MagneticButton(options?: { maxPull?: number }): UIFXRecipe;
-export declare function ShatterButton(options?: { seed?: number }): UIFXRecipe;
-export declare function ConfettiButton(options?: { seed?: number; colors?: string[] }): UIFXRecipe;
-export declare function GlitchButton(options?: { seed?: number }): UIFXRecipe;
+export declare function MagneticButton(options?: RecipeOptions & { maxPull?: number }): UIFXRecipe;
+export declare function ShatterButton(options?: RecipeOptions): UIFXRecipe;
+export declare function ConfettiButton(options?: RecipeOptions): UIFXRecipe;
+export declare function GlitchButton(options?: RecipeOptions): UIFXRecipe;
 
 // -- Vol.1: Sliders --
-export declare function SparkSlider(options?: { seed?: number; color?: string }): UIFXRecipe;
-export declare function CosmicSlider(options?: { seed?: number; dustCount?: number }): UIFXRecipe;
-export declare function LaserSlider(): UIFXRecipe;
+export declare function SparkSlider(options?: RecipeOptions & { color?: string }): UIFXRecipe;
+export declare function CosmicSlider(options?: RecipeOptions & { dustCount?: number }): UIFXRecipe;
+export declare function LaserSlider(options?: RecipeOptions): UIFXRecipe;
 
 // -- Vol.2: Toggles --
-export declare function PendulumToggle(): UIFXRecipe;
-export declare function CircuitToggle(options?: { seed?: number }): UIFXRecipe;
-export declare function LightningToggle(options?: { seed?: number }): UIFXRecipe;
-export declare function DNAToggle(): UIFXRecipe;
+export declare function PendulumToggle(options?: RecipeOptions): UIFXRecipe;
+export declare function CircuitToggle(options?: RecipeOptions): UIFXRecipe;
+export declare function LightningToggle(options?: RecipeOptions): UIFXRecipe;
+export declare function DNAToggle(options?: RecipeOptions): UIFXRecipe;
 
 // -- Vol.2: Buttons --
-export declare function HeartbeatButton(options?: { seed?: number }): UIFXRecipe;
-export declare function BreathingButton(): UIFXRecipe;
-export declare function InkSplashButton(options?: { seed?: number }): UIFXRecipe;
-export declare function PixelDissolveButton(options?: { seed?: number; cols?: number; rows?: number }): UIFXRecipe;
-export declare function FireworkButton(options?: { seed?: number }): UIFXRecipe;
+export declare function HeartbeatButton(options?: RecipeOptions): UIFXRecipe;
+export declare function BreathingButton(options?: RecipeOptions): UIFXRecipe;
+export declare function InkSplashButton(options?: RecipeOptions): UIFXRecipe;
+export declare function PixelDissolveButton(options?: RecipeOptions & { cols?: number; rows?: number }): UIFXRecipe;
+export declare function FireworkButton(options?: RecipeOptions): UIFXRecipe;
 
 // -- Vol.2: Sliders --
-export declare function AuroraSlider(): UIFXRecipe;
-export declare function WaveSlider(options?: { seed?: number }): UIFXRecipe;
-export declare function ElasticBandSlider(): UIFXRecipe;
-export declare function GravitySlider(): UIFXRecipe;
+export declare function AuroraSlider(options?: RecipeOptions): UIFXRecipe;
+export declare function WaveSlider(options?: RecipeOptions): UIFXRecipe;
+export declare function ElasticBandSlider(options?: RecipeOptions): UIFXRecipe;
+export declare function GravitySlider(options?: RecipeOptions): UIFXRecipe;
 
 // -- Vol.2: Loaders --
-export declare function OrbitLoader(): UIFXRecipe;
-export declare function HelixLoader(): UIFXRecipe;
+export declare function OrbitLoader(options?: RecipeOptions): UIFXRecipe;
+export declare function HelixLoader(options?: RecipeOptions): UIFXRecipe;
 
 // -- Vol.2: Checkboxes --
-export declare function RippleCheck(): UIFXRecipe;
-export declare function MorphCheck(): UIFXRecipe;
+export declare function RippleCheck(options?: RecipeOptions): UIFXRecipe;
+export declare function MorphCheck(options?: RecipeOptions): UIFXRecipe;
 
 // -- Vol.2: Counters --
-export declare function FlameCounter(options?: { seed?: number }): UIFXRecipe;
-export declare function GlitchCounter(options?: { seed?: number }): UIFXRecipe;
+export declare function FlameCounter(options?: RecipeOptions): UIFXRecipe;
+export declare function GlitchCounter(options?: RecipeOptions): UIFXRecipe;
 
 // -- Vol.2: Rating --
-export declare function BubbleRating(options?: { seed?: number }): UIFXRecipe;
+export declare function BubbleRating(options?: RecipeOptions): UIFXRecipe;
 
 // -- Vol.3: Knobs --
-export declare function VolumeKnob(): UIFXRecipe;
-export declare function CompassKnob(): UIFXRecipe;
+export declare function VolumeKnob(options?: RecipeOptions): UIFXRecipe;
+export declare function CompassKnob(options?: RecipeOptions): UIFXRecipe;
 
 // -- Vol.3: Progress --
-export declare function RingProgress(options?: { seed?: number }): UIFXRecipe;
-export declare function BatteryGauge(): UIFXRecipe;
-export declare function SignalMeter(): UIFXRecipe;
+export declare function RingProgress(options?: RecipeOptions): UIFXRecipe;
+export declare function BatteryGauge(options?: RecipeOptions): UIFXRecipe;
+export declare function SignalMeter(options?: RecipeOptions): UIFXRecipe;
 
 // -- Vol.3: Controls --
-export declare function PillTabs(): UIFXRecipe;
-export declare function Stepper(): UIFXRecipe;
-export declare function RadioOrbit(): UIFXRecipe;
+export declare function PillTabs(options?: RecipeOptions): UIFXRecipe;
+export declare function Stepper(options?: RecipeOptions): UIFXRecipe;
+export declare function RadioOrbit(options?: RecipeOptions): UIFXRecipe;
 
 // -- Vol.3: Indicators --
-export declare function PasswordStrength(): UIFXRecipe;
-export declare function WaterLevel(): UIFXRecipe;
-export declare function HeatMap(options?: { seed?: number }): UIFXRecipe;
+export declare function PasswordStrength(options?: RecipeOptions): UIFXRecipe;
+export declare function WaterLevel(options?: RecipeOptions): UIFXRecipe;
+export declare function HeatMap(options?: RecipeOptions): UIFXRecipe;
 
 // -- Vol.3: Mood --
-export declare function DayNightToggle(options?: { seed?: number }): UIFXRecipe;
-export declare function ReactionPicker(): UIFXRecipe;
-export declare function NotificationBell(): UIFXRecipe;
+export declare function DayNightToggle(options?: RecipeOptions): UIFXRecipe;
+export declare function ReactionPicker(options?: RecipeOptions): UIFXRecipe;
+export declare function NotificationBell(options?: RecipeOptions): UIFXRecipe;
 
 // -- Vol.3: Feedback --
-export declare function TypewriterField(): UIFXRecipe;
-export declare function SoundWaveBtn(): UIFXRecipe;
-export declare function UploadProgress(): UIFXRecipe;
+export declare function TypewriterField(options?: RecipeOptions): UIFXRecipe;
+export declare function SoundWaveBtn(options?: RecipeOptions): UIFXRecipe;
+export declare function UploadProgress(options?: RecipeOptions): UIFXRecipe;
 
 // -- Vol.3: Fun --
-export declare function ScratchReveal(options?: { seed?: number }): UIFXRecipe;
-export declare function TimerCountdown(): UIFXRecipe;
-export declare function PullRefresh(): UIFXRecipe;
+export declare function ScratchReveal(options?: RecipeOptions): UIFXRecipe;
+export declare function TimerCountdown(options?: RecipeOptions): UIFXRecipe;
+export declare function PullRefresh(options?: RecipeOptions): UIFXRecipe;
 
 // ===========================================================
 //  BARREL OBJECTS (back-compat)