@zakkster/lite-scratch-fx 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## [1.2.0] - 2026-08-22
+
+Concurrent scratch-card reveals over one shared particle pool. Purely additive --
+`createScratchController` and its options are unchanged.
+
+### Added
+- **`createScratchStage({ maxParticles, seed })`** — a stage that owns one particle
+  engine and lets any number of controllers reveal **at the same time** over that one
+  pool (where `{ engine }` allowed only one reveal at a time). Each
+  `stage.createController(src, fx, { capacity })` reserves a fixed sub-range of the lanes,
+  renders only its own particles through reused subarray views (zero per-frame allocation),
+  and keeps its own deterministic RNG. `stage.tick(dt)` (seconds) drives every active reveal
+  from one clock; reserving past `maxParticles` throws. Stage-managed controllers have no
+  `tick` of their own. See `decisions/0001-concurrent-shared-reveals.md`.
+- `src/PixelScan.js` — the reveal-scan logic extracted into a shared `createPixelScanner`,
+  now used by both the controller and the stage (no behaviour change).
+
+### Notes
+- Feasible with no change to `@zakkster/lite-soa-particle-engine`: raw-mode `tick(dt)` is
+  pure dispatch and the lanes are public typed arrays recipes already write, so a stage can
+  partition one pool into per-controller sub-ranges entirely in this package.
+
+## [1.1.0] - 2026-08-22
+
+Recipe organization and an extensible registry, modeled on `@zakkster/lite-ambient-fx`.
+No behaviour change to any recipe — all 21 bodies are byte-identical to 1.0.0.
+
+### Added
+- **`RECIPE_META`** — a live array of `{ id, name, category, themeable, needsUntaintedCanvas }`
+  for every recipe, so a host can build a picker (group by `category`, filter by `themeable`)
+  without hardcoding the list. Mirrors lite-ambient's `THEME_META`.
+- **`registerRecipe(id, factory, meta?)`** — register a custom recipe or override a built-in;
+  it 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'`, and `false` flags.
+- `resolvePalette` is now exported (and typed) for authors writing themeable recipes.
+- **Host-driven mode** — `createScratchController(src, fx, { driven: true })` skips the
+  engine's RAF loop; the host calls `controller.tick(dt)` (dt in seconds) so one page clock
+  drives N controllers. `tick()` is a no-op unless driven and a reveal is active.
+- **Shared engine** — `createScratchController(src, fx, { engine })` reuses a caller-supplied
+  particle engine, so a grid of scratch boxes holds one lane pool instead of one per box.
+  A shared engine serves one reveal at a time (a reveal on a busy shared engine is ignored);
+  `destroy()` never tears down a caller-supplied engine. The two options compose.
+
+### Changed
+- **The two recipe files are merged into one `src/ScratchRecipes.js`, grouped by family**
+  (particle / image / beam / css) with section banners — replacing the arbitrary
+  `ScratchRecipes.js` (12) + `ScratchRecipes2.js` (9) split. `ScratchRecipes2.js` is removed
+  from the package. All imports resolve through `index.js`, so the public API is unchanged.
+- `RECIPES` is now an extensible null-prototype registry (was a frozen object) so
+  `registerRecipe` can add to it. Reads are unaffected.
+
 ## [1.0.0] - 2026-08-22
 
 First published release. The effects and controller existed as loose source files; this

package/README.md

