@zakkster/lite-scratch-fx 1.3.2 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [1.4.0] - 2026-08-23
+
+Determinism, recipe tuning, and stage lane reclaim. One backward-compatible interface
+addition -- a 5th `rng` argument to `recipe.init`; recipes that ignore it are unaffected.
+
+### Added
+- **Seeded RNG passed to `recipe.init` (B-14).** `recipe.init(ctx, capacity, w, h, rng)` now
+  receives the controller's or stage's seeded `Random` as an additive 5th argument.
+  `dragonBreath`, `shineWave`, and `lightningCrawl` drew from `Math.random()` in `init`/`tick`,
+  breaking reproducibility; they now draw from `rng`, so two reveals at the same seed produce
+  byte-identical lanes. Recipes with a shorter `init` signature ignore the argument.
+- **Stage sub-range reclaim (B-8).** `createScratchStage` keeps a free list of released lane
+  ranges; `controller.destroy()` returns its `[start, capacity)` range and `createController`
+  reuses an exact-capacity match before extending the pool, so a grid rebuilt after destroying
+  all controllers no longer throws `pool exhausted`. `remainingCapacity` counts the free list.
+  `cancel()` and completion do not reclaim -- the range stays reserved and the controller is
+  revealable. The per-frame tick path is byte-identical (the free list is touched only in
+  `createController`/`destroy`).
+
+### Changed
+- **`burn` retuned to a 0.2 s flash (B-15).** Defaults `count` 150 -> 100, `duration` 1500 -> 200
+  ms; spawn `size` 2-5 -> 3-8, `decay` 0.01-0.03 -> 0.02-0.05, upward `vy` -1..-4 -> -7..-2. The
+  additive gravity term `vy += 0.1 * ds` is removed and the cover fade is power2.in (`1 - t*t`)
+  instead of the cubic `easeIn`. Matches the consuming renderer's burn.
+- **`iceBreath` default `count` 300 -> 450 (B-16).**
+
+### Removed
+- `Math.random()` from `dragonBreath`, `shineWave`, and `lightningCrawl` (replaced by the
+  seeded `rng`).
+
 ## [1.3.2] - 2026-08-23
 
 Recipe-fidelity pass against the consuming renderer. No API or signature change; the

package/README.md

