Bound match boot's wait on the voice-over manifest

[Knorcedger]

What changed?

Starting a match blocked on fetching the optional voice-over manifest with no timeout: a connection that accepts and then stalls (captive portal, wedged CDN edge) left bootGame hanging on a black screen after START, and the stalled promise was cached for the whole session.

The wait is now bounded and the cache made failure-aware:

• loadVoiceManifest races its fetch and body read against the abort signal, so the bound holds even where the platform's fetch never surfaces the abort (this is also what lets the stall test drive it with a never-settling fetch).
• Match boot goes through a new createVoiceManifestFetch(): one bounded attempt (2 s, AbortController + timer) cached per session. An attempt the server never answered — timed out, offline, refused — resolves empty so the match starts on time with synthesised narration, and is not kept, so the next match retries. A real answer (manifest, or the 404 of a build with no recordings) stays cached as before. The fetch can never reject out of boot, whatever the load does.
• bootGame kicks the fetch off before artwork loading, so the bound overlaps asset loading instead of stacking a serial wait on it; the happy path gains no delay.

Related issue

Closes #148

Why this approach?

• The bound lives inside loadVoiceManifest (not just in the caller's signal) because fetch only rejects on abort when the platform honours it — a stalled connection on a sloppy WebView stack is exactly the case the timeout exists for.
• AbortController + setTimeout instead of AbortSignal.timeout, which iOS 15 WKWebView and stale Android System WebViews (< Chrome 103) lack — the platforms most likely to sit behind a captive portal.
• Retry-next-match applies to every unanswered attempt, not only timeouts: an airplane-mode boot must not silence recordings until app restart, while a 404 is the build's real "no recordings" and stays cached.
• Considered reusing boundedAssetLoad/scopedAbortSignal from assets.ts: declined because boundedAssetLoad awaits its operation without racing (it would hang on a fetch that ignores its signal, hiding the exact bug), scopedAbortSignal is module-private, and importing the pixi-heavy atlas loader into the audio module inverts the dependency direction. The controller pattern is reused; the helpers are not.
• Out of scope, per the issue: in-boot retries, progress UI, and the recorded/synthesised seam (createRecordedSpeech is untouched).

Verification

• npm run typecheck
• npm test (17/17 in recordedSpeech.test.ts, full suite green)
• npm run build (via npm run check, incl. bundle budget)
• I added or updated tests where behavior changed — stall bounded with a never-settling fetch (headers and body variants), happy path parses, answered results cached, timed-out/rejected/synchronously-throwing attempts resolve empty and retry next match
• I included screenshots or a recording for visible changes — n/a, no visible changes (boot no longer hangs; nothing looks different)

Provenance and AI assistance

Implemented and reviewed with Claude Code (analysis, code, tests, and this PR); no third-party assets involved.

Contributor checklist

• I searched issues and active pull requests before implementation and coordinated ownership in the linked issue
• This pull request closes or references exactly one primary coordination issue
• I read CONTRIBUTING.md and followed the deterministic simulation rules
• I reviewed and understand every submitted change
• I have the right to submit this code and any included assets
• My commits are signed off under the Developer Certificate of Origin (git commit -s)
• This PR contains no credentials, private player data, or unlicensed third-party material

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
bannerfall	Ready	Preview	Aug 23, 2026 9:25am