@zakkster/lite-ui-fx 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -5,6 +5,75 @@ All notable changes to `@zakkster/lite-ui-fx` are documented here.
 The format follows Keep a Changelog; this project adheres to Semantic
 Versioning.
 
+## [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
+
+none
+
+### Removed
+
+none
+
+## [1.9.1] -- 2026-09-07
+
+Patch: a rendering fix for the ReactionPicker recipe.
+
+### Added
+
+none
+
+### Changed
+
+- demo (not shipped in the package): the `passwordStrength` showcase input is
+  seeded with a weak value (`abc`) instead of an already-maximal one, so typing
+  visibly moves the strength meter. The recipe itself was unchanged and correct.
+
+### Fixed
+
+- ReactionPicker: the emoji faces inherited the circle's translucent `fillStyle`
+  (0.04 alpha at rest), so a colour glyph rendered at 4% opacity and the faces
+  were invisible until hover. An opaque fill (`colors[i]`) is now set before each
+  glyph; all five faces render at rest, and hover still inflates and highlights
+  the selected one. One precomputed array read per glyph -- the frame path stays
+  zero-allocation (torture alloc = 0.8759765625 B/op, unchanged).
+
+### Removed
+
+none
+
 ## [1.9.0] -- 2026-09-07
 
 Grouped controls (roadmap U7): a third mount mode for a control that is N native

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 four E1 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`). See [0008](decisions/0008-headless-skins.md).
+
 ### The recipe registry
 
 ```js
@@ -348,6 +376,7 @@ 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).
 
 ---
 

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.0';
+export const VERSION = '1.10.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)
 // =========================================================

package/UIFXHeadless.d.ts

@@ -0,0 +1,23 @@
+// UIFXHeadless.d.ts -- types for the ./headless subpath (E1, decisions/0008).
+// Curates the headless-skin surface: skinHeadless (the mount adapter, in the
+// controller) + the skin family and its sibling registry (in the recipes module).
+
+export { skinHeadless } from './UIFXController';
+export type {
+    SkinOptions,
+    SkinInstance,
+    HeadlessSkinRecipe,
+    HeadlessSkinRecipeFactory,
+    HeadlessSkinDescriptor,
+} from './UIFXController';
+
+export {
+    SwitchSkin,
+    SliderSkin,
+    ProgressSkin,
+    RatingSkin,
+    HEADLESS_SKINS,
+    SKIN_META,
+    SKIN_NAMES,
+} from './UIFXRecipes';
+export type { SkinMeta } from './UIFXRecipes';

package/UIFXHeadless.js

@@ -0,0 +1,23 @@
+// UIFXHeadless.js -- the ./headless subpath (E1, decisions/0008).
+//
+// Curates the headless-skin surface: skinHeadless (the mount adapter, which lives
+// with the other mounts in UIFXController.js) + the skin family and its sibling
+// registry (in UIFXRecipes.js). Importing one skin tree-shakes the rest
+// (sideEffects:false).
+//
+// @zakkster/lite-headless is a COMPOSE-TARGET, never a dependency: this module (and
+// the whole package) imports it nowhere. skinHeadless couples to a primitive ONLY
+// through the painted-attribute contract (its docs/CSS_CONTRACT.md) that the skin's
+// `headless.read` parses -- so ./headless works against any lite-headless version
+// honouring that contract.
+
+export { skinHeadless } from './UIFXController.js';
+export {
+    SwitchSkin,
+    SliderSkin,
+    ProgressSkin,
+    RatingSkin,
+    HEADLESS_SKINS,
+    SKIN_META,
+    SKIN_NAMES,
+} from './UIFXRecipes.js';

package/UIFXRecipes.d.ts

@@ -1,10 +1,11 @@
 import type {
     UIFXRecipe, UIFXInstance, MountOptions,
     UIFXGroupRecipe, GroupOptions, UIFXGroupInstance, DecorateInstance,
+    HeadlessSkinRecipe,
 } from './UIFXController';
 
 // ===========================================================
