@zakkster/lite-audio 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,195 @@
 # Changelog
 
+## 1.1.0
+
+The music layer. Streaming tracks via `MediaElementAudioSourceNode` share the
+same bus graph as SFX; the crossfade is the mixer, the buses are the routing,
+the pool is untouched.
+
+Not purely additive after all. Putting tracks on the buses turned three
+existing behaviours into bugs — `stopAll()` that leaves the music playing,
+`playUnique()` that hands back a live SFX handle to say "the track started",
+`resumeTrack()` that plays silence — and surfaced one that predates the music
+layer entirely: SFX handles did not carry their bus. See **Fixed**.
+
+### Added
+
+- **`defineTracks(config)`** — fetch + attach `<audio>` elements + register
+  per-track signals (loadState, playing, position, duration). Same async
+  shape as `defineSounds`. Config accepts `loop`, `loopStart`, `loopEnd`
+  alongside `src`, `bus`, `volume`. Format fallback via `canPlayType` over
+  the src array, same probe as SFX.
+- **`playTrack(name, opts?)`** — starts or resumes a track. Idempotent per
+  name; playing an already-playing track is a no-op unless `restart: true`
+  is set. `fadeIn` (ms) schedules an equal-power ramp; `position` (seconds)
+  seeks before play. Silent no-op if the context is still locked or the
+  track is not `ready`.
+- **`stopTrack(name, { fade? })`** — schedules a fade-out on the track's
+  xfadeGain. The `playing` signal flips false immediately (HUDs update); the
+  `<audio>` element is paused after the fade so decoding stops. Default
+  fade 200 ms.
+- **`pauseTrack(name)` / `resumeTrack(name)`** — pause without losing
+  position; resume picks up where paused. Distinct from stop/play in that
+  no fade is scheduled and the graph stays live.
+- **`crossfade(from, to, durationMs)`** — equal-power ramp on both sides.
+  Either side may be `null` for fade-out-only or fade-in-only. Curves are
+  scaled from the outgoing/incoming track's current xfadeGain value, so a
+  mid-flight retarget starts from where the automation actually is and has
+  no discontinuity.
+  - **Interruption semantics (case c).** A track fading out from a previous
+    crossfade keeps its scheduled fade. Only tracks named in the new call
+    are touched. A track that was fading IN and is now the OUTGOING of the
+    new call reads its current gain, cancels its schedule, and starts an
+    equal-power fade-out from that value.
+- **`playExclusive(name, opts?)`** — starts `name`, fades every other
+  playing track on `name`'s bus. Bus-scoped, not category-scoped: buses are
+  the physical version of the manager's categories, so an exclusive on the
+  music bus leaves SFX and voice untouched.
+- **`playUnique(name, thresholdMs = 100)`** — manager parity. Timestamp
+  gate keyed by name via `Map<string, timestamp>`. Works on both registered
+  sounds (dispatches to `play`) and tracks (dispatches to `playTrack`).
+  Returns `-1` on threshold rejection or unknown name.
+- **New reactive readouts.** `trackLoadState(name)`, `trackPlaying(name)`,
+  `trackPosition(name)`, `trackDuration(name)`.
+
+### Changed
+
+- **Default bus set.** `LiteAudioOptions.buses` now defaults to
+  `['sfx', 'ui', 'voice', 'music']` so `defineTracks` works with its default
+  routing out of the box. Explicit `buses` config still overrides.
+
+### Fixed
+
+- **SFX handles did not name a bus.** A pool handle is a full uint32
+  (`[gen:24][channel:8]`) with no spare bits, and every bus runs its own pool
+  counting channels and generations from zero. So the first play on *every* bus
+  returned the identical handle — `0x00000000` — and `stop()` broadcast that raw
+  value to every pool, where each generation check happily passed. Stopping an
+  `sfx` voice also killed whatever sat on channel 0 of `ui`, `voice`, and
+  `music`. The generation counter cannot prevent this: it is a recycle counter,
+  not a namespace. `play()` now returns `busIndex * 2^32 + poolHandle`; `stop()`
+  resolves the owning pool in O(1) and cannot cross a bus boundary. Handles stay
+  plain opaque numbers, exact well inside 2^53.
+- **`stopAll()` and `stopBus()` ignored music.** Both stopped pool voices only,
+  so a scene change that called `stopAll()` left the old theme playing under the
+  new scene. Both now also fade out the tracks routed to the buses they name
+  (`opts.fade`, default 200 ms). "Stop every voice on every bus" has to mean the
+  bus, now that tracks live on it.
+- **`playUnique()` returned `0` for a track.** `0` is not a null handle — it is
+  channel 0, generation 0, bus 0: a perfectly good voice. A caller doing
+  `const h = playUnique('theme'); ... stop(h)` killed an unrelated SFX voice.
+  Tracks are singletons addressed by name and have no handle, so a track start
+  now reports `-2`, which is inert to `stop()` and distinguishable from the `-1`
+  that already meant "skipped".
+- **`resumeTrack()` after `stopTrack()` played silence.** `stopTrack()` fades
+  `xfadeGain` to zero; `resumeTrack()` restarted the element and set
+  `playing` to `true` without ever restoring the gain. The result was a track
+  that was decoding, reporting itself as playing, and completely inaudible — a
+  signal that lied. `resumeTrack()` now lifts the gain back to full over a 40 ms
+  equal-power ramp (a no-op when it is already there) and disarms any pause left
+  queued behind the earlier fade.
+- **`destroy()` left the `<audio>` elements holding their streams.** Handlers
+  were removed and the element paused, but a paused element that still has a
+  `src` can keep buffering, and after `_tracks.clear()` nothing could reach it to
+  stop. Teardown now releases the source (`removeAttribute('src')` + `load()`).
+
+### Internal
+
+- **Equal-power curves precomputed at module load.** Two 128-sample
+  `Float32Array`s (`EQ_POWER_IN`, `EQ_POWER_OUT`). Per-crossfade allocation
+  is one scaled `Float32Array` per side (512 bytes each), GC'd after the
+  curve executes. Off the hot path — scene transitions, not frame loops.
+- **Position writes are throttled at the source.** A per-track
+  `lastPositionWrite` timestamp on the ctx clock; a `timeupdate` listener
+  writes to the position signal only if 100 ms of ctx time have passed
+  since the last write. No `setInterval`, no rAF loop, no allocation.
+- **Delayed pause after stopTrack.** `<audio>.pause()` is deferred until
+  `fade + 30 ms` via injectable `setTimeout`, so the fade tail is audible.
+  Tests inject a manual scheduler and call `flush()` to make teardown
+  deterministic.
+
+### Mock harness (test/mock-ctx.js) extensions
+
+- **`mockParam` params now follow their automation.** Every scheduling call
+  still records its shape into `.events`, and now also settles `.value` on the
+  value it is heading for (including a new `setValueCurveAtTime`). Recording
+  alone was not enough: it let a test prove a fade-out was *scheduled* while
+  saying nothing about where the gain ended up — and "scheduled a fade-out"
+  plus "still audible" is precisely the shape of the `resumeTrack` bug fixed
+  above. A harness that cannot express the bug cannot catch it. Tests that care
+  about the ramp read `.events`; tests that care about the outcome read `.value`.
+- `mockMediaElementSource(element)` factory, and `ctx.createMediaElementSource(el)`
+  on the mock context. The node keeps a reference to the element it was built
+  from, so a test can assert the graph was wired to the right track.
+- `mockAudioElement(src?)` factory: `play` / `pause` / `load` /
+  `removeAttribute`, settable `currentTime`, `duration`, `loop`, `paused`,
+  `playCalls` / `pauseCalls` / `loadCalls` / `srcReleased` counters, and
+  `_fire(type)` / `_listenerCount(type)` so tests can dispatch `timeupdate`,
+  `ended`, and `loadedmetadata` by hand.
+- `mockDocument()` — hands out `<audio>` elements and records them in order, so
+  "one element per track" is an assertion rather than a hope.
+- `mockScheduler()` — manual `setTimeout` / `clearTimeout` for
+  `opts.setTimeout` / `opts.clearTimeout`. `stopTrack` defers the element pause
+  until after the fade; with a real timer that is a race, and with this it is an
+  assertion.
+
+Every v1.0.0 test consumes the harness unchanged.
+
+### Test coverage (v1.1.0)
+
+**75 tests across 18 suites, all green.** 32 carried from v1.0.0 unchanged, plus:
+
+`test/Tracks.test.js` — 37 tests:
+
+- **defineTracks** (6): ready state, one `<audio>` element per track,
+  unknown-bus throw, idempotent re-definition, error when no source resolves,
+  duration from `loadedmetadata` and error from the element.
+- **playTrack** (7): graph wired `source -> xfade -> volume -> bus` with the
+  track's volume on `volumeGain`, element starts and `playing` flips, no-op
+  while locked, no-op when never loaded, idempotent unless `restart`, seeks to
+  `position`, `fadeIn` schedules an equal-power curve of the right duration.
+- **stopTrack** (3): `playing` flips at once while the element keeps decoding
+  through the fade tail, the pause lands only on scheduler flush, `fade: 0`
+  drops the gain in one step with no curve, stopping an idle track arms nothing.
+- **pauseTrack / resumeTrack** (4): pause preserves position and does not touch
+  the gain; **resume after `stopTrack` restores the gain instead of playing
+  silence**; resume disarms the pause queued behind the fade; resume refuses
+  while locked or unloaded.
+- **Looping and position** (4): native `element.loop` when there are no custom
+  points and disabled when there are, `timeupdate` seek back to `loopStart` on
+  crossing `loopEnd`, position signal throttled to 100 ms of context time,
+  `ended` flips `playing` without tearing the graph down.
+- **Crossfade** (5): both sides scheduled from the same instant over the same
+  duration; **combined power holds at 1.0 across every sample** (a linear fade
+  would dip to 0.71); one-sided fades in each direction; a mid-flight retarget
+  starts from the gain's current value with no jump.
+- **playExclusive / playUnique** (3): exclusive fades bus siblings and leaves
+  other buses alone; **`playUnique` returns `-2` for a track and cannot be
+  mistaken for handle `0`**; threshold gating and unknown names.
+- **Bus-wide stops** (2): `stopAll()` reaches the music; `stopBus()` stays
+  scoped to the bus it names.
+- **Teardown** (3): `destroy()` releases the elements (`removeAttribute('src')`
+  + `load()`), removes handlers, disconnects the track nodes, clears the pending
+  pause timer, and is idempotent and inert afterwards.
+
+`test/BusHandles.test.js` — 6 tests: handles from different buses are never
+equal while their raw pool handles are identical, `stop()` cannot cross a bus
+boundary, `busOf()`, stolen-handle staleness, `activeCount()` per-bus and
+engine-wide, and handles staying exact integers well inside 2^53.
+
+Not covered, and honestly so: **format fallback**. `pickSupportedSrc()` probes
+the real `document` / `Audio` globals rather than the injected ones, so under
+`node:test` it always takes the "no `<audio>` available, first URL wins" branch.
+Testing it would mean either injecting the probe or polluting globals; the
+branch it actually runs is covered, the `canPlayType` path is not.
+
+### Deliberately deferred to A3 (v1.2.0)
+
+- Ducking (sfx/voice activity dips the music bus via a follower ramp)
+- Mix snapshots (`captureSnapshot()` / `applySnapshot(name, ms)`)
+- Auto-suspend (D9)
+- Per-bus `AnalyserNode` meter signals (opt-in)
+
 ## 1.0.0
 
 Initial release. Ships the SFX layer of the lite-audio stack: signal-driven
