refactor(player): extract the Sonos cast-session state machine from PlayerBar.tsx

[benders]

FROM @claude: Proposal from a codebase + issue-backlog analysis (2026-07-08). Plan written for execution by a coding agent.

Problem

frontend/src/components/player/PlayerBar.tsx is 933 lines and holds the entire Sonos cast-session state machine inside React effects and refs: track-advance detection (TrackURI change + pendingNextRef), scrobble-once arming (scrobbledRef, sessionStartPosRef), resume offsets across sink switches (baseOffsetRef, pendingBaseOffsetRef, pendingLocalSeekRef), device-switch teardown (prevDeviceIdRef), volume separation (local vs castVolume), and the polling loop.

This is the project's defect factory: ~15 closed Sonos bugs (#181, #182, #194, #198, #202, #204, #208…) and 4 open ones (#191, #192, #206, #207) trace to state transitions that can only be reproduced with real hardware, because the logic is welded to React lifecycle and SOAP polling. The pitfalls "Frontend" table is mostly a list of this file's regressions.

Extracting the session logic into a plain, dependency-free TypeScript state machine makes this bug class table-driven-testable, and is a prerequisite for #191 (Now Playing) and #192 (grouping), which both add more device state.

Related issues

• Unblocks Show Now Playing info for Sonos speakers #191 (Sonos Now Playing), Allow Sonos grouping (multi-room playback) #192 (grouping/multi-room), Sonos bug: Unexpected volume jumps during track switching #206 (volume jumps — likely fixed by this refactor or trivially after it), Clicking volume "speaker" icon when volume is at zero should set it low #207 (volume icon behavior).
• Refs Sonos: Use on device queue to prevent large playback gaps #202, Sonos casting: safer + better-synced volume handling #181, Sonos: seek restarts track from 0 on lossless pass-through #204 (closed bugs whose repro sequences become the test fixtures).

Design

stateDiagram-v2
    [*] --> Local
    Local --> Starting: castTo(deviceId)
    Starting --> Casting: device reports PLAYING
    Casting --> Casting: poll tick / volume / seek / setNext
    Casting --> Advancing: TrackURI changed (gapless auto-advance)
    Advancing --> Casting: jumpTo(cached pendingNext index)
    Casting --> Ended: STOPPED after PLAYING and no pendingNext
    Casting --> Local: switchToLocal (carry position offset)
    Casting --> Starting: switch device (teardown previous first)
    Ended --> Local

Loading

CastSession is a pure reducer: (state, event) → { state, effects[] }. Events come from two places only — user intents (play, pause, seek, setVolume, castTo, next, prev) and poll snapshots ({ transportState, trackUri, positionMs, volume }). Effects are descriptions ({ type: "sonosPlay", … }, { type: "scrobble", trackId }, { type: "stopDevice", deviceId }), executed by a thin React hook. No timers, no fetches, no React inside the machine — fully deterministic and unit-testable.

Encode the existing pitfall rules as invariants in the machine:

• next() on PLAYING → STOPPED is only the end-of-queue fallback; advance detection is TrackURI change (Sonos: Use on device queue to prevent large playback gaps #202).
• peekNext() result is cached in state and reused for both the set-next call and the post-advance jumpTo — never re-rolled under shuffle (Sonos: Use on device queue to prevent large playback gaps #202).
• Local volume and castVolume never cross (Sonos casting: safer + better-synced volume handling #181).
• Scrobble arms once per queue item id, not per sink switch (current scrobbledRef semantics — preserve exactly; one recording path per pitfalls Track play counts for local + peer media, expose via Subsonic API #197).

Implementation plan

1. frontend/src/features/player/cast-session.ts (new) — the reducer + types (CastState, CastEvent, CastEffect, createInitialState). Port the logic currently in PlayerBar's Sonos effects (~lines 60–500) ref-by-ref: each useRef becomes a named field of CastState with a comment mapping it back. Before creating the file: check frontend/eslint.config.js bounded-dir rules — features/player/ may not import from features/*-admin/; the machine imports nothing but types, so it satisfies any placement, but confirm components/player/PlayerBar.tsx is allowed to import from features/player/ (it should be; only features/* dirs are mutually restricted). If lint says otherwise, place it in frontend/src/lib/cast-session.ts and note why in the PR.
2. frontend/src/features/player/useCastSession.ts (new) — React hook owning: the poll interval, dispatching poll snapshots into the reducer, and executing effects via the existing API functions (sonosPlay, sonosSeek, sonosSetNext, sonosCommand, sonosSetVolume, getSonosState from frontend/src/lib/api.ts) and the player store (frontend/src/stores/player.ts). Scrobbling goes through the existing scrobble() in frontend/src/lib/subsonic.ts.
3. frontend/src/components/player/PlayerBar.tsx — delete the Sonos effect blocks and refs; keep local <audio> handling, rendering, and the isSonos branch points, consuming useCastSession. Target: PlayerBar under ~450 lines with zero Sonos-protocol knowledge.
4. No backend changes. hub/src/routes/sonos.ts untouched.

Testing plan

Table-driven tests are the point of this refactor — each historical bug becomes a fixture:

• frontend/src/features/player/cast-session.test.ts (new), pure reducer tests, no React:
  • Sonos: Use on device queue to prevent large playback gaps #202 gapless: poll sequence PLAYING(uriA) → PLAYING(uriB) → exactly one jumpTo effect with the cached next index; no next() re-roll under shuffle.
  • Sonos: Use on device queue to prevent large playback gaps #202 end-of-queue: PLAYING → STOPPED with empty queue → Ended, no advance.
  • Sonos bug: Unexpected volume jumps during track switching #206 volume: replay a poll sequence around track switch and assert no sonosSetVolume effect is emitted unless the user changed volume (this test should reproduce the reported jump — if it does, fix inside the machine and close Sonos bug: Unexpected volume jumps during track switching #206 in this PR; if not, document findings on Sonos bug: Unexpected volume jumps during track switching #206).
  • Device switch: castTo(B) while casting to A → stopDevice(A) effect precedes play on B (Sonos cast: stop playback on previous device when destination changes #198 regression guard).
  • Sink switch position: Casting → Local carries positionMs into the local-seek effect (pendingLocalSeekRef semantics, Sonos cast: resume from current playback position #194/Sonos: seek restarts track from 0 on lossless pass-through #204).
  • Scrobble: threshold crossing emits exactly one scrobble per queue item across sink switches.
• frontend/src/components/player/PlayerBar.test.tsx (617 lines, exists): must keep passing with minimal mock changes; follow docs/frontend-testing.md patterns.
• Boundary: pnpm lint:boundary zero output; extend frontend/src/features/boundary-lint.test.ts only if a new carve-out was needed.
• pnpm verify for the repo; no federation suite needed (no /rest/* change) — but if any scrobble call path changes, re-read pitfalls Track play counts for local + peer media, expose via Subsonic API #197 first.
• Manual hardware pass (note in PR for the user): cast, gapless advance ×2, volume change, device switch, cast→local resume. Agent cannot do this — list it as a checklist in the PR description.

Acceptance criteria

• cast-session.ts imports nothing from React, lib/api.ts, or the store — pure types + reducer.
• Every pitfalls "Frontend" row about Sonos has a corresponding named test case.
• PlayerBar.tsx contains no useRef whose comment mentions Sonos protocol behavior.

Agent execution notes

Read docs/sonos.md, docs/pitfalls.md ("Frontend", "Sonos cast"), and docs/frontend-testing.md first. This is Player-side frontend work: obey the Hub/Player boundary section of AGENTS.md. Feature branch + Draft PR; commit the machine+tests before rewiring PlayerBar.