-//  RECIPE OPTIONS + FACTORIES (all 56)
+//  RECIPE OPTIONS + FACTORIES (all 57)
 // ===========================================================
 
 /**
@@ -272,7 +273,7 @@ export declare function mountRecipe(
 ): UIFXInstance | UIFXGroupInstance | DecorateInstance;
 
 // ===========================================================
-//  DEFAULT EXPORT -- combined all-56 namespace
+//  DEFAULT EXPORT -- combined all-57 namespace
 // ===========================================================
 
 declare const UIFXAllRecipes: {
@@ -335,3 +336,30 @@ declare const UIFXAllRecipes: {
     SuccessBloom: typeof SuccessBloom;
 };
 export default UIFXAllRecipes;
+
+// ===========================================================
+//  HEADLESS SKINS (E1, decisions/0008)
+//  A sibling registry of RECIPES/RECIPE_META: skins are driven by skinHeadless
+//  (a handle + host), never by mountRecipe (a container), so they are kept
+//  separate and the 57-recipe count is unchanged.
+// ===========================================================
+
+export declare function SwitchSkin(options?: RecipeOptions): HeadlessSkinRecipe;
+export declare function SliderSkin(options?: RecipeOptions): HeadlessSkinRecipe;
+export declare function ProgressSkin(options?: RecipeOptions): HeadlessSkinRecipe;
+export declare function RatingSkin(options?: RecipeOptions): HeadlessSkinRecipe;
+
+/** A headless-skin meta row. `primitive` names the lite-headless primitive the
+ *  skin is designed to paint. */
+export interface SkinMeta {
+    id: string;
+    name: string;
+    primitive: string;
+    themeable: boolean;
+    motionSafe: boolean;
+}
+
+/** id -> skin factory (null-prototype). Driven by skinHeadless, never mountRecipe. */
+export declare const HEADLESS_SKINS: Record<string, (options?: RecipeOptions) => HeadlessSkinRecipe>;
+export declare const SKIN_META: SkinMeta[];
+export declare const SKIN_NAMES: readonly string[];

package/UIFXRecipes.js

@@ -2571,8 +2571,14 @@ export function ReactionPicker(o = {}) {
                 c.fillStyle=active?colors30[i]:'rgba(255,255,255,.04)';
                 c.beginPath();c.arc(cx,cy-sizes[i]+10,sizes[i],0,PI2);c.fill();
 
-                // Emoji face (simplified) -- font from a const-string LUT
+                // Emoji face -- font from a const-string LUT. Set an OPAQUE fill
+                // first: the circle's fillStyle above is translucent (4% at rest),
+                // and a colour glyph inherits that alpha, so without this the faces
+                // are invisible until hover. colors[i] keeps a mono-emoji fallback
+                // tinted per reaction; a colour-emoji font ignores the hue and only
+                // takes the full alpha. Precomputed array read -- zero alloc.
                 c.font=FONTS[Math.round(sizes[i]*1.2)]||FONTS[48];c.textAlign='center';c.textBaseline='middle';
+                c.fillStyle=colors[i];
                 c.fillText(emojis[i],cx,cy-sizes[i]+10);
             }
 
@@ -3428,3 +3434,206 @@ export function mountRecipe(container, id, options) {
     return mountUIFX(container, type, factory, mountOptions);
 }
 
