@zakkster/lite-ui-fx 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,107 @@ All notable changes to `@zakkster/lite-ui-fx` are documented here.
 The format follows Keep a Changelog; this project adheres to Semantic
 Versioning.
 
+## [1.5.0] -- 2026-09-07
+
+New native element types (U4a, the first half of roadmap U4). Vol.3 faked
+checkboxes as `role=switch` toggles and knobs/progress meters as sliders; U4a
+promotes them to their true native elements (law 1). Additive: a bare mount of
+any existing recipe is unchanged; 50 -> 53 recipes. Decorate mode is U4b.
+
+### Added
+
+- Three `UIType`s, each wrapping the correct native element: `CHECKBOX`
+  (`<input type=checkbox>`, no `role=switch`; indeterminate via `setValue(null)`,
+  exposed as `state.indeterminate`), `PROGRESS` (native `<progress>`,
+  non-interactive, value written by `setValue`; opt-in `announce` adds a
+  visually-hidden `aria-live=polite` region updated at 10% steps), and `KNOB`
+  (`<input type=range>`, arrow keys native, canvas-side `knobMode`
+  `'rotate' | 'vertical'` pointer mapping).
+- `instance.setValue(v)` / `instance.setChecked(b)`: one call syncs the native
+  element, `state`, any PROGRESS announcer, and fires the recipe hook
+  (`onDrag`/`onToggle`) exactly once (a programmatic write emits no native event).
+- Options `knobMode` (KNOB-only) and `announce` (PROGRESS-only), both validated
+  fail-closed (presence on the wrong type throws).
+- Three recipes, born themed and t3-gated: `TickDraw`, `IndeterminateScan`
+  (CHECKBOX, honouring `state.indeterminate`), `LiquidFill` (PROGRESS). Registered
+  in `RECIPES` / `RECIPE_META` / the default export / a new `UIFXRecipes4` barrel.
+- `decisions/0003-element-types.md`; controller `npm test` coverage for the new
+  types; t2 gains the CHECKBOX-no-switch, PROGRESS-value, KNOB-arrows, and
+  `setValue`/`setChecked`-once contracts (A10-A13).
+
+### Changed
+
+- Eight Vol.3 recipes re-homed onto their true types (rippleCheck/morphCheck ->
+  checkbox; volumeKnob/compassKnob -> knob; ringProgress/batteryGauge/signalMeter/
+  uploadProgress -> progress). Re-home is a `RECIPE_META.type` string change only
+  -- no recipe body touched -- so each renders byte-identical to 1.4.0 (proven by
+  `git diff`); new types keep the donor's default geometry (checkbox 64x36,
+  knob/progress 200x28).
+- The mount type guard and `registerRecipe` both derive their valid-type set from
+  `UIType`, so the controller, the registry, and the d.ts cannot drift as types
+  are added; an unknown type still throws (fail closed).
+- Torture: `makeChurn` drives the new types (checkbox like toggle + sweeps
+  indeterminate, knob like slider, progress sweeps value with no hook); t0/t5
+  synthetic batches iterate all six types; the t3 tier now gates 53 recipes
+  (default AND themed). `npm test` 164 pass; torture `gc major=0`, `alloc=0 B/op`.
+- Docs (`llms.txt`, `README.md`, both `.d.ts`) updated to 53 recipes and the new
+  types / options / methods.
+
+### Fixed
+
+- The Vol.3 semantic mis-mounts: a checkbox is no longer announced as a switch
+  (WCAG role match), and progress meters are non-interactive rather than
+  user-draggable sliders.
+
+## [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/README.md

@@ -21,26 +21,26 @@ https://cdpn.io/pen/debug/yyaPKpB
 ## Live Demo (UI-FX vol3.)
 https://cdpn.io/pen/debug/YPGEaYY
 
