@zakkster/lite-ui-fx 1.11.0 → 1.12.0

package/CHANGELOG.md

@@ -5,6 +5,50 @@ All notable changes to `@zakkster/lite-ui-fx` are documented here.
 The format follows Keep a Changelog; this project adheres to Semantic
 Versioning.
 
+## [1.12.0] -- 2026-09-08
+
+Enrichment session E2 (decisions/0010): eight bespoke decorations on the U4b decorate
+mode -- text-fx, card, and pointer micro-interactions painted AROUND a live element.
+The first session since U4b to grow the MAIN recipe registry; no new dependency.
+
+### Added
+
+- Eight `decorateUIFX` recipes on the `./recipes` subpath (RECIPE_META type
+  `decorate`), growing `RECIPE_NAMES` 57 -> 65 across three new families. Each is
+  themeable, `motionSafe` (a reduced-motion calm path), and allocates zero bytes per
+  frame, gated by the t3 torture tier (now gating 65 recipes, default AND themed):
+  - Text, painted OVER the host's own live glyphs: `TextShimmer` (a swept light band),
+    `SpotlightText` (a pointer-follow reading highlight), `UnderlineDraw` (a
+    focus-triggered underline wipe, distinct from TypewriterField).
+  - Card: `BorderBeam` (a comet around the perimeter), `TiltShine` (a pointer-driven
+    sheen), `CardSpotlight` (a pointer-follow radial glow).
+  - Pointer: `MagneticPull` (an accent ring eased toward the pointer; the host never
+    moves), `PointerRipple` (expanding rings from each press, a fixed Float32Array pool).
+  A recipe receives only `(ctx, dt, now, state, pointer)` -- never a DOM handle -- so a
+  decoration cannot read layout and is structurally reflow-safe. Shimmer/glow/beam use
+  const colours + `globalAlpha` with no gradient built in tick; no dependency was added
+  (`package.json` deps stay `lite-lerp` / `lite-random` / `lite-ticker`).
+- `test/decorations-e2.test.mjs`: registry shape, additive-diff + exact-restore over
+  `<input>` / `<div>` / `<button>` hosts, and reduced-motion calm-path divergence. The
+  t3 decorate churn now sweeps the pointer and fires the click hook so the pointer
+  decorations' full draw paths are inside the alloc window.
+
+### Changed
+
+- `llms.txt` and `README.md`: the recipe catalog + counts move 57 -> 65 (new families
+  Text, Card, Pointer), the `motionSafe` roster 6 -> 14, and the catalog size figure is
+  re-measured (~29 KB min+gzip). `demo/index.html` auto-generates the eight scenes from
+  RECIPE_META (the card/pointer families decorate a visible card host). Documentation
+  and demo only; no shipped code path changed.
+
+### Fixed
+
+none
+
+### Removed
+
+none
+
 ## [1.11.0] -- 2026-09-08
 
 Enrichment session E1b (decisions/0009): seven bespoke headless skins continuing the

package/README.md

@@ -1,6 +1,6 @@
 # @zakkster/lite-ui-fx
 
