@zakkster/lite-scratch-fx 1.3.2 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,81 @@
 # Changelog
 
+## [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
+addition -- a 5th `rng` argument to `recipe.init`; recipes that ignore it are unaffected.
+
+### Added
+- **Seeded RNG passed to `recipe.init` (B-14).** `recipe.init(ctx, capacity, w, h, rng)` now
+  receives the controller's or stage's seeded `Random` as an additive 5th argument.
+  `dragonBreath`, `shineWave`, and `lightningCrawl` drew from `Math.random()` in `init`/`tick`,
+  breaking reproducibility; they now draw from `rng`, so two reveals at the same seed produce
+  byte-identical lanes. Recipes with a shorter `init` signature ignore the argument.
+- **Stage sub-range reclaim (B-8).** `createScratchStage` keeps a free list of released lane
+  ranges; `controller.destroy()` returns its `[start, capacity)` range and `createController`
+  reuses an exact-capacity match before extending the pool, so a grid rebuilt after destroying
+  all controllers no longer throws `pool exhausted`. `remainingCapacity` counts the free list.
+  `cancel()` and completion do not reclaim -- the range stays reserved and the controller is
+  revealable. The per-frame tick path is byte-identical (the free list is touched only in
+  `createController`/`destroy`).
+
+### 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 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
+- `Math.random()` from `dragonBreath`, `shineWave`, and `lightningCrawl` (replaced by the
+  seeded `rng`).
+
 ## [1.3.2] - 2026-08-23
 
 Recipe-fidelity pass against the consuming renderer. No API or signature change; the

package/README.md

