@zakkster/lite-ui-fx 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -5,6 +5,49 @@ All notable changes to `@zakkster/lite-ui-fx` are documented here.
 The format follows Keep a Changelog; this project adheres to Semantic
 Versioning.
 
+## [1.7.0] -- 2026-09-07
+
+Host integration (roadmap U5). Two host-clock modes plus reduced-motion and a
+frame-budget signal, applied to BOTH mount modes (`mountUIFX` and `decorateUIFX`).
+Additive: a default mount is byte-identical to 1.6.0.
+
+### Added
+
+- `{ ticker }` mount option (both modes): a caller-supplied ticker
+  (`{ add(fn) -> removeFn }`, e.g. `@zakkster/lite-ticker`) drives the component
+  instead of the shared ref-counted ticker. `destroy()` unregisters the
+  component's frame but never destroys the caller's ticker (ownership stays with
+  the caller).
+- `{ driven: true }` mount option (both modes): no ticker and no RAF; the host
+  drives each frame via `instance.tick(dtMs)`. `instance.tick` is the internal
+  frame body in driven mode and throws otherwise. `{ ticker }` and `{ driven }`
+  are mutually exclusive; a non-boolean `driven` or a ticker without `.add()`
+  throws at mount.
+- `state.reducedMotion` (both modes): read from
+  `matchMedia('(prefers-reduced-motion: reduce)')` before `recipe.init` and
+  watched via the AbortController; absent `matchMedia` is a no-op (stays `false`).
+  Calm paths for six recipes -- `SwarmToggle`, `PasswordStrength`,
+  `TypewriterField`, `FocusHalo`, `ErrorShake`, `SuccessBloom`: under reduced
+  motion `ErrorShake` stops displacing, `SuccessBloom` spawns no particles, and
+  `SwarmToggle` rests its particles at formation.
+- `state.budget` (0..1, both modes): a per-frame frame-budget number (1 at
+  ~60fps, lower as frames lengthen), computed in place with no allocation, for
+  budget-aware recipes to shed work.
+- `mountRecipe` emits a `console.warn` (not a throw) when mounting a
+  `motionSafe:false` recipe while the user prefers reduced motion.
+- TypeScript: `HostTicker`, `HostClockOptions`, `state.reducedMotion` /
+  `state.budget`, and `instance.tick(dtMs)` on both instance types.
+- `decisions/0005-host-clock.md`. U5 coverage: t5 caller-ticker ownership +
+  driven determinism, t3 reduced-motion churn, and two t9 controls (`fake-calm`,
+  `ticker-ownership`). 177 -> 196 node:test tests; 5 -> 7 torture controls.
+
+### Changed
+
+- The per-mount frame loop is one named function shared by all three clock modes;
+  the default (shared-ticker) path is byte-identical to 1.6.0.
+- `RECIPE_META.motionSafe` is now `true` for six recipes (previously `false` for
+  all 56): it marks exactly the recipes that ship a reduced-motion calm path.
+
 ## [1.6.0] -- 2026-09-07
 
 Decorate mode (U4b, the second half of roadmap U4). A second public mount mode

package/UIFX-RECIPE-GUIDE.md

@@ -70,12 +70,44 @@ The controller provides this every frame:
     h: number,          // Element height
     padding: number,    // Canvas overflow padding
     dpr: number,        // Device pixel ratio
+    reducedMotion: boolean, // U5: user prefers reduced motion (see below)
+    budget: number,     // U5: 0--1 frame budget (1 at ~60fps, lower under load)
     // Decorate mode only (decorateUIFX): the live host's value + validity.
     text: string,       // the host form-control's value string ('' if none)
     valid: boolean,     // the host's validity (el.validity.valid, else true)
 }
 ```
 
+## Reduced Motion & Frame Budget (U5)
+
+Two state fields let a recipe be a good citizen without changing the interface.
+
+- **`state.reducedMotion`** is `true` when the user has set
+  `prefers-reduced-motion: reduce`. A recipe that animates should read it and
+  render a **static** alternative -- no continuous motion, no bursts, no shakes.
+  Fades and instant state changes are fine; sustained or positional motion is not.
+  When your recipe ships such a calm path, set its `RECIPE_META.motionSafe: true`;
+  that flag is a promise the calm path exists, so keep them in sync.
+
+  ```javascript
+  tick(c, dt, now, st) {
+      // full motion vs. a steady, motion-free render
+      const wobble = st.reducedMotion ? 0 : Math.sin(now / 200) * 4;
+      // ... draw using `wobble` (0 = no motion) ...
+  }
+  ```
+
+- **`state.budget`** is `1` when frames are healthy and drops toward `0` as they
+  lengthen. A budget-aware recipe scales expensive work by it (fewer particles,
+  less glow) so it degrades before the host drops frames. Consuming it is optional.
+
+  ```javascript
+  const live = (this.count = Math.floor(MAX_PARTICLES * st.budget));
+  ```
+
+Both are read-only per-frame numbers -- never write them, never allocate to honour
+them (a branch on a boolean/number is free; a new array per frame is not).
+
 ## The Pointer Object
 
 ```javascript

package/UIFXController.d.ts

