@zakkster/lite-ui-fx 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,101 @@ 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
+checkboxes as `role=switch` toggles and knobs/progress meters as sliders; U4a
+promotes them to their true native elements (law 1). Additive: a bare mount of
+any existing recipe is unchanged; 50 -> 53 recipes. Decorate mode is U4b.
+
+### Added
+
+- Three `UIType`s, each wrapping the correct native element: `CHECKBOX`
+  (`<input type=checkbox>`, no `role=switch`; indeterminate via `setValue(null)`,
+  exposed as `state.indeterminate`), `PROGRESS` (native `<progress>`,
+  non-interactive, value written by `setValue`; opt-in `announce` adds a
+  visually-hidden `aria-live=polite` region updated at 10% steps), and `KNOB`
+  (`<input type=range>`, arrow keys native, canvas-side `knobMode`
+  `'rotate' | 'vertical'` pointer mapping).
+- `instance.setValue(v)` / `instance.setChecked(b)`: one call syncs the native
+  element, `state`, any PROGRESS announcer, and fires the recipe hook
+  (`onDrag`/`onToggle`) exactly once (a programmatic write emits no native event).
+- Options `knobMode` (KNOB-only) and `announce` (PROGRESS-only), both validated
+  fail-closed (presence on the wrong type throws).
+- Three recipes, born themed and t3-gated: `TickDraw`, `IndeterminateScan`
+  (CHECKBOX, honouring `state.indeterminate`), `LiquidFill` (PROGRESS). Registered
+  in `RECIPES` / `RECIPE_META` / the default export / a new `UIFXRecipes4` barrel.
+- `decisions/0003-element-types.md`; controller `npm test` coverage for the new
+  types; t2 gains the CHECKBOX-no-switch, PROGRESS-value, KNOB-arrows, and
+  `setValue`/`setChecked`-once contracts (A10-A13).
+
+### Changed
+
+- Eight Vol.3 recipes re-homed onto their true types (rippleCheck/morphCheck ->
+  checkbox; volumeKnob/compassKnob -> knob; ringProgress/batteryGauge/signalMeter/
+  uploadProgress -> progress). Re-home is a `RECIPE_META.type` string change only
+  -- no recipe body touched -- so each renders byte-identical to 1.4.0 (proven by
+  `git diff`); new types keep the donor's default geometry (checkbox 64x36,
+  knob/progress 200x28).
+- The mount type guard and `registerRecipe` both derive their valid-type set from
+  `UIType`, so the controller, the registry, and the d.ts cannot drift as types
+  are added; an unknown type still throws (fail closed).
+- Torture: `makeChurn` drives the new types (checkbox like toggle + sweeps
+  indeterminate, knob like slider, progress sweeps value with no hook); t0/t5
+  synthetic batches iterate all six types; the t3 tier now gates 53 recipes
+  (default AND themed). `npm test` 164 pass; torture `gc major=0`, `alloc=0 B/op`.
+- Docs (`llms.txt`, `README.md`, both `.d.ts`) updated to 53 recipes and the new
+  types / options / methods.
+
+### Fixed
+
+- The Vol.3 semantic mis-mounts: a checkbox is no longer announced as a switch
+  (WCAG role match), and progress meters are non-interactive rather than
+  user-draggable sliders.
+
 ## [1.4.0] -- 2026-09-07
 
 The theming pass (U3b), completing U3's third finding (U-06). One option

package/README.md

@@ -21,26 +21,27 @@ https://cdpn.io/pen/debug/yyaPKpB
 ## Live Demo (UI-FX vol3.)
 https://cdpn.io/pen/debug/YPGEaYY
 
-**50 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
 - **Sliders** -- Spark, Cosmic Void, Laser, Aurora, Wave, Elastic Band, Gravity
 - **Knobs** -- Volume dial, Compass needle
-- **Progress** -- Ring, Battery, Signal meter
+- **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)
+- **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 50 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 50 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 50 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';
@@ -136,7 +137,7 @@ import { RECIPES, RECIPE_META, RECIPE_NAMES, registerRecipe, mountRecipe } from
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `container` | `HTMLElement` | Parent to mount into |
-| `type` | `'button' \| 'toggle' \| 'slider'` | Determines native element type |
+| `type` | `'button' \| 'toggle' \| 'slider' \| 'checkbox' \| 'progress' \| 'knob'` | Determines native element type |
 | `recipeFactory` | `() => Recipe` | Factory function (controller calls it) |
 | `options.width` | `number` | Element width (auto from type if omitted) |
 | `options.height` | `number` | Element height |
