@zakkster/lite-scratch-fx 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+## [1.0.0] - 2026-08-22
+
+First published release. The effects and controller existed as loose source files; this
+release consolidates them into a real package, makes every recipe themeable, holds the
+zero-GC line on the reveal path, and stands up the torture gate.
+
+### Added
+- `createScratchController(sourceCanvas, effectCanvas, { maxParticles, seed, scanPrecision })`
+  — scans the still-covered pixels of a scratch layer for spawn points, runs a reveal
+  recipe to completion, clears the overlay, and calls the completion callback.
+- 21 reveal recipes: `burn`, `shatter`, `dissolve`, `explode`, `dragonBreath`,
+  `iceBreath`, `shineWave`, `lightningCrawl`, `shine`, `peel`, `fade`, `implosion`,
+  `glitchReveal`, `matrixDecay`, `goldDust`, `pixelShatter`, `laserScan`,
+  `confettiBlast`, `liquidMelt`, `neonPulse`, `cosmicDust`.
+- **Themeable palettes.** The 14 recipes with a visible palette take a unified
+  `{ colors, theme }` pair — pass a `{ light, mid, dark }` `theme` shorthand or an
+  explicit `colors` ramp; `colors` wins, and both default to the recipe's own palette.
+  Replaces three inconsistent conventions (`color`, `colors`, hardcoded). New
+  `resolvePalette` helper in `src/Palette.js`.
+- `RECIPES` registry (short-name → factory) and `RECIPE_NAMES` for data-driven pickers.
+- Full TypeScript declarations (`index.d.ts`), including `Theme` and `ThemeableRecipeOptions`.
+- Test suite under `node:test` (46 checks): controller lifecycle, the `data[]` dataFlag
+  indexing invariant, a reveal-to-completion smoke test for every recipe, and theming
+  (every themeable recipe drives its palette from a theme; short-ramp safety; `colors`
+  overrides `theme`).
+- Torture gate `npm run torture` (`node --expose-gc test/torture.mjs`, lite-gc-profiler +
+  lite-leak): completion, degenerate scratch layers, RNG-spawn determinism, the
+  one-scan-canvas-ever assertion, the per-frame tick heap-growth gate, and controls that
+  prove each gate can fail.
+
+### Changed
+- **Zero-GC reveal path.** `scanPixels` no longer mints an offscreen canvas or an
+  object per surviving pixel on every reveal — the scan canvas is built once and the
+  spawn points fill preallocated `Float32Array`s read through one reused `spot` object.
+  The per-frame `tick` no longer allocates a fresh particle-view object; it reuses one.
+- Test runner is `node:test` (was vitest); `vitest` and `typescript` devDependencies
+  dropped in favour of `@zakkster/lite-gc-profiler` + `@zakkster/lite-leak`.
+- Dropped the unused `@zakkster/lite-ticker` runtime dependency (it backed the removed
+  shared-ticker path and was imported nowhere).
+
+### Fixed
+- **Reveals never completed.** The controller attached a ticker that called
+  `engine._loop` every frame, but the SoA engine already owns its own
+  `requestAnimationFrame` loop and computes its own `dt`. Driving it a second time
+  corrupted `dt`, so particle life never decayed and the completion condition
+  (`alive === 0 && elapsed >= duration`) was never met — a reveal would run forever. The
+  external ticker is removed; the engine self-drives via `start()` / `stop()`.
+- **`count: 0` recipes spawned a full pool.** `recipe.count || maxParticles` turned an
+  explicit `0` (pure-canvas reveals like `shine`, `implosion`, `laserScan`) into
+  `maxParticles` (2000). Now uses `?? maxParticles`, so `0` is honoured.
+- Import specifier typo: `ScratchController` imported `from 'lite-ticker'` (unscoped);
+  the ticker dependency has since been removed entirely.
+- Removed a duplicate `ImplosionRecipe` that was defined in two source files (and a
+  dangling reference to it in a re-export barrel).
+
+### Removed
+- The `sharedTicker` controller option. It implied the reveal loop could share one RAF
+  with `@zakkster/lite-ambient-fx`, but ambient-fx owns its own loop and the SoA engine
+  self-drives, so the option did nothing except enable the double-drive bug above.
+- The older standalone effect module (`ScratchFXRecipes.js`), superseded by the
+  recipe-interface versions.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zahary Shinikchiev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# @zakkster/lite-scratch-fx
+
+[![npm version](https://img.shields.io/npm/v/@zakkster/lite-scratch-fx.svg?style=for-the-badge&color=latest)](https://www.npmjs.com/package/@zakkster/lite-scratch-fx)
+[![sponsor](https://img.shields.io/badge/sponsor-PeshoVurtoleta-ea4aaa.svg?logo=github)](https://github.com/sponsors/PeshoVurtoleta)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@zakkster/lite-scratch-fx?style=for-the-badge)](https://bundlephobia.com/result?p=@zakkster/lite-scratch-fx)
+[![npm downloads](https://img.shields.io/npm/dm/@zakkster/lite-scratch-fx?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-scratch-fx)
+[![npm total downloads](https://img.shields.io/npm/dt/@zakkster/lite-scratch-fx?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-scratch-fx)
+![TypeScript](https://img.shields.io/badge/TypeScript-Types-informational)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
+
+One-shot **scratch-card reveal effects** on canvas. A controller scans the remaining
+pixels of a scratch layer, spawns particles from those points, and delegates physics
+and rendering to a **recipe**. Ships **21 ready-made reveal recipes**; bring your own by
+matching the recipe interface.
+
+Zero GSAP. Deterministic RNG. The particle engine owns its own `requestAnimationFrame`
+loop and auto-cleans up on completion.
+
+```
+npm install @zakkster/lite-scratch-fx
+```
+
+## Quick start
+
+```js
+import { createScratchController, BurnRecipe } from '@zakkster/lite-scratch-fx';
+
+// scratchCanvas: the layer the user scratches off.
+// fxCanvas: an overlay canvas the effect renders particles onto.
+const fx = createScratchController(scratchCanvas, fxCanvas, { seed: 42 });
+
+revealButton.onclick = () => {
+    fx.reveal(BurnRecipe({ duration: 1500 }), () => {
+        console.log('prize revealed');
+    });
+};
+```
+
+`reveal(recipe, onDone)` samples spawn points from the still-covered pixels of the
+scratch layer, runs the recipe to completion, then clears the overlay and calls
+`onDone`. A second `reveal` while one is active is ignored.
+
+## Theming
+
+Every recipe with a visible palette (14 of the 21) takes the same two options, so a
+themed host can drive them all through one shape. Pass a `{ light, mid, dark }`
+`theme` for the common case, or an explicit `colors` ramp to override it. Either
+defaults to the recipe's own palette when omitted, so untyped calls look exactly as
+before.
+
+```js
+// A skin threads one triple through every effect:
+const vikings = { light: '#e8d5a0', mid: '#b8860b', dark: '#3a2a10' };
+fx.reveal(RECIPES.burn({ theme: vikings }));
+fx.reveal(RECIPES.dissolve({ theme: vikings }));   // single-colour recipes use theme.light
+
+// Or hand a recipe an exact ramp:
+fx.reveal(RECIPES.confettiBlast({ colors: ['#ff0055', '#00ffcc', '#ffcc00'] }));
+```
+
+`colors` wins when both are given. The seven image-based (`shatter`, `pixelShatter`,
+`glitchReveal`) and neutral (`shine`, `peel`, `fade`, `implosion`) recipes have no
+palette to theme and safely ignore both options.
+
+## The 21 recipes
+
+Import them by name, or pick from the `RECIPES` registry:
+
+```js
+import { RECIPES, RECIPE_NAMES, createScratchController } from '@zakkster/lite-scratch-fx';
+
+const recipe = RECIPES.cosmicDust({ count: 300 });
+fx.reveal(recipe);
+// RECIPE_NAMES is every key: 'burn', 'shatter', 'dissolve', …
+```
+
+| Recipe | Effect |
+|---|---|
+| `burn` | Embers rise and fade while the layer burns away |
+| `shatter` | The layer breaks into gravity-driven glass pieces |
+| `dissolve` | Pixels detach and drift off |
+| `explode` | A hard outward blast of debris |
+| `dragonBreath` | A sweep of fire particles |
+| `iceBreath` | A sweep of frost particles |
+| `shineWave` | A moving light beam with sparkle particles |
+| `lightningCrawl` | Procedural lightning bolts crawl across |
+| `shine` | A single pass of light (no particles) |
+| `peel` | The layer curls and peels away |
+| `fade` | A plain opacity fade |
+| `implosion` | The layer collapses to the center with speed lines |
+| `glitchReveal` | Digital slice-and-shift glitch |
+| `matrixDecay` | Falling code-rain decay |
+| `goldDust` | Drifting gold sparkle |
+| `pixelShatter` | The layer shatters into pixel blocks |
+| `laserScan` | A scanning laser line |
+| `confettiBlast` | A confetti burst |
+| `liquidMelt` | The layer melts and runs |
+| `neonPulse` | A neon pulse ring |
+| `cosmicDust` | Slow drifting star dust |
+
+Several recipes (`shatter`, `glitchReveal`, `pixelShatter`) snapshot the scratch layer
+with `sourceCanvas.toDataURL()` and an `Image`, so the layer must be same-origin
+(untainted) for those effects.
+
+## Writing a recipe
+
+A recipe is a plain object. The controller drives it:
+
+```js
+function MyRecipe({ count = 120, duration = 1000 } = {}) {
+    let size;
+    return {
+        count,                                   // 0 = pure-canvas reveal, no particles
+        init(ctx, capacity, w, h) {              // allocate parallel per-particle arrays
+            size = new Float32Array(capacity);
+        },
+        spawn(idx, rng, w, h, spot) {            // one particle; spot is 0..1 on the layer
+            size[idx] = rng.range(2, 5);
+            return { x: spot.x * w, y: spot.y * h, vx: rng.range(-1, 1), vy: rng.range(-4, -1), life: 1 };
+        },
+        tick(dt, elapsedMs, p, ctx, src, w, h) { // every frame; return true when done
+            let alive = 0;
+            for (let i = 0; i < p.max; i++) {
+                if (p.life[i] <= 0) continue;
+                const slot = p.data[i];          // maps back to the array index (see below)
+                p.x[i] += p.vx[i] * dt * 60;
+                p.y[i] += p.vy[i] * dt * 60;
+                p.life[i] -= dt;
+                if (p.life[i] <= 0) continue;
+                alive++;
+                ctx.globalAlpha = p.life[i];
+                ctx.beginPath();
+                ctx.arc(p.x[i], p.y[i], size[slot], 0, Math.PI * 2);
+                ctx.fill();
+            }
+            return alive === 0 && elapsedMs >= duration;
+        },
+        destroy() { size = null; },
+    };
+}
+```
+
+**Per-particle state and `p.data[i]`.** Recipes keep their own parallel arrays (`size`
+above), keyed by the particle's slot. The controller passes each particle's spawn ring
+index as the engine's data flag, so inside `tick` you read `p.data[i]` to get the index
+your `spawn` wrote to. This mapping is covered by a test so it stays correct across
+engine upgrades.
+
+**`spot` is shared and mutable.** The `spot` handed to every `spawn` call is one reused
+object — read `spot.x` / `spot.y` synchronously and never retain the reference; the next
+spawn overwrites it. This is what keeps the reveal-start frame allocation-free (no
+`{x, y}` literal per surviving pixel). To make a recipe themeable, take `{ colors, theme }`
+in your factory and resolve a ramp once with `resolvePalette` from `./src/Palette.js`.
+
+The per-frame `tick` runs allocation-free by design: the particle-view object is reused
+across frames, and physics runs over the engine's typed-array lanes. `npm run torture`
+gates both the reveal-start scan and the per-frame tick against heap growth.
+
+## API
+
+### `createScratchController(sourceCanvas, effectCanvas, options?)`
+
+| Option | Type | Default | |
+|---|---|---|---|
+| `maxParticles` | number | `2000` | Particle pool capacity |
+| `seed` | number | `Date.now()` | Deterministic RNG seed |
+| `scanPrecision` | number | `32` | Horizontal resolution of the spawn-point pixel scan |
+
+Returns `{ reveal(recipe, onDone?), seed(s), destroy() }`.
+
+- **`reveal(recipe, onDone?)`** — run a recipe; ignored if one is active.
+- **`seed(s)`** — re-seed the RNG for reproducible reveals.
+- **`destroy()`** — stop, clean up the active recipe, release the engine.
+
+## Notes on the engine
+
+The particle engine (`@zakkster/lite-soa-particle-engine`) owns its own animation-frame
+loop and computes its own delta time; the controller does not drive it from an external
+ticker. An earlier draft accepted a `sharedTicker` and drove the engine loop manually —
+that double-drove the loop and corrupted its `dt`, breaking life decay and completion.
+It has been removed.
+
+## Dependencies
+
+`@zakkster/lite-soa-particle-engine`, `@zakkster/lite-random`, `@zakkster/lite-lerp`.
+
+## License
+
+MIT © Zahary Shinikchiev

package/index.d.ts

@@ -0,0 +1,150 @@
+/**
+ * @zakkster/lite-scratch-fx — type declarations.
+ */
+
+/** The raw SoA particle arrays a recipe's `tick` receives. */
+export interface ParticleView {
+    x: Float32Array;
+    y: Float32Array;
+    vx: Float32Array;
+    vy: Float32Array;
+    life: Float32Array;
+    invLife: Float32Array;
+    /** Per-particle data flag; for these recipes it carries the spawn ring index. */
+    data: Float32Array | Uint32Array;
+    /** Capacity of the parallel arrays (loop `for i < max`). */
+    max: number;
+}
+
+/** The initial state a recipe returns from `spawn`. */
+export interface SpawnState {
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    /** Lifetime in seconds; must be > 0 for the particle to be emitted. */
+    life: number;
+}
+
+/**
+ * A normalized spawn point (0..1 in each axis) taken from the scratch layer.
+ * NOTE: this object is shared and reused across every `spawn` call in a reveal —
+ * read `x`/`y` synchronously and never retain the reference.
+ */
+export interface SpawnSpot {
+    x: number;
+    y: number;
+}
+
+/** A palette shorthand: a themed host threads one of these through every effect. */
+export interface Theme {
+    light?: string;
+    mid?: string;
+    dark?: string;
+}
+
+/** Deterministic RNG passed to `spawn` (from @zakkster/lite-random). */
+export interface RecipeRng {
+    next(): number;
+    int(min: number, max: number): number;
+    range(min: number, max: number): number;
+}
+
+/**
+ * A reveal recipe. The controller calls `init` once, `spawn` for each particle, then
+ * `tick` every frame until it returns `true`; `destroy` releases any arrays.
+ */
+export interface Recipe {
+    /** Particles to spawn. `0` means a pure-canvas reveal with no particles. */
+    count: number;
+    init(ctx: CanvasRenderingContext2D, capacity: number, w: number, h: number): void;
+    spawn(idx: number, rng: RecipeRng, w: number, h: number, spot: SpawnSpot): SpawnState;
+    /** Return `true` when the effect is complete. `elapsedMs` is milliseconds since reveal. */
+    tick(
+        dt: number,
+        elapsedMs: number,
+        engine: ParticleView,
+        ctx: CanvasRenderingContext2D,
+        sourceCanvas: HTMLCanvasElement,
+        w: number,
+        h: number,
+    ): boolean;
+    destroy(): void;
+}
+
+export interface ScratchControllerOptions {
+    /** Particle pool capacity. Default 2000. */
+    maxParticles?: number;
+    /** Seed for the deterministic RNG. Default `Date.now()`. */
+    seed?: number;
+    /** Horizontal resolution of the spawn-point pixel scan. Default 32. */
+    scanPrecision?: number;
+}
+
+export interface ScratchController {
+    /** Run a reveal recipe. Ignored if one is already active or the controller is destroyed. */
+    reveal(recipe: Recipe, onDone?: () => void): void;
+    /** Re-seed the RNG. */
+    seed(s: number): void;
+    /** Stop, clean up the active recipe, and release the engine. */
+    destroy(): void;
+}
+
+/**
+ * Create a scratch-card reveal controller over a scratch layer and an effect overlay.
+ */
+export function createScratchController(
+    sourceCanvas: HTMLCanvasElement,
+    effectCanvas: HTMLCanvasElement,
+    options?: ScratchControllerOptions,
+): ScratchController;
+
+export { createScratchController as ScratchController };
+
+// ── Recipe factories. Each returns a Recipe; all options are optional. ──
+
+export interface RecipeOptions {
+    count?: number;
+    duration?: number;
+    [key: string]: unknown;
+}
+
+/** Options for the 14 recipes that carry a themeable palette. */
+export interface ThemeableRecipeOptions extends RecipeOptions {
+    /** An explicit colour ramp; wins over `theme`. */
+    colors?: string[];
+    /** A `{ light, mid, dark }` shorthand mapped onto the recipe's ramp. */
+    theme?: Theme;
+}
+
+export function BurnRecipe(opts?: ThemeableRecipeOptions): Recipe;
+export function ShatterRecipe(opts?: RecipeOptions & { gravity?: number }): Recipe;
+export function DissolveRecipe(opts?: ThemeableRecipeOptions): Recipe;
+export function ExplodeRecipe(opts?: ThemeableRecipeOptions & { force?: number }): Recipe;
+export function DragonBreathRecipe(opts?: ThemeableRecipeOptions): Recipe;
+export function IceBreathRecipe(opts?: ThemeableRecipeOptions): Recipe;
+export function ShineWaveRecipe(opts?: ThemeableRecipeOptions & { beamWidth?: number; particleCount?: number }): Recipe;
+export function LightningCrawlRecipe(opts?: ThemeableRecipeOptions & { boltCount?: number }): Recipe;
+export function ShineRecipe(opts?: RecipeOptions & { width?: number }): Recipe;
+export function PeelRecipe(opts?: RecipeOptions): Recipe;
+export function FadeRecipe(opts?: RecipeOptions): Recipe;
+export function ImplosionRecipe(opts?: RecipeOptions): Recipe;
+
+export function GlitchRevealRecipe(opts?: RecipeOptions): Recipe;
+export function MatrixDecayRecipe(opts?: ThemeableRecipeOptions): Recipe;
+export function GoldDustRecipe(opts?: ThemeableRecipeOptions): Recipe;
+export function PixelShatterRecipe(opts?: RecipeOptions): Recipe;
+export function LaserScanRecipe(opts?: ThemeableRecipeOptions): Recipe;
+export function ConfettiBlastRecipe(opts?: ThemeableRecipeOptions): Recipe;
+export function LiquidMeltRecipe(opts?: ThemeableRecipeOptions): Recipe;
+export function NeonPulseRecipe(opts?: ThemeableRecipeOptions): Recipe;
+export function CosmicDustRecipe(opts?: ThemeableRecipeOptions): Recipe;
+
+/** A factory that builds a recipe from options. */
+export type RecipeFactory = (opts?: RecipeOptions) => Recipe;
+
+/** Registry of every built-in recipe, keyed by short name. */
+export const RECIPES: Readonly<Record<string, RecipeFactory>>;
+
+/** Names of every built-in recipe (keys of RECIPES). */
+export const RECIPE_NAMES: readonly string[];

package/index.js

@@ -0,0 +1,84 @@
+/**
+ * @zakkster/lite-scratch-fx
+ *
+ * One-shot scratch-card reveal effects. A controller scans the remaining pixels of
+ * a scratch layer, spawns particles from those points, and delegates physics and
+ * rendering to a recipe. 21 ready-made reveal recipes; bring your own by matching
+ * the recipe interface. Themeable palettes, a zero-GC reveal path, and a
+ * deterministic seeded RNG for reproducible reveals.
+ *
+ * Copyright (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
+ * MIT License.
+ */
+
+export { createScratchController } from './src/ScratchController.js';
+export { default as ScratchController } from './src/ScratchController.js';
+
+// Core reveal recipes.
+export {
+    BurnRecipe,
+    ShatterRecipe,
+    DissolveRecipe,
+    ExplodeRecipe,
+    DragonBreathRecipe,
+    IceBreathRecipe,
+    ShineWaveRecipe,
+    LightningCrawlRecipe,
+    ShineRecipe,
+    PeelRecipe,
+    FadeRecipe,
+    ImplosionRecipe,
+} from './src/ScratchRecipes.js';
+
+// Extended / stylized reveal recipes.
+export {
+    GlitchRevealRecipe,
+    MatrixDecayRecipe,
+    GoldDustRecipe,
+    PixelShatterRecipe,
+    LaserScanRecipe,
+    ConfettiBlastRecipe,
+    LiquidMeltRecipe,
+    NeonPulseRecipe,
+    CosmicDustRecipe,
+} from './src/ScratchRecipes2.js';
+
+// A combined registry keyed by short name, for data-driven pickers (demo dropdowns,
+// random selection, config files). Keys are the recipe name without the `Recipe` suffix.
+import {
+    BurnRecipe, ShatterRecipe, DissolveRecipe, ExplodeRecipe, DragonBreathRecipe,
+    IceBreathRecipe, ShineWaveRecipe, LightningCrawlRecipe, ShineRecipe, PeelRecipe,
+    FadeRecipe, ImplosionRecipe,
+} from './src/ScratchRecipes.js';
+import {
+    GlitchRevealRecipe, MatrixDecayRecipe, GoldDustRecipe, PixelShatterRecipe,
+    LaserScanRecipe, ConfettiBlastRecipe, LiquidMeltRecipe, NeonPulseRecipe,
+    CosmicDustRecipe,
+} from './src/ScratchRecipes2.js';
+
+export const RECIPES = Object.freeze({
+    burn: BurnRecipe,
+    shatter: ShatterRecipe,
+    dissolve: DissolveRecipe,
+    explode: ExplodeRecipe,
+    dragonBreath: DragonBreathRecipe,
+    iceBreath: IceBreathRecipe,
+    shineWave: ShineWaveRecipe,
+    lightningCrawl: LightningCrawlRecipe,
+    shine: ShineRecipe,
+    peel: PeelRecipe,
+    fade: FadeRecipe,
+    implosion: ImplosionRecipe,
+    glitchReveal: GlitchRevealRecipe,
+    matrixDecay: MatrixDecayRecipe,
+    goldDust: GoldDustRecipe,
+    pixelShatter: PixelShatterRecipe,
+    laserScan: LaserScanRecipe,
+    confettiBlast: ConfettiBlastRecipe,
+    liquidMelt: LiquidMeltRecipe,
+    neonPulse: NeonPulseRecipe,
+    cosmicDust: CosmicDustRecipe,
+});
+
+/** Names of every built-in recipe (the keys of RECIPES). */
+export const RECIPE_NAMES = Object.freeze(Object.keys(RECIPES));

package/llms.txt

@@ -0,0 +1,97 @@
+# @zakkster/lite-scratch-fx
+
+> One-shot scratch-card reveal effects on canvas. A controller scans the remaining pixels
+> of a scratch layer, spawns particles from them, and delegates physics + rendering to a
+> recipe. 21 ready-made reveal recipes, themeable palettes. Zero GSAP, zero-GC hot path,
+> deterministic seeded RNG for reproducible reveals.
+
+## Core model
+
+createScratchController(sourceCanvas, effectCanvas, { maxParticles = 2000, seed = Date.now(), scanPrecision = 32 })
+  -> { reveal(recipe, onDone?), seed(s), destroy() }
+
+sourceCanvas = the scratch layer (what the user scratches off).
+effectCanvas = an overlay canvas the particles render onto.
+
+reveal(recipe, onDone?):
+  1. sizes effectCanvas to the scratch layer,
+  2. scanPixels(): downsamples the scratch layer to scanPrecision px wide and collects the
+     still-covered pixels (alpha > 128) into preallocated Float32Arrays as normalized 0..1
+     spawn points. The scan canvas is built ONCE at construction and reused; no per-pixel
+     object and no per-reveal canvas are allocated (zero-GC reveal start),
+  3. recipe.init(ctx, maxParticles, w, h),
+  4. for each of min(recipe.count ?? maxParticles, maxParticles) particles: recipe.spawn(...)
+     -> {x,y,vx,vy,life}, emitted into the engine with the spawn ring index as the data flag,
+  5. engine.start() (the engine owns its RAF loop),
+  6. each frame the engine calls recipe.tick(...); when it returns true the controller stops
+     the engine, calls recipe.destroy(), clears the overlay, and calls onDone.
+A second reveal while one is active is ignored.
+
+## Recipe interface
+
+{
+  count,                                    // particles to spawn; 0 = pure-canvas reveal
+  init(ctx, capacity, w, h),                // allocate parallel per-particle arrays
+  spawn(idx, rng, w, h, spot),              // -> { x, y, vx, vy, life }; spot is {x,y} in 0..1
+  tick(dt, elapsedMs, p, ctx, src, w, h),   // -> true when complete
+  destroy(),
+}
+
+spot is a SHARED, reused object: read spot.x/spot.y synchronously in spawn, never retain it
+(the next spawn overwrites it in place). p (the engine view) has raw SoA arrays: x, y, vx, vy,
+life, invLife, data, max -- and is itself reused across frames, so tick allocates nothing.
+dt is in SECONDS. elapsedMs is milliseconds since reveal.
+
+## Theming
+
+14 of the 21 recipes carry a visible palette and take a unified { colors, theme } pair:
+  colors: string[]              an explicit ramp; highest precedence
+  theme:  {light, mid, dark}    shorthand mapped onto the recipe's ramp
+  (omit both)                   the recipe's own default palette
+Multi-colour recipes index the ramp per particle; single-colour recipes use ramp[0]. A host
+threads one {light, mid, dark} triple through every effect for a consistent skin. The 7
+image-based (shatter, pixelShatter, glitchReveal) and neutral (shine, peel, fade, implosion)
+recipes have no palette and ignore both options. Helper: resolvePalette(colors, theme, fallback)
+in src/Palette.js.
+
+## data[] indexing (load-bearing)
+
+Recipes keep per-particle state in their own parallel typed arrays keyed by slot. To map a
+live particle back to its slot inside tick, the controller passes engine._head (the spawn
+ring index) as emit()'s dataFlag; the engine stores it at data[i]; recipes read data[i] back
+as the index into their arrays. Verified: emit writes this.data[i]=dataFlag at i=_head then
+advances _head, so data[i]===idx for that particle, and it's stable across frames. A test
+locks this because it couples recipes to engine internals (_head).
+
+## Recipes (21)
+
+Core (ScratchRecipes.js): BurnRecipe, ShatterRecipe, DissolveRecipe, ExplodeRecipe,
+DragonBreathRecipe, IceBreathRecipe, ShineWaveRecipe, LightningCrawlRecipe, ShineRecipe,
+PeelRecipe, FadeRecipe, ImplosionRecipe.
+Extended (ScratchRecipes2.js): GlitchRevealRecipe, MatrixDecayRecipe, GoldDustRecipe,
+PixelShatterRecipe, LaserScanRecipe, ConfettiBlastRecipe, LiquidMeltRecipe, NeonPulseRecipe,
+CosmicDustRecipe.
+
+RECIPES is a frozen registry keyed by short name (burn, shatter, …); RECIPE_NAMES lists them.
+shatter/glitchReveal/pixelShatter snapshot the scratch layer via sourceCanvas.toDataURL()+Image,
+so that layer must be same-origin (untainted).
+
+## Engine driving (why there is no shared ticker)
+
+@zakkster/lite-soa-particle-engine owns its own requestAnimationFrame loop: start() schedules
+it, stop() cancels it, and _loop computes dt from performance.now() deltas internally. The
+controller must NOT also drive _loop from an external ticker -- doing so double-drives the loop
+and corrupts dt, which breaks life decay and completion (a reveal runs forever). An earlier
+draft accepted a sharedTicker and did exactly that; it was removed. ambient-fx also owns its own
+loop and does not accept a shared ticker, so "one RAF for atmosphere + reveal" was never real.
+
+## Fixed in 1.0.0 (was broken pre-package)
+
+- Reveals never completed (double-driven engine loop -> corrupted dt). Fixed: engine self-drives.
+- count:0 recipes spawned 2000 particles (`count || max`); fixed to `count ?? max`.
+- `from 'lite-ticker'` (unscoped) import typo; ticker dependency removed entirely.
+- Duplicate ImplosionRecipe across two files + a dangling barrel reference; de-duplicated.
+
+## Dependencies
+
+@zakkster/lite-soa-particle-engine, @zakkster/lite-random, @zakkster/lite-lerp.

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@zakkster/lite-scratch-fx",
+  "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
+  "version": "1.0.0",
+  "description": "One-shot scratch-card reveal effects. A controller scans the remaining pixels of a scratch layer, spawns particles from them, and delegates physics and rendering to a recipe. 21 ready-made reveal recipes (burn, shatter, dissolve, glitch, gold dust, cosmic dust, and more), themeable palettes, zero GSAP, zero-GC hot path, and deterministic seeded RNG for reproducible reveals.",
+  "type": "module",
+  "main": "./index.js",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "node": "./index.js",
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "src/ScratchController.js",
+    "src/ScratchRecipes.js",
+    "src/ScratchRecipes2.js",
+    "src/Palette.js",
+    "README.md",
+    "CHANGELOG.md",
+    "llms.txt",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/PeshoVurtoleta/lite-scratch-fx#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PeshoVurtoleta/lite-scratch-fx.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PeshoVurtoleta/lite-scratch-fx/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/PeshoVurtoleta"
+  },
+  "dependencies": {
+    "@zakkster/lite-lerp": "^1.1.0",
+    "@zakkster/lite-random": "^1.1.0",
+    "@zakkster/lite-soa-particle-engine": "^1.2.0"
+  },
+  "keywords": [
+    "scratch-card",
+    "reveal",
+    "particles",
+    "canvas",
+    "vfx",
+    "effects",
+    "game",
+    "zero-gc",
+    "deterministic",
+    "oklch",
+    "zakkster"
+  ],
+  "devDependencies": {
+    "@zakkster/lite-gc-profiler": "^1.15.0",
+    "@zakkster/lite-leak": "^1.8.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "torture": "node --expose-gc test/torture.mjs"
+  }
+}