@zakkster/lite-ui-fx 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -5,7 +5,97 @@ All notable changes to `@zakkster/lite-ui-fx` are documented here.
 The format follows Keep a Changelog; this project adheres to Semantic
 Versioning.
 
-## [1.1.0] -- unreleased
+## [1.3.0] -- 2026-09-07
+
+The recipe sweep (U3), first pass: zero per-frame allocation across all 50
+recipes (U-03) and geometry derived from state (U-05). The `zero-gc` keyword is
+true for the first time. Theming (U-06) and the blueprint-doc rewrite are a
+deferred follow-up; `themeable` / `motionSafe` stay `false`.
+
+### Fixed
+
+- U-03 (zero-GC): every built-in recipe now runs its per-frame body -- idle and
+  under interaction -- without allocating. Per-frame `rgba(...,${alpha})` colour
+  strings became a const colour + `globalAlpha`; recipes whose RGB varies with a
+  value (FlameCounter, HeatMap, DayNightToggle) use a precomputed colour LUT;
+  particle `push`/`splice` pools became fixed preallocated pools with a live
+  flag; per-frame gradients moved to `init` (VolumeKnob / RingProgress build
+  once; LaserSlider / AuroraSlider build a reference gradient in `init` and scale
+  it to the fill, AuroraSlider cycling a bounded set of phase gradients); value
+  labels read a precomputed `PCT` table or a change-detection cache instead of
+  building `${n}%` / `String(n)` / `.toFixed()` per frame; the GlitchButton
+  per-tick closure and the CompassKnob / ReactionPicker per-frame array literals
+  were hoisted; `setLineDash([4,3])` uses one shared module-level array.
+- U-05 (size-true): spawn and inset positions derive from `st.w` -- NeonPulse
+  ring origin (was `46`/`18`), SparkSlider and ScratchReveal spark spawn (was
+  `val * 200`), BubbleRating bubble gap (was `200 / 5`).
+
+### Added
+
+- `test/torture/t3-frame-alloc.mjs` (+ `t3-scan.mjs`): the U-03 gate. It runs in
+  a child process under `--max-semi-space-size=1` and gates each recipe on
+  `major === 0`, zero gradient constructions after `init`, and a bounded count of
+  distinct fill/stroke colour strings (a per-frame colour template mints
+  hundreds; a const palette or LUT a few dozen). Wired into `torture.mjs`.
+
+### Changed
+
+- Harness: the recording `Ctx2DStub` backs numeric context properties
+  (`globalAlpha`, `lineWidth`, ...) with a `Float64Array` so writing a
+  non-integer never boxes a HeapNumber -- the gate measures the recipe, not the
+  stub. `gcGate` gained a warmup phase and an optional zero-alloc churn driver.
+- `mountUIFX` forwards the validated options to the recipe factory, so a recipe
+  can read its own config (a no-arg or wrapped factory ignores the argument).
+  This is inert until the U-06 theming pass uses it.
+
+## [1.2.0] -- 2026-09-06
+
+Recipes ship as code (U-13). The three GitHub-only recipe volumes are
+consolidated into one `UIFXRecipes.js` at the package root, exposed as the
+`./recipes` subpath export behind a registry. No recipe body changes -- the
+zero-GC / size-true / theming sweep is U3.
+
+### Added
+
+- `./recipes` subpath export: all 50 recipes ship in one `UIFXRecipes.js`
+  (with `UIFXRecipes.d.ts`), versioned, typed, and tree-shakeable
+  (`sideEffects: false`). `UIFX-RECIPE-GUIDE.md` moves to the package root and
+  ships as well.
+- Recipe registry (ported from `@zakkster/lite-scratch-fx`): `RECIPES`
+  (null-prototype, id -> factory), `RECIPE_META` (`{ id, name, type, family,
+  themeable, motionSafe }`; `themeable` and `motionSafe` are `false` for all
+  until U3), `RECIPE_NAMES` (frozen), and `registerRecipe(id, factory, meta)`
+  with an in-place meta-merge.
+- `mountRecipe(container, id, options?)`: resolves the id fail closed (an
+  unknown id throws with a did-you-mean; a non-string id gets the same clean
+  message), asserts any `options.type` matches the recipe's declared type, then
+  mounts via `mountUIFX`.
+- Torture: `t0-lifecycle` and `t1-degenerate` iterate `RECIPE_META`, so all 50
+  recipes are mounted, exercised, and destroyed by construction. New
+  `test/registry.test.mjs` (registry + `mountRecipe` contract + a boundary
+  matrix) and `test/treeshake.test.mjs` (an esbuild proof that importing one
+  recipe drops the others).
+
+### Changed
+
+- Fail closed on the element type: `mountUIFX` now throws on any `type` other
+  than `UIType.BUTTON` / `TOGGLE` / `SLIDER` (an unknown type previously became
+  a button silently), and `registerRecipe` rejects a recipe with no valid type
+  before any mutation.
+- The recipes are no longer a GitHub ZIP / copy-paste. `README.md` and
+  `llms.txt` document the `./recipes` import and drop the "not included in the
+  npm package" wording.
+- `package.json`: `exports["./recipes"]` added; `files[]` ships
+  `UIFXRecipes.js`, `UIFXRecipes.d.ts`, and `UIFX-RECIPE-GUIDE.md`; `esbuild`
+  added as a devDependency (the tree-shake proof only -- not shipped).
+- Decision recorded in `decisions/0001-recipes-position.md`.
+
+### Removed
+
+- The `recipes/` directory (three volumes plus their `.d.ts`). Their exports
+  are unchanged and now come from the root `UIFXRecipes.js`.
+
+## [1.1.0] -- 2026-09-06
 
 Controller correctness: the two S1 defects (U-01, U-02) and three
 controller-level S3s (U-09, U-10, U-11). No visual change at default mounts.

