@zakkster/lite-scratch-fx 1.3.1 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # 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
+default owned-engine path and 60 Hz playback are byte-identical to 1.3.1.
+
+### Changed
+- **Frame-rate-independent recipe physics (B-12).** Every per-tick physics term in the
+  nine affected recipes (`burn`, `dragonBreath`, `iceBreath`, `shatter`, `pixelShatter`,
+  `cosmicDust`, `confettiBlast`, `liquidMelt`, `shineWave`) now scales with `ds = dt * 60`:
+  additive gravity/turbulence/rotation by `* ds`, multiplicative damping by
+  `Math.pow(k, ds)`, and the `dragonBreath` size ramp by `Math.pow(1.04, ds)`. Position
+  and life were already real-time while damping/gravity/rotation were still per-tick, so a
+  trajectory's shape changed with refresh rate -- `iceBreath`'s `*= 0.96` damping retained
+  0.0864 of velocity per second at 60 Hz but 0.0075 at 120 Hz, an 11.6x divergence. At
+  `dt = 1/60`, `ds === 1` exactly, so every term collapses to its former constant
+  (0-ULP identical, locked by test). `Math.random()` calls are unchanged.
+- **Particle glow is a painted halo instead of `ctx.shadowBlur` (B-13).** `burn`,
+  `dragonBreath`, and `laserScan` drew a per-particle Gaussian shadow blur every frame;
+  they now paint a second arc at twice the radius with `globalAlpha = life * 0.3` behind
+  the crisp core, in the particle's existing composite mode. `laserScan`'s halo uses the
+  themed `palette[0]` (previously inherited white).
+- **Shared `{ engine }` capacity derives from `engine.x.length` (B-9).** On the shared-engine
+  path the recipe's parallel arrays and the `count` clamp are now sized to the supplied
+  engine's lane length rather than `maxParticles`, so an engine larger than `maxParticles`
+  can no longer write past the recipe arrays (previously silent out-of-range writes,
+  yielding size-0 particles). The owned-engine path is unaffected (`engine.x.length ===
+  maxParticles`). JSDoc, `index.d.ts`, and the README option table updated to match.
+
+### Added
+- Offscreen draw cull (B-17): `burn`, `dragonBreath`, `iceBreath`, and `explode` skip the
+  draw for a particle once `y < -50`; the particle is still updated and alive (draw-only).
+- Stage: a reveal started from within a controller's `onDone` (which fires during the
+  fan-out) is deferred to the next tick via a per-stage `pending` set, so the freshly
+  revealed controller is not given a frame in the tick it was created (B-11).
+
+### Removed
+- All `ctx.shadowBlur` / `ctx.shadowColor` use in recipes (replaced by the painted halo).
+- The two redundant `ctx.save()` / `ctx.restore()` pairs in `explode` and `dragonBreath`,
+  which set no per-particle transform; state is now set directly.
+
+### Fixed
+- The stage `onTick` fan-out is wrapped in `try/finally` so a throwing `_frame` cannot
+  strand the internal `dispatching` flag, which would otherwise silently defer every
+  subsequent reveal.
+- The `createScratchStage` fan-out comment no longer contradicts itself (it claimed both to
+  avoid a Set copy and to iterate a snapshot); it now states that Set deletion during
+  `for...of` is safe and that the real subtlety is `onDone` firing mid-loop.
+
 ## [1.3.1] - 2026-08-22
 
 ### Fixed

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
@@ -190,7 +190,7 @@ createScratchController(sourceCanvas, effectCanvas, options?): ScratchController
 
 | Option         | Type              | Default       | Meaning                                             |
 | -------------- | ----------------- | ------------- | --------------------------------------------------- |
