@zakkster/lite-scratch-fx 1.3.0 → 1.3.2

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## [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
+- **`PeelRecipe`** -- removed a per-frame forced synchronous layout read. `tick`
+  previously read `src.offsetWidth` (a layout property) inside the transform
+  template string on every frame, immediately after writing `style.transform` /
+  `style.transformOrigin`, forcing a synchronous reflow each frame while a peel
+  reveal was active. The source layer's logical width is now captured once in
+  `init` (the engine already measures it to size the effect canvas and passes it
+  as `w`) and reused, so the per-frame `tick` body is write-only. No visual or
+  API change.
+
 ## [1.3.0] - 2026-08-22
 
 Abortable, self-restoring reveals. A reveal can now be cancelled, and the host scratch

package/README.md

@@ -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.3.2'`                                                    | 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

@@ -85,7 +85,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;

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.0';
+export const VERSION = '1.3.2';
 
 export { createScratchController } from './src/ScratchController.js';
 export { default as ScratchController } from './src/ScratchController.js';

package/package.json

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

@@ -47,6 +47,7 @@ export function BurnRecipe({count = 150, 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;
             let alive = 0;
             const progress = clamp(elapsed / duration, 0, 1);
             src.style.opacity = 1 - easeIn(progress);
@@ -54,22 +55,24 @@ export function BurnRecipe({count = 150, duration = 1500, colors, theme} = {}) {
             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;
+                vy[i] += 0.1 * ds;
+                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 +155,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() {
@@ -196,32 +199,35 @@ 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] += (Math.random() - 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;
@@ -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++;
@@ -883,6 +895,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 +915,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] += (Math.random() - 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] + (Math.random() - 0.5) * 0.3 * ds, 1, 8);
                 ctx.globalAlpha = 0.7;
                 ctx.fillStyle = palette[pcol[i]];
                 ctx.save();
@@ -955,20 +968,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(sx, sy, sr * 2, 0, Math.PI * 2);
+                    ctx.fill();
+                    ctx.fillStyle = '#ffffff';
+                    ctx.globalAlpha = 1;
                     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, 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';
             }
 
@@ -1151,9 +1170,11 @@ export function NeonPulseRecipe({duration = 800, colors, theme} = {}) {
 // ===========================================================================
 
 export function PeelRecipe({duration = 1000} = {}) {
+    let peelW = 0;
     return {
         count: 0,
-        init() {
+        init(ctx, capacity, w) {
+            peelW = w > 0 ? w : 0;
         },
         spawn() {
             return {x: 0, y: 0, vx: 0, vy: 0, life: 0};
@@ -1162,7 +1183,7 @@ export function PeelRecipe({duration = 1000} = {}) {
             const raw = clamp(elapsed / duration, 0, 1);
             const t = easeIn(raw);
             src.style.transformOrigin = 'right center';
-            src.style.transform = `perspective(800px) rotateY(${t * 90}deg) rotateX(${t * -20}deg) translateX(${t * src.offsetWidth}px)`;
+            src.style.transform = `perspective(800px) rotateY(${t * 90}deg) rotateX(${t * -20}deg) translateX(${t * peelW}px)`;
             src.style.opacity = 1 - t;
             if (raw >= 1) {
                 src.style.transform = '';

package/src/ScratchStage.js

@@ -37,17 +37,37 @@ 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;
     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;
+        }
     });
 
     /**
@@ -120,6 +140,10 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
             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;
@@ -171,7 +195,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. */
@@ -224,6 +251,7 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
             if (destroyed) return;
             destroyed = true;
             active.clear();
+            pending.clear();
             engine.destroy();
         },