package/README.md

@@ -40,26 +40,22 @@ https://cdpn.io/pen/debug/YPGEaYY
 
 Every recipe is zero-GC, uses `dt`-based animation, and includes accessibility indicators (focus rings, state labels).
 
-`@zakkster/lite-ui-fx` ships only the core controller on npm (zero bloat).
-All visual effects live in the GitHub repo as **recipes**.
+All 50 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.
 
-**Recipe Collections:**
-- Vol. 1 (10 recipes):
-  https://github.com/PeshoVurtoleta/lite-ui-fx/blob/main/recipes/UIFXRecipes.js
-- Vol. 2 (20 recipes):
-  https://github.com/PeshoVurtoleta/lite-ui-fx/blob/main/recipes/UIFXRecipes2.js
-- Vol. 3 (20 recipes):
-  https://github.com/PeshoVurtoleta/lite-ui-fx/blob/main/recipes/UIFXRecipes3.js
-
-**How to write your own:**
-https://github.com/PeshoVurtoleta/lite-ui-fx/blob/main/recipes/UIFX-RECIPE-GUIDE.md
+```javascript
+import { mountUIFX, UIType } from '@zakkster/lite-ui-fx';
+import { SwarmToggle } from '@zakkster/lite-ui-fx/recipes';
+```
 
-Recipes are **optional**, **open-source**, and **not included in the npm package**
-to keep the install size tiny (<2 KB).
-You can copy/paste any recipe into your project or use them as inspiration.
+The `./recipes` entry also exports a registry for data-driven pickers:
+`RECIPES` (id -> factory), `RECIPE_META` (`{ id, name, type, family }`),
+`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.
 
-Download all recipes as a ZIP
-https://github.com/PeshoVurtoleta/lite-ui-fx/archive/refs/heads/main.zip
+**How to write your own:** see [UIFX-RECIPE-GUIDE.md](UIFX-RECIPE-GUIDE.md), shipped in the package.
 
 Part of the [@zakkster/lite-*](https://www.npmjs.com/org/zakkster) ecosystem.
 
@@ -69,15 +65,15 @@ Part of the [@zakkster/lite-*](https://www.npmjs.com/org/zakkster) ecosystem.
 npm i @zakkster/lite-ui-fx
 ```
 