@@ -145,8 +146,48 @@ import { RECIPES, RECIPE_META, RECIPE_NAMES, registerRecipe, mountRecipe } from
 | `options.value` | `number` | Slider initial value, 0..1 (default 0.5); out-of-range throws |
 | `options.checked` | `boolean` | Toggle initial state (default false) |
 | `options.disabled` | `boolean` | Disables the native element; sets `state.disabled` |
+| `options.knobMode` | `'rotate' \| 'vertical'` | KNOB only: pointer-to-value mapping (default `'rotate'`); wrong type throws |
+| `options.announce` | `boolean` | PROGRESS only: opt-in `aria-live` announcements at 10% steps; wrong type throws |
 
-Returns `{ el, canvas, wrapper, state, destroy() }`.
+Recipe theming options (`seed`, `colors`, `theme`, `text`, `font`) are also
+accepted and forwarded to the recipe -- see `llms.txt` for the full option surface.
+
+Returns `{ el, canvas, wrapper, state, setValue(v), setChecked(b), destroy() }`.
+
+- `setValue(v)` -- SLIDER/KNOB/PROGRESS: set `v` in `0..1` (updates the element +
+  `state.val`, fires `onDrag` once). CHECKBOX: `setValue(null)` sets indeterminate.
+- `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
 
@@ -155,6 +196,13 @@ Returns `{ el, canvas, wrapper, state, destroy() }`.
 | `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` (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)
 
@@ -163,13 +211,16 @@ Returns `{ el, canvas, wrapper, state, destroy() }`.
     hover: boolean;      // Pointer inside element
     active: boolean;     // Pointer pressed
     focused: boolean;    // Keyboard focus
-    toggled: boolean;    // Checkbox state
+    toggled: boolean;    // Checkbox/toggle state
+    indeterminate: boolean; // CHECKBOX only: native indeterminate (setValue(null))
     disabled: boolean;   // Disabled via options.disabled
     val: number;         // Slider value (0-1)
     w: number;           // Element width
     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
 }
 ```
 
@@ -180,7 +231,7 @@ Returns `{ el, canvas, wrapper, state, 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** | **50 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
 
@@ -213,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

@@ -1,11 +1,17 @@
 export declare const VERSION: string;
 
-export type UITypeValue = 'button' | 'toggle' | 'slider';
+export type UITypeValue = 'button' | 'toggle' | 'slider' | 'checkbox' | 'progress' | 'knob';
 
 export declare const UIType: Readonly<{
     BUTTON: 'button';
     TOGGLE: 'toggle';
     SLIDER: 'slider';
+    /** Plain checkbox (no role=switch); indeterminate via setValue(null). */
+    CHECKBOX: 'checkbox';
+    /** Native <progress>, non-interactive; value driven by setValue. */
+    PROGRESS: 'progress';
+    /** <input type=range>; arrows native, pointer mapped by knobMode. */
+    KNOB: 'knob';
 }>;
 
 export interface UIFXState {
@@ -13,12 +19,19 @@ export interface UIFXState {
     active: boolean;
     focused: boolean;
     toggled: boolean;
+    /** CHECKBOX only: the native indeterminate state (set via setValue(null)). */
+    indeterminate: boolean;
     disabled: boolean;
     val: number;
     w: number;
     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 {
@@ -72,6 +85,26 @@ export interface MountOptions {
     text?: string;
     /** Canvas font string; falls back to the recipe's historical font. */
     font?: string;
+    /** KNOB only: pointer-to-value mapping (default 'rotate'). Throws on any other type. */
+    knobMode?: 'rotate' | 'vertical';
+    /** PROGRESS only: opt-in aria-live announcements at 10% steps. Throws on any other type. */
+    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 {
@@ -80,6 +113,21 @@ export interface UIFXInstance {
     wrapper: HTMLDivElement;
     state: UIFXState;
 
+    /**
+     * Set a valued control (SLIDER/KNOB/PROGRESS) to v in [0,1]: updates the
+     * native element, state.val, any PROGRESS announcer, and fires onDrag once.
+     * For a CHECKBOX, setValue(null) sets the indeterminate state. Throws on the
+     * wrong element type or an out-of-range value.
+     */
+    setValue(v: number | null): void;
+
+    /**
+     * Set a TOGGLE/CHECKBOX checked state: updates the native element,
+     * state.toggled, clears indeterminate, and fires onToggle exactly once.
+     * Throws on any other element type.
+     */
+    setChecked(b: boolean): void;
+
     destroy(): void;
 }
 
@@ -90,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;