@zakkster/lite-scratch-fx 1.0.0 → 1.3.0

package/index.d.ts

@@ -1,7 +1,19 @@
 /**
- * @zakkster/lite-scratch-fx — type declarations.
+ * @zakkster/lite-scratch-fx -- type declarations.
  */
 
+/** The package version. Kept in sync with package.json and CHANGELOG. */
+export const VERSION: string;
+
+/** A @zakkster/lite-soa-particle-engine instance. Opaque here; share one across controllers. */
+export interface SoaParticleEngine {
+    tick(dt: number): boolean;
+    start(): void;
+    stop(): void;
+    clear(): void;
+    destroy(): void;
+}
+
 /** The raw SoA particle arrays a recipe's `tick` receives. */
 export interface ParticleView {
     x: Float32Array;
@@ -28,7 +40,7 @@ export interface SpawnState {
 
 /**
  * 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 —
+ * 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 {
@@ -73,20 +85,50 @@ export interface Recipe {
 }
 
 export interface ScratchControllerOptions {
-    /** Particle pool capacity. Default 2000. */
+    /** Particle pool capacity. Default 2000. Ignored when `engine` is supplied. */
     maxParticles?: number;
     /** Seed for the deterministic RNG. Default `Date.now()`. */
     seed?: number;
     /** Horizontal resolution of the spawn-point pixel scan. Default 32. */
     scanPrecision?: number;
+    /**
+     * Host-driven mode. When true the controller never starts a RAF loop; the host calls
+     * `tick(dt)` every frame (dt in seconds). One page clock can drive N controllers.
+     */
+    driven?: boolean;
+    /**
+     * Share a caller-supplied particle engine (one lane pool for the whole page). The
+     * engine has a single render slot and one pool, so only one reveal per shared engine
+     * at a time; `destroy()` will not tear a shared engine down.
+     */
+    engine?: SoaParticleEngine;
+    /**
+     * Device-pixel-ratio for sharp rendering on high-DPI screens. Default 1. Pass
+     * window.devicePixelRatio. Recipes still author in CSS pixels.
+     */
+    dpr?: number;
 }
 
 export interface ScratchController {
-    /** Run a reveal recipe. Ignored if one is already active or the controller is destroyed. */
+    /**
+     * Run a reveal recipe. Ignored if one is already active, the controller is destroyed,
+     * or a shared engine is busy with another controller's reveal.
+     */
     reveal(recipe: Recipe, onDone?: () => void): void;
+    /**
+     * Advance one frame in host-driven mode; `dt` is in SECONDS. A no-op unless the
+     * controller was created with `{ driven: true }` and a reveal is active.
+     */
+    tick(dt: number): void;
     /** Re-seed the RNG. */
     seed(s: number): void;
-    /** Stop, clean up the active recipe, and release the engine. */
+    /**
+     * Abort an in-flight reveal: stop the effect and restore the host canvas's inline
+     * style to what it was at reveal start. Does NOT fire `onDone`; the controller is
+     * revealable again afterwards. A no-op when idle or destroyed.
+     */
+    cancel(): void;
+    /** Stop, clean up the active recipe, and release the engine (owned engines only). */
     destroy(): void;
 }
 
@@ -101,7 +143,73 @@ export function createScratchController(
 
 export { createScratchController as ScratchController };
 
-// ── Recipe factories. Each returns a Recipe; all options are optional. ──
+// -- Concurrent reveals over one shared pool (createScratchStage) --
+
+export interface ScratchStageOptions {
+    /** Total shared pool capacity, split across controllers. Default 2000. */
+    maxParticles?: number;
+    /** Base seed; each controller derives its own (base + index) unless it passes one. */
+    seed?: number;
+    /**
+     * Device-pixel-ratio for sharp rendering on high-DPI screens. Default 1. Pass
+     * window.devicePixelRatio. Recipes still author in CSS pixels.
+     */
+    dpr?: number;
+}
+
+export interface StageControllerOptions {
+    /** Slots reserved for this controller's particles out of the shared pool. Default 300. */
+    capacity?: number;
+    /** RNG seed for this controller. Default: the stage's base seed + controller index. */
+    seed?: number;
+    /** Horizontal resolution of the spawn-point pixel scan. Default 32. */
+    scanPrecision?: number;
+    /**
+     * Device-pixel-ratio for sharp rendering on high-DPI screens. Default 1 (the stage
+     * dpr). Pass window.devicePixelRatio. Recipes still author in CSS pixels.
+     */
+    dpr?: number;
+}
+
+/** A stage-managed controller. The stage drives it, so it has no `tick` of its own. */
+export interface StageController {
+    /** Reveal a recipe. Ignored if this controller is already revealing or destroyed. */
+    reveal(recipe: Recipe, onDone?: () => void): void;
+    /** Re-seed this controller's RNG. */
+    seed(s: number): void;
+    /**
+     * Abort this controller's in-flight reveal: stop the effect and restore the host
+     * canvas's inline style. Does NOT fire `onDone`; the controller is revealable again.
+     * A no-op when idle or destroyed. Does not touch other controllers' reveals.
+     */
+    cancel(): void;
+    /** Remove this controller from the stage (its sub-range is not reclaimed). */
+    destroy(): void;
+}
+
+/**
+ * A stage owning one shared particle pool. Any number of controllers can reveal at once,
+ * all rendering from the one pool, driven by a single `tick(dt)`.
+ */
+export interface ScratchStage {
+    /** Reserve a sub-range and return a controller bound to this stage. */
+    createController(
+        sourceCanvas: HTMLCanvasElement,
+        effectCanvas: HTMLCanvasElement,
+        options?: StageControllerOptions,
+    ): StageController;
+    /** Advance every active reveal one frame; `dt` is in SECONDS. */
+    tick(dt: number): void;
+    /** Stop everything and release the shared engine. */
+    destroy(): void;
+    /** Slots still unreserved in the shared pool. */
+    readonly remainingCapacity: number;
+}
+
+/** Create a stage for concurrent reveals over one shared particle pool. */
+export function createScratchStage(options?: ScratchStageOptions): ScratchStage;
+
+// -- Recipe factories. Each returns a Recipe; all options are optional. --
 
 export interface RecipeOptions {
     count?: number;
@@ -143,8 +251,39 @@ 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>>;
+/** Resolve a colour ramp from `colors` / `theme` / a fallback (see `src/Palette.js`). */
+export function resolvePalette(
+    colors: string[] | undefined,
+    theme: Theme | undefined,
+    fallback: string[],
+): string[];
 
-/** Names of every built-in recipe (keys of RECIPES). */
+/**
+ * Extensible registry of recipes, keyed by short name. Built-ins are present at load;
+ * `registerRecipe` adds more. A null-prototype object.
+ */
+export const RECIPES: Record<string, RecipeFactory>;
+
+/** Names of every built-in recipe (keys of RECIPES at load time). */
 export const RECIPE_NAMES: readonly string[];
+
+export type RecipeCategory = 'particle' | 'image' | 'beam' | 'css' | (string & {});
+
+/** Display + capability metadata for a recipe, for building pickers. */
+export interface RecipeMeta {
+    id: string;
+    name: string;
+    category: RecipeCategory;
+    themeable: boolean;
+    needsUntaintedCanvas: boolean;
+}
+
+/** Live metadata array for every recipe; `registerRecipe` keeps it in sync. */
+export const RECIPE_META: RecipeMeta[];
+
+/** Register a custom recipe (or override a built-in); reflected in RECIPES + RECIPE_META. */
+export function registerRecipe(
+    id: string,
+    factory: RecipeFactory,
+    meta?: Partial<Omit<RecipeMeta, 'id'>>,
+): RecipeFactory;

package/index.js

@@ -11,74 +11,127 @@
  * MIT License.
  */
 
+// Three-place version sync: this constant, package.json "version", and the top
+// CHANGELOG.md heading must always match. /release keeps them locked.
+export const VERSION = '1.3.0';
+
 export { createScratchController } from './src/ScratchController.js';
 export { default as ScratchController } from './src/ScratchController.js';
+export { createScratchStage } from './src/ScratchStage.js';
+export { resolvePalette } from './src/Palette.js';
 
-// Core reveal recipes.
+// All 21 recipes now live in one file, grouped by family.
 export {
-    BurnRecipe,
-    ShatterRecipe,
-    DissolveRecipe,
-    ExplodeRecipe,
-    DragonBreathRecipe,
-    IceBreathRecipe,
-    ShineWaveRecipe,
-    LightningCrawlRecipe,
-    ShineRecipe,
-    PeelRecipe,
-    FadeRecipe,
-    ImplosionRecipe,
+    BurnRecipe, DissolveRecipe, ExplodeRecipe, DragonBreathRecipe, IceBreathRecipe,
+    GoldDustRecipe, ConfettiBlastRecipe, CosmicDustRecipe, MatrixDecayRecipe, LiquidMeltRecipe,
+    ShatterRecipe, PixelShatterRecipe, GlitchRevealRecipe,
+    ShineRecipe, ShineWaveRecipe, LaserScanRecipe, LightningCrawlRecipe, NeonPulseRecipe,
+    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,
+    BurnRecipe, DissolveRecipe, ExplodeRecipe, DragonBreathRecipe, IceBreathRecipe,
+    GoldDustRecipe, ConfettiBlastRecipe, CosmicDustRecipe, MatrixDecayRecipe, LiquidMeltRecipe,
+    ShatterRecipe, PixelShatterRecipe, GlitchRevealRecipe,
+    ShineRecipe, ShineWaveRecipe, LaserScanRecipe, LightningCrawlRecipe, NeonPulseRecipe,
+    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({
+// -- Recipe registry (extensible: registerRecipe adds to it) --
+// Keyed by short name, for data-driven pickers (demo dropdowns, random selection,
+// config files). A null-prototype object so keys never collide with Object.prototype.
+export const RECIPES = Object.assign(Object.create(null), {
     burn: BurnRecipe,
-    shatter: ShatterRecipe,
     dissolve: DissolveRecipe,
     explode: ExplodeRecipe,
     dragonBreath: DragonBreathRecipe,
     iceBreath: IceBreathRecipe,
+    goldDust: GoldDustRecipe,
+    confettiBlast: ConfettiBlastRecipe,
+    cosmicDust: CosmicDustRecipe,
+    matrixDecay: MatrixDecayRecipe,
+    liquidMelt: LiquidMeltRecipe,
+    shatter: ShatterRecipe,
+    pixelShatter: PixelShatterRecipe,
+    glitchReveal: GlitchRevealRecipe,
+    shine: ShineRecipe,
     shineWave: ShineWaveRecipe,
+    laserScan: LaserScanRecipe,
     lightningCrawl: LightningCrawlRecipe,
-    shine: ShineRecipe,
+    neonPulse: NeonPulseRecipe,
     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). */
+/**
+ * Display + capability metadata for every built-in recipe, so a host can build a
+ * picker without hardcoding the list. Mirrors lite-ambient's THEME_META. A live
+ * array: registerRecipe() updates it, so existing pickers keep working.
+ *
+ *   category            'particle' | 'image' | 'beam' | 'css' | (custom)
+ *   themeable           accepts { colors, theme }
+ *   needsUntaintedCanvas snapshots the scratch layer via toDataURL() (same-origin only)
+ */
+export const RECIPE_META = [
+    { id: 'burn', name: 'Burn', category: 'particle', themeable: true, needsUntaintedCanvas: false },
+    { id: 'dissolve', name: 'Dissolve', category: 'particle', themeable: true, needsUntaintedCanvas: false },
+    { id: 'explode', name: 'Explode', category: 'particle', themeable: true, needsUntaintedCanvas: false },
+    { id: 'dragonBreath', name: 'Dragon Breath', category: 'particle', themeable: true, needsUntaintedCanvas: false },
+    { id: 'iceBreath', name: 'Ice Breath', category: 'particle', themeable: true, needsUntaintedCanvas: false },
+    { id: 'goldDust', name: 'Gold Dust', category: 'particle', themeable: true, needsUntaintedCanvas: false },
+    { id: 'confettiBlast', name: 'Confetti Blast', category: 'particle', themeable: true, needsUntaintedCanvas: false },
+    { id: 'cosmicDust', name: 'Cosmic Dust', category: 'particle', themeable: true, needsUntaintedCanvas: false },
+    { id: 'matrixDecay', name: 'Matrix Decay', category: 'particle', themeable: true, needsUntaintedCanvas: false },
+    { id: 'liquidMelt', name: 'Liquid Melt', category: 'particle', themeable: true, needsUntaintedCanvas: false },
+    { id: 'shatter', name: 'Shatter', category: 'image', themeable: false, needsUntaintedCanvas: true },
+    { id: 'pixelShatter', name: 'Pixel Shatter', category: 'image', themeable: false, needsUntaintedCanvas: true },
+    { id: 'glitchReveal', name: 'Glitch Reveal', category: 'image', themeable: false, needsUntaintedCanvas: true },
+    { id: 'shine', name: 'Shine', category: 'beam', themeable: false, needsUntaintedCanvas: false },
+    { id: 'shineWave', name: 'Shine Wave', category: 'beam', themeable: true, needsUntaintedCanvas: false },
+    { id: 'laserScan', name: 'Laser Scan', category: 'beam', themeable: true, needsUntaintedCanvas: false },
+    { id: 'lightningCrawl', name: 'Lightning Crawl', category: 'beam', themeable: true, needsUntaintedCanvas: false },
+    { id: 'neonPulse', name: 'Neon Pulse', category: 'beam', themeable: true, needsUntaintedCanvas: false },
+    { id: 'peel', name: 'Peel', category: 'css', themeable: false, needsUntaintedCanvas: false },
+    { id: 'fade', name: 'Fade', category: 'css', themeable: false, needsUntaintedCanvas: false },
+    { id: 'implosion', name: 'Implosion', category: 'css', themeable: false, needsUntaintedCanvas: false },
+];
+
+/** Names of every built-in recipe (the keys of RECIPES at load time). */
 export const RECIPE_NAMES = Object.freeze(Object.keys(RECIPES));
+
+/**
+ * Register a custom recipe, or override a built-in. Instantly usable via
+ * RECIPES[id] and reflected in RECIPE_META so existing pickers keep working.
+ * Mirrors lite-ambient's registerTheme().
+ *
+ * @param {string} id        short name (the RECIPES key)
+ * @param {Function} factory a recipe factory: (opts) => Recipe
+ * @param {{ name?: string, category?: string, themeable?: boolean, needsUntaintedCanvas?: boolean }} [meta]
+ *   Omitted fields fall back to the existing entry (when overriding), then to a
+ *   de-camelCased name, category 'custom', and false flags.
+ * @returns {Function} the registered factory
+ */
+export function registerRecipe(id, factory, meta) {
+    if (typeof id !== 'string' || id.length === 0) {
+        throw new TypeError('registerRecipe: id must be a non-empty string');
+    }
+    if (typeof factory !== 'function') {
+        throw new TypeError('registerRecipe: factory must be a function');
+    }
+    RECIPES[id] = factory;
+
+    const idx = RECIPE_META.findIndex((m) => m.id === id);
+    const prev = idx >= 0 ? RECIPE_META[idx] : null;
+    const entry = {
+        id,
+        name: (meta && meta.name) || (prev && prev.name)
+            || id.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/^[a-z]/, (c) => c.toUpperCase()),
+        category: (meta && meta.category) || (prev && prev.category) || 'custom',
+        themeable: meta && 'themeable' in meta ? !!meta.themeable : (prev ? prev.themeable : false),
+        needsUntaintedCanvas: meta && 'needsUntaintedCanvas' in meta
+            ? !!meta.needsUntaintedCanvas : (prev ? prev.needsUntaintedCanvas : false),
+    };
+    if (idx >= 0) RECIPE_META[idx] = entry; else RECIPE_META.push(entry);
+    return factory;
+}

package/llms.txt

@@ -7,8 +7,9 @@
 
 ## Core model
 
-createScratchController(sourceCanvas, effectCanvas, { maxParticles = 2000, seed = Date.now(), scanPrecision = 32 })
-  -> { reveal(recipe, onDone?), seed(s), destroy() }
+createScratchController(sourceCanvas, effectCanvas,
+    { maxParticles = 2000, seed = Date.now(), scanPrecision = 32, driven = false, engine, dpr = 1 })
+  -> { reveal(recipe, onDone?), tick(dt), cancel(), seed(s), destroy() }
 
 sourceCanvas = the scratch layer (what the user scratches off).
 effectCanvas = an overlay canvas the particles render onto.
@@ -65,25 +66,58 @@ 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.
+All 21 live in src/ScratchRecipes.js, grouped by family with section banners:
+  particle (spawn from covered pixels, own physics): burn, dissolve, explode, dragonBreath,
+    iceBreath, goldDust, confettiBlast, cosmicDust, matrixDecay, liquidMelt
+  image (snapshot layer via toDataURL()+Image; same-origin only): shatter, pixelShatter, glitchReveal
+  beam/canvas (draw light/lines on the overlay): shine, shineWave, laserScan, lightningCrawl, neonPulse
+  css (drive the layer's own transform/opacity): peel, fade, implosion
+
+## Registry, metadata, extension
+
+VERSION: the package version string (kept in sync with package.json and CHANGELOG).
+RECIPES: an extensible null-prototype registry keyed by short name (burn, shatter, ...).
+RECIPE_NAMES: the built-in keys at load time.
+RECIPE_META: a live array of { id, name, category, themeable, needsUntaintedCanvas } for every
+  recipe -- the source for building pickers without hardcoding. category is
+  'particle'|'image'|'beam'|'css'. needsUntaintedCanvas is true only for shatter/pixelShatter/
+  glitchReveal. themeable is true for the 14 recipes that take { colors, theme }.
+registerRecipe(id, factory, meta?): add a recipe or override a built-in; lands in RECIPES and
+  RECIPE_META immediately so existing pickers keep working. Mirrors lite-ambient's registerTheme.
+  Omitted meta fields fall back to the prior entry, then a de-camelCased name, category 'custom',
+  false flags. Throws TypeError on a bad id or non-function factory.
+
+## Engine driving (three modes, dt always correct)
+
+The old sharedTicker bug was DOUBLE-driving: the engine self-drove its RAF loop AND an external
+ticker called _loop, corrupting dt so reveals ran forever. That is removed. Three single-drive
+modes exist now:
+  DEFAULT: the controller owns a SoaParticleEngine that self-drives via start()/stop().
+  driven: true -- the controller never calls start(); the host calls controller.tick(dt) each
+    frame with dt in SECONDS (engine.tick(dt) is the engine's primary API; start() is a thin RAF
+    wrapper over it). One page clock drives N controllers. tick() is a no-op unless driven AND a
+    reveal is active.
+  { engine } -- N controllers share one caller-supplied engine (one lane pool for the page).
+    The engine has a single onTick slot and one particle pool, so ONE reveal per shared engine at
+    a time: a reveal on a busy shared engine is ignored (guarded by a module WeakSet). destroy()
+    does NOT destroy a shared engine (the caller owns it); it only unbinds and frees the slot.
+    Compose with driven:true and drive the page from one clock.
+
+## Concurrent reveals over one pool: createScratchStage
+
+createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr = 1 })
+  -> { createController(src, fx, { capacity = 300, seed?, scanPrecision = 32, dpr? }) -> stageController,
+       tick(dt), destroy(), get remainingCapacity }
+stageController -> { reveal(recipe, onDone?), cancel(), seed(s), destroy() }   // NO tick -- the stage drives.
+
+When { engine } (one reveal at a time) is not enough and you need MANY boxes revealing at once
+over one pool: a stage owns one raw engine and gives each controller a fixed sub-range [start,
+start+capacity) of the lanes. reserving past maxParticles throws. Each controller emits directly
+into its slots (data[start+i]=i), renders through subarray views of its range (built once per
+controller, reused every frame -> zero per-frame alloc), draws to its own ctx, keeps its own RNG.
+stage.tick(dt) advances the single engine once; the one onTick fans out to every active reveal.
+Feasible with no engine change because raw tick(dt) is pure dispatch (no physics/culling) and the
+lanes are public typed arrays recipes already write. See decisions/0001-concurrent-shared-reveals.md.
 
 ## Fixed in 1.0.0 (was broken pre-package)
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "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.",
+  "version": "1.3.0",
+  "description": "One-shot scratch-card reveal effects on canvas. A controller scans the still-covered pixels of a scratch layer, spawns particles from them, and delegates physics and rendering to a recipe. 21 themeable recipes (burn, shatter, dissolve, glitch, gold dust, cosmic dust, and more), a registry with a register hook, zero GSAP, a zero-GC hot path, deterministic seeded RNG, and a stage that runs a grid of simultaneous reveals over one shared pool.",
   "type": "module",
   "main": "./index.js",
   "module": "./index.js",
@@ -20,7 +20,9 @@
     "index.d.ts",
     "src/ScratchController.js",
     "src/ScratchRecipes.js",
-    "src/ScratchRecipes2.js",
+    "src/ScratchStage.js",
+    "src/HostStyle.js",
+    "src/PixelScan.js",
     "src/Palette.js",
     "README.md",
     "CHANGELOG.md",
@@ -55,7 +57,9 @@
     "game",
     "zero-gc",
     "deterministic",
-    "oklch",
+    "theme",
+    "reveal-animation",
+    "scratch-off",
     "zakkster"
   ],
   "devDependencies": {

package/src/HostStyle.js

@@ -0,0 +1,42 @@
+/**
+ * HostStyle -- snapshot and restore the host layer's inline style across a reveal.
+ *
+ * lite-scratch-fx BORROWS the host scratch layer's inline style for the duration of a
+ * reveal (recipes write these 5 props during tick) and returns it to exactly what it
+ * found on every terminal transition -- completion, cancel, and destroy. The host owns
+ * the final revealed state via onDone; the library leaves no fingerprints.
+ *
+ * The snapshot is one small plain object per reveal. This is a COLD path -- capture at
+ * reveal start, restore at reveal end. Never call these per frame.
+ *
+ * See decisions/0002-host-style-and-cancel.md for the contract.
+ *
+ * Copyright (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
+ * MIT License.
+ */
+
+// The 5 inline style props the built-in recipes write during tick (particle/beam/css/
+// image families combined). Capturing every element's CURRENT inline value (usually '')
+// means restore returns the host to pristine regardless of what a custom recipe touched
+// among these props.
+export function captureHostStyle(el) {
+    if (!el || !el.style) return null;   // fail closed: nothing to borrow, nothing to restore
+    const s = el.style;
+    return {
+        opacity: s.opacity,
+        transform: s.transform,
+        filter: s.filter,
+        clipPath: s.clipPath,
+        transformOrigin: s.transformOrigin,
+    };
+}
+
+export function restoreHostStyle(el, snap) {
+    if (!el || !el.style || !snap) return;   // fail closed
+    const s = el.style;
+    s.opacity = snap.opacity;
+    s.transform = snap.transform;
+    s.filter = snap.filter;
+    s.clipPath = snap.clipPath;
+    s.transformOrigin = snap.transformOrigin;
+}

package/src/PixelScan.js

@@ -0,0 +1,74 @@
+/**
+ * Pixel scanner -- finds the still-covered pixels of a scratch layer as normalized
+ * 0..1 spawn points. Allocated ONCE per scanner and reused across every scan: the
+ * offscreen canvas, its context, and the spot arrays are built lazily and grown only
+ * when the source canvas is resized, so a scan allocates nothing per pixel (only
+ * getImageData's single buffer, which the 2D canvas API mandates).
+ *
+ * Shared by ScratchController and ScratchStage.
+ *
+ * Copyright (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
+ * MIT License.
+ */
+
+/**
+ * @param {HTMLCanvasElement} sourceCanvas  The scratch layer to scan.
+ * @returns {{ scan(precision:number): { spotX: Float32Array, spotY: Float32Array, count: number },
+ *             destroy(): void }}
+ */
+export function createPixelScanner(sourceCanvas) {
+    let scanCanvas = null;
+    let scanCtx = null;
+    let scanW = 0, scanH = 0;
+    let spotX = new Float32Array(0);
+    let spotY = new Float32Array(0);
+    const result = { spotX, spotY, count: 0 };   // reused -- no per-scan allocation
+
+    function ensure(precision) {
+        const srcW = sourceCanvas.width || sourceCanvas.offsetWidth || 1;
+        const srcH = sourceCanvas.height || sourceCanvas.offsetHeight || 1;
+        const h = Math.max(1, Math.floor(srcH * (precision / srcW)));
+        if (scanCanvas && scanW === precision && scanH === h) return;
+        scanW = precision;
+        scanH = h;
+        if (!scanCanvas) {
+            scanCanvas = document.createElement('canvas');
+            scanCtx = scanCanvas.getContext('2d', { willReadFrequently: true });
+        }
+        scanCanvas.width = scanW;
+        scanCanvas.height = scanH;
+        const cap = scanW * scanH;
+        if (spotX.length < cap) {
+            spotX = new Float32Array(cap);
+            spotY = new Float32Array(cap);
+        }
+    }
+
+    return {
+        scan(precision) {
+            ensure(precision);
+            scanCtx.clearRect(0, 0, scanW, scanH);
+            scanCtx.drawImage(sourceCanvas, 0, 0, scanW, scanH);
+            const data = scanCtx.getImageData(0, 0, scanW, scanH).data;
+            let n = 0;
+            for (let i = 3; i < data.length; i += 4) {
+                if (data[i] > 128) {
+                    const p = (i - 3) / 4;
+                    spotX[n] = (p % scanW) / scanW;
+                    spotY[n] = ((p / scanW) | 0) / scanH;
+                    n++;
+                }
+            }
+            result.spotX = spotX;
+            result.spotY = spotY;
+            result.count = n;
+            return result;
+        },
+        destroy() {
+            scanCanvas = null;
+            scanCtx = null;
+        },
+    };
+}
+
+export default createPixelScanner;