@zakkster/lite-scratch-fx 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## [1.6.0] - 2026-08-23
+
+Reduced-motion support (N-4). Backward compatible: the new controller/stage option
+defaults to `false`, the helper and metadata field are additive, and existing callers
+are byte-unaffected. The per-frame render path is unchanged.
+
+### Added
+- **`reducedMotion` option on `createScratchController` and `stage.createController`
+  (default `false`).** When `true`, every `reveal(recipe)` ignores the passed recipe and
+  runs an internal `count: 0` opacity fade instead -- zero particles, no motion beyond the
+  fade, `onDone` still fires once on completion. The library does not read
+  `prefers-reduced-motion` itself; the host passes the result of its own media query. The
+  fallback recipe is built once per controller (cold path) and reused across reveals; it is
+  stateless, so it is re-entrant across successive reveals on the same controller.
+- **`reducedMotionRecipe(recipe, { scale = 0.25, duration } = {})`.** A pure wrapper that
+  keeps a recipe's look but spawns `Math.round(recipe.count * scale)` particles (a quarter
+  by default). It delegates `init`/`spawn`/`tick`/`destroy` to the inner recipe and reuses
+  its arrays, so it adds no hot-path allocation. `duration`, if given, caps the reveal early
+  (`elapsedMs >= duration`); it does not re-time the inner easing curve. It reduces particle
+  count only and cannot suppress a recipe's own per-particle glow, which is drawn inside the
+  inner `tick`. Throws `TypeError` on a non-recipe argument or a non-finite/negative `scale`.
+- **`RECIPE_META[*].motionSafe` (boolean).** Marks inherently calm built-ins so a picker can
+  prefer them under reduced motion. Strict: `true` for `fade` only (a pure opacity fade);
+  every recipe that moves geometry -- particles, the peel wipe, the implosion -- is `false`.
+  Threaded through `registerRecipe` with the same prev-fallback rule as the other flags.
+
+### Changed
+- **Torture gate extended.** Two tiers added to `test/torture.mjs`: T6 gates the blanket
+  `reducedMotion` reveal/tick/complete cycle and T7 gates a `reducedMotionRecipe`-wrapped
+  steady state, both under the existing 64 B/op ceiling (measured 41.6 and 6.9 B/op; their
+  broken-variant controls allocate ~1193 and ~1149 B/op). Test count 283 -> 322.
+
+## [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

package/README.md