@@ -36,7 +36,7 @@ import { createScratchController, BurnRecipe } from '@zakkster/lite-scratch-fx';
 const fx = createScratchController(scratchCanvas, fxCanvas, { seed: 42 });
 
 revealButton.onclick = () => {
-    fx.reveal(BurnRecipe({ duration: 1500 }), () => {
+    fx.reveal(BurnRecipe(), () => {
         console.log('prize revealed');
     });
 };
@@ -131,7 +131,7 @@ 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
+        init(ctx, capacity, w, h, rng) {         // allocate arrays; rng = seeded Random (same one passed to spawn), use instead of Math.random for reproducible reveals
             size = new Float32Array(capacity);
         },
         spawn(idx, rng, w, h, spot) {            // one particle; spot is 0..1 on the layer
@@ -261,7 +261,7 @@ resolvePalette(colors, theme, fallback): string[]
 
 | Constant                  | Value                                                        | Meaning                                              |
 | ------------------------- | ----------------------------------------------------------- | ---------------------------------------------------- |
-| `VERSION`                 | `'1.3.2'`                                                    | Package version string (synced to package.json).     |
+| `VERSION`                 | `'1.4.0'`                                                    | Package version string (synced to package.json).     |
 | `maxParticles` (default)  | `2000`                                                       | Controller / stage pool capacity.                    |
 | `scanPrecision` (default) | `32`                                                         | Horizontal resolution of the spawn-point scan.       |
 | stage `capacity` (default)| `300`                                                       | Slots a stage controller reserves from the pool.     |

package/index.d.ts

@@ -69,7 +69,8 @@ export interface RecipeRng {
 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;
+    /** `rng` is the controller/stage's seeded Random instance (same one passed to spawn); use it instead of Math.random for reproducible reveals. */
+    init(ctx: CanvasRenderingContext2D, capacity: number, w: number, h: number, rng: RecipeRng): 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(
@@ -183,7 +184,10 @@ export interface StageController {
      * 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). */
+    /**
+     * Remove this controller from the stage. Its sub-range is reclaimed into the stage
+     * free-list for exact-capacity reuse by a later createController.
+     */
     destroy(): void;
 }
 

package/index.js

@@ -13,7 +13,7 @@
 
 // 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.2';
+export const VERSION = '1.4.0';
 
 export { createScratchController } from './src/ScratchController.js';
 export { default as ScratchController } from './src/ScratchController.js';

package/llms.txt

@@ -32,7 +32,7 @@ A second reveal while one is active is ignored.
 
 {
   count,                                    // particles to spawn; 0 = pure-canvas reveal
-  init(ctx, capacity, w, h),                // allocate parallel per-particle arrays
+  init(ctx, capacity, w, h, rng),           // allocate arrays; rng = seeded Random (same as spawn), use instead of Math.random for reproducible reveals
   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(),
@@ -116,6 +116,8 @@ start+capacity) of the lanes. reserving past maxParticles throws. Each controlle
 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.
+controller.destroy() reclaims its sub-range into a stage free-list for exact-capacity reuse by a
+later createController; cancel/completion hold the range (the controller stays revealable).
 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.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zakkster/lite-scratch-fx",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "version": "1.3.2",
+  "version": "1.4.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",

package/src/ScratchController.js

@@ -204,7 +204,7 @@ export function createScratchController(sourceCanvas, effectCanvas, {
             const spots = scanner.scan(scanPrecision);
 
             // Init recipe with LOGICAL size (recipes stay in CSS px).
-            recipe.init(ctx, cap, logicalW, logicalH);
+            recipe.init(ctx, cap, logicalW, logicalH, rng);
 
             // Populate ring buffer. A recipe may declare `count: 0` (a pure-canvas reveal
             // like Shine or Implosion that draws no particles); use ?? so an explicit 0 is

package/src/ScratchRecipes.js

@@ -5,7 +5,7 @@
  * ScratchController.reveal(recipe, onDone). Grouped by family below.
  *
  * Recipe interface:
- *   { count, init(ctx, capacity, w, h),
+ *   { count, init(ctx, capacity, w, h, rng),
  *     spawn(idx, rng, w, h, spot),
  *     tick(dt, elapsedMs, engine, ctx, sourceCanvas, w, h) -> boolean,
  *     destroy() }
@@ -28,7 +28,7 @@ import {resolvePalette} from './Palette.js';
 //  Spawn particles from the scratch layer's still-covered pixels and run their own physics.
 // ===========================================================================
 
-export function BurnRecipe({count = 150, duration = 1500, colors, theme} = {}) {
+export function BurnRecipe({count = 100, duration = 200, colors, theme} = {}) {
     let pSize, pDecay, pColorIdx;
     const palette = resolvePalette(colors, theme, ['#ff6b00', '#ff8c00', '#ffaa00', '#ff4500', '#8B0000']);
 
@@ -40,22 +40,21 @@ export function BurnRecipe({count = 150, duration = 1500, colors, theme} = {}) {
             pColorIdx = new Uint8Array(capacity);
         },
         spawn(idx, rng, w, h, spot) {
-            pSize[idx] = rng.range(2, 5);
-            pDecay[idx] = rng.range(0.01, 0.03);
+            pSize[idx] = rng.range(3, 8);
+            pDecay[idx] = rng.range(0.02, 0.05);
             pColorIdx[idx] = rng.int(0, palette.length - 1);
-            return {x: spot.x * w, y: spot.y * h, vx: rng.range(-1, 1), vy: rng.range(-1, -4), life: 1.0};
+            return {x: spot.x * w, y: spot.y * h, vx: rng.range(-1, 1), vy: rng.range(-7, -2), life: 1.0};
         },
         tick(dt, elapsed, engine, ctx, src, w, h) {
             const {x, y, vx, vy, life, data, max} = engine;
             const ds = dt * 60;
             let alive = 0;
             const progress = clamp(elapsed / duration, 0, 1);
-            src.style.opacity = 1 - easeIn(progress);
+            src.style.opacity = 1 - progress * progress;
 
             for (let i = 0; i < max; i++) {
                 if (life[i] <= 0) continue;
                 const p = data[i];
-                vy[i] += 0.1 * ds;
                 x[i] += vx[i] * ds;
                 y[i] += vy[i] * ds;
                 life[i] -= pDecay[p] * ds;
@@ -173,12 +172,13 @@ export function ExplodeRecipe({count = 80, duration = 750, force = 15, colors, t
 
 
 export function DragonBreathRecipe({count = 200, duration = 1200, colors, theme} = {}) {
-    let pSize, pDecay, pColorIdx;
+    let pSize, pDecay, pColorIdx, r;
     const palette = resolvePalette(colors, theme, ['#FFF', '#FFD700', '#FF4500', '#8B0000', '#2F2F2F']);
 
     return {
         count,
-        init(ctx, capacity) {
+        init(ctx, capacity, w, h, rng) {
+            r = rng;
             pSize = new Float32Array(capacity);
             pDecay = new Float32Array(capacity);
             pColorIdx = new Uint8Array(capacity);
@@ -210,7 +210,7 @@ export function DragonBreathRecipe({count = 200, duration = 1200, colors, theme}
                 const p = data[i];
                 x[i] += vx[i] * ds;
                 y[i] += vy[i] * ds;
-                vx[i] += (Math.random() - 0.5) * 0.5 * ds;
+                vx[i] += (r.next() - 0.5) * 0.5 * ds;
                 vy[i] *= dvy;
                 pSize[p] *= dsz;
                 life[i] -= pDecay[p] * ds;
@@ -233,13 +233,13 @@ export function DragonBreathRecipe({count = 200, duration = 1200, colors, theme}
             return alive === 0 && elapsed >= duration;
         },
         destroy() {
-            pSize = pDecay = pColorIdx = null;
+            pSize = pDecay = pColorIdx = r = null;
         },
     };
 }
 
 
-export function IceBreathRecipe({count = 300, duration = 1500, colors, theme} = {}) {
+export function IceBreathRecipe({count = 450, duration = 1500, colors, theme} = {}) {
     let pSize, pDecay, pRot, pRotSpd, pColorIdx;
     const palette = resolvePalette(colors, theme, ['#FFF', '#E0FFFF', '#00FFFF', '#1E90FF', '#4682B4']);
 
@@ -871,22 +871,23 @@ export function ShineRecipe({duration = 500, width = 250} = {}) {
 
 export function ShineWaveRecipe({duration = 600, beamWidth = 80, particleCount = 60, colors, theme} = {}) {
     const palette = resolvePalette(colors, theme, ['#FFF', '#E0E8FF', '#B0C4FF', '#88AAFF']);
-    let py, pvy, pox, psz, pcol;
+    let py, pvy, pox, psz, pcol, r;
 
     return {
         count: 0, // No SoA particles -- managed internally
-        init(ctx, capacity, w, h) {
+        init(ctx, capacity, w, h, rng) {
+            r = rng;
             py = new Float32Array(particleCount);
             pvy = new Float32Array(particleCount);
             pox = new Float32Array(particleCount);
             psz = new Float32Array(particleCount);
             pcol = new Uint8Array(particleCount);
             for (let i = 0; i < particleCount; i++) {
-                py[i] = Math.random() * h;
-                pvy[i] = (Math.random() - 0.5) * 2;
-                pox[i] = (Math.random() - 0.5) * beamWidth * 0.6;
-                psz[i] = Math.random() * 4 + 2;
-                pcol[i] = (Math.random() * palette.length) | 0;
+                py[i] = r.next() * h;
+                pvy[i] = (r.next() - 0.5) * 2;
+                pox[i] = (r.next() - 0.5) * beamWidth * 0.6;
+                psz[i] = r.next() * 4 + 2;
+                pcol[i] = (r.next() * palette.length) | 0;
             }
         },
         spawn() {
@@ -916,10 +917,10 @@ export function ShineWaveRecipe({duration = 600, beamWidth = 80, particleCount =
             for (let i = 0; i < particleCount; i++) {
                 const px2 = bx + pox[i];
                 py[i] += pvy[i] * ds;
-                pvy[i] += (Math.random() - 0.5) * 0.3 * ds;
+                pvy[i] += (r.next() - 0.5) * 0.3 * ds;
                 if (py[i] < -10) py[i] = h + 10;
                 if (py[i] > h + 10) py[i] = -10;
-                psz[i] = clamp(psz[i] + (Math.random() - 0.5) * 0.3 * ds, 1, 8);
+                psz[i] = clamp(psz[i] + (r.next() - 0.5) * 0.3 * ds, 1, 8);
                 ctx.globalAlpha = 0.7;
                 ctx.fillStyle = palette[pcol[i]];
                 ctx.save();
@@ -932,7 +933,7 @@ export function ShineWaveRecipe({duration = 600, beamWidth = 80, particleCount =
             return raw >= 1;
         },
         destroy() {
-            py = pvy = pox = psz = pcol = null;
+            py = pvy = pox = psz = pcol = r = null;
         },
     };
 }
@@ -1013,6 +1014,7 @@ export function LightningCrawlRecipe({boltCount = 5, duration = 600, colors, the
     const cMid = palette[(palette.length - 1) >> 1];
     const cOuter = palette[palette.length - 1];
     let bolts = [];
+    let r;
 
     function genPts(x1, y1, x2, y2, d) {
         let p = [{x: x1, y: y1}, {x: x2, y: y2}];
@@ -1022,7 +1024,7 @@ export function LightningCrawlRecipe({boltCount = 5, duration = 600, colors, the
                 const a = p[j], b = p[j + 1];
                 const mx = (a.x + b.x) / 2, my = (a.y + b.y) / 2;
                 const dist = Math.hypot(b.x - a.x, b.y - a.y);
-                const off = (Math.random() - 0.5) * dist * 0.4;
+                const off = (r.next() - 0.5) * dist * 0.4;
                 const nx = -(b.y - a.y) / (dist || 1), ny = (b.x - a.x) / (dist || 1);
                 np.push({x: mx + nx * off, y: my + ny * off});
                 np.push(b);
@@ -1045,39 +1047,40 @@ export function LightningCrawlRecipe({boltCount = 5, duration = 600, colors, the
             ctx.stroke();
         });
         if (d > 2) for (let i = 2; i < pts.length - 1; i += 3) {
-            if (Math.random() > 0.5) continue;
-            const bl = Math.hypot(x2 - x1, y2 - y1) * (0.15 + Math.random() * 0.2);
-            const ba = Math.atan2(y2 - y1, x2 - x1) + (Math.random() - 0.5) * 1.5;
+            if (r.next() > 0.5) continue;
+            const bl = Math.hypot(x2 - x1, y2 - y1) * (0.15 + r.next() * 0.2);
+            const ba = Math.atan2(y2 - y1, x2 - x1) + (r.next() - 0.5) * 1.5;
             drawBolt(ctx, pts[i].x, pts[i].y, pts[i].x + Math.cos(ba) * bl, pts[i].y + Math.sin(ba) * bl, th * 0.5, d - 2);
         }
     }
 
     return {
         count: 0,
-        init(ctx, capacity, w, h) {
+        init(ctx, capacity, w, h, rng) {
+            r = rng;
             bolts = [];
             for (let b = 0; b < boltCount; b++) {
-                const e = (Math.random() * 4) | 0;
+                const e = (r.next() * 4) | 0;
                 let sx, sy;
                 if (e === 0) {
                     sx = 0;
-                    sy = Math.random() * h;
+                    sy = r.next() * h;
                 } else if (e === 1) {
                     sx = w;
-                    sy = Math.random() * h;
+                    sy = r.next() * h;
                 } else if (e === 2) {
-                    sx = Math.random() * w;
+                    sx = r.next() * w;
                     sy = 0;
                 } else {
-                    sx = Math.random() * w;
+                    sx = r.next() * w;
                     sy = h;
                 }
                 bolts.push({
                     sx,
                     sy,
-                    ex: w * (0.3 + Math.random() * 0.4),
-                    ey: h * (0.3 + Math.random() * 0.4),
-                    delay: Math.random() * 0.3
+                    ex: w * (0.3 + r.next() * 0.4),
+                    ey: h * (0.3 + r.next() * 0.4),
+                    delay: r.next() * 0.3
                 });
             }
         },
@@ -1109,6 +1112,7 @@ export function LightningCrawlRecipe({boltCount = 5, duration = 600, colors, the
         },
         destroy() {
             bolts = [];
+            r = null;
         },
     };
 }

package/src/ScratchStage.js

@@ -46,6 +46,12 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
     const pending = new Set();
     let dispatching = false;
     let nextStart = 0;
+    // Free-list of reclaimed [start, capacity] ranges from destroyed controllers, in
+    // parallel arrays. Exact-match reuse only: a new controller reclaims a range solely
+    // when its capacity equals a freed one. Cold path (createController/destroy) -- never
+    // touched per frame.
+    const freeStart = [], freeCap = [];
+    let reclaimedCapacity = 0;
     let controllerCount = 0;
     let destroyed = false;
 
@@ -89,13 +95,32 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
         if (!(typeof dpr === 'number' && Number.isFinite(dpr) && dpr > 0)) {
             throw new TypeError('createController: dpr must be a positive finite number');
         }
-        if (nextStart + capacity > maxParticles) {
-            throw new RangeError(
-                `createController: pool exhausted -- ${nextStart}+${capacity} exceeds maxParticles ${maxParticles}`,
-            );
+        // Reclaim an exact-capacity range from a destroyed controller before growing the
+        // pool. On a hit we skip the nextStart bump and the exhaustion throw entirely.
+        let start;
+        let reused = -1;
+        for (let i = 0; i < freeCap.length; i++) {
+            if (freeCap[i] === capacity) { reused = i; break; }
         }
-        const start = nextStart;
-        nextStart += capacity;
+        if (reused >= 0) {
+            start = freeStart[reused];
+            // Swap-remove: order is irrelevant for exact-match reuse.
+            const last = freeCap.length - 1;
+            freeStart[reused] = freeStart[last];
+            freeCap[reused] = freeCap[last];
+            freeStart.pop();
+            freeCap.pop();
+            reclaimedCapacity -= capacity;
+        } else {
+            if (nextStart + capacity > maxParticles) {
+                throw new RangeError(
+                    `createController: pool exhausted -- ${nextStart}+${capacity} exceeds maxParticles ${maxParticles}`,
+                );
+            }
+            start = nextStart;
+            nextStart += capacity;
+        }
+        // A reused range is a NEW controller, so the index always advances -> new default seed.
         const index = controllerCount++;
 
         const ctx = effectCanvas.getContext('2d');
@@ -133,7 +158,8 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
         // The single terminator for this controller's reveal. Completion (fireDone=true),
         // cancel() (false), and destroy() (false) all route here so the recipe teardown,
         // host-style restore, canvas clear, and active-set removal happen in one place.
-        // Cold path: once per reveal, never per frame. Sub-range stays reserved (B-8).
+        // Cold path: once per reveal, never per frame. The sub-range is held across every
+        // completion and cancel, and reclaimed into the stage free-list only on destroy() (B-8).
         function endReveal(fireDone) {
             if (!activeRecipe) return;
             if (activeRecipe.destroy) activeRecipe.destroy();
@@ -171,7 +197,7 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
                 hostSnapshot = captureHostStyle(sourceCanvas);
 
                 const spots = scanner.scan(scanPrecision);
-                recipe.init(ctx, capacity, cw, ch);
+                recipe.init(ctx, capacity, cw, ch, rng);
 
                 const requested = recipe.count ?? capacity;
                 const count = Math.min(requested, capacity);
@@ -224,7 +250,10 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
             /** Re-seed this controller's RNG. */
             seed(s) { rng.reset(s); },
 
-            /** Remove this controller from the stage. Its sub-range is not reclaimed (v1). */
+            /**
+             * Remove this controller from the stage. Its sub-range is reclaimed into the
+             * stage free-list for exact-capacity reuse by a later createController.
+             */
             destroy() {
                 if (ctlDestroyed) return;
                 ctlDestroyed = true;
@@ -232,6 +261,9 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
                 // host-style restore, active-set removal, no onDone) before scanner teardown.
                 endReveal(false);
                 scanner.destroy();
+                // Reclaim the sub-range. The early-return above guarantees one push per
+                // controller, so a double-destroy cannot double-free.
+                freeStart.push(start); freeCap.push(capacity); reclaimedCapacity += capacity;
             },
         };
         return controller;
@@ -256,7 +288,7 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
         },
 
         /** @internal How many slots are still unreserved (for tests / diagnostics). */
-        get remainingCapacity() { return maxParticles - nextStart; },
+        get remainingCapacity() { return maxParticles - nextStart + reclaimedCapacity; },
     };
 }