@zakkster/lite-ui-fx 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,49 @@ All notable changes to `@zakkster/lite-ui-fx` are documented here.
 The format follows Keep a Changelog; this project adheres to Semantic
 Versioning.
 
+## [1.6.0] -- 2026-09-07
+
+Decorate mode (U4b, the second half of roadmap U4). A second public mount mode
+alongside the hijack `mountUIFX`: `decorateUIFX` positions a canvas AROUND an
+existing visible element instead of hijacking it. Additive: a bare `mountUIFX`
+mount is byte-identical to 1.5.0; 53 -> 56 recipes.
+
+### Added
+
+- `decorateUIFX(el, recipeFactory, options)`: a canvas overlay AROUND a live
+  element -- no `opacity:0`, no reparent. The overlay is a sibling placed from the
+  host's offset box and removed on `destroy()`, so the host is byte-identical
+  before and after (additive-only). Recipe `state` is wired from the host's own
+  events; for a form-control host `state.text` and `state.valid` mirror `el.value`
+  and `el.validity`, read at event time (never per frame). `setValue`/`setChecked`
+  are hijack-only and throw. Options are a subset (`padding`, `seed`, `colors`,
+  `theme`, `text`, `font`); the hijack-only keys throw in decorate mode.
+- Three decorate recipes, born themed and t3-gated: `FocusHalo`, `ErrorShake`,
+  `SuccessBloom` (generic form feedback, reading `state.focused` / `state.valid`).
+  Registered in `RECIPES` / `RECIPE_META` (type `'decorate'`) / the default export
+  / a new `UIFXRecipes5` barrel.
+- `'decorate'` as a `RECIPE_META.type` routing tag: `mountRecipe(el, id)` routes a
+  decorate recipe to `decorateUIFX`. `VALID_META_TYPES` gains exactly this one
+  non-`UIType` tag; `mountUIFX` still rejects it (the two paths cannot cross).
+- Optional `state.text` / `state.valid` fields (decorate mode only). TypeScript
+  `DecorateOptions`, `DecorateInstance`, and `decorateUIFX` in the d.ts.
+- `decisions/0004-decorate-mode.md`; decorate coverage across the suite: t0 host
+  byte-identical DOM diff + a t9 `decorate-host-mutation` control, t1 fail-closed +
+  degenerate sweep, t2 A14-A16 (state wiring, host untouched, non-input host), t3
+  zero-alloc churn, t5 decorate on the shared ticker. 164 -> 177 node:test tests.
+
+### Changed
+
+- `PasswordStrength` and `TypewriterField` re-homed from their U4a-era fake types
+  (slider / toggle) onto decorate mode (`RECIPE_META.type` `'decorate'`). Unlike
+  the U4a re-homes these are behaviour ports: they now read the live host input --
+  PasswordStrength derives strength from `state.text` (zero-alloc `charCodeAt`
+  scan, recomputed only on change); TypewriterField animates an underline that
+  grows with the typed text (no `measureText`). Both stay `themeable`.
+- RECIPE_META covers 56 recipes; `themeable` true for all 56, `motionSafe` false
+  for all 56. All 56 stay zero-GC under the t3 frame-alloc gate (default AND
+  themed). `mountUIFX` and every hijack mount are unchanged.
+
 ## [1.5.0] -- 2026-09-07
 
 New native element types (U4a, the first half of roadmap U4). Vol.3 faked

package/README.md

@@ -21,7 +21,7 @@ https://cdpn.io/pen/debug/yyaPKpB
 ## Live Demo (UI-FX vol3.)
 https://cdpn.io/pen/debug/YPGEaYY
 
-**53 recipes** across UI element categories:
+**56 recipes** across UI element categories:
 
 - **Toggles** -- Swarm, Liquid, Neon Pulse, Pendulum, Circuit, Lightning, DNA
 - **Buttons** -- Magnetic, Shatter, Confetti, Glitch, Heartbeat, Breathing, Ink Splash, Pixel Dissolve, Firework
@@ -29,18 +29,19 @@ https://cdpn.io/pen/debug/YPGEaYY
 - **Knobs** -- Volume dial, Compass needle
 - **Progress** -- Ring, Battery, Signal meter, Liquid Fill
 - **Controls** -- Pill tabs, Stepper, Radio orbit
-- **Indicators** -- Password strength, Water level, Heat map
+- **Indicators** -- Water level, Heat map
 - **Mood** -- Day/night, Reaction picker, Notification bell
-- **Feedback** -- Typewriter, Sound wave, Upload progress
+- **Feedback** -- Sound wave, Upload progress
 - **Fun** -- Scratch reveal, Timer countdown, Pull refresh
 - **Checkboxes** -- Ripple, Morph (X to check), Tick Draw, Indeterminate Scan
 - **Loaders** -- Orbit planets, DNA helix
 - **Counters** -- Flame heat, Glitch signal
 - **Rating** -- Bubble inflate
+- **Form (decorate)** -- Focus halo, Error shake, Success bloom, Password strength, Typewriter field (mounted via `decorateUIFX`, around a live element)
 
 Every recipe is zero-GC, uses `dt`-based animation, and includes accessibility indicators (focus rings, state labels).
 
-All 53 recipes ship in the package on the `./recipes` subpath -- versioned,
+All 56 recipes ship in the package on the `./recipes` subpath -- versioned,
 typed, and tree-shakeable. With `sideEffects: false`, importing one recipe pulls
 in only that recipe, so a controller-only install stays tiny.
 
