@zakkster/lite-ui-fx 1.0.0

package/README.md

@@ -0,0 +1,232 @@
+# @zakkster/lite-ui-fx
+
+[![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)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@zakkster/lite-ui-fx?style=for-the-badge)](https://bundlephobia.com/result?p=@zakkster/lite-ui-fx)
+[![npm downloads](https://img.shields.io/npm/dm/@zakkster/lite-ui-fx?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-ui-fx)
+[![npm total downloads](https://img.shields.io/npm/dt/@zakkster/lite-ui-fx?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-ui-fx)
+![TypeScript](https://img.shields.io/badge/TypeScript-Types-informational)
+![Dependencies](https://img.shields.io/badge/dependencies-3-brightgreen)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
+
+## ✨ What is lite-ui-fx?
+
+`@zakkster/lite-ui-fx` overlays a DPR-aware canvas on native HTML elements and renders them with pluggable, physics-driven **recipes**. The native element stays invisible but fully accessible — handling focus, keyboard, and pointer events. The canvas handles all visuals.
+
+## 🎬 Live Demo (UI-FX)
+https://cdpn.io/pen/debug/RNGjMjQ
+
+## 🎬 Live Demo (UI-FX vol.2)
+https://cdpn.io/pen/debug/yyaPKpB
+
+## 🎬 Live Demo (UI-FX vol3.)
+https://cdpn.io/pen/debug/YPGEaYY
+
+**50 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
+- 🔀 **Controls** — Pill tabs, Stepper, Radio orbit
+- 📈 **Indicators** — Password strength, Water level, Heat map
+- 🌗 **Mood** — Day/night, Reaction picker, Notification bell
+- 💬 **Feedback** — Typewriter, Sound wave, Upload progress
+- 🎮 **Fun** — Scratch reveal, Timer countdown, Pull refresh
+- ✅ **Checkboxes** — Ripple, Morph (X → ✓)
+- 🔄 **Loaders** — Orbit planets, DNA helix
+- 🔢 **Counters** — Flame heat, Glitch signal
+- ⭐ **Rating** — Bubble inflate
+
+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**.
+
+📁 **Recipe Collections:**  
+- Vol. 1 (10 recipes):  
+  https://github.com/PeshoVurtoleta/lite-ui-fx/blob/main/UIFXRecipes.js  
+- Vol. 2 (20 recipes):  
+  https://github.com/PeshoVurtoleta/lite-ui-fx/blob/main/UIFXRecipes2.js  
+- Vol. 3 (20 recipes):  
+  https://github.com/PeshoVurtoleta/lite-ui-fx/blob/main/UIFXRecipes3.js  
+
+📘 **How to write your own:**  
+https://github.com/PeshoVurtoleta/lite-ui-fx/blob/main/UIFX-RECIPE-GUIDE.md
+
+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.
+
+📦 Download all recipes as a ZIP  
+https://github.com/PeshoVurtoleta/lite-ui-fx/archive/refs/heads/main.zip
+
+Part of the [@zakkster/lite-*](https://www.npmjs.com/org/zakkster) ecosystem.
+
+## 🚀 Install
+
+```bash
+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.
+
+
+## 🕹️ Quick Start
+
+```javascript
+import { mountUIFX, UIType } from '@zakkster/lite-ui-fx';
+import { SwarmToggle } from './recipes/UIFXRecipes.js';
+
+// Mount a canvas-rendered toggle onto a container
+const instance = mountUIFX(
+    document.getElementById('my-container'),
+    UIType.TOGGLE,
+    SwarmToggle,
+    { label: 'Sound effects', width: 64, height: 36 }
+);
+
+// The native checkbox is invisible but fully accessible.
+// Screen readers see: <input type="checkbox" role="switch" aria-label="Sound effects">
+// Canvas renders: 150 particles forming a knob that explodes on toggle.
+
+// Cleanup when done:
+instance.destroy();
+```
+
+## 📦 Import Map
+
+```javascript
+// 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';
+
+// Vol. 3 — 20 recipes (knobs, progress, controls, indicators, mood, feedback, fun)
+import { VolumeKnob, WaterLevel, TimerCountdown } from './recipes/UIFXRecipes3.js';
+```
+
+## 🧠 How It Works
+
+```
+┌──────────────────────────────────────────────────┐
+│  mountUIFX(container, type, recipeFactory, opts)  │
+│                                                    │
+│  ┌──── Wrapper div ────────────────────────────┐  │
+│  │                                              │  │
+│  │  Native element (opacity:0, z-index:2)       │  │
+│  │  → receives pointer, keyboard, focus events  │  │
+│  │  → accessible to screen readers              │  │
+│  │                                              │  │
+│  │  Canvas overlay (z-index:1, DPR-scaled)      │  │
+│  │  → recipe.tick() renders every frame         │  │
+│  │  → padding allows particle overflow          │  │
+│  │                                              │  │
+│  └──────────────────────────────────────────────┘  │
+│                                                    │
+│  Shared Ticker (ref-counted, one RAF for all)      │
+│  AbortController (all events cleaned on destroy)   │
+└──────────────────────────────────────────────────┘
+```
+
+## ⚙️ API
+
+### `mountUIFX(container, type, recipeFactory, options?)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `container` | `HTMLElement` | Parent to mount into |
+| `type` | `'button' \| 'toggle' \| 'slider'` | 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 |
+| `options.padding` | `number` | Canvas overflow (default: 40px) |
+| `options.label` | `string` | Accessible label (aria-label) |
+
+Returns `{ el, canvas, wrapper, state, destroy() }`.
+
+### Element Types
+
+| Type | Native Element | Recipe Hooks | 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) |
+
+### State Object (provided to `tick()` every frame)
+
+```typescript
+{
+    hover: boolean;      // Pointer inside element
+    active: boolean;     // Pointer pressed
+    focused: boolean;    // Keyboard focus
+    toggled: boolean;    // Checkbox state
+    val: number;         // Slider value (0–1)
+    w: number;           // Element width
+    h: number;           // Element height
+    padding: number;     // Canvas padding
+    dpr: number;         // Device pixel ratio
+}
+```
+
+## 📊 Comparison
+
+| Library | Size | Approach | Recipes | A11y | Install |
+|---------|------|----------|---------|------|---------|
+| 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** | **30 built-in** | **Native + visual** | **`npm i @zakkster/lite-ui-fx`** |
+
+## 🎨 Writing Custom Recipes
+
+See the full [UIFX-RECIPE-GUIDE.md](recipes/UIFX-RECIPE-GUIDE.md) (included in the package).
+
+Minimal recipe:
+
+```javascript
+export function MyButton() {
+    let pressScale = 1;
+    return {
+        onClick() { pressScale = 0.85; },
+        tick(ctx, dt, now, state) {
+            pressScale += (1 - pressScale) * dt * 10;
+            ctx.translate(state.w/2, state.h/2);
+            ctx.scale(pressScale, pressScale);
+            ctx.translate(-state.w/2, -state.h/2);
+            ctx.fillStyle = state.hover ? '#a78bfa' : '#333';
+            ctx.beginPath(); ctx.roundRect(0, 0, state.w, state.h, 10); ctx.fill();
+            ctx.fillStyle = '#fff'; ctx.font = '600 13px sans-serif';
+            ctx.textAlign = 'center'; ctx.textBaseline = 'middle';
+            ctx.fillText('PRESS ME', state.w/2, state.h/2);
+        },
+    };
+}
+```
+
+## 📦 TypeScript
+
+Full declarations for controller, all 3 recipe volumes, and shared interfaces:
+
+```
+UIFXController.d.ts    — mountUIFX, UIType, UIFXState, UIFXPointer, UIFXRecipe
+UIFXRecipes.d.ts       — 10 recipe factories (Vol. 1)
+UIFXRecipes2.d.ts      — 20 recipe factories (Vol. 2)
+UIFXRecipes3.d.ts      — 20 recipe factories (Vol. 3)
+```
+
+## 📚 LLM-Friendly Documentation
+
+See `llms.txt` for AI-optimized metadata and the complete recipe catalog.
+
+## License
+
+MIT

package/UIFXController.d.ts

@@ -0,0 +1,71 @@
+export type UITypeValue = 'button' | 'toggle' | 'slider';
+
+export declare const UIType: Readonly<{
+    BUTTON: 'button';
+    TOGGLE: 'toggle';
+    SLIDER: 'slider';
+}>;
+
+export interface UIFXState {
+    hover: boolean;
+    active: boolean;
+    focused: boolean;
+    toggled: boolean;
+    val: number;
+    w: number;
+    h: number;
+    padding: number;
+    dpr: number;
+}
+
+export interface UIFXPointer {
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+}
+
+export interface UIFXRecipe {
+    init?(ctx: CanvasRenderingContext2D, w: number, h: number, padding: number): void;
+
+    tick(ctx: CanvasRenderingContext2D, dt: number, now: number, state: UIFXState, pointer: UIFXPointer): void;
+
+    onHover?(state: UIFXState, pointer: UIFXPointer): void;
+
+    onLeave?(state: UIFXState, pointer: UIFXPointer): void;
+
+    onClick?(x: number, y: number, state: UIFXState): void;
+
+    onToggle?(checked: boolean, state: UIFXState): void;
+
+    onDrag?(value: number, velocity: number, state: UIFXState): void;
+
+    destroy?(): void;
+}
+
+export type RecipeFactory = () => UIFXRecipe;
+
+export interface MountOptions {
+    width?: number;
+    height?: number;
+    padding?: number;
+    label?: string;
+}
+
+export interface UIFXInstance {
+    el: HTMLElement;
+    canvas: HTMLCanvasElement;
+    wrapper: HTMLDivElement;
+    state: UIFXState;
+
+    destroy(): void;
+}
+
+export declare function mountUIFX(
+    container: HTMLElement,
+    type: UITypeValue,
+    recipeFactory: RecipeFactory,
+    options?: MountOptions
+): UIFXInstance;
+
+export default mountUIFX;

package/UIFXController.js

@@ -0,0 +1,272 @@
+/**
+ * @zakkster/lite-ui-fx — Canvas-Hijacked UI Components
+ *
+ * Overlays a DPR-aware canvas on top of native HTML elements (buttons,
+ * checkboxes, sliders). The native element handles accessibility, focus,
+ * and events. The canvas handles visuals via a pluggable recipe system.
+ *
+ * Architecture:
+ *   Native element (opacity:0, z-index:2) — receives all pointer/keyboard events
+ *   Canvas overlay (z-index:1) — renders the visual recipe
+ *   Recipe factory → { init?, tick, onHover?, onLeave?, onClick?, onToggle?, onDrag?, destroy? }
+ *
+ * Uses:
+ *   @zakkster/lite-lerp   — interpolation in recipes
+ *   @zakkster/lite-random  — deterministic particle effects
+ *   @zakkster/lite-color   — OKLCH color math (optional per recipe)
+ *
+ * Depends on: @zakkster/lite-ticker (shared RAF loop)
+ */
+
+import { Ticker } from '@zakkster/lite-ticker';
+
+// ─────────────────────────────────────────────────────────
+//  SHARED TICKER (ref-counted, one RAF for all UI components)
+// ─────────────────────────────────────────────────────────
+
+let _sharedTicker = null;
+let _sharedRefs = 0;
+
+function acquireTicker() {
+    if (!_sharedTicker) {
+        _sharedTicker = new Ticker();
+        _sharedTicker.start();
+    }
+    _sharedRefs++;
+    return _sharedTicker;
+}
+
+function releaseTicker() {
+    _sharedRefs--;
+    if (_sharedRefs <= 0 && _sharedTicker) {
+        _sharedTicker.destroy();
+        _sharedTicker = null;
+        _sharedRefs = 0;
+    }
+}
+
+
+// ─────────────────────────────────────────────────────────
+//  ELEMENT TYPES
+// ─────────────────────────────────────────────────────────
+
+/** @enum {string} */
+export const UIType = Object.freeze({
+    BUTTON: 'button',
+    TOGGLE: 'toggle',
+    SLIDER: 'slider',
+});
+
+
+// ═══════════════════════════════════════════════════════════
+//  UIFXController — The Canvas Hijacker
+// ═══════════════════════════════════════════════════════════
+
+/**
+ * Mount a canvas-rendered recipe onto a native HTML element.
+ *
+ * @param {HTMLElement} container    Parent element to mount into
+ * @param {string}      type         'button' | 'toggle' | 'slider'
+ * @param {Function}    recipeFactory  () => Recipe object
+ * @param {Object}      [options]
+ * @param {number}      [options.width]   Element width (auto-detected from type if omitted)
+ * @param {number}      [options.height]  Element height
+ * @param {number}      [options.padding=40]  Canvas overflow padding (for particles)
+ * @param {string}      [options.label]   Accessible label for the element
+ * @returns {{ el: HTMLElement, destroy: Function }}
+ */
+export function mountUIFX(container, type, recipeFactory, {
+    width,
+    height,
+    padding = 40,
+    label = '',
+} = {}) {
+    // ── Resolve dimensions ──
+    const w = width  || (type === UIType.BUTTON ? 160 : type === UIType.SLIDER ? 200 : 64);
+    const h = height || (type === UIType.BUTTON ? 48  : type === UIType.SLIDER ? 28  : 36);
+    const dpr = window.devicePixelRatio || 1;
+
+    // ── Create native element (invisible, accessible, receives events) ──
+    let el;
+    if (type === UIType.TOGGLE) {
+        el = document.createElement('input');
+        el.type = 'checkbox';
+        el.setAttribute('role', 'switch');
+        if (label) el.setAttribute('aria-label', label);
+    } else if (type === UIType.SLIDER) {
+        el = document.createElement('input');
+        el.type = 'range';
+        el.min = '0'; el.max = '100'; el.value = '50';
+        if (label) el.setAttribute('aria-label', label);
+    } else {
+        el = document.createElement('button');
+        el.textContent = label || 'Action';
+        el.type = 'button';
+    }
+
+    Object.assign(el.style, {
+        position: 'relative', zIndex: '2',
+        opacity: '0', cursor: 'pointer',
+        width: `${w}px`, height: `${h}px`,
+        border: 'none', background: 'transparent',
+        margin: '0', padding: '0',
+        WebkitAppearance: 'none', appearance: 'none',
+    });
+
+    // Slider thumb needs explicit sizing for hit area
+    if (type === UIType.SLIDER) {
+        const thumbCSS = document.createElement('style');
+        thumbCSS.textContent = `
+            .uifx-slider::-webkit-slider-thumb { -webkit-appearance:none; width:24px; height:24px; cursor:grab; }
+            .uifx-slider::-moz-range-thumb { width:24px; height:24px; cursor:grab; border:none; background:transparent; }
+        `;
+        document.head.appendChild(thumbCSS);
+        el.classList.add('uifx-slider');
+    }
+
+    // ── Create canvas overlay (DPR-aware) ──
+    const canvas = document.createElement('canvas');
+    const cw = w + padding * 2;
+    const ch = h + padding * 2;
+    canvas.width = cw * dpr;
+    canvas.height = ch * dpr;
+    Object.assign(canvas.style, {
+        position: 'absolute', top: '0', left: '0',
+        width: `${cw}px`, height: `${ch}px`,
+        transform: `translate(-${padding}px, -${padding}px)`,
+        pointerEvents: 'none', zIndex: '1',
+    });
+
+    const ctx = canvas.getContext('2d');
+    ctx.scale(dpr, dpr);
+
+    // ── Wrapper ──
+    const wrapper = document.createElement('div');
+    Object.assign(wrapper.style, {
+        position: 'relative', display: 'inline-block',
+        width: `${w}px`, height: `${h}px`,
+    });
+    wrapper.appendChild(el);
+    wrapper.appendChild(canvas);
+    container.appendChild(wrapper);
+
+    // ── State ──
+    const state = {
+        hover: false,
+        active: false,      // pointer is down
+        focused: false,      // keyboard focus
+        toggled: false,      // checkbox state
+        val: type === UIType.SLIDER ? 0.5 : 0,  // slider value 0–1
+        w, h, padding, dpr,
+    };
+
+    const pointer = { x: -999, y: -999, vx: 0, vy: 0 };
+
+    // ── Initialize recipe ──
+    const recipe = recipeFactory();
+    if (recipe.init) recipe.init(ctx, w, h, padding);
+
+    // ── Events (all via AbortController) ──
+    const ac = new AbortController();
+    const signal = ac.signal;
+
+    function updatePointer(e) {
+        const r = el.getBoundingClientRect();
+        const nx = e.clientX - r.left;
+        const ny = e.clientY - r.top;
+        pointer.vx = nx - pointer.x;
+        pointer.vy = ny - pointer.y;
+        pointer.x = nx;
+        pointer.y = ny;
+    }
+
+    el.addEventListener('pointermove', updatePointer, { signal });
+    el.addEventListener('pointerenter', (e) => {
+        state.hover = true;
+        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 });
+
+    // Focus tracking (for keyboard accessibility indicators)
+    el.addEventListener('focus', () => { state.focused = true; }, { signal });
+    el.addEventListener('blur', () => { state.focused = false; }, { signal });
+
+    // Toggle events
+    if (type === UIType.TOGGLE) {
+        el.addEventListener('change', () => {
+            state.toggled = el.checked;
+            if (recipe.onToggle) recipe.onToggle(state.toggled, state);
+        }, { signal });
+        // Keyboard: Space/Enter toggles checkbox
+        el.addEventListener('keydown', (e) => {
+            if (e.code === 'Space' || e.code === 'Enter') {
+                el.checked = !el.checked;
+                state.toggled = el.checked;
+                if (recipe.onToggle) recipe.onToggle(state.toggled, state);
+            }
+        }, { signal });
+    }
+
+    // Slider events
+    if (type === UIType.SLIDER) {
+        el.addEventListener('input', () => {
+            state.val = el.value / 100;
+            if (recipe.onDrag) recipe.onDrag(state.val, pointer.vx, state);
+        }, { signal });
+    }
+
+    // ── Render loop (shared ticker) ──
+    const ticker = acquireTicker();
+    let destroyed = false;
+
+    const removeTick = ticker.add((dtMs) => {
+        if (destroyed) 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 = native element's top-left
+        recipe.tick(ctx, dt, now, state, pointer);
+        ctx.restore();
+    });
+
+    // ── Public API ──
+    return {
+        /** The native HTML element (for external state reads). */
+        el,
+
+        /** The canvas element (for external styling). */
+        canvas,
+
+        /** The wrapper div (for positioning). */
+        wrapper,
+
+        /** Current state (read-only reference). */
+        state,
+
+        /** Destroy everything. Idempotent. */
+        destroy() {
+            if (destroyed) return;
+            destroyed = true;
+            ac.abort();
+            removeTick();
+            if (recipe.destroy) recipe.destroy();
+            releaseTicker();
+            wrapper.remove();
+        },
+    };
+}
+
+export default mountUIFX;

package/llms.txt

@@ -0,0 +1,69 @@
+# @zakkster/lite-ui-fx
+> Canvas-hijacked UI components with pluggable recipe system. 30 built-in recipes.
+
+## Install
+npm i @zakkster/lite-ui-fx
+
+## Core Concept
+Native HTML element (opacity:0, z-index:2) handles events + a11y.
+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 — Recipes (3 volumes, 30 total)
+import { SwarmToggle, MagneticButton, SparkSlider } from ./recipes/UIFXRecipes.js';
+import { PendulumToggle, HeartbeatButton, AuroraSlider } from './recipes/UIFXRecipes2.js';
+import { VolumeKnob, WaterLevel, TimerCountdown } from './recipes/UIFXRecipes3.js';
+
+## Mount
+const instance = mountUIFX(container, UIType.TOGGLE, SwarmToggle, { label: 'Sound' });
+instance.destroy(); // cleanup
+
+## Element Types
+UIType.TOGGLE → <input type="checkbox" role="switch"> → state.toggled, onToggle(checked)
+UIType.BUTTON → <button> → state.active, onClick(x, y, state)
+UIType.SLIDER → <input type="range"> → state.val (0–1), onDrag(val, velocity)
+
+## State Object (provided to tick every frame)
+{ hover, active, focused, toggled, val, w, h, padding, dpr }
+
+## 30 Built-in Recipes
+
+### Vol. 1 (UIFXRecipes.js) — 10 recipes
+Toggles: SwarmToggle, LiquidToggle, NeonPulseToggle
+Buttons: MagneticButton, ShatterButton, ConfettiButton, GlitchButton
+Sliders: SparkSlider, CosmicSlider, LaserSlider
+
+### Vol. 2 (UIFXRecipes2.js) — 20 recipes
+Toggles: PendulumToggle, CircuitToggle, LightningToggle, DNAToggle
+Buttons: HeartbeatButton, BreathingButton, InkSplashButton, PixelDissolveButton, FireworkButton
+Sliders: AuroraSlider, WaveSlider, ElasticBandSlider, GravitySlider
+Loaders: OrbitLoader, HelixLoader
+Checkboxes: RippleCheck, MorphCheck
+Counters: FlameCounter, GlitchCounter
+Rating: BubbleRating
+
+### Vol. 3 (UIFXRecipes3.js) — 20 recipes
+Knobs: VolumeKnob, CompassKnob
+Progress: RingProgress, BatteryGauge, SignalMeter
+Controls: PillTabs, Stepper, RadioOrbit
+Indicators: PasswordStrength, WaterLevel, HeatMap
+Mood: DayNightToggle, ReactionPicker, NotificationBell
+Feedback: TypewriterField, SoundWaveBtn, UploadProgress
+Fun: ScratchReveal, TimerCountdown, PullRefresh
+
+## Writing Custom Recipes
+See UIFX-RECIPE-GUIDE.md (included in package).
+
+## Dependencies
+@zakkster/lite-ticker, @zakkster/lite-lerp, @zakkster/lite-random
+
+## Key Facts
+- DPR-aware canvas (retina sharp)
+- AbortController cleanup on destroy
+- Ref-counted shared Ticker (one RAF for all components)
+- Safari-safe roundRect polyfill in recipes
+- Accessibility: role=switch, aria-label, keyboard focus tracking
+- Zero-GC in all built-in recipes (TypedArrays, seeded RNG)

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@zakkster/lite-ui-fx",
+  "version": "1.0.0",
+  "description": "Canvas-hijacked UI components with a pluggable recipe system. 30 built-in recipes across toggles, buttons, sliders, knobs, loaders, checkboxes, counters, and ratings.",
+  "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
+  "license": "MIT",
+  "type": "module",
+  "main": "UIFXController.js",
+  "types": "UIFXController.d.ts",
+  "exports": {
+    ".": {
+      "import": "./UIFXController.js",
+      "types": "./UIFXController.d.ts"
+    }
+  },
+  "files": [
+    "UIFXController.js",
+    "UIFXController.d.ts",
+    "llms.txt"
+  ],
+  "keywords": [
+    "ui",
+    "canvas",
+    "microinteraction",
+    "toggle",
+    "button",
+    "slider",
+    "knob",
+    "recipe",
+    "animation",
+    "zero-gc",
+    "game",
+    "a11y"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@zakkster/lite-ticker": "^1.0.0",
+    "@zakkster/lite-lerp": "^1.0.0",
+    "@zakkster/lite-random": "^1.0.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "homepage": "https://github.com/PeshoVurtoleta/lite-ui-fx#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PeshoVurtoleta/lite-ui-fx.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PeshoVurtoleta/lite-ui-fx/issues",
+    "email": "shinikchiev@yahoo.com"
+  }
+}