@@ -27,6 +27,12 @@ export interface UIFXState {
     h: number;
     padding: number;
     dpr: number;
+    /** U5: true when the user prefers reduced motion (matchMedia). Calm-path
+     *  recipes render statically when set; recipes that ignore it animate. */
+    reducedMotion: boolean;
+    /** U5: frame budget in 0..1 -- 1 at ~60fps, lower as frames lengthen.
+     *  Budget-aware recipes shed work (particles/glow) when it drops. */
+    budget: number;
     /** Decorate mode only (decorateUIFX): the host form-control's current value.
      *  Absent for hijack mounts and for a non-form host (then ''). */
     text?: string;
@@ -61,7 +67,30 @@ export interface UIFXRecipe {
 
 export type RecipeFactory = () => UIFXRecipe;
 
-export interface MountOptions {
+/**
+ * A caller-supplied clock for the { ticker } host-clock mode (U5). Duck-typed to
+ * @zakkster/lite-ticker: it must expose add(fn) returning a remove function. The
+ * component registers its frame on it and, on destroy, removes that frame but
+ * NEVER destroys the ticker -- ownership stays with the caller.
+ */
+export interface HostTicker {
+    add(fn: (dtMs: number) => void): () => void;
+}
+
+/**
+ * Host-clock options (U5, decisions/0005), shared by both mount modes. Three
+ * mutually-exclusive modes: omit both for the shared ref-counted ticker (default);
+ * `ticker` to ride a caller-supplied clock; `driven: true` for no clock at all
+ * (the host calls instance.tick(dtMs)). Passing both throws.
+ */
+export interface HostClockOptions {
+    /** Ride a caller-supplied ticker instead of the shared one. Mutually exclusive with `driven`. */
+    ticker?: HostTicker;
+    /** No ticker/RAF: the host drives frames via instance.tick(dtMs). Mutually exclusive with `ticker`. */
+    driven?: boolean;
+}
+
+export interface MountOptions extends HostClockOptions {
     width?: number;
     height?: number;
     padding?: number;
@@ -97,7 +126,7 @@ export interface MountOptions {
  * the hijack-only options (width/height/value/checked/disabled/knobMode/announce/
  * label) are rejected -- passing one throws (fail closed).
  */
-export interface DecorateOptions {
+export interface DecorateOptions extends HostClockOptions {
     /** Overlay padding around the host, in px (default 40). */
     padding?: number;
     seed?: number;
@@ -113,6 +142,14 @@ export interface UIFXInstance {
     wrapper: HTMLDivElement;
     state: UIFXState;
 
+    /**
+     * Drive one frame by hand (U5). Callable ONLY when mounted with { driven: true }
+     * -- it is the internal frame body, so a driven host pays exactly the internal
+     * per-frame cost. On a ticker-driven component it throws (that component owns
+     * its own clock).
+     */
+    tick(dtMs: number): void;
+
     /**
      * Set a valued control (SLIDER/KNOB/PROGRESS) to v in [0,1]: updates the
      * native element, state.val, any PROGRESS announcer, and fires onDrag once.
@@ -150,6 +187,9 @@ export interface DecorateInstance {
     /** The overlay canvas (the only DOM node decorate adds). */
     canvas: HTMLCanvasElement;
     state: UIFXState;
+    /** Drive one frame by hand (U5). Callable ONLY with { driven: true }; a
+     *  ticker-driven decoration throws. */
+    tick(dtMs: number): void;
     /** Hijack-only. Throws in decorate mode. */
     setValue(v?: number | null): void;
     /** Hijack-only. Throws in decorate mode. */

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.6.0';
+export const VERSION = '1.7.0';
 
 // ---------------------------------------------------------
 //  SHARED TICKER (ref-counted, one RAF for all UI components)
@@ -79,19 +79,51 @@ function releaseSliderStyle() {
 }
 
 
+// ---------------------------------------------------------
+//  HOST CLOCK + FRAME STATE (U5) -- shared by both mount modes
+// ---------------------------------------------------------
+
+// Frame budget (state.budget, 0..1): 1 when frames hit ~60fps, degrading as the
+// frame delta grows so budget-aware recipes shed work BEFORE frames drop. A
+// smoothed instantaneous ratio -- zero allocation (module consts + arithmetic on
+// the dt the clock already provides; no extra clock read).
+const _TARGET_DT = 1 / 60;    // seconds per frame at 60fps
+const _BUDGET_SMOOTH = 0.1;   // EMA weight toward the instantaneous ratio
+
+// prefers-reduced-motion query, created once at mount (cold). Returns null when
+// matchMedia is absent -- fail closed: state.reducedMotion then stays false and
+// every recipe renders its full-motion path, never throwing. The caller reads
+// .matches into state BEFORE recipe.init, then wires the change listener once the
+// AbortController exists (so teardown removes it). One helper, both mount modes.
+function _reducedMotionQuery() {
+    return (typeof window.matchMedia === 'function')
+        ? window.matchMedia('(prefers-reduced-motion: reduce)')
+        : null;
+}
+
+// instance.tick() outside { driven } mode. A shared module stub (not a per-mount
+// closure) so a ticker-driven component allocates nothing for a member it fails
+// closed on: a component that rides a ticker does not accept hand-driven frames.
+function _drivenOnly() {
+    throw new Error('tick(dtMs) is only callable in driven mode ({ driven: true }); this component rides a ticker');
+}
+
+
 // ---------------------------------------------------------
 //  MOUNT-TIME VALIDATION (cold path only -- never a hot body)
 // ---------------------------------------------------------
 
 const KNOWN_HOOKS = ['init', 'tick', 'onHover', 'onLeave', 'onClick', 'onToggle', 'onDrag', 'destroy'];
-const KNOWN_OPTIONS = ['width', 'height', 'padding', 'label', 'value', 'checked', 'disabled', 'seed', 'colors', 'theme', 'text', 'font', 'knobMode', 'announce'];
+const KNOWN_OPTIONS = ['width', 'height', 'padding', 'label', 'value', 'checked', 'disabled', 'seed', 'colors', 'theme', 'text', 'font', 'knobMode', 'announce', 'ticker', 'driven'];
 const KNOB_MODES = ['rotate', 'vertical'];
 
 // Options valid in decorate mode (decorateUIFX). A canvas AROUND a live element
 // inherits the host's geometry (offset box) and value (read from el), so the
 // hijack-only options (width/height/value/checked/disabled/knobMode/announce/
-// label) are rejected here -- fail closed. Cold: read only at mount.
-const DECORATE_OPTIONS = ['padding', 'seed', 'colors', 'theme', 'text', 'font'];
+// label) are rejected here -- fail closed. The host-clock options (ticker/driven)
+// ARE valid in decorate mode: a decoration wants host-clock control every bit as
+// much as a hijack does. Cold: read only at mount.
+const DECORATE_OPTIONS = ['padding', 'seed', 'colors', 'theme', 'text', 'font', 'ticker', 'driven'];
 
 // Levenshtein edit distance. Cold: only reached on the error path.
 function _editDistance(a, b) {
@@ -249,6 +281,25 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
         throw new Error('mountUIFX: option "seed" must be a finite number');
     }
 
+    // Host clock (U5, decisions/0005). Three mutually-exclusive modes, resolved
+    // once here (cold): default -> the shared ref-counted ticker; { ticker } -> a
+    // caller-supplied lite-ticker drives this component; { driven:true } -> no
+    // ticker/RAF, the host calls instance.tick(dtMs). Both-passed, a non-boolean
+    // driven, or a ticker missing .add() is an Error, never a silent pick.
+    const callerTicker = options.ticker;
+    if (options.driven !== undefined && typeof options.driven !== 'boolean') {
+        throw new Error('mountUIFX: option "driven" must be a boolean');
+    }
+    const driven = options.driven === true;
+    if (callerTicker !== undefined) {
+        if (driven) {
+            throw new Error('mountUIFX: options "ticker" and "driven" are mutually exclusive');
+        }
+        if (!callerTicker || typeof callerTicker.add !== 'function') {
+            throw new Error('mountUIFX: option "ticker" must be a ticker with an .add(fn) method');
+        }
+    }
+
     // Type-scoped options (U4a). knobMode belongs only to a KNOB; announce only
     // to a PROGRESS. Presence on the wrong type is a mistake, not a silent
     // ignore (fail closed). Both validated here, before any element exists.
@@ -415,6 +466,10 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
     }
     let _lastAnnouncePct = -1;  // last announced 10% step (cold: only setValue writes)
 
+    // prefers-reduced-motion query (U5): read its initial value into state below,
+    // BEFORE recipe.init, so a recipe reading state.reducedMotion in init is right.
+    const rmq = _reducedMotionQuery();
+
     // -- State (value/checked/disabled land here BEFORE frame 1) --
     const state = {
         hover: false,
@@ -424,6 +479,8 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
         indeterminate: false,  // CHECKBOX only; set via setValue(null)
         disabled,           // recipes can render a disabled look
         val: value !== undefined ? value : (type === UIType.SLIDER || type === UIType.KNOB ? 0.5 : 0),  // 0-1
+        reducedMotion: rmq ? !!rmq.matches : false,  // U5: calm-path recipes honour it
+        budget: 1,          // U5: 0..1 frame budget, updated in place per frame
         w, h, padding, dpr,
     };
 
@@ -583,17 +640,31 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
         }, { signal });
     }
 
-    // -- Render loop (shared ticker) --
-    const ticker = acquireTicker();
-    tickerAcquired = true;
+    // -- Reduced-motion change watch (U5). Cold; through signal so destroy removes
+    //    it. The initial value was already read into state above. --
+    if (rmq) {
+        rmq.addEventListener('change', () => { state.reducedMotion = !!rmq.matches; }, { signal });
+    }
+
+    // -- Render loop. The frame body is ONE named function so all three clock
+    //    modes invoke the SAME code with no wrapper: default and { ticker } pass
+    //    `frame` to a ticker's .add(); { driven } exposes it as instance.tick. --
     let destroyed = false;
     let quarantined = false;  // a recipe.tick throw quarantines only this one
 
-    removeTick = ticker.add((dtMs) => {
+    function frame(dtMs) {
         if (destroyed || quarantined) return;
         const dt = dtMs / 1000;
         const now = performance.now();
 
+        // Frame budget (U5): update in place from the dt already in hand -- no
+        // allocation, no extra clock read.
+        if (dt > 0) {
+            let inst = _TARGET_DT / dt;
+            if (inst > 1) inst = 1; else if (inst < 0) inst = 0;
+            state.budget += (inst - state.budget) * _BUDGET_SMOOTH;
+        }
+
         ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
         ctx.clearRect(0, 0, cw, ch);
         ctx.save();
@@ -610,7 +681,20 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
             return;
         }
         ctx.restore();
-    });
+    }
+
+    // Clock mode (validated cold in phase 1). Only the shared path acquires the
+    // ref-counted ticker; { ticker } borrows the host's clock and must never
+    // destroy it; { driven } schedules no RAF (the host calls instance.tick).
+    if (driven) {
+        // no ticker acquired; removeTick stays null
+    } else if (callerTicker !== undefined) {
+        removeTick = callerTicker.add(frame);
+    } else {
+        const ticker = acquireTicker();
+        tickerAcquired = true;
+        removeTick = ticker.add(frame);
+    }
 
     // -- Public API --
     return {
@@ -626,6 +710,14 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
         /** Current state (read-only reference). */
         state,
 
+        /**
+         * Drive one frame by hand (U5). Callable ONLY in { driven: true } mode:
+         * it IS the internal frame body, so a driven host pays exactly the internal
+         * per-frame cost (no wrapper). A ticker-driven component owns its own clock,
+         * so its tick() fails closed.
+         */
+        tick: driven ? frame : _drivenOnly,
+
         /**
          * Programmatically set a valued control (SLIDER/KNOB/PROGRESS) to v in
          * [0,1]: updates the native element, state.val, any PROGRESS announcer,
@@ -675,9 +767,9 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
             if (destroyed) return;
             destroyed = true;
             ac.abort();
-            removeTick();
+            if (removeTick) removeTick();        // shared OR caller ticker; null when driven
             if (recipe.destroy) recipe.destroy();
-            releaseTicker();
+            if (tickerAcquired) releaseTicker();  // release ONLY the shared ticker we acquired -- never a caller's
             if (type === UIType.SLIDER || type === UIType.KNOB) releaseSliderStyle();
             wrapper.remove();
         },
@@ -689,10 +781,8 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
         // ticker exist) never releases a ticker or aborts an ac that was never
         // created. recipe.destroy() is deliberately NOT called: init did not
         // succeed, so there is no initialised recipe to tear down.
-        if (tickerAcquired) {
-            if (removeTick) removeTick();
-            releaseTicker();
-        }
+        if (removeTick) removeTick();          // shared OR caller ticker -- both must unwind
+        if (tickerAcquired) releaseTicker();   // release ONLY the shared ticker we acquired
         if (acCreated) ac.abort();
         if (wrapperAppended) wrapper.remove();
         if (styleAcquired) releaseSliderStyle();
@@ -780,6 +870,22 @@ export function decorateUIFX(el, recipeFactory, options = {}) {
         throw new Error('decorateUIFX: option "seed" must be a finite number');
     }
 
+    // Host clock (U5, decisions/0005) -- same three modes as mountUIFX. A
+    // decoration wants host-clock control every bit as much as a hijack does.
+    const callerTicker = options.ticker;
+    if (options.driven !== undefined && typeof options.driven !== 'boolean') {
+        throw new Error('decorateUIFX: option "driven" must be a boolean');
+    }
+    const driven = options.driven === true;
+    if (callerTicker !== undefined) {
+        if (driven) {
+            throw new Error('decorateUIFX: options "ticker" and "driven" are mutually exclusive');
+        }
+        if (!callerTicker || typeof callerTicker.add !== 'function') {
+            throw new Error('decorateUIFX: option "ticker" must be a ticker with an .add(fn) method');
+        }
+    }
+
     // 3. recipeFactory + recipe object + hooks (same contract as mountUIFX).
     if (typeof recipeFactory !== 'function') {
         throw new Error('decorateUIFX: recipeFactory must be a function');
@@ -840,6 +946,10 @@ export function decorateUIFX(el, recipeFactory, options = {}) {
     el.parentNode.insertBefore(canvas, el.nextSibling);
     canvasAppended = true;
 
+    // prefers-reduced-motion query (U5): initial value read into state below,
+    // BEFORE recipe.init (same as mountUIFX).
+    const rmq = _reducedMotionQuery();
+
     // -- State. Generic fields wire like hijack mode; text/valid mirror the host,
     //    read now at init (law: hook initial values from the element) and refreshed
     //    at event time only. --
@@ -849,6 +959,8 @@ export function decorateUIFX(el, recipeFactory, options = {}) {
         focused: (typeof document !== 'undefined' && document.activeElement === el),
         text: (typeof el.value === 'string' ? el.value : ''),
         valid: (el.validity ? !!el.validity.valid : true),
+        reducedMotion: rmq ? !!rmq.matches : false,  // U5: calm-path recipes honour it
+        budget: 1,          // U5: 0..1 frame budget, updated in place per frame
         w: ow, h: oh, padding, dpr,
     };
     const pointer = { x: -999, y: -999, vx: 0, vy: 0 };
@@ -948,17 +1060,28 @@ export function decorateUIFX(el, recipeFactory, options = {}) {
         }, { signal });
     }
 
-    // -- Render loop (shared ticker; same quarantine-on-throw as mountUIFX). --
-    const ticker = acquireTicker();
-    tickerAcquired = true;
+    // -- Reduced-motion change watch (U5). Cold; through signal. --
+    if (rmq) {
+        rmq.addEventListener('change', () => { state.reducedMotion = !!rmq.matches; }, { signal });
+    }
+
+    // -- Render loop. ONE named frame body; three clock modes invoke it with no
+    //    wrapper (same as mountUIFX). Same quarantine-on-throw. --
     let destroyed = false;
     let quarantined = false;
 
-    removeTick = ticker.add((dtMs) => {
+    function frame(dtMs) {
         if (destroyed || quarantined) return;
         const dt = dtMs / 1000;
         const now = performance.now();
 
+        // Frame budget (U5): update in place, no allocation.
+        if (dt > 0) {
+            let inst = _TARGET_DT / dt;
+            if (inst > 1) inst = 1; else if (inst < 0) inst = 0;
+            state.budget += (inst - state.budget) * _BUDGET_SMOOTH;
+        }
+
         ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
         ctx.clearRect(0, 0, cw, ch);
         ctx.save();
@@ -973,7 +1096,19 @@ export function decorateUIFX(el, recipeFactory, options = {}) {
             return;
         }
         ctx.restore();
-    });
+    }
+
+    // Clock mode (validated cold in phase 1). Shared ticker / caller ticker /
+    // driven -- identical to mountUIFX.
+    if (driven) {
+        // no ticker acquired; removeTick stays null
+    } else if (callerTicker !== undefined) {
+        removeTick = callerTicker.add(frame);
+    } else {
+        const ticker = acquireTicker();
+        tickerAcquired = true;
+        removeTick = ticker.add(frame);
+    }
 
     // -- Public API --
     return {
@@ -986,6 +1121,12 @@ export function decorateUIFX(el, recipeFactory, options = {}) {
         /** Current state (read-only reference). */
         state,
 
+        /**
+         * Drive one frame by hand (U5). Callable ONLY in { driven: true } mode; it
+         * IS the internal frame body. A ticker-driven decoration fails closed.
+         */
+        tick: driven ? frame : _drivenOnly,
+
         /**
          * Hijack-only. A decoration reflects the host; it does not own or push
          * into the host's value, so setValue/setChecked fail closed here (use the
@@ -1004,9 +1145,9 @@ export function decorateUIFX(el, recipeFactory, options = {}) {
             if (destroyed) return;
             destroyed = true;
             ac.abort();
-            removeTick();
+            if (removeTick) removeTick();        // shared OR caller ticker; null when driven
             if (recipe.destroy) recipe.destroy();
-            releaseTicker();
+            if (tickerAcquired) releaseTicker();  // release ONLY the shared ticker we acquired
             canvas.remove();  // the ONLY DOM node decorate added
         },
     };
@@ -1014,10 +1155,8 @@ export function decorateUIFX(el, recipeFactory, options = {}) {
         // A phase-2 step threw (realistically recipe.init). Unwind ONLY what was
         // acquired, reverse order, each flag-guarded. recipe.destroy is NOT called
         // (init did not succeed). Re-throw the ORIGINAL error, unwrapped.
-        if (tickerAcquired) {
-            if (removeTick) removeTick();
-            releaseTicker();
-        }
+        if (removeTick) removeTick();          // shared OR caller ticker -- both must unwind
+        if (tickerAcquired) releaseTicker();   // release ONLY the shared ticker we acquired
         if (acCreated) ac.abort();
         if (canvasAppended) canvas.remove();
         throw err;

package/UIFXRecipes.js

@@ -235,16 +235,26 @@ export function SwarmToggle(o = {}) {
             // Knob target position
             const tx = st.toggled ? st.w - 18 : 18;
 
-            // Render particles (spring toward formation)
+            // Render particles (spring toward formation). Under reduced motion
+            // (U5) they REST at the formation -- no swarm drift, no explosion --
+            // so the toggle reads as a static knob. This is the reference calm path.
             ctx.fillStyle = st.toggled ? P.accent : P.dim;
-            for (let i = 0; i < N; i++) {
-                vx[i] += ((tx + ox[i]) - px[i]) * 15 * dt;
-                vy[i] += ((st.h / 2 + oy[i]) - py[i]) * 15 * dt;
-                vx[i] *= 0.85;
-                vy[i] *= 0.85;
-                px[i] += vx[i] * dt;
-                py[i] += vy[i] * dt;
-                ctx.fillRect(px[i], py[i], 1.5, 1.5);
+            if (st.reducedMotion) {
+                for (let i = 0; i < N; i++) {
+                    px[i] = tx + ox[i];
+                    py[i] = st.h / 2 + oy[i];
+                    ctx.fillRect(px[i], py[i], 1.5, 1.5);
+                }
+            } else {
+                for (let i = 0; i < N; i++) {
+                    vx[i] += ((tx + ox[i]) - px[i]) * 15 * dt;
+                    vy[i] += ((st.h / 2 + oy[i]) - py[i]) * 15 * dt;
+                    vx[i] *= 0.85;
+                    vy[i] *= 0.85;
+                    px[i] += vx[i] * dt;
+                    py[i] += vy[i] * dt;
+                    ctx.fillRect(px[i], py[i], 1.5, 1.5);
+                }
             }
 
             if (st.focused) drawFocusRing(ctx, st.w, st.h, st.h / 2);
@@ -2335,7 +2345,8 @@ export function PasswordStrength(o = {}) {
             const t = st.text || '';
             if (t !== lastText) { lastText = t; strength = pwStrength(t); }
             const level=Math.ceil(strength*4);
-            for(let i=0;i<4;i++) segs[i]=lerp(segs[i],i<level?1:0,dt*10);
+            // Reduced motion (U5): snap segments to their level (no grow animation).
+            for(let i=0;i<4;i++) segs[i]=st.reducedMotion?(i<level?1:0):lerp(segs[i],i<level?1:0,dt*10);
 
             const segW=(st.w-12)/4,segH=8;
             for(let i=0;i<4;i++){
@@ -2604,15 +2615,17 @@ export function TypewriterField(o = {}) {
     return {
         tick(c,dt,now,st) {
             const len=(st.text || '').length;
-            if(len>lastLen) spark=1;   // a new char landed -> caret pulse
+            // Reduced motion (U5): no keystroke pulse, no caret blink, underline
+            // snaps to length -- a steady underline + steady caret, zero animation.
+            if(len>lastLen && !st.reducedMotion) spark=1;   // a new char landed -> caret pulse
             lastLen=len;
-            blink=(blink+dt*3)%2;
-            spark=spark>0?spark-dt*3:0;
+            if(!st.reducedMotion) blink=(blink+dt*3)%2;
+            spark=st.reducedMotion?0:(spark>0?spark-dt*3:0);
 
             // Underline grows toward a fraction of the width set by text length
             // (capped at ~24 chars = full width). No measureText -> zero-alloc.
             const target=len===0?0:Math.min(len/24,1);
-            fill=lerp(fill,target,dt*8);
+            fill=st.reducedMotion?target:lerp(fill,target,dt*8);
             const y=st.h-3, x0=2, x1=2+(st.w-4)*fill;
 
             c.strokeStyle='rgba(255,255,255,.08)';c.lineWidth=2;
@@ -2626,7 +2639,7 @@ export function TypewriterField(o = {}) {
                 c.beginPath();c.arc(x1,y,4+spark*3,0,PI2);c.fill();
                 c.globalAlpha=1;
             }
-            if(st.focused&&blink<1){
+            if(st.focused&&(st.reducedMotion||blink<1)){
                 c.fillStyle=P.accent;c.fillRect(x1,y-9,1.5,12);
             }
         },
@@ -2909,7 +2922,8 @@ export function FocusHalo(o = {}) {
         tick(c,dt,now,st) {
             halo=lerp(halo, st.focused?1:0, dt*8);
             if(halo<0.01) return;
-            const breathe=0.75+Math.sin(now/380)*0.25, r=8;
+            // Reduced motion (U5): a steady halo, no breathing pulse.
+            const breathe=st.reducedMotion?1:0.75+Math.sin(now/380)*0.25, r=8;
             c.strokeStyle=P.accent;
             for(let i=3;i>=1;i--){
                 c.globalAlpha=halo*breathe*(0.10*i);
@@ -2936,7 +2950,9 @@ export function ErrorShake(o = {}) {
             shake = shake>0 ? shake-dt*1.6 : 0;
             if(shake<0.01 && st.valid!==false) return;   // nothing to show
 
-            const dx = shake>0 ? Math.sin(now/22)*shake*6 : 0;
+            // Reduced motion (U5): the border appears/holds but NEVER shakes
+            // (dx stays 0) -- the whole point of the media query.
+            const dx = (shake>0 && !st.reducedMotion) ? Math.sin(now/22)*shake*6 : 0;
             const a = st.valid===false ? 0.9 : shake, r=8;
             c.globalAlpha=a;c.strokeStyle=P.accent;c.lineWidth=2;
             rr(c,dx,0,st.w,st.h,r);c.stroke();
@@ -2955,6 +2971,7 @@ export function SuccessBloom(o = {}) {
     let wasValid=true, ring=0;
     function bloom(st){
         ring=1;
+        if(st.reducedMotion) return;   // U5 calm: a fading ring only, no particle burst
         const cx=st.w/2, cy=st.h/2;
         for(let i=0;i<N;i++){
             const ang=(i/N)*PI2, sp=40+(i%5)*8;
@@ -2969,7 +2986,8 @@ export function SuccessBloom(o = {}) {
 
             if(ring>0){
                 ring-=dt*1.4; if(ring<0) ring=0;
-                const cx=st.w/2, cy=st.h/2, rad=(1-ring)*st.w*0.6;
+                // Reduced motion (U5): a fixed-radius ring that fades (alpha), no expansion.
+                const cx=st.w/2, cy=st.h/2, rad=st.reducedMotion?st.w*0.5:(1-ring)*st.w*0.6;
                 c.globalAlpha=ring;c.strokeStyle=P.accent;c.lineWidth=2;
                 c.beginPath();c.arc(cx,cy,rad,0,PI2);c.stroke();
                 c.globalAlpha=1;
@@ -3149,7 +3167,7 @@ export const RECIPES = Object.assign(Object.create(null), {
  *   motionSafe inherently-calm under prefers-reduced-motion (false for all -- U5)
  */
 export const RECIPE_META = [
-    { id: 'swarmToggle', name: 'Swarm Toggle', type: 'toggle', family: 'Toggles', themeable: true, motionSafe: false },
+    { id: 'swarmToggle', name: 'Swarm Toggle', type: 'toggle', family: 'Toggles', themeable: true, motionSafe: true },
     { id: 'liquidToggle', name: 'Liquid Toggle', type: 'toggle', family: 'Toggles', themeable: true, motionSafe: false },
     { id: 'neonPulseToggle', name: 'Neon Pulse Toggle', type: 'toggle', family: 'Toggles', themeable: true, motionSafe: false },
     { id: 'magneticButton', name: 'Magnetic Button', type: 'button', family: 'Buttons', themeable: true, motionSafe: false },
@@ -3190,21 +3208,21 @@ export const RECIPE_META = [
     { id: 'pillTabs', name: 'Pill Tabs', type: 'button', family: 'Controls', themeable: true, motionSafe: false },
     { id: 'stepper', name: 'Stepper', type: 'button', family: 'Controls', themeable: true, motionSafe: false },
     { id: 'radioOrbit', name: 'Radio Orbit', type: 'slider', family: 'Controls', themeable: true, motionSafe: false },
-    { id: 'passwordStrength', name: 'Password Strength', type: 'decorate', family: 'Indicators', themeable: true, motionSafe: false },
+    { id: 'passwordStrength', name: 'Password Strength', type: 'decorate', family: 'Indicators', themeable: true, motionSafe: true },
     { id: 'waterLevel', name: 'Water Level', type: 'slider', family: 'Indicators', themeable: true, motionSafe: false },
     { id: 'heatMap', name: 'Heat Map', type: 'slider', family: 'Indicators', themeable: true, motionSafe: false },
     { id: 'dayNightToggle', name: 'Day Night Toggle', type: 'toggle', family: 'Mood', themeable: true, motionSafe: false },
     { id: 'reactionPicker', name: 'Reaction Picker', type: 'button', family: 'Mood', themeable: true, motionSafe: false },
     { id: 'notificationBell', name: 'Notification Bell', type: 'button', family: 'Mood', themeable: true, motionSafe: false },
-    { id: 'typewriterField', name: 'Typewriter Field', type: 'decorate', family: 'Feedback', themeable: true, motionSafe: false },
+    { id: 'typewriterField', name: 'Typewriter Field', type: 'decorate', family: 'Feedback', themeable: true, motionSafe: true },
     { id: 'soundWaveBtn', name: 'Sound Wave Btn', type: 'button', family: 'Feedback', themeable: true, motionSafe: false },
     { id: 'uploadProgress', name: 'Upload Progress', type: 'progress', family: 'Feedback', themeable: true, motionSafe: false },
     { id: 'scratchReveal', name: 'Scratch Reveal', type: 'slider', family: 'Fun', themeable: true, motionSafe: false },
     { id: 'timerCountdown', name: 'Timer Countdown', type: 'toggle', family: 'Fun', themeable: true, motionSafe: false },
     { id: 'pullRefresh', name: 'Pull Refresh', type: 'slider', family: 'Fun', themeable: true, motionSafe: false },
-    { id: 'focusHalo', name: 'Focus Halo', type: 'decorate', family: 'Form', themeable: true, motionSafe: false },
-    { id: 'errorShake', name: 'Error Shake', type: 'decorate', family: 'Form', themeable: true, motionSafe: false },
-    { id: 'successBloom', name: 'Success Bloom', type: 'decorate', family: 'Form', themeable: true, motionSafe: false },
+    { id: 'focusHalo', name: 'Focus Halo', type: 'decorate', family: 'Form', themeable: true, motionSafe: true },
+    { id: 'errorShake', name: 'Error Shake', type: 'decorate', family: 'Form', themeable: true, motionSafe: true },
+    { id: 'successBloom', name: 'Success Bloom', type: 'decorate', family: 'Form', themeable: true, motionSafe: true },
 ];
 
 /** Names of every built-in recipe (the keys of RECIPES at load time). */
@@ -3329,6 +3347,15 @@ export function mountRecipe(container, id, options) {
     }
     const meta = RECIPE_META.find((m) => m.id === id) || null;
     const type = meta ? meta.type : undefined;
+    // Reduced-motion advisory (U5, decisions/0005): a recipe with no calm path,
+    // mounted while the user prefers reduced motion, gets a console.warn -- advice,
+    // not a gate (a host may run its own toggle). Cold, mount-time only; a missing
+    // matchMedia is a silent skip (fail closed, never throw).
+    if (meta && meta.motionSafe === false &&
+        typeof window !== 'undefined' && typeof window.matchMedia === 'function' &&
+        window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+        console.warn('mountRecipe: recipe "' + id + '" is not motionSafe and the user prefers reduced motion; it will animate. See RECIPE_META.motionSafe.');
+    }
     if (options && 'type' in options && options.type !== type) {
         throw new Error(
             'mountRecipe: recipe "' + id + '" mounts as "' + type +

package/llms.txt

@@ -1,7 +1,7 @@
 # @zakkster/lite-ui-fx
 > Canvas-hijacked UI components with pluggable recipe system. 56 built-in recipes.
 
-VERSION 1.6.0
+VERSION 1.7.0
 
 ## Install
 npm i @zakkster/lite-ui-fx
@@ -54,10 +54,24 @@ text      // visible canvas label; falls back to label, then the recipe default
 font      // canvas font string; falls back to the recipe's historical font
 knobMode  // KNOB only: 'rotate' | 'vertical' pointer mapping (default 'rotate'); wrong type throws
 announce  // PROGRESS only: opt-in aria-live announcements at 10% steps; wrong type throws
-// decorateUIFX accepts a SUBSET: padding, seed, colors, theme, text, font. The
+ticker    // U5 host clock: a caller-supplied lite-ticker ({ add(fn)->removeFn }) drives this component
+driven    // U5 host clock: boolean; true = no ticker/RAF, the host calls instance.tick(dtMs)
+// decorateUIFX accepts a SUBSET: padding, seed, colors, theme, text, font -- PLUS
+// the host-clock keys ticker/driven (a decoration wants clock control too). The
 // hijack-only keys (width/height/value/checked/disabled/knobMode/announce/label)
 // throw in decorate mode -- geometry comes from the host, value is read from it.
 
+## Host clock (U5) -- three mutually-exclusive modes, both mount modes
+// default (neither option): the shared ref-counted ticker -- one RAF for all
+//   components, byte-identical to earlier versions.
+// { ticker: t }: a caller-supplied lite-ticker drives this component. destroy()
+//   removes the component's frame but NEVER destroys the caller's ticker.
+const inst = mountUIFX(container, UIType.SLIDER, SparkSlider, { ticker: myTicker });
+// { driven: true }: no ticker/RAF at all; the host drives each frame by hand.
+const d = mountUIFX(container, UIType.BUTTON, MagneticButton, { driven: true });
+d.tick(16.7);   // one frame; the SAME body the ticker would call. throws when NOT driven.
+// Passing both, a non-boolean driven, or a ticker without .add() throws (fail closed).
+
 ## Element Types
 UIType.TOGGLE   -> <input type="checkbox" role="switch"> -> state.toggled, onToggle(checked)
 UIType.BUTTON   -> <button> -> state.active, onClick(x, y, state)
@@ -69,8 +83,13 @@ UIType.KNOB     -> <input type="range"> -> state.val, arrows native + knobMode p
                    RECIPE_META.type 'decorate' routes mountRecipe to decorateUIFX. State: focused + text + valid.
 
 ## State Object (provided to tick every frame)
-{ hover, active, focused, toggled, indeterminate, disabled, val, w, h, padding, dpr }
-// decorate mode adds: text (host value string), valid (host validity boolean).
+{ hover, active, focused, toggled, indeterminate, disabled, val, w, h, padding, dpr,
+  reducedMotion, budget }
+// reducedMotion (U5): boolean, true when the user prefers reduced motion; a
+//   calm-path recipe renders statically when set (RECIPE_META.motionSafe marks which).
+// budget (U5): 0..1 frame budget, 1 at ~60fps, lower as frames lengthen; budget-aware
+//   recipes shed work (particles/glow) when it drops.
+// decorate mode also adds: text (host value string), valid (host validity boolean).
 
 ## 56 Built-in Recipes
 
@@ -123,9 +142,19 @@ See UIFX-RECIPE-GUIDE.md (included in package).
   Gated per recipe by the t3-frame-alloc torture tier (default AND themed mount).
 - Themeable: all 56 recipes honour { colors, theme:{light,mid,dark}, text, font },
   resolved once in init (zero per-frame alloc). RECIPE_META.themeable is true for
-  all 56; motionSafe stays false (reduced motion is a later pass). A bare mount is
-  byte-identical to pre-theming. Shipped palettes + APCA contrast are authored with
-  @zakkster/lite-hueforge (a dev-only tool, never a runtime dependency).
+  all 56. A bare mount is byte-identical to pre-theming. Shipped palettes + APCA
+  contrast are authored with @zakkster/lite-hueforge (a dev-only tool, never a
+  runtime dependency).
+- U5 host clock: mount { ticker } to ride a caller-supplied lite-ticker (destroy
+  never destroys the caller's clock) or { driven:true } to drive instance.tick(dtMs)
+  by hand (no RAF); omit both for the shared ref-counted ticker. Default byte-identical.
+- U5 reduced motion: state.reducedMotion (matchMedia, watched) makes calm-path
+  recipes render statically -- ErrorShake stops shaking, SwarmToggle/SuccessBloom/
+  FocusHalo drop their motion. RECIPE_META.motionSafe is true for EXACTLY the
+  recipes that ship a calm path (SwarmToggle + the 5 decorate recipes today; the
+  rest honestly false until each lands one). mountRecipe warns (not throws) mounting
+  a motionSafe:false recipe under active reduce. state.budget (0..1) lets budget-aware
+  recipes shed work before frames drop.
 - U4a element types: CHECKBOX (indeterminate), PROGRESS (setValue-driven, aria-live
   opt-in), KNOB (knobMode pointer map); setValue/setChecked sync native+state+hook once.
 - U4b decorate mode (decorateUIFX): a canvas AROUND a live element -- no hijack, no

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-ui-fx",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Canvas-hijacked UI components with a pluggable recipe system. 50 built-in recipes across toggles, buttons, sliders, knobs, loaders, checkboxes, counters, and ratings.",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
   "license": "MIT",