feat(mobile): add playback speed and quality settings to the player

[Ur-imazing]

Summary

The mobile watch player now has viewer-controlled playback speed and stream quality. A gear button beside the AirPlay and Cast buttons opens a YouTube-style two-level sheet; a quality pick reloads the same Mux stream under a resolution constraint and resumes where the viewer was, and a speed pick applies at once — locally, and to the cast receiver while casting.

Session-settled decisions carried from planning: quality switches by reloading a constrained stream URL (user-directed, over a native expo-video patch — keeps delivery over-the-air); tiers map to a 480p cap, a 720p cap, and a 1080p floor (user-directed); speed-only while casting (user-directed); the sheet is component state, not a route (user-approved — a routed sheet cannot present over the fullscreen player); a quality reload holds the frame and never re-arms the opening veil (user-approved).

Design decisions

• One constraint seam. The host applies applyQualityConstraint to the resolved source URL and hands only the adapter the constrained URL. Host bookkeeping stays on raw URLs, and every swap — dub changes included — inherits the active tier. sameStreamSource/isSameMuxAsset compare by Mux playback id, so raw-vs-constrained URLs still match in the admission fallback.
• The swap guard learned constraints. The adapter coalesces two URLs only when they name the same Mux asset AND the same constraint. A constraint-only swap keeps the QoE session (a quality reload is not a session ending, R14) and suppresses the adapter's promise-time resume — the host's one-shot sourceLoad latch owns seek, rate, and play-state restore, because a seek at replaceAsync resolution is silently dropped.
• Failure release. A tier swap that errors or hangs releases within 8s: the pending resume clears, the tier reverts once (bounded by a null revertTier), and one namespaced log line records it. A no-op revert (the viewer already re-picked the revert tier) clears the latch outright instead of re-arming a timer-less one.
• Session scoping. Settings live in a module-scope store keyed by the host's slug-stable video key (the seed path flips videoId mid-playback, so an id-shaped key would falsely reset). resetFor re-keys on takeover; session endings (dismissed/abandoned/replaced) reset to defaults. A stored tier applies only when its key matches the current content, so a stale tier can never constrain the next video's first load.
• Cast speed. setCastPlaybackRate lives in the cast facade (SDK imports stay under src/lib/cast/); the sheet's pick while casting is fire-and-forget with a logged failure, and MediaLoadRequest.playbackRate carries the session speed so a starting session inherits it.
• Context variants. Casting shows speed only; offline (file://) and non-Mux streams hide the quality row (supportsQualityConstraint shares the parser with applyQualityConstraint, so the menu and the effect cannot disagree). The gear renders only where the chrome threads its callback, so the autostart veil's button row never shows it.

New concepts

Mux playback modifiers. Mux honors playback-behavior parameters directly on the public HLS URL: stream.mux.com/<id>.m3u8?max_resolution=720p caps the renditions the manifest offers, and min_resolution=1080p floors them; the stream still adapts inside the allowed band. This is why quality control needed no player API and ships over-the-air: the "setting" is a URL, and switching quality is an ordinary source swap. The trade-off is a visible reload on change (a native track-selection patch would switch seamlessly, but costs a two-platform patch on every SDK upgrade). Do not use modifiers on signed Mux URLs — there they must be JWT claims, not query params; current production streams are unsigned.

Testing

2478 tests green (162 suites), typecheck and eslint clean. Each unit landed proof-first (red observed before implementation), including a guard-falsification pair proving the new constraint comparison in the swap admission is load-bearing. Guard suites (player ownership, cast import boundary, Android compositing, suppression) extended, not bypassed. The change is OTA-shippable: no native module, config plugin, or app.json change.

Code review: ce-code-review (full roster + in-process adversarial; the cross-model pass did not run — the cursor-agent CLI was unauthenticated in its detached context, and no content egressed). Verdict "Ready with fixes"; all three actionable findings were applied here (the resume latch now takes the same cast and foreground vetoes as every sibling play() path; two edge-path tests pin the cross-asset invalidation and the replaced pause-skip; a no-op revert clears the latch). A fourth, P1-rated finding (a settings de-key cascade on replacement) was refuted by the independent validation pass — the interleaving is unreachable because reconcileSession ends the old session synchronously inside the request-store commit — and verified empirically.

Known residuals (informational)

• The replaced reset's safety rests on that synchronous in-commit ordering; it is load-bearing and implicit.
• PlaybackHost.tsx grew 1243 to 1456 lines; extracting a useQualityTierResume hook is the structural follow-up.
• Quality-swap failures count into the QoE error_count (a failed reload is a real viewer-visible error; left as a deliberate telemetry choice).
• Dismissing with a tier set issues one wasted replaceAsync on the dying player during the exit animation (accepted).
• Per-item sourceLoad multiplicity on rapid re-picks was only checkable on a device. Resolved in the merge with main: fix(mobile): recover wedged Android playback and correct picture-in-picture resume #2022's realistic mock exposed it, and the latch now consumes only the load of the currently requested source (recoverPlayback's fail-open payload rule), pinned by the U2 suite.
• After fix(mobile): recover wedged Android playback and correct picture-in-picture resume #2022's error recovery fires, a picked tier stays selected in the sheet while the stream runs unconstrained until the next pick — deliberate: the constrained stream is what errored, so recovering unconstrained is the safer default.

Outstanding device verification (owner: Urim)

1. Simulator smoke on birth-of-jesus: quality change resumes within ±2s at the selected speed (include one rapid re-pick), speed survives a mini-player round trip, gear present in portrait and fullscreen, sheet variants (cast / offline / non-Mux), and the dev-launch timing comparison for the page-load convention.
2. Mux floor probe: play a 720p-max asset at Highest; record here whether Mux serves the closest renditions or the logged uncapped fallback engaged.
3. Cast hardware: receiver rate change and load inheritance on a real Chromecast (emulators cannot discover receivers).

Post-Deploy Monitoring & Validation

• Datadog mobile logs: player_settings.quality_swap_released (release_reason=timeout|load_error) — a spike means constrained URLs are failing on real assets; cast.command_failed with cast_command=set_playback_rate.
• Datadog QoE: video.qoe error_count/rebuffer_count distributions and video.resume_failed should stay flat.
• Healthy: quality_swap_released near zero; QoE unchanged.
• Failure/rollback: eas update:rollback on the channel removes the feature — no schema or native surface.
• Validation window: first week of OTA rollout. Owner: Urim.

Work Loop

• ce:plan done
• ce:work done
• ce:review done
• ce:compound done

Notes

• Plan: docs/plans/2026-08-25-1454-feat-mobile-player-video-settings-plan.md (left uncommitted in the worktree by request-scope rules; say the word and it ships in a follow-up commit).
• Review artifacts: ce-code-review run 20260825-195258-f3a1.

---