@zakkster/lite-ui-fx 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,58 @@ 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

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/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;
@@ -72,6 +80,10 @@ export interface MountOptions {
     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 {
@@ -80,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.4.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', 'seed', 'colors', 'theme', 'text', 'font'];
+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,8 @@ 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
@@ -233,6 +243,26 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
         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') {
         throw new Error('mountUIFX: recipeFactory must be a function');
@@ -279,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';
@@ -316,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');
@@ -349,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,
     };
 
@@ -366,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);
@@ -417,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 });
@@ -431,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. --
@@ -497,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;
@@ -505,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();
         },
     };

package/UIFXRecipes.d.ts

@@ -1,7 +1,7 @@
 import type { UIFXRecipe, UIFXInstance, MountOptions } from './UIFXController';
 
 // ===========================================================
-//  RECIPE OPTIONS + FACTORIES (all 50)
+//  RECIPE OPTIONS + FACTORIES (all 53)
 // ===========================================================
 
 /**
@@ -72,6 +72,9 @@ export declare function HelixLoader(options?: RecipeOptions): UIFXRecipe;
 // -- Vol.2: Checkboxes --
 export declare function RippleCheck(options?: RecipeOptions): UIFXRecipe;
 export declare function MorphCheck(options?: RecipeOptions): UIFXRecipe;
+// -- U4a: CHECKBOX recipes (honour st.indeterminate) --
+export declare function TickDraw(options?: RecipeOptions): UIFXRecipe;
+export declare function IndeterminateScan(options?: RecipeOptions): UIFXRecipe;
 
 // -- Vol.2: Counters --
 export declare function FlameCounter(options?: RecipeOptions): UIFXRecipe;
@@ -88,6 +91,8 @@ export declare function CompassKnob(options?: RecipeOptions): UIFXRecipe;
 export declare function RingProgress(options?: RecipeOptions): UIFXRecipe;
 export declare function BatteryGauge(options?: RecipeOptions): UIFXRecipe;
 export declare function SignalMeter(options?: RecipeOptions): UIFXRecipe;
+// -- U4a: PROGRESS recipe --
+export declare function LiquidFill(options?: RecipeOptions): UIFXRecipe;
 
 // -- Vol.3: Controls --
 export declare function PillTabs(options?: RecipeOptions): UIFXRecipe;
@@ -177,11 +182,18 @@ export declare const UIFXRecipes3: {
     PullRefresh: typeof PullRefresh;
 };
 
+/** U4a additions -- new native element types (kept out of the Vol.1-3 snapshots). */
+export declare const UIFXRecipes4: {
+    TickDraw: typeof TickDraw;
+    IndeterminateScan: typeof IndeterminateScan;
+    LiquidFill: typeof LiquidFill;
+};
+
 // ===========================================================
 //  RECIPE REGISTRY
 // ===========================================================
 
-export type RecipeType = 'toggle' | 'button' | 'slider';
+export type RecipeType = 'toggle' | 'button' | 'slider' | 'checkbox' | 'progress' | 'knob';
 
 export type RecipeFactory = (options?: Record<string, unknown>) => UIFXRecipe;
 
@@ -221,7 +233,7 @@ export declare function mountRecipe(
 ): UIFXInstance;
 
 // ===========================================================
