@zakkster/lite-ui-fx 1.0.5 → 1.1.0

package/CHANGELOG.md

@@ -5,7 +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.0.5] -- unreleased
+## [1.1.0] -- unreleased
+
+Controller correctness: the two S1 defects (U-01, U-02) and three
+controller-level S3s (U-09, U-10, U-11). No visual change at default mounts.
+
+### Fixed
+
+- U-01 (keyboard): a toggle activates on one Space press with exactly one
+  `onToggle`, and the native checkbox is the sole source of truth. The manual
+  keydown checked-flip -- which fired a second `onToggle` -- is removed; Enter
+  is bridged to the same native activation via `el.click()`.
+- U-02 (loop survival): one malformed recipe can no longer freeze the page.
+  Invalid recipes are rejected at mount (fail closed -- every side effect is
+  unwound, so no orphan DOM and no leaked refcount); a `tick()` that throws
+  quarantines only that component (one `console.error`, its canvas cleared)
+  while the shared ticker and every other component keep running.
+- U-09 (style leak): the slider-thumb `<style>` is one shared, ref-counted
+  node -- injected on first slider mount, removed when the last slider
+  unmounts; `document.head` child count nets to zero.
+- U-10 (fail-open options): unknown option keys and unknown recipe-hook keys
+  are now errors with a did-you-mean hint; `value` must be a number in [0,1].
+- U-11 (forced reflow): the bounding rect is cached on pointerenter and
+  refreshed on scroll/resize (passive listeners); `pointermove` does zero
+  layout reads.
+
+### Added
+
+- Mount options `value` (slider initial, 0..1), `checked` (toggle initial),
+  and `disabled` -- each lands in the native element and `state` before the
+  first frame. New `state.disabled` for recipes to render a disabled look.
+- DPR re-read: the canvas re-scales on a display-density change
+  (`matchMedia`, feature-detected; a silent no-op where unavailable).
+- Torture tiers t2 (the accessibility contract) and t5 (100-component scale
+  plus the U-02 quarantine regression); two t9 controls (double-toggle,
+  validation-bypass).
+
+### Changed
+
+- Mount validates every input before any side effect (fail closed):
+  container, options, factory, and recipe shape are checked before the DOM,
+  the shared style/ticker refcounts, or the render loop are touched.
+
+## [1.0.5] -- 2026-09-06
 
 Truth pass, law pass, and the torture skeleton. No runtime behaviour
 changes: this release makes the package honest, lawful, and provable.

package/README.md

@@ -150,6 +150,9 @@ import { VolumeKnob, WaterLevel, TimerCountdown } from './recipes/UIFXRecipes3.j
 | `options.height` | `number` | Element height |
 | `options.padding` | `number` | Canvas overflow (default: 40px) |
 | `options.label` | `string` | Accessible label (aria-label) |
+| `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` |
 
 Returns `{ el, canvas, wrapper, state, destroy() }`.
 
@@ -169,6 +172,7 @@ Returns `{ el, canvas, wrapper, state, destroy() }`.
     active: boolean;     // Pointer pressed
     focused: boolean;    // Keyboard focus
     toggled: boolean;    // Checkbox state
+    disabled: boolean;   // Disabled via options.disabled
     val: number;         // Slider value (0-1)
     w: number;           // Element width
     h: number;           // Element height

package/UIFXController.d.ts