+// ===========================================================
+//  HEADLESS SKINS (E1, decisions/0008)
+//  A skin is an ordinary recipe PLUS a `headless` descriptor:
+//    { attrs: string[], read(host, handle, state) }
+//  skinHeadless (controller) observes `attrs` on the lite-headless primitive's
+//  painted element and calls read() at EVENT time to parse the painted state into
+//  preallocated state slots. Skins live in their OWN registry (HEADLESS_SKINS /
+//  SKIN_META), NOT RECIPES/RECIPE_META: a skin needs a handle + host, not a
+//  container, so it does not fit mountRecipe. The 57-recipe count is unchanged.
+// ===========================================================
+
+// Painted-attribute readers (EVENT time only -- never a per-frame call, so
+// getAttribute/parseFloat here are off the hot path). A boolean is PRESENT with any
+// value except the string "false" (handles presence-booleans like data-disabled and
+// value-booleans like the switch's data-checked="true"; decisions/0008 decision 3).
+function _skinBool(el, name) {
+    if (!el.hasAttribute(name)) return false;
+    return el.getAttribute(name) !== 'false';
+}
+function _ariaTrue(el, name) { return el.getAttribute(name) === 'true'; }
+function _skinNum(el, name, def) {
+    const v = el.getAttribute(name);
+    if (v == null) return def;
+    const n = parseFloat(v);
+    return n === n ? n : def;   // n===n rejects NaN without an isNaN call
+}
+
+/** Switch skin -- a sliding track+knob driven by the primitive's data-checked /
+ *  aria-checked. Zero per-frame alloc: const colors, globalAlpha, one eased scalar. */
+export function SwitchSkin(o = {}) {
+    const P = resolveTheme(o, { accent: '#38bdf8', dim: '#3a3a4a', dim2: '#e2e2f0' });
+    let t = 0;   // animated 0..1 toward the checked state
+    return {
+        headless: {
+            attrs: ['data-checked', 'aria-checked', 'data-disabled', 'aria-disabled'],
+            read(host, handle, st) {
+                st.toggled = _skinBool(host, 'data-checked') || _ariaTrue(host, 'aria-checked')
+                    || (handle && typeof handle.isChecked === 'function' ? !!handle.isChecked() : false);
+                st.disabled = _skinBool(host, 'data-disabled') || _ariaTrue(host, 'aria-disabled');
+            },
+        },
+        tick(c, dt, now, st) {
+            const w = st.w, h = st.h, r = h / 2;
+            const k = dt * 12; t += ((st.toggled ? 1 : 0) - t) * (k > 1 ? 1 : k);
+            c.globalAlpha = st.disabled ? 0.4 : 1;
+            c.fillStyle = st.toggled ? P.accent : P.dim;
+            roundRect(c, 0, 0, w, h, r); c.fill();
+            const kx = r + t * (w - h);
+            c.fillStyle = P.dim2;
+            c.beginPath(); c.arc(kx, r, r - 3, 0, PI2); c.fill();
+            c.globalAlpha = 1;
+            if (st.focused) fr(c, w, h, r);
+        },
+    };
+}
+
+/** Slider skin -- rail + fill + thumb, driven by aria-valuenow/min/max; the thumb
+ *  pulses while data-dragging is painted. */
+export function SliderSkin(o = {}) {
+    const P = resolveTheme(o, { accent: '#fbbf24', dim: '#9999b8', dim2: '#e2e2f0' });
+    let dv = 0;   // displayed value, eased toward st.val
+    return {
+        headless: {
+            attrs: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax', 'data-disabled', 'data-dragging'],
+            read(host, handle, st) {
+                const mn = _skinNum(host, 'aria-valuemin', 0);
+                const mx = _skinNum(host, 'aria-valuemax', 100);
+                const nw = _skinNum(host, 'aria-valuenow', mn);
+                const span = mx - mn;
+                let v = span > 0 ? (nw - mn) / span : 0;
+                st.val = v < 0 ? 0 : (v > 1 ? 1 : v);
+                st.active = _skinBool(host, 'data-dragging');
+                st.disabled = _skinBool(host, 'data-disabled');
+            },
+        },
+        tick(c, dt, now, st) {
+            const w = st.w, cy = st.h / 2;
+            const k = dt * 10; dv += (st.val - dv) * (k > 1 ? 1 : k);
+            c.globalAlpha = st.disabled ? 0.2 : 0.4;
+            c.fillStyle = P.dim; roundRect(c, 0, cy - 2, w, 4, 2); c.fill();
+            const fx = dv * w;
+            c.globalAlpha = st.disabled ? 0.4 : 1;
+            c.fillStyle = P.accent; roundRect(c, 0, cy - 2, fx > 0 ? fx : 0, 4, 2); c.fill();
+            const tr = st.active ? 8 : 6;
+            c.fillStyle = P.dim2;
+            c.beginPath(); c.arc(fx, cy, tr, 0, PI2); c.fill();
+            if (st.active) {
+                c.globalAlpha = 0.3; c.fillStyle = P.accent;
+                c.beginPath(); c.arc(fx, cy, tr + 5, 0, PI2); c.fill();
+            }
+            c.globalAlpha = 1;
+            if (st.focused) fr(c, w, st.h, cy);
+        },
+    };
+}
+
+/** Progress skin -- a value ring (aria-valuenow/max) with a percent label; an
+ *  indeterminate sweep when data-loading, a full accent ring when data-complete. */
+export function ProgressSkin(o = {}) {
+    const P = resolveTheme(o, { accent: '#6ee7b6', accent2: '#a78bfa', dim: '#e2e2f0' });
+    const FONT = pickFont(o, "700 14px 'JetBrains Mono',monospace");
+    let dv = 0;     // displayed value
+    let spin = 0;   // indeterminate sweep phase
+    return {
+        headless: {
+            attrs: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax', 'data-complete', 'data-loading'],
+            read(host, handle, st) {
+                const mn = _skinNum(host, 'aria-valuemin', 0);
+                const mx = _skinNum(host, 'aria-valuemax', 100);
+                const nw = _skinNum(host, 'aria-valuenow', mn);
+                const span = mx - mn;
+                let v = span > 0 ? (nw - mn) / span : 0;
+                st.val = v < 0 ? 0 : (v > 1 ? 1 : v);
+                st.complete = _skinBool(host, 'data-complete');
+                st.indeterminate = _skinBool(host, 'data-loading');
+            },
+        },
+        tick(c, dt, now, st) {
+            const cx = st.w / 2, cy = st.h / 2, R = Math.min(cx, cy) - 6, lw = 6;
+            c.strokeStyle = P.dim; c.globalAlpha = 0.15; c.lineWidth = lw;
+            c.beginPath(); c.arc(cx, cy, R, 0, PI2); c.stroke();
+            c.globalAlpha = 1;
+            if (st.indeterminate && !st.complete) {
+                spin += dt * 3;
+                c.strokeStyle = P.accent; c.lineWidth = lw;
+                c.beginPath(); c.arc(cx, cy, R, spin, spin + 1.6); c.stroke();
+            } else {
+                const target = st.complete ? 1 : st.val;
+                const k = dt * 6; dv += (target - dv) * (k > 1 ? 1 : k);
+                const a = -Math.PI / 2, ea = a + dv * PI2;
+                c.strokeStyle = st.complete ? P.accent : P.accent2; c.lineWidth = lw;
+                c.beginPath(); c.arc(cx, cy, R, a, ea); c.stroke();
+                c.fillStyle = P.dim; c.font = FONT; c.textAlign = 'center'; c.textBaseline = 'middle';
+                c.fillText(PCT[Math.round(dv * 100)], cx, cy);
+            }
+            if (st.focused) fr(c, st.w, st.h, st.h / 2);
+        },
+    };
+}
+
+/** Rating skin -- N bubbles (count from aria-valuemax, bounded) filled to
+ *  aria-valuenow/max. Fixed-count loop, no per-frame allocation. */
+export function RatingSkin(o = {}) {
+    const P = resolveTheme(o, { accent: '#f472b6', dim: '#3a3a4a' });
+    let dv = 0;   // animated filled count
+    return {
+        headless: {
+            attrs: ['aria-valuenow', 'aria-valuemax', 'data-disabled'],
+            read(host, handle, st) {
+                const mx = _skinNum(host, 'aria-valuemax', 5);
+                const nw = _skinNum(host, 'aria-valuenow', 0);
+                let n = mx > 0 ? (mx | 0) : 5;
+                st.count = n > 10 ? 10 : n;
+                let v = mx > 0 ? nw / mx : 0;
+                st.val = v < 0 ? 0 : (v > 1 ? 1 : v);
+                st.disabled = _skinBool(host, 'data-disabled');
+            },
+        },
+        tick(c, dt, now, st) {
+            const n = st.count > 0 ? st.count : 5;
+            const k = dt * 12; dv += (st.val * n - dv) * (k > 1 ? 1 : k);
+            const cy = st.h / 2;
+            const gap = st.w / n;
+            const rad = (gap < st.h ? gap : st.h) * 0.32;
+            const base = st.disabled ? 0.4 : 1;
+            for (let i = 0; i < n; i++) {
+                const cx = gap * (i + 0.5);
+                const fillAmt = dv - i;
+                c.globalAlpha = base * 0.35; c.fillStyle = P.dim;
+                c.beginPath(); c.arc(cx, cy, rad, 0, PI2); c.fill();
+                if (fillAmt > 0) {
+                    c.globalAlpha = base * (fillAmt > 1 ? 1 : fillAmt); c.fillStyle = P.accent;
+                    c.beginPath(); c.arc(cx, cy, rad, 0, PI2); c.fill();
+                }
+            }
+            c.globalAlpha = 1;
+            if (st.focused) fr(c, st.w, st.h, st.h / 2);
+        },
+    };
+}
+
+/**
+ * The headless-skin registry -- a SIBLING of RECIPES, not part of it (decisions/
+ * 0008 decision 4). id -> factory (null-prototype), the meta rows a picker/demo
+ * iterates, and the frozen id list. Each skin is driven by skinHeadless with a
+ * lite-headless handle + host, never by mountRecipe.
+ */
+export const HEADLESS_SKINS = Object.assign(Object.create(null), {
+    switchSkin: SwitchSkin,
+    sliderSkin: SliderSkin,
+    progressSkin: ProgressSkin,
+    ratingSkin: RatingSkin,
+});
+
+export const SKIN_META = [
+    { id: 'switchSkin', name: 'Switch Skin', primitive: 'switch', themeable: true, motionSafe: false },
+    { id: 'sliderSkin', name: 'Slider Skin', primitive: 'slider', themeable: true, motionSafe: false },
+    { id: 'progressSkin', name: 'Progress Skin', primitive: 'progress', themeable: true, motionSafe: false },
+    { id: 'ratingSkin', name: 'Rating Skin', primitive: 'rating', themeable: true, motionSafe: false },
+];
+
+export const SKIN_NAMES = Object.freeze(Object.keys(HEADLESS_SKINS));
+