-**50 recipes** across UI element categories:
+**53 recipes** across UI element categories:
 
 - **Toggles** -- Swarm, Liquid, Neon Pulse, Pendulum, Circuit, Lightning, DNA
 - **Buttons** -- Magnetic, Shatter, Confetti, Glitch, Heartbeat, Breathing, Ink Splash, Pixel Dissolve, Firework
 - **Sliders** -- Spark, Cosmic Void, Laser, Aurora, Wave, Elastic Band, Gravity
 - **Knobs** -- Volume dial, Compass needle
-- **Progress** -- Ring, Battery, Signal meter
+- **Progress** -- Ring, Battery, Signal meter, Liquid Fill
 - **Controls** -- Pill tabs, Stepper, Radio orbit
 - **Indicators** -- Password strength, Water level, Heat map
 - **Mood** -- Day/night, Reaction picker, Notification bell
 - **Feedback** -- Typewriter, Sound wave, Upload progress
 - **Fun** -- Scratch reveal, Timer countdown, Pull refresh
-- **Checkboxes** -- Ripple, Morph (X to check)
+- **Checkboxes** -- Ripple, Morph (X to check), Tick Draw, Indeterminate Scan
 - **Loaders** -- Orbit planets, DNA helix
 - **Counters** -- Flame heat, Glitch signal
 - **Rating** -- Bubble inflate
 
 Every recipe is zero-GC, uses `dt`-based animation, and includes accessibility indicators (focus rings, state labels).
 
-All 50 recipes ship in the package on the `./recipes` subpath -- versioned,
+All 53 recipes ship in the package on the `./recipes` subpath -- versioned,
 typed, and tree-shakeable. With `sideEffects: false`, importing one recipe pulls
 in only that recipe, so a controller-only install stays tiny.
 
