@zakkster/lite-scratch-fx 1.0.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,86 @@
 # Changelog
 
+## [1.3.0] - 2026-08-22
+
+Abortable, self-restoring reveals. A reveal can now be cancelled, and the host scratch
+layer is returned to exactly the inline style it had before the reveal on completion,
+cancel, AND destroy -- so a grid can reset every round. Purely additive.
+
+### Added
+- **`controller.cancel()`** on both the standalone controller and stage-managed
+  controllers -- abort an in-flight reveal: stop the effect, restore the host canvas's
+  inline style, and do NOT fire `onDone`; the controller is revealable again afterwards.
+  A no-op when idle or destroyed. A stage `cancel()` does not touch other controllers'
+  in-flight reveals and does not reclaim the sub-range. See
+  `decisions/0002-host-style-and-cancel.md`.
+- `src/HostStyle.js` -- `captureHostStyle` / `restoreHostStyle`, a shared cold-path helper
+  that snapshots and restores the host layer's 5 inline style props.
+- **`dpr` option** for sharp rendering on high-DPI displays; recipes still author in CSS pixels.
+
+### Fixed
+- **Recipes stranded inline style on the host `sourceCanvas`.** The reveal recipes write
+  `opacity`, `transform`, `filter`, `clipPath`, and `transformOrigin` on the host layer
+  during `tick`; `opacity` was never restored and the others only on the completion frame,
+  so an aborted (or opacity-fading) reveal left the cover invisible or transformed forever.
+  The controller now snapshots those 5 props at reveal start and restores them on every
+  terminal transition -- completion, cancel, and destroy -- via a single `endReveal`
+  terminator. No inline `opacity`/`transform`/`filter`/`clipPath`/`transformOrigin`
+  survives a reveal.
+
+## [1.2.0] - 2026-08-22
+
+Concurrent scratch-card reveals over one shared particle pool. Purely additive --
+`createScratchController` and its options are unchanged.
+
+### Added
+- **`createScratchStage({ maxParticles, seed })`** -- a stage that owns one particle
+  engine and lets any number of controllers reveal **at the same time** over that one
+  pool (where `{ engine }` allowed only one reveal at a time). Each
+  `stage.createController(src, fx, { capacity })` reserves a fixed sub-range of the lanes,
+  renders only its own particles through reused subarray views (zero per-frame allocation),
+  and keeps its own deterministic RNG. `stage.tick(dt)` (seconds) drives every active reveal
+  from one clock; reserving past `maxParticles` throws. Stage-managed controllers have no
+  `tick` of their own. See `decisions/0001-concurrent-shared-reveals.md`.
+- `src/PixelScan.js` -- the reveal-scan logic extracted into a shared `createPixelScanner`,
+  now used by both the controller and the stage (no behaviour change).
+- A `VERSION`-matches-`package.json` test, and a README rebuilt on the LiteSepforge
+  documentation spine. No API or behaviour change.
+
+### Notes
+- Feasible with no change to `@zakkster/lite-soa-particle-engine`: raw-mode `tick(dt)` is
+  pure dispatch and the lanes are public typed arrays recipes already write, so a stage can
+  partition one pool into per-controller sub-ranges entirely in this package.
+
+## [1.1.0] - 2026-08-22
+
+Recipe organization and an extensible registry, modeled on `@zakkster/lite-ambient-fx`.
+No behaviour change to any recipe -- all 21 bodies are byte-identical to 1.0.0.
+
+### Added
+- **`RECIPE_META`** -- a live array of `{ id, name, category, themeable, needsUntaintedCanvas }`
+  for every recipe, so a host can build a picker (group by `category`, filter by `themeable`)
+  without hardcoding the list. Mirrors lite-ambient's `THEME_META`.
+- **`registerRecipe(id, factory, meta?)`** -- register a custom recipe or override a built-in;
+  it 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'`, and `false` flags.
+- `resolvePalette` is now exported (and typed) for authors writing themeable recipes.
+- **Host-driven mode** -- `createScratchController(src, fx, { driven: true })` skips the
+  engine's RAF loop; the host calls `controller.tick(dt)` (dt in seconds) so one page clock
+  drives N controllers. `tick()` is a no-op unless driven and a reveal is active.
+- **Shared engine** -- `createScratchController(src, fx, { engine })` reuses a caller-supplied
+  particle engine, so a grid of scratch boxes holds one lane pool instead of one per box.
+  A shared engine serves one reveal at a time (a reveal on a busy shared engine is ignored);
+  `destroy()` never tears down a caller-supplied engine. The two options compose.
+
+### Changed
+- **The two recipe files are merged into one `src/ScratchRecipes.js`, grouped by family**
+  (particle / image / beam / css) with section banners -- replacing the arbitrary
+  `ScratchRecipes.js` (12) + `ScratchRecipes2.js` (9) split. `ScratchRecipes2.js` is removed
+  from the package. All imports resolve through `index.js`, so the public API is unchanged.
+- `RECIPES` is now an extensible null-prototype registry (was a frozen object) so
+  `registerRecipe` can add to it. Reads are unaffected.
+
 ## [1.0.0] - 2026-08-22
 
 First published release. The effects and controller existed as loose source files; this
