@codexo/exojs 0.6.12 → 0.7.12

package/CHANGELOG.md

@@ -4,6 +4,1430 @@ All notable changes to ExoJS are documented in this file.
 
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.12] - 2026-05-07
+
+API audit cleanup pass — implements collision-response computation that was
+silently returning zero/null, exports previously-internal type aliases that
+callers couldn't otherwise type, and removes a handful of small API papercuts
+surfaced during the JSDoc-coverage pass that landed across `0.7.x`.
+
+### Fixed — Collision-response computation
+
+Four collision paths were returning a `CollisionResponse` whose `projectionN`
+and `projectionV` were zero vectors (or returning `null` outright), making
+the response unusable for separation/sliding logic.
+
+- **`getCollisionRectangleRectangle`** — now returns the minimum-translation
+  vector (MTV) along the axis with the smaller penetration, signed by the
+  centre-to-centre direction. Existing `overlap` and containment flags are
+  unchanged.
+- **`getCollisionCircleRectangle`** — rewritten to use the standard
+  closest-point-on-rect algorithm. Previously computed distance against an
+  out-of-rect anchor point, producing a wrong result whenever the circle
+  centre was inside the rectangle. Normal points from rect surface toward
+  circle; falls back to the smaller-exit axis when the circle centre is
+  inside the rect.
+- **`Ellipse.collidesWith`** — implements `Ellipse`-vs-`Rectangle` and
+  `Ellipse`-vs-`Circle` via the directional ellipse-boundary equation
+  `1 / sqrt((dx/rx)² + (dy/ry)²)`. Other targets (ellipse-vs-ellipse,
+  ellipse-vs-polygon, ellipse-vs-line) still return `null` —
+  `intersectsWith` remains the boolean fallback.
+- **`Line.collidesWith`** — kept returning `null` (lines have no
+  meaningful SAT response), but the JSDoc now states the contract
+  explicitly so callers don't expect a vector.
+
+`Rectangle.collidesWith` and `Circle.collidesWith` route ellipse targets to
+the new functions via the existing `swap` flag.
+
+### Fixed — Object-URL leak (re-emphasised; was 0.7.11 fix)
+
+The 0.7.11 fix for `MusicFactory` and `VideoFactory` URL revocation is
+unchanged in 0.7.12 — listing it here for completeness because the pre-1.0
+audit findings memory carries a forward reference to it.
+
+### Changed — Visibility / readonly tightening (potentially breaking)
+
+Pre-1.0 cleanups that narrow the public surface where callers could
+previously poke at internal state:
+
+- **`GamepadMapping.buttons` / `.axes`** typed `ReadonlyArray<GamepadControl>`
+  instead of `Array<GamepadControl>`. Internal `destroy()` retains the
+  `length = 0` clear via a local cast. **Breaking** for callers that were
+  pushing or splicing the arrays directly.
+- **`View.updateTransform()` / `.updateBounds()`** changed from `public` to
+  `protected`. They were never safe to call externally — invoking them
+  bypassed the dirty-flag clearing in `getTransform()` / `getBounds()` and
+  could cause redundant recalculation. **Breaking** if you relied on them.
+- **`IndexedDbDatabase.getObjectStore()`** changed from `public` to
+  `protected`. Only callers were the class's own `load`/`save`/`delete`
+  methods. **Breaking** if any subclass referenced it externally.
+- **`GamepadDefinitions.normalizeIds`** is no longer exported. It was an
+  in-file helper that leaked through the barrel. **Breaking** for any
+  caller importing it directly.
+- **`GamepadPromptLayouts.buildControlChannelMap()`** renamed to
+  `getControlChannelMap()` — the name now matches the behaviour (returns a
+  pre-built constant; never builds anything). **Breaking** rename.
+
+### Added — API surface
+
+Additive changes; not breaking:
+
+- `EqualizerFilter` now exposes runtime setters for `lowFrequency`,
+  `midFrequency`, and `highFrequency` (previously only construction-time).
+  Smooth ramp via `setTargetAtTime` to avoid clicks.
+- `Filter` (abstract base for post-process filters) now declares a
+  `destroy()` method with a no-op default. `BlurFilter` / `ColorFilter` /
+  `WebGl2ShaderFilter` / `WebGpuShaderFilter` mark their existing
+  implementations as `override`. Generic-filter consumers no longer need
+  a cast to release filters.
+- `getCollisionEllipseRectangle` and `getCollisionEllipseCircle` are
+  exported from the math barrel for direct use.
+
+### Changed — Internal cleanups
+
+Doc-only and signature-only refactors:
+
+- `Sprite._invalidateSubtreeTransform` / `._invalidateBoundsCascade` tagged
+  `@internal` (they are `public` only because of TS friend-class limits).
+- `_getDebugQuadtree` (InteractionManager) and `_walkBounds` (Quadtree)
+  tagged `@internal` to mark the friend-class link to the debug layer.
+- `PerformanceLayer` declares `viewMode` explicitly to match the other
+  debug layers.
+- `PointerStackLayer._buildLines` lost its two unused `_panelX` / `_panelY`
+  parameters. Internal-only; not user-visible.
+- `intersectionCirclePoly` got an inline comment explaining the
+  negated-frame coordinate transform.
+- `AudioAnalyserOptions` interface picked up per-field JSDoc with documented
+  defaults.
+- `SoundFactoryOptions.poolSize` JSDoc names the implicit `Sound` default (8).
+- `ChorusFilter` lost a redundant `as AudioParam` cast.
+- `Video.setupWithAudioContext` is now an arrow-bound field instead of a
+  context-bound method; cleaner internally, no API change.
+- `ShaderUniform.propName` uses `String.prototype.substring` instead of the
+  deprecated `substr`.
+- `Tween.repeat` JSDoc now ships an `@example` block clarifying that
+  `repeat(2)` runs the animation three times total.
+- `Line.collidesWith` documents the always-`null` behaviour as intentional.
+- `RenderTarget.addDestroyListener` / `.removeDestroyListener` got JSDoc
+  pointing out that `RenderTexture` (which extends `RenderTarget`) inherits
+  them; the audit finding that claimed otherwise was incorrect.
+
+## [0.7.11] - 2026-05-07
+
+Performance pass — adds a multi-domain benchmark suite, an auto-profiler
+that finds Top-3-Wins from baseline data, and three measured optimizations
+those benchmarks identified. Includes a breaking change to
+`InteractionManager` (the `useSpatialIndex` flag is removed; spatial
+indexing is now automatic and persistent).
+
+### Added — Performance infrastructure
+
+- **`test/perf/` benchmark suite** covering five domains: rendering,
+  audio, collision, scene-graph, interaction. Each domain has its own
+  script (`npm run perf:bench:rendering`, `:audio`, `:collision`,
+  `:scene-graph`, `:interaction`) plus `:all` aggregator. Output: JSON
+  + Markdown to `test/perf/results/`.
+- **Baseline snapshot** committed as `test/perf/results/baseline.md` —
+  reference numbers at 0.7.10 for future regression detection.
+- **Auto-profiler** (`npm run perf:profile`, `:gc` variant with
+  `--expose-gc`) that re-runs the hottest scenarios with granular
+  sub-timings, heap-delta tracking, and call counters. Writes
+  `test/perf/results/findings.md` with auto-derived Top-3 Wins
+  recommendations.
+- Profile helpers (`SubTimingTracker`, `CallCounter`, `MemoryTracker`)
+  in `test/perf/profile-runner.ts` for future ad-hoc profiling.
+
+### Performance — Win 1: `Polygon.getNormals()` cached
+
+Mirrors the 0.6.19 dirty-flag pattern from `Sprite.getNormals()` and the
+0.7.8 work on `Circle.getNormals()`. `Polygon.getNormals()` now caches
+the result and recomputes only when shape mutates. Returns the same
+array reference on subsequent calls. Eliminates per-call allocation of
+N `Vector` instances during SAT collision — significant for collision-
+heavy scenes. Cache invalidated on `setPoints`, `setPosition`, `set`,
+`copy`, and the `x` / `y` / `position` setters.
+
+The legacy `normals` getter is now `@deprecated` — call `getNormals()`
+directly. Behavior is identical; the getter just delegates.
+
+### Performance — Win 2: `Quadtree.queryPoint()` documented buffer reuse
+
+The `results?: Array<QuadtreeItem<T>>` parameter has been there since
+0.6.16 but was undocumented. JSDoc now explicitly documents the
+buffer-reuse pattern for zero-allocation hot-path queries. Added a
+`Quadtree.remove(item)` method (needed internally by Win 3); also
+publicly available for users who want to maintain quadtrees externally.
+
+### Performance — Win 3: Persistent Spatial-Index (BREAKING)
+
+`InteractionManager`'s spatial index now lives across frames and is
+incrementally maintained — replaces the per-frame full rebuild. This
+also makes the `useSpatialIndex` opt-in flag unnecessary and **the
+flag has been removed entirely**.
+
+**How it works now:**
+- A persistent quadtree is created lazily when the first interactive
+  node enters the scene.
+- `Container.addChild` / `removeChild` walk subtrees and add/remove
+  interactive descendants from the index.
+- `RenderNode.interactive = true/false` toggles registration.
+- Transform mutations on interactive nodes (position / rotation / scale)
+  mark the node as "stale" via `_invalidateBoundsCascade`.
+- Stale entries are lazy-updated at the start of `InteractionManager.update()`
+  on the next frame, before queries are dispatched.
+- When the last interactive node is removed, the quadtree is disposed
+  and lifecycle returns to zero overhead.
+
+**Practical effect:** scenes with many interactive nodes get the same
+~5× faster hit-testing the old `useSpatialIndex = true` provided, but
+without the per-frame rebuild cost. Mostly-static scenes (the common
+case) see particularly large wins — incremental updates only fire on
+actually-moved nodes.
+
+### Changed (BREAKING)
+
+- **`InteractionManager.useSpatialIndex` removed.** Spatial indexing is
+  now automatic. Code that explicitly set the flag (`= true` or
+  `= false`) gets a TypeScript error; the value should simply be
+  removed. Old `useSpatialIndex = true` users get the same speedup
+  automatically. Old `useSpatialIndex = false` users get a faster hit
+  path with negligible mutation overhead.
+- **`RenderNode.interactive` is now a getter/setter** (was a public
+  field). External behavior is identical for normal usage
+  (`node.interactive = true`). Any code that relied on the field's
+  shape (descriptor inspection, etc.) needs to adapt. Reading the value
+  is a getter call — same observable behavior.
+- The `HitTestLayer` debug overlay no longer requires
+  `useSpatialIndex = true` to draw quadtree quadrants; it draws them
+  whenever the persistent quadtree is non-null (i.e., whenever any
+  interactive node exists in the active scene).
+
+### Migration
+
+```ts
+// Before:
+app.interaction.useSpatialIndex = true;   // flag opt-in
+
+// After:
+// Nothing — index is automatic. Just have at least one interactive
+// node in the scene and queries use the persistent quadtree.
+```
+
+### Notes
+
+- This release adds 30 net new tests (Polygon-cache + persistent-index
+  lifecycle), removes a few `useSpatialIndex`-flag assertion tests, and
+  modifies `interaction.test.ts` `TestSprite` to expose `getBounds()`
+  for the persistent index. Test count: 1196 → 1212.
+- The benchmark suite and auto-profiler are dev infrastructure — they
+  live in `test/perf/` and are not shipped via npm (the `files` array
+  in package.json controls what's packed).
+- The findings.md committed alongside baseline.md is a snapshot of
+  performance characteristics at 0.7.11 baseline — re-running profiles
+  will overwrite locally but the committed reference remains for
+  diff comparisons.
+- Future perf passes can use the same auto-profiler tooling to identify
+  the next round of Wins. CI-integrated regression detection is a
+  future Phase 4 if there's demand.
+
+## [0.7.10] - 2026-05-07
+
+Closes the audio chapter. Adds the long-deferred fade transition helper,
+a procedural tone generator, and four custom-DSP filter classes that
+demonstrate the WorkletFilter foundation from 0.7.1. After this release,
+ExoJS audio is feature-complete for the originally-planned scope.
+
+### Added
+
+- **`crossFade(from, to, durationMs, options?): Promise<void>`** — top-
+  level helper that calls `from.fadeOut()` and `to.fadeIn()` in parallel,
+  optionally auto-playing `to` if paused. Resolves after `durationMs`
+  elapses. Replaces the manual `await` + dual-fade pattern documented in
+  0.6.20.
+- **`Envelope`** — ADSR (Attack-Decay-Sustain-Release) generator usable
+  on any `AudioParam`. Schedules a gain curve via `trigger()` (attack →
+  decay → sustain) and `release()` (sustain → 0). Independent of any
+  specific media class — apply to oscillators, filters, or custom
+  AudioParam targets.
+- **`OscillatorSound`** — procedural tone generator. No AudioBuffer
+  needed — each `play()` synthesizes via WebAudio's `OscillatorNode`.
+  Configurable `frequency`, `type` (`sine` | `square` | `sawtooth` |
+  `triangle`), `detune` (cents), optional `Envelope`. Pool semantics
+  match `Sound` (default `poolSize: 8`, `SoundPoolStrategy.FirstInFirstOut`).
+  Static helper `OscillatorSound.midiToFrequency(midiNote)` and
+  `setNote(midiNote)` for music apps. Default-routes to `mixer.sound`.
+- **`ChorusFilter`** — modulated-delay chorus / vibrato effect. Native
+  WebAudio nodes only (DelayNode + Oscillator LFO + GainNodes), no
+  worklet. Configurable `delayMs`, `depthMs`, `rateHz`, `wet`. Use as
+  an Audio bus filter:
+  ```ts
+  bus.addFilter(new ChorusFilter({ rateHz: 1.5, depthMs: 5 }));
+  ```
+- **`PitchShiftFilter`** — granular real-time pitch shifter (WorkletFilter).
+  Configurable `pitch` (0.25× to 4×), `wet`, internal `grainSize`. V1
+  quality is good for ±1 octave; beyond that, audible granular artifacts.
+  Higher-quality phase-vocoder pitch shifting is V2.
+- **`VocoderFilter`** — classic 16-band vocoder (WorkletFilter, 2-input).
+  Takes a `modulator: AudioBus` whose spectral envelope shapes the
+  carrier signal (the bus the filter is attached to). Configurable
+  `numBands`, `minHz`, `maxHz`, `bandQ`, `wet`, `envelopeSmoothing`.
+  Per-band biquad bandpass filters + envelope follower entirely in the
+  worklet for sample-accurate processing.
+- **`GranularFilter`** — granular synthesis effect. Slices recent input
+  audio into Hann-windowed grains and replays them with randomized
+  offset and pitch. Configurable `grainSize`, `density`, `spread`,
+  `pitchMin`, `pitchMax`, `wet`. Suitable for ambient textures, glitch
+  effects, time-stretching, pitch clouds.
+
+### Notes
+
+- `OscillatorSound` does NOT support spatial audio in V1 (no
+  `position` / `velocity` properties). For spatial procedural audio,
+  attach the OscillatorSound to a spatial `Sound` bus or wait for a
+  future enhancement. `Sound`'s spatial path covers AudioBuffer-based
+  sources.
+- All four custom-DSP filters extend the `WorkletFilter` base from
+  0.7.1, except `ChorusFilter` which uses native nodes (sufficient for
+  modulated-delay topology).
+- The audio chapter as originally scoped is now closed:
+  - 0.7.0 — AudioMixer + Buses + Filters + Spatial + Pool
+  - 0.7.1 — AudioWorklet foundation + DuckingFilter migration
+  - 0.7.2 — BeatDetector (Stage 1+2) + AudioAnalyser rewrite
+  - 0.7.7 — 3/4 time-signature detection + AudioListener bugfix
+  - 0.7.10 — crossFade + OscillatorSound + Envelope + 4 custom-DSP
+    filters (Chorus, PitchShift, Vocoder, Granular)
+- Items deferred indefinitely: HRTF binaural panning, ambisonic /
+  surround output, MIDI playback, voice chat, ASR/TTS, format
+  conversion, audio editor / waveform UI, custom-loudness
+  normalization. These remain out-of-scope per the original audio
+  modernization roadmap.
+
+## [0.7.9] - 2026-05-07
+
+Fixes a GLSL compile-error in the 0.7.8 shader auto-upgrade path.
+
+### Fixed
+
+- **`upgradeFragmentShaderToGl300()` now always prepends `precision highp
+  float;`** before the `out vec4 fragColor;` declaration. Previously, if
+  the user's source already contained a precision declaration anywhere
+  (e.g., `precision lowp float;` mid-source), the upgrader skipped its
+  own injection — but the user's declaration came AFTER the
+  `out vec4 fragColor;` line, which itself uses a float-typed variable.
+  GLSL ES 3.00 requires precision to be declared before any float-typed
+  declaration, so the compiler rejected the output with
+  `0:2: '' : No precision specified for (float).`
+
+  Multiple precision declarations are legal in GLSL ES 3.00 with
+  last-precision-wins semantics. The fix always injects `precision highp
+  float;` at line 2 (before `out vec4 fragColor;`); the user's own
+  precision declaration further down still applies to their code via
+  the standard last-precision-wins rule. No semantic change for
+  user-provided shader logic; previously-broken shaders with custom
+  precision declarations now compile correctly.
+
+## [0.7.8] - 2026-05-04
+
+GLSL 1.00 → 3.00 auto-upgrade for `WebGl2ShaderFilter` (Shadertoy/ISF
+shaders work out of the box) plus a code-hygiene pass — `Circle.getNormals()`
+now caches via dirty-flag (matching 0.6.19's Sprite pattern), Rectangle-vs-
+Rectangle collision response now reports correct `overlap` value, and the
+`destroy()` audit cleans up TODO comments across 8 value classes (with
+real cleanup logic added to `ObservableVector` and `Circle` where needed).
+
+### Added
+
+- **`upgradeFragmentShaderToGl300(source)`** — exported utility function.
+  Upgrades GLSL ES 1.00 fragment shader source to 3.00 with documented
+  transformations (adds `#version 300 es`, `precision highp float`,
+  `out vec4 fragColor`, replaces `gl_FragColor` / `texture2D(` /
+  `textureCube(` / `texture2DProj(` / `varying`). Idempotent: 3.00
+  source returns unchanged. Edge cases not handled (`gl_FragData[N]`,
+  `textureLod` variants, etc.) produce GLSL compile errors that the
+  user must port manually.
+- **`WebGl2ShaderFilterOptions.autoUpgrade: boolean`** (default `true`)
+  — when enabled, the constructor passes the user's `fragmentSource`
+  through `upgradeFragmentShaderToGl300()` before storing. Set to
+  `false` for strict 3.00 input (legacy code becomes a compile error
+  — useful for CI / linting setups that want to catch legacy shaders
+  as bugs). Vertex shader source is never auto-upgraded; legacy
+  vertex sources must be ported manually.
+
+### Performance
+
+- **`Circle.getNormals()` cached via dirty flag** (matching the 0.6.19
+  pattern for `Sprite.getNormals()`). Returns a stable array of `Vector`
+  references on subsequent calls; recomputes only when radius / position
+  / x / y change. Reduces GC pressure in collision-detection hot paths
+  (especially SAT polygon-vs-circle).
+- **`Circle.getCollisionVertices()` invalidation bug fixed.** The
+  cache existed since the initial commit but was never invalidated on
+  position / radius changes — moving a Circle after first collision
+  check returned stale vertex positions. Now invalidates correctly via
+  `_verticesDirty` flag.
+
+### Fixed
+
+- **`getCollisionRectangleRectangle.overlap`** now returns the correct
+  minimum axis overlap (`min(overlapX, overlapY)`) instead of hardcoded
+  `0`. Required for any collision-response logic that pushes shapes
+  apart by their overlap distance. Other collision shapes (Circle-vs-
+  Circle, Circle-vs-Rectangle, polygon-via-SAT) already computed this
+  correctly.
+
+### Changed
+
+- **`destroy()` audit complete** across 8 value classes:
+  - `Vector`, `Size`, `Interval`, `Random`, `Time`, `TorqueAffector`
+    — kept as no-op; `// todo` comments replaced with explanatory
+    "no-op — pure value class, kept for `Destroyable` interface
+    conformance" comments.
+  - `ObservableVector` — `destroy()` now nulls the change callback
+    to prevent leaks if the instance is held in external scope.
+    Field type widened to `(() => void) | null`; all internal call
+    sites already used optional-chaining, so no functional change for
+    live instances.
+  - `Circle` — `destroy()` now destroys all cached `Vector` instances
+    in `_collisionVertices` and `_normals` arrays (added in this
+    release).
+
+### Notes
+
+- The autoUpgrade default is `true` so Shadertoy/ISF/legacy shaders
+  work without any flag. Strict-3.00 codebases can opt out per filter.
+- Removed the private `Circle.getCollisionVertex` helper — its logic
+  was inlined into `getCollisionVertices` for the cache-reuse pattern.
+  Internal change, no external impact.
+
+## [0.7.7] - 2026-05-04
+
+Critical bugfix in `AudioListener` and adds 3/4 time-signature detection
+to `BeatDetector`.
+
+### Fixed
+
+- **`AudioListener._tick()` no longer crashes in real browsers.** The
+  WebAudio `AudioListener` interface does not expose a `.context`
+  property — that's an undocumented quirk that does not exist in any
+  spec-compliant browser. The previous `_tick()` implementation read
+  `_audioListener.context.currentTime`, which crashed
+  deterministically on the first frame after audio-context unlock.
+  Tests passed because the jsdom mock incorrectly defined a `.context`
+  property; that has been removed from the mock as well.
+
+  **Severity**: production-critical. The bug fired in every ExoJS app
+  that triggered `getAudioContext()` (i.e. any app using `Sound`,
+  `Music`, `BeatDetector`, `AudioAnalyser`, or `Video` audio), because
+  `AudioMixer.update()` ticks the listener every frame regardless of
+  whether the user explicitly set `listener.target`.
+
+  **Fix**: `AudioListener` now stores its `AudioContext` reference in
+  a private `_ctx` field at setup time and reads `_ctx.currentTime`
+  instead. Mirrors the pattern used elsewhere in the audio stack.
+
+### Added
+
+- **3/4 time-signature detection in `BeatDetector`** — the worklet
+  now tracks parallel posteriors over 4-beat and 3-beat bar
+  structures. Active time signature is selected via hysteresis:
+  - **EMA confidences** (smoothing α=0.1) for each candidate
+  - **Sustain-margin guard**: switching requires the alternate TS's
+    confidence to exceed the active by 1.4× for ~12-16 consecutive
+    beats. Bridges and breakdowns don't trigger spurious switches.
+  - **Settling**: first 8 beats stay 4/4 regardless of evidence
+- **`BeatDetectorOptions.enableTimeSignatureDetection: boolean`**
+  (default `true`) — set to `false` to lock detection to 4/4.
+- **`BeatDetector.timeSignature`** stops being hardcoded to
+  `{numerator: 4, denominator: 4}` — now reflects the active
+  detected TS. Public API unchanged.
+- **`BeatDetector.barLength` and `barPosition`** dynamically reflect
+  the active TS (3 vs 4 positions). The `lookahead` array marks
+  downbeats based on the active bar length.
+
+### Notes
+
+- 6/8, 5/4, 7/8 and other odd time signatures are not detected.
+  Default-fallback is 4/4 in all ambiguous cases.
+- 3/4 detection works best on stable, percussive 3/4 material
+  (waltz-feel music). Performance on Jazz / Rubato / Free-form
+  remains weak — consistent with Stage 1+2 limitations from 0.7.2.
+- The mock-cleanup means existing test fixtures that relied on
+  `audioContext.listener.context` had to be updated; the production
+  path no longer reads that property at all.
+
+## [0.7.6] - 2026-05-04
+
+Closes the remaining WebGPU / WebGL2 backend parity gaps and cleans up
+vestigial backend API. Adds device-loss / context-loss recovery signals
+on both backends, unifies them under `Application.onBackendLost`, moves
+`setCursor` to Application, and removes dead-code throws from WebGPU.
+
+### Added
+
+- **`Application.onBackendLost: Signal<[]>`** — unified signal that
+  fires when either backend's GPU context is lost (WebGl2 context-lost
+  event or WebGpu device-lost promise). User code listens once and
+  doesn't care which backend they're on. Useful for showing a "GPU
+  driver issue, please reload" dialog.
+- **`WebGl2Backend.onContextLost: Signal<[]>`** — backend-specific
+  signal mirroring the existing `webglcontextlost` handler.
+- **`WebGl2Backend.onContextRestored: Signal<[]>`** — backend-specific
+  signal mirroring the existing `webglcontextrestored` handler.
+- **`WebGpuBackend.onDeviceLost: Signal<[GPUDeviceLostInfo]>`** —
+  WebGPU's `device.lost` promise is now subscribed at initialization;
+  resolution dispatches this signal with the loss info. Note: WebGPU
+  device loss is irrecoverable on the same device — user code must
+  reload, retry, or recreate the application to recover. V1 only
+  signals; user decides response strategy.
+- **`WebGpuBackend.deviceLost: boolean`** — getter for current
+  device-loss state.
+- **`WebGpuBackend.clearColor: Color`** + **`setClearColor(color)`** —
+  persistent clear color, matching WebGl2's API. `clear()` without
+  arguments uses the persistent color.
+- **`Application.setCursor(cursor)`** + **`cursor` property** — moved
+  here from `WebGl2Backend`. Accepts CSS cursor strings or a
+  `Texture` / `HTMLImageElement` / `HTMLCanvasElement` (converted to
+  a `url(...)` cursor). Sets `canvas.style.cursor` directly.
+
+### Changed (BREAKING)
+
+- **`WebGl2Backend.setCursor()` and `cursor` getter removed.** Use
+  `app.setCursor(...)` or `app.cursor = ...` instead. Cursor is a DOM
+  concern, not a backend concern; this corrects the misplacement.
+- **`WebGpuBackend.setShader()` removed.** Was a vestigial throw with
+  no callers. WebGPU's pipeline-based architecture doesn't fit the
+  imperative `setShader` pattern. Custom shaders go through
+  `WebGpuShaderFilter` (since 0.7.4).
+- **`WebGpuBackend.setVao()` removed.** VAOs are a WebGL concept;
+  WebGPU uses bind groups + pipelines. Method had no callers.
+- **`WebGpuBackend.setTexture()` and `setRenderTarget()` no-longer-
+  throwing on RenderTarget subclass guards.** Throws were unreachable
+  because `RenderTexture` is the only `RenderTarget` subclass. The
+  guards are gone; the type system already prevents misuse.
+- **`WebGpuBackend.setBlendMode()` no-longer-throwing**. Internal
+  renderers call this during their pipeline setup; the previous throw
+  for unrecognized modes was unreachable (covered all 5 valid blend
+  modes). Method now silently returns; the actual blend logic lives in
+  the pipeline-creation paths inside `WebGpuBlendState` and the
+  individual renderers.
+
+### Migration
+
+```ts
+// Before:
+app.backend.setCursor('pointer');
+const cursor = app.backend.cursor;
+
+// After:
+app.setCursor('pointer');           // or
+app.cursor = 'pointer';
+const cursor = app.cursor;
+```
+
+```ts
+// New: react to backend loss
+app.onBackendLost.add(() => {
+    showReloadDialog();
+});
+
+// Or backend-specific:
+if (app.backend.backendType === RenderBackendType.WebGpu) {
+    (app.backend as WebGpuBackend).onDeviceLost.add((info) => {
+        console.error('GPU device lost:', info.message, info.reason);
+    });
+}
+```
+
+### Notes
+
+- Device-loss is irrecoverable on WebGPU (the lost device cannot be
+  reused; recovery requires creating a fresh device, which means
+  re-initializing the application). V1 dispatches the signal and stops;
+  the user's app code decides whether to reload, retry, or fall back.
+- `setBlendMode` could be removed entirely in a future cleanup if the
+  pipeline-creation path is the only place blend state is set, but it
+  remains as a no-op for now to preserve internal call sites.
+
+## [0.7.5] - 2026-05-04
+
+Expands the debug overlay with three new layers: `BoundingBoxesLayer`,
+`HitTestLayer`, and `PointerStackLayer`. Adds a master visibility switch
+on `DebugOverlay`. Layers can now opt into world-space rendering for
+overlays that need to align with scene content. F2 / F3 / F4 keys are
+hardcoded to toggle the new layers (matching the existing F1 for
+Performance).
+
+### Added
+
+- **`BoundingBoxesLayer`** — renders AABB outlines for every visible
+  RenderNode in the active scene. Color cycles through HSL hue based
+  on `zIndex` (`hue = (zIndex * 30) % 360`), so layered nodes are
+  visually distinct. Toggle via F2 or
+  `debug.layers.boundingBoxes.visible = true`.
+- **`HitTestLayer`** — outlines for `interactive` nodes only, with
+  state-based colors:
+  - **Magenta** (idle interactive)
+  - **Yellow** (currently hovered, via `app.interaction.getHoveredNode()`)
+  - **Cyan** (captured by an active drag, via the new
+    `getCapturedNodes()` accessor)
+  - When `useSpatialIndex` is enabled on InteractionManager,
+    additionally draws faint quadtree quadrant outlines.
+  - Toggle via F3.
+- **`PointerStackLayer`** — fixed top-right text panel listing all
+  RenderNodes in the active scene whose `contains(worldX, worldY)`
+  matches the primary pointer position. Sorted by `zIndex`
+  descending (top of stack first). Limited to 10 entries to avoid
+  overflow. Useful for debugging "why isn't this clickable" — see
+  exactly what's stacked under the cursor. Toggle via F4.
+- **`DebugOverlay.visible: boolean`** (default `true`) — master gate
+  that suppresses all layer rendering when `false` while preserving
+  individual layer states. Restoring `debug.visible = true` brings
+  layers back without rewiring.
+- **`DebugLayer.viewMode: 'screen' | 'world'`** — abstract getter
+  (default `'screen'`); subclasses override. The DebugOverlay groups
+  layers by viewMode and swaps `backend.view` accordingly: world-mode
+  layers render in the active scene's view (matching scene
+  coordinates), screen-mode layers render in canvas-pixel space.
+- **`InteractionManager.getCapturedNodes(): ReadonlyArray<RenderNode>`** —
+  returns the nodes currently captured by active drags. Used by
+  HitTestLayer; also generally useful.
+- **`InputManager.getPrimaryPointerPosition()`** — returns the canvas-
+  pixel position of the primary pointer (or null if none active).
+
+### Notes
+
+- F2 / F3 / F4 are hardcoded for V1 (matching F1 from 0.6.17). A
+  `keybindings: false` opt-out comes when there's concrete demand.
+- BoundingBoxes color cycle is intentionally simple (`hue = z * 30 % 360`).
+  Adapts to any z range without per-frame normalization. If two nodes
+  share zIndex, they share color — that's fine, the layer's purpose is
+  visualizing depth differences.
+- World-mode layers (BoundingBoxes, HitTest) render BEFORE screen-mode
+  layers (Performance, PointerStack) in each frame, so text panels
+  appear on top of outlines.
+
+## [0.7.4] - 2026-05-04
+
+Renames `ShaderFilter` → `WebGl2ShaderFilter` and adds `WebGpuShaderFilter`
+— full backend-specific custom shader support. Custom post-process
+shaders now work on both WebGL2 (GLSL) and WebGPU (WGSL) backends with
+explicit, type-safe class names matching the rest of the codebase
+(WebGl2Backend / WebGpuBackend, WebGl2SpriteRenderer / WebGpuSpriteRenderer,
+etc.).
+
+### Added
+
+- **`WebGpuShaderFilter`** — full WGSL fragment shader support on the
+  WebGPU backend. API mirrors `WebGl2ShaderFilter` — accepts WGSL source,
+  exposes a mutable `uniforms` map, applies as a post-process Filter via
+  `node.filters = [filter]`. Internally creates GPUShaderModules,
+  bind-group layouts, render pipeline, and fullscreen-quad vertex buffer
+  using the same patterns as `WebGpuMaskCompositor`.
+- **WGSL auto-bindings** in `@group(0)`:
+  - `@binding(0) var<uniform> uResolution: vec2<f32>` — output dimensions
+  - `@binding(1) var uTexture: texture_2d<f32>` — input texture
+  - `@binding(2) var uSampler: sampler` — linear sampler
+- **User uniforms** in `@group(1)` — packed into a uniform buffer with
+  16-byte alignment per slot (per WGSL alignment rules; vec3 is 16-byte
+  aligned, not 12). Texture uniforms get separate bind group entries.
+- **WGSL default vertex shader** when omitted — fullscreen pass-through
+  with a `vUv: vec2<f32>` varying.
+
+### Changed (BREAKING)
+
+- **`ShaderFilter` → `WebGl2ShaderFilter`** — the class was always
+  WebGL2-only; the name now reflects that. Same API otherwise.
+- **`ShaderFilterOptions` → `WebGl2ShaderFilterOptions`**.
+- **`wgsl` option removed from `WebGl2ShaderFilterOptions`** — was
+  reserved API surface for future WGSL support, now superseded by the
+  separate `WebGpuShaderFilter`.
+- **Backend guard messages updated**:
+  - `WebGl2ShaderFilter` on WebGPU: `'WebGl2ShaderFilter requires the
+    WebGL2 backend. Use WebGpuShaderFilter on WebGPU.'`
+  - `WebGpuShaderFilter` on WebGL2: `'WebGpuShaderFilter requires the
+    WebGPU backend. Use WebGl2ShaderFilter on WebGL2.'`
+
+`ShaderFilterUniformValue` (the polymorphic uniform value type) is
+**unchanged** and shared between both backends — same value shapes
+(number / tuples / TypedArrays / Texture).
+
+### Migration
+
+```ts
+// Before (0.7.3):
+import { ShaderFilter } from '@codexo/exojs';
+const filter = new ShaderFilter({ fragmentSource: glsl, uniforms: { ... } });
+
+// After (0.7.4):
+import { WebGl2ShaderFilter } from '@codexo/exojs';
+const filter = new WebGl2ShaderFilter({ fragmentSource: glsl, uniforms: { ... } });
+
+// New on WebGPU:
+import { WebGpuShaderFilter } from '@codexo/exojs';
+const filter = new WebGpuShaderFilter({ fragmentSource: wgsl, uniforms: { ... } });
+```
+
+### Notes
+
+- Two separate classes (rather than one polymorphic class with both
+  shader sources) reflects the reality that GLSL and WGSL are entirely
+  different languages with different binding models. Users writing a
+  custom shader inherently know their backend; the explicit class name
+  matches that mental model.
+- 0.7.3 is effectively replaced — it shipped with the wrong name and a
+  WebGPU stub. Window of exposure was minutes; this is corrective.
+- WGSL alignment rules differ from GLSL std140: vec3 occupies 16 bytes
+  (not 12). The user's WGSL struct must declare members accordingly.
+- Performance for fullscreen pixel-shader rendering is equivalent on
+  both backends — choose based on browser support, ecosystem
+  familiarity (GLSL has more tutorials / Shadertoy), or future-proofing
+  preference (WebGPU is the long-term direction).
+
+## [0.7.3] - 2026-05-04
+
+Adds `ShaderFilter` — a high-level Filter subclass that renders the input
+through a user-provided GLSL fragment shader. Unlocks custom post-process
+effects: visualizers, demoscene shaders, glitch/scanline/dithering passes,
+LUT color grading, chromatic aberration, etc.
+
+### Added
+
+- **`ShaderFilter`** — accepts a fragment shader source string + uniforms,
+  applies it as a post-process filter on any `RenderNode` via
+  `node.filters = [shaderFilter]`. Internally lazy-compiles the shader on
+  first apply, allocates a per-instance fullscreen-quad vertex buffer,
+  and uses the existing `RenderTargetPass` orchestration shared with
+  built-in filters like `BlurFilter`.
+- **Auto-bound uniforms** for the user shader:
+  - `uniform sampler2D uTexture` — the filter's input
+  - `uniform vec2 uResolution` — output dimensions
+  - `in vec2 vUv` (varying) — 0..1 UVs across the quad
+- **`ShaderFilter.uniforms`** — mutable map for user uniforms. Set values
+  via property assignment; flushed before each apply():
+  ```ts
+  filter.uniforms.uTime = performance.now() / 1000;
+  filter.uniforms.uColor = [1, 0.5, 0, 1];      // vec4
+  ```
+- **Polymorphic uniform values**: scalar `number`, tuple `[a, b]` /
+  `[a, b, c]` / `[a, b, c, d]`, `Float32Array` / `Int32Array`, or
+  `Texture` / `RenderTexture` (auto-bound to a sampler slot).
+- **Default vertex shader** when `vertexSource` is omitted — pass-through
+  fullscreen quad. User can supply a custom vertex shader for warps /
+  vertex displacement effects.
+- **`wgsl` option** in `ShaderFilterOptions` — reserved API surface for
+  WebGPU support landing in a future release.
+
+### Notes
+
+- **WebGL2-only in V1.** Constructor accepts `wgsl` source, but `apply()`
+  on the WebGPU backend throws `'ShaderFilter does not yet support the
+  WebGPU backend. WGSL support is planned for a future release. Use the
+  WebGL2 backend for now.'` Document this limitation; reasoning: WebGPU
+  requires a separate WGSL pipeline implementation that's substantial
+  on its own. Coming when there's concrete user demand.
+- `fragmentSource` is required at construction. Constructor throws if
+  missing.
+- Internally reuses the existing `Shader` + `WebGl2ShaderProgram`
+  infrastructure — no new public Backend methods added.
+- Vertex buffer is per-instance (4 vertices × 16 bytes = 64 bytes per
+  filter). Pooling across instances was considered but rejected for V1
+  to avoid cross-instance lifecycle coupling.
+
+### Usage
+
+```ts
+import { ShaderFilter } from '@codexo/exojs';
+
+const filter = new ShaderFilter({
+    fragmentSource: `#version 300 es
+        precision highp float;
+        in vec2 vUv;
+        uniform sampler2D uTexture;
+        uniform vec2 uResolution;
+        uniform float uTime;
+        out vec4 outColor;
+        void main() {
+            vec2 uv = vUv;
+            uv.x += sin(uv.y * 10.0 + uTime) * 0.01;  // wavy distort
+            outColor = texture(uTexture, uv);
+        }
+    `,
+    uniforms: {
+        uTime: 0,
+    },
+});
+
+sprite.filters = [filter];
+
+app.onFrame.add((delta) => {
+    filter.uniforms.uTime = performance.now() / 1000;
+});
+```
+
+## [0.7.2] - 2026-05-04
+
+Adds `BeatDetector` (Stage 1+2: causal DSP hybrid tracker with bar-aware
+state model) and rewrites `AudioAnalyser` with a polymorphic source
+setter and convenience helpers. **Breaking change** to AudioAnalyser
+API — see migration below. Pure-additive on BeatDetector.
+
+### Added
+
+- **`BeatDetector`** — Stage 1+2 beat tracker via AudioWorkletNode.
+  Causal DSP pipeline: log-mel spectral flux → 6-second sliding
+  tempogram → top-K tempo candidates with octave-error hysteresis →
+  phase tracker with novelty-snap correction → HMM-lite bar-position
+  posterior. ~500 LOC of inlined worklet source, all in plain JS, no
+  dependencies. Polymorphic `source` setter accepts `AudioBus`,
+  `Sound`, `Music`, `MediaStream`, raw `AudioNode`, or `null`.
+- **BeatDetector live state**:
+  - Stage 1: `tempo`, `beatPhase`, `nextBeatTime`, `confidence`,
+    `gridStability`, `tempoCandidates`, `rms`, `onsetStrength`,
+    `bandEnergy`
+  - Stage 2: `barPosition` (1..N within bar), `barLength`,
+    `timeSignature` (currently always 4/4 in V1), `nextDownbeatTime`,
+    `lookahead` (next 8 beats projected with audio-time precision)
+- **BeatDetector signals**:
+  - Stage 1: `onBeat`, `onTempoChange`
+  - Stage 2: `onDownbeat` (the "1" of each bar), `onBarStart`,
+    `onBeatPredicted` (when lookahead updates)
+- **`BeatDetectorOptions`** — `minBpm` (default 50), `maxBpm` (default
+  250), `fftSize` (default 2048), `hopSize` (default 512),
+  `tempoWindowSec` (default 6), `settlingMs` (default 1500), `melBands`
+  (default 24).
+- **Settling period** — first `settlingMs` ms after worklet starts,
+  beats are suppressed and `confidence` is `0`. Prevents spurious early
+  beat firings before the tempogram has stabilized.
+- **Anti-half/double-tempo hysteresis** — top-K candidates retain
+  octave-related tempos; switch only with 1.5× score margin to resist
+  the classic 60↔120↔240 BPM flipping.
+- **DSP utilities** in `@/audio/dsp` — pure-function exports for
+  `fft`, `mel`, `tempogram`. Used internally by the worklet (inlined
+  as JS strings) but also testable in isolation. Also usable directly
+  by advanced users for custom analysis.
+- **`AudioAnalyser` rewrite** — polymorphic `source` setter (same 5
+  source types as BeatDetector). Lazy-init pattern (works before
+  AudioContext is unlocked).
+- **`AudioAnalyser` data getters**: `getSpectrum(into?)`,
+  `getSpectrumFloat(into?)`, `getWaveform(into?)`,
+  `getWaveformFloat(into?)` — all support a user-provided buffer for
+  zero-allocation reads.
+- **`AudioAnalyser` convenience**: `getBandEnergy(fromHz, toHz)`,
+  `getLowMidHigh()`, `getRms()` — high-level helpers for visualizers
+  and reactive UI.
+
+### Changed (BREAKING)
+
+- **`AudioAnalyser` constructor signature changed.** Old:
+  `new AudioAnalyser(media, options)`. New:
+  `new AudioAnalyser(options?); analyser.source = media`.
+- **`AudioAnalyser` data properties replaced with methods.** Old
+  getters `timeDomainData`, `frequencyData`, `preciseTimeDomainData`,
+  `preciseFrequencyData` are removed. Use `getWaveform()`,
+  `getSpectrum()`, `getWaveformFloat()`, `getSpectrumFloat()`
+  respectively. The new methods accept an optional `into` buffer
+  argument for zero-allocation reuse.
+- **`AudioAnalyser.connect()` removed.** Connection is now automatic
+  on `source` assignment.
+
+### Migration
+
+```ts
+// Before:
+const analyser = new AudioAnalyser(music, { fftSize: 1024 });
+analyser.connect();
+const spectrum = analyser.frequencyData;
+const waveform = analyser.timeDomainData;
+
+// After:
+const analyser = new AudioAnalyser({ fftSize: 1024 });
+analyser.source = music;
+const spectrum = analyser.getSpectrum();
+const waveform = analyser.getWaveform();
+
+// Now also possible:
+analyser.source = mediaStream;     // Mic input
+analyser.source = app.audio.master; // Whole mix
+analyser.getBandEnergy(20, 200);   // Bass energy 0..1
+analyser.getLowMidHigh();          // {low, mid, high}
+```
+
+```ts
+// New: BeatDetector
+const detector = new BeatDetector();
+detector.source = music;
+await detector.ready;
+
+detector.onBeat.add(({ audioTime, tempo, isDownbeat, energy }) => {
+    sprite.scale.set(1.5);
+    new Tween().target(sprite.scale).to({x: 1, y: 1}).duration(200).start();
+});
+
+detector.onDownbeat.add(() => {
+    boss.attack();  // syncs exactly to "the 1" of each bar
+});
+```
+
+### Notes
+
+- BeatDetector is calibrated for percussive, metrically stable music
+  (Pop, EDM, Dance, Hip-Hop). Expect ~85-92% beat F1 in that range.
+  Performance on Jazz, Classical, and Ambient is weaker (50-65%) —
+  Stage 3 (CRNN-based activations) would address that and is deferred.
+- Time-signature detection is hardcoded to 4/4 in V1. Bar-position
+  tracking still works (HMM-lite over 4 beats); 3/4 detection comes
+  later if needed.
+- Lookahead returns 8 beats projected at current tempo. Game-event
+  scheduling can use `audioContext.currentTime` differences for
+  sample-accurate alignment.
+- The DSP runs entirely in the audio thread via AudioWorklet — no
+  main-thread CPU pressure, no jitter from GC or task scheduling. The
+  worklet source is embedded as a JS string in BeatDetector.ts (no
+  separate asset shipped).
+
+## [0.7.1] - 2026-05-04
+
+Adds an AudioWorklet foundation and migrates `DuckingFilter` from
+CPU-thread `setInterval(60Hz)` polling to sample-accurate audio-thread
+DSP. Establishes the architecture for future custom-DSP filters
+(Chorus, Pitch-Shift, Vocoder, etc.) without shipping any new effect
+filters in this release.
+
+### Added
+
+- **`registerWorkletProcessor(audioContext, name, source)`** — Blob-URL
+  based helper for registering AudioWorkletProcessors at runtime from a
+  source string. No build-tooling changes required: worklet code lives
+  as a JavaScript string inside the TypeScript file, gets converted to
+  a Blob URL on first registration, and is cached per-AudioContext.
+  Concurrent registrations are deduplicated via shared in-flight
+  Promises.
+- **`WorkletFilter`** — abstract base class extending `AudioFilter` for
+  filters implemented as AudioWorklet processors. Subclasses declare
+  `_workletName`, `_workletSource`, and (optionally) `_workletOptions`
+  / `_onWorkletReady`. The base handles:
+  - Async worklet loading lifecycle
+  - Stable `inputNode` / `outputNode` GainNodes that exist immediately
+    (audio passes through directly while the worklet loads, then
+    re-routes through the worklet once ready — no destruction or
+    re-wiring on the bus side)
+  - `_setAudioParam(name, value)` helper for smooth parameter updates
+  - Safe destruction during async load
+- **`AudioFilter.ready: Promise<void>`** — resolves when the filter is
+  fully initialized. Sync filters (BiquadFilter-backed, etc.) return
+  an already-resolved Promise. Async filters (WorkletFilter
+  subclasses) return a Promise that resolves once the worklet has
+  loaded. Useful when user code wants to `await` a parameter setup
+  that depends on the underlying node existing.
+
+### Changed
+
+- **`DuckingFilter` is now AudioWorklet-backed.** The setInterval-based
+  envelope follower has been replaced with a sample-accurate worklet
+  processor. Public API is unchanged: same constructor options
+  (`sidechain`, `threshold`, `ratio`, `attackMs`, `releaseMs`), same
+  property setters. Behaviorally:
+  - Detection runs at full sample-rate (typically 48 kHz) instead of
+    60 Hz polling
+  - Audio-thread isolated — no jitter from main-thread garbage
+    collection or task pressure
+  - Functions correctly when the page tab is inactive (audio thread
+    keeps running while CPU thread is throttled)
+  - Initial use has a one-time ~10–50 ms async load cost as the
+    worklet code registers; during that window the filter passes
+    audio through unmodified
+
+### Notes
+
+- AudioWorklet is supported in all browsers since 2020 (Chrome 66+,
+  Firefox 76+, Safari 14.1+). No fallback to the old setInterval
+  approach — environments without worklet support will throw on
+  DuckingFilter construction.
+- The shared infrastructure (`registerWorkletProcessor` +
+  `WorkletFilter`) is the foundation for future custom-DSP filters.
+  Concrete filter additions (Chorus, Pitch-Shift, Vocoder, Granular,
+  etc.) come in subsequent releases.
+- BeatDetector / AudioAnalyser hook revamp is deferred — that's the
+  next focused topic.
+
+## [0.7.0] - 2026-05-04
+
+Audio modernization. Introduces a routing manager with hierarchical buses,
+a filter API consistent with the rendering side, 2D spatial audio, and
+unifies `Sound.play()` into a multi-instance default. Pure-additive on
+the bus / filter / spatial side; the `Sound.play()` semantics are a
+breaking change.
+
+### Added
+
+- **`AudioManager`** — routing mixer accessible via `app.audio` (lazy
+  module-level singleton, also reachable via `getAudioManager()`).
+  Built-in buses `master`, `music`, `sound` with hierarchy
+  (`music` and `sound` are children of `master`).
+- **`AudioBus`** — class with `name` (positional constructor arg),
+  `parent`, `volume`, `muted`, `pan`, `addFilter`, `removeFilter`,
+  `fadeIn`, `fadeOut`, `destroy`. Internal node chain is
+  `inputNode → [filters...] → panNode → outputNode → parent.input`.
+- **Mixer API**: `app.audio.registerBus(bus)`, `getBus(name)`,
+  `hasBus(name)`, `unregisterBus(bus)`. Built-ins cannot be
+  unregistered.
+- **Default routing**: `Sound` → `app.audio.sound`, `Music` →
+  `app.audio.music`, `Video` → `app.audio.master`. Override by
+  setting `media.bus = customBus`.
+- **`AudioManager.muteOnHidden: boolean`** — when true, master is
+  muted while `document.visibilityState !== 'visible'`. Wired
+  through the `app.onVisibilityChange` signal added in 0.6.20.
+- **`AudioFilter`** — abstract base with `inputNode`, `outputNode`,
+  `destroy()`. Buses chain filter `inputNode → outputNode` in the
+  order they were added.
+- **Filter implementations**: `LowpassFilter`, `HighpassFilter`,
+  `CompressorFilter`, `DelayFilter`, `ReverbFilter` (algorithmic
+  impulse-response, no IR assets shipped), `EqualizerFilter`
+  (3-band low-shelf / peaking / high-shelf), `DuckingFilter`
+  (sidechain-driven gain reduction via `AnalyserNode` polled at
+  ~60 Hz; takes a `sidechain: AudioBus` option).
+- **`AudioListener`** — accessible at `app.audio.listener`. Has
+  `position: Vector`, `velocity: Vector`, and a polymorphic
+  `target: SceneNode | View | { x, y } | null` that auto-feeds
+  the WebAudio listener position each frame.
+- **`Sound.position: Vector | null`** — when non-null, the sound
+  becomes spatial: routes through a `PannerNode`
+  (`panningModel: 'equalpower'`, `distanceModel: 'linear'`) and
+  ticks per-frame from `AudioManager.update()`. Setting back to null
+  tears down the panner and restores non-spatial routing.
+- **`Sound.velocity: Vector | null`** — tracked for future Doppler
+  use (modern WebAudio infers Doppler implicitly from positional
+  change between frames; we don't pipe velocity to the panner
+  directly).
+- **`SoundPoolStrategy` enum** — `FirstInFirstOut`,
+  `LeastRecentlyUsed`, `LowestPriority`. Selects the eviction
+  policy when pool capacity is reached.
+- **`Sound.priority: number`** — used by the `LowestPriority`
+  strategy. Default 0.
+- **`AudioManager.update()`** — public per-frame tick called from
+  `Application.update()` between `interaction.update()` and
+  `tweens.update()`. Updates listener position from target,
+  ticks each registered spatial sound's panner.
+
+### Changed (BREAKING)
+
+- **`Sound.play()` is now multi-instance by default.** Each call
+  creates a new pooled instance up to `poolSize`. The previous
+  singleton-replace behavior is opt-in via
+  `play({ replace: true })`.
+- **`Sound.playPooled()` removed.** Use `play()` (which is now the
+  pooled multi-instance path).
+- **`Sound.poolSize` default raised from 1 to 8.** Closer to typical
+  SFX needs without manual configuration.
+- **`Sound._sourceNode` (the previous primary singleton source) is
+  removed.** With pooled play unified, all sources go through
+  `_pooledSources`. As a consequence, `Sound.getTime()` and
+  `Sound.setTime()` no longer track per-source playback position
+  — they're effectively no-ops on Sound now. For precise timing
+  use `Music` (HTMLMediaElement-backed singleton).
+- **`AbstractMedia.bus` property added.** Subclasses (Sound, Music)
+  override `_defaultBus()`, `_connectToBus()`, `_disconnectFromBus()`
+  to integrate with the mixer.
+
+### Migration
+
+```ts
+// Before:
+sound.play();              // singleton — second call replaces first
+sound.playPooled();        // multi-instance — concurrent plays
+
+// After:
+sound.play();              // multi-instance — concurrent plays (default!)
+sound.play({ replace: true }); // singleton — equivalent of old play()
+```
+
+```ts
+// Before — direct destination routing was implicit:
+const sound = new Sound(buffer);
+sound.play();   // → audioContext.destination
+
+// After — routes through the soundBus by default:
+const sound = new Sound(buffer);
+sound.play();   // → app.audio.sound → app.audio.master → destination
+
+// Override to a custom bus:
+const dialogueBus = new AudioBus('dialogue', { parent: app.audio.master });
+app.audio.registerBus(dialogueBus);
+sound.bus = dialogueBus;
+```
+
+```ts
+// Spatial audio:
+const explosion = new Sound(buffer);
+explosion.position = { x: 200, y: 100 };  // becomes spatial
+app.audio.listener.target = playerSprite;  // ears follow player
+
+explosion.play();
+// → routes through equalpower panner with distance falloff
+```
+
+### Notes
+
+- `DuckingFilter` uses its own internal `setInterval(60Hz)` for
+  per-frame envelope-following rather than hooking into
+  `AudioManager.update()`. This keeps audio-side filters
+  self-contained and avoids cross-cutting changes to the mixer
+  contract. May be revisited.
+- `LowestPriority` pool strategy degenerates to FIFO within a
+  single Sound instance because all pooled sources share the same
+  `priority` value. The strategy becomes meaningful when the
+  engine later adds cross-Sound voice management.
+- Spatial sounds share a single `PannerNode` per Sound instance —
+  all simultaneous pooled plays of one sound emit from the same
+  world-space point. Per-instance positions would require an
+  API extension and are deferred.
+- BeatDetector / `AudioAnalyser.onBeat` hooks are deferred to
+  0.7.1 — this release focuses on the mixer / filter / spatial
+  foundation.
+
+## [0.6.20] - 2026-05-02
+
+Adds `view.follow(SceneNode)`, audio fade helpers, and focus / visibility
+infrastructure. Pure additive — no behavior changes for existing code.
+
+### Added
+
+- **`view.follow()` accepts `SceneNode`** in addition to `{x, y}`
+  targets. When the target is a SceneNode, the follow tracks its
+  **world-space position** via `getGlobalTransform()`, so following a
+  Sprite nested under a translated/rotated Container works correctly.
+  New exported type `ViewFollowTarget = SceneNode | { x: number; y:
+  number } | null`.
+- **Audio fade helpers on `AbstractMedia`** — both `Sound` and `Music`
+  inherit:
+  - `fadeIn(durationMs): this` — ramps gain from 0 to current volume.
+    Auto-plays if paused. Cancels any in-flight fade.
+  - `fadeOut(durationMs, options?: { stopAfter?: boolean }): this` —
+    ramps gain to 0. By default calls `pause()` after the fade
+    completes; pass `{ stopAfter: false }` to keep playing at zero
+    volume.
+  - Both return `this` for chaining and use Web Audio's
+    `linearRampToValueAtTime` for sample-accurate fades.
+- **`Application.canvasFocused: boolean`** — passthrough getter for the
+  InputManager's existing canvas focus state.
+- **`Application.documentVisible: boolean`** — tracks
+  `document.visibilityState`, updated on `visibilitychange`.
+- **`Application.onCanvasFocusChange: Signal<[focused: boolean]>`** —
+  fires when the canvas gains or loses focus (canvas blur,
+  click-outside, alt-tab from canvas-focused state).
+- **`Application.onVisibilityChange: Signal<[visible: boolean]>`** —
+  fires when the page tab becomes hidden or visible (minimize, switch
+  tab, etc.).
+- **`Application.pauseOnHidden: boolean`** (default `false`) — when
+  `true`, `app.update()` skips the entire frame body while
+  `documentVisible` is `false`. `requestAnimationFrame` keeps
+  ticking (already throttled by the browser when hidden) so the loop
+  resumes seamlessly when the page becomes visible again.
+- **`InputManager.onCanvasFocusChange`** — same signal also exposed
+  here for users who only need input-side focus tracking without
+  reaching for the Application.
+
+### Notes
+
+- Window-level `blur` / `focus` events are intentionally not exposed as
+  separate signals — `document.visibilitychange` is the better-defined
+  API and covers the common cases.
+- `crossFade()` as a top-level helper was deferred — compose
+  `a.fadeOut(ms)` + `b.fadeIn(ms)` manually until the AudioManager lands.
+- `view.follow()` continues to use lerp-based smoothing for continuous
+  tracking. Scripted one-shot camera moves (zoom-to-room,
+  pan-to-cutscene) should use the existing Tween system on
+  `view.center` for full easing-curve support.
+
+## [0.6.19] - 2026-05-02
+
+Caches global transforms, world-space bounds, sprite vertices, and
+sprite normals via dirty flags. Closes four hot-path recomputation
+gaps that the audit identified — `getGlobalTransform()` and
+`getBounds()` were O(depth) per call, called many times per frame
+from sprite rendering, hit-testing, frustum culling, and collision
+detection. Pure performance change — no public API surface changes.
+
+### Performance
+
+- **`SceneNode.getGlobalTransform()`** is now cache-hit-O(1) instead
+  of O(depth). The cached `_globalTransform` is invalidated on
+  position / rotation / scale / origin change, on parent change
+  (add/remove from a Container), and propagated to all descendants
+  on parent transform changes.
+- **`SceneNode.getBounds()`** is now cache-hit-O(1). Invalidated
+  alongside global transform, plus on local-bounds mutations
+  (`Sprite.setTextureFrame`, `Mesh.recomputeLocalBounds`,
+  `ParticleSystem.setTextureFrame`). Local-bounds changes also
+  cascade up to ancestor Containers' bounds.
+- **`Sprite.vertices`** getter caches the eight world-space vertex
+  components. Recomputes only when the sprite's transform or local
+  bounds change. Previously had a `// todo cache this` comment.
+- **`Sprite.getNormals()`** returns a stable `[Vector, Vector,
+  Vector, Vector]` array. The four `Vector` instances are reused
+  across calls; previously each call allocated four new `Vector`s.
+  Recomputes only when vertices change. Reduces GC pressure in
+  collision-detection hot paths.
+
+### Notes
+
+- `Sprite.getNormals()` now returns the **same array reference** on
+  every call. Callers that previously stored the result and expected
+  it to remain stable across mutations must re-read after any
+  transform change. This is a behavior refinement; no caller in the
+  codebase relied on the prior allocation pattern.
+- Invalidation propagation walks the scene subtree on position /
+  rotation / scale / origin changes. For very large UI trees
+  (thousands of nested children), this is O(descendants) per setter
+  call. Setters are typically called on a small number of nodes per
+  frame, so the cumulative cost is dominated by the savings on
+  the read path. Generation-counter invalidation is a possible
+  future optimization if profiling shows the walk dominates.
+- New flag bits: `SceneNodeTransformFlags.GlobalTransform` (1<<8),
+  `SceneNodeTransformFlags.BoundsRect` (1<<9),
+  `SpriteFlags.Vertices` (0x400), `SpriteFlags.Normals` (0x800).
+  Non-overlapping with existing flags so they share the same
+  `Flags<T>` instance.
+
+## [0.6.18] - 2026-05-02
+
+Fixes a long-standing audio volume-ramp bug.
+
+### Fixed
+
+- **Audio volume / mute changes are now near-instant**. The third
+  argument to `GainNode.setTargetAtTime` is a time constant in
+  **seconds** — `Sound`, `Music`, and the `Video` audio path were
+  passing `10`, which made every volume update take ~30 seconds to
+  reach 95% of its target value. Calling `sound.setVolume(0.5)` would
+  fade over half a minute instead of taking effect immediately.
+  Replaced with `0.01` (10 ms) — fast enough to feel instant, slow
+  enough to avoid the audible click of a snapped value. Standard
+  practice in `pixi-sound`, Howler, and other Web Audio libraries.
+  Affects: `Sound.setVolume`, `Sound.setMuted`, `Sound` audio-context
+  setup, and the equivalent paths on `Music` and `Video`. Bug was
+  present since the initial commit; not caught by tests because the
+  jsdom mock stubs `setTargetAtTime` as a no-op.
+
+## [0.6.17] - 2026-05-02
+
+Rewrites the debug overlay as a canvas-native, tree-shake-able module.
+Replaces the DOM-based 0.6.15 implementation. Also adds a generic
+per-frame application hook.
+
+### Added
+
+- **`Application.onFrame: Signal<[Time]>`** — generic per-frame hook
+  fired between `sceneManager.update()` and `backend.flush()`. Useful
+  for any external tool that wants per-frame ticks without writing a
+  Scene (debug overlays, profilers, custom HUDs).
+- **`@codexo/exojs/debug` subpath export** — DebugOverlay and friends
+  now live behind a separate import path. Apps that don't import it
+  pay zero bundle cost. The root `@codexo/exojs` no longer references
+  any debug code.
+- **Canvas-native `DebugOverlay`** — instantiate manually:
+  ```ts
+  import { DebugOverlay } from '@codexo/exojs/debug';
+  const debug = new DebugOverlay(app);
+  debug.layers.performance.visible = true; // or press F1
+  ```
+  Subscribes to `app.onFrame` for ticking, `inputManager.onKeyDown`
+  for F1 binding, and `app.onResize` for screen-space view sync.
+  Renders into its own screen-space view between scene render and
+  backend flush.
+- **`PerformanceLayer`** (V1's only layer) — FPS, frame-time
+  sparkline, draw calls, node count, culled nodes. Top-left fixed
+  position. Toggle via `F1` or `debug.layers.performance.visible`.
+- **`DebugLayer` abstract base** — exported so future layer types
+  (BoundingBoxes, HitTest, PointerStack) plug in cleanly. V1 ships
+  only PerformanceLayer; more arrive in subsequent patches.
+
+### Changed
+
+- **`Application.debug` removed** — was added in 0.6.15. Apps that
+  used `app.debug.show()` must migrate to `import { DebugOverlay }
+  from '@codexo/exojs/debug'` and instantiate manually. **Breaking
+  change**, but the affected window is one day (0.6.15 → 0.6.17).
+
+### Notes
+
+- The new architecture decouples DebugOverlay from Application so
+  the root bundle tree-shakes the debug code away when unused. This
+  is the same pattern projects use for optional dev-tools modules.
+- F1 binding is hardcoded for V1. Opt-out (`{ keybindings: false }`
+  constructor option) and additional keybindings come with the
+  next layers.
+- F-keys only fire while the canvas has focus — engine convention,
+  not a debug-specific quirk.
+
+## [0.6.16] - 2026-05-02
+
+Adds an opt-in spatial index for hit-testing and replaces the dead
+`core/Quadtree` class with a generic `math/Quadtree<T>`.
+
+### Added
+
+- **`Quadtree<T>`** in `@/math/Quadtree` — generic spatial index with
+  `insert(item)`, `queryPoint(x, y, results?)`, `queryRect(rect, results?)`,
+  `clear()`, and `destroy()`. Items carry their `bounds: Rectangle` and
+  arbitrary `payload: T` separately, so a single tree can index any
+  spatial domain. The `results` array is reused across queries for
+  zero-allocation hot paths.
+- **`InteractionManager.useSpatialIndex: boolean`** (default `false`) —
+  opt-in flag. When enabled, the manager rebuilds a quadtree of all
+  visible interactive nodes once per `update()` tick and uses it for
+  hit-testing instead of the recursive scene-tree walk. Z-order is
+  preserved via insertion-order tags. Captured pointers (active drags)
+  bypass the index — same as the recursive fallback.
+
+### Changed
+
+- **`core/Quadtree`** removed — was dead code, exposed publicly via the
+  `core` barrel but never imported anywhere internally. The new
+  `math/Quadtree<T>` covers the same conceptual ground with a cleaner
+  API and broader applicability. **This is a breaking change for any
+  external code that imported `Quadtree` from `@codexo/exojs`** and
+  relied on the SceneNode-specialized `addSceneNode` /
+  `getRelatedChildren` methods. Replacement: use `Quadtree<RenderNode>`
+  from `@/math/Quadtree` with `insert({ bounds, payload })` and
+  `queryPoint` / `queryRect`.
+
+### Notes
+
+- Default behavior is unchanged: `useSpatialIndex` is off, so the
+  recursive walk remains the hit-test path. Turn it on for scenes
+  with many interactive nodes — the per-frame rebuild + log-time
+  query pays off when the linear walk becomes a bottleneck.
+- Per-frame rebuild is intentional in v1. Smarter invalidation
+  (rebuild only when the scene tree mutates) is a follow-up.
+- The new tree does not redistribute items already-stored in a parent
+  when subdivision happens — fine for the rebuild-each-frame model
+  since items don't accumulate across frames. If item-stable trees
+  become a use case later, redistribution is ~20 LOC to add.
+
+## [0.6.15] - 2026-05-02
+
+Adds a built-in debug HUD for runtime stats. Opt-in HTML overlay that
+shows FPS, frame time, draw calls, node count, active pointers, and
+the currently hovered interactive node — handy during development,
+zero cost when not shown.
+
+### Added
+
+- **`Application.debug`** — auto-instantiated `DebugOverlay` instance.
+  DOM is created lazily on first `show()`, so the panel costs nothing
+  until opt-in. Position-fixed over the canvas, recomputed each frame
+  from `canvas.getBoundingClientRect()` so it tracks if the canvas
+  moves.
+- **`DebugOverlay.show() / hide() / toggle()`** — visibility control.
+  `show()` returns `this` for chaining. Bind to a key in your code if
+  you want a hotkey toggle.
+- **Stats displayed**: FPS (60-sample rolling average), frame time
+  (ms), draw calls, culled nodes, total scene-tree node count, active
+  pointers, hovered node class + cursor coords.
+- **`InteractionManager.getHoveredNode(pointerId?)`** — returns the
+  RenderNode currently hovered by the given pointer (or the first one
+  in iteration order when omitted). Used by the debug panel; also
+  useful for custom HUDs.
+
+### Notes
+
+- The overlay is a styled `<div>` appended to `document.body`. It uses
+  `pointer-events: none` so clicks pass through to the canvas.
+- No keyboard shortcut is wired up — bind `app.debug.toggle()` to
+  whatever key you want.
+- Hit-test box visualization is not in this release — coming when
+  the spatial-index work lands.
+
+## [0.6.14] - 2026-05-02
+
+Reshapes the interaction system around a per-frame tick and adds an
+opt-in drag-and-drop helper. The public per-node signal API from 0.6.13
+is unchanged; only event *cadence* and a new `draggable` flag.
+
+### Added
+
+- **`RenderNode.draggable: boolean`** (default `false`) — when set on
+  an interactive node, a `pointerdown` over the node starts a drag:
+  the framework auto-positions the node by tracking pointer movement
+  while preserving the grab offset, and routes all subsequent pointer
+  events for that pointer ID to the dragged node regardless of where
+  the pointer is. Drag bypasses hit-testing until release.
+- **Three drag signals on `RenderNode`**: `onDragStart`, `onDrag`,
+  `onDragEnd` — all `Signal<[InteractionEvent]>`. Drag events use new
+  event types `'dragstart' | 'drag' | 'dragend'` and dispatch directly
+  on the node (no bubble — parent containers don't receive child drag
+  events).
+- **`InteractionManager.update()`** — public per-frame tick called
+  automatically from `Application.update()` between `inputManager.update()`
+  and `tweens.update()`. Drains a per-pointer queue filled by signal
+  handlers; no-op when nothing happened that frame.
+
+### Changed
+
+- **InteractionManager moved from event-driven to tick-driven.**
+  Signal handlers now only enqueue flags into a per-pointer bitfield
+  and set a dirty flag; the actual hit-test + dispatch happens once
+  per frame in `update()`. Same observable behavior, but decoupled
+  from `InputManager` signal cadence — paves the way for spatial-index
+  integration.
+
+### Notes
+
+- **Drag uses native `setPointerCapture`** so movement keeps tracking
+  even when the pointer leaves canvas bounds. `pointercancel` /
+  `pointerleave` during a drag fires `onDragEnd` (no separate
+  cancellation flag in v1; check the event type if needed).
+- **Drag offset is in canvas-space.** Nodes whose parent containers
+  have non-identity transforms may feel off — v1 assumes top-level
+  draggable elements (UI panels, inventory items). True
+  parent-aware drag is a follow-up.
+- **`pointerover` / `pointerout` are suppressed during a drag** —
+  the dragged node stays "hovered" by definition.
+
+## [0.6.13] - 2026-05-02
+
+Adds object-level pointer events. Scene-graph nodes are now first-class
+event targets — opt in with `node.interactive = true` and listen on
+per-node signals. Pure addition; existing global pointer signals on
+`InputManager` are unchanged.
+
+### Added
+
+- **`RenderNode.interactive: boolean`** (default `false`) — opt-in flag
+  enabling hit-testing for the node. Hit-test reuses the existing
+  `RenderNode.contains(x, y)` (AABB in world space).
+- **`RenderNode.cursor: string | null`** (default `null`) — CSS cursor
+  string applied to `canvas.style.cursor` while the pointer is over the
+  node. Walks up the ancestor chain; first non-null wins.
+- **Six per-node signals**: `onPointerDown`, `onPointerUp`,
+  `onPointerMove`, `onPointerOver`, `onPointerOut`, `onPointerTap` —
+  all `Signal<[InteractionEvent]>`.
+- **`InteractionEvent`** — `type`, `target` (the originally-hit node,
+  stable across bubble), `currentTarget` (changes per bubble step),
+  `pointer`, `worldX`, `worldY`, `stopPropagation()`,
+  `propagationStopped`.
+- **`InteractionManager`** — wired automatically as
+  `Application.interaction`. Subscribes to existing `InputManager`
+  signals (no extra DOM listeners), hit-tests the active scene's root
+  in reverse z-order, dispatches with bubble propagation, and updates
+  the canvas cursor.
+
+### Notes
+
+- **Bubble-only, no capture phase.** Bubble walks `parentNode` and
+  stops at the first non-interactive ancestor — parents must opt in
+  to receive bubbled events. `event.stopPropagation()` halts the walk.
+- **Touch has no hover phase.** `pointerover` / `pointerout` for touch
+  fire only at down/up boundaries (a finger doesn't exist on the
+  surface between presses). Don't rely on hover effects for touch UX.
+- **AABB hit-test only in v1.** Precise (polygon / alpha) hit-testing
+  is deferred. Override `contains(x, y)` for custom shapes.
+- **Cursor is CSS-only.** For animated or texture-based custom cursors,
+  set `canvas.style.cursor = 'none'` and render a sprite that follows
+  pointer position. CSS gives OS-level latency and survives game-loop
+  stutter; engine-rendered cursors don't.
+
 ## [0.6.12] - 2026-05-02
 
 Adds swept (continuous) collision detection. Pure-math addition —