refactor(audio): centralize playback intent and context recovery

[cptbtptpbcptdtptp]

Summary

• Separate caller intent (running or suspended), physical AudioContext state, and pending AudioSource playback requests.
• Let AudioSource register and cancel playback intent instead of depending on one resume Promise settling.
• Coalesce ordinary programmatic resume attempts, while allowing every trusted gesture to issue a fresh native resume when an older attempt is still pending.
• Reconcile AudioContext state changes centrally, preserve explicit suspend across races, and include pending sources in foreground recovery demand.
• Keep the public AudioManager API unchanged.

Root cause

Web Audio may leave resume pending while the context is not yet allowed to start: https://www.w3.org/TR/webaudio-1.1/#dom-audiocontext-resume

The previous implementation made each AudioSource await one cached resume Promise. A pre-gesture call could therefore remain pending indefinitely, and later gestures reused the same Promise instead of reaching the native AudioContext. Explicit caller suspension, autoplay unlock, and foreground recovery also shared the same resume path, so a source play could erase caller-controlled suspend state. Finally, foreground recovery only counted already-playing sources and ignored pending playback demand.

Resulting state model

• Desired state: explicit AudioManager suspend/resume intent.
• Physical state: AudioContext state, reconciled through statechange.
• Playback intent: manager-owned pending callbacks, drained only when desired and physical states both allow playback.
• Recovery: automatic attempts are single-flight; gesture attempts can bypass stale pending attempts; explicit suspend always wins races.

Regression coverage

The audio lifecycle suite now covers:

• rejected and indefinitely pending cold-start resume;
• repeated trusted gestures;
• multiple pending AudioSources;
• stop/pause cancellation;
• explicit suspend versus source play and resume races;
• pending-only foreground recovery;
• visibility, bfcache, and iOS interrupted-context recovery.

Verification

• pnpm vitest run tests/src/core/audio --reporter=dot: 41 passed
• pnpm b:types: passed for all workspace packages
• pnpm b:module with Node 22.19: passed
• Prettier check: passed
• ESLint: no errors and no new warnings
• git diff --check: passed

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e7c06e0d-d168-4430-8c59-ac39ca3a03b6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 81.28342% with 35 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.50%. Comparing base (2a4b86a) to head (bdb23c1).

Files with missing lines	Patch %	Lines
packages/core/src/audio/AudioManager.ts	84.04%	26 Missing ⚠️
packages/core/src/audio/AudioSource.ts	62.50%	9 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           dev/2.0    #3097      +/-   ##
===========================================
- Coverage    85.69%   85.50%   -0.19%     
===========================================
  Files          811      811              
  Lines        94785    94831      +46     
  Branches     11542    11585      +43     
===========================================
- Hits         81223    81084     -139     
- Misses       13474    13657     +183     
- Partials        88       90       +2     

Flag	Coverage Δ
unittests	85.50% <81.28%> (-0.19%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.