@@ -65,7 +65,7 @@ Part of the [@zakkster/lite-*](https://www.npmjs.com/org/zakkster) ecosystem.
 npm i @zakkster/lite-ui-fx
 ```
 
-> The 50 recipes ship in the same package on the `./recipes` subpath and
+> The 53 recipes ship in the same package on the `./recipes` subpath and
 > tree-shake, so importing one adds only that one.
 
 
@@ -97,7 +97,7 @@ instance.destroy();
 // Controller (always needed)
 import { mountUIFX, UIType } from '@zakkster/lite-ui-fx';
 
-// All 50 recipes ship on the ./recipes subpath (tree-shakeable) -- import by name:
+// All 53 recipes ship on the ./recipes subpath (tree-shakeable) -- import by name:
 import { SwarmToggle, MagneticButton, SparkSlider } from '@zakkster/lite-ui-fx/recipes';
 import { PendulumToggle, HeartbeatButton, RippleCheck } from '@zakkster/lite-ui-fx/recipes';
 import { VolumeKnob, WaterLevel, TimerCountdown } from '@zakkster/lite-ui-fx/recipes';
@@ -136,7 +136,7 @@ import { RECIPES, RECIPE_META, RECIPE_NAMES, registerRecipe, mountRecipe } from
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `container` | `HTMLElement` | Parent to mount into |
-| `type` | `'button' \| 'toggle' \| 'slider'` | Determines native element type |
+| `type` | `'button' \| 'toggle' \| 'slider' \| 'checkbox' \| 'progress' \| 'knob'` | Determines native element type |
 | `recipeFactory` | `() => Recipe` | Factory function (controller calls it) |
 | `options.width` | `number` | Element width (auto from type if omitted) |
 | `options.height` | `number` | Element height |
@@ -145,8 +145,18 @@ import { RECIPES, RECIPE_META, RECIPE_NAMES, registerRecipe, mountRecipe } from
 | `options.value` | `number` | Slider initial value, 0..1 (default 0.5); out-of-range throws |
 | `options.checked` | `boolean` | Toggle initial state (default false) |
 | `options.disabled` | `boolean` | Disables the native element; sets `state.disabled` |
+| `options.knobMode` | `'rotate' \| 'vertical'` | KNOB only: pointer-to-value mapping (default `'rotate'`); wrong type throws |
+| `options.announce` | `boolean` | PROGRESS only: opt-in `aria-live` announcements at 10% steps; wrong type throws |
 
-Returns `{ el, canvas, wrapper, state, destroy() }`.
+Recipe theming options (`seed`, `colors`, `theme`, `text`, `font`) are also
+accepted and forwarded to the recipe -- see `llms.txt` for the full option surface.
+
+Returns `{ el, canvas, wrapper, state, setValue(v), setChecked(b), destroy() }`.
+
+- `setValue(v)` -- SLIDER/KNOB/PROGRESS: set `v` in `0..1` (updates the element +
+  `state.val`, fires `onDrag` once). CHECKBOX: `setValue(null)` sets indeterminate.
+- `setChecked(b)` -- TOGGLE/CHECKBOX: set checked (updates the element +
+  `state.toggled`, fires `onToggle` once).
 
 ### Element Types
 
@@ -155,6 +165,9 @@ Returns `{ el, canvas, wrapper, state, destroy() }`.
 | `UIType.TOGGLE` | `<input type="checkbox" role="switch">` | `onToggle(checked)` | `state.toggled` |
 | `UIType.BUTTON` | `<button>` | `onClick(x, y, state)` | `state.active` |
 | `UIType.SLIDER` | `<input type="range">` | `onDrag(val, velocity)` | `state.val` (0-1) |
+| `UIType.CHECKBOX` | `<input type="checkbox">` (no `role=switch`) | `onToggle(checked)` | `state.toggled`, `state.indeterminate` |
+| `UIType.PROGRESS` | `<progress>` (non-interactive) | (driven by `setValue`) | `state.val` (0-1) |
+| `UIType.KNOB` | `<input type="range">` | `onDrag(val, velocity)` | `state.val` (0-1) |
 
 ### State Object (provided to `tick()` every frame)
 
@@ -163,7 +176,8 @@ Returns `{ el, canvas, wrapper, state, destroy() }`.
     hover: boolean;      // Pointer inside element
     active: boolean;     // Pointer pressed
     focused: boolean;    // Keyboard focus
-    toggled: boolean;    // Checkbox state
+    toggled: boolean;    // Checkbox/toggle state
+    indeterminate: boolean; // CHECKBOX only: native indeterminate (setValue(null))
     disabled: boolean;   // Disabled via options.disabled
     val: number;         // Slider value (0-1)
     w: number;           // Element width
@@ -180,7 +194,7 @@ Returns `{ el, canvas, wrapper, state, destroy() }`.
 | Framer Motion | ~45 KB | React HOC | 0 | Via React | `npm i framer-motion` |
 | GSAP | ~25 KB | Timeline | 0 | Manual | `npm i gsap` |
 | Lottie | ~55 KB | JSON animation | After Effects | Manual | `npm i lottie-web` |
-| **lite-ui-fx** | **< 5 KB** | **Canvas hijack** | **50 built-in** | **Native + visual** | **`npm i @zakkster/lite-ui-fx`** |
+| **lite-ui-fx** | **< 5 KB** | **Canvas hijack** | **53 built-in** | **Native + visual** | **`npm i @zakkster/lite-ui-fx`** |
 
 ## Writing Custom Recipes
 

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

@@ -1,11 +1,17 @@
 export declare const VERSION: string;
 
-export type UITypeValue = 'button' | 'toggle' | 'slider';
+export type UITypeValue = 'button' | 'toggle' | 'slider' | 'checkbox' | 'progress' | 'knob';
 
 export declare const UIType: Readonly<{
     BUTTON: 'button';
     TOGGLE: 'toggle';
     SLIDER: 'slider';
+    /** Plain checkbox (no role=switch); indeterminate via setValue(null). */
+    CHECKBOX: 'checkbox';
+    /** Native <progress>, non-interactive; value driven by setValue. */
+    PROGRESS: 'progress';
+    /** <input type=range>; arrows native, pointer mapped by knobMode. */
+    KNOB: 'knob';
 }>;
 
 export interface UIFXState {
@@ -13,6 +19,8 @@ export interface UIFXState {
     active: boolean;
     focused: boolean;
     toggled: boolean;
+    /** CHECKBOX only: the native indeterminate state (set via setValue(null)). */
+    indeterminate: boolean;
     disabled: boolean;
     val: number;
     w: number;
@@ -59,6 +67,23 @@ 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;
+    /** KNOB only: pointer-to-value mapping (default 'rotate'). Throws on any other type. */
+    knobMode?: 'rotate' | 'vertical';
+    /** PROGRESS only: opt-in aria-live announcements at 10% steps. Throws on any other type. */
+    announce?: boolean;
 }
 
 export interface UIFXInstance {
@@ -67,6 +92,21 @@ export interface UIFXInstance {
     wrapper: HTMLDivElement;
     state: UIFXState;
 
+    /**
+     * 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.
+     * For a CHECKBOX, setValue(null) sets the indeterminate state. Throws on the
+     * wrong element type or an out-of-range value.
+     */
+    setValue(v: number | null): void;
+
+    /**
+     * Set a TOGGLE/CHECKBOX checked state: updates the native element,
+     * state.toggled, clears indeterminate, and fires onToggle exactly once.
+     * Throws on any other element type.
+     */
+    setChecked(b: boolean): void;
+
     destroy(): void;
 }
 

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.5.0';
 
 // ---------------------------------------------------------
 //  SHARED TICKER (ref-counted, one RAF for all UI components)
@@ -84,7 +84,8 @@ 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', 'knobMode', 'announce'];
+const KNOB_MODES = ['rotate', 'vertical'];
 
 // Levenshtein edit distance. Cold: only reached on the error path.
 function _editDistance(a, b) {
@@ -143,8 +144,15 @@ export const UIType = Object.freeze({
     BUTTON: 'button',
     TOGGLE: 'toggle',
     SLIDER: 'slider',
+    CHECKBOX: 'checkbox',   // <input type=checkbox> WITHOUT role=switch (a check is not a switch)
+    PROGRESS: 'progress',   // native <progress>, non-interactive, value driven programmatically
+    KNOB: 'knob',           // <input type=range>, arrows native, canvas-side knobMode pointer map
 });
 
+// The valid mount types, derived once from UIType so the controller guard, the
+// recipe registry, and the d.ts never drift apart. Cold: read only at mount.
+const _KNOWN_TYPES = new Set(Object.values(UIType));
+
 
 // =========================================================
 //  UIFXController -- The Canvas Hijacker
@@ -177,11 +185,11 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
         throw new Error('mountUIFX: container must be a DOM element');
     }
 
-    // 1b. type: exactly one of the three known element types. An unknown or
+    // 1b. type: exactly one of the known element types (UIType). An unknown or
     //     undefined type is an Error here, never a silent default to a button
     //     (fail closed -- the type selects the native element).
-    if (type !== UIType.BUTTON && type !== UIType.TOGGLE && type !== UIType.SLIDER) {
-        throw new Error('mountUIFX: type must be UIType.BUTTON, UIType.TOGGLE, or UIType.SLIDER');
+    if (!_KNOWN_TYPES.has(type)) {
+        throw new Error('mountUIFX: type must be one of UIType.BUTTON, TOGGLE, SLIDER, CHECKBOX, PROGRESS, KNOB');
     }
 
     // 2. options: unknown keys -> did-you-mean; value/checked/disabled
@@ -205,6 +213,55 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
     const height = options.height;
     const padding = options.padding === undefined ? 40 : options.padding;
     const label = options.label === undefined ? '' : options.label;
+    const knobMode = options.knobMode || 'rotate';   // KNOB pointer map; validated below
+    const announce = options.announce === true;       // PROGRESS aria-live; validated below
+
+    // 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');
+    }
+
+    // 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.
+    if (options.knobMode !== undefined) {
+        if (type !== UIType.KNOB) {
+            throw new Error('mountUIFX: option "knobMode" is only valid for UIType.KNOB');
+        }
+        if (KNOB_MODES.indexOf(options.knobMode) === -1) {
+            throw new Error('mountUIFX: option "knobMode" must be "rotate" or "vertical"');
+        }
+    }
+    if (options.announce !== undefined) {
+        if (type !== UIType.PROGRESS) {
+            throw new Error('mountUIFX: option "announce" is only valid for UIType.PROGRESS');
+        }
+        if (typeof options.announce !== 'boolean') {
+            throw new Error('mountUIFX: option "announce" must be a boolean');
+        }
+    }
 
     // 3. recipeFactory
     if (typeof recipeFactory !== 'function') {
@@ -252,24 +309,37 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
 
     try {
     // -- Resolve dimensions --
-    const w = width  || (type === UIType.BUTTON ? 160 : type === UIType.SLIDER ? 200 : 64);
-    const h = height || (type === UIType.BUTTON ? 48  : type === UIType.SLIDER ? 28  : 36);
+    // SLIDER/PROGRESS/KNOB share the 200x28 range geometry (so every vol.3
+    // re-home renders byte-identical to its slider era); CHECKBOX shares the
+    // 64x36 toggle geometry; BUTTON keeps 160x48.
+    const _rangeLike = type === UIType.SLIDER || type === UIType.PROGRESS || type === UIType.KNOB;
+    const w = width  || (type === UIType.BUTTON ? 160 : _rangeLike ? 200 : 64);
+    const h = height || (type === UIType.BUTTON ? 48  : _rangeLike ? 28  : 36);
     let dpr = window.devicePixelRatio || 1;
 
     // -- Create native element (invisible, accessible, receives events) --
     let el;
-    if (type === UIType.TOGGLE) {
+    if (type === UIType.TOGGLE || type === UIType.CHECKBOX) {
         el = document.createElement('input');
         el.type = 'checkbox';
-        el.setAttribute('role', 'switch');
+        // TOGGLE is a switch; CHECKBOX is a plain checkbox. A check is not a
+        // switch -- U4a drops the role for CHECKBOX (the vol.3 mis-mount fix).
+        if (type === UIType.TOGGLE) el.setAttribute('role', 'switch');
         el.checked = checked;  // coerced boolean; lands before frame 1
         if (label) el.setAttribute('aria-label', label);
-    } else if (type === UIType.SLIDER) {
+    } else if (type === UIType.SLIDER || type === UIType.KNOB) {
         el = document.createElement('input');
         el.type = 'range';
         el.min = '0'; el.max = '100';
         el.value = value !== undefined ? String(value * 100) : '50';  // 0..1 -> 0..100
         if (label) el.setAttribute('aria-label', label);
+    } else if (type === UIType.PROGRESS) {
+        // Non-interactive: value is written programmatically (setValue) only,
+        // and exposed to assistive tech by the native <progress> element.
+        el = document.createElement('progress');
+        el.max = 1;
+        el.value = value !== undefined ? value : 0;  // 0..1
+        if (label) el.setAttribute('aria-label', label);
     } else {
         el = document.createElement('button');
         el.textContent = label || 'Action';
@@ -289,7 +359,7 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
     // Slider thumb needs explicit sizing for hit area. One shared, ref-counted
     // <style> for all sliders (U-09): released in destroy() when the last slider
     // goes -- head child count nets to zero across mount/destroy.
-    if (type === UIType.SLIDER) {
+    if (type === UIType.SLIDER || type === UIType.KNOB) {
         acquireSliderStyle();
         styleAcquired = true;
         el.classList.add('uifx-slider');
@@ -322,14 +392,32 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
     container.appendChild(wrapper);
     wrapperAppended = true;
 
+    // -- Optional aria-live announcer for PROGRESS (U4a). Opt-in via
+    //    { announce: true }: a visually-hidden polite region that setValue
+    //    updates at 10% steps. It lives in the wrapper, so wrapper.remove() in
+    //    destroy() takes it with everything else -- no separate teardown. --
+    let announceRegion = null;
+    if (type === UIType.PROGRESS && announce) {
+        announceRegion = document.createElement('span');
+        announceRegion.setAttribute('aria-live', 'polite');
+        Object.assign(announceRegion.style, {
+            position: 'absolute', width: '1px', height: '1px',
+            overflow: 'hidden', clipPath: 'inset(50%)',
+            whiteSpace: 'nowrap', border: '0', padding: '0', margin: '-1px',
+        });
+        wrapper.appendChild(announceRegion);
+    }
+    let _lastAnnouncePct = -1;  // last announced 10% step (cold: only setValue writes)
+
     // -- State (value/checked/disabled land here BEFORE frame 1) --
     const state = {
         hover: false,
         active: false,      // pointer is down
         focused: false,      // keyboard focus
         toggled: checked,   // coerced boolean; element + state AGREE
+        indeterminate: false,  // CHECKBOX only; set via setValue(null)
         disabled,           // recipes can render a disabled look
-        val: value !== undefined ? value : (type === UIType.SLIDER ? 0.5 : 0),  // 0-1
+        val: value !== undefined ? value : (type === UIType.SLIDER || type === UIType.KNOB ? 0.5 : 0),  // 0-1
         w, h, padding, dpr,
     };
 
@@ -339,6 +427,28 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
     // pointer event, then lazily filled once (see updatePointer).
     let rect = null;
 
+    // Apply a numeric value to a valued control (SLIDER/KNOB/PROGRESS): reflect
+    // it to the native element, update state, announce (PROGRESS), and fire
+    // onDrag exactly once when asked. A programmatic el.value write fires NO
+    // native 'input', so this explicit hook call is the only one -- no double
+    // fire. Cold path (setValue + knob drag), never a per-frame body.
+    function _applyVal(v, fireHook) {
+        state.val = v;
+        if (type === UIType.PROGRESS) {
+            el.value = v;  // 0..1, native max=1
+            if (announceRegion) {
+                const pct = Math.round(v * 10) * 10;
+                if (pct !== _lastAnnouncePct) {
+                    _lastAnnouncePct = pct;
+                    announceRegion.textContent = pct + '%';
+                }
+            }
+        } else {
+            el.value = String(v * 100);  // range 0..100
+        }
+        if (fireHook && recipe.onDrag) recipe.onDrag(v, pointer.vx, state);
+    }
+
     // -- Initialize recipe (already validated in phase 1: object, tick fn,
     //    only known hooks). ctx exists now, so init can run. --
     if (recipe.init) recipe.init(ctx, w, h, padding);
@@ -390,9 +500,12 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
     el.addEventListener('focus', () => { state.focused = true; }, { signal });
     el.addEventListener('blur', () => { state.focused = false; }, { signal });
 
-    // Toggle events
-    if (type === UIType.TOGGLE) {
+    // Toggle + checkbox events (both are a native <input type=checkbox>)
+    if (type === UIType.TOGGLE || type === UIType.CHECKBOX) {
         el.addEventListener('change', () => {
+            // A user interaction resolves any indeterminate state (native does
+            // this too); keep state.indeterminate in agreement.
+            state.indeterminate = false;
             state.toggled = el.checked;
             if (recipe.onToggle) recipe.onToggle(state.toggled, state);
         }, { signal });
@@ -404,14 +517,51 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
         }, { signal });
     }
 
-    // Slider events
-    if (type === UIType.SLIDER) {
+    // Slider + knob value events. A range input fires 'input' on native drag
+    // (slider) AND on arrow keys (both) -- one path for keyboard on either type.
+    if (type === UIType.SLIDER || type === UIType.KNOB) {
         el.addEventListener('input', () => {
             state.val = el.value / 100;
             if (recipe.onDrag) recipe.onDrag(state.val, pointer.vx, state);
         }, { signal });
     }
 
+    // KNOB pointer remap (U4a). A range input maps value to horizontal thumb
+    // position; a knob maps a rotational or vertical drag instead. Arrow keys
+    // stay native (the 'input' handler above); for pointer we drive the value
+    // ourselves and preventDefault the native jump-to-pointer, restoring focus
+    // by hand. All cold: pointer handlers, no per-frame work.
+    if (type === UIType.KNOB) {
+        let knobActive = false;
+        let knobStartVal = 0;
+        let knobStartY = 0;
+        el.addEventListener('pointerdown', (e) => {
+            knobActive = true;
+            knobStartVal = state.val;
+            knobStartY = e.clientY;
+            refreshRect();
+            el.focus();
+            e.preventDefault();  // suppress the range's native jump-to-pointer
+            if (el.setPointerCapture) el.setPointerCapture(e.pointerId);
+        }, { signal });
+        el.addEventListener('pointermove', (e) => {
+            if (!knobActive) return;
+            let v;
+            if (knobMode === 'vertical') {
+                v = knobStartVal + (knobStartY - e.clientY) / 150;  // 150px = full sweep
+            } else {
+                const cx = rect ? rect.left + rect.width / 2 : e.clientX;
+                const cy = rect ? rect.top + rect.height / 2 : e.clientY;
+                let a = Math.atan2(e.clientY - cy, e.clientX - cx);  // -PI..PI
+                a = (a + Math.PI * 2.5) % (Math.PI * 2);             // 0 at bottom, clockwise
+                v = a / (Math.PI * 2);
+            }
+            if (v < 0) v = 0; else if (v > 1) v = 1;
+            _applyVal(v, true);  // reflect + fire onDrag once
+        }, { signal });
+        el.addEventListener('pointerup', () => { knobActive = false; }, { signal });
+    }
+
     // -- DPR re-read on display change (cold, feature-detected). Absent
     //    matchMedia is a silent no-op: the canvas stays at mount DPR (fail
     //    closed, never throw). Listener bound to signal for teardown. --
@@ -470,6 +620,50 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
         /** Current state (read-only reference). */
         state,
 
+        /**
+         * Programmatically set a valued control (SLIDER/KNOB/PROGRESS) to v in
+         * [0,1]: updates the native element, state.val, any PROGRESS announcer,
+         * and fires onDrag exactly once (a programmatic write emits no native
+         * event, so there is no second fire). For a CHECKBOX, setValue(null)
+         * sets the indeterminate state. Fail closed on wrong type / bad value.
+         */
+        setValue(v) {
+            if (destroyed) return;
+            if (type === UIType.CHECKBOX) {
+                if (v === null) {
+                    el.indeterminate = true;
+                    state.indeterminate = true;
+                    return;
+                }
+                throw new Error('setValue: a checkbox takes setChecked(bool), or setValue(null) for indeterminate');
+            }
+            if (type !== UIType.SLIDER && type !== UIType.KNOB && type !== UIType.PROGRESS) {
+                throw new Error('setValue: only SLIDER, KNOB, and PROGRESS carry a numeric value');
+            }
+            if (typeof v !== 'number' || !Number.isFinite(v) || v < 0 || v > 1) {
+                throw new Error('setValue: v must be a number in [0,1]');
+            }
+            _applyVal(v, true);
+        },
+
+        /**
+         * Programmatically set a TOGGLE/CHECKBOX checked state: updates the
+         * native element, state.toggled, clears indeterminate, and fires
+         * onToggle exactly once. Fail closed on the wrong type.
+         */
+        setChecked(b) {
+            if (destroyed) return;
+            if (type !== UIType.TOGGLE && type !== UIType.CHECKBOX) {
+                throw new Error('setChecked: only TOGGLE and CHECKBOX carry a checked state');
+            }
+            const nb = !!b;
+            el.indeterminate = false;
+            el.checked = nb;
+            state.indeterminate = false;
+            state.toggled = nb;
+            if (recipe.onToggle) recipe.onToggle(nb, state);
+        },
+
         /** Destroy everything. Idempotent. */
         destroy() {
             if (destroyed) return;
@@ -478,7 +672,7 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
             removeTick();
             if (recipe.destroy) recipe.destroy();
             releaseTicker();
-            if (type === UIType.SLIDER) releaseSliderStyle();
+            if (type === UIType.SLIDER || type === UIType.KNOB) releaseSliderStyle();
             wrapper.remove();
         },
     };