@zakkster/lite-scratch-fx 1.4.0 → 1.5.1

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## [1.5.1] - 2026-08-23
+
+Cover-fade fidelity patch for `iceBreath`. Backward compatible; no API change.
+
+### Fixed
+- **`iceBreath` brightness ramp is now eased, matching the game's tween (B-21).** The
+  `brightness()` filter followed a linear `1 + fadeT` while the opacity one line above
+  followed the cubic `1 - fadeT^3`. GSAP applies a tween's ease to its numeric filter
+  target too, so both should share the cubic `power2.in` curve. The tick now computes
+  `ez = easeIn(fadeT)` once and drives opacity as `1 - ez` and brightness as `1 + ez`;
+  binding both writes to the same value removes the drift that caused the bug. Observable
+  change: at the fade midpoint brightness is `1.125`, not `1.5` (the cover no longer blows
+  out to near-white by mid-reveal). No allocation added; the torture gate is unchanged.
+
+### Changed
+- **Docs: `iceBreath`/`dragonBreath` `spread` is a jet half-angle (B-22).** The catalog
+  card now states `spread` is a half-angle in radians, matching `README.md` and `llms.txt`.
+  `IceBreathRecipe({ spread: FX_CONFIG.iceBreath.spread })` doubles the cone; pass
+  `spread / 2`. No code change.
+
+## [1.5.0] - 2026-08-23
+
+Cover-fade fidelity, live image reveals, and additive recipe/stage knobs. Backward
+compatible: every new recipe option and the new stage method is additive, and calling
+with no options reproduces prior output byte-identically.
+
+### Added
+- **`stage.remainingCapacityFor(capacity)` (B-19).** Returns the exact particle-slots
+  allocatable for a request of that capacity: `(maxParticles - nextStart) + n * capacity`,
+  where `n` is the count of reclaimed ranges of that exact capacity. A size-`C`
+  `createController` succeeds iff `remainingCapacityFor(C) >= C`. Zero-allocation; throws
+  `TypeError` on a non-integer or negative argument. `remainingCapacity` is unchanged (total
+  free slots); its JSDoc now states reclaimed ranges are reusable only on an exact-capacity
+  match, so `remainingCapacityFor` is the number to consult for an allocation decision.
+- **Additive recipe factory options.** `dissolve` gains `fadeSpeed` (cover-fade window as a
+  fraction of `duration`, default `0.3`); `dragonBreath` and `iceBreath` gain `spread`,
+  `speedMin`, `speedMax` (spawn cone half-angle in radians and speed range; defaults `0.3`/
+  `12`/`25` and `0.225`/`15`/`28`); `peel` and `shineWave` gain `ease` (a `t -> t` easing
+  function, default `easeIn`/`easeInOut`). A non-function `ease` falls back to the default.
+  Every default equals the previous literal, so existing callers are unaffected, and each
+  numeric knob is a single `rng` draw in the same position (determinism preserved).
+
+### Changed
+- **Image recipes draw the scratch layer live (R5).** `shatter`, `pixelShatter`, and
+  `glitchReveal` now draw the source canvas each frame with `drawImage(src, ...)` instead of
+  snapshotting it once via `toDataURL()` + `Image`. This removes the synchronous PNG encode,
+  the async decode, and the blank first frames: they render on frame 1 and work on any
+  canvas, including cross-origin/tainted layers. `RECIPE_META[*].needsUntaintedCanvas` is now
+  `false` for every built-in; the field is retained so a third-party recipe that reads the
+  canvas back (`getImageData`/`toDataURL`) can still advertise a same-origin requirement.
+- **`iceBreath` and `dragonBreath` cover fades match the consuming renderer.** `iceBreath`
+  fades with `power2.in` (cubic, `1 - easeIn`) over 0.5 s after a 0.1 s delay; `dragonBreath`
+  fades with `power1.in` (quadratic) over 0.4 s after a 0.1 s delay. Both were previously
+  linear with no delay.
+
+### Fixed
+- **Burn cover fade restored to cubic (B-18).** 1.4.0 shipped a quadratic fade (`1 - t*t`).
+  The consuming renderer tweens the burn cover with `power2.in`, which is cubic in GSAP's
+  naming (`Power2 = Cubic`; verified `parseEase('power2.in')(0.5) === 0.125`), so the correct
+  curve is `1 - easeIn(progress)` (`easeIn = t*t*t`). Reverted to cubic: at `progress` 0.5 the
+  cover opacity is `0.875`, not `0.75`.
+
+### Removed
+- The `toDataURL()` snapshot and `Image` decode from `shatter`, `pixelShatter`, and
+  `glitchReveal` (replaced by live `drawImage(src, ...)`).
+
 ## [1.4.0] - 2026-08-23
 
 Determinism, recipe tuning, and stage lane reclaim. One backward-compatible interface