@@ -65,7 +66,7 @@ Part of the [@zakkster/lite-*](https://www.npmjs.com/org/zakkster) ecosystem.
 npm i @zakkster/lite-ui-fx
 ```
 
-> The 53 recipes ship in the same package on the `./recipes` subpath and
+> The 56 recipes ship in the same package on the `./recipes` subpath and
 > tree-shake, so importing one adds only that one.
 
 
@@ -97,7 +98,7 @@ instance.destroy();
 // Controller (always needed)
 import { mountUIFX, UIType } from '@zakkster/lite-ui-fx';
 
-// All 53 recipes ship on the ./recipes subpath (tree-shakeable) -- import by name:
+// All 56 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';
@@ -158,6 +159,36 @@ Returns `{ el, canvas, wrapper, state, setValue(v), setChecked(b), destroy() }`.
 - `setChecked(b)` -- TOGGLE/CHECKBOX: set checked (updates the element +
   `state.toggled`, fires `onToggle` once).
 
+### `decorateUIFX(el, recipeFactory, options?)` -- the second mount mode
+
+Where `mountUIFX` **hijacks** (creates a hidden native element under a canvas),
+`decorateUIFX` **decorates**: it positions a canvas *around* an existing, visible
+element without hijacking it -- no `opacity:0`, no reparenting. The overlay is a
+sibling placed from the host's offset box and removed on `destroy()`, so the host
+is byte-identical before and after. Recipe `state` is wired from the host's own
+events; for a form-control host, `state.text` and `state.valid` mirror `el.value`
+and `el.validity` (read at event time, never per frame). This is the honest home
+for a decoration over a real input.
+
+```javascript
+import { decorateUIFX } from '@zakkster/lite-ui-fx';
+import { PasswordStrength } from '@zakkster/lite-ui-fx/recipes';
+
+const input = document.querySelector('#password');
+const deco = decorateUIFX(input, PasswordStrength, { theme });
+// ... input stays fully usable; the meter tracks what the user types ...
+deco.destroy(); // removes ONLY the overlay; the input is untouched
+```
+
+`options` is a subset: `padding`, `seed`, `colors`, `theme`, `text`, `font`. The
+hijack-only keys (`width`/`height`/`value`/`checked`/`disabled`/`knobMode`/
+`announce`/`label`) throw in decorate mode. Returns
+`{ el, canvas, state, setValue, setChecked, destroy() }`, where `setValue` and
+`setChecked` are hijack-only and throw (a decoration reflects the host; it does
+not drive it). Built-in decorate recipes: `FocusHalo`, `ErrorShake`,
+`SuccessBloom`, `PasswordStrength`, `TypewriterField` (`RECIPE_META.type` =
+`'decorate'`, so `mountRecipe(el, id)` routes them here automatically).
+
 ### Element Types
 
 | Type | Native Element | Recipe Hooks | Key State |
@@ -168,6 +199,10 @@ Returns `{ el, canvas, wrapper, state, setValue(v), setChecked(b), destroy() }`.
 | `UIType.CHECKBOX` | `<input type="checkbox">` (no `role=switch`) | `onToggle(checked)` | `state.toggled`, `state.indeterminate` |
 | `UIType.PROGRESS` | `<progress>` (non-interactive) | (driven by `setValue`) | `state.val` (0-1) |
 | `UIType.KNOB` | `<input type="range">` | `onDrag(val, velocity)` | `state.val` (0-1) |
+| *(decorate)* | none -- a canvas AROUND a live host (`decorateUIFX`) | host events -> state | `state.focused`, `state.text`, `state.valid` |
+
+*(decorate)* is a mount mode, not a `UIType`: it creates no native element. A recipe
+with `RECIPE_META.type === 'decorate'` is mounted via `decorateUIFX`.
 
 ### State Object (provided to `tick()` every frame)
 
@@ -184,6 +219,8 @@ Returns `{ el, canvas, wrapper, state, setValue(v), setChecked(b), destroy() }`.
     h: number;           // Element height
     padding: number;     // Canvas padding
     dpr: number;         // Device pixel ratio
+    text?: string;       // decorate mode only: the host value string
+    valid?: boolean;     // decorate mode only: the host validity
 }
 ```
 
@@ -194,7 +231,7 @@ Returns `{ el, canvas, wrapper, state, setValue(v), setChecked(b), destroy() }`.
 | Framer Motion | ~45 KB | React HOC | 0 | Via React | `npm i framer-motion` |
 | GSAP | ~25 KB | Timeline | 0 | Manual | `npm i gsap` |
 | Lottie | ~55 KB | JSON animation | After Effects | Manual | `npm i lottie-web` |
-| **lite-ui-fx** | **< 5 KB** | **Canvas hijack** | **53 built-in** | **Native + visual** | **`npm i @zakkster/lite-ui-fx`** |
+| **lite-ui-fx** | **< 5 KB** | **Canvas hijack + decorate** | **56 built-in** | **Native + visual** | **`npm i @zakkster/lite-ui-fx`** |
 
 ## Writing Custom Recipes
 
@@ -227,6 +264,7 @@ export function MyButton() {
 Full TypeScript declarations are included for:
 
 - `mountUIFX`
+- `decorateUIFX` (+ `DecorateOptions`, `DecorateInstance`)
 - `UIType`
 - `UIFXState`
 - `UIFXPointer`

package/UIFX-RECIPE-GUIDE.md

@@ -63,12 +63,16 @@ The controller provides this every frame:
     hover: boolean,     // Pointer is inside the element
     active: boolean,    // Pointer is pressed down
     focused: boolean,   // Element has keyboard focus
-    toggled: boolean,   // Checkbox checked state (toggles)
-    val: number,        // 0--1 slider value (sliders)
+    toggled: boolean,   // Checkbox checked state (toggles/checkboxes)
+    indeterminate: boolean, // CHECKBOX only: native indeterminate (setValue(null))
+    val: number,        // 0--1 value (sliders/knobs/progress)
     w: number,          // Element width in CSS pixels
     h: number,          // Element height
     padding: number,    // Canvas overflow padding
     dpr: number,        // Device pixel ratio
+    // Decorate mode only (decorateUIFX): the live host's value + validity.
+    text: string,       // the host form-control's value string ('' if none)
+    valid: boolean,     // the host's validity (el.validity.valid, else true)
 }
 ```
 
@@ -121,13 +125,65 @@ const instance = mountUIFX(
 instance.destroy();
 ```
 
-## Three Element Types
+## Element Types & Mount Modes
+
+`mountUIFX` HIJACKS -- it creates one of six native elements (opacity:0) under the
+canvas:
 
 | Type | Native Element | Recipe Gets | Key State |
 |------|----------------|-------------|-----------|
 | `UIType.TOGGLE` | `<input type="checkbox" role="switch">` | `onToggle(checked)` | `state.toggled` |
 | `UIType.BUTTON` | `<button>` | `onClick(x, y, state)` | `state.active` |
 | `UIType.SLIDER` | `<input type="range">` | `onDrag(val, velocity)` | `state.val` (0--1) |
+| `UIType.CHECKBOX` | `<input type="checkbox">` (no `role=switch`) | `onToggle(checked)` | `state.toggled`, `state.indeterminate` |
+| `UIType.PROGRESS` | `<progress>` (non-interactive) | (driven by `setValue`) | `state.val` |
+| `UIType.KNOB` | `<input type="range">` | `onDrag(val, velocity)` | `state.val`, `knobMode` |
+
+## Decorate-Mode Recipes (a canvas AROUND a live element)
+
+`decorateUIFX(el, factory, options)` is the SECOND mount mode: instead of creating
+a hidden element, it positions a canvas around an EXISTING, visible element (a real
+`<input>`, a button, any element). Same recipe interface, same coordinate system --
+`(0,0)` is the host's top-left, `state.w/h` are the host's size -- but three rules
+differ, and breaking them is caught by the torture t0 decorate DOM-diff:
+
+1. **Never touch the host.** A decoration paints ONLY its overlay canvas. Do not
+   write `el.style`, set an attribute, or read/move the host in `init`/`tick`. The
+   host must be byte-identical after `destroy()` (additive-only). The controller
+   never sets `opacity:0` and never reparents the host -- neither may your recipe.
+2. **Read host content from `state`, at frame time, allocation-free.** For a
+   form-control host, `state.text` (the value string) and `state.valid` (validity)
+   are updated by the controller at EVENT time (input/change/invalid) -- never per
+   frame. Your `tick` reads them; scan `state.text` with `charCodeAt` (no allocating
+   string ops), and edge-detect `state.valid` against a closure-cached previous.
+   There is NO new hook: a decoration reacts by polling `state` in `tick`.
+3. **`setValue`/`setChecked` are hijack-only.** A decoration reflects the host; it
+   does not drive it. Both throw in decorate mode.
+
+```javascript
+import { decorateUIFX } from './UIFXController.js';
+// A decoration reads state.focused / state.valid / state.text; it never draws the
+// host's own text (the real element already shows it).
+export function Underline() {
+    let fill = 0;
+    return {
+        tick(ctx, dt, now, state) {
+            const len = (state.text || '').length;           // number, no alloc
+            fill += ((len ? Math.min(len / 24, 1) : 0) - fill) * dt * 8;
+            ctx.strokeStyle = state.focused ? '#6ee7b6' : '#556';
+            ctx.lineWidth = 2;
+            ctx.beginPath();
+            ctx.moveTo(2, state.h - 3);
+            ctx.lineTo(2 + (state.w - 4) * fill, state.h - 3);
+            ctx.stroke();
+        },
+    };
+}
+const deco = decorateUIFX(document.querySelector('#field'), Underline);
+```
+
+Register a decorate recipe with `RECIPE_META.type: 'decorate'` -- then
+`mountRecipe(el, id)` routes it to `decorateUIFX` automatically.
 
 ## Using @zakkster Libraries in Recipes
 

package/UIFXController.d.ts

@@ -27,6 +27,11 @@ export interface UIFXState {
     h: number;
     padding: number;
     dpr: number;
+    /** Decorate mode only (decorateUIFX): the host form-control's current value.
+     *  Absent for hijack mounts and for a non-form host (then ''). */
+    text?: string;
+    /** Decorate mode only: the host's validity (el.validity.valid, else true). */
+    valid?: boolean;
 }
 
 export interface UIFXPointer {
@@ -86,6 +91,22 @@ export interface MountOptions {
     announce?: boolean;
 }
 
+/**
+ * Options accepted by decorateUIFX. A subset of MountOptions: a decoration
+ * inherits the host's geometry (offset box) and value (read from the host), so
+ * the hijack-only options (width/height/value/checked/disabled/knobMode/announce/
+ * label) are rejected -- passing one throws (fail closed).
+ */
+export interface DecorateOptions {
+    /** 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;
+}
+
 export interface UIFXInstance {
     el: HTMLElement;
     canvas: HTMLCanvasElement;
@@ -117,4 +138,41 @@ export declare function mountUIFX(
     options?: MountOptions
 ): UIFXInstance;
 
+/**
+ * The instance returned by decorateUIFX. Like UIFXInstance but WITHOUT `wrapper`
+ * (there is none -- the overlay is a sibling of the host, not a wrapper around
+ * it), and setValue/setChecked are hijack-only: a decoration reflects the host,
+ * it does not drive it, so both throw.
+ */
+export interface DecorateInstance {
+    /** The decorated host element (unchanged -- decorate never mutates it). */
+    el: HTMLElement;
+    /** The overlay canvas (the only DOM node decorate adds). */
+    canvas: HTMLCanvasElement;
+    state: UIFXState;
+    /** Hijack-only. Throws in decorate mode. */
+    setValue(v?: number | null): void;
+    /** Hijack-only. Throws in decorate mode. */
+    setChecked(b?: boolean): void;
+    /** Remove the overlay + every listener decorate added; the host is left
+     *  byte-identical to before decorate. Idempotent. */
+    destroy(): void;
+}
+
+/**
+ * Decorate an EXISTING visible element with a canvas recipe WITHOUT hijacking it:
+ * no native element is created, opacity is never set, and the host is never
+ * reparented. An overlay canvas is added as a sibling and removed on destroy, so
+ * the host is byte-identical before and after. Recipe state is wired from the
+ * host's own events; for a form-control host, state.text/state.valid mirror
+ * el.value/el.validity (read at event time, never per frame). This is the honest
+ * home for a decoration over a real input (PasswordStrength, TypewriterField) and
+ * for generic form feedback (FocusHalo, ErrorShake, SuccessBloom). See 0004.
+ */
+export declare function decorateUIFX(
+    el: HTMLElement,
+    recipeFactory: RecipeFactory,
+    options?: DecorateOptions
+): DecorateInstance;
+
 export default mountUIFX;

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.5.0';
+export const VERSION = '1.6.0';
 
 // ---------------------------------------------------------
 //  SHARED TICKER (ref-counted, one RAF for all UI components)
@@ -87,6 +87,12 @@ const KNOWN_HOOKS = ['init', 'tick', 'onHover', 'onLeave', 'onClick', 'onToggle'
 const KNOWN_OPTIONS = ['width', 'height', 'padding', 'label', 'value', 'checked', 'disabled', 'seed', 'colors', 'theme', 'text', 'font', 'knobMode', 'announce'];
 const KNOB_MODES = ['rotate', 'vertical'];
 
+// Options valid in decorate mode (decorateUIFX). A canvas AROUND a live element
+// inherits the host's geometry (offset box) and value (read from el), so the
+// hijack-only options (width/height/value/checked/disabled/knobMode/announce/
+// label) are rejected here -- fail closed. Cold: read only at mount.
+const DECORATE_OPTIONS = ['padding', 'seed', 'colors', 'theme', 'text', 'font'];
+
 // Levenshtein edit distance. Cold: only reached on the error path.
 function _editDistance(a, b) {
     const al = a.length;
@@ -695,4 +701,327 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
     }
 }
 
+// =========================================================
+//  decorateUIFX -- The second mount mode (canvas AROUND a live element)
+// =========================================================
+
+/**
+ * Decorate an EXISTING visible element with a canvas recipe, WITHOUT hijacking
+ * it. Unlike mountUIFX this creates no native element, never sets opacity:0, and
+ * never reparents `el`: it adds ONE absolutely-positioned overlay canvas as a
+ * sibling in el.parentNode (placed from el's offset box) plus the listeners it
+ * owns, and on destroy removes exactly those -- the host is byte-identical to
+ * before. Recipe state is wired from el's own events; for a form-control host,
+ * state.text and state.valid mirror el.value / el.validity (read at event time,
+ * never per frame). This is the honest home for a decoration over a real input
+ * (PasswordStrength, TypewriterField) and for generic form feedback (FocusHalo,
+ * ErrorShake, SuccessBloom). See decisions/0004.
+ *
+ * @param {HTMLElement} el            The live element to decorate (stays visible).
+ * @param {Function}    recipeFactory (options) => Recipe object
+ * @param {Object}      [options]     padding, seed, colors, theme, text, font
+ * @returns {{ el, canvas, state, setValue, setChecked, destroy }}
+ */
+export function decorateUIFX(el, recipeFactory, options = {}) {
+    // =====================================================================
+    //  PHASE 1 -- VALIDATION ONLY. No side effect until every check passes
+    //  (fail closed, mirrors mountUIFX): no createElement, no insertBefore,
+    //  no ticker acquire, no recipe.init.
+    // =====================================================================
+
+    // 1. el must be a live, attached DOM element -- we read its offset box and
+    //    hang the overlay off its parent. A detached el has no parentNode to host
+    //    the canvas: an Error, never a silent no-op.
+    if (!el || typeof el.addEventListener !== 'function' ||
+        typeof el.getBoundingClientRect !== 'function') {
+        throw new Error('decorateUIFX: el must be a DOM element');
+    }
+    if (!el.parentNode || typeof el.parentNode.insertBefore !== 'function') {
+        throw new Error('decorateUIFX: el must be attached to the DOM (no parentNode to host the overlay)');
+    }
+
+    // 2. options: decorate accepts a subset. A hijack-only key is a mistake, not a
+    //    silent ignore; a truly unknown key gets a did-you-mean over the decorate
+    //    set. Both fail closed, before any element exists.
+    for (const k in options) {
+        if (!Object.prototype.hasOwnProperty.call(options, k)) continue;
+        if (DECORATE_OPTIONS.indexOf(k) === -1) {
+            if (KNOWN_OPTIONS.indexOf(k) !== -1) {
+                throw new Error('decorateUIFX: option "' + k + '" is not valid in decorate mode (hijack-only)');
+            }
+            throw new Error(_didYouMean('decorateUIFX: unknown option', k, DECORATE_OPTIONS));
+        }
+    }
+    const padding = options.padding === undefined ? 40 : options.padding;
+
+    // Theming options (decisions/0002): validated fail closed here, 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('decorateUIFX: 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('decorateUIFX: option "colors" must be an array of color strings');
+    }
+    if (options.text !== undefined && typeof options.text !== 'string') {
+        throw new Error('decorateUIFX: option "text" must be a string');
+    }
+    if (options.font !== undefined && typeof options.font !== 'string') {
+        throw new Error('decorateUIFX: option "font" must be a string');
+    }
+    if (options.seed !== undefined &&
+        (typeof options.seed !== 'number' || !Number.isFinite(options.seed))) {
+        throw new Error('decorateUIFX: option "seed" must be a finite number');
+    }
+
+    // 3. recipeFactory + recipe object + hooks (same contract as mountUIFX).
+    if (typeof recipeFactory !== 'function') {
+        throw new Error('decorateUIFX: recipeFactory must be a function');
+    }
+    const recipe = recipeFactory(options);
+    if (!recipe || typeof recipe !== 'object') {
+        throw new Error('decorateUIFX: recipe must be an object');
+    }
+    if (typeof recipe.tick !== 'function') {
+        throw new Error('decorateUIFX: 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('decorateUIFX: unknown recipe hook', k, KNOWN_HOOKS));
+        }
+    }
+
+    // =====================================================================
+    //  PHASE 2 -- SIDE EFFECTS (fail-closed unwind, mirrors mountUIFX). The
+    //  only acquisitions are the overlay canvas, the AbortController, and the
+    //  shared ticker -- unwound in reverse order on any throw.
+    // =====================================================================
+    let canvasAppended = false;
+    let acCreated = false;
+    let tickerAcquired = false;
+    let canvas = null;
+    let ac = null;
+    let removeTick = null;
+
+    try {
+    // -- Placement from el's OFFSET box. Because the overlay is a SIBLING of el,
+    //    they share an offsetParent, so offset-box coords land the canvas over el
+    //    WITHOUT writing any style onto the parent (decision 2). Read once here,
+    //    refreshed on resize only. --
+    let ow = el.offsetWidth;
+    let oh = el.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: (el.offsetLeft - padding) + 'px',
+        top: (el.offsetTop - padding) + 'px',
+        width: cw + 'px', height: ch + 'px',
+        pointerEvents: 'none',
+    });
+    const ctx = canvas.getContext('2d');
+    ctx.scale(dpr, dpr);
+
+    // Insert the overlay right AFTER el: among auto-z siblings it paints on top,
+    // and pointerEvents:none keeps el receiving every event. el is NOT touched --
+    // no style write, no reparent (the whole point of decorate mode).
+    el.parentNode.insertBefore(canvas, el.nextSibling);
+    canvasAppended = true;
+
+    // -- State. Generic fields wire like hijack mode; text/valid mirror the host,
+    //    read now at init (law: hook initial values from the element) and refreshed
+    //    at event time only. --
+    const state = {
+        hover: false,
+        active: false,
+        focused: (typeof document !== 'undefined' && document.activeElement === el),
+        text: (typeof el.value === 'string' ? el.value : ''),
+        valid: (el.validity ? !!el.validity.valid : true),
+        w: ow, h: oh, padding, dpr,
+    };
+    const pointer = { x: -999, y: -999, vx: 0, vy: 0 };
+    // Cached rect for pointer math (U-11): filled lazily, refreshed on enter/
+    // scroll/resize; pointermove does ZERO layout reads at steady state.
+    let rect = null;
+
+    // -- Initialize recipe (validated in phase 1). ctx exists now. --
+    if (recipe.init) recipe.init(ctx, ow, oh, padding);
+
+    // -- Events (all via AbortController: destroy()'s abort removes exactly what
+    //    decorate added and nothing the host owned). --
+    ac = new AbortController();
+    acCreated = true;
+    const signal = ac.signal;
+
+    function updatePointer(e) {
+        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(); }
+    // Reposition the overlay from the offset box after a layout change (cold path).
+    // All layout READS are hoisted above the style WRITES: writing canvas.style
+    // dirties layout, so reading el.offset* afterwards would force a synchronous
+    // reflow. A decoration over live DOM is the one place this package can force
+    // layout (see the U4b brief HOT PATH note), so keep read-before-write even here.
+    function reposition() {
+        const nw = el.offsetWidth;
+        const nh = el.offsetHeight;
+        const ol = el.offsetLeft;
+        const ot = el.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 });
+
+    el.addEventListener('pointermove', updatePointer, { signal });
+    el.addEventListener('pointerenter', (e) => {
+        state.hover = true;
+        refreshRect();
+        updatePointer(e);
+        if (recipe.onHover) recipe.onHover(state, pointer);
+    }, { signal });
+    el.addEventListener('pointerleave', () => {
+        state.hover = false;
+        if (recipe.onLeave) recipe.onLeave(state, pointer);
+    }, { signal });
+    el.addEventListener('pointerdown', (e) => {
+        state.active = true;
+        updatePointer(e);
+        if (recipe.onClick) recipe.onClick(pointer.x, pointer.y, state);
+    }, { signal });
+    el.addEventListener('pointerup', () => { state.active = false; }, { signal });
+
+    el.addEventListener('focus', () => { state.focused = true; }, { signal });
+    el.addEventListener('blur', () => { state.focused = false; }, { signal });
+
+    // Host content -> state, at EVENT time only (el.value getter allocates a
+    // string; keep it off the frame path). A non-form host never fires these.
+    function syncHostValue() {
+        state.text = (typeof el.value === 'string' ? el.value : '');
+        state.valid = (el.validity ? !!el.validity.valid : true);
+    }
+    el.addEventListener('input', syncHostValue, { signal });
+    el.addEventListener('change', syncHostValue, { signal });
+    el.addEventListener('invalid', () => { state.valid = false; }, { signal });
+
+    // -- DPR re-read on display change (cold, feature-detected; absent matchMedia
+    //    is a silent no-op -- fail closed, never throw). --
+    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; same quarantine-on-throw as mountUIFX). --
+    const ticker = acquireTicker();
+    tickerAcquired = true;
+    let destroyed = false;
+    let quarantined = false;
+
+    removeTick = ticker.add((dtMs) => {
+        if (destroyed || quarantined) return;
+        const dt = dtMs / 1000;
+        const now = performance.now();
+
+        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('decorateUIFX: recipe.tick threw; decoration quarantined', err);
+            ctx.restore();
+            ctx.clearRect(0, 0, cw, ch);
+            return;
+        }
+        ctx.restore();
+    });
+
+    // -- Public API --
+    return {
+        /** The decorated host element (unchanged; provided for external reads). */
+        el,
+
+        /** The overlay canvas (for external styling). */
+        canvas,
+
+        /** Current state (read-only reference). */
+        state,
+
+        /**
+         * Hijack-only. A decoration reflects the host; it does not own or push
+         * into the host's value, so setValue/setChecked fail closed here (use the
+         * host's own API to change it -- the decoration follows via its events).
+         */
+        setValue() {
+            throw new Error('decorateUIFX: setValue is hijack-only; a decoration reflects the host, it does not drive it');
+        },
+        setChecked() {
+            throw new Error('decorateUIFX: setChecked is hijack-only; a decoration reflects the host, it does not drive it');
+        },
+
+        /** Destroy: remove the overlay + every listener decorate added. Idempotent.
+         *  The host element is byte-identical to before decorate (never touched). */
+        destroy() {
+            if (destroyed) return;
+            destroyed = true;
+            ac.abort();
+            removeTick();
+            if (recipe.destroy) recipe.destroy();
+            releaseTicker();
+            canvas.remove();  // the ONLY DOM node decorate added
+        },
+    };
+    } catch (err) {
+        // A phase-2 step threw (realistically recipe.init). Unwind ONLY what was
+        // acquired, reverse order, each flag-guarded. recipe.destroy is NOT called
+        // (init did not succeed). Re-throw the ORIGINAL error, unwrapped.
+        if (tickerAcquired) {
+            if (removeTick) removeTick();
+            releaseTicker();
+        }
+        if (acCreated) ac.abort();
+        if (canvasAppended) canvas.remove();
+        throw err;
+    }
+}
+
 export default mountUIFX;

