@zakkster/lite-scratch-fx 1.0.0 → 1.3.0

package/src/ScratchController.js

@@ -3,7 +3,20 @@
  *
  * Mounts a reveal recipe, scans the remaining visible pixels of the scratch layer for
  * spawn points, delegates physics + rendering to the recipe, and auto-cleans up on
- * completion. The particle engine owns its own requestAnimationFrame loop.
+ * completion.
+ *
+ * Driving model (three ways, all keep dt correct -- the double-drive that corrupts dt is
+ * never possible):
+ *   - DEFAULT: the controller owns a SoaParticleEngine and lets it self-drive via its own
+ *     requestAnimationFrame loop (start() on reveal, stop() on completion).
+ *   - HOST-DRIVEN (`{ driven: true }`): the controller never calls start(); the host runs
+ *     one clock (e.g. @zakkster/lite-ticker / lite-raf) and calls `controller.tick(dt)`
+ *     every frame with dt in SECONDS. One page loop drives N controllers.
+ *   - SHARED ENGINE (`{ engine }`): N controllers share one caller-supplied engine, so one
+ *     lane pool serves the whole page instead of one per controller. The engine has a
+ *     single render slot and one particle pool, so ONE reveal per shared engine at a time
+ *     -- a reveal attempted while another is active on the same engine is ignored. Pair
+ *     with `{ driven: true }` and drive the page from one clock.
  *
  * Recipe interface:
  *   {
@@ -29,97 +42,71 @@
 
 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';
+
+// Shared engines currently driving a reveal. A shared engine has one render slot and one
+// particle pool, so only one controller may reveal on it at a time; a second reveal is
+// ignored rather than clobbering the first. Owned engines never enter this set.
+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.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)
+ * @param {SoaParticleEngine} [options.engine]    Share a caller-supplied engine + lane pool
+ * @param {number} [options.dpr=1]                 Device-pixel-ratio for sharp high-DPI output
  */
 export function createScratchController(sourceCanvas, effectCanvas, {
     maxParticles = 2000,
     seed = Date.now(),
     scanPrecision = 32,
+    driven = false,
+    engine: externalEngine = null,
+    dpr = 1,
 } = {}) {
+    if (!(typeof dpr === 'number' && Number.isFinite(dpr) && dpr > 0)) {
+        throw new TypeError('createScratchController: dpr must be a positive finite number');
+    }
     const ctx = effectCanvas.getContext('2d');
-    const engine = new SoaParticleEngine(maxParticles);
+    const ownEngine = !externalEngine;
+    const engine = externalEngine || new SoaParticleEngine(maxParticles);
     const rng = new Random(seed);
-    // The SoA engine owns its own requestAnimationFrame loop: start() schedules it, stop()
-    // cancels it, and it computes dt internally. The controller must NOT also drive
-    // engine._loop from an external ticker -- that double-drives the loop and corrupts its
-    // dt, which breaks both particle life decay and completion detection. (An earlier
-    // version accepted a `sharedTicker` and did exactly that; it is removed.)
 
     let activeRecipe = null;
     let destroyed = false;
     let elapsed = 0;
     let onComplete = null;
+    // The host layer's inline style as it was at reveal START -- one small object per
+    // reveal (cold path), restored on every terminal transition so recipes leave no
+    // surviving inline opacity/transform/filter/clipPath/transformOrigin.
+    let hostSnapshot = null;
+    // Logical (CSS-pixel) reveal dimensions, cached at reveal start. Recipes author and
+    // draw in these; the device-pixel canvas is dpr x larger and the 2D transform maps
+    // logical -> device. Every per-frame clearRect and recipe call uses these, never the
+    // device-px effectCanvas.width/height.
+    let logicalW = 0, logicalH = 0;
 
-    // ── Reveal-scan scratch, all allocated ONCE (zero-GC on the reveal-start frame) ──
-    // The offscreen scan canvas, its context, and the spawn-point arrays are built here
-    // and reused across every reveal. Only getImageData() -- a single small typed array
-    // per reveal, mandated by the 2D canvas API -- is not reusable; the per-pixel object
-    // churn of the previous design (one `{x, y}` literal per surviving pixel) is gone.
-    let scanCanvas = null;
-    let scanCtx = null;
-    let scanW = 0, scanH = 0;
-    let spotX = new Float32Array(0);   // grown lazily if the source canvas is ever resized
-    let spotY = new Float32Array(0);
-    let spotCount = 0;
+    // The pixel scanner owns the offscreen scan canvas + spot arrays, all allocated once
+    // and reused across reveals -- zero per-pixel allocation on the reveal-start frame.
+    const scanner = createPixelScanner(sourceCanvas);
     const spot = { x: 0.5, y: 0.5 };   // the single shared, reused spawn point
 
-    function ensureScanBuffers(precision) {
-        const srcW = sourceCanvas.width || sourceCanvas.offsetWidth || 1;
-        const srcH = sourceCanvas.height || sourceCanvas.offsetHeight || 1;
-        const h = Math.max(1, Math.floor(srcH * (precision / srcW)));
-        if (scanCanvas && scanW === precision && scanH === h) return;
-        // Dims changed (or first run): (re)build. Off the hot path -- once per resize.
-        scanW = precision;
-        scanH = h;
-        if (!scanCanvas) {
-            scanCanvas = document.createElement('canvas');
-            scanCtx = scanCanvas.getContext('2d', { willReadFrequently: true });
-        }
-        scanCanvas.width = scanW;
-        scanCanvas.height = scanH;
-        const cap = scanW * scanH;
-        if (spotX.length < cap) {
-            spotX = new Float32Array(cap);
-            spotY = new Float32Array(cap);
-        }
-    }
-
-    // ── Scan remaining visible pixels from the scratch canvas into spotX/spotY ──
-    // Fills the preallocated arrays and sets spotCount. Allocates nothing per pixel.
-    function scanPixels(precision = scanPrecision) {
-        ensureScanBuffers(precision);
-        scanCtx.clearRect(0, 0, scanW, scanH);
-        scanCtx.drawImage(sourceCanvas, 0, 0, scanW, scanH);
-        const data = scanCtx.getImageData(0, 0, scanW, scanH).data;
-        let n = 0;
-        for (let i = 3; i < data.length; i += 4) {
-            if (data[i] > 128) {
-                const p = (i - 3) / 4;
-                spotX[n] = (p % scanW) / scanW;
-                spotY[n] = ((p / scanW) | 0) / scanH;
-                n++;
-            }
-        }
-        spotCount = n;
-    }
-
     // The particle-view object handed to recipe.tick every frame. Built ONCE and
     // reused: the engine's SoA arrays are stable references for the life of the engine,
     // so a fresh `{ x, y, ... }` literal per frame would be a pure zero-GC violation on
     // the hottest path in the package. Reassign the fields each frame (free) instead.
     let pView = null;
 
-    // ── Render callback (the engine calls this every frame with raw SoA arrays) ──
-    engine.onTick((dt, x, y, vx, vy, life, invLife, data, max) => {
+    // -- Render callback (the engine calls this every frame with raw SoA arrays) --
+    function renderTick(dt, x, y, vx, vy, life, invLife, data, max) {
         if (destroyed || !activeRecipe) return;
         elapsed += dt;
-        const w = effectCanvas.width;
-        const h = effectCanvas.height;
-        ctx.clearRect(0, 0, w, h);
+        ctx.clearRect(0, 0, logicalW, logicalH);
 
         if (pView === null) {
             pView = { x, y, vx, vy, life, invLife, data, max };
@@ -130,43 +117,84 @@ export function createScratchController(sourceCanvas, effectCanvas, {
 
         // Delegate everything to the recipe. Returns true when done.
         const isFinished = activeRecipe.tick(
-            dt, elapsed * 1000, pView, ctx, sourceCanvas, w, h,
+            dt, elapsed * 1000, pView, ctx, sourceCanvas, logicalW, logicalH,
         );
 
-        if (isFinished) {
-            engine.stop();
-            if (activeRecipe.destroy) activeRecipe.destroy();
-            activeRecipe = null;
-            ctx.clearRect(0, 0, w, h);
-            const done = onComplete;
-            onComplete = null;
-            if (done) done();
-        }
-    });
+        if (isFinished) endReveal(true);
+    }
+
+    // The single terminator for a reveal. Every terminal transition -- natural completion
+    // (fireDone=true), cancel() (false), and destroy() (false) -- routes through here, so
+    // the engine release, recipe teardown, host-style restore, and canvas clear happen in
+    // exactly one place and can never diverge. Cold path: called once per reveal, never
+    // per frame. onDone fires ONLY on natural completion (fireDone).
+    function endReveal(fireDone) {
+        if (!activeRecipe) return;
+        if (ownEngine && !driven) engine.stop();
+        releaseEngine();
+        if (activeRecipe.destroy) activeRecipe.destroy();
+        if (hostSnapshot) { restoreHostStyle(sourceCanvas, hostSnapshot); hostSnapshot = null; }
+        ctx.clearRect(0, 0, logicalW, logicalH);
+        const done = onComplete;
+        activeRecipe = null;
+        onComplete = null;
+        if (fireDone && done) done();
+    }
+
+    // Release our hold on a shared engine's single render slot so the next controller can
+    // reveal on it. A no-op for an owned engine, which stays bound for its whole life.
+    function releaseEngine() {
+        if (ownEngine) return;
+        engine.onTick(null);
+        busySharedEngines.delete(engine);
+    }
+
+    // An owned engine is bound once for its whole life; the renderTick early-returns when no
+    // reveal is active. A shared engine is bound per-reveal (in reveal) and released on
+    // completion so it can serve other controllers.
+    if (ownEngine) engine.onTick(renderTick);
 
     return {
         /**
-         * Execute a reveal recipe.
+         * Execute a reveal recipe. Ignored if this controller is already revealing, is
+         * destroyed, or shares an engine that another controller is revealing on.
          * @param {Object} recipe
          * @param {Function} [onDone]  Called when the effect completes
          */
         reveal(recipe, onDone) {
             if (destroyed || activeRecipe) return;
+            if (!ownEngine && busySharedEngines.has(engine)) return;
 
             activeRecipe = recipe;
             onComplete = onDone || null;
             elapsed = 0;
+
+            if (!ownEngine) {
+                engine.onTick(renderTick);
+                busySharedEngines.add(engine);
+            }
             engine.clear();
 
-            // Size the effect canvas to match the scratch layer
-            const w = effectCanvas.width = sourceCanvas.offsetWidth || sourceCanvas.width;
-            const h = effectCanvas.height = sourceCanvas.offsetHeight || sourceCanvas.height;
+            // Logical (CSS-pixel) size of the scratch layer -- recipes author in these.
+            logicalW = sourceCanvas.offsetWidth || sourceCanvas.width;
+            logicalH = sourceCanvas.offsetHeight || sourceCanvas.height;
+            // Device-pixel backing store: dpr x larger so output is sharp on high-DPI
+            // screens. Assigning width/height also resets the 2D transform, so map logical
+            // -> device with setTransform. At dpr === 1 skip it: behaviour is then
+            // byte-identical to the pre-DPR path (no setTransform call, no scaled dims).
+            effectCanvas.width = Math.round(logicalW * dpr);
+            effectCanvas.height = Math.round(logicalH * dpr);
+            if (dpr !== 1) ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+
+            // Borrow the host layer's inline style: snapshot it now (cold path, one small
+            // object) so endReveal can return it pristine on completion/cancel/destroy.
+            hostSnapshot = captureHostStyle(sourceCanvas);
 
-            // Scan spawn points from visible pixels (fills spotX/spotY, sets spotCount).
-            scanPixels();
+            // Scan spawn points from visible pixels.
+            const spots = scanner.scan(scanPrecision);
 
-            // Init recipe
-            recipe.init(ctx, maxParticles, w, h);
+            // Init recipe with LOGICAL size (recipes stay in CSS px).
+            recipe.init(ctx, maxParticles, 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
@@ -175,20 +203,43 @@ export function createScratchController(sourceCanvas, effectCanvas, {
             const count = Math.min(requested, maxParticles);
             for (let i = 0; i < count; i++) {
                 const idx = engine._head;
-                if (spotCount > 0) {
-                    const k = rng.int(0, spotCount - 1);
-                    spot.x = spotX[k];
-                    spot.y = spotY[k];
+                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(idx, rng, w, h, spot);
+                const state = recipe.spawn(idx, rng, logicalW, logicalH, spot);
                 engine.emit(state.x, state.y, state.vx, state.vy, state.life, idx);
             }
 
-            // The engine owns its RAF loop; start() schedules it and drives onTick.
-            engine.start();
+            // Self-driven: the engine's RAF loop drives renderTick. Host-driven: the host
+            // calls controller.tick(dt) instead; we schedule nothing.
+            if (!driven) engine.start();
+        },
+
+        /**
+         * Advance one frame in host-driven mode. `dt` is in SECONDS. A no-op unless the
+         * controller was created with `{ driven: true }` AND a reveal is active -- so a host
+         * can safely call tick() on every controller each frame; only the revealing one (and,
+         * for a shared engine, only the single active controller) does work.
+         * @param {number} dt  Seconds since the previous frame.
+         */
+        tick(dt) {
+            if (destroyed || !driven || activeRecipe === null) return;
+            engine.tick(dt);
+        },
+
+        /**
+         * Abort an in-flight reveal. Stops the effect, restores the host canvas's inline
+         * style to exactly what it was at reveal start, and does NOT fire onDone. The
+         * controller is revealable again afterwards. A no-op when idle or destroyed.
+         */
+        cancel() {
+            if (destroyed || !activeRecipe) return;
+            endReveal(false);
         },
 
         /** Re-seed the RNG. */
@@ -197,13 +248,12 @@ export function createScratchController(sourceCanvas, effectCanvas, {
         destroy() {
             if (destroyed) return;
             destroyed = true;
-            engine.stop();
-            if (activeRecipe && activeRecipe.destroy) activeRecipe.destroy();
-            activeRecipe = null;
-            onComplete = null;
-            scanCanvas = null;
-            scanCtx = null;
-            engine.destroy();
+            // Route any in-flight reveal through the single terminator (stops/releases the
+            // engine, restores host style, no onDone) before the controller's own teardown.
+            endReveal(false);
+            scanner.destroy();
+            // Only tear down an engine we created. A caller-supplied engine is theirs.
+            if (ownEngine) engine.destroy();
         },
     };
 }