-> Looking for the visual effects?
-> Recipes live in the GitHub repo -- not in the npm package -- to keep the library tiny.
+> The 50 recipes ship in the same package on the `./recipes` subpath and
+> tree-shake, so importing one adds only that one.
 
 
 ## Quick Start
 
 ```javascript
 import { mountUIFX, UIType } from '@zakkster/lite-ui-fx';
-import { SwarmToggle } from './recipes/UIFXRecipes.js';
+import { SwarmToggle } from '@zakkster/lite-ui-fx/recipes';
 
 // Mount a canvas-rendered toggle onto a container
 const instance = mountUIFX(
@@ -101,17 +97,13 @@ instance.destroy();
 // Controller (always needed)
 import { mountUIFX, UIType } from '@zakkster/lite-ui-fx';
 
-// Recipes are NOT included in the npm package.
-// Copy them from the GitHub repo into your own ./recipes folder:
-
-// Vol. 1 -- 10 recipes (toggles, buttons, sliders)
-import { SwarmToggle, MagneticButton, SparkSlider } from './recipes/UIFXRecipes.js';
-
-// Vol. 2 -- 20 recipes (+ loaders, checkboxes, counters, rating)
-import { PendulumToggle, HeartbeatButton, RippleCheck } from './recipes/UIFXRecipes2.js';
+// All 50 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';
 
-// Vol. 3 -- 20 recipes (knobs, progress, controls, indicators, mood, feedback, fun)
-import { VolumeKnob, WaterLevel, TimerCountdown } from './recipes/UIFXRecipes3.js';
+// Registry surface for data-driven pickers:
+import { RECIPES, RECIPE_META, RECIPE_NAMES, registerRecipe, mountRecipe } from '@zakkster/lite-ui-fx/recipes';
 ```
 
 ## How It Works
@@ -192,7 +184,7 @@ Returns `{ el, canvas, wrapper, state, destroy() }`.
 
 ## Writing Custom Recipes
 
-See the full [UIFX-RECIPE-GUIDE.md](recipes/UIFX-RECIPE-GUIDE.md) (included in the package).
+See the full [UIFX-RECIPE-GUIDE.md](UIFX-RECIPE-GUIDE.md) (included in the package).
 
 Minimal recipe:
 
@@ -226,7 +218,7 @@ Full TypeScript declarations are included for:
 - `UIFXPointer`
 - `UIFXRecipe`
 
-(Recipes are not part of the npm package, so their types are not included.)
+Recipe types ship too, on the `./recipes` subpath (`UIFXRecipes.d.ts`).
 
 
 ## LLM-Friendly Documentation

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.1.0';
+export const VERSION = '1.3.0';
 
 // ---------------------------------------------------------
 //  SHARED TICKER (ref-counted, one RAF for all UI components)
@@ -177,6 +177,13 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
         throw new Error('mountUIFX: container must be a DOM element');
     }
 