package/UIFXRecipes.d.ts

@@ -1,7 +1,7 @@
 import type { UIFXRecipe, UIFXInstance, MountOptions } from './UIFXController';
 
 // ===========================================================
-//  RECIPE OPTIONS + FACTORIES (all 53)
+//  RECIPE OPTIONS + FACTORIES (all 56)
 // ===========================================================
 
 /**
@@ -119,6 +119,13 @@ export declare function ScratchReveal(options?: RecipeOptions): UIFXRecipe;
 export declare function TimerCountdown(options?: RecipeOptions): UIFXRecipe;
 export declare function PullRefresh(options?: RecipeOptions): UIFXRecipe;
 
+// -- U4b: DECORATE recipes (mounted AROUND a live element via decorateUIFX).
+//    Generic form feedback; PasswordStrength + TypewriterField (above) re-home
+//    onto decorate mode too. See decisions/0004. --
+export declare function FocusHalo(options?: RecipeOptions): UIFXRecipe;
+export declare function ErrorShake(options?: RecipeOptions): UIFXRecipe;
+export declare function SuccessBloom(options?: RecipeOptions): UIFXRecipe;
+
 // ===========================================================
 //  BARREL OBJECTS (back-compat)
 // ===========================================================
@@ -189,11 +196,21 @@ export declare const UIFXRecipes4: {
     LiquidFill: typeof LiquidFill;
 };
 
+/** U4b additions -- decorate-mode recipes (kept out of the Vol.1-3 + Vol.4 snapshots). */
+export declare const UIFXRecipes5: {
+    FocusHalo: typeof FocusHalo;
+    ErrorShake: typeof ErrorShake;
+    SuccessBloom: typeof SuccessBloom;
+};
+
 // ===========================================================
 //  RECIPE REGISTRY
 // ===========================================================
 
