@zakkster/lite-scratch-fx 1.2.0 → 1.3.0

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @zakkster/lite-scratch-fx — type declarations.
+ * @zakkster/lite-scratch-fx -- type declarations.
  */
 
 /** The package version. Kept in sync with package.json and CHANGELOG. */
@@ -40,7 +40,7 @@ export interface SpawnState {
 
 /**
  * A normalized spawn point (0..1 in each axis) taken from the scratch layer.
- * NOTE: this object is shared and reused across every `spawn` call in a reveal —
+ * NOTE: this object is shared and reused across every `spawn` call in a reveal --
  * read `x`/`y` synchronously and never retain the reference.
  */
 export interface SpawnSpot {
@@ -102,6 +102,11 @@ export interface ScratchControllerOptions {
      * at a time; `destroy()` will not tear a shared engine down.
      */
     engine?: SoaParticleEngine;
+    /**
+     * Device-pixel-ratio for sharp rendering on high-DPI screens. Default 1. Pass
+     * window.devicePixelRatio. Recipes still author in CSS pixels.
+     */
+    dpr?: number;
 }
 
 export interface ScratchController {
@@ -117,6 +122,12 @@ export interface ScratchController {
     tick(dt: number): void;
     /** Re-seed the RNG. */
     seed(s: number): void;
+    /**
+     * Abort an in-flight reveal: stop the effect and restore the host canvas's inline
+     * style to what it was at reveal start. Does NOT fire `onDone`; the controller is
+     * revealable again afterwards. A no-op when idle or destroyed.
+     */
+    cancel(): void;
     /** Stop, clean up the active recipe, and release the engine (owned engines only). */
     destroy(): void;
 }
@@ -132,13 +143,18 @@ export function createScratchController(
 
 export { createScratchController as ScratchController };
 
-// ── Concurrent reveals over one shared pool (createScratchStage) ──
+// -- Concurrent reveals over one shared pool (createScratchStage) --
 
 export interface ScratchStageOptions {
     /** Total shared pool capacity, split across controllers. Default 2000. */
     maxParticles?: number;
     /** Base seed; each controller derives its own (base + index) unless it passes one. */
     seed?: number;
+    /**
+     * Device-pixel-ratio for sharp rendering on high-DPI screens. Default 1. Pass
+     * window.devicePixelRatio. Recipes still author in CSS pixels.
+     */
+    dpr?: number;
 }
 
 export interface StageControllerOptions {
@@ -148,6 +164,11 @@ export interface StageControllerOptions {
     seed?: number;
     /** Horizontal resolution of the spawn-point pixel scan. Default 32. */
     scanPrecision?: number;
+    /**
+     * Device-pixel-ratio for sharp rendering on high-DPI screens. Default 1 (the stage
+     * dpr). Pass window.devicePixelRatio. Recipes still author in CSS pixels.
+     */
+    dpr?: number;
 }
 
 /** A stage-managed controller. The stage drives it, so it has no `tick` of its own. */
@@ -156,6 +177,12 @@ export interface StageController {
     reveal(recipe: Recipe, onDone?: () => void): void;
     /** Re-seed this controller's RNG. */
     seed(s: number): void;
+    /**
+     * Abort this controller's in-flight reveal: stop the effect and restore the host
+     * canvas's inline style. Does NOT fire `onDone`; the controller is revealable again.
+     * 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). */
     destroy(): void;
 }
@@ -182,7 +209,7 @@ export interface ScratchStage {
 /** Create a stage for concurrent reveals over one shared particle pool. */
 export function createScratchStage(options?: ScratchStageOptions): ScratchStage;
 
-// ── Recipe factories. Each returns a Recipe; all options are optional. ──
+// -- Recipe factories. Each returns a Recipe; all options are optional. --
 
 export interface RecipeOptions {
     count?: 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.2.0';
+export const VERSION = '1.3.0';
 
 export { createScratchController } from './src/ScratchController.js';
 export { default as ScratchController } from './src/ScratchController.js';
@@ -37,7 +37,7 @@ import {
     PeelRecipe, FadeRecipe, ImplosionRecipe,
 } from './src/ScratchRecipes.js';
 
-// ── Recipe registry (extensible: registerRecipe adds to it) ──
+// -- Recipe registry (extensible: registerRecipe adds to it) --
 // Keyed by short name, for data-driven pickers (demo dropdowns, random selection,
 // config files). A null-prototype object so keys never collide with Object.prototype.
 export const RECIPES = Object.assign(Object.create(null), {

package/llms.txt

@@ -8,8 +8,8 @@
 ## Core model
 
 createScratchController(sourceCanvas, effectCanvas,
-    { maxParticles = 2000, seed = Date.now(), scanPrecision = 32, driven = false, engine })
-  -> { reveal(recipe, onDone?), tick(dt), seed(s), destroy() }
+    { maxParticles = 2000, seed = Date.now(), scanPrecision = 32, driven = false, engine, dpr = 1 })
+  -> { reveal(recipe, onDone?), tick(dt), cancel(), seed(s), destroy() }
 
 sourceCanvas = the scratch layer (what the user scratches off).
 effectCanvas = an overlay canvas the particles render onto.
@@ -76,7 +76,7 @@ All 21 live in src/ScratchRecipes.js, grouped by family with section banners:
 ## Registry, metadata, extension
 
 VERSION: the package version string (kept in sync with package.json and CHANGELOG).
-RECIPES: an extensible null-prototype registry keyed by short name (burn, shatter, …).
+RECIPES: an extensible null-prototype registry keyed by short name (burn, shatter, ...).
 RECIPE_NAMES: the built-in keys at load time.
 RECIPE_META: a live array of { id, name, category, themeable, needsUntaintedCanvas } for every
   recipe -- the source for building pickers without hardcoding. category is
@@ -105,10 +105,10 @@ modes exist now:
 
 ## Concurrent reveals over one pool: createScratchStage
 
-createScratchStage({ maxParticles = 2000, seed = Date.now() })
-  -> { createController(src, fx, { capacity = 300, seed?, scanPrecision = 32 }) -> stageController,
+createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr = 1 })
+  -> { createController(src, fx, { capacity = 300, seed?, scanPrecision = 32, dpr? }) -> stageController,
        tick(dt), destroy(), get remainingCapacity }
-stageController -> { reveal(recipe, onDone?), seed(s), destroy() }   // NO tick -- the stage drives.
+stageController -> { reveal(recipe, onDone?), cancel(), seed(s), destroy() }   // NO tick -- the stage drives.
 
 When { engine } (one reveal at a time) is not enough and you need MANY boxes revealing at once
 over one pool: a stage owns one raw engine and gives each controller a fixed sub-range [start,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zakkster/lite-scratch-fx",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "version": "1.2.0",
+  "version": "1.3.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",
@@ -21,6 +21,7 @@
     "src/ScratchController.js",
     "src/ScratchRecipes.js",
     "src/ScratchStage.js",
+    "src/HostStyle.js",
     "src/PixelScan.js",
     "src/Palette.js",
     "README.md",

package/src/HostStyle.js

@@ -0,0 +1,42 @@
+/**
+ * HostStyle -- snapshot and restore the host layer's inline style across a reveal.
+ *
+ * lite-scratch-fx BORROWS the host scratch layer's inline style for the duration of a
+ * reveal (recipes write these 5 props during tick) and returns it to exactly what it
+ * found on every terminal transition -- completion, cancel, and destroy. The host owns
+ * the final revealed state via onDone; the library leaves no fingerprints.
+ *
+ * The snapshot is one small plain object per reveal. This is a COLD path -- capture at
+ * reveal start, restore at reveal end. Never call these per frame.
+ *
+ * See decisions/0002-host-style-and-cancel.md for the contract.
+ *
+ * Copyright (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
+ * MIT License.
+ */
+
+// The 5 inline style props the built-in recipes write during tick (particle/beam/css/
+// image families combined). Capturing every element's CURRENT inline value (usually '')
+// means restore returns the host to pristine regardless of what a custom recipe touched
+// among these props.
+export function captureHostStyle(el) {
+    if (!el || !el.style) return null;   // fail closed: nothing to borrow, nothing to restore
+    const s = el.style;
+    return {
+        opacity: s.opacity,
+        transform: s.transform,
+        filter: s.filter,
+        clipPath: s.clipPath,
+        transformOrigin: s.transformOrigin,
+    };
+}
+
+export function restoreHostStyle(el, snap) {
+    if (!el || !el.style || !snap) return;   // fail closed
+    const s = el.style;
+    s.opacity = snap.opacity;
+    s.transform = snap.transform;
+    s.filter = snap.filter;
+    s.clipPath = snap.clipPath;
+    s.transformOrigin = snap.transformOrigin;
+}

package/src/ScratchController.js

@@ -43,6 +43,7 @@
 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
@@ -58,6 +59,7 @@ const busySharedEngines = new WeakSet();
  * @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,
@@ -65,7 +67,11 @@ export function createScratchController(sourceCanvas, effectCanvas, {
     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 ownEngine = !externalEngine;
     const engine = externalEngine || new SoaParticleEngine(maxParticles);
@@ -75,6 +81,15 @@ export function createScratchController(sourceCanvas, effectCanvas, {
     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;
 
     // 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.
@@ -87,13 +102,11 @@ export function createScratchController(sourceCanvas, effectCanvas, {
     // 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) ──
+    // -- 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 };
@@ -104,19 +117,28 @@ 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) {
-            if (!driven) engine.stop();
-            releaseEngine();
-            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
@@ -153,15 +175,26 @@ export function createScratchController(sourceCanvas, effectCanvas, {
             }
             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.
             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
@@ -178,7 +211,7 @@ export function createScratchController(sourceCanvas, effectCanvas, {
                     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);
             }
 
@@ -199,17 +232,25 @@ export function createScratchController(sourceCanvas, effectCanvas, {
             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. */
         seed(s) { rng.reset(s); },
 
         destroy() {
             if (destroyed) return;
             destroyed = true;
-            if (!driven) engine.stop();
-            releaseEngine();
-            if (activeRecipe && activeRecipe.destroy) activeRecipe.destroy();
-            activeRecipe = null;
-            onComplete = null;
+            // 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();

package/src/ScratchRecipes.js

@@ -359,7 +359,7 @@ export function GoldDustRecipe({count = 150, duration = 2000, colors, theme} = {
                 ctx.fill();
             }
 
-            // ← FIX: Reset composite operation every frame
+            // <- FIX: Reset composite operation every frame
             ctx.globalCompositeOperation = 'source-over';
             ctx.globalAlpha = 1;
             return alive === 0 && elapsed >= duration;
@@ -372,7 +372,7 @@ export function GoldDustRecipe({count = 150, duration = 2000, colors, theme} = {
 
 
 export function ConfettiBlastRecipe({count = 80, duration = 1500, colors, theme} = {}) {
-    // ← FIX: Dedicated parallel arrays instead of repurposing size/decay
+    // <- FIX: Dedicated parallel arrays instead of repurposing size/decay
     let pWobblePhase, pWobbleSpeed, pColorIdx;
     const palette = resolvePalette(colors, theme, ['#ff0055', '#00ffcc', '#ffcc00', '#aa00ff', '#ff6600', '#00aaff']);
 
@@ -480,7 +480,7 @@ export function CosmicDustRecipe({count = 200, duration = 1800, colors, theme} =
                 ctx.fill();
             }
 
-            // ← FIX: Reset composite operation every frame
+            // <- FIX: Reset composite operation every frame
             ctx.globalCompositeOperation = 'source-over';
             ctx.globalAlpha = 1;
             return alive === 0 && elapsed >= duration;
@@ -522,7 +522,7 @@ export function MatrixDecayRecipe({count = 200, duration = 1500, colors, theme}
 
             // NOTE: No trail fillRect here. The ScratchController clears the canvas
             // every frame before calling tick(). Crisp falling text over the fading
-            // scratch layer is cleaner for a reveal effect — no persistent black box
+            // scratch layer is cleaner for a reveal effect -- no persistent black box
             // obscuring the prize underneath.
 
             ctx.font = '14px monospace';
@@ -598,7 +598,7 @@ export function LiquidMeltRecipe({count = 100, duration = 1200, colors, theme} =
 
                 ctx.globalAlpha = life[i];
                 ctx.fillStyle = palette[0];
-                // ← FIX: Use fillRect instead of roundRect for Safari < 17.4 compat
+                // <- FIX: Use fillRect instead of roundRect for Safari < 17.4 compat
                 ctx.fillRect(x[i] - sz / 2, pOriginY[p], sz, streakHeight);
                 // Rounded tip at bottom
                 ctx.beginPath();
@@ -685,7 +685,7 @@ export function ShatterRecipe({count = 30, duration = 1200, gravity = 0.5} = {})
 
 
 export function PixelShatterRecipe({count = 60, duration = 1200} = {}) {
-    let pRot, pRotSpd, pSz, pOrigX, pOrigY; // ← FIX: Store ORIGINAL positions
+    let pRot, pRotSpd, pSz, pOrigX, pOrigY; // <- FIX: Store ORIGINAL positions
     let img = null, imgReady = false;
 
     return {
@@ -702,7 +702,7 @@ export function PixelShatterRecipe({count = 60, duration = 1200} = {}) {
             pRot[idx] = rng.range(0, Math.PI);
             pRotSpd[idx] = rng.range(-0.3, 0.3);
             pSz[idx] = rng.range(5, 15);
-            pOrigX[idx] = sx; // ← FIX: Store spawn position for source crop
+            pOrigX[idx] = sx; // <- FIX: Store spawn position for source crop
             pOrigY[idx] = sy;
 
             const angle = rng.range(0, Math.PI * 2);
@@ -744,7 +744,7 @@ export function PixelShatterRecipe({count = 60, duration = 1200} = {}) {
                 ctx.globalAlpha = life[i];
                 ctx.translate(x[i], y[i]);
                 ctx.rotate(pRot[p]);
-                // ← FIX: Source crop uses ORIGINAL position, not current animated position
+                // <- FIX: Source crop uses ORIGINAL position, not current animated position
                 ctx.drawImage(img, pOrigX[p], pOrigY[p], sz, sz, -sz / 2, -sz / 2, sz, sz);
                 ctx.restore();
             }
@@ -862,7 +862,7 @@ export function ShineWaveRecipe({duration = 600, beamWidth = 80, particleCount =
     let py, pvy, pox, psz, pcol;
 
     return {
-        count: 0, // No SoA particles — managed internally
+        count: 0, // No SoA particles -- managed internally
         init(ctx, capacity, w, h) {
             py = new Float32Array(particleCount);
             pvy = new Float32Array(particleCount);
@@ -966,14 +966,14 @@ export function LaserScanRecipe({duration = 1000, colors, theme} = {}) {
                     ctx.fill();
                 }
 
-                // ← FIX: Reset shadow + composite every frame
+                // <- FIX: Reset shadow + composite every frame
                 ctx.shadowBlur = 0;
                 ctx.shadowColor = 'transparent';
                 ctx.globalCompositeOperation = 'source-over';
             }
 
             if (raw >= 1) {
-                // ← FIX: Clean up clipPath on completion
+                // <- FIX: Clean up clipPath on completion
                 src.style.clipPath = '';
                 return true;
             }
@@ -1110,7 +1110,7 @@ export function NeonPulseRecipe({duration = 800, colors, theme} = {}) {
             const cx = w / 2, cy = h / 2;
 
             src.style.opacity = 1 - t;
-            // ← FIX: Clamp scale to prevent overflow; clean up on completion
+            // <- FIX: Clamp scale to prevent overflow; clean up on completion
             src.style.transform = `scale(${1 + t * 0.3})`;
             src.style.transformOrigin = 'center';
 
@@ -1127,7 +1127,7 @@ export function NeonPulseRecipe({duration = 800, colors, theme} = {}) {
                 ctx.stroke();
             }
 
-            // ← FIX: Reset composite operation
+            // <- FIX: Reset composite operation
             ctx.globalCompositeOperation = 'source-over';
             ctx.globalAlpha = 1;
 

package/src/ScratchStage.js

@@ -23,13 +23,18 @@
 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() } = {}) {
+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;
@@ -54,12 +59,16 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now() } =
      * @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 } = {}) {
+    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}`,
@@ -91,8 +100,31 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now() } =
         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. */
@@ -102,8 +134,17 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now() } =
                 onComplete = onDone || null;
                 elapsed = 0;
 
-                cw = effectCanvas.width = sourceCanvas.offsetWidth || sourceCanvas.width;
-                ch = effectCanvas.height = sourceCanvas.offsetHeight || sourceCanvas.height;
+                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);
@@ -139,15 +180,18 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now() } =
                 elapsed += dt;
                 ctx.clearRect(0, 0, cw, ch);
                 const isFinished = activeRecipe.tick(dt, elapsed * 1000, pView, ctx, sourceCanvas, cw, ch);
-                if (isFinished) {
-                    if (activeRecipe.destroy) activeRecipe.destroy();
-                    activeRecipe = null;
-                    ctx.clearRect(0, 0, cw, ch);
-                    active.delete(controller);
-                    const done = onComplete;
-                    onComplete = null;
-                    if (done) done();
-                }
+                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. */
@@ -157,10 +201,9 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now() } =
             destroy() {
                 if (ctlDestroyed) return;
                 ctlDestroyed = true;
-                if (activeRecipe && activeRecipe.destroy) activeRecipe.destroy();
-                activeRecipe = null;
-                onComplete = null;
-                active.delete(controller);
+                // 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();
             },
         };