package/llms.txt

@@ -1,7 +1,7 @@
 # @zakkster/lite-ui-fx
 > Canvas-hijacked UI components with pluggable recipe system. 57 built-in recipes.
 
-VERSION 1.9.0
+VERSION 1.10.0
 
 ## Install
 npm i @zakkster/lite-ui-fx
@@ -87,6 +87,34 @@ driven    // U5 host clock: boolean; true = no ticker/RAF, the host calls instan
 // padding, disabled, seed, colors, theme, text, font, ticker, driven. The hijack-
 // only keys (value/checked/knobMode/announce) throw -- a group uses index, not value.
 
+## Mount -- HEADLESS SKIN mode (E1): paint a lite-headless primitive
+// skinHeadless: a FOURTH mount adapter. It places a canvas over a @zakkster/lite-
+// headless primitive and drives a recipe from the primitive's PAINTED state
+// attributes (its docs/CSS_CONTRACT.md) -- lite-ui-fx paints, lite-headless behaves.
+// Arm's-length: couples through the attribute contract, NEVER an import, so
+// lite-headless is never a dependency. Structurally a decoration: host byte-
+// identical, one overlay canvas + one MutationObserver removed on destroy; the
+// lite-headless handle is never destroyed (the caller owns it).
+import { skinHeadless, SwitchSkin, SliderSkin, ProgressSkin, RatingSkin } from '@zakkster/lite-ui-fx/headless';
+import { HEADLESS_SKINS, SKIN_META, SKIN_NAMES } from '@zakkster/lite-ui-fx/headless';
+const skin = skinHeadless(handle, SwitchSkin, { host: switchThumbEl, theme });
+skin.el          // the skinned host (unchanged)
+skin.canvas      // the overlay (the only DOM node added)
+skin.state       // read-only; driven by the observer from painted attrs
+skin.tick(dtMs)  // driven mode only
+skin.destroy()   // remove overlay + observer + listeners; host + handle untouched
+// A skin is an ordinary recipe PLUS a descriptor: recipe.headless = { attrs:string[],
+//   read(host, handle, state) }. skinHeadless observes `attrs` and calls read() at
+//   EVENT time (never per frame) to parse painted state into preallocated slots.
+// options: { host(REQUIRED), padding, seed, colors, theme, text, font, ticker, driven };
+//   hijack-only keys throw. setValue/setChecked throw (a skin reflects the primitive).
+// E1 skins (SKIN_META, a registry SEPARATE from RECIPES -- the 57-recipe count is
+//   unchanged): SwitchSkin (data-checked/aria-checked), SliderSkin (aria-valuenow/
+//   min/max + data-dragging), ProgressSkin (aria-valuenow/max + data-complete/
+//   data-loading), RatingSkin (aria-valuenow/max over N items). Each themeable, born
+//   zero-alloc + t6-gated. A painted attr is truthy when PRESENT with any value but
+//   "false" (handles boolean data-disabled and value data-checked="true").
+
 ## Host clock (U5) -- three mutually-exclusive modes, both mount modes
 // default (neither option): the shared ref-counted ticker -- one RAF for all
 //   components, byte-identical to earlier versions.
