@zakkster/lite-ui-fx 1.0.5 → 1.2.0

package/CHANGELOG.md

@@ -5,7 +5,96 @@ 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.2.0] -- unreleased
+
+Recipes ship as code (U-13). The three GitHub-only recipe volumes are
+consolidated into one `UIFXRecipes.js` at the package root, exposed as the
+`./recipes` subpath export behind a registry. No recipe body changes -- the
+zero-GC / size-true / theming sweep is U3.
+
+### Added
+
+- `./recipes` subpath export: all 50 recipes ship in one `UIFXRecipes.js`
+  (with `UIFXRecipes.d.ts`), versioned, typed, and tree-shakeable
+  (`sideEffects: false`). `UIFX-RECIPE-GUIDE.md` moves to the package root and
+  ships as well.
+- Recipe registry (ported from `@zakkster/lite-scratch-fx`): `RECIPES`
+  (null-prototype, id -> factory), `RECIPE_META` (`{ id, name, type, family,
+  themeable, motionSafe }`; `themeable` and `motionSafe` are `false` for all
+  until U3), `RECIPE_NAMES` (frozen), and `registerRecipe(id, factory, meta)`
+  with an in-place meta-merge.
+- `mountRecipe(container, id, options?)`: resolves the id fail closed (an
+  unknown id throws with a did-you-mean; a non-string id gets the same clean
+  message), asserts any `options.type` matches the recipe's declared type, then
+  mounts via `mountUIFX`.
+- Torture: `t0-lifecycle` and `t1-degenerate` iterate `RECIPE_META`, so all 50
+  recipes are mounted, exercised, and destroyed by construction. New
+  `test/registry.test.mjs` (registry + `mountRecipe` contract + a boundary
+  matrix) and `test/treeshake.test.mjs` (an esbuild proof that importing one
+  recipe drops the others).
+
+### Changed
+
+- Fail closed on the element type: `mountUIFX` now throws on any `type` other
+  than `UIType.BUTTON` / `TOGGLE` / `SLIDER` (an unknown type previously became
+  a button silently), and `registerRecipe` rejects a recipe with no valid type
+  before any mutation.
+- The recipes are no longer a GitHub ZIP / copy-paste. `README.md` and
+  `llms.txt` document the `./recipes` import and drop the "not included in the
+  npm package" wording.
+- `package.json`: `exports["./recipes"]` added; `files[]` ships
+  `UIFXRecipes.js`, `UIFXRecipes.d.ts`, and `UIFX-RECIPE-GUIDE.md`; `esbuild`
+  added as a devDependency (the tree-shake proof only -- not shipped).
+- Decision recorded in `decisions/0001-recipes-position.md`.
+
+### Removed
+
+- The `recipes/` directory (three volumes plus their `.d.ts`). Their exports
+  are unchanged and now come from the root `UIFXRecipes.js`.
+
+## [1.1.0] -- 2026-09-06
+
+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

@@ -40,26 +40,22 @@ https://cdpn.io/pen/debug/YPGEaYY
 
 Every recipe is zero-GC, uses `dt`-based animation, and includes accessibility indicators (focus rings, state labels).
 
-`@zakkster/lite-ui-fx` ships only the core controller on npm (zero bloat).
-All visual effects live in the GitHub repo as **recipes**.
+All 50 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.
 
-**Recipe Collections:**
-- Vol. 1 (10 recipes):
-  https://github.com/PeshoVurtoleta/lite-ui-fx/blob/main/recipes/UIFXRecipes.js
-- Vol. 2 (20 recipes):
-  https://github.com/PeshoVurtoleta/lite-ui-fx/blob/main/recipes/UIFXRecipes2.js
-- Vol. 3 (20 recipes):
-  https://github.com/PeshoVurtoleta/lite-ui-fx/blob/main/recipes/UIFXRecipes3.js
-
-**How to write your own:**
-https://github.com/PeshoVurtoleta/lite-ui-fx/blob/main/recipes/UIFX-RECIPE-GUIDE.md
+```javascript
+import { mountUIFX, UIType } from '@zakkster/lite-ui-fx';
+import { SwarmToggle } from '@zakkster/lite-ui-fx/recipes';
+```
 
