@zakkster/lite-scratch-fx 1.0.0 → 1.3.0

package/src/ScratchStage.js

@@ -0,0 +1,235 @@
+/**
+ * ScratchStage -- concurrent scratch-card reveals over ONE shared particle pool.
+ *
+ * A stage owns a single raw SoaParticleEngine and hands each controller a fixed,
+ * contiguous sub-range of its lanes. Any number of controllers can reveal at the same
+ * time, all rendering from one pool, driven by one clock -- so a grid of scratch boxes
+ * holds one lane pool instead of one per box.
+ *
+ * See decisions/0001-concurrent-shared-reveals.md for why this needs no engine change:
+ * raw-mode tick(dt) is pure dispatch (no physics, no culling), the lanes are public typed
+ * arrays the recipes already write, and each controller owns disjoint slots.
+ *
+ *   const stage = createScratchStage({ maxParticles: 1500, seed: 1 });
+ *   const boxes = cards.map((c) => stage.createController(c.scratch, c.fx, { capacity: 200 }));
+ *   // one clock drives the grid; many boxes reveal at once, one pool:
+ *   function frame(now) { const dt = (now - last) / 1000; last = now; stage.tick(dt);
+ *                         requestAnimationFrame(frame); }
+ *
+ * Copyright (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
+ * MIT License.
+ */
+
+import { SoaParticleEngine } from '@zakkster/lite-soa-particle-engine';
+import { Random }            from '@zakkster/lite-random';
+import { createPixelScanner } from './PixelScan.js';
+import { captureHostStyle, restoreHostStyle } from './HostStyle.js';
+
+/**
+ * @param {Object} [options]
+ * @param {number} [options.maxParticles=2000]  Total shared pool capacity.
+ * @param {number} [options.seed=Date.now()]     Base seed; each controller derives its own.
+ * @param {number} [options.dpr=1]               Default device-pixel-ratio for controllers.
+ */
+export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr: stageDpr = 1 } = {}) {
+    if (!(typeof stageDpr === 'number' && Number.isFinite(stageDpr) && stageDpr > 0)) {
+        throw new TypeError('createScratchStage: dpr must be a positive finite number');
+    }
+    const engine = new SoaParticleEngine(maxParticles);
+    const active = new Set();
+    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.
+    engine.onTick((dt) => {
+        if (destroyed || active.size === 0) return;
+        for (const c of active) c._frame(dt);
+    });
+
+    /**
+     * Reserve a sub-range and return a stage-managed controller. The stage drives it; the
+     * controller has no tick() of its own.
+     * @param {HTMLCanvasElement} sourceCanvas
+     * @param {HTMLCanvasElement} effectCanvas
+     * @param {Object} [opts]
+     * @param {number} [opts.capacity=300]      Slots reserved for this controller's particles.
+     * @param {number} [opts.seed]              RNG seed; defaults to base seed + index.
+     * @param {number} [opts.scanPrecision=32]  Pixel-scan resolution.
+     * @param {number} [opts.dpr]               Per-controller device-pixel-ratio (default: stage dpr).
+     */
+    function createController(sourceCanvas, effectCanvas, { capacity = 300, seed: cSeed, scanPrecision = 32, dpr = stageDpr } = {}) {
+        if (destroyed) throw new Error('createScratchStage: stage is destroyed');
+        if (!(Number.isInteger(capacity) && capacity >= 0)) {
+            throw new TypeError('createController: capacity must be a non-negative integer');
+        }
+        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}`,
+            );
+        }
+        const start = nextStart;
+        nextStart += capacity;
+        const index = controllerCount++;
+
+        const ctx = effectCanvas.getContext('2d');
+        const rng = new Random(cSeed ?? (seed + index));
+        const scanner = createPixelScanner(sourceCanvas);
+
+        // Stable subarray views of this controller's sub-range, built ONCE (the engine's
+        // lanes are fixed for its life). Reused every frame -> zero per-frame allocation.
+        const end = start + capacity;
+        const pView = {
+            x: engine.x.subarray(start, end),
+            y: engine.y.subarray(start, end),
+            vx: engine.vx.subarray(start, end),
+            vy: engine.vy.subarray(start, end),
+            life: engine.life.subarray(start, end),
+            invLife: engine.invLife.subarray(start, end),
+            data: engine.data.subarray(start, end),
+            max: 0,
+        };
+        const spot = { x: 0.5, y: 0.5 };
+
+        let activeRecipe = null;
+        let onComplete = null;
+        let elapsed = 0;
+        // Logical (CSS-pixel) reveal size. Recipes author and draw in these; the device-px
+        // effect canvas is dpr x larger and the 2D transform maps logical -> device. Every
+        // read of cw/ch (the _frame clearRect, recipe init/spawn/tick, endReveal clearRect)
+        // wants logical, so cw/ch are logical throughout.
+        let cw = 0, ch = 0;
+        let ctlDestroyed = false;
+        // Host layer inline style at reveal START -- one small object per reveal (cold
+        // path), restored on every terminal transition (completion/cancel/destroy).
+        let hostSnapshot = null;
+
+        // 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).
+        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);
+            const done = onComplete;
+            activeRecipe = null;
+            onComplete = null;
+            if (fireDone && done) done();
+        }
+
+        const controller = {
+            /** Reveal a recipe. Ignored if this controller is already revealing or destroyed. */
+            reveal(recipe, onDone) {
+                if (ctlDestroyed || activeRecipe) return;
+                activeRecipe = recipe;
+                onComplete = onDone || null;
+                elapsed = 0;
+
+                cw = sourceCanvas.offsetWidth || sourceCanvas.width;
+                ch = sourceCanvas.offsetHeight || sourceCanvas.height;
+                // Device-pixel backing store: dpr x larger for sharp high-DPI output.
+                // Assigning width/height resets the 2D transform, so map logical -> device
+                // with setTransform. At dpr === 1 skip it for byte-identical behaviour.
+                effectCanvas.width = Math.round(cw * dpr);
+                effectCanvas.height = Math.round(ch * dpr);
+                if (dpr !== 1) ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+
+                // Borrow the host layer's inline style; endReveal restores it pristine.
+                hostSnapshot = captureHostStyle(sourceCanvas);
+
+                const spots = scanner.scan(scanPrecision);
+                recipe.init(ctx, capacity, cw, ch);
+
+                const requested = recipe.count ?? capacity;
+                const count = Math.min(requested, capacity);
+                for (let i = 0; i < count; i++) {
+                    if (spots.count > 0) {
+                        const k = rng.int(0, spots.count - 1);
+                        spot.x = spots.spotX[k];
+                        spot.y = spots.spotY[k];
+                    } else {
+                        spot.x = 0.5;
+                        spot.y = 0.5;
+                    }
+                    const state = recipe.spawn(i, rng, cw, ch, spot);
+                    const g = start + i;
+                    engine.x[g] = state.x;
+                    engine.y[g] = state.y;
+                    engine.vx[g] = state.vx;
+                    engine.vy[g] = state.vy;
+                    engine.life[g] = state.life;
+                    engine.invLife[g] = 1.0 / state.life;
+                    engine.data[g] = i;   // local index -> the recipe reads data[i] === i in its window
+                }
+                pView.max = count;
+                active.add(controller);
+            },
+
+            /** @internal Called by the stage each frame. */
+            _frame(dt) {
+                if (ctlDestroyed || !activeRecipe) return;
+                elapsed += dt;
+                ctx.clearRect(0, 0, cw, ch);
+                const isFinished = activeRecipe.tick(dt, elapsed * 1000, pView, ctx, sourceCanvas, cw, ch);
+                if (isFinished) endReveal(true);
+            },
+
+            /**
+             * Abort this controller's in-flight reveal: stop the effect, restore the host
+             * canvas's inline style, and do NOT fire onDone; the controller is revealable
+             * again. A no-op when idle or destroyed. Does not reclaim the sub-range (B-8)
+             * and never touches other controllers' in-flight reveals.
+             */
+            cancel() {
+                if (ctlDestroyed || !activeRecipe) return;
+                endReveal(false);
+            },
+
+            /** Re-seed this controller's RNG. */
+            seed(s) { rng.reset(s); },
+
+            /** Remove this controller from the stage. Its sub-range is not reclaimed (v1). */
+            destroy() {
+                if (ctlDestroyed) return;
+                ctlDestroyed = true;
+                // Route any in-flight reveal through the single terminator (recipe teardown,
+                // host-style restore, active-set removal, no onDone) before scanner teardown.
+                endReveal(false);
+                scanner.destroy();
+            },
+        };
+        return controller;
+    }
+
+    return {
+        createController,
+
+        /** Advance every active reveal one frame. `dt` is in SECONDS. */
+        tick(dt) {
+            if (destroyed) return;
+            engine.tick(dt);
+        },
+
+        /** Stop everything and release the shared engine. Controllers become inert. */
+        destroy() {
+            if (destroyed) return;
+            destroyed = true;
+            active.clear();
+            engine.destroy();
+        },
+
+        /** @internal How many slots are still unreserved (for tests / diagnostics). */
+        get remainingCapacity() { return maxParticles - nextStart; },
+    };
+}
+
+export default createScratchStage;