@@ -187,9 +215,9 @@ 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 56 recipes honour { colors, theme:{light,mid,dark}, text, font },
+- Themeable: all 57 recipes honour { colors, theme:{light,mid,dark}, text, font },
   resolved once in init (zero per-frame alloc). RECIPE_META.themeable is true for
-  all 56. A bare mount is byte-identical to pre-theming. Shipped palettes + APCA
+  all 57. 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).
 - U5 host clock: mount { ticker } to ride a caller-supplied lite-ticker (destroy
@@ -218,3 +246,11 @@ See UIFX-RECIPE-GUIDE.md (included in package).
   selects programmatically (fires onSelect once, no focus steal). Additive: the
   single-element API is byte-identical; the four vol.3 fakes (PillTabs/Stepper/
   RadioOrbit/BubbleRating) re-home to real group types, SegmentedSlide is new.
+- E1 headless skins (./headless subpath, skinHeadless): a FOURTH mount adapter that
+  paints a @zakkster/lite-headless primitive by OBSERVING its painted state
+  attributes (one MutationObserver; parsed at event time, never per frame) --
+  lite-ui-fx paints, lite-headless behaves. lite-headless is a compose-target, NEVER
+  a dependency (the package imports it nowhere). 4 skins (switch/slider/progress/
+  rating) live in a registry (HEADLESS_SKINS/SKIN_META) SEPARATE from the 57 recipes;
+  each themeable + zero per-frame alloc (t6-gated). setValue/setChecked throw (a skin
+  reflects the primitive); destroy leaves the host + handle untouched. See 0008.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zakkster/lite-ui-fx",
-  "version": "1.9.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.",
+  "version": "1.10.0",
+  "description": "Canvas-hijacked UI components with a pluggable recipe system: 57 built-in recipes across toggles, buttons, sliders, knobs, loaders, checkboxes, counters and ratings, in three mount modes (hijack, decorate, grouped controls) plus a lite-headless skin adapter.",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
   "license": "MIT",
   "type": "module",
@@ -16,6 +16,10 @@
     "./recipes": {
       "import": "./UIFXRecipes.js",
       "types": "./UIFXRecipes.d.ts"
+    },
+    "./headless": {
+      "import": "./UIFXHeadless.js",
+      "types": "./UIFXHeadless.d.ts"
     }
   },
   "files": [
@@ -23,6 +27,8 @@
     "UIFXController.d.ts",
     "UIFXRecipes.js",
     "UIFXRecipes.d.ts",
+    "UIFXHeadless.js",
+    "UIFXHeadless.d.ts",
     "UIFX-RECIPE-GUIDE.md",
     "llms.txt",
     "CHANGELOG.md",