-//  DEFAULT EXPORT -- combined all-50 namespace
+//  DEFAULT EXPORT -- combined all-53 namespace
 // ===========================================================
 
 declare const UIFXAllRecipes: {
@@ -252,6 +264,8 @@ declare const UIFXAllRecipes: {
     HelixLoader: typeof HelixLoader;
     RippleCheck: typeof RippleCheck;
     MorphCheck: typeof MorphCheck;
+    TickDraw: typeof TickDraw;
+    IndeterminateScan: typeof IndeterminateScan;
     FlameCounter: typeof FlameCounter;
     GlitchCounter: typeof GlitchCounter;
     BubbleRating: typeof BubbleRating;
@@ -260,6 +274,7 @@ declare const UIFXAllRecipes: {
     RingProgress: typeof RingProgress;
     BatteryGauge: typeof BatteryGauge;
     SignalMeter: typeof SignalMeter;
+    LiquidFill: typeof LiquidFill;
     PillTabs: typeof PillTabs;
     Stepper: typeof Stepper;
     RadioOrbit: typeof RadioOrbit;

package/UIFXRecipes.js

@@ -1,9 +1,9 @@
 /**
- * @zakkster/lite-ui-fx -- Recipe Collection (all 50)
+ * @zakkster/lite-ui-fx -- Recipe Collection (all 53)
  *
  * The three recipe volumes consolidated into one shipped, typed, versioned
- * module, exposed as the ./recipes subpath export. See
- * decisions/0001-recipes-position.md.
+ * module, exposed as the ./recipes subpath export, plus the U4a additions for
+ * the new native element types. See decisions/0001-recipes-position.md.
  *
  *   Vol.1 (10): SwarmToggle, LiquidToggle, NeonPulseToggle, MagneticButton,
  *               ShatterButton, ConfettiButton, GlitchButton, SparkSlider,
@@ -18,6 +18,7 @@
  *               HeatMap, DayNightToggle, ReactionPicker, NotificationBell,
  *               TypewriterField, SoundWaveBtn, UploadProgress, ScratchReveal,
  *               TimerCountdown, PullRefresh
+ *   U4a (3):    TickDraw, IndeterminateScan (CHECKBOX), LiquidFill (PROGRESS)
  *
  * Registry: RECIPES (null-prototype), RECIPE_META (live), RECIPE_NAMES,
  * registerRecipe(id, factory, meta?), mountRecipe(container, id, options?).
@@ -1588,6 +1589,84 @@ export function MorphCheck(o = {}) {
     };
 }
 
+/** Tick Draw (U4a CHECKBOX) -- the checkmark strokes itself on; a centred dash
+ *  when indeterminate; empty when off. Reads st.toggled + st.indeterminate. */
+export function TickDraw(o = {}) {
+    const P = resolveTheme(o, { accent: '#34d399', surface: '#0a0a12', dim2: '#8888aa' });
+    const boxOff = 'rgba(255,255,255,.06)';
+    const FONT = pickFont(o, "500 9px 'JetBrains Mono',monospace");
+    let drawT = 0;   // 0..1 stroke progress of the check
+    return {
+        tick(ctx, dt, now, st) {
+            // Indeterminate suppresses the check; a full check draws only when on.
+            drawT = lerp(drawT, st.indeterminate ? 0 : (st.toggled ? 1 : 0), dt * 12);
+            const sz = Math.min(st.w, st.h), cx = sz / 2, cy = sz / 2, r = 6;
+
+            ctx.fillStyle = (st.toggled || st.indeterminate) ? P.accent : boxOff;
+            roundRect(ctx, 0, 0, sz, sz, r); ctx.fill();
+
+            ctx.strokeStyle = P.surface; ctx.lineWidth = 3; ctx.lineCap = 'round';
+            if (st.indeterminate) {
+                // Standard indeterminate glyph: one centred dash.
+                ctx.beginPath(); ctx.moveTo(sz * 0.28, cy); ctx.lineTo(sz * 0.72, cy); ctx.stroke();
+            } else if (drawT > 0.01) {
+                const p1 = clamp(drawT * 2, 0, 1), p2 = clamp(drawT * 2 - 1, 0, 1);
+                ctx.beginPath();
+                ctx.moveTo(cx - 7, cy);
+                ctx.lineTo(cx - 7 + 7 * p1, cy + 7 * p1);
+                if (p2 > 0) ctx.lineTo(cx + 14 * p2, cy + 7 - 14 * p2);
+                ctx.stroke();
+            }
+            ctx.lineCap = 'butt';
+
+            label(ctx, st.indeterminate ? '\u2212' : (st.toggled ? '\u2713' : '\u25cb'),
+                cx, sz + 12, (st.toggled || st.indeterminate) ? P.accent : P.dim2, FONT);
+            if (st.focused) focusRing(ctx, sz, sz, r);
+        },
+    };
+}
+
+/** Indeterminate Scan (U4a CHECKBOX) -- sweeps a scan line while indeterminate,
+ *  settles to a stroked check when toggled, empty when off. */
+export function IndeterminateScan(o = {}) {
+    const P = resolveTheme(o, { accent: '#60a5fa', surface: '#0a0a12', dim2: '#8888aa' });
+    const FONT = pickFont(o, "500 9px 'JetBrains Mono',monospace");
+    let scan = 0;    // 0..1 sweep phase
+    let checkT = 0;  // 0..1 check reveal
+    return {
+        tick(ctx, dt, now, st) {
+            checkT = lerp(checkT, (!st.indeterminate && st.toggled) ? 1 : 0, dt * 12);
+            const sz = Math.min(st.w, st.h), cx = sz / 2, cy = sz / 2, r = 6;
+
+            ctx.fillStyle = (st.toggled && !st.indeterminate) ? P.accent : 'rgba(255,255,255,.06)';
+            roundRect(ctx, 0, 0, sz, sz, r); ctx.fill();
+
+            if (st.indeterminate) {
+                // Scan line sweeping down, fading at the sweep ends (globalAlpha,
+                // not a per-frame colour string).
+                scan += dt * 1.6; if (scan > 1) scan -= 1;
+                const y = 4 + scan * (sz - 8);
+                ctx.strokeStyle = P.accent; ctx.lineWidth = 2; ctx.lineCap = 'round';
+                ctx.globalAlpha = Math.sin(scan * Math.PI);
+                ctx.beginPath(); ctx.moveTo(4, y); ctx.lineTo(sz - 4, y); ctx.stroke();
+                ctx.globalAlpha = 1; ctx.lineCap = 'butt';
+            } else if (checkT > 0.01) {
+                const p1 = clamp(checkT * 2, 0, 1), p2 = clamp(checkT * 2 - 1, 0, 1);
+                ctx.strokeStyle = P.surface; ctx.lineWidth = 3; ctx.lineCap = 'round';
+                ctx.beginPath();
+                ctx.moveTo(cx - 7, cy);
+                ctx.lineTo(cx - 7 + 7 * p1, cy + 7 * p1);
+                if (p2 > 0) ctx.lineTo(cx + 14 * p2, cy + 7 - 14 * p2);
+                ctx.stroke(); ctx.lineCap = 'butt';
+            }
+
+            label(ctx, st.indeterminate ? '\u2212' : (st.toggled ? '\u2713' : '\u25cb'),
+                cx, sz + 12, (st.toggled || st.indeterminate) ? P.accent : P.dim2, FONT);
+            if (st.focused) focusRing(ctx, sz, sz, r);
+        },
+    };
+}
+
 
 // ===========================================================
 //  COUNTERS (use slider val as input)
@@ -2037,6 +2116,55 @@ export function SignalMeter(o = {}) {
 //  CONTROLS
 // ===========================================================
 
+/** Liquid Fill (U4a PROGRESS) -- a container that fills with a waving liquid to
+ *  the progress value, with a percentage readout. Non-interactive. */
+export function LiquidFill(o = {}) {
+    const P = resolveTheme(o, { accent: '#22d3ee', accent2: '#0ea5e9', dim: '#e2e2f0' });
+    const FONT = pickFont(o, "700 14px 'JetBrains Mono',monospace");
+    let displayVal = 0, phase = 0, liquid = null;
+    return {
+        init(c, w, h) {
+            // Vertical liquid gradient, built ONCE (cold): crest -> base.
+            const g = c.createLinearGradient(0, 0, 0, h);
+            g.addColorStop(0, P.accent);
+            g.addColorStop(1, P.accent2);
+            liquid = g;
+        },
+        tick(c, dt, now, st) {
+            displayVal = lerp(displayVal, st.val, dt * 5);
+            phase += dt * 3;
+            const w = st.w, h = st.h, r = Math.min(12, h / 2);
+
+            // Container outline
+            c.strokeStyle = 'rgba(255,255,255,.14)'; c.lineWidth = 2;
+            roundRect(c, 1, 1, w - 2, h - 2, r); c.stroke();
+
+            // Liquid body, clipped to the container, with a sine surface. Const
+            // gradient fill + fixed-step sampling -> zero per-frame allocation.
+            c.save();
+            roundRect(c, 1, 1, w - 2, h - 2, r); c.clip();
+            const surface = h - displayVal * h;
+            const amp = displayVal > 0.01 && displayVal < 0.99 ? 3 : 0;
+            c.fillStyle = liquid || P.accent;
+            c.beginPath();
+            c.moveTo(0, h);
+            c.lineTo(0, surface);
+            for (let x = 0; x <= w; x += 6) {
+                c.lineTo(x, surface + Math.sin(x * 0.15 + phase) * amp);
+            }
+            c.lineTo(w, h);
+            c.closePath();
+            c.fill();
+            c.restore();
+
+            // Percentage readout (PCT LUT -- no per-frame string build)
+            c.fillStyle = P.dim; c.font = FONT; c.textAlign = 'center'; c.textBaseline = 'middle';
+            c.fillText(PCT[Math.round(displayVal * 100)], w / 2, h / 2);
+            if (st.focused) fr(c, w, h, r);
+        },
+    };
+}
+
 /** 6. Pill Tabs -- 3 segmented tabs with sliding indicator. */
 export function PillTabs(o = {}) {
     const P = resolveTheme(o, { accent: '#c4b5fd', accent2: '#a78bfa', dim: '#9999b8' });
@@ -2726,9 +2854,17 @@ export const UIFXRecipes3 = {
     ScratchReveal, TimerCountdown, PullRefresh,
 };
 
+// U4a additions -- new native element types (CHECKBOX, PROGRESS). Kept out of the
+// Vol.1-3 historical snapshots above so those stay accurate; all recipes remain
+// reachable via RECIPES / RECIPE_META and their named exports regardless.
+export const UIFXRecipes4 = {
+    TickDraw, IndeterminateScan,
+    LiquidFill,
+};
+
 
 // ===========================================================
-//  DEFAULT EXPORT -- combined all-50 namespace
+//  DEFAULT EXPORT -- combined all-53 namespace
 // ===========================================================
 
 export default {
@@ -2759,6 +2895,8 @@ export default {
     HelixLoader,
     RippleCheck,
     MorphCheck,
+    TickDraw,
+    IndeterminateScan,
     FlameCounter,
     GlitchCounter,
     BubbleRating,
@@ -2767,6 +2905,7 @@ export default {
     RingProgress,
     BatteryGauge,
     SignalMeter,
+    LiquidFill,
     PillTabs,
     Stepper,
     RadioOrbit,
@@ -2822,6 +2961,8 @@ export const RECIPES = Object.assign(Object.create(null), {
     helixLoader: HelixLoader,
     rippleCheck: RippleCheck,
     morphCheck: MorphCheck,
+    tickDraw: TickDraw,
+    indeterminateScan: IndeterminateScan,
     flameCounter: FlameCounter,
     glitchCounter: GlitchCounter,
     bubbleRating: BubbleRating,
@@ -2830,6 +2971,7 @@ export const RECIPES = Object.assign(Object.create(null), {
     ringProgress: RingProgress,
     batteryGauge: BatteryGauge,
     signalMeter: SignalMeter,
+    liquidFill: LiquidFill,
     pillTabs: PillTabs,
     stepper: Stepper,
     radioOrbit: RadioOrbit,
@@ -2883,16 +3025,19 @@ export const RECIPE_META = [
     { id: 'gravitySlider', name: 'Gravity Slider', type: 'slider', family: 'Sliders', themeable: true, motionSafe: false },
     { id: 'orbitLoader', name: 'Orbit Loader', type: 'toggle', family: 'Loaders', themeable: true, motionSafe: false },
     { id: 'helixLoader', name: 'Helix Loader', type: 'toggle', family: 'Loaders', themeable: true, motionSafe: false },
-    { id: 'rippleCheck', name: 'Ripple Check', type: 'toggle', family: 'Checkboxes', themeable: true, motionSafe: false },
-    { id: 'morphCheck', name: 'Morph Check', type: 'toggle', family: 'Checkboxes', themeable: true, motionSafe: false },
+    { id: 'rippleCheck', name: 'Ripple Check', type: 'checkbox', family: 'Checkboxes', themeable: true, motionSafe: false },
+    { id: 'morphCheck', name: 'Morph Check', type: 'checkbox', family: 'Checkboxes', themeable: true, motionSafe: false },
+    { id: 'tickDraw', name: 'Tick Draw', type: 'checkbox', family: 'Checkboxes', themeable: true, motionSafe: false },
+    { id: 'indeterminateScan', name: 'Indeterminate Scan', type: 'checkbox', family: 'Checkboxes', themeable: true, motionSafe: false },
     { id: 'flameCounter', name: 'Flame Counter', type: 'slider', family: 'Counters', themeable: true, motionSafe: false },
     { id: 'glitchCounter', name: 'Glitch Counter', type: 'slider', family: 'Counters', themeable: true, motionSafe: false },
     { id: 'bubbleRating', name: 'Bubble Rating', type: 'slider', family: 'Rating', themeable: true, motionSafe: false },
-    { id: 'volumeKnob', name: 'Volume Knob', type: 'slider', family: 'Knobs', themeable: true, motionSafe: false },
-    { id: 'compassKnob', name: 'Compass Knob', type: 'slider', family: 'Knobs', themeable: true, motionSafe: false },
-    { id: 'ringProgress', name: 'Ring Progress', type: 'slider', family: 'Progress', themeable: true, motionSafe: false },
-    { id: 'batteryGauge', name: 'Battery Gauge', type: 'slider', family: 'Progress', themeable: true, motionSafe: false },
-    { id: 'signalMeter', name: 'Signal Meter', type: 'slider', family: 'Progress', themeable: true, motionSafe: false },
+    { id: 'volumeKnob', name: 'Volume Knob', type: 'knob', family: 'Knobs', themeable: true, motionSafe: false },
+    { id: 'compassKnob', name: 'Compass Knob', type: 'knob', family: 'Knobs', themeable: true, motionSafe: false },
+    { id: 'ringProgress', name: 'Ring Progress', type: 'progress', family: 'Progress', themeable: true, motionSafe: false },
+    { id: 'batteryGauge', name: 'Battery Gauge', type: 'progress', family: 'Progress', themeable: true, motionSafe: false },
+    { id: 'signalMeter', name: 'Signal Meter', type: 'progress', family: 'Progress', themeable: true, motionSafe: false },
+    { id: 'liquidFill', name: 'Liquid Fill', type: 'progress', family: 'Progress', themeable: true, motionSafe: false },
     { 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 },
@@ -2904,7 +3049,7 @@ export const RECIPE_META = [
     { id: 'notificationBell', name: 'Notification Bell', type: 'button', family: 'Mood', themeable: true, motionSafe: false },
     { id: 'typewriterField', name: 'Typewriter Field', type: 'toggle', family: 'Feedback', themeable: true, motionSafe: false },
     { id: 'soundWaveBtn', name: 'Sound Wave Btn', type: 'button', family: 'Feedback', themeable: true, motionSafe: false },
-    { id: 'uploadProgress', name: 'Upload Progress', type: 'slider', 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 },
@@ -2913,6 +3058,11 @@ export const RECIPE_META = [
 /** Names of every built-in recipe (the keys of RECIPES at load time). */
 export const RECIPE_NAMES = Object.freeze(Object.keys(RECIPES));
 
+// The valid recipe/mount types, taken from the controller's UIType so the
+// registry's fail-closed check and the controller's mount guard are one source
+// of truth (they cannot drift as U4 adds types). Built once at load (cold).
+const VALID_META_TYPES = new Set(Object.values(UIType));
+
 /**
  * Register a custom recipe, or override a built-in. Instantly usable via
  * RECIPES[id] and reflected in RECIPE_META so existing pickers keep working.
@@ -2937,9 +3087,11 @@ export function registerRecipe(id, factory, meta) {
     const type = (meta && meta.type) || (prev && prev.type) || undefined;
     // A recipe's type selects its native element; a typeless recipe cannot be
     // mounted. Reject it at registration (fail closed) -- checked BEFORE any
-    // mutation, so a rejected call leaves RECIPES/RECIPE_META untouched.
-    if (type !== 'toggle' && type !== 'button' && type !== 'slider') {
-        throw new TypeError('registerRecipe: type must be "toggle", "button", or "slider"');
+    // mutation, so a rejected call leaves RECIPES/RECIPE_META untouched. The
+    // valid set is UIType (VALID_META_TYPES), so registry + controller never
+    // disagree about what a type is.
+    if (!VALID_META_TYPES.has(type)) {
+        throw new TypeError('registerRecipe: type must be one of "button", "toggle", "slider", "checkbox", "progress", "knob"');
     }
 
     RECIPES[id] = factory;

package/llms.txt

@@ -1,7 +1,7 @@
 # @zakkster/lite-ui-fx
-> Canvas-hijacked UI components with pluggable recipe system. 50 built-in recipes.
+> Canvas-hijacked UI components with pluggable recipe system. 53 built-in recipes.
 
-VERSION 1.4.0
+VERSION 1.5.0
 
 ## Install
 npm i @zakkster/lite-ui-fx
@@ -14,7 +14,7 @@ Recipe = { tick(), init?(), onHover?(), onClick?(), onToggle?(), onDrag?(), dest
 ## Import -- Controller
 import { mountUIFX, UIType } from '@zakkster/lite-ui-fx';
 
-## Import -- Recipes (one ./recipes subpath, 50 total, tree-shakeable)
+## Import -- Recipes (one ./recipes subpath, 53 total, tree-shakeable)
 import { SwarmToggle, MagneticButton, SparkSlider } from '@zakkster/lite-ui-fx/recipes';
 import { PendulumToggle, HeartbeatButton, AuroraSlider } from '@zakkster/lite-ui-fx/recipes';
 import { VolumeKnob, WaterLevel, TimerCountdown } from '@zakkster/lite-ui-fx/recipes';
@@ -26,7 +26,9 @@ import { RECIPES, RECIPE_META, RECIPE_NAMES, registerRecipe, mountRecipe } from
 
 ## Mount
 const instance = mountUIFX(container, UIType.TOGGLE, SwarmToggle, { label: 'Sound' });
-instance.destroy(); // cleanup
+instance.setValue(v);   // SLIDER/KNOB/PROGRESS: v in 0..1 (fires onDrag once); CHECKBOX: setValue(null) = indeterminate
+instance.setChecked(b); // TOGGLE/CHECKBOX: set checked (fires onToggle once)
+instance.destroy();     // cleanup
 
 ## Options (4th arg; unknown option or recipe-hook keys throw a did-you-mean -- fail closed)
 width, height, padding=40, label   // geometry + accessible label
@@ -38,16 +40,21 @@ colors    // string[] palette override; wins over theme (array-palette recipes:
 theme     // { light, mid, dark } -> accent/dim/surface; partial or wrong-shape throws
 text      // visible canvas label; falls back to label, then the recipe default (label-in-name)
 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
 
 ## Element Types
-UIType.TOGGLE -> <input type="checkbox" role="switch"> -> state.toggled, onToggle(checked)
-UIType.BUTTON -> <button> -> state.active, onClick(x, y, state)
-UIType.SLIDER -> <input type="range"> -> state.val (0-1), onDrag(val, velocity)
+UIType.TOGGLE   -> <input type="checkbox" role="switch"> -> state.toggled, onToggle(checked)
+UIType.BUTTON   -> <button> -> state.active, onClick(x, y, state)
+UIType.SLIDER   -> <input type="range"> -> state.val (0-1), onDrag(val, velocity)
+UIType.CHECKBOX -> <input type="checkbox"> (no role=switch) -> state.toggled + state.indeterminate, onToggle(checked)
+UIType.PROGRESS -> <progress> (non-interactive) -> state.val, driven by instance.setValue
+UIType.KNOB     -> <input type="range"> -> state.val, arrows native + knobMode pointer map, onDrag(val, velocity)
 
 ## State Object (provided to tick every frame)
-{ hover, active, focused, toggled, disabled, val, w, h, padding, dpr }
+{ hover, active, focused, toggled, indeterminate, disabled, val, w, h, padding, dpr }
 
-## 50 Built-in Recipes
+## 53 Built-in Recipes
 
 ### Vol. 1 -- 10 recipes
 Toggles: SwarmToggle, LiquidToggle, NeonPulseToggle
@@ -72,6 +79,10 @@ Mood: DayNightToggle, ReactionPicker, NotificationBell
 Feedback: TypewriterField, SoundWaveBtn, UploadProgress
 Fun: ScratchReveal, TimerCountdown, PullRefresh
 
+### U4a -- 3 recipes (new element types)
+Checkboxes (UIType.CHECKBOX): TickDraw, IndeterminateScan
+Progress (UIType.PROGRESS): LiquidFill
+
 ## Writing Custom Recipes
 See UIFX-RECIPE-GUIDE.md (included in package).
 
@@ -87,8 +98,10 @@ See UIFX-RECIPE-GUIDE.md (included in package).
 - Zero-GC in all built-in recipes: const colors + globalAlpha, precomputed
   color/label LUTs, fixed preallocated particle pools, gradients built in init.
   Gated per recipe by the t3-frame-alloc torture tier (default AND themed mount).
-- Themeable: all 50 recipes honour { colors, theme:{light,mid,dark}, text, font },
+- Themeable: all 53 recipes honour { colors, theme:{light,mid,dark}, text, font },
   resolved once in init (zero per-frame alloc). RECIPE_META.themeable is true for
-  all 50; motionSafe stays false (reduced motion is a later pass). A bare mount is
+  all 53; 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).
+- U4a element types: CHECKBOX (indeterminate), PROGRESS (setValue-driven, aria-live
+  opt-in), KNOB (knobMode pointer map); setValue/setChecked sync native+state+hook once.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-ui-fx",
-  "version": "1.4.0",
+  "version": "1.5.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",