@zakkster/lite-ui-fx 1.9.1 → 1.11.0

package/CHANGELOG.md

@@ -5,6 +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.11.0] -- 2026-09-08
+
+Enrichment session E1b (decisions/0009): seven bespoke headless skins continuing the
+E1 adapter -- the select trigger (resolving the dropdown decision toward a V4 skin),
+a tri-state checkbox + checkbox-group master, and meter/steps/accordion/skeleton.
+Single-host, no new dependency; the 57-recipe registry is byte-identical.
+
+### Added
+
+- Seven headless skins on the `./headless` subpath, registered in the sibling
+  `HEADLESS_SKINS` / `SKIN_META` / `SKIN_NAMES` (4 -> 11 skins; RECIPES / RECIPE_META
+  and the 57-recipe count unchanged). Each is single-host, themeable, and allocates
+  zero bytes per frame, gated by the t6 torture tier (now gating 11 skins):
+  - `CheckboxSkin` -- tri-state from `aria-checked` (`true`|`false`|`mixed`) or the
+    `data-checked` / `data-indeterminate` presence pair, onto the existing `toggled`
+    / `indeterminate` state slots.
+  - `CheckboxGroupSkin` -- the same body over a checkbox-group master (identical
+    3-state contract; "mixed" reads as partial members).
+  - `SelectSkin` -- the select TRIGGER: `aria-expanded` drives an open/close chevron,
+    the handle `value()` fast path drives a selected-value dot. The portaled listbox
+    open-state is a recorded follow-on (decisions/0009).
+  - `MeterSkin` -- `aria-valuenow`/`min`/`max` fill, zone-tinted from `data-zone`.
+  - `StepsSkin` -- a node rail from `data-step-count` / `data-current-index` /
+    `data-complete`.
+  - `AccordionSkin` -- a header chevron + underline from `aria-expanded` / `data-open`.
+  - `SkeletonSkin` -- a zero-allocation `globalAlpha` shimmer from `data-loading` /
+    `aria-busy`.
+  `@zakkster/lite-headless` is imported nowhere and is not a dependency; no dependency
+  was added.
+
+### Changed
+
+- `llms.txt` and `README.md`: the `./headless` skin catalog lists all 11 skins, and
+  the sibling primitive count is corrected ("59" -> 62, the `@zakkster/lite-headless`
+  1.9.1 catalog). Documentation only; no code path changed.
+
+### Fixed
+
+none
+
+### Removed
+
+none
+
+## [1.10.0] -- 2026-09-08
+
+Enrichment session E1: skinHeadless, a fourth mount adapter that paints a
+`@zakkster/lite-headless` primitive by observing the state attributes it paints.
+Additive -- the three existing mount modes and the 57-recipe registry are
+byte-identical.
+
+### Added
+
+- `skinHeadless(handle, recipeFactory, options)` -- a fourth mount adapter, exported
+  from `.` and from the new `./headless` subpath. It places an overlay canvas over
+  the element a `@zakkster/lite-headless` primitive paints on and drives a recipe from
+  that primitive's painted state attributes via one `MutationObserver`, parsed at
+  event time (never per frame). It couples through the painted-attribute contract
+  only: `@zakkster/lite-headless` is imported nowhere and is not a dependency.
+  Structurally a decoration -- no native element, host byte-identical, one overlay
+  canvas + one observer removed on `destroy()`, the primitive handle never destroyed.
+  `setValue`/`setChecked` throw. See decisions/0008.
+- The `./headless` subpath (`UIFXHeadless.js` + `UIFXHeadless.d.ts`) and four headless
+  skins: `SwitchSkin` (data-checked/aria-checked), `SliderSkin` (aria-valuenow/min/max
+  + data-dragging), `ProgressSkin` (aria-valuenow/max + data-complete/data-loading),
+  `RatingSkin` (aria-valuenow/max). They live in a registry (`HEADLESS_SKINS`,
+  `SKIN_META`, `SKIN_NAMES`) separate from `RECIPES`/`RECIPE_META`, so the 57-recipe
+  count is unchanged. Each resolves theme in init and allocates zero bytes per frame,
+  gated by a new torture tier (t6); the existing alloc baseline is unchanged.
+
+### Changed
+
+- `package.json` `description`: corrected the recipe count (was "50", now 57) and
+  named the three mount modes plus the headless-skin adapter.
+- `llms.txt` and `UIFXRecipes.d.ts`: corrected a stale recipe count ("56" -> 57 in the
+  themeable and default-namespace notes) left over from the U7 addition of the 57th
+  recipe. Shipped-doc accuracy only; no code path changed.
+
+### Fixed
+
+- ReactionPicker: paints a hairline ring around each disc and seeds the discs at
+  rest radius, so the row is visible on the first frame and where colour-emoji
+  glyphs do not render. Previously only the 4%-alpha discs and the emoji drew, so
+  an un-ticked or emoji-less environment showed an empty card. No added per-frame
+  allocation; the torture alloc baseline is unchanged.
+
+### Removed
+
+none
+
 ## [1.9.1] -- 2026-09-07
 
 Patch: a rendering fix for the ReactionPicker recipe.