@@ -15,95 +205,15 @@ buses over one `AudioPool` per bus, iOS/mobile unlock ported verbatim from
   — click-free by construction, no manual ramp code in userland.
 - **Unlock ported verbatim (D3).** Silent-buffer pulse + `ctx.resume()` on the
   first `touchstart` / `touchend` / `mousedown` / `keydown`, capture-phase,
-  behind an `AbortController` — same event set and same attach shape as the
-  manager. Handles `'interrupted'` state (iOS phone-call scenario) as
-  equivalent to `'suspended'`. Added: `ctxState()` and `unlocked()` as signals
-  the rest of the app can subscribe to.
+  behind an `AbortController`. Handles `'interrupted'` state (iOS phone-call
+  scenario) as equivalent to `'suspended'`.
 - **Bounded pre-unlock play queue (D3 extension).** `play()` before unlock
-  returns `-1` and enqueues the intent. Same-sound repeats collapse to
-  latest-per-sound; new distinct sounds past `queueLimit` are silently dropped.
-  Flushed on unlock. The manager's silent-drop behavior was the #1 mobile-game
-  paper cut Howler could not fix from the outside; lite-audio fixes it from
-  the inside.
-- **Reactive loader (D4).** `defineSounds(config)` fetches + decodes each
-  sound; a `loadState(id)` signal per sound transitions
-  `'idle' -> 'loading' -> 'ready' | 'error'` observably. Format fallback via
-  `canPlayType` probe over the `src` array. Fetch is injectable for tests.
-- **Positional hot path (D5).** `play(soundId, volume, pan, pitch)` — no
-  options object per call. `playOpts(id, {...})` sugar layer above handles
-  `pitchVar` random-pitch resolution.
-- **Bus-tagged voice handles (D5/D6).** `play()` returns
-  `busIndex * 2^32 + poolHandle`. The tag is not decoration: every bus runs its
-  own `AudioPool`, and every pool counts channels and generations from zero, so
-  the first play on *each* bus returns the identical raw handle
-  (`0x00000000` - channel 0, generation 0). A handle alone cannot say which bus
-  issued it, and the pool's generation check cannot help, because it is a
-  recycle counter, not a namespace. With the tag, `stop()` resolves the owning
-  pool in O(1) and cannot reach across a bus boundary. Handles stay plain
-  numbers, exact well inside 2^53, opaque to callers.
-- **Fades delegated to pool (D6).** `stop(handle)` routes to the handle's own
-  bus; the generation check inside that pool means a stale handle after a steal
-  is a silent no-op, never a wrong-voice hit.
-- **`isPlaying(handle)`, `busOf(handle)`, `activeCount(busName?)`.** Liveness of
-  one voice, the bus that issued a handle, and the live voice count per bus or
-  engine-wide. Allocation-free; `activeCount()` is safe to call every frame.
-- **Master mute persistence (D7).** localStorage key `'lite_audio_muted'` -
-  byte-identical to `lite-audio-manager` so a game migrating between the two
-  keeps the player's saved preference intact.
-- **Mock-ctx test harness (D8).** `test/mock-ctx.js` records every
-  `AudioParam` scheduled event into an `.events` array, runs a real state
-  machine covering all four `AudioContextState` values, and mocks
-  `decodeAudioData` + `fetch` with length-hint payloads so different mock
-  URLs decode to different-sized buffers deterministically. Foundation for
-  every later lite-audio session.
-
-### Deliberately deferred (roadmap D10)
-
-- **Music streaming layer.** `MediaElementAudioSourceNode`, crossfades,
-  reactive `position()` / `duration()`, `playExclusive` / `playUnique` -
-  ships in **v1.1.0** (roadmap session A2).
-- **Ducking, mix snapshots, per-bus meters, auto-suspend.** Ships in
-  **v1.2.0** (roadmap session A3).
-- **`./compat` shim.** `AudioManager`-shaped adapter over `LiteAudio` for
-  drop-in migration, plus full parity certification. Ships in **v2.0.0**
-  (roadmap session A4).
-- **3D spatial (PannerNode/HRTF), AudioWorklet custom DSP, convolution
-  reverb.** Post-2.0.
-
-### Demo
-
-- New `demo/index.html`: single-file, four scenes, no asset folder - every sound
-  is synthesized in an `OfflineAudioContext`, encoded to WAV, and served to the
-  engine as a `blob:` URL, so the real fetch + decode path runs.
-  **unlock** - the context lifecycle as an SVG state machine driven by
-  `ctxState()`, plus the pre-unlock queue: fire plays while locked and watch
-  latest-per-sound collapse and the `queueLimit` drop, then dispatch the gesture
-  and hear the flush. The engine takes a *fake window* through `opts.window`, so
-  the demo owns the gesture instead of racing it - the one-shot feature becomes
-  replayable. **loader** - `loadState()` per sound, with one asset behind 2.6s of
-  injected fetch latency and one pointed at a 404, so `loading` and `error` are
-  states you can actually watch. **mixer** - bus faders and mutes as signals,
-  with a gain scope plotting the real `GainNode.value` against the signal target:
-  the 10ms `setTargetAtTime` bend is the click you do not hear. **voices** - the
-  per-bus pools, and the twin-handle trap: two buses hand back the same raw
-  handle, and only the bus tag keeps `stop()` from killing both.
-
-### Test coverage
-
-38 tests across 10 suites, all green. Gate items from the roadmap:
-
-- Unlock state machine including `'interrupted'` — 6 tests
-- Loader fallback + error - 5 tests
-- Bus effect writes as `setTargetAtTime` on the mock ctx - 4 tests
-- Steal + declick schedule shape (delegated) - 1 test
-- Generation no-op on stale handles (delegated) - covered in 2 playback tests
-- Unlock queue flush (latest-per-sound, bounded) - 3 tests
-- Zero-GC hot path shape - 1 test
-- Master mute persistence — 3 tests
-- Playback delegation to pool — 6 tests
-- destroy() idempotency + listener detachment - 3 tests
-
-- Handle namespace across buses - 6 tests (`test/BusHandles.test.js`)
+  returns `-1` and enqueues the intent (latest-per-sound, bounded).
+- **Reactive loader (D4).** `defineSounds(config)` with per-sound
+  `loadState()` signal transitions and format fallback.
+- **Positional hot path (D5) and pool-delegated stops (D6).**
+- **Master mute persistence (D7).** localStorage key `'lite_audio_muted'`.
+- **Mock-ctx test harness (D8).**
 
 ### Peer dependency pins
 