@@ -13,6 +13,7 @@ export interface UIFXState {
     active: boolean;
     focused: boolean;
     toggled: boolean;
+    disabled: boolean;
     val: number;
     w: number;
     h: number;
@@ -52,6 +53,12 @@ export interface MountOptions {
     height?: number;
     padding?: number;
     label?: string;
+    /** Slider initial value, 0..1 (default 0.5). Out-of-range or non-number throws. */
+    value?: number;
+    /** Toggle initial checked state (default false). */
+    checked?: boolean;
+    /** Disables the native element and sets state.disabled for recipes. */
+    disabled?: boolean;
 }
 
 export interface UIFXInstance {

package/UIFXController.js

@@ -22,7 +22,7 @@ import { Ticker } from '@zakkster/lite-ticker';
 
 // Three-place version sync: this constant, package.json "version", and the
 // VERSION line in llms.txt must always match. /release keeps them locked.
-export const VERSION = '1.0.5';
+export const VERSION = '1.1.0';
 
 // ---------------------------------------------------------
 //  SHARED TICKER (ref-counted, one RAF for all UI components)
@@ -50,6 +50,90 @@ function releaseTicker() {
 }
 
 
+// ---------------------------------------------------------
+//  SHARED SLIDER STYLE (ref-counted, one <style> for all sliders)
+// ---------------------------------------------------------
+
+let _sliderStyle = null;
+let _sliderRefs = 0;
+
+function acquireSliderStyle() {
+    if (!_sliderStyle) {
+        _sliderStyle = document.createElement('style');
+        _sliderStyle.textContent = `
+            .uifx-slider::-webkit-slider-thumb { -webkit-appearance:none; width:24px; height:24px; cursor:grab; }
+            .uifx-slider::-moz-range-thumb { width:24px; height:24px; cursor:grab; border:none; background:transparent; }
+        `;
+        document.head.appendChild(_sliderStyle);
+    }
+    _sliderRefs++;
+}
+
+function releaseSliderStyle() {
+    _sliderRefs--;
+    if (_sliderRefs <= 0 && _sliderStyle) {
+        _sliderStyle.remove();
+        _sliderStyle = null;
+        _sliderRefs = 0;
+    }
+}
+
+
+// ---------------------------------------------------------
+//  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'];
+
+// Levenshtein edit distance. Cold: only reached on the error path.
+function _editDistance(a, b) {
+    const al = a.length;
+    const bl = b.length;
+    if (al === 0) return bl;
+    if (bl === 0) return al;
+    let prev = new Array(bl + 1);
+    for (let j = 0; j <= bl; j++) prev[j] = j;
+    for (let i = 1; i <= al; i++) {
+        const cur = new Array(bl + 1);
+        cur[0] = i;
+        for (let j = 1; j <= bl; j++) {
+            const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+            let m = prev[j] + 1;
+            const del = cur[j - 1] + 1;
+            if (del < m) m = del;
+            const sub = prev[j - 1] + cost;
+            if (sub < m) m = sub;
+            cur[j] = m;
+        }
+        prev = cur;
+    }
+    return prev[bl];
+}
+
+// Nearest known key within edit distance <=2, else one sharing a >=2-char
+// prefix, else null. Cold path.
+function _suggest(name, known) {
+    let best = null;
+    let bestD = Infinity;
+    for (let i = 0; i < known.length; i++) {
+        const d = _editDistance(name, known[i]);
+        if (d < bestD) { bestD = d; best = known[i]; }
+    }
+    if (bestD <= 2) return best;
+    const head = name.length >= 2 ? name.slice(0, 2) : name;
+    for (let i = 0; i < known.length; i++) {
+        if (known[i].indexOf(head) === 0) return known[i];
+    }
+    return null;
+}
+
+function _didYouMean(prefix, name, known) {
+    const s = _suggest(name, known);
+    return prefix + ' "' + name + '"' + (s ? '. Did you mean "' + s + '"?' : '');
+}
+
+
 // ---------------------------------------------------------
 //  ELEMENT TYPES
 // ---------------------------------------------------------
@@ -79,16 +163,88 @@ export const UIType = Object.freeze({
  * @param {string}      [options.label]   Accessible label for the element
  * @returns {{ el: HTMLElement, destroy: Function }}
  */
-export function mountUIFX(container, type, recipeFactory, {
-    width,
-    height,
-    padding = 40,
-    label = '',
-} = {}) {
+export function mountUIFX(container, type, recipeFactory, options = {}) {
+    // =====================================================================
+    //  PHASE 1 -- VALIDATION ONLY. No side effect runs until every check
+    //  below has passed: no createElement, no appendChild, no
+    //  acquireSliderStyle, no ticker acquire, no recipe.init. A rejected
+    //  mount must leave the DOM and every shared refcount exactly as it
+    //  found them (fail closed -- BLOCKER 1).
+    // =====================================================================
+
+    // 1. container
+    if (!container || typeof container.appendChild !== 'function') {
+        throw new Error('mountUIFX: container must be a DOM element');
+    }
+
+    // 2. options: unknown keys -> did-you-mean; value/checked/disabled
+    //    validated and coerced HERE, before any element exists.
+    for (const k in options) {
+        if (!Object.prototype.hasOwnProperty.call(options, k)) continue;
+        if (KNOWN_OPTIONS.indexOf(k) === -1) {
+            throw new Error(_didYouMean('mountUIFX: unknown option', k, KNOWN_OPTIONS));
+        }
+    }
+    const value = options.value;
+    if (value !== undefined &&
+        (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1)) {
+        // null is not zero: an out-of-range or non-numeric value is an error,
+        // never a silent coercion.
+        throw new Error('mountUIFX: option "value" must be a number in [0,1]');
+    }
+    const checked = options.checked === undefined ? false : !!options.checked;
+    const disabled = options.disabled === undefined ? false : !!options.disabled;
+    const width = options.width;
+    const height = options.height;
+    const padding = options.padding === undefined ? 40 : options.padding;
+    const label = options.label === undefined ? '' : options.label;
+
+    // 3. recipeFactory
+    if (typeof recipeFactory !== 'function') {
+        throw new Error('mountUIFX: recipeFactory must be a function');
+    }
+
+    // 4. recipe object + hooks. Created now so a bad recipe throws BEFORE any
+    //    DOM/refcount side effect; .init is deferred to phase 2 (needs ctx).
+    const recipe = recipeFactory();
+    if (!recipe || typeof recipe !== 'object') {
+        throw new Error('mountUIFX: recipe must be an object');
+    }
+    if (typeof recipe.tick !== 'function') {
+        throw new Error('mountUIFX: recipe.tick must be a function');
+    }
+    for (const k in recipe) {
+        if (!Object.prototype.hasOwnProperty.call(recipe, k)) continue;
+        if (typeof recipe[k] === 'function' && KNOWN_HOOKS.indexOf(k) === -1) {
+            throw new Error(_didYouMean('mountUIFX: unknown recipe hook', k, KNOWN_HOOKS));
+        }
+    }
+
+    // =====================================================================
+    //  PHASE 2 -- SIDE EFFECTS. Every check above has passed; only now do
+    //  we allocate DOM, bump refcounts, and wire events.
+    //
+    //  This region is ALSO fail-closed: if any step throws (realistically a
+    //  user recipe.init, but anything here), we UNWIND every side effect that
+    //  actually landed -- in reverse acquisition order, each guarded by its own
+    //  flag so nothing underflows a refcount or double-frees -- then re-throw
+    //  the ORIGINAL error. A try/catch is free on the success path; this is all
+    //  cold mount code with zero hot-path impact.
+    // =====================================================================
+
+    let styleAcquired = false;   // acquireSliderStyle() bumped _sliderRefs
+    let wrapperAppended = false;  // wrapper is in container.children
+    let acCreated = false;       // AbortController exists (listeners may be on it)
+    let tickerAcquired = false;  // acquireTicker() bumped _sharedRefs
+    let wrapper = null;
+    let ac = null;
+    let removeTick = null;
+
+    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);
-    const dpr = window.devicePixelRatio || 1;
+    let dpr = window.devicePixelRatio || 1;
 
     // -- Create native element (invisible, accessible, receives events) --
     let el;
@@ -96,17 +252,20 @@ export function mountUIFX(container, type, recipeFactory, {
         el = document.createElement('input');
         el.type = 'checkbox';
         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) {
         el = document.createElement('input');
         el.type = 'range';
-        el.min = '0'; el.max = '100'; el.value = '50';
+        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 {
         el = document.createElement('button');
         el.textContent = label || 'Action';
         el.type = 'button';
     }
+    if (disabled) el.disabled = true;  // lands before frame 1
 
     Object.assign(el.style, {
         position: 'relative', zIndex: '2',
@@ -117,14 +276,12 @@ export function mountUIFX(container, type, recipeFactory, {
         WebkitAppearance: 'none', appearance: 'none',
     });
 
-    // Slider thumb needs explicit sizing for hit area
+    // 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) {
-        const thumbCSS = document.createElement('style');
-        thumbCSS.textContent = `
-            .uifx-slider::-webkit-slider-thumb { -webkit-appearance:none; width:24px; height:24px; cursor:grab; }
-            .uifx-slider::-moz-range-thumb { width:24px; height:24px; cursor:grab; border:none; background:transparent; }
-        `;
-        document.head.appendChild(thumbCSS);
+        acquireSliderStyle();
+        styleAcquired = true;
         el.classList.add('uifx-slider');
     }
 
@@ -145,7 +302,7 @@ export function mountUIFX(container, type, recipeFactory, {
     ctx.scale(dpr, dpr);
 
     // -- Wrapper --
-    const wrapper = document.createElement('div');
+    wrapper = document.createElement('div');
     Object.assign(wrapper.style, {
         position: 'relative', display: 'inline-block',
         width: `${w}px`, height: `${h}px`,
@@ -153,40 +310,58 @@ export function mountUIFX(container, type, recipeFactory, {
     wrapper.appendChild(el);
     wrapper.appendChild(canvas);
     container.appendChild(wrapper);
+    wrapperAppended = true;
 
-    // -- State --
+    // -- State (value/checked/disabled land here BEFORE frame 1) --
     const state = {
         hover: false,
         active: false,      // pointer is down
         focused: false,      // keyboard focus
-        toggled: false,      // checkbox state
-        val: type === UIType.SLIDER ? 0.5 : 0,  // slider value 0-1
+        toggled: checked,   // coerced boolean; element + state AGREE
+        disabled,           // recipes can render a disabled look
+        val: value !== undefined ? value : (type === UIType.SLIDER ? 0.5 : 0),  // 0-1
         w, h, padding, dpr,
     };
 
     const pointer = { x: -999, y: -999, vx: 0, vy: 0 };
+    // Cached bounding rect. Refreshed on pointerenter + scroll/resize (cold);
+    // pointermove reads it with ZERO layout reads (U-11). null until the first
+    // pointer event, then lazily filled once (see updatePointer).
+    let rect = null;
 
-    // -- Initialize recipe --
-    const recipe = recipeFactory();
+    // -- 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);
 
     // -- Events (all via AbortController) --
-    const ac = new AbortController();
+    ac = new AbortController();
+    acCreated = true;
     const signal = ac.signal;
 
     function updatePointer(e) {
-        const r = el.getBoundingClientRect();
-        const nx = e.clientX - r.left;
-        const ny = e.clientY - r.top;
+        // Lazily fill the rect on the first pointer event (e.g. a pointerdown
+        // with no prior pointerenter). Fires getBoundingClientRect at most once
+        // until the next scroll/resize/enter nulls or refreshes it -- steady-
+        // state pointermove does ZERO layout reads (U-11 / NIT 1).
+        if (!rect) rect = el.getBoundingClientRect();
+        const nx = e.clientX - rect.left;
+        const ny = e.clientY - rect.top;
         pointer.vx = nx - pointer.x;
         pointer.vy = ny - pointer.y;
         pointer.x = nx;
         pointer.y = ny;
     }
+    function refreshRect() { rect = el.getBoundingClientRect(); }
+
+    // Rect invalidation on layout shift -- cold path, through ac.signal so
+    // destroy()'s abort removes them (no orphaned window listeners).
+    window.addEventListener('scroll', refreshRect, { passive: true, signal });
+    window.addEventListener('resize', refreshRect, { passive: true, signal });
 
     el.addEventListener('pointermove', updatePointer, { signal });
     el.addEventListener('pointerenter', (e) => {
         state.hover = true;
+        refreshRect();          // one layout read per enter
         updatePointer(e);
         if (recipe.onHover) recipe.onHover(state, pointer);
     }, { signal });
@@ -211,13 +386,11 @@ export function mountUIFX(container, type, recipeFactory, {
             state.toggled = el.checked;
             if (recipe.onToggle) recipe.onToggle(state.toggled, state);
         }, { signal });
-        // Keyboard: Space/Enter toggles checkbox
+        // Space activates the checkbox natively (browser fires click -> change ->
+        // the listener above). Enter is not native for a checkbox; route it
+        // through the SAME activation path so there is one onToggle per press.
         el.addEventListener('keydown', (e) => {
-            if (e.code === 'Space' || e.code === 'Enter') {
-                el.checked = !el.checked;
-                state.toggled = el.checked;
-                if (recipe.onToggle) recipe.onToggle(state.toggled, state);
-            }
+            if (e.code === 'Enter') el.click();
         }, { signal });
     }
 
@@ -229,12 +402,29 @@ export function mountUIFX(container, type, recipeFactory, {
         }, { 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. --
+    if (typeof window.matchMedia === 'function') {
+        const mq = window.matchMedia('(resolution: ' + dpr + 'dppx)');
+        mq.addEventListener('change', () => {
+            const nd = window.devicePixelRatio || 1;
+            dpr = nd;
+            canvas.width = cw * nd;
+            canvas.height = ch * nd;
+            ctx.setTransform(nd, 0, 0, nd, 0, 0);
+            state.dpr = nd;
+        }, { signal });
+    }
+
     // -- Render loop (shared ticker) --
     const ticker = acquireTicker();
+    tickerAcquired = true;
     let destroyed = false;
+    let quarantined = false;  // a recipe.tick throw quarantines only this one
 
-    const removeTick = ticker.add((dtMs) => {
-        if (destroyed) return;
+    removeTick = ticker.add((dtMs) => {
+        if (destroyed || quarantined) return;
         const dt = dtMs / 1000;
         const now = performance.now();
 
@@ -242,7 +432,17 @@ export function mountUIFX(container, type, recipeFactory, {
         ctx.clearRect(0, 0, cw, ch);
         ctx.save();
         ctx.translate(padding, padding); // Origin = native element's top-left
-        recipe.tick(ctx, dt, now, state, pointer);
+        try {
+            recipe.tick(ctx, dt, now, state, pointer);
+        } catch (err) {
+            // U-02B: contain the throw. The shared Ticker never sees it, so its
+            // RAF reschedules and every other component keeps running.
+            quarantined = true;
+            console.error('mountUIFX: recipe.tick threw for type "' + type + '"; component quarantined', err);
+            ctx.restore();
+            ctx.clearRect(0, 0, cw, ch);
+            return;
+        }
         ctx.restore();
     });
 
@@ -268,9 +468,27 @@ export function mountUIFX(container, type, recipeFactory, {
             removeTick();
             if (recipe.destroy) recipe.destroy();
             releaseTicker();
+            if (type === UIType.SLIDER) releaseSliderStyle();
             wrapper.remove();
         },
     };
+    } catch (err) {
+        // A step in phase 2 threw (realistically recipe.init -- user code).
+        // Unwind ONLY what was actually acquired, in reverse acquisition order,
+        // each guarded by its flag so an early throw (e.g. at init, before ac /
+        // 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 (acCreated) ac.abort();
+        if (wrapperAppended) wrapper.remove();
+        if (styleAcquired) releaseSliderStyle();
+        // Re-throw the ORIGINAL error, preserved verbatim (never wrapped).
+        throw err;
+    }
 }
 
 export default mountUIFX;

package/llms.txt

@@ -1,7 +1,7 @@
 # @zakkster/lite-ui-fx
 > Canvas-hijacked UI components with pluggable recipe system. 50 built-in recipes.
 
-VERSION 1.0.5
+VERSION 1.1.0
 
 ## Install
 npm i @zakkster/lite-ui-fx
@@ -23,13 +23,19 @@ import { VolumeKnob, WaterLevel, TimerCountdown } from './recipes/UIFXRecipes3.j
 const instance = mountUIFX(container, UIType.TOGGLE, SwarmToggle, { label: 'Sound' });
 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
+value     // slider start, number 0..1 (default 0.5); out-of-range or non-number throws
+checked   // toggle start, boolean (default false)
+disabled  // native disabled attr + state.disabled for recipes to render
+
 ## 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)
 
 ## State Object (provided to tick every frame)
-{ hover, active, focused, toggled, val, w, h, padding, dpr }
+{ hover, active, focused, toggled, disabled, val, w, h, padding, dpr }
 
 ## 50 Built-in Recipes
 

package/package.json

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