@@ -74,6 +74,31 @@ fx.reveal(recipe);
 // RECIPE_NAMES is every key: 'burn', 'shatter', 'dissolve', …
 ```
 
+### Building a picker with `RECIPE_META`
+
+`RECIPE_META` is a live array of `{ id, name, category, themeable, needsUntaintedCanvas }`
+for every recipe, so a UI can group and filter without hardcoding the list:
+
+```js
+import { RECIPE_META } from '@zakkster/lite-scratch-fx';
+
+// Only the recipes a themed skin can drive:
+const themeable = RECIPE_META.filter((m) => m.themeable);
+// Group a dropdown by category: 'particle' | 'image' | 'beam' | 'css'
+```
+
+### Registering your own recipe
+
+`registerRecipe(id, factory, meta?)` adds a recipe (or overrides a built-in). It lands in
+`RECIPES` and `RECIPE_META` immediately, so existing pickers pick it up with no code change:
+
+```js
+import { registerRecipe, createScratchController } from '@zakkster/lite-scratch-fx';
+
+registerRecipe('sparkle', SparkleRecipe, { category: 'particle', themeable: true });
+fx.reveal(RECIPES.sparkle({ theme: mySkin }));
+```
+
 | Recipe | Effect |
 |---|---|
 | `burn` | Embers rise and fade while the layer burns away |
@@ -172,13 +197,90 @@ Returns `{ reveal(recipe, onDone?), seed(s), destroy() }`.
 - **`seed(s)`** — re-seed the RNG for reproducible reveals.
 - **`destroy()`** — stop, clean up the active recipe, release the engine.
 
+## Scaling to a grid of scratch boxes
+
+By default each controller owns a particle engine that self-drives its own
+`requestAnimationFrame` loop — fine for one card. For a page full of scratch boxes,
+two options let one clock and one lane pool serve the whole grid:
+
+```js
+import { createScratchController } from '@zakkster/lite-scratch-fx';
+import { SoaParticleEngine } from '@zakkster/lite-soa-particle-engine';
+
+// One shared engine (one lane pool for the whole page) + host-driven controllers.
+const engine = new SoaParticleEngine(1500);
+const boxes = cards.map((c) => createScratchController(c.scratch, c.fx, { engine, driven: true }));
+
+// One page loop drives them all; dt is in SECONDS.
+let last = performance.now();
+function frame(now) {
+    const dt = (now - last) / 1000; last = now;
+    for (const b of boxes) b.tick(dt);   // only the box mid-reveal does work
+    requestAnimationFrame(frame);
+}
+requestAnimationFrame(frame);
+```
+
+- **`{ driven: true }`** — the controller never starts its own RAF; you call `tick(dt)`
+  each frame. `tick` is a no-op unless a reveal is active, so calling it on every box is
+  cheap. One clock, N controllers.
+- **`{ engine }`** — share one caller-supplied engine, so the page holds *one* lane pool
+  instead of one per box. A shared engine has a single render slot and one particle pool,
+  so **one reveal per shared engine at a time**: a `reveal` on a busy shared engine is
+  ignored (a scratch-card grid reveals one card at a time anyway). `destroy()` never tears
+  down a shared engine — its lifecycle is yours.
+
+The two compose (shared + driven, above) or stand alone. The default (own engine,
+self-driven) is unchanged.
+
+### Concurrent reveals over one pool: `createScratchStage`
+
+`{ engine }` shares a pool but runs **one reveal at a time**. When you need **many boxes
+revealing simultaneously** while still holding a single pool, use a stage: it owns one
+engine, hands each controller a fixed sub-range of the lanes, and dispatches every active
+reveal through one clock.
+
+```js
+import { createScratchStage } from '@zakkster/lite-scratch-fx';
+
+const stage = createScratchStage({ maxParticles: 1500, seed: 1 });
+const boxes = cards.map((c) =>
+    stage.createController(c.scratch, c.fx, { capacity: 200 }));   // reserves 200 slots each
+
+// Any number of boxes can reveal at once; one pool, one loop:
+boxes[3].reveal(RECIPES.burn({ theme: skin }));
+boxes[7].reveal(RECIPES.confettiBlast());
+
+let last = performance.now();
+function frame(now) {
+    const dt = (now - last) / 1000; last = now;
+    stage.tick(dt);                // advances every active reveal
+    requestAnimationFrame(frame);
+}
+requestAnimationFrame(frame);
+```
+
+Each controller reserves `capacity` slots from `maxParticles` (reserving past the pool
+throws), renders only its own particles, and keeps its own deterministic RNG. Stage-managed
+controllers have no `tick` of their own — the stage drives them. The per-frame `stage.tick`
+is allocation-free even with many reveals in flight (torture-gated). Use `createScratchStage`
+for a live grid of simultaneous reveals; use `{ engine }` when reveals are one-at-a-time and
+you just want the memory saving; use the default per-controller engine for a single card.
+
 ## 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.
+By default the particle engine (`@zakkster/lite-soa-particle-engine`) self-drives its own
+animation-frame loop and computes its own delta time. There are exactly three single-drive
+modes, none of which can double-drive the loop:
+
+- **default** — the engine self-drives (`start()`/`stop()`).
+- **`{ driven: true }`** — the host drives via `controller.tick(dt)` *instead of* the engine's
+  RAF (see [Scaling to a grid](#scaling-to-a-grid-of-scratch-boxes)).
+- **`createScratchStage`** — the stage drives all its controllers via `stage.tick(dt)`.
+
+The removed `sharedTicker` option was a different thing: it drove the engine loop *in addition*
+to the engine's own RAF, double-driving it and corrupting `dt` (breaking life decay and
+completion). Driven mode replaces it correctly — one clock, one drive.
 
 ## Dependencies
 

package/index.d.ts

@@ -2,6 +2,18 @@
  * @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;
@@ -73,20 +85,39 @@ 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;
 }
 
 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. */
+    /** Stop, clean up the active recipe, and release the engine (owned engines only). */
     destroy(): void;
 }
 
@@ -101,6 +132,56 @@ export function createScratchController(
 
 export { createScratchController as ScratchController };
 
+// ── 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;
+}
+
+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;
+}
+
+/** 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;
+    /** 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 {
@@ -143,8 +224,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.2.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 })
+  -> { reveal(recipe, onDone?), tick(dt), 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() })
+  -> { createController(src, fx, { capacity = 300, seed?, scanPrecision = 32 }) -> stageController,
+       tick(dt), destroy(), get remainingCapacity }
+stageController -> { reveal(recipe, onDone?), 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.2.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,8 @@
     "index.d.ts",
     "src/ScratchController.js",
     "src/ScratchRecipes.js",
-    "src/ScratchRecipes2.js",
+    "src/ScratchStage.js",
+    "src/PixelScan.js",
     "src/Palette.js",
     "README.md",
     "CHANGELOG.md",
@@ -55,7 +56,9 @@
     "game",
     "zero-gc",
     "deterministic",
-    "oklch",
+    "theme",
+    "reveal-animation",
+    "scratch-off",
     "zakkster"
   ],
   "devDependencies": {