package/README.md

@@ -54,7 +54,18 @@ await audio.defineSounds({
 // flushed on the first touchstart / mousedown / keydown otherwise. No polling,
 // no "waiting for unlock" ceremony in the caller.
 const handle = audio.play('laser', 0.8, 0.0, 1.0);
-audio.stop(handle);
+audio.stop(handle);                       // stale handles are silent no-ops
+audio.isPlaying(handle);                  // false once stolen, stopped, or played out
+
+// Music: streamed, not decoded. Singletons, addressed by name.
+await audio.defineTracks({
+    menu: { src: ['/menu.mp3'],  bus: 'music', loop: true },
+    boss: { src: ['/boss.mp3'],  bus: 'music', loop: true, loopStart: 8, loopEnd: 96 },
+});
+
+audio.playTrack('menu', { fadeIn: 600 });
+audio.crossfade('menu', 'boss', 800);     // equal-power, both sides, no power dip
+audio.trackPosition('boss');              // ReadSignal<number>, throttled to 10 Hz
 
 // Reactive state - subscribe with lite-signal's effect() for UI hookup.
 audio.unlocked();                         // ReadSignal<boolean>
@@ -64,9 +75,28 @@ audio.busVolume('sfx');                   // ReadSignal<number>
 audio.setBusVolume('sfx', 0.5);           // schedules setTargetAtTime, click-free
 audio.setMuted(true);                     // master mute, persists to localStorage
 
+audio.stopAll();                          // every voice AND every track
 audio.destroy();                          // idempotent, disconnects the graph
 ```
 
+## Handles
+
+`play()` returns a **bus-tagged** handle: `busIndex * 2^32 + poolHandle`. Treat it
+as opaque — get it from `play()`, pass it to `stop()` / `isPlaying()`.
+
+The tag is not decoration. A pool handle is a full `uint32` — `[gen:24][channel:8]`,
+no spare bits — and every bus runs its own `AudioPool` counting channels and
+generations from zero. So the first play on *every* bus hands back the identical
+raw handle, `0x00000000`. Without the tag, `stop()` on an `sfx` handle also killed
+whatever sat on channel 0 of `ui`, `voice`, and `music`. The generation counter
+cannot prevent that: it is a recycle counter, not a namespace. With the tag,
+`stop()` resolves the owning pool in O(1) and cannot cross a bus boundary.
+
+Handles stay plain numbers, exact well inside `2^53`, so `-1` still means "no voice"
+(unknown sound, not loaded, or context locked). `playUnique()` on a *track* returns
+`-2`: tracks are name-addressed singletons with no handle, and `0` was never
+available as a "nothing" value — it is a real voice.
+
 ## Why not Howler?
 
 Howler.js is a good general-purpose audio library. It handles decoding, HTML5
@@ -111,6 +141,39 @@ bus-tagged handles (`busIndex * 2^32 | (gen << 8) | channel`); a stale
 listeners behind an `AbortController`), plus a bounded pre-unlock play queue
 so a call fired before the first user gesture does not vanish.
 
+## Music layer
+
+SFX are decoded into memory and fired through a pool; a five-minute track would be
+~50 MB of PCM for that privilege. Tracks are streamed instead —
+`MediaElementAudioSourceNode` over an `<audio>` element — and routed into the *same*
+bus graph, so one master mute and one set of faders govern both.
+
+Each track is a singleton addressed by name, with its own two-gain chain:
+
+```
+<audio> -> MediaElementSource -> xfadeGain -> volumeGain -> bus.gain -> master
+```
+
+`xfadeGain` carries crossfade curves (0..1); `volumeGain` carries the track's
+baseline volume. They are separate on purpose: a crossfade must not clobber the
+mix, and changing the mix mid-crossfade must not fight the curve.
+
+| Call | Does |
+| --- | --- |
+| `playTrack(name, { fadeIn?, position?, restart? })` | Start or restart. Idempotent. No-op while locked — music is scene-scale, so it is *not* queued the way SFX are. |
+| `stopTrack(name, { fade? })` | Equal-power fade out, then pause the element so the browser stops decoding. `playing` flips to `false` at once; the tail is an audio detail, not a state a HUD should show. |
+| `pauseTrack(name)` / `resumeTrack(name)` | Pause without losing position. `resumeTrack()` also restores a gain that an earlier `stopTrack()` faded away — otherwise it would decode, report itself playing, and be inaudible. |
+| `crossfade(from, to, ms)` | Equal-power both sides. Either side may be `null`. A retarget mid-fade starts from where the gain actually is, so there is no discontinuity. |
+| `playExclusive(name, { fade? })` | Start `name`, fade every other playing track **on the same bus**. Other buses are untouched. |
+| `stopBus(name, { fade? })` / `stopAll({ fade? })` | Stop the pool voices *and* fade the tracks routed there. Once music lives on a bus, "stop the bus" has to mean the bus. |
+
+Loop points: `loop: true` alone uses the native `element.loop`. Add `loopEnd` and the
+engine takes over — `timeupdate` seeks back to `loopStart` on crossing it, and the
+native loop is switched off (it would jump to `0`, not to `loopStart`). Note that
+`timeupdate` fires roughly four times a second, so a custom loop can overshoot by up
+to ~250 ms. For a tight musical loop, prefer an asset whose file boundaries *are* the
+loop.
+
 ## Signal readouts (the whole reactive surface)
 
 | Signal | Read via | Notes |
@@ -121,6 +184,10 @@ so a call fired before the first user gesture does not vanish.
 | Bus volume | `audio.busVolume(name)` | 0..1 (or higher; not clamped) |
 | Bus mute | `audio.busMuted(name)` | Independent of master mute |
 | Load state | `audio.loadState(id)` | `'idle' \| 'loading' \| 'ready' \| 'error'` |
+| Track load state | `audio.trackLoadState(name)` | Same four states |
+| Track playing | `audio.trackPlaying(name)` | Flips `false` the instant a stop is *asked for*, not when the fade ends |
+| Track position | `audio.trackPosition(name)` | Seconds, written at most every 100 ms |
+| Track duration | `audio.trackDuration(name)` | `0` until `loadedmetadata` lands |
 
 All readable via `signal()` (calling), `signal.peek()` (untracked read), or
 inside a `computed()` / `effect()`.
@@ -129,13 +196,15 @@ inside a `computed()` / `effect()`.
 
 ```js
 new LiteAudio({
-    buses:            ['sfx', 'ui', 'voice'],   // user-facing buses
+    buses:            ['sfx', 'ui', 'voice', 'music'],  // user-facing buses
     poolCapacity:     32,                        // voices per bus pool
     queueLimit:       32,                        // bound on pre-unlock queue
     mutedStorageKey:  'lite_audio_muted',        // manager parity default
     fetch:            globalThis.fetch,          // injectable for tests
     window:           globalThis.window,         // ditto
     document:         globalThis.document,       // ditto
+    setTimeout:       globalThis.setTimeout,     // ditto (deferred track pause)
+    clearTimeout:     globalThis.clearTimeout,   // ditto
 });
 ```
 
@@ -156,19 +225,26 @@ notes for that.
 npm test
 ```
 
-32 tests across 9 suites, covering unlock state machine (including
-`'interrupted'`), loader fallback + error, bus signal writes as
-`setTargetAtTime` on a mock AudioContext, pool delegation (steal, generation
-no-op on stale handles, stopBus scope), unlock queue flush semantics
-(latest-per-sound, bounded), and destroy idempotency + listener detachment.
-
-The mock harness (`test/mock-ctx.js`) records every `AudioParam` scheduled
-event into an inspectable `.events` array, runs a real context state machine
-(all four states — `suspended`, `running`, `interrupted`, `closed`), and
-mocks `fetch` + `decodeAudioData` with length-hint payloads so tests can
-distinguish sounds deterministically. This harness is the D8 foundation the
-next roadmap sessions will reuse for the music layer, ducking, and parity
-certification.
+75 tests across 18 suites. The unlock state machine (including `'interrupted'`),
+loader fallback + error, bus writes as `setTargetAtTime`, pool delegation (steal,
+generation no-op on stale handles, bus scope), unlock queue semantics
+(latest-per-sound, bounded), destroy idempotency — plus the whole music layer
+(`test/Tracks.test.js`) and the bus-handle namespace (`test/BusHandles.test.js`).
+
+The mock harness (`test/mock-ctx.js`) records every `AudioParam` scheduled event
+into an inspectable `.events` array **and settles `.value` on whatever the
+automation is heading for**. That second half matters more than it sounds: a
+harness that only records schedules can prove a fade-out was *scheduled* while
+saying nothing about whether the gain ended up silent — and "scheduled a fade-out"
+plus "still audible" is exactly the shape of a real bug this suite now catches. It
+also runs a real context state machine (all four states), mocks `fetch` +
+`decodeAudioData` with length-hint payloads, and hands out `<audio>` elements and
+a manual timer scheduler so the deferred pause behind a track fade is an assertion
+rather than a race.
+
+Not covered, and honestly so: `pickSupportedSrc()` probes the real `document` /
+`Audio` globals rather than the injected ones, so under `node:test` it always takes
+the "first URL wins" branch. The `canPlayType` path is unexercised.
 
 ## License
 

package/llms.txt

@@ -1,5 +1,5 @@
 # @zakkster/lite-audio
-> Zero-GC reactive Web Audio engine. Signal-driven buses, ABA-safe voice handles, unlock queue, per-bus AudioPool. SFX layer over @zakkster/lite-audio-pool.
+> Zero-GC reactive Web Audio engine. Signal-driven buses, ABA-safe voice handles, unlock queue, per-bus AudioPool, streaming music tracks with equal-power crossfade.
 
 ## Install
 npm i @zakkster/lite-audio @zakkster/lite-signal @zakkster/lite-audio-pool
@@ -9,44 +9,49 @@ import { LiteAudio } from '@zakkster/lite-audio';
 
 ## Key Facts
 - Zero deps of its own; two peers: @zakkster/lite-signal (^1.3), @zakkster/lite-audio-pool (^1.1)
-- Signal-driven control surface: bus volumes, master mute, ctx state, per-sound load state are all reactive
+- Signal-driven control surface: bus volumes, master mute, ctx state, per-sound and per-track load state are all reactive
 - Bus writes go through setTargetAtTime for click-free transitions (10 ms time constant)
 - Pre-unlock play() calls are queued (bounded, latest-per-sound), flushed on first user gesture
 - iOS/Safari unlock: silent-buffer pulse + resume() on touchstart/touchend/mousedown/keydown (capture phase, exact set the manager uses)
 - Handles 'interrupted' state (iOS phone-call scenario) the same as 'suspended'
 - Master mute persists to localStorage under 'lite_audio_muted' (byte-identical to lite-audio-manager for migration)
-- One AudioPool per bus (pool v1.1.0+ output param + per-play buffer override)
-- Positional hot path: play(soundId, volume, pan, pitch) - no options object per call
-- Handles are bus-tagged: busIndex * 2^32 + poolHandle. Pool handles collide across buses (every pool starts at channel 0 / generation 0), so the tag is what makes stop() name one voice
-- v1.0.0 covers SFX only; music streaming layer (MediaElementAudioSourceNode) lands in v1.1.0
+- One AudioPool per bus for SFX (pool v1.1.0+ output param + per-play buffer override)
+- Music tracks stream via MediaElementAudioSourceNode routed through the same bus graph
+- Positional hot path for SFX: play(soundId, volume, pan, pitch) - no options object per call
+- SFX handles are bus-tagged: busIndex * 2^32 + poolHandle. Raw pool handles collide across buses (every pool starts at channel 0 / generation 0), so the tag is what makes stop() name one voice
+- Music tracks are singletons addressed by name, not handle - stopTrack('menu_bg') not stop(handle)
+- v1.1.0 ships SFX + music (crossfade, exclusive, unique, loop points). Ducking / snapshots / auto-suspend are v1.2.0; Howler-shim compat subpath is v2.0.0.
 
 ## Quick Start
 ```js
 import { LiteAudio } from '@zakkster/lite-audio';
 
-const audio = new LiteAudio({ buses: ['sfx', 'ui', 'voice'] });
-await audio.init();                       // creates AudioContext
+const audio = new LiteAudio();            // buses default to sfx/ui/voice/music
+await audio.init();
+
+// SFX
 await audio.defineSounds({
     laser: { src: ['/laser.opus', '/laser.mp3'], bus: 'sfx' },
-    hit:   { src: ['/hit.wav'], bus: 'sfx', pitchVar: 0.15 },
     click: { src: ['/click.mp3'], bus: 'ui' },
 });
-
-// Fires immediately if unlocked; queued and flushed on first gesture otherwise.
 const h = audio.play('laser', 0.8, 0.0, 1.0);
 audio.stop(h);
-audio.isPlaying(h);                       // false once stolen, stopped, or played out
+
+// Music
+await audio.defineTracks({
+    menu:     { src: ['/menu.mp3'], bus: 'music' },
+    gameplay: { src: ['/gameplay.mp3'], bus: 'music',
+                loop: true, loopStart: 4.5, loopEnd: 92 },
+});
+audio.playTrack('menu', { fadeIn: 400 });
+audio.crossfade('menu', 'gameplay', 500);
+audio.stopTrack('gameplay', { fade: 300 });
 
 // Reactive readouts
 audio.unlocked();                         // ReadSignal<boolean>
-audio.ctxState();                         // ReadSignal<'suspended'|'running'|'interrupted'|'closed'>
-audio.loadState('laser');                 // ReadSignal<'idle'|'loading'|'ready'|'error'>
-audio.busVolume('sfx');                   // ReadSignal<number>
-
-// Writes
-audio.setBusVolume('sfx', 0.5);
-audio.setBusMuted('ui', true);
-audio.setMuted(true);                     // master, persists to localStorage
+audio.trackPlaying('gameplay');           // ReadSignal<boolean>
+audio.trackPosition('gameplay');          // ReadSignal<number>, throttled ~10 Hz
+audio.setMuted(true);                     // master mute, persists to localStorage
 
 audio.destroy();                          // idempotent
 ```
@@ -57,50 +62,56 @@ audio.destroy();                          // idempotent
 ```
 new LiteAudio(opts?)
 ```
-- `opts.buses?: string[]` - defaults ['sfx', 'ui', 'voice']. 'master' is implicit.
-- `opts.poolCapacity?: number` - defaults 32.
-- `opts.queueLimit?: number` - defaults 32.
+- `opts.buses?: string[]` - defaults ['sfx', 'ui', 'voice', 'music']. 'master' is implicit.
+- `opts.poolCapacity?: number` - defaults 32 (SFX per bus).
+- `opts.queueLimit?: number` - defaults 32 (pre-unlock queue).
 - `opts.mutedStorageKey?: string` - defaults 'lite_audio_muted'.
 - `opts.fetch?, opts.window?, opts.document?` - test injectables.
+- `opts.setTimeout?, opts.clearTimeout?` - test injectables for stopTrack teardown.
 
 ### async init(ctx?): Promise<void>
 Wires the engine to an AudioContext. Creates one via globalThis.AudioContext if none passed. Sets up master gain, bus gains, master-mute effect, per-bus volume+mute effects, statechange listener, unlock listeners.
 
-### async defineSounds(config): Promise<void>
-Fetches and decodes every sound in the config. Config shape:
-```
-{ [soundId]: { src: string[], bus?: string, volume?: number, pitchVar?: number } }
-```
-Resolves after every sound has settled. Load state per sound is a reactive signal readable via loadState(soundId). Pools are built (or rebuilt) once per touched bus at the end.
-
-### play(soundId, volume?, pan?, pitch?): number
-Positional hot path. Returns a handle >= 0 on success, -1 on any skip (unknown sound, not-yet-ready sound, context locked). Locked plays are queued (latest-per-sound, bounded by queueLimit) and flushed on unlock.
+### SFX (v1.0.0)
 
-### playOpts(soundId, opts?): number
-Sugar over play() with pitchVar resolution: `pitch = 1 + (rand*2-1)*pitchVar`.
+async defineSounds(config): fetch + decodeAudioData every sound. Config `{ [id]: { src: string[], bus?, volume?, pitchVar? } }`.
+play(soundId, volume?, pan?, pitch?): positional hot path, returns handle >= 0 or -1.
+playOpts(soundId, opts?): sugar with pitchVar resolution.
+stop(handle): stops a specific play. The handle carries its bus, so stop() resolves the owning pool in O(1) and can never reach across a bus boundary.
+isPlaying(handle): boolean. busOf(handle): string|null. activeCount(busName?): live SFX voices per bus or engine-wide.
+stopBus(name, opts?), stopAll(opts?): bus- and engine-wide stops. Both stop SFX voices AND fade out any music track routed to those buses (opts.fade, default 200ms).
+loadState(id): ReadSignal<'idle'|'loading'|'ready'|'error'>.
 
-### stop(handle): void
-Stops a specific play. Stale handles (channel stolen or already ended) are silent no-ops. The handle carries its bus, so stop() resolves the owning pool in O(1) and can never reach across a bus boundary.
+### Music (v1.1.0)
 
-### isPlaying(handle): boolean, busOf(handle): string|null, activeCount(busName?): number
-Liveness of one voice, the bus that issued a handle, and the live voice count per bus or engine-wide.
+async defineTracks(config): fetch + attach <audio> elements for streaming. Config `{ [name]: { src: string[], bus?, volume?, loop?, loopStart?, loopEnd? } }`.
+playTrack(name, opts?): starts or resumes. Opts `{ fadeIn?, position?, restart? }`. Idempotent unless restart.
+stopTrack(name, { fade? }): fades out, pauses element after fade. Playing signal flips false immediately.
+pauseTrack(name) / resumeTrack(name): position preserved.
+crossfade(from, to, durationMs): equal-power both sides. Either side can be null.
+playExclusive(name, opts?): bus-scoped - fades other playing tracks on same bus.
+playUnique(name, thresholdMs = 100): timestamp gate, works on sounds AND tracks. Returns a handle for a sound, -2 for a track (singleton, name-addressed), -1 on rejection or unknown. Never 0 for a track - 0 is a real handle.
+trackLoadState(name), trackPlaying(name), trackPosition(name), trackDuration(name): per-track signals.
 
-### stopBus(busName): void, stopAll(): void
-Bus- and engine-wide stops.
+### Crossfade semantics
+- Equal-power curves precomputed at module load (128 samples each: EQ_POWER_IN, EQ_POWER_OUT). Per-call scaled Float32Array per side is the only allocation, off the hot path (scene transitions).
+- Interruption (case c): only tracks named in the new call are touched. A track fading out from a previous crossfade keeps its schedule. A track being retargeted reads its current xfadeGain value and starts an equal-power ramp scaled from that value - no discontinuities.
+- Graph: <audio> -> MediaElementSource -> xfadeGain (0..1 crossfade knob) -> volumeGain (baseline volume) -> bus.gain
 
-### setBusVolume(name, v), setBusMuted(name, m), setMuted(state)
-Signal setters. Every write schedules a setTargetAtTime on the affected GainNode with a 10 ms time constant.
+### Bus + master
+setBusVolume(name, v), setBusMuted(name, m), setMuted(state): signal setters. Every write schedules setTargetAtTime with a 10 ms time constant.
 
 ### Reactive readables
-`ctxState() : ReadSignal<CtxState>`
+`ctxState() : ReadSignal<'suspended'|'running'|'interrupted'|'closed'>`
 `unlocked() : ReadSignal<boolean>`
 `muted() : ReadSignal<boolean>`
 `loadState(id) : ReadSignal<LoadState> | undefined`
+`trackLoadState(name), trackPlaying(name), trackPosition(name), trackDuration(name) : ReadSignal | undefined`
 `busVolume(name), busMuted(name) : ReadSignal | undefined`
 `busNode(name) : GainNode | undefined`
 `masterNode() : GainNode | null`
 
 ### destroy(): void
-Stops every voice, tears down pools (which disconnect their nodes), disposes signal effects, aborts unlock/lifecycle controllers, releases references. Idempotent. Does not close the AudioContext.
+Stops every voice, tears down SFX pools, tears down every track (pauses element, disconnects source + gains, removes timeupdate/ended listeners, cancels pending pause timers), disposes signal effects, aborts unlock/lifecycle controllers, releases references. Idempotent. Does not close the AudioContext.
 
 See Audio.js source for full inline documentation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-audio",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Zero-GC reactive Web Audio engine. Signal-driven buses, ABA-safe voice handles, unlock queue. SFX layer over @zakkster/lite-audio-pool.",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
   "license": "MIT",
@@ -39,13 +39,12 @@
   "scripts": {
     "test": "node --test test/*.test.js"
   },
-  "homepage": "https://github.com/PeshoVurtoleta/lite-audio#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/PeshoVurtoleta/lite-audio.git"
+    "url": "git+https://github.com/PeshoVurtoleta/lite-scheduler.git"
   },
   "bugs": {
-    "url": "https://github.com/PeshoVurtoleta/lite-audio/issues",
+    "url": "https://github.com/PeshoVurtoleta/lite-signal/issues",
     "email": "shinikchiev@yahoo.com"
   },
   "engines": {