@@ -58,6 +58,7 @@ time.
   - [createScratchController](#createscratchcontroller)
   - [createScratchStage](#createscratchstage)
   - [Registry and palette helpers](#registry-and-palette-helpers)
+  - [Reduced motion](#reduced-motion)
   - [Constants](#constants)
 - [Composability](#composability)
 - [Zero-GC design notes](#zero-gc-design-notes)
@@ -270,11 +271,39 @@ current built-in look:
 - **`PeelRecipe`** / **`ShineWaveRecipe`** -- `ease` (`(t: number) => number`): the easing
   applied to progress; defaults to the recipe's built-in curve (`easeIn` / `easeInOut`).
 
+### Reduced motion
+
+Reveals run in lottery / instant-win UIs, so honouring `prefers-reduced-motion` matters.
+The library does not read the media query itself -- the host owns it -- but it gives you
+two ways to respond, plus a flag for building a picker.
+
+- **Blanket switch: `{ reducedMotion: true }`** on `createScratchController` or
+  `stage.createController`. Every `reveal(recipe)` then ignores the recipe it is handed and
+  runs a calm `count: 0` opacity fade instead -- zero particles, no spray, `onDone` still
+  fires once on completion. This is the honest "motion off" path.
+
+  ```js
+  const calm = matchMedia('(prefers-reduced-motion: reduce)').matches;
+  const ctrl = createScratchController(cover, fx, { reducedMotion: calm });
+  ctrl.reveal(RECIPES.dragonBreath());   // draws a plain fade when calm is true
+  ```
+
+- **Toned-down variant: `reducedMotionRecipe(recipe, { scale = 0.25, duration? })`**. Wraps
+  any recipe and keeps its look but spawns `round(count * scale)` particles (a quarter, by
+  default); an optional `duration` caps the reveal early. It reuses the inner recipe's
+  arrays, so it adds no hot-path allocation. Note it can only reduce particle *count* -- it
+  cannot suppress a recipe's own per-particle glow, which is drawn inside the recipe's
+  `tick`. For a full "motion off", use the blanket switch above.
+
+- **`RECIPE_META[*].motionSafe`** marks the inherently calm built-ins so a picker can prefer
+  them. It is strict: only `fade` (a pure opacity fade) is `motionSafe: true`; every recipe
+  that moves geometry -- particles, a peel wipe, an implosion -- is `false`.
+
 ### Constants
 
 | Constant                  | Value                                                        | Meaning                                              |
 | ------------------------- | ----------------------------------------------------------- | ---------------------------------------------------- |
-| `VERSION`                 | `'1.5.0'`                                                    | Package version string (synced to package.json).     |
+| `VERSION`                 | `'1.6.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.     |

package/index.d.ts

@@ -108,6 +108,12 @@ export interface ScratchControllerOptions {
      * window.devicePixelRatio. Recipes still author in CSS pixels.
      */
     dpr?: number;
+    /**
+     * Honour prefers-reduced-motion. When true, every reveal runs a calm count:0
+     * opacity fade instead of the requested recipe (motion off, not a wrapped recipe).
+     * Default false. The host owns the media query and passes the result.
+     */
+    reducedMotion?: boolean;
 }
 
 export interface ScratchController {
@@ -170,6 +176,11 @@ export interface StageControllerOptions {
      * dpr). Pass window.devicePixelRatio. Recipes still author in CSS pixels.
      */
     dpr?: number;
+    /**
+     * Honour prefers-reduced-motion. When true, every reveal runs a calm count:0
+     * opacity fade instead of the requested recipe. Default false. The host owns the query.
+     */
+    reducedMotion?: boolean;
 }
 
 /** A stage-managed controller. The stage drives it, so it has no `tick` of its own. */
@@ -244,6 +255,18 @@ export function PeelRecipe(opts?: RecipeOptions & { ease?: (t: number) => number
 export function FadeRecipe(opts?: RecipeOptions): Recipe;
 export function ImplosionRecipe(opts?: RecipeOptions): Recipe;
 
+/**
+ * Dial a recipe down for reduced motion: a pure delegating wrapper that reduces the
+ * inner recipe's particle COUNT (default a quarter) and, optionally, caps the reveal
+ * early via `duration`. Adds zero hot-path allocation (reuses the inner arrays). It
+ * cannot suppress the inner recipe's per-particle painted halo -- that lives inside
+ * its tick; `duration` caps the reveal early, it does not re-time the inner curve.
+ */
+export function reducedMotionRecipe(
+    recipe: Recipe,
+    opts?: { scale?: number; duration?: number },
+): Recipe;
+
 export function GlitchRevealRecipe(opts?: RecipeOptions): Recipe;
 export function MatrixDecayRecipe(opts?: ThemeableRecipeOptions): Recipe;
 export function GoldDustRecipe(opts?: ThemeableRecipeOptions): Recipe;
@@ -282,6 +305,8 @@ export interface RecipeMeta {
     category: RecipeCategory;
     themeable: boolean;
     needsUntaintedCanvas: boolean;
+    /** Inherently-calm reveal a picker can prefer under prefers-reduced-motion; strict = pure-opacity fade only. */
+    motionSafe: boolean;
 }
 
 /** Live metadata array for every recipe; `registerRecipe` keeps it in sync. */

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.5.0';
+export const VERSION = '1.6.0';
 
 export { createScratchController } from './src/ScratchController.js';
 export { default as ScratchController } from './src/ScratchController.js';
@@ -27,6 +27,7 @@ export {
     ShatterRecipe, PixelShatterRecipe, GlitchRevealRecipe,
     ShineRecipe, ShineWaveRecipe, LaserScanRecipe, LightningCrawlRecipe, NeonPulseRecipe,
     PeelRecipe, FadeRecipe, ImplosionRecipe,
+    reducedMotionRecipe,
 } from './src/ScratchRecipes.js';
 
 import {
@@ -76,29 +77,31 @@ export const RECIPES = Object.assign(Object.create(null), {
  *                        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.
+ *   motionSafe          inherently-calm reveal a picker can prefer under
+ *                        prefers-reduced-motion; strict = pure-opacity fade only.
  */
 export const RECIPE_META = [
-    { id: 'burn', name: 'Burn', category: 'particle', themeable: true, needsUntaintedCanvas: false },
-    { id: 'dissolve', name: 'Dissolve', category: 'particle', themeable: true, needsUntaintedCanvas: false },
-    { id: 'explode', name: 'Explode', category: 'particle', themeable: true, needsUntaintedCanvas: false },
-    { id: 'dragonBreath', name: 'Dragon Breath', category: 'particle', themeable: true, needsUntaintedCanvas: false },
-    { id: 'iceBreath', name: 'Ice Breath', category: 'particle', themeable: true, needsUntaintedCanvas: false },
-    { id: 'goldDust', name: 'Gold Dust', category: 'particle', themeable: true, needsUntaintedCanvas: false },
-    { id: 'confettiBlast', name: 'Confetti Blast', category: 'particle', themeable: true, needsUntaintedCanvas: false },
-    { 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: 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 },
-    { id: 'lightningCrawl', name: 'Lightning Crawl', category: 'beam', themeable: true, needsUntaintedCanvas: false },
-    { id: 'neonPulse', name: 'Neon Pulse', category: 'beam', themeable: true, needsUntaintedCanvas: false },
-    { id: 'peel', name: 'Peel', category: 'css', themeable: false, needsUntaintedCanvas: false },
-    { id: 'fade', name: 'Fade', category: 'css', themeable: false, needsUntaintedCanvas: false },
-    { id: 'implosion', name: 'Implosion', category: 'css', themeable: false, needsUntaintedCanvas: false },
+    { id: 'burn', name: 'Burn', category: 'particle', themeable: true, needsUntaintedCanvas: false, motionSafe: false },
+    { id: 'dissolve', name: 'Dissolve', category: 'particle', themeable: true, needsUntaintedCanvas: false, motionSafe: false },
+    { id: 'explode', name: 'Explode', category: 'particle', themeable: true, needsUntaintedCanvas: false, motionSafe: false },
+    { id: 'dragonBreath', name: 'Dragon Breath', category: 'particle', themeable: true, needsUntaintedCanvas: false, motionSafe: false },
+    { id: 'iceBreath', name: 'Ice Breath', category: 'particle', themeable: true, needsUntaintedCanvas: false, motionSafe: false },
+    { id: 'goldDust', name: 'Gold Dust', category: 'particle', themeable: true, needsUntaintedCanvas: false, motionSafe: false },
+    { id: 'confettiBlast', name: 'Confetti Blast', category: 'particle', themeable: true, needsUntaintedCanvas: false, motionSafe: false },
+    { id: 'cosmicDust', name: 'Cosmic Dust', category: 'particle', themeable: true, needsUntaintedCanvas: false, motionSafe: false },
+    { id: 'matrixDecay', name: 'Matrix Decay', category: 'particle', themeable: true, needsUntaintedCanvas: false, motionSafe: false },
+    { id: 'liquidMelt', name: 'Liquid Melt', category: 'particle', themeable: true, needsUntaintedCanvas: false, motionSafe: false },
+    { id: 'shatter', name: 'Shatter', category: 'image', themeable: false, needsUntaintedCanvas: false, motionSafe: false },
+    { id: 'pixelShatter', name: 'Pixel Shatter', category: 'image', themeable: false, needsUntaintedCanvas: false, motionSafe: false },
+    { id: 'glitchReveal', name: 'Glitch Reveal', category: 'image', themeable: false, needsUntaintedCanvas: false, motionSafe: false },
+    { id: 'shine', name: 'Shine', category: 'beam', themeable: false, needsUntaintedCanvas: false, motionSafe: false },
+    { id: 'shineWave', name: 'Shine Wave', category: 'beam', themeable: true, needsUntaintedCanvas: false, motionSafe: false },
+    { id: 'laserScan', name: 'Laser Scan', category: 'beam', themeable: true, needsUntaintedCanvas: false, motionSafe: false },
+    { id: 'lightningCrawl', name: 'Lightning Crawl', category: 'beam', themeable: true, needsUntaintedCanvas: false, motionSafe: false },
+    { id: 'neonPulse', name: 'Neon Pulse', category: 'beam', themeable: true, needsUntaintedCanvas: false, motionSafe: false },
+    { id: 'peel', name: 'Peel', category: 'css', themeable: false, needsUntaintedCanvas: false, motionSafe: false },
+    { id: 'fade', name: 'Fade', category: 'css', themeable: false, needsUntaintedCanvas: false, motionSafe: true },
+    { id: 'implosion', name: 'Implosion', category: 'css', themeable: false, needsUntaintedCanvas: false, motionSafe: false },
 ];
 
 /** Names of every built-in recipe (the keys of RECIPES at load time). */
@@ -111,7 +114,7 @@ export const RECIPE_NAMES = Object.freeze(Object.keys(RECIPES));
  *
  * @param {string} id        short name (the RECIPES key)
  * @param {Function} factory a recipe factory: (opts) => Recipe
- * @param {{ name?: string, category?: string, themeable?: boolean, needsUntaintedCanvas?: boolean }} [meta]
+ * @param {{ name?: string, category?: string, themeable?: boolean, needsUntaintedCanvas?: boolean, motionSafe?: boolean }} [meta]
  *   Omitted fields fall back to the existing entry (when overriding), then to a
  *   de-camelCased name, category 'custom', and false flags.
  * @returns {Function} the registered factory
@@ -135,6 +138,7 @@ export function registerRecipe(id, factory, meta) {
         themeable: meta && 'themeable' in meta ? !!meta.themeable : (prev ? prev.themeable : false),
         needsUntaintedCanvas: meta && 'needsUntaintedCanvas' in meta
             ? !!meta.needsUntaintedCanvas : (prev ? prev.needsUntaintedCanvas : false),
+        motionSafe: meta && 'motionSafe' in meta ? !!meta.motionSafe : (prev ? prev.motionSafe : false),
     };
     if (idx >= 0) RECIPE_META[idx] = entry; else RECIPE_META.push(entry);
     return factory;

package/llms.txt

@@ -8,7 +8,8 @@
 ## Core model
 
 createScratchController(sourceCanvas, effectCanvas,
-    { maxParticles = 2000, seed = Date.now(), scanPrecision = 32, driven = false, engine, dpr = 1 })
+    { maxParticles = 2000, seed = Date.now(), scanPrecision = 32, driven = false, engine, dpr = 1,
+      reducedMotion = false })
   -> { reveal(recipe, onDone?), tick(dt), cancel(), seed(s), destroy() }
 
 sourceCanvas = the scratch layer (what the user scratches off).
@@ -85,12 +86,14 @@ falls back to the recipe's default curve.
 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, ...).
 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
+RECIPE_META: a live array of { id, name, category, themeable, needsUntaintedCanvas, motionSafe } for
+  every recipe -- the source for building pickers without hardcoding. category is
   '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 }.
+  requirement to pickers. themeable is true for the 14 recipes that take { colors, theme }. motionSafe
+  is an inherently-calm reveal a picker can prefer under prefers-reduced-motion; strict = true for
+  'fade' ONLY (pure-opacity cross-fade), false for every other built-in (all animate or paint).
 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',
@@ -115,7 +118,7 @@ modes exist now:
 ## Concurrent reveals over one pool: createScratchStage
 
 createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr = 1 })
-  -> { createController(src, fx, { capacity = 300, seed?, scanPrecision = 32, dpr? }) -> stageController,
+  -> { createController(src, fx, { capacity = 300, seed?, scanPrecision = 32, dpr?, reducedMotion = false }) -> stageController,
        tick(dt), destroy(), get remainingCapacity, remainingCapacityFor(capacity) }
 stageController -> { reveal(recipe, onDone?), cancel(), seed(s), destroy() }   // NO tick -- the stage drives.
 
@@ -130,6 +133,23 @@ later createController; cancel/completion hold the range (the controller stays r
 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.
 
+## Reduced motion
+
+The host owns the media query; the library never touches matchMedia (DOM-query-free, SSR-safe).
+Read prefers-reduced-motion and pass the boolean in. Two shapes:
+  Blanket switch: createScratchController(src, fx, { reducedMotion }) (and stage.createController).
+    When true, EVERY reveal honestly REPLACES the requested recipe with a calm count:0 opacity fade
+    (~300ms, motion off -- not a wrapped recipe): zero particles spawn, no halo painted. The calm
+    fallback is built once per controller (cold) -> no per-reveal garbage. Default false = full motion.
+  Helper: reducedMotionRecipe(recipe, { scale = 0.25, duration }) -> Recipe. A pure delegating wrapper:
+    count becomes round(inner.count * scale) (fewer particles; 0 stays 0), init/spawn/tick/destroy
+    delegate verbatim -> zero added hot-path alloc. Reduces particle COUNT only -- it CANNOT suppress
+    the inner recipe's per-particle painted halo (that lives in the inner tick; deferred). duration is
+    an early-complete CAP (tick returns innerDone || elapsedMs >= duration), NOT a re-timing of the curve.
+    Throws TypeError if recipe has no tick function or scale is not a finite number >= 0.
+RECIPE_META.motionSafe lets a picker prefer 'fade' (the only strict motion-safe reveal) under the query.
+See decisions/0003-reduced-motion.md.
+
 ## Fixed in 1.0.0 (was broken pre-package)
 
 - Reveals never completed (double-driven engine loop -> corrupted dt). Fixed: engine self-drives.

package/package.json

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

@@ -44,6 +44,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';
+import { reducedMotionFallbackRecipe } from './ScratchRecipes.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
@@ -62,6 +63,9 @@ const busySharedEngines = new WeakSet();
  * @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
+ * @param {boolean} [options.reducedMotion=false]  Honour prefers-reduced-motion: every reveal
+ *                                                  runs a calm count:0 opacity fade instead of
+ *                                                  the requested recipe (motion off, not wrapped)
  */
 export function createScratchController(sourceCanvas, effectCanvas, {
     maxParticles = 2000,
@@ -70,6 +74,7 @@ export function createScratchController(sourceCanvas, effectCanvas, {
     driven = false,
     engine: externalEngine = null,
     dpr = 1,
+    reducedMotion = false,
 } = {}) {
     if (!(typeof dpr === 'number' && Number.isFinite(dpr) && dpr > 0)) {
         throw new TypeError('createScratchController: dpr must be a positive finite number');
@@ -98,6 +103,11 @@ export function createScratchController(sourceCanvas, effectCanvas, {
     const scanner = createPixelScanner(sourceCanvas);
     const spot = { x: 0.5, y: 0.5 };   // the single shared, reused spawn point
 
+    // Reduced-motion blanket fallback: built ONCE here (cold) when the option is
+    // set, reused across every reveal so no per-reveal garbage. Stateless -- the
+    // controller tracks elapsed and the recipe only writes src.style.opacity.
+    const reducedFallback = reducedMotion ? reducedMotionFallbackRecipe() : null;
+
     // The particle-view object handed to recipe.tick every frame. Built ONCE and
     // reused: the engine's SoA arrays are stable references for the life of the engine,
     // so a fresh `{ x, y, ... }` literal per frame would be a pure zero-GC violation on
@@ -167,6 +177,11 @@ export function createScratchController(sourceCanvas, effectCanvas, {
             if (destroyed || activeRecipe) return;
             if (!ownEngine && busySharedEngines.has(engine)) return;
 
+            // Reduced-motion blanket: honestly REPLACE the requested recipe with the
+            // calm count:0 opacity fade (never a wrap). Cold path, once per reveal;
+            // the count read + spawn loop below run against the swapped-in recipe.
+            if (reducedMotion) recipe = reducedFallback;
+
             activeRecipe = recipe;
             onComplete = onDone || null;
             elapsed = 0;

package/src/ScratchRecipes.js

@@ -275,8 +275,9 @@ export function IceBreathRecipe({count = 450, duration = 1500, spread = 0.225, s
             const dv = Math.pow(0.96, ds);
             let alive = 0;
             const fadeT = clamp((elapsed - 100) / 500, 0, 1);
-            src.style.opacity = 1 - easeIn(fadeT);
-            src.style.filter = `brightness(${1 + fadeT})`;
+            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;
@@ -1237,6 +1238,88 @@ export function ImplosionRecipe({duration = 800} = {}) {
 }
 
 
+// ===========================================================================
+//  REDUCED MOTION
+// ===========================================================================
+
+// Fixed fade duration for the reduced-motion blanket fallback (ms). A short,
+// calm pure-opacity dissolve -- honest "motion off", not a wrapped recipe.
+const REDUCED_MOTION_FADE_MS = 300;
+
+/**
+ * The calm fallback a controller/stage swaps in when created with
+ * `{ reducedMotion: true }`. A count:0 recipe: zero particles spawn, and the
+ * scratch layer fades its opacity 1 -> 0 over a short fixed duration. Shared by
+ * ScratchController and ScratchStage so the calm body lives in exactly one place.
+ * Satisfies the full recipe contract (init/spawn/tick/destroy).
+ * @returns {Object} a fresh reduced-motion fallback recipe
+ */
+export function reducedMotionFallbackRecipe() {
+    return {
+        count: 0,
+        init() {
+        },
+        // count:0 means the controller never calls spawn; kept for contract safety.
+        spawn() {
+            return {x: 0, y: 0, vx: 0, vy: 0, life: 0};
+        },
+        tick(dt, elapsedMs, engine, ctx, src) {
+            src.style.opacity = 1 - clamp(elapsedMs / REDUCED_MOTION_FADE_MS, 0, 1);
+            return elapsedMs >= REDUCED_MOTION_FADE_MS;
+        },
+        destroy() {
+        },
+    };
+}
+
+/**
+ * A pure delegating wrapper that dials an existing recipe down for reduced
+ * motion by reducing its particle COUNT (default a quarter) and, optionally,
+ * capping the reveal early. It reuses the inner recipe's arrays and delegates
+ * init/spawn/tick/destroy verbatim, so it adds ZERO hot-path allocation.
+ *
+ * Honest limits, on purpose:
+ *  - It reduces particle COUNT only. It CANNOT suppress the per-particle painted
+ *    halo/glow -- that lives inside the inner recipe's own tick. Suppressing it
+ *    needs a recipe-interface change and is deferred.
+ *  - `duration` is an early-complete CAP, not a re-timing. The inner curve's own
+ *    duration is baked into its closure and cannot be shortened from outside, so
+ *    tick returns `innerDone || (duration != null && elapsedMs >= duration)`.
+ *    The reveal ends sooner; the inner animation is not re-scaled onto it.
+ *
+ * @param {Object} recipe  the inner recipe to dial down
+ * @param {{ scale?: number, duration?: number }} [opts]
+ *   scale     particle-count multiplier (default 0.25); finite, >= 0
+ *   duration  optional early-complete cap in ms
+ * @returns {Object} the wrapped recipe
+ */
+export function reducedMotionRecipe(recipe, {scale = 0.25, duration} = {}) {
+    if (!recipe || typeof recipe !== 'object' || typeof recipe.tick !== 'function') {
+        throw new TypeError('reducedMotionRecipe: recipe must be an object with a tick function');
+    }
+    if (!(typeof scale === 'number' && Number.isFinite(scale) && scale >= 0)) {
+        throw new TypeError('reducedMotionRecipe: scale must be a finite number >= 0');
+    }
+    return {
+        // Fewer particles. A count:0 inner recipe stays 0.
+        count: Math.round((recipe.count || 0) * scale),
+        init(ctx, capacity, w, h, rng) {
+            return recipe.init(ctx, capacity, w, h, rng);
+        },
+        spawn(idx, rng, w, h, spot) {
+            return recipe.spawn(idx, rng, w, h, spot);
+        },
+        tick(dt, elapsedMs, engine, ctx, src, w, h) {
+            const innerDone = recipe.tick(dt, elapsedMs, engine, ctx, src, w, h);
+            return innerDone || (duration != null && elapsedMs >= duration);
+        },
+        destroy() {
+            if (recipe.destroy) recipe.destroy();
+        },
+    };
+}
+
+
 // ===========================================================================
 //  RECIPE MAP
 // ===========================================================================

package/src/ScratchStage.js

@@ -24,6 +24,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';
+import { reducedMotionFallbackRecipe } from './ScratchRecipes.js';
 
 /**
  * @param {Object} [options]
@@ -86,8 +87,10 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
      * @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).
+     * @param {boolean} [opts.reducedMotion=false]  Honour prefers-reduced-motion: every reveal runs
+     *                                               a calm count:0 opacity fade instead of the recipe.
      */
-    function createController(sourceCanvas, effectCanvas, { capacity = 300, seed: cSeed, scanPrecision = 32, dpr = stageDpr } = {}) {
+    function createController(sourceCanvas, effectCanvas, { capacity = 300, seed: cSeed, scanPrecision = 32, dpr = stageDpr, reducedMotion = false } = {}) {
         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');
@@ -142,6 +145,10 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
         };
         const spot = { x: 0.5, y: 0.5 };
 
+        // Reduced-motion blanket fallback: built ONCE here (cold) when the option is
+        // set, reused across every reveal so no per-reveal garbage. Stateless.
+        const reducedFallback = reducedMotion ? reducedMotionFallbackRecipe() : null;
+
         let activeRecipe = null;
         let onComplete = null;
         let elapsed = 0;
@@ -180,6 +187,10 @@ export function createScratchStage({ maxParticles = 2000, seed = Date.now(), dpr
             /** Reveal a recipe. Ignored if this controller is already revealing or destroyed. */
             reveal(recipe, onDone) {
                 if (ctlDestroyed || activeRecipe) return;
+                // Reduced-motion blanket: honestly REPLACE the requested recipe with the
+                // calm count:0 opacity fade (never a wrap). Cold path; the count read +
+                // spawn loop below run against the swapped-in recipe.
+                if (reducedMotion) recipe = reducedFallback;
                 activeRecipe = recipe;
                 onComplete = onDone || null;
                 elapsed = 0;