@@ -8,18 +89,18 @@ zero-GC line on the reveal path, and stands up the torture gate.
 
 ### Added
 - `createScratchController(sourceCanvas, effectCanvas, { maxParticles, seed, scanPrecision })`
-  — scans the still-covered pixels of a scratch layer for spawn points, runs a reveal
+  -- scans the still-covered pixels of a scratch layer for spawn points, runs a reveal
   recipe to completion, clears the overlay, and calls the completion callback.
 - 21 reveal recipes: `burn`, `shatter`, `dissolve`, `explode`, `dragonBreath`,
   `iceBreath`, `shineWave`, `lightningCrawl`, `shine`, `peel`, `fade`, `implosion`,
   `glitchReveal`, `matrixDecay`, `goldDust`, `pixelShatter`, `laserScan`,
   `confettiBlast`, `liquidMelt`, `neonPulse`, `cosmicDust`.
 - **Themeable palettes.** The 14 recipes with a visible palette take a unified
-  `{ colors, theme }` pair — pass a `{ light, mid, dark }` `theme` shorthand or an
+  `{ colors, theme }` pair -- pass a `{ light, mid, dark }` `theme` shorthand or an
   explicit `colors` ramp; `colors` wins, and both default to the recipe's own palette.
   Replaces three inconsistent conventions (`color`, `colors`, hardcoded). New
   `resolvePalette` helper in `src/Palette.js`.
-- `RECIPES` registry (short-name → factory) and `RECIPE_NAMES` for data-driven pickers.
+- `RECIPES` registry (short-name -> factory) and `RECIPE_NAMES` for data-driven pickers.
 - Full TypeScript declarations (`index.d.ts`), including `Theme` and `ThemeableRecipeOptions`.
 - Test suite under `node:test` (46 checks): controller lifecycle, the `data[]` dataFlag
   indexing invariant, a reveal-to-completion smoke test for every recipe, and theming
@@ -32,7 +113,7 @@ zero-GC line on the reveal path, and stands up the torture gate.
 
 ### Changed
 - **Zero-GC reveal path.** `scanPixels` no longer mints an offscreen canvas or an
-  object per surviving pixel on every reveal — the scan canvas is built once and the
+  object per surviving pixel on every reveal -- the scan canvas is built once and the
   spawn points fill preallocated `Float32Array`s read through one reused `spot` object.
   The per-frame `tick` no longer allocates a fresh particle-view object; it reuses one.
 - Test runner is `node:test` (was vitest); `vitest` and `typescript` devDependencies
@@ -45,7 +126,7 @@ zero-GC line on the reveal path, and stands up the torture gate.
   `engine._loop` every frame, but the SoA engine already owns its own
   `requestAnimationFrame` loop and computes its own `dt`. Driving it a second time
   corrupted `dt`, so particle life never decayed and the completion condition
-  (`alive === 0 && elapsed >= duration`) was never met — a reveal would run forever. The
+  (`alive === 0 && elapsed >= duration`) was never met -- a reveal would run forever. The
   external ticker is removed; the engine self-drives via `start()` / `stop()`.
 - **`count: 0` recipes spawned a full pool.** `recipe.count || maxParticles` turned an
   explicit `0` (pure-canvas reveals like `shine`, `implosion`, `laserScan`) into