-| `maxParticles` | number            | `2000`        | Particle pool capacity (ignored when `engine` given) |
+| `maxParticles` | number            | `2000`        | Sizes the owned pool; when `engine` is given the capacity is taken from `engine.x.length` and this is ignored |
 | `seed`         | number            | `Date.now()`  | Deterministic RNG seed                              |
 | `scanPrecision`| number            | `32`          | Horizontal resolution of the spawn-point pixel scan |
 | `driven`       | boolean           | `false`       | Host-driven mode: you call `tick(dt)` each frame    |
@@ -261,7 +261,7 @@ resolvePalette(colors, theme, fallback): string[]
 
 | Constant                  | Value                                                        | Meaning                                              |
 | ------------------------- | ----------------------------------------------------------- | ---------------------------------------------------- |
-| `VERSION`                 | `'1.3.0'`                                                    | 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(
@@ -85,7 +86,7 @@ export interface Recipe {
 }
 
 export interface ScratchControllerOptions {
-    /** Particle pool capacity. Default 2000. Ignored when `engine` is supplied. */
+    /** Sizes the owned pool. Default 2000. When `engine` is supplied the capacity is taken from `engine.x.length` and this is ignored. */
     maxParticles?: number;
     /** Seed for the deterministic RNG. Default `Date.now()`. */
     seed?: number;
@@ -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.1';
+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.1",
+  "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

@@ -54,7 +54,9 @@ const busySharedEngines = new WeakSet();
  * @param {HTMLCanvasElement} sourceCanvas  The scratch layer being revealed
  * @param {HTMLCanvasElement} effectCanvas  Overlay canvas for VFX
  * @param {Object} [options]
- * @param {number} [options.maxParticles=2000]  Pool capacity (ignored when `engine` is given)
+ * @param {number} [options.maxParticles=2000]  Sizes the owned pool; when `engine` is supplied
+ *                                               the capacity is taken from `engine.x.length` and
+ *                                               maxParticles is ignored.
  * @param {number} [options.seed=Date.now()]     Deterministic RNG seed
  * @param {number} [options.scanPrecision=32]     Horizontal resolution of the pixel scan
  * @param {boolean} [options.driven=false]        Host-driven: skip start(), call tick(dt)
@@ -175,6 +177,14 @@ export function createScratchController(sourceCanvas, effectCanvas, {
             }
             engine.clear();
 
+            // Real pool capacity of the engine we actually write into. The slot index comes
+            // from engine._head, which ranges over the ENGINE's capacity, so the recipe arrays
+            // and count clamp must be sized to THAT, not maxParticles. For an owned engine
+            // (new SoaParticleEngine(maxParticles)) cap === maxParticles -- byte-identical to
+            // the old path. For a shared engine larger than maxParticles this stops spawn()
+            // from writing past the recipe arrays (size-0 particles, palette[undefined]).
+            const cap = engine.x.length;
+
             // Logical (CSS-pixel) size of the scratch layer -- recipes author in these.
             logicalW = sourceCanvas.offsetWidth || sourceCanvas.width;
             logicalH = sourceCanvas.offsetHeight || sourceCanvas.height;
@@ -194,13 +204,13 @@ export function createScratchController(sourceCanvas, effectCanvas, {
             const spots = scanner.scan(scanPrecision);
 
             // Init recipe with LOGICAL size (recipes stay in CSS px).
-            recipe.init(ctx, maxParticles, 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
-            // honoured rather than falling back to maxParticles.
-            const requested = recipe.count ?? maxParticles;
-            const count = Math.min(requested, maxParticles);
+            // honoured rather than falling back to the pool capacity.
+            const requested = recipe.count ?? cap;
+            const count = Math.min(requested, cap);
             for (let i = 0; i < count; i++) {
                 const idx = engine._head;
                 if (spots.count > 0) {

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,36 +40,38 @@ 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;
-                x[i] += vx[i] * dt * 60;
-                y[i] += vy[i] * dt * 60;
-                life[i] -= pDecay[p] * dt * 60;
+                x[i] += vx[i] * ds;
+                y[i] += vy[i] * ds;
+                life[i] -= pDecay[p] * ds;
                 if (life[i] <= 0) continue;
                 alive++;
-                ctx.globalAlpha = life[i];
+                if (y[i] < -50) continue;
                 ctx.globalCompositeOperation = 'lighter';
                 ctx.fillStyle = palette[pColorIdx[p]];
-                ctx.shadowBlur = 10;
-                ctx.shadowColor = ctx.fillStyle;
+                ctx.globalAlpha = life[i] * 0.3;
+                ctx.beginPath();
+                ctx.arc(x[i], y[i], pSize[p] * 2, 0, Math.PI * 2);
+                ctx.fill();
+                ctx.globalAlpha = life[i];
                 ctx.beginPath();
                 ctx.arc(x[i], y[i], pSize[p], 0, Math.PI * 2);
                 ctx.fill();
             }
-            ctx.shadowBlur = 0;
             ctx.globalCompositeOperation = 'source-over';
             ctx.globalAlpha = 1;
             return alive === 0 && elapsed >= duration;
@@ -152,14 +154,14 @@ export function ExplodeRecipe({count = 80, duration = 750, force = 15, colors, t
                 life[i] -= 0.02 * dt * 60;
                 if (life[i] <= 0) continue;
                 alive++;
-                ctx.save();
+                if (y[i] < -50) continue;
                 ctx.globalAlpha = life[i];
                 ctx.fillStyle = palette[pColorIdx[p]];
                 ctx.beginPath();
                 ctx.arc(x[i], y[i], pSize[p], 0, Math.PI * 2);
                 ctx.fill();
-                ctx.restore();
             }
+            ctx.globalAlpha = 1;
             return alive === 0 && elapsed >= duration;
         },
         destroy() {
@@ -170,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);
@@ -196,44 +199,47 @@ export function DragonBreathRecipe({count = 200, duration = 1200, colors, theme}
         },
         tick(dt, elapsed, engine, ctx, src, w, h) {
             const {x, y, vx, vy, life, data, max} = engine;
+            const ds = dt * 60;
+            const dvy = Math.pow(0.98, ds);
+            const dsz = Math.pow(1.04, ds);
             let alive = 0;
             src.style.opacity = 1 - clamp(elapsed / (duration * 0.4), 0, 1);
 
             for (let i = 0; i < max; i++) {
                 if (life[i] <= 0) continue;
                 const p = data[i];
-                x[i] += vx[i] * dt * 60;
-                y[i] += vy[i] * dt * 60;
-                vx[i] += (Math.random() - 0.5) * 0.5;
-                vy[i] *= 0.98;
-                pSize[p] *= 1 + 0.04 * dt * 60;
-                life[i] -= pDecay[p] * dt * 60;
+                x[i] += vx[i] * ds;
+                y[i] += vy[i] * ds;
+                vx[i] += (r.next() - 0.5) * 0.5 * ds;
+                vy[i] *= dvy;
+                pSize[p] *= dsz;
+                life[i] -= pDecay[p] * ds;
                 if (life[i] <= 0) continue;
                 alive++;
-                ctx.save();
-                ctx.globalAlpha = life[i];
+                if (y[i] < -50) continue;
                 ctx.globalCompositeOperation = 'lighter';
-                ctx.shadowBlur = 15;
-                ctx.shadowColor = palette[pColorIdx[p]];
                 ctx.fillStyle = palette[pColorIdx[p]];
+                ctx.globalAlpha = life[i] * 0.3;
+                ctx.beginPath();
+                ctx.arc(x[i], y[i], pSize[p] * 2, 0, Math.PI * 2);
+                ctx.fill();
+                ctx.globalAlpha = life[i];
                 ctx.beginPath();
                 ctx.arc(x[i], y[i], pSize[p], 0, Math.PI * 2);
                 ctx.fill();
-                ctx.restore();
             }
-            ctx.shadowBlur = 0;
             ctx.globalCompositeOperation = 'source-over';
             ctx.globalAlpha = 1;
             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']);
 
@@ -264,6 +270,8 @@ export function IceBreathRecipe({count = 300, duration = 1500, colors, theme} =
         },
         tick(dt, elapsed, engine, ctx, src, w, h) {
             const {x, y, vx, vy, life, data, max} = engine;
+            const ds = dt * 60;
+            const dv = Math.pow(0.96, ds);
             let alive = 0;
             const t = clamp(elapsed / (duration * 0.4), 0, 1);
             src.style.opacity = 1 - t;
@@ -272,14 +280,15 @@ export function IceBreathRecipe({count = 300, duration = 1500, colors, theme} =
             for (let i = 0; i < max; i++) {
                 if (life[i] <= 0) continue;
                 const p = data[i];
-                x[i] += vx[i] * dt * 60;
-                y[i] += vy[i] * dt * 60;
-                vx[i] *= 0.96;
-                vy[i] *= 0.96;
-                pRot[p] += pRotSpd[p];
-                life[i] -= pDecay[p] * dt * 60;
+                x[i] += vx[i] * ds;
+                y[i] += vy[i] * ds;
+                vx[i] *= dv;
+                vy[i] *= dv;
+                pRot[p] += pRotSpd[p] * ds;
+                life[i] -= pDecay[p] * ds;
                 if (life[i] <= 0) continue;
                 alive++;
+                if (y[i] < -50) continue;
                 ctx.save();
                 ctx.globalAlpha = life[i];
                 ctx.globalCompositeOperation = 'screen';
@@ -403,7 +412,7 @@ export function ConfettiBlastRecipe({count = 80, duration = 1500, colors, theme}
                 if (life[i] <= 0) continue;
                 const p = data[i];
 
-                vy[i] += 0.5; // Gravity
+                vy[i] += 0.5 * ds; // Gravity
                 x[i] += vx[i] * ds;
                 y[i] += vy[i] * ds;
                 pWobblePhase[p] += pWobbleSpeed[p] * ds;
@@ -451,6 +460,7 @@ export function CosmicDustRecipe({count = 200, duration = 1800, colors, theme} =
         tick(dt, elapsed, engine, ctx, src, w, h) {
             const {x, y, life, data, max} = engine;
             const ds = dt * 60;
+            const dr = Math.pow(0.95, ds);
             let alive = 0;
             const cx = w / 2, cy = h / 2;
 
@@ -461,7 +471,7 @@ export function CosmicDustRecipe({count = 200, duration = 1800, colors, theme} =
                 if (life[i] <= 0) continue;
                 const p = data[i];
 
-                pRadius[p] *= 0.95; // Spiral inward
+                pRadius[p] *= dr; // Spiral inward
                 pAngle[p] += 0.2 * ds; // Spin
                 x[i] = cx + Math.cos(pAngle[p]) * pRadius[p];
                 y[i] = cy + Math.sin(pAngle[p]) * pRadius[p];
@@ -584,7 +594,7 @@ export function LiquidMeltRecipe({count = 100, duration = 1200, colors, theme} =
                 if (life[i] <= 0) continue;
                 const p = data[i];
 
-                vy[i] += 0.4; // Heavy gravity
+                vy[i] += 0.4 * ds; // Heavy gravity
                 y[i] += vy[i] * ds;
                 life[i] -= 0.015 * ds;
                 if (life[i] <= 0 || y[i] > h + 30) {
@@ -651,16 +661,17 @@ export function ShatterRecipe({count = 30, duration = 1200, gravity = 0.5} = {})
             if (!img.complete) return false;
 
             const {x, y, vx, vy, life, data, max} = engine;
+            const ds = dt * 60;
             const progress = clamp(elapsed / duration, 0, 1);
             let alive = 0;
 
             for (let i = 0; i < max; i++) {
                 if (life[i] <= 0) continue;
                 const p = data[i];
-                x[i] += vx[i] * dt * 60;
-                y[i] += vy[i] * dt * 60;
-                vy[i] += gravity;
-                pRot[p] += pRotSpd[p];
+                x[i] += vx[i] * ds;
+                y[i] += vy[i] * ds;
+                vy[i] += gravity * ds;
+                pRot[p] += pRotSpd[p] * ds;
                 pOpacity[p] = 1 - progress;
                 if (pOpacity[p] <= 0.01) {
                     life[i] = 0;
@@ -723,6 +734,7 @@ export function PixelShatterRecipe({count = 60, duration = 1200} = {}) {
 
             const {x, y, vx, vy, life, data, max} = engine;
             const ds = dt * 60;
+            const dv = Math.pow(0.95, ds);
             const progress = clamp(elapsed / duration, 0, 1);
             let alive = 0;
 
@@ -732,9 +744,9 @@ export function PixelShatterRecipe({count = 60, duration = 1200} = {}) {
                 const p = data[i];
                 x[i] += vx[i] * ds;
                 y[i] += vy[i] * ds;
-                vx[i] *= 0.95;
-                vy[i] *= 0.95; // Drag
-                pRot[p] += pRotSpd[p];
+                vx[i] *= dv;
+                vy[i] *= dv; // Drag
+                pRot[p] += pRotSpd[p] * ds;
                 life[i] -= 0.02 * ds;
                 if (life[i] <= 0) continue;
                 alive++;
@@ -859,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() {
@@ -883,6 +896,7 @@ export function ShineWaveRecipe({duration = 600, beamWidth = 80, particleCount =
         tick(dt, elapsed, engine, ctx, src, w, h) {
             const raw = clamp(elapsed / duration, 0, 1);
             const t = easeInOut(raw);
+            const ds = dt * 60;
             const bx = lerp(-beamWidth, w + beamWidth, t);
             src.style.opacity = t > 0.3 ? 1 - (t - 0.3) / 0.7 : 1;
 
@@ -902,11 +916,11 @@ export function ShineWaveRecipe({duration = 600, beamWidth = 80, particleCount =
             ctx.globalCompositeOperation = 'lighter';
             for (let i = 0; i < particleCount; i++) {
                 const px2 = bx + pox[i];
-                py[i] += pvy[i];
-                pvy[i] += (Math.random() - 0.5) * 0.3;
+                py[i] += pvy[i] * 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, 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();
@@ -919,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;
         },
     };
 }
@@ -955,20 +969,26 @@ export function LaserScanRecipe({duration = 1000, colors, theme} = {}) {
                 ctx.fillStyle = '#ffffff';
                 ctx.fillRect(0, scanY - 1, w, 2);
 
-                // Glow
-                ctx.shadowBlur = 15;
-                ctx.shadowColor = palette[0];
-
-                // Sparks (deterministic positions)
+                // Sparks (deterministic positions) with a painted halo
                 for (let i = 0; i < 5; i++) {
+                    const sx = sparkSeeds[i * 2] * w;
+                    const sy = scanY - sparkSeeds[i * 2 + 1] * 20;
+                    const sr = sparkSeeds[i * 2] * 2;
+                    // Themed glow halo (was shadowColor = palette[0]) behind a white core
+                    ctx.fillStyle = palette[0];
+                    ctx.globalAlpha = 0.3;
                     ctx.beginPath();
-                    ctx.arc(sparkSeeds[i * 2] * w, scanY - sparkSeeds[i * 2 + 1] * 20, sparkSeeds[i * 2] * 2, 0, Math.PI * 2);
+                    ctx.arc(sx, sy, sr * 2, 0, Math.PI * 2);
+                    ctx.fill();
+                    ctx.fillStyle = '#ffffff';
+                    ctx.globalAlpha = 1;
+                    ctx.beginPath();
+                    ctx.arc(sx, sy, sr, 0, Math.PI * 2);
                     ctx.fill();
                 }
 
-                // <- FIX: Reset shadow + composite every frame
-                ctx.shadowBlur = 0;
-                ctx.shadowColor = 'transparent';
+                // <- FIX: Reset alpha + composite every frame
+                ctx.globalAlpha = 1;
                 ctx.globalCompositeOperation = 'source-over';
             }
 
@@ -994,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}];
@@ -1003,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);
@@ -1026,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
                 });
             }
         },
@@ -1090,6 +1112,7 @@ export function LightningCrawlRecipe({boltCount = 5, duration = 600, colors, the
         },
         destroy() {
             bolts = [];
+            r = null;
         },
     };
 }

package/src/ScratchStage.js

@@ -37,17 +37,43 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
     }
     const engine = new SoaParticleEngine(maxParticles);
     const active = new Set();
+    // Adds that arrive DURING a fan-out (a reveal started from another controller's onDone)
+    // are parked here and merged after the loop, so the freshly revealed controller is not
+    // visited in the frame it was born. Reused for the life of the stage (created once,
+    // cleared -- never re-created), so the per-frame path allocates nothing. Per-stage, not
+    // module scope: a reveal on a DIFFERENT stage during this dispatch must land in ITS OWN
+    // active set. tick() is synchronous, so only one stage is ever mid-dispatch.
+    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;
 
     // One render dispatch for the whole pool. Raw tick(dt) hands us the lanes and `max`;
     // we ignore them (each controller holds stable subarray views of its own sub-range) and
-    // fan out to every active reveal. A Set copy is avoided: a controller that completes
-    // removes itself, so iterate a snapshot to stay safe against mid-iteration deletion.
+    // fan out to every active reveal. Deleting the current or a later entry during a
+    // for...of over a Set is already safe, so no snapshot copy is needed for that. The real
+    // subtlety is that endReveal fires onDone DURING this loop, so a reveal started from a
+    // controller's onDone would otherwise be visited in the SAME frame -- `dispatching`
+    // parks such adds in `pending` and merges them once the loop is done.
     engine.onTick((dt) => {
         if (destroyed || active.size === 0) return;
-        for (const c of active) c._frame(dt);
+        dispatching = true;
+        // finally: a throwing _frame must not strand `dispatching` true -- it routes every
+        // future reveal into `pending`, so leaving it set would silently defer them forever.
+        try {
+            for (const c of active) c._frame(dt);
+        } finally {
+            for (const c of pending) active.add(c);
+            pending.clear();
+            dispatching = false;
+        }
     });
 
     /**
@@ -69,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; }
+        }
+        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;
         }
-        const 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');
@@ -113,13 +158,18 @@ 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();
             if (hostSnapshot) { restoreHostStyle(sourceCanvas, hostSnapshot); hostSnapshot = null; }
             ctx.clearRect(0, 0, cw, ch);
             active.delete(controller);
+            // Also drop from pending: if this controller was revealed earlier in THIS same
+            // dispatch (parked in pending) and now completes, the post-loop merge must not
+            // resurrect it into active.
+            pending.delete(controller);
             const done = onComplete;
             activeRecipe = null;
             onComplete = null;
@@ -147,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);
@@ -171,7 +221,10 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
                     engine.data[g] = i;   // local index -> the recipe reads data[i] === i in its window
                 }
                 pView.max = count;
-                active.add(controller);
+                // A reveal started OUTSIDE a dispatch goes straight to active and runs the
+                // same frame. A reveal started DURING a dispatch (from another controller's
+                // onDone) is parked; the post-loop merge adds it, so it starts next frame.
+                (dispatching ? pending : active).add(controller);
             },
 
             /** @internal Called by the stage each frame. */
@@ -197,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;
@@ -205,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;
@@ -224,11 +283,12 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
             if (destroyed) return;
             destroyed = true;
             active.clear();
+            pending.clear();
             engine.destroy();
         },
 
         /** @internal How many slots are still unreserved (for tests / diagnostics). */
-        get remainingCapacity() { return maxParticles - nextStart; },
+        get remainingCapacity() { return maxParticles - nextStart + reclaimedCapacity; },
     };
 }