-export type RecipeType = 'toggle' | 'button' | 'slider' | 'checkbox' | 'progress' | 'knob';
+// 'decorate' is not a UIType (it creates no native element); it is the registry
+// routing tag for a recipe mounted AROUND a live element via decorateUIFX. See
+// decisions/0004.
+export type RecipeType = 'toggle' | 'button' | 'slider' | 'checkbox' | 'progress' | 'knob' | 'decorate';
 
 export type RecipeFactory = (options?: Record<string, unknown>) => UIFXRecipe;
 
@@ -223,7 +240,10 @@ export declare function registerRecipe(
 ): RecipeFactory;
 
 /**
- * Resolve a recipe id to its factory + declared type and mount it via mountUIFX.
+ * Resolve a recipe id to its factory + declared type and mount it. A hijack
+ * recipe mounts via mountUIFX (the native element is created inside `container`);
+ * a recipe whose meta.type is 'decorate' mounts via decorateUIFX, treating
+ * `container` as the LIVE element to decorate (a canvas is placed AROUND it).
  * Fail closed: unknown id or a conflicting options.type throws.
  */
 export declare function mountRecipe(
@@ -233,7 +253,7 @@ export declare function mountRecipe(
 ): UIFXInstance;
 
 // ===========================================================
-//  DEFAULT EXPORT -- combined all-53 namespace
+//  DEFAULT EXPORT -- combined all-56 namespace
 // ===========================================================
 
 declare const UIFXAllRecipes: {
@@ -290,5 +310,8 @@ declare const UIFXAllRecipes: {
     ScratchReveal: typeof ScratchReveal;
     TimerCountdown: typeof TimerCountdown;
     PullRefresh: typeof PullRefresh;
+    FocusHalo: typeof FocusHalo;
+    ErrorShake: typeof ErrorShake;
+    SuccessBloom: typeof SuccessBloom;
 };
 export default UIFXAllRecipes;

package/UIFXRecipes.js

@@ -1,5 +1,5 @@
 /**
- * @zakkster/lite-ui-fx -- Recipe Collection (all 53)
+ * @zakkster/lite-ui-fx -- Recipe Collection (all 56)
  *
  * The three recipe volumes consolidated into one shipped, typed, versioned
  * module, exposed as the ./recipes subpath export, plus the U4a additions for
@@ -19,6 +19,9 @@
  *               TypewriterField, SoundWaveBtn, UploadProgress, ScratchReveal,
  *               TimerCountdown, PullRefresh
  *   U4a (3):    TickDraw, IndeterminateScan (CHECKBOX), LiquidFill (PROGRESS)
+ *   U4b (3):    FocusHalo, ErrorShake, SuccessBloom (DECORATE) -- generic form
+ *               feedback; PasswordStrength + TypewriterField re-homed to DECORATE
+ *               (canvas AROUND a live input, driven by state.text; see 0004)
  *
  * Registry: RECIPES (null-prototype), RECIPE_META (live), RECIPE_NAMES,
  * registerRecipe(id, factory, meta?), mountRecipe(container, id, options?).
@@ -32,7 +35,7 @@
 
 import { lerp, clamp, easeOut, easeIn, easeInOut } from '@zakkster/lite-lerp';
 import { Random } from '@zakkster/lite-random';
-import { mountUIFX, UIType } from './UIFXController.js';
+import { mountUIFX, decorateUIFX, UIType } from './UIFXController.js';
 
 
 // ---------------------------------------------------------
@@ -2294,6 +2297,28 @@ export function RadioOrbit(o = {}) {
 // ===========================================================
 
 /** 9. Password Strength -- Segmented bar with color progression and label. */
+/** Password strength 0..1 from a string, zero-alloc (charCodeAt scan, no
+ *  allocating string ops). Length (up to ~12 chars) is 60%, character-class
+ *  diversity (lower/upper/digit/symbol) 40%. COLD -- called only when the
+ *  decorated field's text changes. */
+function pwStrength(s) {
+    const n = s.length;
+    if (n === 0) return 0;
+    let lo = 0, up = 0, di = 0, sy = 0;
+    for (let i = 0; i < n; i++) {
+        const c = s.charCodeAt(i);
+        if (c >= 97 && c <= 122) lo = 1;
+        else if (c >= 65 && c <= 90) up = 1;
+        else if (c >= 48 && c <= 57) di = 1;
+        else sy = 1;
+    }
+    const v = Math.min(n / 12, 1) * 0.6 + ((lo + up + di + sy) / 4) * 0.4;
+    return v > 1 ? 1 : v;
+}
+
+/** Password Strength (U4b DECORATE, re-home) -- four strength segments driven by
+ *  the LIVE host input's value (state.text), not a faked slider. Strength is
+ *  recomputed only when the text changes (cold); the tick is zero-alloc. */
 export function PasswordStrength(o = {}) {
     let segs=[0,0,0,0];
     const labels=['WEAK','FAIR','GOOD','STRONG'];
@@ -2302,9 +2327,14 @@ export function PasswordStrength(o = {}) {
         : (o.theme ? [o.theme.light, o.theme.mid, o.theme.dark, o.theme.light] : ['#ff6b6b','#fbbf24','#38bdf8','#6ee7b6']);
     const colors = base.length >= 4 ? base : [base[0], base[1 % base.length], base[2 % base.length], base[3 % base.length]];
     const noneColor = (o.theme && o.theme.mid) || '#666';
+    let lastText = null, strength = 0;  // strength recomputed only on text change
     return {
         tick(c,dt,now,st) {
-            const level=Math.ceil(st.val*4);
+            // state.text is the live host value; rescan only on change (cold). A
+            // bare decoration over an empty field reads '' -> strength 0.
+            const t = st.text || '';
+            if (t !== lastText) { lastText = t; strength = pwStrength(t); }
+            const level=Math.ceil(strength*4);
             for(let i=0;i<4;i++) segs[i]=lerp(segs[i],i<level?1:0,dt*10);
 
             const segW=(st.w-12)/4,segH=8;
@@ -2562,33 +2592,43 @@ export function NotificationBell(o = {}) {
 // ===========================================================
 
 /** 15. Typewriter Field -- Characters appear one by one with cursor blink. */
+/** Typewriter Field (U4b DECORATE, re-home) -- an animated underline that grows
+ *  with the LIVE host input's text and a caret that flares on each new character.
+ *  Draws NO text (the real input shows its own; a decoration never re-renders the
+ *  host content) and reads only state.text's length -- zero-alloc, no measureText. */
 export function TypewriterField(o = {}) {
     const P = resolveTheme(o, { accent: '#6ee7b6', dim2: '#8888aa' });
-    const FONT = pickFont(o, "500 13px 'JetBrains Mono',monospace");
-    const text=pickText(o, 'Hello World');
-    let charIdx=0, timer=0, cursorBlink=0, typing=false;
-    let display='', dispW=0, lastIdx=-1; // substring rebuilt only when a char lands
+    const themed = !!(o.theme || o.colors);
+    const glow = themed ? rgbaOf(P.accent, .5) : 'rgba(110,231,182,.5)';
+    let lastLen=0, fill=0, spark=0, blink=0;
     return {
-        onToggle(checked){typing=checked;if(checked){charIdx=0;timer=0}},
         tick(c,dt,now,st) {
-            cursorBlink=(cursorBlink+dt*3)%2;
-            if(typing&&charIdx<text.length){timer+=dt;if(timer>.08){timer=0;charIdx++}}
-
-            c.fillStyle='rgba(255,255,255,.04)';rr(c,0,0,st.w,st.h,6);c.fill();
-            c.strokeStyle='rgba(255,255,255,.06)';c.lineWidth=1;rr(c,0,0,st.w,st.h,6);c.stroke();
-
-            c.fillStyle=P.accent;c.font=FONT;c.textAlign='left';c.textBaseline='middle';
-            // Rebuild the visible substring + its width only when a char is added.
-            if(charIdx!==lastIdx){lastIdx=charIdx;display=text.substring(0,charIdx);dispW=c.measureText(display).width;}
-            c.fillText(display,8,st.h/2);
-
-            // Cursor
-            if(cursorBlink<1){
-                c.fillStyle=P.accent;c.fillRect(9+dispW,st.h/2-8,1.5,16);
+            const len=(st.text || '').length;
+            if(len>lastLen) spark=1;   // a new char landed -> caret pulse
+            lastLen=len;
+            blink=(blink+dt*3)%2;
+            spark=spark>0?spark-dt*3:0;
+
+            // Underline grows toward a fraction of the width set by text length
+            // (capped at ~24 chars = full width). No measureText -> zero-alloc.
+            const target=len===0?0:Math.min(len/24,1);
+            fill=lerp(fill,target,dt*8);
+            const y=st.h-3, x0=2, x1=2+(st.w-4)*fill;
+
+            c.strokeStyle='rgba(255,255,255,.08)';c.lineWidth=2;
+            c.beginPath();c.moveTo(x0,y);c.lineTo(st.w-2,y);c.stroke();
+            c.strokeStyle=P.accent;c.lineWidth=2;
+            c.beginPath();c.moveTo(x0,y);c.lineTo(x1,y);c.stroke();
+
+            // Caret: a glow that flares on each keystroke, blinks when idle+focused.
+            if(spark>0.01){
+                c.globalAlpha=spark;c.fillStyle=glow;
+                c.beginPath();c.arc(x1,y,4+spark*3,0,PI2);c.fill();
+                c.globalAlpha=1;
+            }
+            if(st.focused&&blink<1){
+                c.fillStyle=P.accent;c.fillRect(x1,y-9,1.5,12);
             }
-
-            lbl(c,typing?'TYPING...':'TOGGLE TO TYPE',st.w/2,st.h+10,typing?P.accent:P.dim2);
-            if(st.focused)fr(c,st.w,st.h,6);
         },
     };
 }
@@ -2854,6 +2894,100 @@ export const UIFXRecipes3 = {
     ScratchReveal, TimerCountdown, PullRefresh,
 };
 
+// ===========================================================
+//  DECORATIONS (U4b) -- canvas AROUND a live element (decorateUIFX). Generic form
+//  feedback reading state.focused / state.valid / state.text; NONE draw the host's
+//  own content. Born themed + zero-alloc + t3-gated. See decisions/0004.
+// ===========================================================
+
+/** Focus Halo (U4b DECORATE) -- a soft glow around the host that breathes while
+ *  focused and fades on blur. Generic form feedback; reads only state.focused. */
+export function FocusHalo(o = {}) {
+    const P = resolveTheme(o, { accent: '#6ee7b6' });
+    let halo=0;  // 0..1 presence
+    return {
+        tick(c,dt,now,st) {
+            halo=lerp(halo, st.focused?1:0, dt*8);
+            if(halo<0.01) return;
+            const breathe=0.75+Math.sin(now/380)*0.25, r=8;
+            c.strokeStyle=P.accent;
+            for(let i=3;i>=1;i--){
+                c.globalAlpha=halo*breathe*(0.10*i);
+                c.lineWidth=i*2;
+                rr(c,-i*2,-i*2,st.w+i*4,st.h+i*4,r+i*2);c.stroke();
+            }
+            c.globalAlpha=halo;c.strokeStyle=P.accent;c.lineWidth=1.5;
+            rr(c,-1,-1,st.w+2,st.h+2,r);c.stroke();
+            c.globalAlpha=1;
+        },
+    };
+}
+
+/** Error Shake (U4b DECORATE) -- a red border that shakes on the state.valid
+ *  true->false edge and settles as the shake decays; a steady red border holds
+ *  while invalid. Draws only its OWN jitter (never moves the host). */
+export function ErrorShake(o = {}) {
+    const P = resolveTheme(o, { accent: '#ff6b6b' });
+    let wasValid=true, shake=0;
+    return {
+        tick(c,dt,now,st) {
+            if(wasValid && st.valid===false) shake=1;   // valid -> invalid edge
+            wasValid = st.valid !== false;
+            shake = shake>0 ? shake-dt*1.6 : 0;
+            if(shake<0.01 && st.valid!==false) return;   // nothing to show
+
+            const dx = shake>0 ? Math.sin(now/22)*shake*6 : 0;
+            const a = st.valid===false ? 0.9 : shake, r=8;
+            c.globalAlpha=a;c.strokeStyle=P.accent;c.lineWidth=2;
+            rr(c,dx,0,st.w,st.h,r);c.stroke();
+            c.globalAlpha=1;
+        },
+    };
+}
+
+/** Success Bloom (U4b DECORATE) -- a green ring + fixed-pool particle bloom on the
+ *  state.valid false->true edge (a fixed error resolved). Zero-alloc: typed-array
+ *  pool preallocated in the factory. */
+export function SuccessBloom(o = {}) {
+    const P = resolveTheme(o, { accent: '#6ee7b6' });
+    const N = 20;
+    const px=new Float32Array(N), py=new Float32Array(N), pvx=new Float32Array(N), pvy=new Float32Array(N), pa=new Float32Array(N);
+    let wasValid=true, ring=0;
+    function bloom(st){
+        ring=1;
+        const cx=st.w/2, cy=st.h/2;
+        for(let i=0;i<N;i++){
+            const ang=(i/N)*PI2, sp=40+(i%5)*8;
+            px[i]=cx; py[i]=cy; pvx[i]=Math.cos(ang)*sp; pvy[i]=Math.sin(ang)*sp; pa[i]=1;
+        }
+    }
+    return {
+        tick(c,dt,now,st) {
+            // false -> true edge = success. (undefined stays !== false: no edge.)
+            if(wasValid===false && st.valid!==false) bloom(st);
+            wasValid = st.valid !== false;
+
+            if(ring>0){
+                ring-=dt*1.4; if(ring<0) ring=0;
+                const cx=st.w/2, cy=st.h/2, rad=(1-ring)*st.w*0.6;
+                c.globalAlpha=ring;c.strokeStyle=P.accent;c.lineWidth=2;
+                c.beginPath();c.arc(cx,cy,rad,0,PI2);c.stroke();
+                c.globalAlpha=1;
+            }
+            c.fillStyle=P.accent;
+            for(let i=0;i<N;i++){
+                if(pa[i]<=0) continue;
+                px[i]+=pvx[i]*dt; py[i]+=pvy[i]*dt; pvx[i]*=0.92; pvy[i]*=0.92; pa[i]-=dt*1.4;
+                if(pa[i]<=0) continue;
+                c.globalAlpha=pa[i];
+                c.beginPath();c.arc(px[i],py[i],2.5,0,PI2);c.fill();
+            }
+            c.globalAlpha=1;
+        },
+    };
+}
+
+
 // U4a additions -- new native element types (CHECKBOX, PROGRESS). Kept out of the
 // Vol.1-3 historical snapshots above so those stay accurate; all recipes remain
 // reachable via RECIPES / RECIPE_META and their named exports regardless.
@@ -2862,6 +2996,13 @@ export const UIFXRecipes4 = {
     LiquidFill,
 };
 
+// U4b additions -- decorate-mode recipes (a canvas AROUND a live element). Kept out
+// of the Vol.1-3 + Vol.4 snapshots above; reachable via RECIPES / RECIPE_META and
+// their named exports regardless.
+export const UIFXRecipes5 = {
+    FocusHalo, ErrorShake, SuccessBloom,
+};
+
 
 // ===========================================================
 //  DEFAULT EXPORT -- combined all-53 namespace
@@ -2921,6 +3062,9 @@ export default {
     ScratchReveal,
     TimerCountdown,
     PullRefresh,
+    FocusHalo,
+    ErrorShake,
+    SuccessBloom,
 };
 
 
@@ -2987,6 +3131,9 @@ export const RECIPES = Object.assign(Object.create(null), {
     scratchReveal: ScratchReveal,
     timerCountdown: TimerCountdown,
     pullRefresh: PullRefresh,
+    focusHalo: FocusHalo,
+    errorShake: ErrorShake,
+    successBloom: SuccessBloom,
 });
 
 /**
@@ -2994,8 +3141,10 @@ export const RECIPES = Object.assign(Object.create(null), {
  * a picker without hardcoding the list. A live array: registerRecipe() updates
  * it, so existing pickers keep working.
  *
- *   type       'toggle' | 'button' | 'slider' -- the native element it mounts on
- *   family     display grouping (Toggles, Buttons, Sliders, Knobs, ...)
+ *   type       'toggle'|'button'|'slider'|'checkbox'|'progress'|'knob' -- the
+ *              native element it mounts on (mountUIFX); or 'decorate' -- mounted
+ *              AROUND a live element via decorateUIFX (no native element created)
+ *   family     display grouping (Toggles, Buttons, Sliders, Knobs, Form, ...)
  *   themeable  accepts { colors, theme } (true for all as of U3b/1.4.0)
  *   motionSafe inherently-calm under prefers-reduced-motion (false for all -- U5)
  */
@@ -3041,18 +3190,21 @@ export const RECIPE_META = [
     { id: 'pillTabs', name: 'Pill Tabs', type: 'button', family: 'Controls', themeable: true, motionSafe: false },
     { id: 'stepper', name: 'Stepper', type: 'button', family: 'Controls', themeable: true, motionSafe: false },
     { id: 'radioOrbit', name: 'Radio Orbit', type: 'slider', family: 'Controls', themeable: true, motionSafe: false },
-    { id: 'passwordStrength', name: 'Password Strength', type: 'slider', family: 'Indicators', themeable: true, motionSafe: false },
+    { id: 'passwordStrength', name: 'Password Strength', type: 'decorate', family: 'Indicators', themeable: true, motionSafe: false },
     { id: 'waterLevel', name: 'Water Level', type: 'slider', family: 'Indicators', themeable: true, motionSafe: false },
     { id: 'heatMap', name: 'Heat Map', type: 'slider', family: 'Indicators', themeable: true, motionSafe: false },
     { id: 'dayNightToggle', name: 'Day Night Toggle', type: 'toggle', family: 'Mood', themeable: true, motionSafe: false },
     { id: 'reactionPicker', name: 'Reaction Picker', type: 'button', family: 'Mood', themeable: true, motionSafe: false },
     { id: 'notificationBell', name: 'Notification Bell', type: 'button', family: 'Mood', themeable: true, motionSafe: false },
-    { id: 'typewriterField', name: 'Typewriter Field', type: 'toggle', family: 'Feedback', themeable: true, motionSafe: false },
+    { id: 'typewriterField', name: 'Typewriter Field', type: 'decorate', family: 'Feedback', themeable: true, motionSafe: false },
     { id: 'soundWaveBtn', name: 'Sound Wave Btn', type: 'button', family: 'Feedback', themeable: true, motionSafe: false },
     { id: 'uploadProgress', name: 'Upload Progress', type: 'progress', family: 'Feedback', themeable: true, motionSafe: false },
     { id: 'scratchReveal', name: 'Scratch Reveal', type: 'slider', family: 'Fun', themeable: true, motionSafe: false },
     { id: 'timerCountdown', name: 'Timer Countdown', type: 'toggle', family: 'Fun', themeable: true, motionSafe: false },
     { id: 'pullRefresh', name: 'Pull Refresh', type: 'slider', family: 'Fun', themeable: true, motionSafe: false },
+    { id: 'focusHalo', name: 'Focus Halo', type: 'decorate', family: 'Form', themeable: true, motionSafe: false },
+    { id: 'errorShake', name: 'Error Shake', type: 'decorate', family: 'Form', themeable: true, motionSafe: false },
+    { id: 'successBloom', name: 'Success Bloom', type: 'decorate', family: 'Form', themeable: true, motionSafe: false },
 ];
 
 /** Names of every built-in recipe (the keys of RECIPES at load time). */
@@ -3061,7 +3213,11 @@ export const RECIPE_NAMES = Object.freeze(Object.keys(RECIPES));
 // The valid recipe/mount types, taken from the controller's UIType so the
 // registry's fail-closed check and the controller's mount guard are one source
 // of truth (they cannot drift as U4 adds types). Built once at load (cold).
-const VALID_META_TYPES = new Set(Object.values(UIType));
+// Plus the ONE non-UIType routing tag: 'decorate' (U4b) creates no native
+// element -- it is mounted AROUND a live element by decorateUIFX, not by
+// mountUIFX -- so it is not a UIType, but it is a valid RECIPE_META.type that
+// mountRecipe routes on (see below). It is the only member not from UIType.
+const VALID_META_TYPES = new Set([...Object.values(UIType), 'decorate']);
 
 /**
  * Register a custom recipe, or override a built-in. Instantly usable via
@@ -3144,13 +3300,18 @@ function nearestRecipe(id) {
 }
 
 /**
- * Resolve a recipe id to its factory + declared type and mount it via
- * mountUIFX. Fail closed:
+ * Resolve a recipe id to its factory + declared type and mount it. A hijack
+ * recipe (type toggle/button/slider/checkbox/progress/knob) mounts via mountUIFX,
+ * creating the native element inside `container`. A DECORATE recipe (type
+ * 'decorate', U4b) mounts via decorateUIFX, treating the first argument as the
+ * LIVE element to decorate (a canvas is placed AROUND it -- nothing is created
+ * inside it). Fail closed:
  *   - unknown id -> throw naming the nearest known id (did-you-mean).
  *   - options.type present and != the recipe's declared type -> throw.
  * options.type is consumed here, never forwarded as a mount option.
  *
- * @param {HTMLElement} container
+ * @param {HTMLElement} container  hijack: parent to mount into; decorate: the
+ *                                 live element to decorate.
  * @param {string} id
  * @param {Object} [options]
  * @returns {{ el: HTMLElement, destroy: Function }}
@@ -3179,6 +3340,13 @@ export function mountRecipe(container, id, options) {
         mountOptions = {};
         for (const k in options) if (k !== 'type') mountOptions[k] = options[k];
     }
+    // A decoration is mounted AROUND a live element (no native element created),
+    // so it routes to decorateUIFX with `container` as the host element. Every
+    // other type is a hijack mount. mountUIFX keeps rejecting 'decorate' via its
+    // own _KNOWN_TYPES guard, so the two paths cannot cross.
+    if (type === 'decorate') {
+        return decorateUIFX(container, factory, mountOptions);
+    }
     return mountUIFX(container, type, factory, mountOptions);
 }
 

package/llms.txt

@@ -1,7 +1,7 @@
 # @zakkster/lite-ui-fx
-> Canvas-hijacked UI components with pluggable recipe system. 53 built-in recipes.
+> Canvas-hijacked UI components with pluggable recipe system. 56 built-in recipes.
 
-VERSION 1.5.0
+VERSION 1.6.0
 
 ## Install
 npm i @zakkster/lite-ui-fx
@@ -12,9 +12,9 @@ Canvas overlay (z-index:1) renders visuals via a recipe factory function.
 Recipe = { tick(), init?(), onHover?(), onClick?(), onToggle?(), onDrag?(), destroy?() }
 
 ## Import -- Controller
-import { mountUIFX, UIType } from '@zakkster/lite-ui-fx';
+import { mountUIFX, decorateUIFX, UIType } from '@zakkster/lite-ui-fx';
 
-## Import -- Recipes (one ./recipes subpath, 53 total, tree-shakeable)
+## Import -- Recipes (one ./recipes subpath, 56 total, tree-shakeable)
 import { SwarmToggle, MagneticButton, SparkSlider } from '@zakkster/lite-ui-fx/recipes';
 import { PendulumToggle, HeartbeatButton, AuroraSlider } from '@zakkster/lite-ui-fx/recipes';
 import { VolumeKnob, WaterLevel, TimerCountdown } from '@zakkster/lite-ui-fx/recipes';
@@ -24,11 +24,23 @@ import { RECIPES, RECIPE_META, RECIPE_NAMES, registerRecipe, mountRecipe } from
 // RECIPES id->factory (null-proto); RECIPE_META { id, name, type, family, themeable, motionSafe }; RECIPE_NAMES frozen.
 // mountRecipe(container, id, options?): resolves id fail-closed (did-you-mean), asserts META.type, mounts.
 
-## Mount
+## Mount -- two modes
+// HIJACK (mountUIFX): creates a native element (opacity:0) inside `container` and
+// paints a canvas over it. The native element owns events + a11y.
 const instance = mountUIFX(container, UIType.TOGGLE, SwarmToggle, { label: 'Sound' });
 instance.setValue(v);   // SLIDER/KNOB/PROGRESS: v in 0..1 (fires onDrag once); CHECKBOX: setValue(null) = indeterminate
 instance.setChecked(b); // TOGGLE/CHECKBOX: set checked (fires onToggle once)
 instance.destroy();     // cleanup
+// DECORATE (decorateUIFX): a canvas AROUND an EXISTING visible element -- no
+// native element created, no opacity:0, host never reparented; the overlay is a
+// sibling placed from the host's offset box, removed on destroy (host byte-
+// identical). State is wired from the host's own events; for a form-control host
+// state.text/state.valid mirror el.value/el.validity (read at event time). This
+// is the home for a decoration over a real input.
+const deco = decorateUIFX(inputEl, PasswordStrength, { theme });
+deco.destroy();         // removes ONLY the overlay + its listeners; host untouched
+// setValue/setChecked are HIJACK-ONLY: they throw in decorate mode (a decoration
+// reflects the host; it does not drive it).
 
 ## Options (4th arg; unknown option or recipe-hook keys throw a did-you-mean -- fail closed)
 width, height, padding=40, label   // geometry + accessible label
@@ -42,6 +54,9 @@ text      // visible canvas label; falls back to label, then the recipe default
 font      // canvas font string; falls back to the recipe's historical font
 knobMode  // KNOB only: 'rotate' | 'vertical' pointer mapping (default 'rotate'); wrong type throws
 announce  // PROGRESS only: opt-in aria-live announcements at 10% steps; wrong type throws
+// decorateUIFX accepts a SUBSET: padding, seed, colors, theme, text, font. The
+// hijack-only keys (width/height/value/checked/disabled/knobMode/announce/label)
+// throw in decorate mode -- geometry comes from the host, value is read from it.
 
 ## Element Types
 UIType.TOGGLE   -> <input type="checkbox" role="switch"> -> state.toggled, onToggle(checked)
@@ -50,11 +65,14 @@ UIType.SLIDER   -> <input type="range"> -> state.val (0-1), onDrag(val, velocity
 UIType.CHECKBOX -> <input type="checkbox"> (no role=switch) -> state.toggled + state.indeterminate, onToggle(checked)
 UIType.PROGRESS -> <progress> (non-interactive) -> state.val, driven by instance.setValue
 UIType.KNOB     -> <input type="range"> -> state.val, arrows native + knobMode pointer map, onDrag(val, velocity)
+(decorate)      -> NO native element created; a canvas AROUND a live host (decorateUIFX). Not a UIType --
+                   RECIPE_META.type 'decorate' routes mountRecipe to decorateUIFX. State: focused + text + valid.
 
 ## State Object (provided to tick every frame)
 { hover, active, focused, toggled, indeterminate, disabled, val, w, h, padding, dpr }
+// decorate mode adds: text (host value string), valid (host validity boolean).
 
-## 53 Built-in Recipes
+## 56 Built-in Recipes
 
 ### Vol. 1 -- 10 recipes
 Toggles: SwarmToggle, LiquidToggle, NeonPulseToggle
@@ -83,6 +101,11 @@ Fun: ScratchReveal, TimerCountdown, PullRefresh
 Checkboxes (UIType.CHECKBOX): TickDraw, IndeterminateScan
 Progress (UIType.PROGRESS): LiquidFill
 
+### U4b -- 3 recipes (decorate mode: a canvas AROUND a live element)
+Form feedback (decorateUIFX): FocusHalo, ErrorShake, SuccessBloom
+// Re-homed to decorate mode (type 'decorate'): PasswordStrength (reads the live
+// input's text), TypewriterField (an underline that grows with the typed text).
+
 ## Writing Custom Recipes
 See UIFX-RECIPE-GUIDE.md (included in package).
 
@@ -98,10 +121,15 @@ 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 53 recipes honour { colors, theme:{light,mid,dark}, text, font },
+- Themeable: all 56 recipes honour { colors, theme:{light,mid,dark}, text, font },
   resolved once in init (zero per-frame alloc). RECIPE_META.themeable is true for
-  all 53; motionSafe stays false (reduced motion is a later pass). A bare mount is
+  all 56; motionSafe stays false (reduced motion is a later pass). A bare mount is
   byte-identical to pre-theming. Shipped palettes + APCA contrast are authored with
   @zakkster/lite-hueforge (a dev-only tool, never a runtime dependency).
 - U4a element types: CHECKBOX (indeterminate), PROGRESS (setValue-driven, aria-live
   opt-in), KNOB (knobMode pointer map); setValue/setChecked sync native+state+hook once.
+- U4b decorate mode (decorateUIFX): a canvas AROUND a live element -- no hijack, no
+  opacity:0, host never reparented; the overlay is a sibling placed from the host's
+  offset box and removed on destroy (host byte-identical, additive-only). State is
+  wired from the host's own events (state.text/state.valid at event time). It is the
+  second mount mode + the surface the enrichment decorations build on.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-ui-fx",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Canvas-hijacked UI components with a pluggable recipe system. 50 built-in recipes across toggles, buttons, sliders, knobs, loaders, checkboxes, counters, and ratings.",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
   "license": "MIT",