fix(web): avoid duplicate audiobook playback starts

[Quick104]

Summary

• wait for the shared browser capability probe to settle before starting audiobook playback
• cover the startup lifecycle with a regression test that holds the async probe open and proves exactly one session is created
• record the user-visible fix in the feature changelog

Cause

Commit 4b6c05e18 in PR #634 made the shared codec probe publish an explicit unsettled state and a final settled state. The video player waited for the final state, but the audiobook hook still started on every capability object change. One render therefore issued three POST /playback/start requests in CI.

This change applies the same settled gate to audiobook startup while preserving the existing cleanup when no active file exists.

Validation

Passed:

• pnpm exec vitest run src/pages/audiobooks/player/useAudiobookPlayback.test.ts — 16 tests
• pnpm run lint — 0 errors; 155 existing warnings
• pnpm run format:check
• pnpm run build
• make test-web — 285 files, 2,067 tests
• go build ./...
• tracked-file gofmt check
• go vet ./...
• golangci-lint run --new-from-merge-base="origin/main" ./... — 0 issues
• make verify-settings-bindings-all
• make verify-playback-fixtures
• make verify-local-paths

make test-go completed all packages except two existing macOS process-lock tests in internal/jellycompat: TestBeginWebOperationRecoversDeadProcessLock and TestBeginWebOperationRejectsLiveProcessLock. Both failures reproduce unchanged in a detached clean origin/main worktree. The main-branch GitHub Actions Go job at a0a31e891 passed on Linux.

Manual browser playback was not run; the session-start lifecycle is covered at hook level.

Related issue: N/A — narrow regression after #634

AI Disclosure

• Tool(s): T3 Code with Codex
• Model(s): gpt-5.6-sol
• Involvement: Fully AI-generated; human verification pending
• Adversarial review: Traced the codec-probe and session-effect lifecycle, compared the video and audiobook consumers, checked the no-active-file cleanup path, and added a controlled async-probe regression test. The review found and corrected an early-return ordering edge case before publication.

Summary by CodeRabbit

• Bug Fixes

  • Improved audiobook playback startup by waiting for browser capability detection to complete before beginning playback.
  • Prevented repeated playback session creation and replacement during startup.

• Tests

  • Added coverage confirming playback starts exactly once after capability detection finishes.

• Documentation

  • Documented the updated audiobook playback behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ab08cfd4-6fc0-4e5c-9899-840ec619e6ca

📥 Commits

Reviewing files that changed from the base of the PR and between a0a31e8 and 6318c49.

📒 Files selected for processing (3)

• docs/feature-changelog.md
• web/src/pages/audiobooks/player/useAudiobookPlayback.test.ts
• web/src/pages/audiobooks/player/useAudiobookPlayback.ts

Included review availability: 4 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 5 reviews per hour.

---

📝 Walkthrough

Walkthrough

Audiobook playback now waits for browser codec capability detection to settle before requesting a playback session. Test coverage verifies that pending detection causes no request and that playback starts once after detection resolves. The feature changelog documents this behavior.

Changes

Audiobook playback initialization

Layer / File(s)	Summary
Capability-gated playback session start web/src/pages/audiobooks/player/useAudiobookPlayback.ts, web/src/pages/audiobooks/player/useAudiobookPlayback.test.ts, docs/feature-changelog.md	The playback-session effect waits for settled codec detection and retries when detection completes. Tests verify one session request after an unsupported probe result. The changelog records the behavior.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 6318c

This localized change prevents duplicate audiobook playback starts while preserving existing cleanup behavior, with regression coverage and validation completed; no actionable merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (1 skipped: 1 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: preventing duplicate audiobook playback starts in the web client.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (1 skipped: 1 unsupported.)

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch t3code/fix-audiobook-duplicate-start

---

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6318c49c66

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Keep the active session alive while the probe refreshes

When a display-route matchMedia change invokes useCodecDetection.refresh, it first publishes settled: false and may leave decodingInfo() pending. This dependency change runs the previous effect's cleanup—deleting the active playback session—before this early return, while no replacement starts until the probe settles. Moving the browser between HDR and SDR displays can therefore interrupt a playing audiobook for the duration of a slow probe, or indefinitely if it stalls; retain the active session until the final capabilities are available.

AGENTS.md reference: AGENTS.md:L62-L64

Useful? React with 👍 / 👎.