@@ -22,8 +88,8 @@ addition -- a 5th `rng` argument to `recipe.init`; recipes that ignore it are un
 ### 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.
+  additive gravity term `vy += 0.1 * ds` is removed and the cover fade is quadratic (`1 - t*t`)
+  instead of the cubic `easeIn`. (The quadratic fade was a regression -- see 1.5.0 B-18.)
 - **`iceBreath` default `count` 300 -> 450 (B-16).**
 
 ### Removed

package/README.md

@@ -234,6 +234,8 @@ stage.createController(sourceCanvas, effectCanvas, options?): StageController
 stage.tick(dt): void                  // advance every active reveal one frame; dt in SECONDS
 stage.destroy(): void                 // stop everything and release the shared engine
 stage.remainingCapacity              // slots still unreserved in the shared pool (read-only)
+stage.remainingCapacityFor(capacity) // exact slots allocatable for a request of this size:
+                                     // a size-C createController succeeds iff this returns >= C
 ```
 
 `createController` options: `capacity` (slots reserved out of the pool, default `300` --
@@ -257,11 +259,22 @@ resolvePalette(colors, theme, fallback): string[]
 - **`resolvePalette(colors, theme, fallback)`** -- resolve a colour ramp for a themeable
   recipe: `colors` wins, then `theme`, then the recipe's own `fallback`.
 
+Several recipes take extra tuning knobs alongside `count`/`duration`; all default to the
+current built-in look:
+
+- **`DissolveRecipe`** -- `fadeSpeed` (default `0.3`): fraction of `duration` over which the
+  source layer fades out.
+- **`DragonBreathRecipe`** / **`IceBreathRecipe`** -- `spread` (jet half-angle in radians,
+  defaults `0.3` / `0.225`), `speedMin`/`speedMax` (spawn speed range, defaults `12`-`25`
+  / `15`-`28`).
+- **`PeelRecipe`** / **`ShineWaveRecipe`** -- `ease` (`(t: number) => number`): the easing
+  applied to progress; defaults to the recipe's built-in curve (`easeIn` / `easeInOut`).
+
 ### Constants
 
 | Constant                  | Value                                                        | Meaning                                              |
 | ------------------------- | ----------------------------------------------------------- | ---------------------------------------------------- |
-| `VERSION`                 | `'1.4.0'`                                                    | Package version string (synced to package.json).     |
+| `VERSION`                 | `'1.5.1'`                                                    | 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.     |
@@ -271,9 +284,11 @@ resolvePalette(colors, theme, fallback): string[]
 
 `RECIPES` is an extensible null-prototype registry keyed by short name;
 `RECIPE_NAMES` is its keys at load time; `RECIPE_META` is a live array
-(`registerRecipe` keeps it in sync). `needsUntaintedCanvas` is `true` only for the 3
-image recipes, which snapshot the layer via `toDataURL()` and therefore need a same-origin
-canvas.
+(`registerRecipe` keeps it in sync). Image recipes draw the source canvas live each
+frame via `drawImage(src)`, so they work on cross-origin/tainted layers;
+`needsUntaintedCanvas` is retained in `RECIPE_META` (all built-ins `false`) for a
+third-party recipe that reads the canvas back (`getImageData`/`toDataURL`) and needs to
+advertise a same-origin requirement to pickers.
 
 ---
 
@@ -328,6 +343,8 @@ The erase is plain canvas `destination-out` -- this library never touches your i
 stage holds **one** lane pool for the whole grid, hands each card a fixed 200-slot
 sub-range, and the single `stage.tick(dt)` fans out to every card that is mid-reveal. Add
 a recipe with `registerRecipe` and the `RECIPE_META` picker above serves it with no edit.
+A recipe instance holds per-reveal state, so build a fresh one per reveal (as `RECIPES[pick()]()`
+does above) rather than sharing a single instance across cards or reveals.
 
 ---
 
@@ -387,9 +404,11 @@ gate rejects its deliberately-broken variant.
   `{ colors, theme }`; `colors` wins, `theme` maps a `{ light, mid, dark }` triple onto the
   ramp, and omitting both keeps the recipe's own default. A skin threads one triple through
   the whole grid.
-- **Image recipes need an untainted canvas.** `shatter`, `pixelShatter`, and
-  `glitchReveal` snapshot the layer via `toDataURL()` and an `Image`, so the scratch layer
-  must be same-origin. `RECIPE_META[n].needsUntaintedCanvas` flags them for a picker.
+- **Image recipes draw the source canvas live.** `shatter`, `pixelShatter`, and
+  `glitchReveal` draw the scratch layer each frame via `drawImage(src)` -- no snapshot --
+  so they work on cross-origin/tainted layers. `needsUntaintedCanvas` is retained in
+  `RECIPE_META` (all built-ins `false`) for a third-party recipe that reads the canvas back
+  (`getImageData`/`toDataURL`) and must advertise a same-origin requirement to a picker.
 
 ---
 

package/index.d.ts

@@ -208,6 +208,8 @@ export interface ScratchStage {
     destroy(): void;
     /** Slots still unreserved in the shared pool. */
     readonly remainingCapacity: number;
+    /** Exact particle-slots allocatable for a request of this capacity; a size-C createController succeeds iff this returns >= C. */
+    remainingCapacityFor(capacity: number): number;
 }
 
 /** Create a stage for concurrent reveals over one shared particle pool. */
@@ -231,14 +233,14 @@ export interface ThemeableRecipeOptions extends RecipeOptions {
 
 export function BurnRecipe(opts?: ThemeableRecipeOptions): Recipe;
 export function ShatterRecipe(opts?: RecipeOptions & { gravity?: number }): Recipe;
-export function DissolveRecipe(opts?: ThemeableRecipeOptions): Recipe;
+export function DissolveRecipe(opts?: ThemeableRecipeOptions & { fadeSpeed?: number }): Recipe;
 export function ExplodeRecipe(opts?: ThemeableRecipeOptions & { force?: number }): Recipe;
-export function DragonBreathRecipe(opts?: ThemeableRecipeOptions): Recipe;
-export function IceBreathRecipe(opts?: ThemeableRecipeOptions): Recipe;
-export function ShineWaveRecipe(opts?: ThemeableRecipeOptions & { beamWidth?: number; particleCount?: number }): Recipe;
+export function DragonBreathRecipe(opts?: ThemeableRecipeOptions & { spread?: number; speedMin?: number; speedMax?: number }): Recipe;
+export function IceBreathRecipe(opts?: ThemeableRecipeOptions & { spread?: number; speedMin?: number; speedMax?: number }): Recipe;
+export function ShineWaveRecipe(opts?: ThemeableRecipeOptions & { beamWidth?: number; particleCount?: number; ease?: (t: number) => number }): Recipe;
 export function LightningCrawlRecipe(opts?: ThemeableRecipeOptions & { boltCount?: number }): Recipe;
 export function ShineRecipe(opts?: RecipeOptions & { width?: number }): Recipe;
-export function PeelRecipe(opts?: RecipeOptions): Recipe;
+export function PeelRecipe(opts?: RecipeOptions & { ease?: (t: number) => number }): Recipe;
 export function FadeRecipe(opts?: RecipeOptions): Recipe;
 export function ImplosionRecipe(opts?: RecipeOptions): Recipe;
 

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.4.0';
+export const VERSION = '1.5.1';
 
 export { createScratchController } from './src/ScratchController.js';
 export { default as ScratchController } from './src/ScratchController.js';
@@ -71,7 +71,11 @@ export const RECIPES = Object.assign(Object.create(null), {
  *
  *   category            'particle' | 'image' | 'beam' | 'css' | (custom)
  *   themeable           accepts { colors, theme }
- *   needsUntaintedCanvas snapshots the scratch layer via toDataURL() (same-origin only)
+ *   needsUntaintedCanvas all built-in recipes are false: image recipes draw the
+ *                        scratch layer live via drawImage(src), never reading it
+ *                        back. The flag is retained so a third-party recipe that
+ *                        does read the canvas (getImageData/toDataURL) can
+ *                        advertise a same-origin requirement to pickers.
  */
 export const RECIPE_META = [
     { id: 'burn', name: 'Burn', category: 'particle', themeable: true, needsUntaintedCanvas: false },
@@ -84,9 +88,9 @@ export const RECIPE_META = [
     { id: 'cosmicDust', name: 'Cosmic Dust', category: 'particle', themeable: true, needsUntaintedCanvas: false },
     { id: 'matrixDecay', name: 'Matrix Decay', category: 'particle', themeable: true, needsUntaintedCanvas: false },
     { id: 'liquidMelt', name: 'Liquid Melt', category: 'particle', themeable: true, needsUntaintedCanvas: false },
-    { id: 'shatter', name: 'Shatter', category: 'image', themeable: false, needsUntaintedCanvas: true },
-    { id: 'pixelShatter', name: 'Pixel Shatter', category: 'image', themeable: false, needsUntaintedCanvas: true },
-    { id: 'glitchReveal', name: 'Glitch Reveal', category: 'image', themeable: false, needsUntaintedCanvas: true },
+    { id: 'shatter', name: 'Shatter', category: 'image', themeable: false, needsUntaintedCanvas: false },
+    { id: 'pixelShatter', name: 'Pixel Shatter', category: 'image', themeable: false, needsUntaintedCanvas: false },
+    { id: 'glitchReveal', name: 'Glitch Reveal', category: 'image', themeable: false, needsUntaintedCanvas: false },
     { id: 'shine', name: 'Shine', category: 'beam', themeable: false, needsUntaintedCanvas: false },
     { id: 'shineWave', name: 'Shine Wave', category: 'beam', themeable: true, needsUntaintedCanvas: false },
     { id: 'laserScan', name: 'Laser Scan', category: 'beam', themeable: true, needsUntaintedCanvas: false },

package/llms.txt

@@ -69,10 +69,17 @@ locks this because it couples recipes to engine internals (_head).
 All 21 live in src/ScratchRecipes.js, grouped by family with section banners:
   particle (spawn from covered pixels, own physics): burn, dissolve, explode, dragonBreath,
     iceBreath, goldDust, confettiBlast, cosmicDust, matrixDecay, liquidMelt
-  image (snapshot layer via toDataURL()+Image; same-origin only): shatter, pixelShatter, glitchReveal
+  image (draw the layer live each frame via drawImage(src); works on any canvas, incl. cross-origin): shatter, pixelShatter, glitchReveal
   beam/canvas (draw light/lines on the overlay): shine, shineWave, laserScan, lightningCrawl, neonPulse
   css (drive the layer's own transform/opacity): peel, fade, implosion
 
+Every factory takes an options bag; all options default to the shipped tuning, so calling with
+no args reproduces the stock effect. Beyond { colors, theme } (the 14 themeable recipes) and
+count/duration, the FX_CONFIG-style knobs are: dissolve fadeSpeed (fade window as a fraction of
+duration); dragonBreath and iceBreath spread / speedMin / speedMax (spawn cone half-angle in
+radians and speed range); peel and shineWave ease (a t -> t easing function). A non-function ease
+falls back to the recipe's default curve.
+
 ## Registry, metadata, extension
 
 VERSION: the package version string (kept in sync with package.json and CHANGELOG).
@@ -80,8 +87,10 @@ RECIPES: an extensible null-prototype registry keyed by short name (burn, shatte
 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
-  'particle'|'image'|'beam'|'css'. needsUntaintedCanvas is true only for shatter/pixelShatter/
-  glitchReveal. themeable is true for the 14 recipes that take { colors, theme }.
+  'particle'|'image'|'beam'|'css'. needsUntaintedCanvas is false for every built-in (image recipes
+  draw the layer live via drawImage(src), never reading it back); the flag is retained so a
+  third-party recipe that reads the canvas (getImageData/toDataURL) can advertise a same-origin
+  requirement to pickers. themeable is true for the 14 recipes that take { colors, theme }.
 registerRecipe(id, factory, meta?): add a recipe or override a built-in; lands in RECIPES and
   RECIPE_META immediately so existing pickers keep working. Mirrors lite-ambient's registerTheme.
   Omitted meta fields fall back to the prior entry, then a de-camelCased name, category 'custom',
@@ -107,7 +116,7 @@ modes exist now:
 
 createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr = 1 })
   -> { createController(src, fx, { capacity = 300, seed?, scanPrecision = 32, dpr? }) -> stageController,
-       tick(dt), destroy(), get remainingCapacity }
+       tick(dt), destroy(), get remainingCapacity, remainingCapacityFor(capacity) }
 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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zakkster/lite-scratch-fx",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "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/ScratchRecipes.js

@@ -50,7 +50,7 @@ export function BurnRecipe({count = 100, duration = 200, colors, theme} = {}) {
             const ds = dt * 60;
             let alive = 0;
             const progress = clamp(elapsed / duration, 0, 1);
-            src.style.opacity = 1 - progress * progress;
+            src.style.opacity = 1 - easeIn(progress);
 
             for (let i = 0; i < max; i++) {
                 if (life[i] <= 0) continue;
@@ -83,7 +83,7 @@ export function BurnRecipe({count = 100, duration = 200, colors, theme} = {}) {
 }
 
 
-export function DissolveRecipe({count = 150, duration = 1000, colors, theme} = {}) {
+export function DissolveRecipe({count = 150, duration = 1000, fadeSpeed = 0.3, colors, theme} = {}) {
     let pSize;
     const palette = resolvePalette(colors, theme, ['#DC143C']);
 
@@ -99,7 +99,7 @@ export function DissolveRecipe({count = 150, duration = 1000, colors, theme} = {
         tick(dt, elapsed, engine, ctx, src, w, h) {
             const {x, y, vy, life, data, max} = engine;
             let alive = 0;
-            src.style.opacity = 1 - clamp(elapsed / (duration * 0.3), 0, 1);
+            src.style.opacity = 1 - clamp(elapsed / (duration * fadeSpeed), 0, 1);
 
             for (let i = 0; i < max; i++) {
                 if (life[i] <= 0) continue;
@@ -171,7 +171,7 @@ export function ExplodeRecipe({count = 80, duration = 750, force = 15, colors, t
 }
 
 
-export function DragonBreathRecipe({count = 200, duration = 1200, colors, theme} = {}) {
+export function DragonBreathRecipe({count = 200, duration = 1200, spread = 0.3, speedMin = 12, speedMax = 25, colors, theme} = {}) {
     let pSize, pDecay, pColorIdx, r;
     const palette = resolvePalette(colors, theme, ['#FFF', '#FFD700', '#FF4500', '#8B0000', '#2F2F2F']);
 
@@ -184,8 +184,8 @@ export function DragonBreathRecipe({count = 200, duration = 1200, colors, theme}
             pColorIdx = new Uint8Array(capacity);
         },
         spawn(idx, rng, w, h, spot) {
-            const angle = -Math.PI / 2 + rng.range(-0.3, 0.3);
-            const speed = rng.range(12, 25);
+            const angle = -Math.PI / 2 + rng.range(-spread, spread);
+            const speed = rng.range(speedMin, speedMax);
             pSize[idx] = rng.range(4, 12);
             pDecay[idx] = rng.range(0.01, 0.025);
             pColorIdx[idx] = rng.int(0, palette.length - 1);
@@ -203,7 +203,8 @@ export function DragonBreathRecipe({count = 200, duration = 1200, colors, theme}
             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);
+            const fadeT = clamp((elapsed - 100) / 400, 0, 1);
+            src.style.opacity = 1 - fadeT * fadeT;
 
             for (let i = 0; i < max; i++) {
                 if (life[i] <= 0) continue;
@@ -239,7 +240,7 @@ export function DragonBreathRecipe({count = 200, duration = 1200, colors, theme}
 }
 
 
-export function IceBreathRecipe({count = 450, duration = 1500, colors, theme} = {}) {
+export function IceBreathRecipe({count = 450, duration = 1500, spread = 0.225, speedMin = 15, speedMax = 28, colors, theme} = {}) {
     let pSize, pDecay, pRot, pRotSpd, pColorIdx;
     const palette = resolvePalette(colors, theme, ['#FFF', '#E0FFFF', '#00FFFF', '#1E90FF', '#4682B4']);
 
@@ -253,8 +254,8 @@ export function IceBreathRecipe({count = 450, duration = 1500, colors, theme} =
             pColorIdx = new Uint8Array(capacity);
         },
         spawn(idx, rng, w, h, spot) {
-            const angle = -Math.PI / 2 + rng.range(-0.225, 0.225);
-            const speed = rng.range(15, 28);
+            const angle = -Math.PI / 2 + rng.range(-spread, spread);
+            const speed = rng.range(speedMin, speedMax);
             pSize[idx] = rng.range(2, 7);
             pDecay[idx] = rng.range(0.005, 0.025);
             pRot[idx] = rng.range(0, Math.PI);
@@ -273,9 +274,10 @@ export function IceBreathRecipe({count = 450, duration = 1500, colors, theme} =
             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;
-            src.style.filter = `brightness(${1 + t})`;
+            const fadeT = clamp((elapsed - 100) / 500, 0, 1);
+            const ez = easeIn(fadeT);
+            src.style.opacity = 1 - ez;
+            src.style.filter = `brightness(${1 + ez})`;
 
             for (let i = 0; i < max; i++) {
                 if (life[i] <= 0) continue;
@@ -629,12 +631,12 @@ export function LiquidMeltRecipe({count = 100, duration = 1200, colors, theme} =
 // ===========================================================================
 //  IMAGE REVEALS
 // ===========================================================================
-//  Snapshot the scratch layer via toDataURL() + Image and animate the pixels. Same-origin only.
+//  Draw the scratch layer live each frame via drawImage(src); no snapshot, works on any canvas (incl. cross-origin).
 // ===========================================================================
 
 export function ShatterRecipe({count = 30, duration = 1200, gravity = 0.5} = {}) {
     let pRot, pRotSpd, pSz, pOpacity;
-    let img = null;
+    let hidden = false;
 
     return {
         count,
@@ -652,13 +654,7 @@ export function ShatterRecipe({count = 30, duration = 1200, gravity = 0.5} = {})
             return {x: spot.x * w, y: spot.y * h, vx: rng.range(-15, 15), vy: rng.range(-10, -2), life: 1.0};
         },
         tick(dt, elapsed, engine, ctx, src, w, h) {
-            // Lazy-capture source image on first frame
-            if (!img) {
-                img = new Image();
-                img.src = src.toDataURL();
-                src.style.opacity = '0';
-            }
-            if (!img.complete) return false;
+            if (!hidden) { src.style.opacity = '0'; hidden = true; }
 
             const {x, y, vx, vy, life, data, max} = engine;
             const ds = dt * 60;
@@ -682,14 +678,14 @@ export function ShatterRecipe({count = 30, duration = 1200, gravity = 0.5} = {})
                 ctx.globalAlpha = pOpacity[p];
                 ctx.translate(x[i], y[i]);
                 ctx.rotate(pRot[p]);
-                ctx.drawImage(img, -pSz[p] / 2, -pSz[p] / 2, pSz[p], pSz[p]);
+                ctx.drawImage(src, -pSz[p] / 2, -pSz[p] / 2, pSz[p], pSz[p]);
                 ctx.restore();
             }
             return alive === 0;
         },
         destroy() {
             pRot = pRotSpd = pSz = pOpacity = null;
-            img = null;
+            hidden = false;
         },
     };
 }
@@ -697,7 +693,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 img = null, imgReady = false;
+    let hidden = false;
 
     return {
         count,
@@ -721,16 +717,7 @@ export function PixelShatterRecipe({count = 60, duration = 1200} = {}) {
             return {x: sx, y: sy, vx: Math.cos(angle) * spd, vy: Math.sin(angle) * spd, life: 1.0};
         },
         tick(dt, elapsed, engine, ctx, src, w, h) {
-            if (!img) {
-                img = new Image();
-                img.onload = () => {
-                    imgReady = true;
-                };
-                img.src = src.toDataURL();
-                src.style.opacity = '0';
-                return false;
-            }
-            if (!imgReady) return false;
+            if (!hidden) { src.style.opacity = '0'; hidden = true; }
 
             const {x, y, vx, vy, life, data, max} = engine;
             const ds = dt * 60;
@@ -757,23 +744,21 @@ export function PixelShatterRecipe({count = 60, duration = 1200} = {}) {
                 ctx.translate(x[i], y[i]);
                 ctx.rotate(pRot[p]);
                 // <- 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.drawImage(src, pOrigX[p], pOrigY[p], sz, sz, -sz / 2, -sz / 2, sz, sz);
                 ctx.restore();
             }
             return alive === 0;
         },
         destroy() {
             pRot = pRotSpd = pSz = pOrigX = pOrigY = null;
-            img = null;
-            imgReady = false;
+            hidden = false;
         },
     };
 }
 
 
 export function GlitchRevealRecipe({duration = 800} = {}) {
-    let img = null;
-    let imgReady = false;
+    let hidden = false;
     let sliceSeeds = null; // Pre-generated random values for deterministic slicing
 
     return {
@@ -788,17 +773,7 @@ export function GlitchRevealRecipe({duration = 800} = {}) {
             return {x: 0, y: 0, vx: 0, vy: 0, life: 0};
         },
         tick(dt, elapsed, engine, ctx, src, w, h) {
-            // Lazy capture with onload guard
-            if (!img) {
-                img = new Image();
-                img.onload = () => {
-                    imgReady = true;
-                };
-                img.src = src.toDataURL();
-                src.style.opacity = '0';
-                return false;
-            }
-            if (!imgReady) return false;
+            if (!hidden) { src.style.opacity = '0'; hidden = true; }
 
             const raw = clamp(elapsed / duration, 0, 1);
 
@@ -817,9 +792,9 @@ export function GlitchRevealRecipe({duration = 800} = {}) {
 
                 // Red channel
                 ctx.globalCompositeOperation = 'screen';
-                ctx.drawImage(img, 0, sliceY, w, sliceH, offsetX - rgbShift, sliceY, w, sliceH);
+                ctx.drawImage(src, 0, sliceY, w, sliceH, offsetX - rgbShift, sliceY, w, sliceH);
                 // Cyan channel
-                ctx.drawImage(img, 0, sliceY, w, sliceH, offsetX + rgbShift, sliceY, w, sliceH);
+                ctx.drawImage(src, 0, sliceY, w, sliceH, offsetX + rgbShift, sliceY, w, sliceH);
             }
 
             ctx.globalCompositeOperation = 'source-over';
@@ -827,9 +802,8 @@ export function GlitchRevealRecipe({duration = 800} = {}) {
             return raw >= 1;
         },
         destroy() {
-            img = null;
-            imgReady = false;
             sliceSeeds = null;
+            hidden = false;
         },
     };
 }
@@ -869,8 +843,9 @@ export function ShineRecipe({duration = 500, width = 250} = {}) {
 }
 
 
-export function ShineWaveRecipe({duration = 600, beamWidth = 80, particleCount = 60, colors, theme} = {}) {
+export function ShineWaveRecipe({duration = 600, beamWidth = 80, particleCount = 60, ease = easeInOut, colors, theme} = {}) {
     const palette = resolvePalette(colors, theme, ['#FFF', '#E0E8FF', '#B0C4FF', '#88AAFF']);
+    const ez = typeof ease === 'function' ? ease : easeInOut;
     let py, pvy, pox, psz, pcol, r;
 
     return {
@@ -895,7 +870,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 t = ez(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;
@@ -1173,8 +1148,9 @@ export function NeonPulseRecipe({duration = 800, colors, theme} = {}) {
 //  Drive the scratch layer's own transform/opacity; little or no particle work.
 // ===========================================================================
 
-export function PeelRecipe({duration = 1000} = {}) {
+export function PeelRecipe({duration = 1000, ease = easeIn} = {}) {
     let peelW = 0;
+    const ez = typeof ease === 'function' ? ease : easeIn;
     return {
         count: 0,
         init(ctx, capacity, w) {
@@ -1185,7 +1161,7 @@ export function PeelRecipe({duration = 1000} = {}) {
         },
         tick(dt, elapsed, engine, ctx, src) {
             const raw = clamp(elapsed / duration, 0, 1);
-            const t = easeIn(raw);
+            const t = ez(raw);
             src.style.transformOrigin = 'right center';
             src.style.transform = `perspective(800px) rotateY(${t * 90}deg) rotateX(${t * -20}deg) translateX(${t * peelW}px)`;
             src.style.opacity = 1 - t;

package/src/ScratchStage.js

@@ -287,8 +287,27 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
             engine.destroy();
         },
 
-        /** @internal How many slots are still unreserved (for tests / diagnostics). */
+        /**
+         * @internal Total unreserved slots (fresh tail + reclaimed). Reclaimed slots are
+         * reusable only on an EXACT capacity match, so for an allocation decision use
+         * remainingCapacityFor(capacity).
+         */
         get remainingCapacity() { return maxParticles - nextStart + reclaimedCapacity; },
+
+        /**
+         * @internal Exact particle-slots allocatable for a request of this capacity; a
+         * size-C createController succeeds iff remainingCapacityFor(C) >= C.
+         */
+        remainingCapacityFor(capacity) {
+            if (!(Number.isInteger(capacity) && capacity >= 0)) {
+                throw new TypeError('remainingCapacityFor: capacity must be a non-negative integer');
+            }
+            let n = 0;
+            for (let i = 0; i < freeCap.length; i++) {
+                if (freeCap[i] === capacity) n++;
+            }
+            return (maxParticles - nextStart) + n * capacity;
+        },
     };
 }