+    // 1b. type: exactly one of the three known element types. An unknown or
+    //     undefined type is an Error here, never a silent default to a button
+    //     (fail closed -- the type selects the native element).
+    if (type !== UIType.BUTTON && type !== UIType.TOGGLE && type !== UIType.SLIDER) {
+        throw new Error('mountUIFX: type must be UIType.BUTTON, UIType.TOGGLE, or UIType.SLIDER');
+    }
+
     // 2. options: unknown keys -> did-you-mean; value/checked/disabled
     //    validated and coerced HERE, before any element exists.
     for (const k in options) {
@@ -206,7 +213,10 @@ export function mountUIFX(container, type, recipeFactory, options = {}) {
 
     // 4. recipe object + hooks. Created now so a bad recipe throws BEFORE any
     //    DOM/refcount side effect; .init is deferred to phase 2 (needs ctx).
-    const recipe = recipeFactory();
+    //    The validated options are forwarded so a recipe factory can read its
+    //    own visual config and default a canvas `text` to the accessible
+    //    `label`; a zero-arg or user-wrapped factory ignores the argument.
+    const recipe = recipeFactory(options);
     if (!recipe || typeof recipe !== 'object') {
         throw new Error('mountUIFX: recipe must be an object');
     }

package/UIFXRecipes.d.ts

@@ -0,0 +1,253 @@
+import type { UIFXRecipe, UIFXInstance, MountOptions } from './UIFXController';
+
+// ===========================================================
+//  RECIPE FACTORIES (all 50)
+// ===========================================================
+
+// -- Vol.1: Toggles --
+export declare function SwarmToggle(options?: { seed?: number; count?: number }): UIFXRecipe;
+export declare function LiquidToggle(): UIFXRecipe;
+export declare function NeonPulseToggle(): UIFXRecipe;
+
+// -- Vol.1: Buttons --
+export declare function MagneticButton(options?: { maxPull?: number }): UIFXRecipe;
+export declare function ShatterButton(options?: { seed?: number }): UIFXRecipe;
+export declare function ConfettiButton(options?: { seed?: number; colors?: string[] }): UIFXRecipe;
+export declare function GlitchButton(options?: { seed?: number }): UIFXRecipe;
+
+// -- Vol.1: Sliders --
+export declare function SparkSlider(options?: { seed?: number; color?: string }): UIFXRecipe;
+export declare function CosmicSlider(options?: { seed?: number; dustCount?: number }): UIFXRecipe;
+export declare function LaserSlider(): UIFXRecipe;
+
+// -- Vol.2: Toggles --
+export declare function PendulumToggle(): UIFXRecipe;
+export declare function CircuitToggle(options?: { seed?: number }): UIFXRecipe;
+export declare function LightningToggle(options?: { seed?: number }): UIFXRecipe;
+export declare function DNAToggle(): UIFXRecipe;
+
+// -- Vol.2: Buttons --
+export declare function HeartbeatButton(options?: { seed?: number }): UIFXRecipe;
+export declare function BreathingButton(): UIFXRecipe;
+export declare function InkSplashButton(options?: { seed?: number }): UIFXRecipe;
+export declare function PixelDissolveButton(options?: { seed?: number; cols?: number; rows?: number }): UIFXRecipe;
+export declare function FireworkButton(options?: { seed?: number }): UIFXRecipe;
+
+// -- Vol.2: Sliders --
+export declare function AuroraSlider(): UIFXRecipe;
+export declare function WaveSlider(options?: { seed?: number }): UIFXRecipe;
+export declare function ElasticBandSlider(): UIFXRecipe;
+export declare function GravitySlider(): UIFXRecipe;
+
+// -- Vol.2: Loaders --
+export declare function OrbitLoader(): UIFXRecipe;
+export declare function HelixLoader(): UIFXRecipe;
+
+// -- Vol.2: Checkboxes --
+export declare function RippleCheck(): UIFXRecipe;
+export declare function MorphCheck(): UIFXRecipe;
+
+// -- Vol.2: Counters --
+export declare function FlameCounter(options?: { seed?: number }): UIFXRecipe;
+export declare function GlitchCounter(options?: { seed?: number }): UIFXRecipe;
+
+// -- Vol.2: Rating --
+export declare function BubbleRating(options?: { seed?: number }): UIFXRecipe;
+
+// -- Vol.3: Knobs --
+export declare function VolumeKnob(): UIFXRecipe;
+export declare function CompassKnob(): UIFXRecipe;
+
+// -- Vol.3: Progress --
+export declare function RingProgress(options?: { seed?: number }): UIFXRecipe;
+export declare function BatteryGauge(): UIFXRecipe;
+export declare function SignalMeter(): UIFXRecipe;
+
+// -- Vol.3: Controls --
+export declare function PillTabs(): UIFXRecipe;
+export declare function Stepper(): UIFXRecipe;
+export declare function RadioOrbit(): UIFXRecipe;
+
+// -- Vol.3: Indicators --
+export declare function PasswordStrength(): UIFXRecipe;
+export declare function WaterLevel(): UIFXRecipe;
+export declare function HeatMap(options?: { seed?: number }): UIFXRecipe;
+
+// -- Vol.3: Mood --
+export declare function DayNightToggle(options?: { seed?: number }): UIFXRecipe;
+export declare function ReactionPicker(): UIFXRecipe;
+export declare function NotificationBell(): UIFXRecipe;
+
+// -- Vol.3: Feedback --
+export declare function TypewriterField(): UIFXRecipe;
+export declare function SoundWaveBtn(): UIFXRecipe;
+export declare function UploadProgress(): UIFXRecipe;
+
+// -- Vol.3: Fun --
+export declare function ScratchReveal(options?: { seed?: number }): UIFXRecipe;
+export declare function TimerCountdown(): UIFXRecipe;
+export declare function PullRefresh(): UIFXRecipe;
+
+// ===========================================================
+//  BARREL OBJECTS (back-compat)
+// ===========================================================
+
+export declare const UIFXRecipes: {
+    SwarmToggle: typeof SwarmToggle;
+    LiquidToggle: typeof LiquidToggle;
+    NeonPulseToggle: typeof NeonPulseToggle;
+    MagneticButton: typeof MagneticButton;
+    ShatterButton: typeof ShatterButton;
+    ConfettiButton: typeof ConfettiButton;
+    GlitchButton: typeof GlitchButton;
+    SparkSlider: typeof SparkSlider;
+    CosmicSlider: typeof CosmicSlider;
+    LaserSlider: typeof LaserSlider;
+};
+
+export declare const UIFXRecipes2: {
+    PendulumToggle: typeof PendulumToggle;
+    CircuitToggle: typeof CircuitToggle;
+    LightningToggle: typeof LightningToggle;
+    DNAToggle: typeof DNAToggle;
+    HeartbeatButton: typeof HeartbeatButton;
+    BreathingButton: typeof BreathingButton;
+    InkSplashButton: typeof InkSplashButton;
+    PixelDissolveButton: typeof PixelDissolveButton;
+    FireworkButton: typeof FireworkButton;
+    AuroraSlider: typeof AuroraSlider;
+    WaveSlider: typeof WaveSlider;
+    ElasticBandSlider: typeof ElasticBandSlider;
+    GravitySlider: typeof GravitySlider;
+    OrbitLoader: typeof OrbitLoader;
+    HelixLoader: typeof HelixLoader;
+    RippleCheck: typeof RippleCheck;
+    MorphCheck: typeof MorphCheck;
+    FlameCounter: typeof FlameCounter;
+    GlitchCounter: typeof GlitchCounter;
+    BubbleRating: typeof BubbleRating;
+};
+
+export declare const UIFXRecipes3: {
+    VolumeKnob: typeof VolumeKnob;
+    CompassKnob: typeof CompassKnob;
+    RingProgress: typeof RingProgress;
+    BatteryGauge: typeof BatteryGauge;
+    SignalMeter: typeof SignalMeter;
+    PillTabs: typeof PillTabs;
+    Stepper: typeof Stepper;
+    RadioOrbit: typeof RadioOrbit;
+    PasswordStrength: typeof PasswordStrength;
+    WaterLevel: typeof WaterLevel;
+    HeatMap: typeof HeatMap;
+    DayNightToggle: typeof DayNightToggle;
+    ReactionPicker: typeof ReactionPicker;
+    NotificationBell: typeof NotificationBell;
+    TypewriterField: typeof TypewriterField;
+    SoundWaveBtn: typeof SoundWaveBtn;
+    UploadProgress: typeof UploadProgress;
+    ScratchReveal: typeof ScratchReveal;
+    TimerCountdown: typeof TimerCountdown;
+    PullRefresh: typeof PullRefresh;
+};
+
+// ===========================================================
+//  RECIPE REGISTRY
+// ===========================================================
+
+export type RecipeType = 'toggle' | 'button' | 'slider';
+
+export type RecipeFactory = (options?: Record<string, unknown>) => UIFXRecipe;
+
+export interface RecipeMeta {
+    id: string;
+    name: string;
+    type: RecipeType;
+    family: string;
+    themeable: boolean;
+    motionSafe: boolean;
+}
+
+/** Every recipe factory keyed by id. Null-prototype map. */
+export declare const RECIPES: { [id: string]: RecipeFactory };
+
+/** Live metadata array, one row per registered recipe. */
+export declare const RECIPE_META: RecipeMeta[];
+
+/** Frozen list of the built-in recipe ids at load time. */
+export declare const RECIPE_NAMES: readonly string[];
+
+/** Register a custom recipe, or override a built-in. Returns the factory. */
+export declare function registerRecipe(
+    id: string,
+    factory: RecipeFactory,
+    meta?: Partial<Omit<RecipeMeta, 'id'>>,
+): RecipeFactory;
+
+/**
+ * Resolve a recipe id to its factory + declared type and mount it via mountUIFX.
+ * Fail closed: unknown id or a conflicting options.type throws.
+ */
+export declare function mountRecipe(
+    container: HTMLElement,
+    id: string,
+    options?: MountOptions & { type?: RecipeType },
+): UIFXInstance;
+
+// ===========================================================
+//  DEFAULT EXPORT -- combined all-50 namespace
+// ===========================================================
+
+declare const UIFXAllRecipes: {
+    SwarmToggle: typeof SwarmToggle;
+    LiquidToggle: typeof LiquidToggle;
+    NeonPulseToggle: typeof NeonPulseToggle;
+    MagneticButton: typeof MagneticButton;
+    ShatterButton: typeof ShatterButton;
+    ConfettiButton: typeof ConfettiButton;
+    GlitchButton: typeof GlitchButton;
+    SparkSlider: typeof SparkSlider;
+    CosmicSlider: typeof CosmicSlider;
+    LaserSlider: typeof LaserSlider;
+    PendulumToggle: typeof PendulumToggle;
+    CircuitToggle: typeof CircuitToggle;
+    LightningToggle: typeof LightningToggle;
+    DNAToggle: typeof DNAToggle;
+    HeartbeatButton: typeof HeartbeatButton;
+    BreathingButton: typeof BreathingButton;
+    InkSplashButton: typeof InkSplashButton;
+    PixelDissolveButton: typeof PixelDissolveButton;
+    FireworkButton: typeof FireworkButton;
+    AuroraSlider: typeof AuroraSlider;
+    WaveSlider: typeof WaveSlider;
+    ElasticBandSlider: typeof ElasticBandSlider;
+    GravitySlider: typeof GravitySlider;
+    OrbitLoader: typeof OrbitLoader;
+    HelixLoader: typeof HelixLoader;
+    RippleCheck: typeof RippleCheck;
+    MorphCheck: typeof MorphCheck;
+    FlameCounter: typeof FlameCounter;
+    GlitchCounter: typeof GlitchCounter;
+    BubbleRating: typeof BubbleRating;
+    VolumeKnob: typeof VolumeKnob;
+    CompassKnob: typeof CompassKnob;
+    RingProgress: typeof RingProgress;
+    BatteryGauge: typeof BatteryGauge;
+    SignalMeter: typeof SignalMeter;
+    PillTabs: typeof PillTabs;
+    Stepper: typeof Stepper;
+    RadioOrbit: typeof RadioOrbit;
+    PasswordStrength: typeof PasswordStrength;
+    WaterLevel: typeof WaterLevel;
+    HeatMap: typeof HeatMap;
+    DayNightToggle: typeof DayNightToggle;
+    ReactionPicker: typeof ReactionPicker;
+    NotificationBell: typeof NotificationBell;
+    TypewriterField: typeof TypewriterField;
+    SoundWaveBtn: typeof SoundWaveBtn;
+    UploadProgress: typeof UploadProgress;
+    ScratchReveal: typeof ScratchReveal;
+    TimerCountdown: typeof TimerCountdown;
+    PullRefresh: typeof PullRefresh;
+};
+export default UIFXAllRecipes;