Audio: one owner for the context, and the Safari suspend that wedged it

[obiot]

Fixes a Safari-only failure confirmed by @obiot: a page left idle for thirty seconds before its first click lost every loaded clip for the life of the page, while tone() and noise() kept playing.

Why that asymmetry is the whole diagnosis

The generators need only a live context. Sound#play goes through the engine's state machine. So "tones audible, clips silent" means the context is healthy and the engine's bookkeeping is wrong — it is never a context problem.

The wedge

1. No gesture yet, so the context is suspended. The thirty-second idle timer arms.
2. It fires: state = "suspending", then ctx.suspend(). WebKit never settles that promise when the suspend is asked for outside a user gesture, on a context the page was never allowed to start. There is no "already suspended, resolve now" shortcut, and an engine waiting on that promise never issues another suspend.
3. First click. _autoResume()'s "suspending" branch only raised a flag for the settlement to act on. But the unlock path's own scratch ctx.resume() ran in the same gesture and started the hardware.
4. Final state: context running, engine "suspending", forever. Every play() sees state !== "running", sets _playLock and parks on once("resume", ...). Nothing will ever emit it.

A resume requested while the suspend is in flight is now issued at once; the context orders it after the suspend, so the last request wins. _resumeAfterSuspend is gone.

Chromium and Firefox settle that promise immediately, which is why this reproduced on the reporter's machine every time and never once in automation. Playwright's WebKit build does not carry Safari's gesture restriction either, so it is unreachable from a harness here. The fix is pinned by a unit test that stubs ctx.suspend to a promise that never settles, fake-times the idle window, and asserts the clip actually plays after the click.

The structure that made it possible

The context had two owners: the engine held it and ran its own recovery, while the procedural generators carried a private _resumeIfSuspended they called before every beep. One context, two owners, and only one of them ever restarted it.

src/audio/context.ts is now the only thing that takes, drops or revives a context, and both sides go through it. It sits outside backend/ because that directory is the vendored howler derivative and this is our own code.

class AudioContextOwner {
  get current(): AudioContext | null
  attach(ctx); detach()
  requestResume()        // a person is interacting: resume even a deliberate suspension
}
interface AudioContextDelegate {
  isRunning(): boolean   // the delegate's view, NOT ctx.state
  resume(): void         // resume with the bookkeeping only it can do
}

Three rules it makes structural rather than conventional:

1. The recovery listeners read the current context when they fire instead of capturing one, so the context swap the unlock performs (sampleRate !== 44100) cannot strand them.
2. A statechange recovers only when the engine still believes it is running, so the deliberate idle suspend is left alone; a gesture or the tab returning always recovers, including when the engine and the context disagree.
3. Reviving goes through _autoResume() so state is corrected and "resume" reaches parked voices. A bare ctx.resume() restarts the hardware and leaves them silent underneath it.

The engine keeps _autoResume/_autoSuspend — those are playback bookkeeping, and moving them would have dragged sounds[], _playLock and the event into the owner, which is the coupling this avoids. It lost _watchContext, _recoverContext and _recoveryArmed.

Named against the Web Audio API: requestResume, isRunning, resume, attach, detach.

Also fixed on the way

• unload() never called detach(), so a failed recreate left the owner pointing at a closed context.
• The unlock completed only from the scratch source's onended; a one-sample buffer in a context that stays suspended never ends, so a refused gesture left the engine half-unlocked with "unlock" never sent. A resolved resume() completes it too.

Verification

• 172 audio tests (from 162), backend spec 57
• Eleven mutations against the final tree, all killed, including the one-line "suspending" fix, the gesture net, the visibility net, the identity check, and a delegate doing a bare ctx.resume()
• tsc --noEmit clean; pnpm lint 0 errors
• debug-plugin 23, matter-adapter 226, planck-adapter 221, all green
• Confirmed working in real Safari by the reporter

Both changelogs updated: the root one for the user-facing fix, and the backend's own for the fork's changes, including a ### Changed note that the engine no longer owns the context's lifetime, since that is a divergence anyone applying an upstream PR needs to know about.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NGvtaUNATVCVxD2qcbiY4t

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.