package/README.md

@@ -50,6 +50,7 @@ Three runtime dependencies, all zero-GC (`@zakkster/lite-ticker`, `lite-lerp`, `
   - [mountUIFX](#mountuifxcontainer-type-recipefactory-options)
   - [decorateUIFX](#decorateuifxel-recipefactory-options)
   - [mountUIFXGroup](#mountuifxgroupcontainer-grouptype-recipefactory-options)
+  - [skinHeadless](#skinheadlesshandle-recipefactory-options)
   - [The recipe registry](#the-recipe-registry)
   - [Constants: UITypes, state, META](#constants-uitypes-state-meta)
 - [Host clock and reduced motion](#host-clock-and-reduced-motion)
@@ -79,6 +80,7 @@ The alternative is a hand-rolled canvas threshold loop (no a11y, allocates freel
 - **`mountUIFX(container, type, recipeFactory, options?)`** -- the hijack mount. Creates a real native element (invisible, accessible) under a DPR-scaled canvas and drives the recipe. Six element types: `TOGGLE`, `BUTTON`, `SLIDER`, `CHECKBOX`, `PROGRESS`, `KNOB`.
 - **`decorateUIFX(el, recipeFactory, options?)`** -- the decorate mount. Places a canvas *around* an existing visible element (a live `<input>`), reading `state.text`/`state.valid` from the host's own events. The host is byte-identical before and after; `destroy()` removes only the overlay.
 - **`mountUIFXGroup(container, groupType, recipeFactory, options)`** -- the group mount. N native elements + one canvas + one recipe: `RADIO`/`RATING` (a fieldset radiogroup), `TABS` (an APG tablist with roving tabindex), `STEPPER` (a spinbutton). The recipe reads `state.index`/`state.count`; selection and keyboard are the native elements' own.
+- **`skinHeadless(handle, recipeFactory, options)`** -- the headless-skin adapter (on the `./headless` subpath). Paints a `@zakkster/lite-headless` primitive by observing the state attributes it paints -- never importing lite-headless, so it stays a compose-target, not a dependency.
 - **57 built-in recipes** on the `./recipes` subpath, versioned, typed, and tree-shakeable. With `sideEffects: false`, importing one recipe drops the other 56. Families: Toggles (7), Buttons (9), Sliders (7), Knobs (2), Progress (4), Checkboxes (4), Loaders (2), Counters (2), Rating (1), Controls (4), Indicators (3), Mood (3), Feedback (3), Fun (3), Form decorations (3).
 - **A registry for data-driven UIs** -- `RECIPES` (id -> factory, null-prototype), `RECIPE_META` (`{ id, name, type, family, themeable, motionSafe }`), `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.
 - **One option convention for theming** -- `{ colors, theme: { light, mid, dark }, text, font }` honoured by all 57 recipes, resolved once in `init` so a themed mount stays zero-GC and a bare mount is byte-identical to pre-theming.
@@ -205,6 +207,32 @@ tabs.destroy();
 
 Built-in group recipes: `PillTabs`, `SegmentedSlide` (`TABS`), `RadioOrbit` (`RADIO`), `Stepper` (`STEPPER`), `BubbleRating` (`RATING`). The first four re-home from their vol.3 single-element fakes to real groups (so their arrow-key selection is finally correct); `mountRecipe(container, id, { items })` routes them here by `META.type`.
 
+### `skinHeadless(handle, recipeFactory, options)`
+
+The fourth mount adapter, on the `./headless` subpath: **skin a `@zakkster/lite-headless` primitive.** lite-headless ships ARIA-correct primitives that render nothing and paint a canonical set of state attributes; `skinHeadless` places a canvas over the element a primitive paints on and drives a recipe from those attributes -- lite-ui-fx paints, lite-headless behaves. It couples through the painted-attribute contract, never an import, so **lite-headless is never a dependency**. Structurally a decoration: the host is byte-identical, one overlay canvas + one `MutationObserver` are removed on `destroy()`, and the primitive `handle` is never destroyed (the caller owns it).
+
+`options`: `host` (the element the primitive paints on, **required**) plus `padding`, `seed`, `colors`, `theme`, `text`, `font`, `ticker`, `driven`. `setValue`/`setChecked` throw -- a skin reflects the primitive, it does not drive it.
+
+A skin is an ordinary recipe plus a descriptor -- `recipe.headless = { attrs, read(host, handle, state) }`. `skinHeadless` observes `attrs` and calls `read()` at **event time** (never per frame) to parse the painted state into preallocated slots. A painted attribute is truthy when present with any value but `"false"` (so both a boolean `data-disabled` and a value `data-checked="true"` work). The 11 skins live in a registry (`HEADLESS_SKINS` / `SKIN_META`) separate from the 57 recipes.
+
+```js
+import { skinHeadless, SwitchSkin } from '@zakkster/lite-ui-fx/headless';
+
+// `sw` is your @zakkster/lite-headless primitive (e.g. createSwitch({ ... })).
+// The skin never imports lite-headless -- it observes the attributes it paints.
+const sw = null;                                        // <- your lite-headless switch handle
+const thumb = document.querySelector('[data-switch-thumb]');
+
+const skin = skinHeadless(sw, SwitchSkin, {
+  host: thumb,
+  theme: { light: '#38bdf8', mid: '#3a3a4a', dark: '#0a0a12' },
+});
+// the overlay now tracks data-checked / aria-checked as the switch paints them
+skin.destroy();                                         // host + handle left untouched
+```
+
+E1 skins: `SwitchSkin` (`data-checked`), `SliderSkin` (`aria-valuenow`/`min`/`max`), `ProgressSkin` (`aria-valuenow`/`max` + `data-complete`/`data-loading`), `RatingSkin` (`aria-valuenow`/`max`). E1b skins: `CheckboxSkin` (tri-state `aria-checked` `true`|`false`|`mixed`), `CheckboxGroupSkin` (the same body over a checkbox-group master), `SelectSkin` (the select **trigger** -- `aria-expanded` + `handle.value()`; the portaled listbox open-state is a follow-on), `MeterSkin` (`aria-valuenow`/`min`/`max` + `data-zone`), `StepsSkin` (`data-step-count`/`data-current-index`), `AccordionSkin` (`aria-expanded`/`data-open`), `SkeletonSkin` (`data-loading`/`aria-busy`). See [0008](decisions/0008-headless-skins.md) + [0009](decisions/0009-headless-skins-select.md).
+
 ### The recipe registry
 
 ```js
@@ -348,6 +376,8 @@ Each is an ADR under [`decisions/`](decisions/):
 - **[0005](decisions/0005-host-clock.md) -- Host clock, reduced motion, frame budget.** Three clock modes, `state.reducedMotion` as a flag the recipe reads, `state.budget` for graceful degradation -- all additive, default path byte-identical.
 - **[0006](decisions/0006-docs-and-demo.md) -- Blueprint docs + a demo that consumes the package.** This README on the blueprint spine, and one demo generated from `RECIPE_META` that imports only public exports (no more inline reimplementation).
 - **[0007](decisions/0007-group-contract.md) -- Grouped controls: one canvas, N native elements.** A third mount mode (`mountUIFXGroup`) for radio/tabs/stepper/rating; `onSelect` is a ninth, group-only hook and group state a superset of scalar state, so the single-element API is byte-identical (additive, 1.9.0).
+- **[0008](decisions/0008-headless-skins.md) -- Headless skins: paint a lite-headless primitive.** `skinHeadless` couples through the painted-attribute contract (one `MutationObserver`, parsed at event time), never an import -- so lite-headless is a compose-target, never a dependency. The four skins live in a registry separate from the 57 recipes (additive, 1.10.0).
+- **[0009](decisions/0009-headless-skins-select.md) -- Headless skins II: the select + tri-state pack.** Adds seven bespoke skins (checkbox tri-state + checkbox-group master, select trigger, meter, steps, accordion, skeleton), all single-host and mapping onto the existing state slots (no state-shape change). `SelectSkin` resolves the `<select>`/dropdown decision toward a V4 skin of the trigger; the portaled listbox open-state is a recorded follow-on. No new dependency (additive, 1.11.0).
 
 ---
 
@@ -370,7 +400,7 @@ The suite covers the a11y state machine (one Space press = one `onToggle`, state
 - **Not a component framework.** It paints controls; it does not do layout, routing, or state management. Bring your own.
 - **Not a worker-mode renderer.** A 200x48 UI canvas does not amortise a worker hop; the shared main-thread ticker is the right tool. (`@zakkster/lite-ambient-fx` is the worker-mode fullscreen backdrop.)
 - **Not a chart or data-viz library.** These are interactive *controls*, not plots. Charts are `@zakkster/lite-charts`.
-- **Not an ARIA behaviour engine.** It renders. The one keyboard behaviour it writes is the tablist roving-tabindex for a `TABS` group (radio/rating/stepper selection is the browser's own); it does not own focus traps, dismiss stacks, or listbox/combobox/menu patterns. `@zakkster/lite-headless` owns behaviour, permanently -- and its 59 primitives are a decorate-mode skin target.
+- **Not an ARIA behaviour engine.** It renders. The one keyboard behaviour it writes is the tablist roving-tabindex for a `TABS` group (radio/rating/stepper selection is the browser's own); it does not own focus traps, dismiss stacks, or listbox/combobox/menu patterns. `@zakkster/lite-headless` owns behaviour, permanently -- and its 62 primitives are a headless-skin target.
 
 ---
 
@@ -383,7 +413,7 @@ Part of the **@zakkster** zero-GC stack:
 - [`lite-random`](https://www.npmjs.com/package/@zakkster/lite-random) -- seeded Mulberry32 RNG (deterministic particle recipes)
 - [`lite-scratch-fx`](https://www.npmjs.com/package/@zakkster/lite-scratch-fx) -- canvas scratch-reveal recipes; shares the `{ light, mid, dark }` theme shape
 - [`lite-ambient-fx`](https://www.npmjs.com/package/@zakkster/lite-ambient-fx) -- fullscreen ambient backdrops (the worker-mode sibling)
-- [`lite-headless`](https://www.npmjs.com/package/@zakkster/lite-headless) -- 59 ARIA-correct primitives; a decorate-mode skin target
+- [`lite-headless`](https://www.npmjs.com/package/@zakkster/lite-headless) -- 62 ARIA-correct primitives; a headless-skin target (`skinHeadless`)
 - **`lite-ui-fx`** -- this package
 
 ---

package/UIFXController.d.ts

@@ -232,6 +232,87 @@ export declare function decorateUIFX(
     options?: DecorateOptions
 ): DecorateInstance;
 
+// =========================================================
+//  skinHeadless -- paint a lite-headless primitive (decisions/0008, E1)
+// =========================================================
+
+/**
+ * The descriptor that makes a recipe skinnable: the painted attributes to observe
+ * and how to parse them into recipe state. read() runs at EVENT time (init + every
+ * mutation), never per frame -- so it may read attributes freely.
+ */
+export interface HeadlessSkinDescriptor {
+    /** The painted state attributes to observe (MutationObserver attributeFilter). */
+    attrs: string[];
+    /** Parse the primitive's painted attributes into the preallocated state slots
+     *  (state.val/toggled/disabled/complete/... ). `handle` is the lite-headless
+     *  primitive handle for an optional signal fast path, or null. */
+    read(host: HTMLElement, handle: any, state: UIFXState): void;
+}
+
+/** A recipe usable with skinHeadless: an ordinary recipe plus a `headless`
+ *  descriptor. Additive to UIFXRecipe -- no hook is added or changed. */
+export interface HeadlessSkinRecipe extends UIFXRecipe {
+    headless: HeadlessSkinDescriptor;
+}
+
+export type HeadlessSkinRecipeFactory = (options?: SkinOptions) => HeadlessSkinRecipe;
+
+/**
+ * Options accepted by skinHeadless. The decorate subset PLUS `host` (the element
+ * the primitive paints on, REQUIRED). The hijack-only options are rejected.
+ */
+export interface SkinOptions extends HostClockOptions {
+    /** The element the lite-headless primitive paints on: the overlay + observer
+     *  target (REQUIRED). */
+    host: HTMLElement;
+    /** Overlay padding around the host, in px (default 40). */
+    padding?: number;
+    seed?: number;
+    colors?: string[];
+    theme?: { light: string; mid: string; dark: string };
+    text?: string;
+    font?: string;
+}
+
+/**
+ * The instance returned by skinHeadless. Like DecorateInstance: no wrapper, and
+ * setValue/setChecked are hijack-only (a skin reflects the primitive, it does not
+ * drive it, so both throw).
+ */
+export interface SkinInstance {
+    /** The skinned host element (unchanged -- skinHeadless never mutates it). */
+    el: HTMLElement;
+    /** The overlay canvas (the only DOM node skinHeadless adds). */
+    canvas: HTMLCanvasElement;
+    state: UIFXState;
+    /** Drive one frame by hand (U5). Callable ONLY with { driven: true }. */
+    tick(dtMs: number): void;
+    /** Hijack-only. Throws in skin mode. */
+    setValue(v?: number | null): void;
+    /** Hijack-only. Throws in skin mode. */
+    setChecked(b?: boolean): void;
+    /** Remove the overlay + observer + every listener the skin added; the host AND
+     *  the lite-headless handle are left untouched. Idempotent. */
+    destroy(): void;
+}
+
+/**
+ * Skin a @zakkster/lite-headless primitive: place a canvas over the element it
+ * paints on and drive a recipe from the primitive's PAINTED state attributes --
+ * lite-ui-fx paints, lite-headless behaves. Arm's-length: it couples through the
+ * painted-attribute contract (lite-headless docs/CSS_CONTRACT.md), NEVER an import,
+ * so lite-headless is never a dependency. Structurally a decoration (0004): no
+ * native element, host byte-identical, one overlay canvas + one MutationObserver
+ * removed on destroy; the `handle` is never destroyed (the caller owns it). The
+ * recipe MUST carry a `headless` descriptor. See decisions/0008.
+ */
+export declare function skinHeadless(
+    handle: any,
+    recipeFactory: HeadlessSkinRecipeFactory,
+    options: SkinOptions
+): SkinInstance;
+
 // =========================================================
 //  Grouped controls (U7, decisions/0007)
 // =========================================================

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.9.1';
+export const VERSION = '1.11.0';
 
 // ---------------------------------------------------------
 //  SHARED TICKER (ref-counted, one RAF for all UI components)
@@ -124,6 +124,10 @@ const KNOB_MODES = ['rotate', 'vertical'];
 // ARE valid in decorate mode: a decoration wants host-clock control every bit as
 // much as a hijack does. Cold: read only at mount.
 const DECORATE_OPTIONS = ['padding', 'seed', 'colors', 'theme', 'text', 'font', 'ticker', 'driven'];
+// skinHeadless (E1, decisions/0008) takes the decorate subset PLUS `host` -- the
+// element the lite-headless primitive paints its state attributes on (REQUIRED; the
+// overlay + MutationObserver target). The hijack-only keys throw, same as decorate.
+const HEADLESS_OPTIONS = ['host', 'padding', 'seed', 'colors', 'theme', 'text', 'font', 'ticker', 'driven'];
 
 // Levenshtein edit distance. Cold: only reached on the error path.
 function _editDistance(a, b) {
@@ -1209,6 +1213,382 @@ export function decorateUIFX(el, recipeFactory, options = {}) {
     }
 }
 
+// =========================================================
+//  skinHeadless -- paint a lite-headless primitive (decisions/0008, E1)
+// =========================================================
+
+/**
+ * Skin a @zakkster/lite-headless primitive: place a canvas over the element the
+ * primitive paints on and drive a recipe from the primitive's PAINTED state
+ * attributes -- lite-ui-fx paints, lite-headless behaves. Arm's-length: it
+ * couples through the attribute contract (docs/CSS_CONTRACT.md), NOT an import, so
+ * lite-headless is never a dependency. Structurally a decoration (0004): no native
+ * element, host never reparented/restyled, one overlay canvas + its listeners + one
+ * MutationObserver; on destroy the host is byte-identical and the handle untouched.
+ *
+ * The recipe MUST be a headless-skin recipe: it carries
+ *   recipe.headless = { attrs: string[], read(host, handle, state) }
+ * where `attrs` is the MutationObserver attributeFilter and `read` parses the
+ * painted attributes into preallocated `state` slots (val/toggled/disabled/...),
+ * called once at init and on every mutation -- EVENT time, never per frame.
+ *
+ * @param {Object}   handle         The lite-headless primitive handle (duck-typed;
+ *                                  passed to read() for an optional signal fast path;
+ *                                  NEVER destroyed here). May be null.
+ * @param {Function} recipeFactory  (options) => Recipe with a `headless` descriptor.
+ * @param {Object}   options        { host: Element (REQUIRED), padding=40, seed,
+ *                                  colors, theme, text, font, ticker, driven }.
+ * @returns {{ el, canvas, state, tick, setValue, setChecked, destroy }}
+ */
+export function skinHeadless(handle, recipeFactory, options = {}) {
+    // =====================================================================
+    //  PHASE 1 -- VALIDATION ONLY (fail closed; mirrors decorateUIFX). No
+    //  createElement, no observer, no ticker acquire, no recipe.init until
+    //  every check below has passed.
+    // =====================================================================
+
+    // 1. handle: duck-typed. It is optional context for read()'s fast path and is
+    //    never destroyed by skinHeadless. Only a non-nullish non-object is a
+    //    mistake (a primitive handle is an object).
+    if (handle !== null && handle !== undefined && typeof handle !== 'object') {
+        throw new Error('skinHeadless: handle must be a lite-headless primitive handle (an object) or null');
+    }
+
+    // 2. options: the decorate subset + `host`. Unknown key -> did-you-mean; a
+    //    hijack-only key -> a clear "not valid in skin mode". Both fail closed.
+    for (const k in options) {
+        if (!Object.prototype.hasOwnProperty.call(options, k)) continue;
+        if (HEADLESS_OPTIONS.indexOf(k) === -1) {
+            if (KNOWN_OPTIONS.indexOf(k) !== -1) {
+                throw new Error('skinHeadless: option "' + k + '" is not valid in skin mode (hijack-only)');
+            }
+            throw new Error(_didYouMean('skinHeadless: unknown option', k, HEADLESS_OPTIONS));
+        }
+    }
+
+    // 3. host: a live, attached DOM element -- the overlay is a sibling of it and
+    //    the observer watches it. A detached host has no parentNode to host the
+    //    canvas: an Error, never a silent no-op (mirrors decorate's el checks).
+    const host = options.host;
+    if (!host || typeof host.getBoundingClientRect !== 'function' ||
+        typeof host.setAttribute !== 'function') {
+        throw new Error('skinHeadless: options.host must be a DOM element (the element the primitive paints on)');
+    }
+    if (!host.parentNode || typeof host.parentNode.insertBefore !== 'function') {
+        throw new Error('skinHeadless: options.host must be attached to the DOM (no parentNode to host the overlay)');
+    }
+
+    const padding = options.padding === undefined ? 40 : options.padding;
+
+    // Theming options (decisions/0002): validated fail closed, forwarded to the
+    // recipe factory which resolves them in init. Cold mount code.
+    const _theme = options.theme;
+    if (_theme !== undefined) {
+        if (_theme === null || typeof _theme !== 'object' ||
+            typeof _theme.light !== 'string' || typeof _theme.mid !== 'string' ||
+            typeof _theme.dark !== 'string' || Object.keys(_theme).length !== 3) {
+            throw new Error('skinHeadless: option "theme" must be { light, mid, dark } of color strings');
+        }
+    }
+    const _colors = options.colors;
+    if (_colors !== undefined &&
+        (!Array.isArray(_colors) || _colors.some((c) => typeof c !== 'string'))) {
+        throw new Error('skinHeadless: option "colors" must be an array of color strings');
+    }
+    if (options.text !== undefined && typeof options.text !== 'string') {
+        throw new Error('skinHeadless: option "text" must be a string');
+    }
+    if (options.font !== undefined && typeof options.font !== 'string') {
+        throw new Error('skinHeadless: option "font" must be a string');
+    }
+    if (options.seed !== undefined &&
+        (typeof options.seed !== 'number' || !Number.isFinite(options.seed))) {
+        throw new Error('skinHeadless: option "seed" must be a finite number');
+    }
+
+    // Host clock (U5, decisions/0005) -- same three modes as decorate.
+    const callerTicker = options.ticker;
+    if (options.driven !== undefined && typeof options.driven !== 'boolean') {
+        throw new Error('skinHeadless: option "driven" must be a boolean');
+    }
+    const driven = options.driven === true;
+    if (callerTicker !== undefined) {
+        if (driven) {
+            throw new Error('skinHeadless: options "ticker" and "driven" are mutually exclusive');
+        }
+        if (!callerTicker || typeof callerTicker.add !== 'function') {
+            throw new Error('skinHeadless: option "ticker" must be a ticker with an .add(fn) method');
+        }
+    }
+
+    // 4. recipeFactory + recipe object + hooks (same 8-hook contract as decorate).
+    if (typeof recipeFactory !== 'function') {
+        throw new Error('skinHeadless: recipeFactory must be a function');
+    }
+    const recipe = recipeFactory(options);
+    if (!recipe || typeof recipe !== 'object') {
+        throw new Error('skinHeadless: recipe must be an object');
+    }
+    if (typeof recipe.tick !== 'function') {
+        throw new Error('skinHeadless: 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('skinHeadless: unknown recipe hook', k, KNOWN_HOOKS));
+        }
+    }
+
+    // 5. The headless descriptor -- what makes a recipe skinnable. A plain recipe
+    //    has no attribute->state mapping, so skinning it is a category error caught
+    //    here (fail closed), not a silent no-paint later.
+    const hspec = recipe.headless;
+    if (!hspec || typeof hspec !== 'object' || !Array.isArray(hspec.attrs) ||
+        hspec.attrs.length === 0 || hspec.attrs.some((a) => typeof a !== 'string') ||
+        typeof hspec.read !== 'function') {
+        throw new Error('skinHeadless: recipe must be a headless-skin recipe with recipe.headless = { attrs: string[], read(host, handle, state) } -- a plain recipe cannot be skinned (use mountUIFX or decorateUIFX)');
+    }
+
+    // =====================================================================
+    //  PHASE 2 -- SIDE EFFECTS (fail-closed unwind, mirrors decorate). The
+    //  acquisitions are the overlay canvas, the MutationObserver, the
+    //  AbortController, and the shared ticker -- unwound in reverse on a throw.
+    // =====================================================================
+    let canvasAppended = false;
+    let moConnected = false;
+    let acCreated = false;
+    let tickerAcquired = false;
+    let canvas = null;
+    let ac = null;
+    let mo = null;
+    let removeTick = null;
+
+    try {
+    // -- Placement from host's OFFSET box (0004 decision 2): the overlay is a
+    //    SIBLING of host, sharing its offsetParent, so it lands over host without
+    //    writing any style onto the parent. Read once, refreshed on resize only. --
+    let ow = host.offsetWidth;
+    let oh = host.offsetHeight;
+    let dpr = window.devicePixelRatio || 1;
+    let cw = ow + padding * 2;
+    let ch = oh + padding * 2;
+
+    canvas = document.createElement('canvas');
+    canvas.width = cw * dpr;
+    canvas.height = ch * dpr;
+    Object.assign(canvas.style, {
+        position: 'absolute',
+        left: (host.offsetLeft - padding) + 'px',
+        top: (host.offsetTop - padding) + 'px',
+        width: cw + 'px', height: ch + 'px',
+        pointerEvents: 'none',
+    });
+    const ctx = canvas.getContext('2d');
+    ctx.scale(dpr, dpr);
+
+    host.parentNode.insertBefore(canvas, host.nextSibling);
+    canvasAppended = true;
+
+    const rmq = _reducedMotionQuery();
+
+    // -- State. A superset of the scalar fields a skin reads; read() (below) writes
+    //    the primitive's painted state into these preallocated slots. --
+    const state = {
+        hover: false,
+        active: false,
+        focused: (typeof document !== 'undefined' && document.activeElement === host),
+        val: 0,               // slider/progress/rating fill 0..1
+        toggled: false,       // switch on/off
+        indeterminate: false, // progress loading / mixed
+        disabled: false,
+        complete: false,      // progress done
+        error: false,
+        count: 0,             // rating item count (read from the primitive)
+        reducedMotion: rmq ? !!rmq.matches : false,
+        budget: 1,
+        w: ow, h: oh, padding, dpr,
+    };
+    const pointer = { x: -999, y: -999, vx: 0, vy: 0 };
+    let rect = null;
+
+    // -- Initialize recipe (validated in phase 1). ctx exists now. --
+    if (recipe.init) recipe.init(ctx, ow, oh, padding);
+
+    // -- Seed state from the primitive's CURRENT painted attributes, before the
+    //    first frame (law: hook initial values). read() is the skin's own parse. --
+    hspec.read(host, handle, state);
+
+    // -- Events (via AbortController, exactly what destroy() removes). --
+    ac = new AbortController();
+    acCreated = true;
+    const signal = ac.signal;
+
+    function updatePointer(e) {
+        if (!rect) rect = host.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 = host.getBoundingClientRect(); }
+    // Reposition the overlay from the offset box after a layout change (cold path).
+    // Layout READS are hoisted above the style WRITES (forced-reflow law): a skin
+    // sits over live DOM, the one place this package can force layout.
+    function reposition() {
+        const nw = host.offsetWidth;
+        const nh = host.offsetHeight;
+        const ol = host.offsetLeft;
+        const ot = host.offsetTop;
+        canvas.style.left = (ol - padding) + 'px';
+        canvas.style.top = (ot - padding) + 'px';
+        if (nw !== ow || nh !== oh) {
+            ow = nw; oh = nh;
+            cw = ow + padding * 2;
+            ch = oh + padding * 2;
+            canvas.width = cw * dpr;
+            canvas.height = ch * dpr;
+            canvas.style.width = cw + 'px';
+            canvas.style.height = ch + 'px';
+            ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+            state.w = ow; state.h = oh;
+        }
+    }
+
+    window.addEventListener('scroll', refreshRect, { passive: true, signal });
+    window.addEventListener('resize', () => { reposition(); refreshRect(); }, { passive: true, signal });
+
+    // Pointer/hover state from the host's own events (a skin may light up on
+    // hover/press). onToggle/onDrag are NOT fired -- the primitive owns value.
+    host.addEventListener('pointermove', updatePointer, { signal });
+    host.addEventListener('pointerenter', (e) => {
+        state.hover = true;
+        refreshRect();
+        updatePointer(e);
+        if (recipe.onHover) recipe.onHover(state, pointer);
+    }, { signal });
+    host.addEventListener('pointerleave', () => {
+        state.hover = false;
+        if (recipe.onLeave) recipe.onLeave(state, pointer);
+    }, { signal });
+    host.addEventListener('pointerdown', (e) => {
+        state.active = true;
+        updatePointer(e);
+        if (recipe.onClick) recipe.onClick(pointer.x, pointer.y, state);
+    }, { signal });
+    host.addEventListener('pointerup', () => { state.active = false; }, { signal });
+    host.addEventListener('focus', () => { state.focused = true; }, { signal });
+    host.addEventListener('blur', () => { state.focused = false; }, { signal });
+
+    // -- THE STATE SOURCE (decisions/0008): one MutationObserver over the painted
+    //    attributes the skin declared; read() parses them into `state` at EVENT
+    //    time. Idempotent + full re-read, so it is order/timing-independent. --
+    mo = new MutationObserver(() => { hspec.read(host, handle, state); });
+    mo.observe(host, { attributes: true, attributeFilter: hspec.attrs, subtree: true });
+    moConnected = true;
+
+    // -- DPR re-read on display change (cold; absent matchMedia is a silent no-op). --
+    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 });
+    }
+    if (rmq) {
+        rmq.addEventListener('change', () => { state.reducedMotion = !!rmq.matches; }, { signal });
+    }
+
+    // -- Render loop. ONE named frame body; three clock modes; quarantine on throw
+    //    (identical to decorate). --
+    let destroyed = false;
+    let quarantined = false;
+
+    function frame(dtMs) {
+        if (destroyed || quarantined) return;
+        const dt = dtMs / 1000;
+        const now = performance.now();
+
+        if (dt > 0) {
+            let inst = _TARGET_DT / dt;
+            if (inst > 1) inst = 1; else if (inst < 0) inst = 0;
+            state.budget += (inst - state.budget) * _BUDGET_SMOOTH;
+        }
+
+        ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+        ctx.clearRect(0, 0, cw, ch);
+        ctx.save();
+        ctx.translate(padding, padding);  // Origin = the host element's top-left
+        try {
+            recipe.tick(ctx, dt, now, state, pointer);
+        } catch (err) {
+            quarantined = true;
+            console.error('skinHeadless: recipe.tick threw; skin quarantined', err);
+            ctx.restore();
+            ctx.clearRect(0, 0, cw, ch);
+            return;
+        }
+        ctx.restore();
+    }
+
+    if (driven) {
+        // no ticker acquired; removeTick stays null
+    } else if (callerTicker !== undefined) {
+        removeTick = callerTicker.add(frame);
+    } else {
+        const ticker = acquireTicker();
+        tickerAcquired = true;
+        removeTick = ticker.add(frame);
+    }
+
+    // -- Public API --
+    return {
+        /** The skinned host element (unchanged; provided for external reads). */
+        el: host,
+        /** The overlay canvas (for external styling). */
+        canvas,
+        /** Current state (read-only reference). */
+        state,
+        /** Drive one frame by hand (U5); callable ONLY in { driven: true }. */
+        tick: driven ? frame : _drivenOnly,
+        /** Hijack-only: a skin reflects the primitive, it does not drive it. */
+        setValue() {
+            throw new Error('skinHeadless: setValue is hijack-only; a skin reflects the primitive, drive the lite-headless handle instead');
+        },
+        setChecked() {
+            throw new Error('skinHeadless: setChecked is hijack-only; a skin reflects the primitive, drive the lite-headless handle instead');
+        },
+        /** Destroy: remove the overlay + observer + every listener the skin added.
+         *  Idempotent. The host AND the lite-headless handle are left untouched. */
+        destroy() {
+            if (destroyed) return;
+            destroyed = true;
+            ac.abort();
+            mo.disconnect();                      // stop observing painted attrs
+            if (removeTick) removeTick();         // shared OR caller ticker; null when driven
+            if (recipe.destroy) recipe.destroy();
+            if (tickerAcquired) releaseTicker();  // release ONLY the shared ticker we acquired
+            canvas.remove();                      // the ONLY DOM node skinHeadless added
+        },
+    };
+    } catch (err) {
+        // A phase-2 step threw (realistically recipe.init or read). Unwind ONLY what
+        // was acquired, reverse order, each flag-guarded. recipe.destroy is NOT
+        // called (init did not complete). Re-throw the ORIGINAL error.
+        if (removeTick) removeTick();
+        if (tickerAcquired) releaseTicker();
+        if (moConnected) mo.disconnect();
+        if (acCreated) ac.abort();
+        if (canvasAppended) canvas.remove();
+        throw err;
+    }
+}
+
 // =========================================================
 //  mountUIFXGroup -- The third mount mode (N native elements, one canvas)
 // =========================================================