-Recipes are **optional**, **open-source**, and **not included in the npm package**
-to keep the install size tiny (<2 KB).
-You can copy/paste any recipe into your project or use them as inspiration.
+The `./recipes` entry also exports a registry for data-driven pickers:
+`RECIPES` (id -> factory), `RECIPE_META` (`{ id, name, type, family }`),
+`RECIPE_NAMES`, `registerRecipe(id, factory, meta)`, and
+`mountRecipe(container, id, options?)` -- which resolves the id fail-closed
+(did-you-mean on a typo) and mounts it as its declared type.
 
-Download all recipes as a ZIP
-https://github.com/PeshoVurtoleta/lite-ui-fx/archive/refs/heads/main.zip
+**How to write your own:** see [UIFX-RECIPE-GUIDE.md](UIFX-RECIPE-GUIDE.md), shipped in the package.
 
 Part of the [@zakkster/lite-*](https://www.npmjs.com/org/zakkster) ecosystem.
 
@@ -69,15 +65,15 @@ Part of the [@zakkster/lite-*](https://www.npmjs.com/org/zakkster) ecosystem.
 npm i @zakkster/lite-ui-fx
 ```
 
-> Looking for the visual effects?
-> Recipes live in the GitHub repo -- not in the npm package -- to keep the library tiny.
+> The 50 recipes ship in the same package on the `./recipes` subpath and
+> tree-shake, so importing one adds only that one.
 
 
 ## Quick Start
 
 ```javascript
 import { mountUIFX, UIType } from '@zakkster/lite-ui-fx';
-import { SwarmToggle } from './recipes/UIFXRecipes.js';
+import { SwarmToggle } from '@zakkster/lite-ui-fx/recipes';
 
 // Mount a canvas-rendered toggle onto a container
 const instance = mountUIFX(
@@ -101,17 +97,13 @@ instance.destroy();
 // Controller (always needed)
 import { mountUIFX, UIType } from '@zakkster/lite-ui-fx';
 
-// Recipes are NOT included in the npm package.
-// Copy them from the GitHub repo into your own ./recipes folder:
-
-// Vol. 1 -- 10 recipes (toggles, buttons, sliders)
-import { SwarmToggle, MagneticButton, SparkSlider } from './recipes/UIFXRecipes.js';
-
-// Vol. 2 -- 20 recipes (+ loaders, checkboxes, counters, rating)
-import { PendulumToggle, HeartbeatButton, RippleCheck } from './recipes/UIFXRecipes2.js';
+// All 50 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';
 
-// Vol. 3 -- 20 recipes (knobs, progress, controls, indicators, mood, feedback, fun)
-import { VolumeKnob, WaterLevel, TimerCountdown } from './recipes/UIFXRecipes3.js';
+// Registry surface for data-driven pickers:
+import { RECIPES, RECIPE_META, RECIPE_NAMES, registerRecipe, mountRecipe } from '@zakkster/lite-ui-fx/recipes';
 ```
 
 ## How It Works
@@ -150,6 +142,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 +164,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
@@ -188,7 +184,7 @@ Returns `{ el, canvas, wrapper, state, destroy() }`.
 
 ## Writing Custom Recipes
 
-See the full [UIFX-RECIPE-GUIDE.md](recipes/UIFX-RECIPE-GUIDE.md) (included in the package).
+See the full [UIFX-RECIPE-GUIDE.md](UIFX-RECIPE-GUIDE.md) (included in the package).
 
 Minimal recipe:
 
@@ -222,7 +218,7 @@ Full TypeScript declarations are included for:
 - `UIFXPointer`
 - `UIFXRecipe`
 
-(Recipes are not part of the npm package, so their types are not included.)
+Recipe types ship too, on the `./recipes` subpath (`UIFXRecipes.d.ts`).
 
 
 ## LLM-Friendly Documentation

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.2.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,95 @@ 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');
+    }
+
+    // 1b. type: exactly one of the three known element types. 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');
+    }
+
+    // 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 +259,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 +283,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 +309,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 +317,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 +393,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 +409,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 +439,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 +475,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;