@@ -36,7 +36,7 @@ import { createScratchController, BurnRecipe } from '@zakkster/lite-scratch-fx';
 const fx = createScratchController(scratchCanvas, fxCanvas, { seed: 42 });
 
 revealButton.onclick = () => {
-    fx.reveal(BurnRecipe({ duration: 1500 }), () => {
+    fx.reveal(BurnRecipe(), () => {
         console.log('prize revealed');
     });
 };
@@ -131,7 +131,7 @@ function MyRecipe({ count = 120, duration = 1000 } = {}) {
     let size;
     return {
         count,                                   // 0 = pure-canvas reveal, no particles
-        init(ctx, capacity, w, h) {              // allocate parallel per-particle arrays
+        init(ctx, capacity, w, h, rng) {         // allocate arrays; rng = seeded Random (same one passed to spawn), use instead of Math.random for reproducible reveals
             size = new Float32Array(capacity);
         },
         spawn(idx, rng, w, h, spot) {            // one particle; spot is 0..1 on the layer
@@ -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.3.2'`                                                    | Package version string (synced to package.json).     |
+| `VERSION`                 | `'1.5.0'`                                                    | 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

@@ -69,7 +69,8 @@ export interface RecipeRng {
 export interface Recipe {
     /** Particles to spawn. `0` means a pure-canvas reveal with no particles. */
     count: number;
-    init(ctx: CanvasRenderingContext2D, capacity: number, w: number, h: number): void;
+    /** `rng` is the controller/stage's seeded Random instance (same one passed to spawn); use it instead of Math.random for reproducible reveals. */
+    init(ctx: CanvasRenderingContext2D, capacity: number, w: number, h: number, rng: RecipeRng): void;
     spawn(idx: number, rng: RecipeRng, w: number, h: number, spot: SpawnSpot): SpawnState;
     /** Return `true` when the effect is complete. `elapsedMs` is milliseconds since reveal. */
     tick(
@@ -183,7 +184,10 @@ export interface StageController {
      * 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). */
+    /**
+     * Remove this controller from the stage. Its sub-range is reclaimed into the stage
+     * free-list for exact-capacity reuse by a later createController.
+     */
     destroy(): void;
 }
 
@@ -204,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. */
@@ -227,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.3.2';
+export const VERSION = '1.5.0';
 
 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

@@ -32,7 +32,7 @@ A second reveal while one is active is ignored.
 
 {
   count,                                    // particles to spawn; 0 = pure-canvas reveal
-  init(ctx, capacity, w, h),                // allocate parallel per-particle arrays
+  init(ctx, capacity, w, h, rng),           // allocate arrays; rng = seeded Random (same as spawn), use instead of Math.random for reproducible reveals
   spawn(idx, rng, w, h, spot),              // -> { x, y, vx, vy, life }; spot is {x,y} in 0..1
   tick(dt, elapsedMs, p, ctx, src, w, h),   // -> true when complete
   destroy(),
@@ -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
@@ -116,6 +125,8 @@ start+capacity) of the lanes. reserving past maxParticles throws. Each controlle
 into its slots (data[start+i]=i), renders through subarray views of its range (built once per
 controller, reused every frame -> zero per-frame alloc), draws to its own ctx, keeps its own RNG.
 stage.tick(dt) advances the single engine once; the one onTick fans out to every active reveal.
+controller.destroy() reclaims its sub-range into a stage free-list for exact-capacity reuse by a
+later createController; cancel/completion hold the range (the controller stays revealable).
 Feasible with no engine change because raw tick(dt) is pure dispatch (no physics/culling) and the
 lanes are public typed arrays recipes already write. See decisions/0001-concurrent-shared-reveals.md.
 

package/package.json

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

package/src/ScratchController.js

@@ -204,7 +204,7 @@ export function createScratchController(sourceCanvas, effectCanvas, {
             const spots = scanner.scan(scanPrecision);
 
             // Init recipe with LOGICAL size (recipes stay in CSS px).
-            recipe.init(ctx, cap, logicalW, logicalH);
+            recipe.init(ctx, cap, logicalW, logicalH, rng);
 
             // 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

package/src/ScratchRecipes.js

@@ -5,7 +5,7 @@
  * ScratchController.reveal(recipe, onDone). Grouped by family below.
  *
  * Recipe interface:
- *   { count, init(ctx, capacity, w, h),
+ *   { count, init(ctx, capacity, w, h, rng),
  *     spawn(idx, rng, w, h, spot),
  *     tick(dt, elapsedMs, engine, ctx, sourceCanvas, w, h) -> boolean,
  *     destroy() }
@@ -28,7 +28,7 @@ import {resolvePalette} from './Palette.js';
 //  Spawn particles from the scratch layer's still-covered pixels and run their own physics.
 // ===========================================================================
 
-export function BurnRecipe({count = 150, duration = 1500, colors, theme} = {}) {
+export function BurnRecipe({count = 100, duration = 200, colors, theme} = {}) {
     let pSize, pDecay, pColorIdx;
     const palette = resolvePalette(colors, theme, ['#ff6b00', '#ff8c00', '#ffaa00', '#ff4500', '#8B0000']);
 
@@ -40,10 +40,10 @@ export function BurnRecipe({count = 150, duration = 1500, colors, theme} = {}) {
             pColorIdx = new Uint8Array(capacity);
         },
         spawn(idx, rng, w, h, spot) {
-            pSize[idx] = rng.range(2, 5);
-            pDecay[idx] = rng.range(0.01, 0.03);
+            pSize[idx] = rng.range(3, 8);
+            pDecay[idx] = rng.range(0.02, 0.05);
             pColorIdx[idx] = rng.int(0, palette.length - 1);
-            return {x: spot.x * w, y: spot.y * h, vx: rng.range(-1, 1), vy: rng.range(-1, -4), life: 1.0};
+            return {x: spot.x * w, y: spot.y * h, vx: rng.range(-1, 1), vy: rng.range(-7, -2), life: 1.0};
         },
         tick(dt, elapsed, engine, ctx, src, w, h) {
             const {x, y, vx, vy, life, data, max} = engine;
@@ -55,7 +55,6 @@ 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 * ds;
                 x[i] += vx[i] * ds;
                 y[i] += vy[i] * ds;
                 life[i] -= pDecay[p] * ds;
@@ -84,7 +83,7 @@ export function BurnRecipe({count = 150, duration = 1500, 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']);
 
@@ -100,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;
@@ -172,20 +171,21 @@ export function ExplodeRecipe({count = 80, duration = 750, force = 15, colors, t
 }
 
 
-export function DragonBreathRecipe({count = 200, duration = 1200, colors, theme} = {}) {
-    let pSize, pDecay, pColorIdx;
+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']);
 
     return {
         count,
-        init(ctx, capacity) {
+        init(ctx, capacity, w, h, rng) {
+            r = rng;
             pSize = new Float32Array(capacity);
             pDecay = new Float32Array(capacity);
             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,14 +203,15 @@ 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;
                 const p = data[i];
                 x[i] += vx[i] * ds;
                 y[i] += vy[i] * ds;
-                vx[i] += (Math.random() - 0.5) * 0.5 * ds;
+                vx[i] += (r.next() - 0.5) * 0.5 * ds;
                 vy[i] *= dvy;
                 pSize[p] *= dsz;
                 life[i] -= pDecay[p] * ds;
@@ -233,13 +234,13 @@ export function DragonBreathRecipe({count = 200, duration = 1200, colors, theme}
             return alive === 0 && elapsed >= duration;
         },
         destroy() {
-            pSize = pDecay = pColorIdx = null;
+            pSize = pDecay = pColorIdx = r = null;
         },
     };
 }
 
 
-export function IceBreathRecipe({count = 300, 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 = 300, 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,9 @@ export function IceBreathRecipe({count = 300, 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);
+            src.style.opacity = 1 - easeIn(fadeT);
+            src.style.filter = `brightness(${1 + fadeT})`;
 
             for (let i = 0; i < max; i++) {
                 if (life[i] <= 0) continue;
@@ -629,12 +630,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 +653,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 +677,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 +692,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 +716,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 +743,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 +772,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 +791,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 +801,8 @@ export function GlitchRevealRecipe({duration = 800} = {}) {
             return raw >= 1;
         },
         destroy() {
-            img = null;
-            imgReady = false;
             sliceSeeds = null;
+            hidden = false;
         },
     };
 }
@@ -869,24 +842,26 @@ 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']);
-    let py, pvy, pox, psz, pcol;
+    const ez = typeof ease === 'function' ? ease : easeInOut;
+    let py, pvy, pox, psz, pcol, r;
 
     return {
         count: 0, // No SoA particles -- managed internally
-        init(ctx, capacity, w, h) {
+        init(ctx, capacity, w, h, rng) {
+            r = rng;
             py = new Float32Array(particleCount);
             pvy = new Float32Array(particleCount);
             pox = new Float32Array(particleCount);
             psz = new Float32Array(particleCount);
             pcol = new Uint8Array(particleCount);
             for (let i = 0; i < particleCount; i++) {
-                py[i] = Math.random() * h;
-                pvy[i] = (Math.random() - 0.5) * 2;
-                pox[i] = (Math.random() - 0.5) * beamWidth * 0.6;
-                psz[i] = Math.random() * 4 + 2;
-                pcol[i] = (Math.random() * palette.length) | 0;
+                py[i] = r.next() * h;
+                pvy[i] = (r.next() - 0.5) * 2;
+                pox[i] = (r.next() - 0.5) * beamWidth * 0.6;
+                psz[i] = r.next() * 4 + 2;
+                pcol[i] = (r.next() * palette.length) | 0;
             }
         },
         spawn() {
@@ -894,7 +869,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;
@@ -916,10 +891,10 @@ export function ShineWaveRecipe({duration = 600, beamWidth = 80, particleCount =
             for (let i = 0; i < particleCount; i++) {
                 const px2 = bx + pox[i];
                 py[i] += pvy[i] * ds;
-                pvy[i] += (Math.random() - 0.5) * 0.3 * ds;
+                pvy[i] += (r.next() - 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 * ds, 1, 8);
+                psz[i] = clamp(psz[i] + (r.next() - 0.5) * 0.3 * ds, 1, 8);
                 ctx.globalAlpha = 0.7;
                 ctx.fillStyle = palette[pcol[i]];
                 ctx.save();
@@ -932,7 +907,7 @@ export function ShineWaveRecipe({duration = 600, beamWidth = 80, particleCount =
             return raw >= 1;
         },
         destroy() {
-            py = pvy = pox = psz = pcol = null;
+            py = pvy = pox = psz = pcol = r = null;
         },
     };
 }
@@ -1013,6 +988,7 @@ export function LightningCrawlRecipe({boltCount = 5, duration = 600, colors, the
     const cMid = palette[(palette.length - 1) >> 1];
     const cOuter = palette[palette.length - 1];
     let bolts = [];
+    let r;
 
     function genPts(x1, y1, x2, y2, d) {
         let p = [{x: x1, y: y1}, {x: x2, y: y2}];
@@ -1022,7 +998,7 @@ export function LightningCrawlRecipe({boltCount = 5, duration = 600, colors, the
                 const a = p[j], b = p[j + 1];
                 const mx = (a.x + b.x) / 2, my = (a.y + b.y) / 2;
                 const dist = Math.hypot(b.x - a.x, b.y - a.y);
-                const off = (Math.random() - 0.5) * dist * 0.4;
+                const off = (r.next() - 0.5) * dist * 0.4;
                 const nx = -(b.y - a.y) / (dist || 1), ny = (b.x - a.x) / (dist || 1);
                 np.push({x: mx + nx * off, y: my + ny * off});
                 np.push(b);
@@ -1045,39 +1021,40 @@ export function LightningCrawlRecipe({boltCount = 5, duration = 600, colors, the
             ctx.stroke();
         });
         if (d > 2) for (let i = 2; i < pts.length - 1; i += 3) {
-            if (Math.random() > 0.5) continue;
-            const bl = Math.hypot(x2 - x1, y2 - y1) * (0.15 + Math.random() * 0.2);
-            const ba = Math.atan2(y2 - y1, x2 - x1) + (Math.random() - 0.5) * 1.5;
+            if (r.next() > 0.5) continue;
+            const bl = Math.hypot(x2 - x1, y2 - y1) * (0.15 + r.next() * 0.2);
+            const ba = Math.atan2(y2 - y1, x2 - x1) + (r.next() - 0.5) * 1.5;
             drawBolt(ctx, pts[i].x, pts[i].y, pts[i].x + Math.cos(ba) * bl, pts[i].y + Math.sin(ba) * bl, th * 0.5, d - 2);
         }
     }
 
     return {
         count: 0,
-        init(ctx, capacity, w, h) {
+        init(ctx, capacity, w, h, rng) {
+            r = rng;
             bolts = [];
             for (let b = 0; b < boltCount; b++) {
-                const e = (Math.random() * 4) | 0;
+                const e = (r.next() * 4) | 0;
                 let sx, sy;
                 if (e === 0) {
                     sx = 0;
-                    sy = Math.random() * h;
+                    sy = r.next() * h;
                 } else if (e === 1) {
                     sx = w;
-                    sy = Math.random() * h;
+                    sy = r.next() * h;
                 } else if (e === 2) {
-                    sx = Math.random() * w;
+                    sx = r.next() * w;
                     sy = 0;
                 } else {
-                    sx = Math.random() * w;
+                    sx = r.next() * w;
                     sy = h;
                 }
                 bolts.push({
                     sx,
                     sy,
-                    ex: w * (0.3 + Math.random() * 0.4),
-                    ey: h * (0.3 + Math.random() * 0.4),
-                    delay: Math.random() * 0.3
+                    ex: w * (0.3 + r.next() * 0.4),
+                    ey: h * (0.3 + r.next() * 0.4),
+                    delay: r.next() * 0.3
                 });
             }
         },
@@ -1109,6 +1086,7 @@ export function LightningCrawlRecipe({boltCount = 5, duration = 600, colors, the
         },
         destroy() {
             bolts = [];
+            r = null;
         },
     };
 }
@@ -1169,8 +1147,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) {
@@ -1181,7 +1160,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

@@ -46,6 +46,12 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
     const pending = new Set();
     let dispatching = false;
     let nextStart = 0;
+    // Free-list of reclaimed [start, capacity] ranges from destroyed controllers, in
+    // parallel arrays. Exact-match reuse only: a new controller reclaims a range solely
+    // when its capacity equals a freed one. Cold path (createController/destroy) -- never
+    // touched per frame.
+    const freeStart = [], freeCap = [];
+    let reclaimedCapacity = 0;
     let controllerCount = 0;
     let destroyed = false;
 
@@ -89,13 +95,32 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
         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}`,
-            );
+        // Reclaim an exact-capacity range from a destroyed controller before growing the
+        // pool. On a hit we skip the nextStart bump and the exhaustion throw entirely.
+        let start;
+        let reused = -1;
+        for (let i = 0; i < freeCap.length; i++) {
+            if (freeCap[i] === capacity) { reused = i; break; }
         }
-        const start = nextStart;
-        nextStart += capacity;
+        if (reused >= 0) {
+            start = freeStart[reused];
+            // Swap-remove: order is irrelevant for exact-match reuse.
+            const last = freeCap.length - 1;
+            freeStart[reused] = freeStart[last];
+            freeCap[reused] = freeCap[last];
+            freeStart.pop();
+            freeCap.pop();
+            reclaimedCapacity -= capacity;
+        } else {
+            if (nextStart + capacity > maxParticles) {
+                throw new RangeError(
+                    `createController: pool exhausted -- ${nextStart}+${capacity} exceeds maxParticles ${maxParticles}`,
+                );
+            }
+            start = nextStart;
+            nextStart += capacity;
+        }
+        // A reused range is a NEW controller, so the index always advances -> new default seed.
         const index = controllerCount++;
 
         const ctx = effectCanvas.getContext('2d');
@@ -133,7 +158,8 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
         // 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).
+        // Cold path: once per reveal, never per frame. The sub-range is held across every
+        // completion and cancel, and reclaimed into the stage free-list only on destroy() (B-8).
         function endReveal(fireDone) {
             if (!activeRecipe) return;
             if (activeRecipe.destroy) activeRecipe.destroy();
@@ -171,7 +197,7 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
                 hostSnapshot = captureHostStyle(sourceCanvas);
 
                 const spots = scanner.scan(scanPrecision);
-                recipe.init(ctx, capacity, cw, ch);
+                recipe.init(ctx, capacity, cw, ch, rng);
 
                 const requested = recipe.count ?? capacity;
                 const count = Math.min(requested, capacity);
@@ -224,7 +250,10 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
             /** Re-seed this controller's RNG. */
             seed(s) { rng.reset(s); },
 
-            /** Remove this controller from the stage. Its sub-range is not reclaimed (v1). */
+            /**
+             * Remove this controller from the stage. Its sub-range is reclaimed into the
+             * stage free-list for exact-capacity reuse by a later createController.
+             */
             destroy() {
                 if (ctlDestroyed) return;
                 ctlDestroyed = true;
@@ -232,6 +261,9 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
                 // host-style restore, active-set removal, no onDone) before scanner teardown.
                 endReveal(false);
                 scanner.destroy();
+                // Reclaim the sub-range. The early-return above guarantees one push per
+                // controller, so a double-destroy cannot double-free.
+                freeStart.push(start); freeCap.push(capacity); reclaimedCapacity += capacity;
             },
         };
         return controller;
@@ -255,8 +287,27 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
             engine.destroy();
         },
 
-        /** @internal How many slots are still unreserved (for tests / diagnostics). */
-        get remainingCapacity() { return maxParticles - nextStart; },
+        /**
+         * @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;
+        },
     };
 }