-> Canvas microinteractions on real native controls. A DPR-aware canvas is hijacked over a hidden native element -- decorated around a live one -- or shared across a group of them -- and painted by a pluggable, zero-GC **recipe**. The native element owns focus, keyboard, and pointer events; the canvas owns the visuals. 57 built-in recipes behind a tree-shakeable registry, one option convention for theming, one clock you can hand it, and reduced-motion built in.
+> Canvas microinteractions on real native controls. A DPR-aware canvas is hijacked over a hidden native element -- decorated around a live one -- or shared across a group of them -- and painted by a pluggable, zero-GC **recipe**. The native element owns focus, keyboard, and pointer events; the canvas owns the visuals. 65 built-in recipes behind a tree-shakeable registry, one option convention for theming, one clock you can hand it, and reduced-motion built in.
 
 [![npm version](https://img.shields.io/npm/v/@zakkster/lite-ui-fx.svg?style=for-the-badge&color=latest)](https://www.npmjs.com/package/@zakkster/lite-ui-fx)
 ![Zero-GC](https://img.shields.io/badge/Zero--GC-Recipes-00C853?style=for-the-badge&logo=leaf&logoColor=white)
@@ -81,9 +81,9 @@ The alternative is a hand-rolled canvas threshold loop (no a11y, allocates freel
 - **`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).
+- **65 built-in recipes** on the `./recipes` subpath, versioned, typed, and tree-shakeable. With `sideEffects: false`, importing one recipe drops the other 64. 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), Text (3), Card (3), Pointer (2).
 - **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.
+- **One option convention for theming** -- `{ colors, theme: { light, mid, dark }, text, font }` honoured by all 65 recipes, resolved once in `init` so a themed mount stays zero-GC and a bare mount is byte-identical to pre-theming.
 - **Host integration** -- ride a caller-supplied `lite-ticker` (`{ ticker }`), drive frames by hand (`{ driven: true }` + `instance.tick(dtMs)`), or take the shared ref-counted ticker by default. Plus `state.reducedMotion` (matchMedia-watched) and `state.budget` (0..1 frame budget).
 - **Full TypeScript declarations** for both entry points, and a written recipe guide ([`UIFX-RECIPE-GUIDE.md`](UIFX-RECIPE-GUIDE.md)) shipped in the package.
 
@@ -213,7 +213,7 @@ The fourth mount adapter, on the `./headless` subpath: **skin a `@zakkster/lite-
 
 `options`: `host` (the element the primitive paints on, **required**) plus `padding`, `seed`, `colors`, `theme`, `text`, `font`, `ticker`, `driven`. `setValue`/`setChecked` throw -- a skin reflects the primitive, it does not drive it.
 
-A skin is an ordinary recipe plus a descriptor -- `recipe.headless = { attrs, read(host, handle, state) }`. `skinHeadless` observes `attrs` and calls `read()` at **event time** (never per frame) to parse the painted state into preallocated slots. A painted attribute is truthy when present with any value but `"false"` (so both a boolean `data-disabled` and a value `data-checked="true"` work). The 11 skins live in a registry (`HEADLESS_SKINS` / `SKIN_META`) separate from the 57 recipes.
+A skin is an ordinary recipe plus a descriptor -- `recipe.headless = { attrs, read(host, handle, state) }`. `skinHeadless` observes `attrs` and calls `read()` at **event time** (never per frame) to parse the painted state into preallocated slots. A painted attribute is truthy when present with any value but `"false"` (so both a boolean `data-disabled` and a value `data-checked="true"` work). The 11 skins live in a registry (`HEADLESS_SKINS` / `SKIN_META`) separate from the 65 recipes.
 
 ```js
 import { skinHeadless, SwitchSkin } from '@zakkster/lite-ui-fx/headless';
@@ -273,7 +273,7 @@ The `state` object passed to `tick(ctx, dt, now, state)` every frame:
 | `index` / `count` / `hoverIndex` | `number` | group mode only: selection, item count, hovered item (-1 none) |
 | `labels` / `itemX` / `itemY` / `itemW` / `itemH` | `string[]` / `Float32Array` | group mode only: item labels + per-item geometry lanes (read by index) |
 
-`RECIPE_META` rows: `{ id, name, type, family, themeable, motionSafe }`. `themeable` is true for all 57; `motionSafe` is true for exactly the recipes that ship a calm reduced-motion path (6 today: SwarmToggle plus the five decorate recipes) and honestly false for the rest.
+`RECIPE_META` rows: `{ id, name, type, family, themeable, motionSafe }`. `themeable` is true for all 65; `motionSafe` is true for exactly the recipes that ship a calm reduced-motion path (14 today: SwarmToggle plus the five U4b decorate recipes and the eight E2 decorations) and honestly false for the rest.
 
 ---
 
@@ -353,13 +353,13 @@ Everything a recipe needs is resolved in `init` (cold): the palette and any ramp
 | Pointer move / drag | **0** | arithmetic only; the bounding rect is cached on pointer-enter, not read per move |
 | `init` / theme resolve | once, cold | palette, ramps, gradients, pools -- then read-only in the loop |
 
-The `t3-frame-alloc` torture tier asserts, per recipe, **zero distinct `fillStyle` string allocations per frame at steady state** and **zero gradient constructions after `init`** -- in both a default and a themed mount, across all 57 recipes (grouped controls included, driven through their selection). Two positive controls -- one allocating a color string per frame, one per group item per frame -- must FAIL the gate, or it would be decorative. The full harness (`@zakkster/lite-leak` + `@zakkster/lite-gc-profiler`) proves **0 retained bytes, 0 major GCs, and ~0.88 B/op** across the whole mount / interact / destroy loop under `--expose-gc`:
+The `t3-frame-alloc` torture tier asserts, per recipe, **zero distinct `fillStyle` string allocations per frame at steady state** and **zero gradient constructions after `init`** -- in both a default and a themed mount, across all 65 recipes (grouped controls included, driven through their selection). Two positive controls -- one allocating a color string per frame, one per group item per frame -- must FAIL the gate, or it would be decorative. The full harness (`@zakkster/lite-leak` + `@zakkster/lite-gc-profiler`) proves **0 retained bytes, 0 major GCs, and ~0.88 B/op** across the whole mount / interact / destroy loop under `--expose-gc`:
 
 ```
 GATE leak=size 0/0 findings=0 warnings=0 | gc major=0 minor=0 maxMs=0.00 | alloc=0.8759765625 B/op
 ```
 
-For size: the controller alone is **~7.1 KB min+gzip** (its three deps external); the full catalog of 57 recipes is **~25 KB min+gzip**, and it tree-shakes -- import one recipe and the bundler drops the other 56.
+For size: the controller alone is **~7.1 KB min+gzip** (its three deps external); the full catalog of 65 recipes is **~29 KB min+gzip**, and it tree-shakes -- import one recipe and the bundler drops the other 64.
 
 </details>
 
@@ -369,21 +369,22 @@ For size: the controller alone is **~7.1 KB min+gzip** (its three deps external)
 
 Each is an ADR under [`decisions/`](decisions/):
 
-- **[0001](decisions/0001-recipes-position.md) -- Recipes ship inside the package.** No more copy-paste-from-a-ZIP: 57 recipes are versioned, typed, and tree-shakeable behind the `./recipes` subpath, exactly the shape the sibling fx packages use.
-- **[0002](decisions/0002-recipe-options.md) -- One recipe option convention.** `{ colors, theme, text, font }` across all 57, resolved cold in `init`; defaults reproduce today's literals byte-for-byte; `text` closes the WCAG label-in-name gap.
+- **[0001](decisions/0001-recipes-position.md) -- Recipes ship inside the package.** No more copy-paste-from-a-ZIP: 65 recipes are versioned, typed, and tree-shakeable behind the `./recipes` subpath, exactly the shape the sibling fx packages use.
+- **[0002](decisions/0002-recipe-options.md) -- One recipe option convention.** `{ colors, theme, text, font }` across all 65, resolved cold in `init`; defaults reproduce today's literals byte-for-byte; `text` closes the WCAG label-in-name gap.
 - **[0003](decisions/0003-element-types.md) -- Real native element types.** CHECKBOX (tri-state), PROGRESS (`setValue`-driven, opt-in `aria-live`), KNOB (native arrows + pointer map) wrap the *correct* native element, not a faked toggle.
 - **[0004](decisions/0004-decorate-mode.md) -- Decorate mode.** A second mount mode for a canvas around a live element -- the honest home for a decoration over a real input, host byte-identical.
 - **[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).
+- **[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 recipe registry (additive, 1.10.0).
 - **[0009](decisions/0009-headless-skins-select.md) -- Headless skins II: the select + tri-state pack.** Adds seven bespoke skins (checkbox tri-state + checkbox-group master, select trigger, meter, steps, accordion, skeleton), all single-host and mapping onto the existing state slots (no state-shape change). `SelectSkin` resolves the `<select>`/dropdown decision toward a V4 skin of the trigger; the portaled listbox open-state is a recorded follow-on. No new dependency (additive, 1.11.0).
+- **[0010](decisions/0010-text-pointer-card-decorations.md) -- Text-fx + pointer + card decorations.** Eight decorate-mode recipes (text shimmer/spotlight/underline, card border-beam/tilt-shine/spotlight, pointer magnetic-pull/ripple) grow the main recipe registry to 65. Each is zero per-frame alloc (const colours + `globalAlpha`, no gradient), `motionSafe` with a real calm path, and structurally reflow-safe -- a recipe receives `ctx` + `state` + `pointer`, never a DOM handle, so it cannot read layout. No new dependency: particle trail/glow and a host-owned scramble defer to later phases (additive, 1.12.0).
 
 ---
 
 ## Testing
 
-**237 deterministic node:test cases across 27 suites, all pass**, plus a torture gate that proves 0 B/op steady state and leak-freedom.
+**299 deterministic node:test cases across 38 suites, all pass**, plus a torture gate that proves 0 B/op steady state and leak-freedom.
 
 ```bash
 npm test          # node:test: contract, boundary, registry, theming, reduced-motion, docs

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.11.0';
+export const VERSION = '1.12.0';
 
 // ---------------------------------------------------------
 //  SHARED TICKER (ref-counted, one RAF for all UI components)

package/UIFXRecipes.d.ts

@@ -134,6 +134,15 @@ export declare function PullRefresh(options?: RecipeOptions): UIFXRecipe;
 export declare function FocusHalo(options?: RecipeOptions): UIFXRecipe;
 export declare function ErrorShake(options?: RecipeOptions): UIFXRecipe;
 export declare function SuccessBloom(options?: RecipeOptions): UIFXRecipe;
+// E2 decorations (text-fx + card + pointer; decisions/0010)
+export declare function TextShimmer(options?: RecipeOptions): UIFXRecipe;
+export declare function SpotlightText(options?: RecipeOptions): UIFXRecipe;
+export declare function UnderlineDraw(options?: RecipeOptions): UIFXRecipe;
+export declare function BorderBeam(options?: RecipeOptions): UIFXRecipe;
+export declare function TiltShine(options?: RecipeOptions): UIFXRecipe;
+export declare function CardSpotlight(options?: RecipeOptions): UIFXRecipe;
+export declare function MagneticPull(options?: RecipeOptions & { maxPull?: number }): UIFXRecipe;
+export declare function PointerRipple(options?: RecipeOptions): UIFXRecipe;
 
 // ===========================================================
 //  BARREL OBJECTS (back-compat)
@@ -334,6 +343,14 @@ declare const UIFXAllRecipes: {
     FocusHalo: typeof FocusHalo;
     ErrorShake: typeof ErrorShake;
     SuccessBloom: typeof SuccessBloom;
+    TextShimmer: typeof TextShimmer;
+    SpotlightText: typeof SpotlightText;
+    UnderlineDraw: typeof UnderlineDraw;
+    BorderBeam: typeof BorderBeam;
+    TiltShine: typeof TiltShine;
+    CardSpotlight: typeof CardSpotlight;
+    MagneticPull: typeof MagneticPull;
+    PointerRipple: typeof PointerRipple;
 };
 export default UIFXAllRecipes;
 
@@ -341,7 +358,7 @@ 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.
+//  separate and the recipe count is unchanged by skins.
 // ===========================================================
 
 export declare function SwitchSkin(options?: RecipeOptions): HeadlessSkinRecipe;

package/UIFXRecipes.js

@@ -3049,6 +3049,256 @@ export function SuccessBloom(o = {}) {
 }
 
 
+// ===========================================================
+//  E2 DECORATIONS -- text-fx, card, and pointer (decorate mode)
+// ===========================================================
+// Eight decorateUIFX recipes (RECIPE_META type 'decorate'): a canvas wrapped
+// AROUND a live element, never modifying it. A recipe receives only (ctx, dt,
+// now, state, pointer) -- never a DOM handle -- so it cannot read layout and is
+// structurally reflow-safe (the decorate adapter owns every DOM read). Each is
+// zero per-frame alloc (const colours + globalAlpha; NO gradient or string built
+// in tick) and ships a reduced-motion calm path (motionSafe). The text-fx paint
+// OVER the host's own live glyphs -- they never re-render the string. See
+// decisions/0010-text-pointer-card-decorations.md.
+
+/** Text Shimmer (E2 DECORATE) -- a soft light band sweeps across the host's text
+ *  left->right on a loop, painting OVER the live glyphs (never rendering them).
+ *  Reduced motion (U5): a faint static sheen, no sweep. */
+export function TextShimmer(o = {}) {
+    const P = resolveTheme(o, { accent: '#e2e8f0' });
+    let phase = 0;
+    return {
+        tick(c, dt, now, st) {
+            if (st.reducedMotion) {
+                c.fillStyle = P.accent; c.globalAlpha = 0.05;
+                c.fillRect(0, 0, st.w, st.h); c.globalAlpha = 1; return;
+            }
+            const BW = st.w * 0.26, slant = st.h * 0.4;
+            phase = (phase + dt * 0.55) % 1;
+            const cx = -BW + phase * (st.w + BW * 2);
+            c.fillStyle = P.accent;
+            for (let i = 0; i < 3; i++) {
+                const w = BW * (1 - i * 0.3);
+                c.globalAlpha = 0.09 - i * 0.025;
+                c.beginPath();
+                c.moveTo(cx - w + slant, 0); c.lineTo(cx + w + slant, 0);
+                c.lineTo(cx + w - slant, st.h); c.lineTo(cx - w - slant, st.h);
+                c.closePath(); c.fill();
+            }
+            c.globalAlpha = 1;
+        },
+    };
+}
+
+/** Spotlight Text (E2 DECORATE) -- a soft highlight tracks the pointer's x across
+ *  the text line while hovering, a reading light over the live glyphs. Reduced
+ *  motion (U5): a centred static highlight on hover, no follow. */
+export function SpotlightText(o = {}) {
+    const P = resolveTheme(o, { accent: '#fde68a' });
+    let on = 0, sx = -1;
+    return {
+        tick(c, dt, now, st, ptr) {
+            const target = st.hover ? 1 : 0;
+            on = st.reducedMotion ? target : lerp(on, target, dt * 8);
+            if (on < 0.01) return;
+            const tx = st.reducedMotion ? st.w / 2 : clamp(ptr.x, 0, st.w);
+            sx = (st.reducedMotion || sx < 0) ? tx : lerp(sx, tx, dt * 12);
+            const rx = st.w * 0.22, ry = st.h * 0.55, cy = st.h / 2;
+            c.fillStyle = P.accent;
+            for (let i = 3; i >= 1; i--) {
+                c.globalAlpha = on * 0.05 * i;
+                c.beginPath(); c.ellipse(sx, cy, rx * (i / 3), ry * (i / 3), 0, 0, PI2); c.fill();
+            }
+            c.globalAlpha = 1;
+        },
+    };
+}
+
+/** Underline Draw (E2 DECORATE) -- a gradient-free underline wipes in left->right
+ *  when the host gains focus and retracts on blur, with a soft leading dot.
+ *  Distinct from TypewriterField (which grows with typed length). Reduced motion
+ *  (U5): the underline snaps to full-width on focus, no wipe, no dot. */
+export function UnderlineDraw(o = {}) {
+    const P = resolveTheme(o, { accent: '#38bdf8' });
+    let draw = 0;
+    return {
+        tick(c, dt, now, st) {
+            const target = st.focused ? 1 : 0;
+            draw = st.reducedMotion ? target : lerp(draw, target, dt * 9);
+            const y = st.h - 3, x0 = 2, full = st.w - 4;
+            c.strokeStyle = P.accent; c.lineWidth = 2;
+            c.globalAlpha = 0.15; c.beginPath(); c.moveTo(x0, y); c.lineTo(x0 + full, y); c.stroke();
+            if (draw > 0.01) {
+                const x1 = x0 + full * draw;
+                c.globalAlpha = 1; c.beginPath(); c.moveTo(x0, y); c.lineTo(x1, y); c.stroke();
+                if (!st.reducedMotion && draw < 0.995) {
+                    c.fillStyle = P.accent;
+                    c.beginPath(); c.arc(x1, y, 2.5, 0, PI2); c.fill();
+                }
+            }
+            c.globalAlpha = 1;
+        },
+    };
+}
+
+/** Border Beam (E2 DECORATE) -- a bright comet travels around the host's border
+ *  over a faint full outline (Magic UI style). Reduced motion (U5): the static
+ *  faint outline only, no travelling beam. */
+export function BorderBeam(o = {}) {
+    const P = resolveTheme(o, { accent: '#a78bfa' });
+    const R = 10;
+    let t = 0;
+    return {
+        tick(c, dt, now, st) {
+            c.strokeStyle = P.accent; c.globalAlpha = 0.14; c.lineWidth = 1.5;
+            rr(c, 0, 0, st.w, st.h, R); c.stroke();
+            c.globalAlpha = 1;
+            if (st.reducedMotion) return;
+            t = (t + dt * 0.4) % 1;
+            const per = 2 * (st.w + st.h), head = t * per;
+            c.fillStyle = P.accent;
+            for (let i = 0; i < 6; i++) {
+                let d = head - i * (per * 0.012); if (d < 0) d += per;
+                let x, y;
+                if (d < st.w) { x = d; y = 0; }
+                else if (d < st.w + st.h) { x = st.w; y = d - st.w; }
+                else if (d < 2 * st.w + st.h) { x = st.w - (d - st.w - st.h); y = st.h; }
+                else { x = 0; y = st.h - (d - 2 * st.w - st.h); }
+                c.globalAlpha = 0.6 * (1 - i / 6);
+                c.beginPath(); c.arc(x, y, 2.2, 0, PI2); c.fill();
+            }
+            c.globalAlpha = 1;
+        },
+    };
+}
+
+/** Tilt Shine (E2 DECORATE) -- a diagonal sheen sweeps across the card toward the
+ *  pointer while hovering, with the border catching a little light. Clipped to
+ *  the card. Reduced motion (U5): a static centred sheen on hover, no follow. */
+export function TiltShine(o = {}) {
+    const P = resolveTheme(o, { accent: '#ffffff' });
+    const R = 10;
+    let on = 0, sx = 0.5;
+    return {
+        tick(c, dt, now, st, ptr) {
+            const target = st.hover ? 1 : 0;
+            on = st.reducedMotion ? target : lerp(on, target, dt * 8);
+            if (on < 0.01) return;
+            const nx = st.reducedMotion ? 0.5 : clamp(ptr.x / st.w, 0, 1);
+            sx = st.reducedMotion ? nx : lerp(sx, nx, dt * 10);
+            c.save();
+            rr(c, 0, 0, st.w, st.h, R); c.clip();
+            const bx = sx * st.w, bw = st.w * 0.5, slant = st.h * 0.6;
+            c.fillStyle = P.accent;
+            for (let i = 0; i < 3; i++) {
+                const w = bw * (1 - i * 0.3);
+                c.globalAlpha = on * (0.10 - i * 0.03);
+                c.beginPath();
+                c.moveTo(bx - w + slant, 0); c.lineTo(bx + w + slant, 0);
+                c.lineTo(bx + w - slant, st.h); c.lineTo(bx - w - slant, st.h);
+                c.closePath(); c.fill();
+            }
+            c.restore();
+            c.globalAlpha = on * 0.4; c.strokeStyle = P.accent; c.lineWidth = 1.5;
+            rr(c, 0, 0, st.w, st.h, R); c.stroke();
+            c.globalAlpha = 1;
+        },
+    };
+}
+
+/** Card Spotlight (E2 DECORATE) -- a soft radial glow follows the pointer over the
+ *  card surface with the border brightening (Aceternity style). Clipped to the
+ *  card. Reduced motion (U5): a static centred glow on hover, no follow. */
+export function CardSpotlight(o = {}) {
+    const P = resolveTheme(o, { accent: '#38bdf8' });
+    const R = 10;
+    let on = 0, gx = 0, gy = 0, seeded = 0;
+    return {
+        tick(c, dt, now, st, ptr) {
+            const target = st.hover ? 1 : 0;
+            on = st.reducedMotion ? target : lerp(on, target, dt * 7);
+            const tx = st.reducedMotion ? st.w / 2 : clamp(ptr.x, 0, st.w);
+            const ty = st.reducedMotion ? st.h / 2 : clamp(ptr.y, 0, st.h);
+            if (!seeded) { gx = tx; gy = ty; seeded = 1; }
+            else { gx = st.reducedMotion ? tx : lerp(gx, tx, dt * 12); gy = st.reducedMotion ? ty : lerp(gy, ty, dt * 12); }
+            if (on < 0.01) return;
+            c.save();
+            rr(c, 0, 0, st.w, st.h, R); c.clip();
+            const rad = Math.min(st.w, st.h) * 0.9;
+            c.fillStyle = P.accent;
+            for (let i = 5; i >= 1; i--) {
+                c.globalAlpha = on * 0.03 * (6 - i);
+                c.beginPath(); c.arc(gx, gy, rad * (i / 5), 0, PI2); c.fill();
+            }
+            c.restore();
+            c.globalAlpha = on * 0.35; c.strokeStyle = P.accent; c.lineWidth = 1.5;
+            rr(c, 0, 0, st.w, st.h, R); c.stroke();
+            c.globalAlpha = 1;
+        },
+    };
+}
+
+/** Magnetic Pull (E2 DECORATE) -- an accent ring is drawn pulled toward the
+ *  pointer within a radius while hovering; the host itself never moves (a
+ *  decoration reflects, it does not drive). Reduced motion (U5): a centred static
+ *  ring on hover, no pull. */
+export function MagneticPull(o = {}) {
+    const { maxPull = 14 } = o;
+    const P = resolveTheme(o, { accent: '#f472b6' });
+    const R = 10;
+    let bx = 0, by = 0, on = 0;
+    return {
+        tick(c, dt, now, st, ptr) {
+            const target = st.hover ? 1 : 0;
+            on = st.reducedMotion ? target : lerp(on, target, dt * 8);
+            const tx = (st.hover && !st.reducedMotion) ? clamp(ptr.x - st.w / 2, -maxPull, maxPull) : 0;
+            const ty = (st.hover && !st.reducedMotion) ? clamp(ptr.y - st.h / 2, -maxPull, maxPull) : 0;
+            bx = st.reducedMotion ? 0 : lerp(bx, tx, dt * 10);
+            by = st.reducedMotion ? 0 : lerp(by, ty, dt * 10);
+            if (on < 0.01) return;
+            c.save(); c.translate(bx, by);
+            c.strokeStyle = P.accent; c.lineWidth = 1.5; c.globalAlpha = on * 0.9;
+            rr(c, 1, 1, st.w - 2, st.h - 2, R); c.stroke();
+            c.globalAlpha = on * 0.18;
+            rr(c, -3, -3, st.w + 6, st.h + 6, R + 3); c.stroke();
+            c.restore();
+            c.globalAlpha = 1;
+        },
+    };
+}
+
+/** Pointer Ripple (E2 DECORATE) -- concentric rings expand from each pointer press
+ *  on the host, fading as they grow (Material style). Zero-alloc: a fixed
+ *  Float32Array ring pool preallocated in the factory. Reduced motion (U5): a
+ *  brief static ring at the press, no expansion. */
+export function PointerRipple(o = {}) {
+    const P = resolveTheme(o, { accent: '#22d3ee' });
+    const N = 6;
+    const rx = new Float32Array(N), ry = new Float32Array(N), ra = new Float32Array(N);
+    let head = 0;
+    function spawn(x, y) {
+        rx[head] = x; ry[head] = y; ra[head] = 1;
+        head = (head + 1) % N;
+    }
+    return {
+        onClick(x, y) { spawn(x, y); },
+        tick(c, dt, now, st) {
+            c.strokeStyle = P.accent; c.lineWidth = 2;
+            const maxR = Math.max(st.w, st.h) * 0.8;
+            for (let i = 0; i < N; i++) {
+                if (ra[i] <= 0) continue;
+                ra[i] -= dt * (st.reducedMotion ? 3 : 1.4);
+                if (ra[i] <= 0) { ra[i] = 0; continue; }
+                const grow = st.reducedMotion ? 0.2 : (1 - ra[i]);
+                c.globalAlpha = ra[i] * 0.7;
+                c.beginPath(); c.arc(rx[i], ry[i], 4 + grow * maxR, 0, PI2); c.stroke();
+            }
+            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.
@@ -3205,6 +3455,14 @@ export const RECIPES = Object.assign(Object.create(null), {
     focusHalo: FocusHalo,
     errorShake: ErrorShake,
     successBloom: SuccessBloom,
+    textShimmer: TextShimmer,
+    spotlightText: SpotlightText,
+    underlineDraw: UnderlineDraw,
+    borderBeam: BorderBeam,
+    tiltShine: TiltShine,
+    cardSpotlight: CardSpotlight,
+    magneticPull: MagneticPull,
+    pointerRipple: PointerRipple,
 });
 
 /**
@@ -3277,6 +3535,14 @@ export const RECIPE_META = [
     { id: 'focusHalo', name: 'Focus Halo', type: 'decorate', family: 'Form', themeable: true, motionSafe: true },
     { id: 'errorShake', name: 'Error Shake', type: 'decorate', family: 'Form', themeable: true, motionSafe: true },
     { id: 'successBloom', name: 'Success Bloom', type: 'decorate', family: 'Form', themeable: true, motionSafe: true },
+    { id: 'textShimmer', name: 'Text Shimmer', type: 'decorate', family: 'Text', themeable: true, motionSafe: true },
+    { id: 'spotlightText', name: 'Spotlight Text', type: 'decorate', family: 'Text', themeable: true, motionSafe: true },
+    { id: 'underlineDraw', name: 'Underline Draw', type: 'decorate', family: 'Text', themeable: true, motionSafe: true },
+    { id: 'borderBeam', name: 'Border Beam', type: 'decorate', family: 'Card', themeable: true, motionSafe: true },
+    { id: 'tiltShine', name: 'Tilt Shine', type: 'decorate', family: 'Card', themeable: true, motionSafe: true },
+    { id: 'cardSpotlight', name: 'Card Spotlight', type: 'decorate', family: 'Card', themeable: true, motionSafe: true },
+    { id: 'magneticPull', name: 'Magnetic Pull', type: 'decorate', family: 'Pointer', themeable: true, motionSafe: true },
+    { id: 'pointerRipple', name: 'Pointer Ripple', type: 'decorate', family: 'Pointer', themeable: true, motionSafe: true },
 ];
 
 /** Names of every built-in recipe (the keys of RECIPES at load time). */

package/llms.txt

@@ -1,7 +1,7 @@
 # @zakkster/lite-ui-fx
-> Canvas-hijacked UI components with pluggable recipe system. 57 built-in recipes.
+> Canvas-hijacked UI components with pluggable recipe system. 65 built-in recipes.
 
-VERSION 1.11.0
+VERSION 1.12.0
 
 ## Install
 npm i @zakkster/lite-ui-fx
@@ -14,11 +14,12 @@ Recipe = { tick(), init?(), onHover?(), onClick?(), onToggle?(), onDrag?(), dest
 ## Import -- Controller
 import { mountUIFX, decorateUIFX, mountUIFXGroup, UIType, GroupType } from '@zakkster/lite-ui-fx';
 
-## Import -- Recipes (one ./recipes subpath, 57 total, tree-shakeable)
+## Import -- Recipes (one ./recipes subpath, 65 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';
 import { PillTabs, SegmentedSlide, RadioOrbit, BubbleRating } from '@zakkster/lite-ui-fx/recipes'; // U7 group recipes
+import { TextShimmer, SpotlightText, BorderBeam, CardSpotlight, MagneticPull, PointerRipple } from '@zakkster/lite-ui-fx/recipes'; // E2 decorations
 
 ## Import -- Recipe registry (data-driven pickers)
 import { RECIPES, RECIPE_META, RECIPE_NAMES, registerRecipe, mountRecipe } from '@zakkster/lite-ui-fx/recipes';
@@ -109,7 +110,7 @@ skin.destroy()   // remove overlay + observer + listeners; host + handle untouch
 //   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).
-// Skins (SKIN_META, a registry SEPARATE from RECIPES -- the 57-recipe count is
+// Skins (SKIN_META, a registry SEPARATE from RECIPES -- the recipe count is
 //   unchanged). E1: 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). E1b (0009):
@@ -165,7 +166,7 @@ GroupType.RATING  -> radiogroup of N radios (rating semantics); native roving
 //   itemX/itemY/itemW/itemH (Float32Array per-item geometry lanes, read by index).
 //   The scalar value fields (val/toggled/indeterminate) are neutral for a group.
 
-## 57 Built-in Recipes
+## 65 Built-in Recipes
 
 ### Vol. 1 -- 10 recipes
 Toggles: SwarmToggle, LiquidToggle, NeonPulseToggle
@@ -208,6 +209,21 @@ Rating (GroupType.RATING): BubbleRating
 // fakes to real group types, so their native arrow-key selection is now correct;
 // SegmentedSlide is new. Selection is state.index; onSelect(index, state) fires once.
 
+### E2 -- text-fx + pointer + card decorations (decorateUIFX: a canvas AROUND a live element)
+Text (paint OVER live text): TextShimmer, SpotlightText, UnderlineDraw
+Card: BorderBeam, TiltShine, CardSpotlight
+Pointer: MagneticPull, PointerRipple
+// All type 'decorate' (RECIPE_META), motionSafe (a reduced-motion calm path), zero
+// per-frame alloc. They paint OVER a live element and never modify it; a recipe
+// receives only (ctx, dt, now, state, pointer) -- never a DOM handle -- so it cannot
+// read layout and is structurally reflow-safe (the decorate adapter owns every DOM
+// read). No lite-particles/lite-noise: shimmer/glow/beam are const colours +
+// globalAlpha, no gradient built in tick. Text-fx cover <input> AND <textarea>;
+// card/pointer decorate any live element. DEFERRED (decisions/0010): pointer trail +
+// proximity-glow (need lite-particles -> the 1.13.0 phase); ScrambleIn (needs
+// host-owned text -> a future hijack-mode text tranche); Dock magnify (a multi-
+// element row -> a future group/dock vehicle). See 0010.
+
 ## Writing Custom Recipes
 See UIFX-RECIPE-GUIDE.md (included in package).
 
@@ -223,9 +239,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 57 recipes honour { colors, theme:{light,mid,dark}, text, font },
+- Themeable: all 65 recipes honour { colors, theme:{light,mid,dark}, text, font },
   resolved once in init (zero per-frame alloc). RECIPE_META.themeable is true for
-  all 57. A bare mount is byte-identical to pre-theming. Shipped palettes + APCA
+  all 65. 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
@@ -234,7 +250,8 @@ See UIFX-RECIPE-GUIDE.md (included in package).
 - U5 reduced motion: state.reducedMotion (matchMedia, watched) makes calm-path
   recipes render statically -- ErrorShake stops shaking, SwarmToggle/SuccessBloom/
   FocusHalo drop their motion. RECIPE_META.motionSafe is true for EXACTLY the
-  recipes that ship a calm path (SwarmToggle + the 5 decorate recipes today; the
+  recipes that ship a calm path (SwarmToggle + the 5 U4b decorate recipes + the 8 E2
+  decorations = 14 today; the
   rest honestly false until each lands one). mountRecipe warns (not throws) mounting
   a motionSafe:false recipe under active reduce. state.budget (0..1) lets budget-aware
   recipes shed work before frames drop.
@@ -259,7 +276,7 @@ See UIFX-RECIPE-GUIDE.md (included in package).
   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). 11 skins live in a registry
-  (HEADLESS_SKINS/SKIN_META) SEPARATE from the 57 recipes: E1 switch/slider/progress/
+  (HEADLESS_SKINS/SKIN_META) SEPARATE from the 65 recipes: E1 switch/slider/progress/
   rating; E1b (decisions/0009) checkbox (tri-state) + checkbox-group master, select
   (the trigger -- resolving the dropdown/item-6 decision toward a V4 skin; the
   portaled listbox open-state is a follow-on), meter, steps, accordion, skeleton --

package/package.json

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