alteropen/streamyfin
1
0
Fork 0
mirror of https://github.com/streamyfin/streamyfin.git synced 2026-07-17 09:53:02 +01:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

chore: stop tracking docs/superpowers workflow artifacts

Browse Source 
Local superpowers planning docs (handoff/plans/specs), never meant for
the repo. Untrack them; files kept locally.
This commit is contained in:
Gauvain
2026-06-01 23:17:45 +02:00
parent 985cb0f337
commit f4a68bca10
12 changed files with 0 additions and 5463 deletions
Download Patch File Download Diff File Expand all files Collapse all files

199
docs/superpowers/chromecast-refactor-handoff.md
View File

@@ -1,199 +0,0 @@
# Chromecast Refactor — Handoff & Resume Document
**Branch:** `refactor-chromecast` · **PR:** #1402 (draft) · **Last updated:** 2026-05-22
This document captures the full state of the Chromecast refactor so the work can be
resumed in a later session. Specs and plans for each sub-project live in
`docs/superpowers/specs/` and `docs/superpowers/plans/`.
---
## 1. Summary
The Chromecast casting code (PR #1402) was refactored across five sub-projects, a
prep task, and small cleanups. All sub-projects are **implemented, type-checked, and
unit-tested**; the branch has dozens of commits unpushed to
`origin/refactor-chromecast` (run `git log origin/refactor-chromecast..HEAD`).
| Sub-project | What | Status |
|---|---|---|
| **A** — Device profiles | Per-device capability detection, profile builder, unified `loadCastMedia`, crash fixes (status 2100, 5.1, bitrate) | ✅ done, **verified on hardware** |
| **Prep #1367** — Segment-skip | Backport segment-skip fixes to PR #1367, remove 177 dead lines | ✅ done, **pushed to #1367** |
| **B** — Track switching | `CastSelection` source-of-truth via customData, audio/subtitle/quality/version switching, multi-version | ✅ done, **verified on hardware** |
| **C** — Player split | `casting-player.tsx` 1428→574 lines: 6 components + 4 hooks | ✅ done, **needs manual re-test** |
| **D** — Session & remote control | Correct PlayMethod, conditional episode buttons, `loadEpisode` race fix, app-wide Jellyfin remote control | ✅ done, **needs manual test** |
| **UX player** — Trickplay & mini-player | Trickplay bubble clamp via `bubbleWidth`, shared `CastTrickplayBubble`, plain-text time, mini-player stop button, `DEBUG_TOUCH_ZONES` overlay | ✅ done, **needs manual test** |
| Loose ends | Dead `liveProgress` export removed, `BitRateSheet` duplicate removed, full-width labelled stop button for movies | ✅ done |
Verification gate for the whole branch: `bun run typecheck` ✅, `bun test utils/` ✅
(32 tests). Note: project-wide `bun run check` shows ~124 pre-existing CRLF errors —
a Windows `core.autocrlf` artifact, unrelated to this work (see §6).
---
## 2. Sub-project A — Device profiles & capability detection
**Spec:** `specs/2026-05-21-chromecast-profiles-design.md` · **Plan:**
`plans/2026-05-21-chromecast-profiles.md` · **Commits:** `bcfa8c6d`..`73214f5d`
Replaced the two static device profiles with `detectCapabilities()` +
`buildChromecastProfile()` (`utils/casting/capabilities.ts`, `buildProfile.ts`), a
unified `loadCastMedia()` (`utils/casting/castLoad.ts`) with downgrade-on-failure,
and `chromecastProfile` / `chromecastMaxBitrate` settings replacing
`enableH265ForChromecast`. Fixed the audio-index, media-source, and PlaySessionId
load-path bugs.
**Verified:** all 7 test-matrix files cast successfully on the Chromecast HD,
including a 50 Mb/s HEVC-10bit movie that previously crashed with status 2100.
---
## 3. Prep — Segment-skip reconciliation (PR #1367)
The chromecast branch and PR #1367 (`autoskip`) both carried segment-skip; #1367 was
behind. The chromecast branch's fixes were backported to the `autoskip` branch
(`useSegmentSkipper` auto-skip-by-identity, `Controls` stale-closure fix, `segments`
cleanup) and the two dead hooks `useIntroSkipper`/`useCreditSkipper` (177 lines) were
removed. **Commit `0990e479` is pushed to `origin/autoskip` — PR #1367 is updated.**
The `page.tsx` plugin-lock lines were not backported (depend on a newer
`PlatformDropdown` not on #1367's base — will arrive when #1367 rebases on develop).
---
## 4. Sub-project B — Track switching & multi-version
**Spec:** `specs/2026-05-21-chromecast-track-switching-design.md` · **Plan:**
`plans/2026-05-21-chromecast-track-switching.md` · **Commits:** `3d65c3bb`..`23b4f20d`
`CastSelection` (`utils/casting/selection.ts`) is the single source of truth, carried
in cast `customData` and read back by `hooks/useCastSelection.ts` with an optimistic
pending overlay. Audio / subtitle / quality / version switching all reflect reality.
The shared `BITRATES` ladder (`components/BitrateSelector.tsx`) was expanded; the cast
quality menu filters it by device capability and media bitrate.
**Verified:** audio (Bleach JP↔FR), SubRip subtitles, and bitrate switching all work
on hardware — which also confirms the `customData` round-trip.
---
## 5. Sub-project C — `casting-player.tsx` split
**Spec:** `specs/2026-05-22-chromecast-player-split-design.md` · **Plan:**
`plans/2026-05-22-chromecast-player-split.md` · **Commits:** `02df2477`..`1ea7f0f4`
Decomposed the 1428-line god-component into a 574-line orchestrator + 6
presentational components (`components/casting/player/`) + 4 hooks
(`useCastPlayerItem`, `useCastEpisodes`, `useCastDismissGesture`,
`useCastPlayerProgress`). Purely structural — zero behaviour change.
**Needs manual re-test:** the cast player has no unit tests; re-test cast + episode
playback, track switching, scrub/trickplay, dismiss — behaviour must match pre-split.
---
## 6. Sub-project D — Session reporting & remote control
**Spec:** `specs/2026-05-22-chromecast-session-remote-control-design.md` · **Plan:**
`plans/2026-05-22-chromecast-session-remote-control.md` · **Commits:**
`288b390e`..`8b94f491`
- Cast sessions now report the real `PlayMethod` (`Transcode`/`DirectPlay`).
- Episode Previous/Next buttons render only when an adjacent episode exists.
- `loadEpisode`/`currentItem` stale-flash race fixed via `loadingEpisodeId`.
- **App-wide Jellyfin remote control:** a `PlaybackController` contract
(`utils/playback/playbackController.ts`); a pure WS-message mapper
(`utils/playback/remoteCommands.ts`, unit-tested); `hooks/useRemoteControl.ts`
dispatches to whichever player (cast / native video / music) is registered.
`WebSocketProvider` advertises the commands and routes the messages.
**Needs manual test:** from the Jellyfin dashboard's active-session panel — pause /
stop / seek / next / volume / "send message" against the cast and the native player.
---
## 7. Pending work (queue)
- **UX player sub-project** — ✅ done (see the UX player row in §1; spec/plan
`2026-05-22-chromecast-ux-player`). Trickplay truncation, time display, mini-player
trickplay + stop button all fixed. Remaining there: the user hand-calibrates the
slider `panHitSlop` using the `DEBUG_TOUCH_ZONES` overlay (flag in
`utils/casting/debug.ts` — flip to `true`, calibrate, flip back).
- **Repo hygiene** — add `* text=auto eol=lf` to `.gitattributes` (fixes the ~124
CRLF errors in `bun run check`); this is best done as a separate PR off `develop`,
since a `git add --renormalize` touches the whole tree. (The `BitRateSheet.tsx`
duplicate and the unused `liveProgress` export have already been removed.)
- **Custom Cast receiver** (deferred from sub-project A) — PR #1521 builds a custom
CAF receiver. Decided to defer; revisit as its own sub-project. It would own
subtitle rendering/styling (ASS, custom style — issues #1452, #1543) and cleaner
session integrity. Sender-side work so far does not block it.
- **Open review notes** (low severity, not fixed):
- D: the `PlaybackController` registry is last-write-wins; the spec's "cast
precedence" is not actually enforced (acceptable — one player at a time).
- D: remote next/previous works for cast but is a no-op for the native video
player (its episode navigation lives in `Controls`, not the screen).
- A: `getStreamUrl` still takes `MediaSources[0]` internally — fine because
`getPlaybackInfo` is called with `mediaSourceId`.
---
## 8. How to resume
1. **Test the branch.** Build from `refactor-chromecast` (`bun run android`). Run the
sub-project C manual re-test and the sub-project D dashboard remote-control test.
Sub-project A's matrix is `docs/chromecast-test-matrix.md`.
2. **Push.** When satisfied, push `refactor-chromecast` to update draft PR #1402
(46 commits unpushed). Decide first what to do with the two uncommitted files
(see §9).
3. **Continue.** Pick the next sub-project from §7 — likely the UX player sub-project.
Each sub-project follows the brainstorm → spec → plan → subagent-execution cycle;
specs/plans go in `docs/superpowers/`.
---
## 9. Working-tree / repo notes
- **Uncommitted, intentionally left for the user to decide:**
- `docs/chromecast-test-matrix.md` — modified to list the user's actual library
titles (anime/movies). If PR #1402 should not expose the personal library, revert
this file to its generic committed form before pushing.
- `scripts/find-test-media.ts` — untracked helper that queries Jellyfin and buckets
the library against the test matrix. Commit it if useful, or leave it local.
- **Commits:** this project does **not** use a `Co-Authored-By` trailer.
- **GPG:** committing requires a warm `gpg-agent` cache; `~/.gnupg/gpg-agent.conf`
was set to an 8h TTL.
---
## 10. Key decisions
- **#1367 is the source of truth for segment-skip** — backport flows chromecast →
#1367, never the reverse.
- **Custom receiver deferred** — the crash fixes (A) were decoupled from it; it is a
future sub-project, not a blocker.
- **Long-term goal:** support AirPlay and other cast protocols — the casting layer is
kept protocol-agnostic (`CastProtocol`). The user has an iOS phone and an
AirPlay-capable Samsung screen for testing.
---
## 11. Player feature ideas (proposed, not yet scoped)
Candidate enhancements for the cast player — each would be its own brainstorm →
spec → plan → execute cycle. The user reacted positively to all of these.
1. **Autoplay next episode + countdown** — an "Next episode in 10s · Cancel" overlay
when an episode ends on the cast. The native player already has go-to-next-episode
countdown logic to port.
2. **Sleep timer** — "stop after this episode / in 30 min".
3. **Resume prompt** — "Resume at 12:34 / Start over" when casting a partially-watched
item.
4. **Chapter markers on the progress bar** — Jellyfin exposes chapters; show ticks +
tap-to-jump.
5. **OS media controls** — control the cast from the OS media notification /
lock screen. **Must be cross-platform:** Android media notification *and* iOS
Now Playing / Control Center. iOS infrastructure already exists
(`modules/mpv-player/ios/MPVNowPlayingManager.swift`) and there are existing PRs
touching the iOS mini-controller / now-playing — reference them before designing.
6. **SyncPlay on cast** (larger) — synchronised group viewing; a `feat/syncplay`
branch exists.

1313
docs/superpowers/plans/2026-05-21-chromecast-profiles.md
View File

File diff suppressed because it is too large Load Diff

1216
docs/superpowers/plans/2026-05-21-chromecast-track-switching.md
View File

File diff suppressed because it is too large Load Diff

409
docs/superpowers/plans/2026-05-22-chromecast-player-split.md
View File

@@ -1,409 +0,0 @@
# Chromecast Player Split — Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Decompose the 1428-line `app/(auth)/casting-player.tsx` god-component into 4 hooks + 6 presentational components + a thin orchestrator, with zero behaviour change.
**Architecture:** Each task extracts one JSX section into a presentational component (`components/casting/player/`) or one logic cluster into a hook (`hooks/`), then rewires `casting-player.tsx` to use it. Purely mechanical — moved code, not new code. State flows orchestrator → components by typed props.
**Tech Stack:** TypeScript (strict), React Native / Expo, `react-native-google-cast`, `react-native-reanimated`, `react-native-gesture-handler`.
**Spec:** `docs/superpowers/specs/2026-05-22-chromecast-player-split-design.md`
**Environment note:** Windows checkout, `core.autocrlf=true` — project-wide `bun run check` reports ~124 pre-existing CRLF errors unrelated to this work. The gate is `bun run typecheck` (fully green) plus Biome on the files each task edits.
---
## Hard rules for every task
1. **Zero behaviour change.** This is a mechanical extraction. Move code; do not rewrite logic, rename behaviour, fix bugs, or "improve" anything. Known issues stay untouched (they belong to a later UX sub-project).
2. **Read `app/(auth)/casting-player.tsx` first.** It is large (~1400 lines). Locate the section by the quoted `{/* comment */}` anchor, not line numbers.
3. **Derive interfaces from real usage.** A component's props = exactly the values the extracted JSX references from the surrounding scope (state, derived values, handlers). A hook's return = exactly the values the rest of `casting-player.tsx` still needs. Type every prop / return field explicitly — no `any`.
4. **`bun run typecheck` must be fully green** before each commit. It is the safety net that catches a missed prop or broken wiring.
5. Preserve imports: when a section moves out, move its imports too; remove imports from `casting-player.tsx` that it no longer uses.
---
## File Structure
| File | Responsibility | Task |
|---|---|---|
| `components/casting/player/CastPlayerHeader.tsx` | Dismiss chevron, connection indicator, settings button | 1 |
| `components/casting/player/CastPlayerTitle.tsx` | Title + episode/season info | 1 |
| `components/casting/player/CastPlayerPoster.tsx` | Poster image, buffering overlay, skip intro/credits bar | 2 |
| `components/casting/player/CastPlayerEpisodeControls.tsx` | 4-button row (Episodes / Previous / Next / Stop) | 3 |
| `components/casting/player/CastPlayerProgressBar.tsx` | Slider, trickplay preview, time display | 4 |
| `components/casting/player/CastPlayerTransportControls.tsx` | Rewind / play-pause / forward | 5 |
| `hooks/useCastPlayerItem.ts` | `fetchedItem` + fetch + `currentItem` derivation | 6 |
| `hooks/useCastEpisodes.ts` | `episodes`/`nextEpisode`/`seasonData` + fetches + `loadEpisode` | 7 |
| `hooks/useCastDismissGesture.ts` | dismiss gesture / animated style | 8 |
| `hooks/useCastPlayerProgress.ts` | slider, scrubbing, live progress, trickplay | 9 |
| `app/(auth)/casting-player.tsx` | Thin orchestrator | all |
Tasks 1-5 extract components (the orchestrator keeps all logic, just renders `<X/>`).
Tasks 6-9 extract hooks. Task 10 finalises and verifies.
---
## Task 1: Extract `CastPlayerHeader` and `CastPlayerTitle`
**Files:**
- Create: `components/casting/player/CastPlayerHeader.tsx`, `components/casting/player/CastPlayerTitle.tsx`
- Modify: `app/(auth)/casting-player.tsx`
- [ ] **Step 1: Create `CastPlayerHeader.tsx`**
In `casting-player.tsx`, locate the JSX under `{/* Header - Fixed at top */}` (the `<View>` containing the dismiss `Pressable` with the `chevron-down` icon, the connection-indicator `Pressable`, and the settings-button `Pressable` with `settings-outline`).
Create `components/casting/player/CastPlayerHeader.tsx` as a presentational component containing exactly that JSX. Define a `CastPlayerHeaderProps` interface for every value the JSX references from the outer scope — e.g. the dismiss handler, the connection state / device name shown in the indicator, the connection-indicator press handler, the settings press handler, and any style insets. Type each explicitly. Move the icon/`Text`/`Pressable` imports the component needs.
- [ ] **Step 2: Create `CastPlayerTitle.tsx`**
Locate the JSX under `{/* Title Area */}` (the `<View>` with the title `Text` and the grey episode/season info `Text`). Create `components/casting/player/CastPlayerTitle.tsx` the same way — a `CastPlayerTitleProps` interface for exactly what it references (title string, episode/season info string or the item fields it derives them from — keep the derivation identical to the original).
- [ ] **Step 3: Rewire `casting-player.tsx`**
Replace the `{/* Header - Fixed at top */}` block with `<CastPlayerHeader ... />` and the `{/* Title Area */}` block with `<CastPlayerTitle ... />`, passing the props. Add the two imports. Remove now-unused imports from `casting-player.tsx`.
- [ ] **Step 4: Verify**
Run: `bun run typecheck`
Expected: PASS — fully green.
Run: `bunx biome check components/casting/player/CastPlayerHeader.tsx components/casting/player/CastPlayerTitle.tsx "app/(auth)/casting-player.tsx"`
Expected: PASS on these files.
- [ ] **Step 5: Commit**
```bash
git add components/casting/player/ "app/(auth)/casting-player.tsx"
git commit -m "refactor(casting): extract CastPlayerHeader and CastPlayerTitle"
```
---
## Task 2: Extract `CastPlayerPoster`
**Files:**
- Create: `components/casting/player/CastPlayerPoster.tsx`
- Modify: `app/(auth)/casting-player.tsx`
- [ ] **Step 1: Create the component**
Locate the JSX under `{/* Poster with buffering overlay */}` (inside the scrollable content area) — the poster `Image`, the empty-poster fallback `View` with the `film-outline` icon, the `{/* Skip intro/credits bar */}` block, and the `{/* Buffering overlay */}` block with the `ActivityIndicator`.
Create `components/casting/player/CastPlayerPoster.tsx` containing that JSX. Define `CastPlayerPosterProps` for everything it references: the poster URL, buffering state, the skip-segment data and skip handlers, the translation function if used, etc. Type each field. Move the imports it needs.
- [ ] **Step 2: Rewire**
Replace the poster block in `casting-player.tsx` with `<CastPlayerPoster ... />`. Add the import; drop unused imports.
- [ ] **Step 3: Verify**
Run: `bun run typecheck`
Expected: PASS — fully green.
Run: `bunx biome check components/casting/player/CastPlayerPoster.tsx "app/(auth)/casting-player.tsx"`
Expected: PASS on these files.
- [ ] **Step 4: Commit**
```bash
git add components/casting/player/CastPlayerPoster.tsx "app/(auth)/casting-player.tsx"
git commit -m "refactor(casting): extract CastPlayerPoster"
```
---
## Task 3: Extract `CastPlayerEpisodeControls`
**Files:**
- Create: `components/casting/player/CastPlayerEpisodeControls.tsx`
- Modify: `app/(auth)/casting-player.tsx`
- [ ] **Step 1: Create the component**
Locate the JSX under `{/* Fixed 4-button control row for episodes - positioned independently */}` — the `<View>` with the four `Pressable`s: Episodes (`list` icon), Previous episode (`play-skip-back`), Next episode (`play-skip-forward`), Stop (`stop-circle`).
Create `components/casting/player/CastPlayerEpisodeControls.tsx` with that JSX. Define `CastPlayerEpisodeControlsProps` for each button's press handler and each button's enabled/visible condition exactly as the original computes it (e.g. whether a previous/next episode exists). Keep the conditions identical. Move the imports.
- [ ] **Step 2: Rewire**
Replace the 4-button block in `casting-player.tsx` with `<CastPlayerEpisodeControls ... />`. Add the import; drop unused imports.
- [ ] **Step 3: Verify**
Run: `bun run typecheck`
Expected: PASS — fully green.
Run: `bunx biome check components/casting/player/CastPlayerEpisodeControls.tsx "app/(auth)/casting-player.tsx"`
Expected: PASS on these files.
- [ ] **Step 4: Commit**
```bash
git add components/casting/player/CastPlayerEpisodeControls.tsx "app/(auth)/casting-player.tsx"
git commit -m "refactor(casting): extract CastPlayerEpisodeControls"
```
---
## Task 4: Extract `CastPlayerProgressBar`
**Files:**
- Create: `components/casting/player/CastPlayerProgressBar.tsx`
- Modify: `app/(auth)/casting-player.tsx`
- [ ] **Step 1: Create the component**
Locate the JSX under `{/* Progress slider with trickplay preview */}` and the adjacent `{/* Time display */}` block (both inside `{/* Fixed bottom controls area */}`). This includes the `<Slider>` with its trickplay-preview render callback and the two time `Text`s.
Create `components/casting/player/CastPlayerProgressBar.tsx` with that JSX. Define `CastPlayerProgressBarProps` for everything it references: the slider shared values, the scrub handlers, the trickplay URL/time/info, the formatted current/end time strings (or the values they derive from), `protocolColor`, etc. Type each field. Move the imports (`Slider`, reanimated, `Image`, `Text`, …).
> The slider passes `react-native-reanimated` shared values. They pass through props unchanged — keep their types (`SharedValue<number>`).
- [ ] **Step 2: Rewire**
Replace the progress-slider + time-display JSX in `casting-player.tsx` with `<CastPlayerProgressBar ... />` (keep it inside the bottom-controls `<View>`). Add the import; drop unused imports.
- [ ] **Step 3: Verify**
Run: `bun run typecheck`
Expected: PASS — fully green.
Run: `bunx biome check components/casting/player/CastPlayerProgressBar.tsx "app/(auth)/casting-player.tsx"`
Expected: PASS on these files.
- [ ] **Step 4: Commit**
```bash
git add components/casting/player/CastPlayerProgressBar.tsx "app/(auth)/casting-player.tsx"
git commit -m "refactor(casting): extract CastPlayerProgressBar"
```
---
## Task 5: Extract `CastPlayerTransportControls`
**Files:**
- Create: `components/casting/player/CastPlayerTransportControls.tsx`
- Modify: `app/(auth)/casting-player.tsx`
- [ ] **Step 1: Create the component**
Locate the JSX under `{/* Playback controls */}` — the `<View>` with the Rewind `Pressable`, the Play/Pause `Pressable`, and the Forward `Pressable` (the rewind/forward show the configured skip seconds).
Create `components/casting/player/CastPlayerTransportControls.tsx` with that JSX. Define `CastPlayerTransportControlsProps` for: the play/pause state, the play/pause handler, the rewind/forward handlers, the rewind/forward skip-second values shown on the buttons. Type each. Move the imports.
- [ ] **Step 2: Rewire**
Replace the playback-controls block in `casting-player.tsx` with `<CastPlayerTransportControls ... />`. Add the import; drop unused imports.
- [ ] **Step 3: Verify**
Run: `bun run typecheck`
Expected: PASS — fully green.
Run: `bunx biome check components/casting/player/CastPlayerTransportControls.tsx "app/(auth)/casting-player.tsx"`
Expected: PASS on these files.
- [ ] **Step 4: Commit**
```bash
git add components/casting/player/CastPlayerTransportControls.tsx "app/(auth)/casting-player.tsx"
git commit -m "refactor(casting): extract CastPlayerTransportControls"
```
---
## Task 6: Extract `useCastPlayerItem`
**Files:**
- Create: `hooks/useCastPlayerItem.ts`
- Modify: `app/(auth)/casting-player.tsx`
- [ ] **Step 1: Create the hook**
In `casting-player.tsx`, identify: the `fetchedItem` `useState`, the `useEffect` that fetches the full item from the Jellyfin API into `fetchedItem`, and the `currentItem` `useMemo` (which derives the effective item from `fetchedItem` and the cast `customData`).
Create `hooks/useCastPlayerItem.ts` exporting `useCastPlayerItem`. Move that state, effect, and memo into it. The hook takes whatever inputs those blocks reference (e.g. `api`, `user`, `mediaStatus`, the route params) as parameters, and returns `{ fetchedItem, currentItem }`. Keep the fetch logic and the derivation byte-for-byte identical.
- [ ] **Step 2: Rewire**
In `casting-player.tsx`, replace the moved `useState` / `useEffect` / `useMemo` with `const { fetchedItem, currentItem } = useCastPlayerItem({ ... });`. Add the import; drop now-unused imports.
- [ ] **Step 3: Verify**
Run: `bun run typecheck`
Expected: PASS — fully green.
Run: `bunx biome check hooks/useCastPlayerItem.ts "app/(auth)/casting-player.tsx"`
Expected: PASS on these files.
- [ ] **Step 4: Commit**
```bash
git add hooks/useCastPlayerItem.ts "app/(auth)/casting-player.tsx"
git commit -m "refactor(casting): extract useCastPlayerItem hook"
```
---
## Task 7: Extract `useCastEpisodes`
**Files:**
- Create: `hooks/useCastEpisodes.ts`
- Modify: `app/(auth)/casting-player.tsx`
- [ ] **Step 1: Create the hook**
Identify in `casting-player.tsx`: the `episodes`, `nextEpisode`, and `seasonData` `useState`s; the `useEffect`(s) that fetch the season / episode list; and the `loadEpisode` `useCallback`.
Create `hooks/useCastEpisodes.ts` exporting `useCastEpisodes`. Move that state, those effects, and `loadEpisode` into it. The hook takes the inputs they reference (`api`, `user`, `currentItem`, `remoteMediaClient`, `castDevice`, `settings`, …) as parameters and returns `{ episodes, nextEpisode, seasonData, loadEpisode }`. Keep all logic identical, including the `loadEpisode` body.
- [ ] **Step 2: Rewire**
Replace the moved declarations with `const { episodes, nextEpisode, seasonData, loadEpisode } = useCastEpisodes({ ... });`. Add the import; drop unused imports.
- [ ] **Step 3: Verify**
Run: `bun run typecheck`
Expected: PASS — fully green.
Run: `bunx biome check hooks/useCastEpisodes.ts "app/(auth)/casting-player.tsx"`
Expected: PASS on these files.
- [ ] **Step 4: Commit**
```bash
git add hooks/useCastEpisodes.ts "app/(auth)/casting-player.tsx"
git commit -m "refactor(casting): extract useCastEpisodes hook"
```
---
## Task 8: Extract `useCastDismissGesture`
**Files:**
- Create: `hooks/useCastDismissGesture.ts`
- Modify: `app/(auth)/casting-player.tsx`
- [ ] **Step 1: Create the hook**
Identify in `casting-player.tsx`: the `translateY` and `context` shared values, the `dismissModal` `useCallback`, the `panGesture` (`Gesture.Pan()...`), and the `animatedStyle` (`useAnimatedStyle`).
Create `hooks/useCastDismissGesture.ts` exporting `useCastDismissGesture`. Move those into it. The hook takes whatever the dismiss logic references (e.g. the navigation/router used to close the screen) as parameters and returns `{ panGesture, animatedStyle, dismissModal }`. Keep the gesture thresholds and animation logic identical.
- [ ] **Step 2: Rewire**
Replace the moved declarations with `const { panGesture, animatedStyle, dismissModal } = useCastDismissGesture({ ... });`. Add the import; drop unused imports.
- [ ] **Step 3: Verify**
Run: `bun run typecheck`
Expected: PASS — fully green.
Run: `bunx biome check hooks/useCastDismissGesture.ts "app/(auth)/casting-player.tsx"`
Expected: PASS on these files.
- [ ] **Step 4: Commit**
```bash
git add hooks/useCastDismissGesture.ts "app/(auth)/casting-player.tsx"
git commit -m "refactor(casting): extract useCastDismissGesture hook"
```
---
## Task 9: Extract `useCastPlayerProgress`
**Files:**
- Create: `hooks/useCastPlayerProgress.ts`
- Modify: `app/(auth)/casting-player.tsx`
> This is the most intricate extraction — reanimated shared values, timing refs,
> the live-progress interpolation, scrubbing, and the `useTrickplay` integration.
> Move it as one cohesive cluster; do not split or simplify it.
- [ ] **Step 1: Create the hook**
Identify in `casting-player.tsx` the progress/slider cluster: the `sliderProgress` / `sliderMin` / `sliderMax` shared values; the `isScrubbing` ref; the `trickplayTime` and `scrubPercentage` state; the `liveProgress` state with `lastSyncPositionRef` / `lastSyncTimestampRef`; the `resumePositionRef`; the effects that sync `liveProgress` from `mediaStatus` and update the refs; the `useTrickplay(...)` call; and any scrub-start/move/end handlers.
Create `hooks/useCastPlayerProgress.ts` exporting `useCastPlayerProgress`. Move that whole cluster in. The hook takes the inputs the cluster references (`mediaStatus`, `duration`, the trickplay inputs, …) as parameters and returns everything the JSX and the rest of the orchestrator still need — e.g. `{ sliderProgress, sliderMin, sliderMax, isScrubbing, trickplayTime, scrubPercentage, progress, liveProgress, resumePositionRef, trickPlayUrl, calculateTrickplayUrl, trickplayInfo, ...scrub handlers }`. Keep every effect, ref, and computation byte-for-byte identical and in the same order.
- [ ] **Step 2: Rewire**
Replace the moved cluster with `const { ... } = useCastPlayerProgress({ ... });`. The `CastPlayerProgressBar` component (Task 4) and `reloadWithSelection` consume these values — make sure they still receive them. Add the import; drop unused imports.
- [ ] **Step 3: Verify**
Run: `bun run typecheck`
Expected: PASS — fully green.
Run: `bun test utils/casting/`
Expected: PASS — all suites pass (the pure-logic suites are unaffected).
Run: `bunx biome check hooks/useCastPlayerProgress.ts "app/(auth)/casting-player.tsx"`
Expected: PASS on these files.
- [ ] **Step 4: Commit**
```bash
git add hooks/useCastPlayerProgress.ts "app/(auth)/casting-player.tsx"
git commit -m "refactor(casting): extract useCastPlayerProgress hook"
```
---
## Task 10: Finalise the orchestrator
**Files:**
- Modify: `app/(auth)/casting-player.tsx`
- [ ] **Step 1: Clean up**
`casting-player.tsx` should now be a thin orchestrator: hook calls, a small amount of wiring, and the JSX tree composing the 6 new components plus the 3 modal components (`ChromecastDeviceSheet`, `ChromecastEpisodeList`, `ChromecastSettingsMenu`) inside the `GestureDetector` / `Animated.View`.
Read the whole file. Remove any now-dead code: unused imports, leftover variables, commented-out fragments, intermediate values that are no longer referenced. Do not change behaviour — only delete what is provably unused.
- [ ] **Step 2: Verify**
Run: `bun run typecheck`
Expected: PASS — fully green.
Run: `bun test utils/casting/`
Expected: PASS.
Run: `bunx biome check "app/(auth)/casting-player.tsx"`
Expected: PASS.
Confirm `casting-player.tsx` is in the ~150-250 line range and contains no large inline JSX section or logic cluster.
- [ ] **Step 3: Commit**
```bash
git add "app/(auth)/casting-player.tsx"
git commit -m "refactor(casting): finalise casting-player orchestrator"
```
---
## Final verification
- [ ] **Checks**
Run: `bun run typecheck` → PASS.
Run: `bun test utils/casting/` → PASS.
- [ ] **Manual re-test** (behaviour must be identical to before the split)
Cast a movie and an episode to the Chromecast. Verify: playback starts; the header / title / poster render; the 4 episode buttons work; audio / subtitle / quality / version switching still works; episode navigation works; the progress slider scrubs and shows trickplay; play/pause/rewind/forward work; the buffering overlay appears; swiping down dismisses the player. Nothing should behave differently from before sub-project C.
---
## Notes for the implementer
- Line numbers drift across tasks — always Read the file and match on the quoted `{/* comment */}` anchors.
- This is a refactor: there is no new behaviour to unit-test. `bun run typecheck` per task is the safety net; the final manual re-test is the behavioural check.
- If extracting a section reveals it is entangled with another (a shared variable that does not cleanly belong to one unit), keep that variable in the orchestrator and pass it as a prop / hook argument — do not duplicate it.
- Out of scope: the trickplay truncation bug, the progress-bar touch-overlap bug, the time-label position, mini-player changes, the `loadEpisode`/`currentItem` race. Do not fix them here — they belong to the later UX sub-project.

843
docs/superpowers/plans/2026-05-22-chromecast-session-remote-control.md
View File

@@ -1,843 +0,0 @@
# Casting Session Reporting & Remote Control — Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Implement app-wide Jellyfin remote control (Playstate / GeneralCommand) routed through a `PlaybackController` registry, fix the cast `PlayMethod` report, make the episode buttons conditional, and fix the `loadEpisode` race.
**Architecture:** A `PlaybackController` interface is the canonical control surface; each player (cast, native video, music) registers an implementation into a Jotai atom while it is active. A pure mapper turns WebSocket remote-control messages into typed actions; a `useRemoteControl` hook dispatches them to the active controller. Small cast fixes ride alongside.
**Tech Stack:** TypeScript (strict), React Native / Expo, Jotai, `@jellyfin/sdk`, `react-native-google-cast`, `sonner-native`. Pure logic is unit-tested with `bun test`.
**Spec:** `docs/superpowers/specs/2026-05-22-chromecast-session-remote-control-design.md`
**Environment note:** Windows checkout, `core.autocrlf=true` — project-wide `bun run check` reports ~124 pre-existing CRLF errors unrelated to this work. The gate is `bun run typecheck` (fully green) plus Biome on the files each task edits.
**Commit note:** Do NOT add a `Co-Authored-By` trailer to any commit message in this project.
---
## File Structure
| File | Responsibility | Task |
|---|---|---|
| `utils/playback/playbackController.ts` | `PlaybackController` interface, atom, `useRegisterPlaybackController` | 1 |
| `utils/playback/remoteCommands.ts` | Pure WS-message → `RemoteAction` mapper | 2 |
| `utils/playback/remoteCommands.test.ts` | Unit tests for the mapper | 2 |
| `hooks/useRemoteControl.ts` | Dispatch remote actions to the active controller | 3 |
| `providers/WebSocketProvider.tsx` | Consume `useRemoteControl`; expand `SupportedCommands` | 4 |
| `app/(auth)/casting-player.tsx` | Register the cast controller; fix `loadEpisode` race | 5, 10 |
| `app/(auth)/player/direct-player.tsx` | Register the native-video controller | 6 |
| `providers/MusicPlayerProvider.tsx` | Register the music controller | 7 |
| `utils/casting/castLoad.ts`, `utils/casting/mediaInfo.ts` | Embed `playMethod` in customData | 8 |
| `hooks/useCasting.ts` | Report the real `PlayMethod` | 8 |
| `components/casting/player/CastPlayerEpisodeControls.tsx` | Conditional Previous / Next buttons | 9 |
---
## Task 1: `PlaybackController` contract & registry
**Files:**
- Create: `utils/playback/playbackController.ts`
- [ ] **Step 1: Write the module**
Create `utils/playback/playbackController.ts`:
```ts
/**
* The canonical playback-control surface. Every player (cast, native video,
* music) implements this interface and registers itself as the active
* controller while it is playing, so remote-control commands can be routed to
* whatever is currently playing.
*/
import { atom, useSetAtom } from "jotai";
import { useEffect } from "react";
export interface PlaybackController {
playPause(): void;
pause(): void;
unpause(): void;
stop(): void;
/** Absolute seek position in milliseconds. */
seek(positionMs: number): void;
next(): void;
previous(): void;
/** Volume 0-1. */
setVolume(level: number): void;
toggleMute(): void;
}
/** The currently-active playback controller, or null when nothing is playing. */
export const activePlaybackControllerAtom = atom<PlaybackController | null>(
null,
);
/**
* Register `controller` as the active playback controller while `active` is
* true. Clears the atom on unmount or when `active` becomes false — but only if
* the atom still holds this exact controller (so a newer registration wins).
*/
export const useRegisterPlaybackController = (
controller: PlaybackController | null,
active: boolean,
): void => {
const setController = useSetAtom(activePlaybackControllerAtom);
useEffect(() => {
if (!active || !controller) return;
setController(controller);
return () => {
setController((current) => (current === controller ? null : current));
};
}, [active, controller, setController]);
};
```
- [ ] **Step 2: Verify types**
Run: `bun run typecheck`
Expected: PASS — no errors.
- [ ] **Step 3: Commit**
```bash
git add utils/playback/playbackController.ts
git commit -m "feat(playback): add PlaybackController contract and registry"
```
---
## Task 2: Pure remote-command mapper
**Files:**
- Create: `utils/playback/remoteCommands.ts`
- Test: `utils/playback/remoteCommands.test.ts`
- [ ] **Step 1: Write the failing test**
Create `utils/playback/remoteCommands.test.ts`:
```ts
import { describe, expect, test } from "bun:test";
import { mapRemoteCommand } from "./remoteCommands";
describe("mapRemoteCommand — Playstate", () => {
test("maps Pause", () => {
expect(mapRemoteCommand({ MessageType: "Playstate", Data: { Command: "Pause" } }))
.toEqual({ kind: "pause" });
});
test("maps Stop, PlayPause, Unpause, NextTrack, PreviousTrack", () => {
const m = (c: string) =>
mapRemoteCommand({ MessageType: "Playstate", Data: { Command: c } });
expect(m("Stop")).toEqual({ kind: "stop" });
expect(m("PlayPause")).toEqual({ kind: "playPause" });
expect(m("Unpause")).toEqual({ kind: "unpause" });
expect(m("NextTrack")).toEqual({ kind: "next" });
expect(m("PreviousTrack")).toEqual({ kind: "previous" });
});
test("maps Seek, converting ticks to milliseconds", () => {
expect(
mapRemoteCommand({
MessageType: "Playstate",
Data: { Command: "Seek", SeekPositionTicks: 600_000_000 },
}),
).toEqual({ kind: "seek", positionMs: 60_000 });
});
test("returns null for Seek with no position", () => {
expect(
mapRemoteCommand({ MessageType: "Playstate", Data: { Command: "Seek" } }),
).toBeNull();
});
test("returns null for an unknown command", () => {
expect(
mapRemoteCommand({ MessageType: "Playstate", Data: { Command: "Wat" } }),
).toBeNull();
});
});
describe("mapRemoteCommand — GeneralCommand", () => {
test("maps SetVolume, converting 0-100 to 0-1", () => {
expect(
mapRemoteCommand({
MessageType: "GeneralCommand",
Data: { Name: "SetVolume", Arguments: { Volume: "40" } },
}),
).toEqual({ kind: "setVolume", level: 0.4 });
});
test("clamps SetVolume to 0-1", () => {
const r = mapRemoteCommand({
MessageType: "GeneralCommand",
Data: { Name: "SetVolume", Arguments: { Volume: "250" } },
});
expect(r).toEqual({ kind: "setVolume", level: 1 });
});
test("maps ToggleMute / Mute / Unmute to toggleMute", () => {
const m = (n: string) =>
mapRemoteCommand({ MessageType: "GeneralCommand", Data: { Name: n } });
expect(m("ToggleMute")).toEqual({ kind: "toggleMute" });
expect(m("Mute")).toEqual({ kind: "toggleMute" });
expect(m("Unmute")).toEqual({ kind: "toggleMute" });
});
test("maps DisplayMessage from Arguments.Text", () => {
expect(
mapRemoteCommand({
MessageType: "GeneralCommand",
Data: { Name: "DisplayMessage", Arguments: { Text: "Hello" } },
}),
).toEqual({ kind: "displayMessage", text: "Hello" });
});
});
describe("mapRemoteCommand — other", () => {
test("returns null for unrelated message types", () => {
expect(mapRemoteCommand({ MessageType: "KeepAlive", Data: {} })).toBeNull();
});
});
```
- [ ] **Step 2: Run the test to verify it fails**
Run: `bun test utils/playback/remoteCommands.test.ts`
Expected: FAIL — `Cannot find module './remoteCommands'`.
- [ ] **Step 3: Write the implementation**
Create `utils/playback/remoteCommands.ts`:
```ts
/**
* Pure mapping from a Jellyfin remote-control WebSocket message to a typed
* action. Dependency-free so it is unit-testable under `bun test`.
*/
/** A WebSocket message envelope (subset). */
export interface RemoteWsMessage {
MessageType: string;
Data?: unknown;
}
export type RemoteAction =
| { kind: "playPause" }
| { kind: "pause" }
| { kind: "unpause" }
| { kind: "stop" }
| { kind: "seek"; positionMs: number }
| { kind: "next" }
| { kind: "previous" }
| { kind: "setVolume"; level: number }
| { kind: "toggleMute" }
| { kind: "displayMessage"; text: string };
const clamp01 = (n: number): number => Math.min(1, Math.max(0, n));
const mapPlaystate = (data: Record<string, unknown>): RemoteAction | null => {
switch (data.Command) {
case "PlayPause":
return { kind: "playPause" };
case "Pause":
return { kind: "pause" };
case "Unpause":
return { kind: "unpause" };
case "Stop":
return { kind: "stop" };
case "NextTrack":
return { kind: "next" };
case "PreviousTrack":
return { kind: "previous" };
case "Seek": {
const ticks = data.SeekPositionTicks;
if (typeof ticks !== "number") return null;
return { kind: "seek", positionMs: Math.floor(ticks / 10000) };
}
default:
return null;
}
};
const mapGeneralCommand = (
data: Record<string, unknown>,
): RemoteAction | null => {
const args = (data.Arguments ?? {}) as Record<string, unknown>;
switch (data.Name) {
case "SetVolume": {
const volume = Number(args.Volume);
if (!Number.isFinite(volume)) return null;
return { kind: "setVolume", level: clamp01(volume / 100) };
}
case "Mute":
case "Unmute":
case "ToggleMute":
return { kind: "toggleMute" };
case "DisplayMessage": {
const text = args.Text ?? args.Header;
if (!text) return null;
return { kind: "displayMessage", text: String(text) };
}
default:
return null;
}
};
/** Map a remote-control WS message to a typed action, or null if unhandled. */
export const mapRemoteCommand = (
message: RemoteWsMessage,
): RemoteAction | null => {
const data = (message.Data ?? {}) as Record<string, unknown>;
if (message.MessageType === "Playstate") return mapPlaystate(data);
if (message.MessageType === "GeneralCommand") return mapGeneralCommand(data);
return null;
};
```
- [ ] **Step 4: Run the test to verify it passes**
Run: `bun test utils/playback/remoteCommands.test.ts`
Expected: PASS — all suites pass.
- [ ] **Step 5: Commit**
```bash
git add utils/playback/remoteCommands.ts utils/playback/remoteCommands.test.ts
git commit -m "feat(playback): add pure remote-command mapper"
```
---
## Task 3: `useRemoteControl` hook
**Files:**
- Create: `hooks/useRemoteControl.ts`
- [ ] **Step 1: Write the hook**
Create `hooks/useRemoteControl.ts`:
```ts
/**
* Dispatches Jellyfin remote-control WebSocket messages to the active
* PlaybackController. DisplayMessage is shown as an in-app toast and needs no
* controller.
*/
import { useAtomValue } from "jotai";
import { useEffect } from "react";
import { toast } from "sonner-native";
import { activePlaybackControllerAtom } from "@/utils/playback/playbackController";
import {
mapRemoteCommand,
type RemoteWsMessage,
} from "@/utils/playback/remoteCommands";
/** Handle one remote-control message (call it whenever a new WS message arrives). */
export const useRemoteControl = (lastMessage: RemoteWsMessage | null): void => {
const controller = useAtomValue(activePlaybackControllerAtom);
useEffect(() => {
if (!lastMessage) return;
const action = mapRemoteCommand(lastMessage);
if (!action) return;
if (action.kind === "displayMessage") {
toast(action.text);
return;
}
if (!controller) return;
switch (action.kind) {
case "playPause":
controller.playPause();
break;
case "pause":
controller.pause();
break;
case "unpause":
controller.unpause();
break;
case "stop":
controller.stop();
break;
case "seek":
controller.seek(action.positionMs);
break;
case "next":
controller.next();
break;
case "previous":
controller.previous();
break;
case "setVolume":
controller.setVolume(action.level);
break;
case "toggleMute":
controller.toggleMute();
break;
}
}, [lastMessage, controller]);
};
```
- [ ] **Step 2: Verify types**
Run: `bun run typecheck`
Expected: PASS — no errors.
> If `sonner-native`'s `toast` export name differs, check an existing usage with
> `grep -rn "sonner-native" --include="*.tsx" components app | head -3` and match it.
- [ ] **Step 3: Commit**
```bash
git add hooks/useRemoteControl.ts
git commit -m "feat(playback): add useRemoteControl dispatch hook"
```
---
## Task 4: Wire remote control into `WebSocketProvider`
**Files:**
- Modify: `providers/WebSocketProvider.tsx`
- [ ] **Step 1: Consume the hook**
In `providers/WebSocketProvider.tsx`, add the import:
```ts
import { useRemoteControl } from "@/hooks/useRemoteControl";
```
Inside the `WebSocketProvider` component body (after `lastMessage` is declared), add:
```ts
// Route Jellyfin remote-control messages to the active player.
useRemoteControl(lastMessage);
```
- [ ] **Step 2: Expand advertised capabilities**
In the `postFullCapabilities` call, replace:
```ts
SupportedCommands: ["Play"],
```
with:
```ts
SupportedCommands: [
"Play",
"DisplayMessage",
"SetVolume",
"ToggleMute",
"Mute",
"Unmute",
],
```
- [ ] **Step 3: Verify types**
Run: `bun run typecheck`
Expected: PASS — no errors.
> `SupportedCommands` is typed as `GeneralCommandType[]` by the Jellyfin SDK. The
> six strings above are all valid `GeneralCommandType` values, so the array
> literal type-checks. If the SDK rejects a literal, that value is not a valid
> `GeneralCommandType` — remove it and report it.
- [ ] **Step 4: Commit**
```bash
git add providers/WebSocketProvider.tsx
git commit -m "feat(playback): handle remote-control messages over WebSocket"
```
---
## Task 5: Register the cast `PlaybackController`
**Files:**
- Modify: `app/(auth)/casting-player.tsx`
- [ ] **Step 1: Build and register the controller**
Read `app/(auth)/casting-player.tsx`. It uses `useCasting` (which exposes
`togglePlayPause`, `pause`, `play`, `seek`, `skipForward`, `skipBackward`, `stop`,
`setVolume`, `progress`, `volume`) and `useCastEpisodes` (`loadEpisode`, `episodes`,
`nextEpisode`), and has `currentItem`.
Add a memoised `PlaybackController` built from those, and register it while a cast
session is active. Concretely:
```tsx
import { useMemo } from "react";
import {
type PlaybackController,
useRegisterPlaybackController,
} from "@/utils/playback/playbackController";
```
Build the controller (place this near the other `useMemo`s, after `castingControls`
and the episode/selection hooks are available):
```tsx
const castController = useMemo<PlaybackController>(
() => ({
playPause: () => {
castingControls.togglePlayPause();
},
pause: () => {
castingControls.pause();
},
unpause: () => {
castingControls.play();
},
stop: () => {
castingControls.stop();
},
seek: (positionMs) => {
castingControls.seek(positionMs);
},
next: () => {
if (nextEpisode) loadEpisode(nextEpisode);
},
previous: () => {
const idx = episodes.findIndex((e) => e.Id === currentItem?.Id);
if (idx > 0) loadEpisode(episodes[idx - 1]);
},
setVolume: (level) => {
castingControls.setVolume(level);
},
toggleMute: () => {
castingControls.setVolume(castingControls.volume > 0 ? 0 : 1);
},
}),
[castingControls, episodes, nextEpisode, loadEpisode, currentItem?.Id],
);
useRegisterPlaybackController(castController, castState === CastState.CONNECTED);
```
> Verify the exact names against `useCasting`'s return and `useCastEpisodes`'s
> return — the methods listed above are what those hooks expose. `castState` /
> `CastState` are already imported in this file. If `castingControls` does not
> expose `volume`, derive the mute-toggle from whatever volume value it does
> expose, or from `currentSelection` — keep the intent (mute ↔ unmute).
- [ ] **Step 2: Verify**
Run: `bun run typecheck`
Expected: PASS — no errors.
Run: `bunx biome check "app/(auth)/casting-player.tsx"`
Expected: PASS.
- [ ] **Step 3: Commit**
```bash
git add "app/(auth)/casting-player.tsx"
git commit -m "feat(casting): register cast PlaybackController for remote control"
```
---
## Task 6: Register the native-video `PlaybackController`
**Files:**
- Modify: `app/(auth)/player/direct-player.tsx`
- [ ] **Step 1: Build and register the controller**
Read `app/(auth)/player/direct-player.tsx` and locate its playback controls — the
play, pause, seek, and (if present) next/previous-episode handlers it already uses
for its on-screen controls (it has a video player ref and `usePlaybackManager` for
`previousItem` / `nextItem`).
Add a memoised `PlaybackController` wrapping those existing handlers, and register
it with `useRegisterPlaybackController(controller, true)` — `true` because the
controller should be active for the whole lifetime of the player screen (the hook
clears it automatically on unmount).
```tsx
import {
type PlaybackController,
useRegisterPlaybackController,
} from "@/utils/playback/playbackController";
```
Build the controller from the screen's existing control functions (do not invent
new playback logic — reuse what the on-screen buttons call). For `setVolume` /
`toggleMute`, if the native player exposes no volume control, implement them as
no-ops (the dashboard volume slider then simply has no effect on local video — that
is acceptable and honest). `seek` takes milliseconds — convert to whatever unit the
player's seek expects.
- [ ] **Step 2: Verify**
Run: `bun run typecheck`
Expected: PASS — no errors.
Run: `bunx biome check "app/(auth)/player/direct-player.tsx"`
Expected: PASS.
- [ ] **Step 3: Commit**
```bash
git add "app/(auth)/player/direct-player.tsx"
git commit -m "feat(player): register native-video PlaybackController"
```
---
## Task 7: Register the music `PlaybackController`
**Files:**
- Modify: `providers/MusicPlayerProvider.tsx`
- [ ] **Step 1: Build and register the controller**
Read `providers/MusicPlayerProvider.tsx` and locate its playback controls (play /
pause / stop / seek / skip-next / skip-previous / volume — whatever it exposes for
the music UI).
Add a memoised `PlaybackController` wrapping those, and register it with
`useRegisterPlaybackController(controller, isMusicActive)` where `isMusicActive` is
the provider's existing "is a track loaded / playing" condition. Reuse the
provider's existing control functions — do not add new playback logic.
```tsx
import {
type PlaybackController,
useRegisterPlaybackController,
} from "@/utils/playback/playbackController";
```
If the music player exposes no volume API, make `setVolume` / `toggleMute` no-ops.
- [ ] **Step 2: Verify**
Run: `bun run typecheck`
Expected: PASS — no errors.
Run: `bunx biome check providers/MusicPlayerProvider.tsx`
Expected: PASS.
- [ ] **Step 3: Commit**
```bash
git add providers/MusicPlayerProvider.tsx
git commit -m "feat(music): register music PlaybackController"
```
---
## Task 8: Report the real cast `PlayMethod`
**Files:**
- Modify: `utils/casting/castLoad.ts`, `utils/casting/mediaInfo.ts`, `hooks/useCasting.ts`
- [ ] **Step 1: Carry `playMethod` in customData**
In `utils/casting/mediaInfo.ts`, add an optional parameter to `buildCastMediaInfo`,
alongside `playSessionId` and `selection`:
```ts
/** "Transcode" when the stream is a server transcode, else "DirectPlay". */
playMethod?: "Transcode" | "DirectPlay";
```
Destructure `playMethod` in the function signature, and add it to the
`slimCustomData` object (extend its inline type with `playMethod?: "Transcode" |
"DirectPlay"`, the same way `selection` was added).
- [ ] **Step 2: Determine and pass `playMethod` in `castLoad.ts`**
In `utils/casting/castLoad.ts`, inside `attemptLoad`, after `getStreamUrl` returns
`data`, determine the play method from whether the resolved media source is a
transcode:
```ts
const playMethod: "Transcode" | "DirectPlay" = data.mediaSource?.TranscodingUrl
? "Transcode"
: "DirectPlay";
```
Pass `playMethod` into the `buildCastMediaInfo({ ... })` call.
> `getStreamUrl` returns `{ url, sessionId, mediaSource }`; `mediaSource` is a
> `MediaSourceInfo` whose `TranscodingUrl` is set when the server chose to
> transcode. Confirm the returned shape in `utils/jellyfin/media/getStreamUrl.ts`.
- [ ] **Step 3: Report it in `useCasting.ts`**
In `hooks/useCasting.ts`, the progress reporting currently sets
`PlayMethod: activeProtocol === "chromecast" ? "DirectStream" : "DirectPlay"` in
both `reportPlaybackStart` and `reportPlaybackProgress`. Read the real play method
from customData near the existing `playSessionId` derivation:
```ts
const playMethod =
(mediaStatus?.mediaInfo?.customData as
| { playMethod?: "Transcode" | "DirectPlay" }
| undefined)?.playMethod ?? "Transcode";
```
Replace both hardcoded `PlayMethod:` expressions with `PlayMethod: playMethod`. Add
`playMethod` to the progress-reporting `useEffect` dependency array.
> Default to `"Transcode"` — a cast stream is a transcode far more often than not,
> so it is the safer fallback when customData has not yet arrived.
- [ ] **Step 4: Verify**
Run: `bun run typecheck`
Expected: PASS — no errors.
Run: `bun test utils/casting/`
Expected: PASS — all suites pass.
- [ ] **Step 5: Commit**
```bash
git add utils/casting/castLoad.ts utils/casting/mediaInfo.ts hooks/useCasting.ts
git commit -m "fix(casting): report the real PlayMethod to Jellyfin"
```
---
## Task 9: Conditional episode buttons
**Files:**
- Modify: `components/casting/player/CastPlayerEpisodeControls.tsx`
- [ ] **Step 1: Make Previous / Next conditional**
Read `components/casting/player/CastPlayerEpisodeControls.tsx`. It receives
`episodes`, `nextEpisode`, and `currentItemId`. The Previous button currently
renders always (disabled when `episodes.findIndex(...) <= 0`); the Next button
renders always (disabled when `!nextEpisode`).
Change both so they are **not rendered at all** when there is no adjacent episode:
- Previous: render only when `episodes.findIndex((e) => e.Id === currentItemId) > 0`.
- Next: render only when `nextEpisode` is truthy.
Keep the Episodes-list and Stop buttons unconditional. Preserve the row layout —
if the row uses fixed spacing, ensure removing a button does not break alignment
(the remaining buttons should stay evenly placed; adjust the container's
`justifyContent` / gap only if needed, behaviour of the remaining buttons unchanged).
- [ ] **Step 2: Verify**
Run: `bun run typecheck`
Expected: PASS — no errors.
Run: `bunx biome check components/casting/player/CastPlayerEpisodeControls.tsx`
Expected: PASS.
- [ ] **Step 3: Commit**
```bash
git add components/casting/player/CastPlayerEpisodeControls.tsx
git commit -m "feat(casting): hide episode buttons when no adjacent episode"
```
---
## Task 10: Fix the `loadEpisode` / `currentItem` race
**Files:**
- Modify: `app/(auth)/casting-player.tsx`
- [ ] **Step 1: Guard against the stale `currentItem`**
Read `app/(auth)/casting-player.tsx`. `loadEpisode` (from `useCastEpisodes`) loads a
new episode on the cast; `currentItem` is derived from the cast `customData` and
updates only once the cast reports the new episode — leaving a window where
`currentItem` still describes the previous episode.
Fix: track the id of the episode being loaded, and treat `currentItem` as "pending"
until the cast's `customData` item id matches it. Concretely:
- Add a ref `pendingEpisodeIdRef` (a `useRef<string | null>(null)`).
- When `loadEpisode` is invoked, set `pendingEpisodeIdRef.current` to the target
episode id. (Wrap the `loadEpisode` call sites, or wrap the function the cast
player passes to `CastPlayerEpisodeControls` / the episode list, so the ref is set
whenever an episode load starts.)
- Clear the ref once `currentItem?.Id === pendingEpisodeIdRef.current` (the cast has
caught up).
- While `pendingEpisodeIdRef.current` is set and does not match `currentItem?.Id`,
the player is mid-transition — guard the derivations that would act on the stale
item (the episode-controls indices and the selection menu) so they do not flash
the previous episode's data. The simplest correct guard: while pending, suppress
rendering the episode-dependent secondary UI, or show the loading state, until
`currentItem` matches.
Keep this minimal and behaviour-preserving for the non-racing path — when no load
is pending, nothing changes.
> This is a real but small bug. If, on reading the file, the cleanest fix is to
> have `useCastEpisodes` expose a `loadingEpisodeId` rather than a ref in the
> screen, do that instead — keep the fix where it reads most naturally. Report
> which approach you took.
- [ ] **Step 2: Verify**
Run: `bun run typecheck`
Expected: PASS — no errors.
Run: `bun test utils/casting/`
Expected: PASS.
Run: `bunx biome check "app/(auth)/casting-player.tsx"`
Expected: PASS.
- [ ] **Step 3: Commit**
```bash
git add "app/(auth)/casting-player.tsx"
git commit -m "fix(casting): guard against stale currentItem during episode load"
```
---
## Final verification
- [ ] **Checks**
Run: `bun test utils/` → PASS (`remoteCommands` plus the existing `casting` suites).
Run: `bun run typecheck` → PASS.
- [ ] **Manual verification**
From the Jellyfin web dashboard's "Devices" / active-session view, with the app
casting:
- The session shows `Transcode` (not direct-play) for a transcoded stream.
- The remote panel's pause / play / stop / seek / next / previous control the cast.
- The volume control changes the cast volume; mute toggles it.
- "Send message" shows a toast in the app.
- Repeat with the native video player open (not casting): transport + message work;
volume is a no-op if the native player has no volume API.
- In the cast player, Previous is absent on the first episode, Next absent on the
last.
- Changing episode shows no flash of the previous episode's title/tracks.
---
## Notes for the implementer
- Line numbers drift — match on quoted code.
- `bun test` is Bun's native runner; `remoteCommands.ts` is pure (no imports) so its
test runs cleanly. Do not write a test that imports `useRemoteControl.ts` or
`playbackController.ts` — they pull React / jotai.
- Tasks 5-7 are integration: reuse each player's existing control functions, do not
reimplement playback logic. A `setVolume` / `toggleMute` no-op is acceptable where
a player has no volume API.
- Do NOT add a `Co-Authored-By` trailer to commit messages.
- Out of scope: track-switching remote commands, the custom receiver.

406
docs/superpowers/plans/2026-05-22-chromecast-ux-player.md
View File

@@ -1,406 +0,0 @@
# Chromecast Player UX — Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Fix the trickplay/scrub-bubble positioning on both casting progress bars, share the bubble in one component, lighten the time display, add a mini-player stop button, and add a developer touch-zone overlay.
**Architecture:** A shared `CastTrickplayBubble` component renders the scrub preview; both sliders feed it via `renderBubble` and set `bubbleWidth` so `react-native-awesome-slider` clamps the bubble itself (no manual positioning). A `DEBUG_TOUCH_ZONES` flag draws red hit-area outlines for hand-calibration.
**Tech Stack:** TypeScript (strict), React Native / Expo, `react-native-awesome-slider`, `expo-image`.
**Spec:** `docs/superpowers/specs/2026-05-22-chromecast-ux-player-design.md`
**Environment note:** Windows checkout, `core.autocrlf=true` — project-wide `bun run check` reports ~124 pre-existing CRLF errors, unrelated. Gate: `bun run typecheck` (fully green) + Biome on edited files.
**Commit note:** Do NOT add a `Co-Authored-By` trailer to commit messages.
---
## File Structure
| File | Responsibility | Task |
|---|---|---|
| `components/casting/player/CastTrickplayBubble.tsx` | Shared scrub-preview bubble (trickplay tile or plain time text) | 1 |
| `utils/casting/debug.ts` | `DEBUG_TOUCH_ZONES` flag | 4 |
| `components/casting/player/CastPlayerProgressBar.tsx` | Use the shared bubble + `bubbleWidth`; drop manual positioning; debug overlay | 2, 4 |
| `components/casting/CastingMiniPlayer.tsx` | Same bubble fix; add a stop button | 3 |
| `app/(auth)/casting-player.tsx` | Drop the now-dead `scrubPercentage` plumbing | 2 |
| `hooks/useCastPlayerProgress.ts` | Drop the now-dead `scrubPercentage` state/return | 2 |
---
## Task 1: Shared `CastTrickplayBubble` component
**Files:**
- Create: `components/casting/player/CastTrickplayBubble.tsx`
- [ ] **Step 1: Create the component**
Create `components/casting/player/CastTrickplayBubble.tsx`:
```tsx
/**
* Shared scrub-preview bubble for the casting progress bars.
*
* Renders the trickplay tile (when trickplay data is available) with the scrub
* time as plain text above it, or just the scrub time as plain text. It does NO
* positioning of its own — the slider places it via its `bubbleWidth` prop.
*/
import { Image } from "expo-image";
import { View } from "react-native";
import { Text } from "@/components/common/Text";
import type { useTrickplay } from "@/hooks/useTrickplay";
import { formatTrickplayTime } from "@/utils/casting/helpers";
type TrickplayReturn = ReturnType<typeof useTrickplay>;
interface CastTrickplayBubbleProps {
/** Current trickplay image URL/coordinates, or null. */
trickPlayUrl: TrickplayReturn["trickPlayUrl"];
/** Parsed trickplay metadata, or null. */
trickplayInfo: TrickplayReturn["trickplayInfo"];
/** Scrub time to display. */
trickplayTime: { hours: number; minutes: number; seconds: number };
/** Trickplay tile width in px (220 main player, 140 mini-player). */
tileWidth: number;
}
export function CastTrickplayBubble({
trickPlayUrl,
trickplayInfo,
trickplayTime,
tileWidth,
}: CastTrickplayBubbleProps) {
const timeText = (
<Text
style={{
color: "#fff",
fontSize: 13,
fontWeight: "600",
textAlign: "center",
textShadowColor: "rgba(0, 0, 0, 0.85)",
textShadowOffset: { width: 0, height: 1 },
textShadowRadius: 3,
}}
>
{formatTrickplayTime(trickplayTime)}
</Text>
);
// No trickplay: just the plain time text.
if (!trickPlayUrl || !trickplayInfo) {
return timeText;
}
const { x, y, url } = trickPlayUrl;
const tileHeight = tileWidth / (trickplayInfo.aspectRatio ?? 1.78);
return (
<View style={{ width: tileWidth, alignItems: "center", gap: 4 }}>
{timeText}
<View
style={{
width: tileWidth,
height: tileHeight,
borderRadius: 8,
overflow: "hidden",
backgroundColor: "#1a1a1a",
}}
>
<Image
cachePolicy='memory-disk'
style={{
width: tileWidth * (trickplayInfo.data?.TileWidth ?? 1),
height: tileHeight * (trickplayInfo.data?.TileHeight ?? 1),
transform: [
{ translateX: -x * tileWidth },
{ translateY: -y * tileHeight },
],
}}
source={{ uri: url }}
contentFit='cover'
/>
</View>
</View>
);
}
```
- [ ] **Step 2: Verify types**
Run: `bun run typecheck`
Expected: PASS — no errors.
- [ ] **Step 3: Commit**
```bash
git add components/casting/player/CastTrickplayBubble.tsx
git commit -m "feat(casting): add shared CastTrickplayBubble component"
```
---
## Task 2: Rework `CastPlayerProgressBar`
**Files:**
- Modify: `components/casting/player/CastPlayerProgressBar.tsx`
- Modify: `app/(auth)/casting-player.tsx`
- Modify: `hooks/useCastPlayerProgress.ts`
- [ ] **Step 1: Rework the slider in `CastPlayerProgressBar.tsx`**
Read `components/casting/player/CastPlayerProgressBar.tsx`. Make these changes:
**(a)** Replace the entire `renderBubble={() => { ... }}` prop (the ~125-line callback that builds the bubble with manual `position: "absolute"` / `left` / `thumbPosition` maths) with:
```tsx
renderBubble={() => (
<CastTrickplayBubble
trickPlayUrl={trickPlayUrl}
trickplayInfo={trickplayInfo}
trickplayTime={trickplayTime}
tileWidth={220}
/>
)}
bubbleWidth={trickPlayUrl && trickplayInfo ? 220 : 64}
```
(`bubbleWidth` tells the slider to clamp the bubble within the track; 220 = trickplay tile width, 64 = plain time-text width.)
**(b)** Reduce `panHitSlop` to a sane default that does not overlap the controls above the bar — change it to:
```tsx
panHitSlop={{ top: 12, bottom: 12, left: 10, right: 10 }}
```
(The exact values will be hand-calibrated by the user with the Task 4 overlay.)
**(c)** `scrubPercentage` was only used by the deleted manual positioning. Remove `scrubPercentage` and `setScrubPercentage` from `CastPlayerProgressBarProps` and the destructured params, and remove the `setScrubPercentage(...)` call inside `onValueChange` (keep the rest of `onValueChange` — the `calculateTrickplayUrl` and `setTrickplayTime` logic).
**(d)** Add the import `import { CastTrickplayBubble } from "@/components/casting/player/CastTrickplayBubble";`. Remove now-unused imports: `Image` (`expo-image`), `Dimensions`, `formatTrickplayTime`. Keep `Text`, `View`, `formatTime`, `calculateEndingTime`, `msToTicks`, `ticksToSeconds` — still used by the static time row and `onValueChange`.
**(e)** The static current/ending/total time row at the bottom is unchanged.
- [ ] **Step 2: Remove the dead `scrubPercentage` plumbing**
In `app/(auth)/casting-player.tsx`: the `<CastPlayerProgressBar .../>` element passes `scrubPercentage` and `setScrubPercentage` props — remove those two props from the element.
In `hooks/useCastPlayerProgress.ts`: remove the `scrubPercentage` / `setScrubPercentage` state and their entries in the hook's return object and return-type interface. (If `scrubPercentage` turns out to be read somewhere else, leave it and report — but the only consumer was `CastPlayerProgressBar`'s manual positioning.)
- [ ] **Step 3: Verify**
Run: `bun run typecheck`
Expected: PASS — fully green.
Run: `bunx biome check components/casting/player/CastPlayerProgressBar.tsx "app/(auth)/casting-player.tsx" hooks/useCastPlayerProgress.ts`
Expected: PASS on these files.
- [ ] **Step 4: Commit**
```bash
git add components/casting/player/CastPlayerProgressBar.tsx "app/(auth)/casting-player.tsx" hooks/useCastPlayerProgress.ts
git commit -m "fix(casting): clamp trickplay bubble via slider bubbleWidth"
```
---
## Task 3: Rework `CastingMiniPlayer`
**Files:**
- Modify: `components/casting/CastingMiniPlayer.tsx`
- [ ] **Step 1: Apply the same bubble fix**
Read `components/casting/CastingMiniPlayer.tsx`. Make these changes:
**(a)** Replace the entire `renderBubble={() => { ... }}` prop (the ~110-line manual-positioning callback) with:
```tsx
renderBubble={() => (
<CastTrickplayBubble
trickPlayUrl={trickPlayUrl}
trickplayInfo={trickplayInfo}
trickplayTime={trickplayTime}
tileWidth={140}
/>
)}
bubbleWidth={trickPlayUrl && trickplayInfo ? 140 : 60}
```
**(b)** `scrubPercentage` is local state here (`const [scrubPercentage, setScrubPercentage] = useState(0);`) used only by the deleted positioning maths. Remove that `useState` and the `setScrubPercentage(...)` call inside `onValueChange` (keep the `calculateTrickplayUrl` / `setTrickplayTime` logic).
**(c)** Add the import `import { CastTrickplayBubble } from "@/components/casting/player/CastTrickplayBubble";`. Remove now-unused imports: `Image` (only if no longer used — the mini-player still renders a poster `Image`, so keep `Image`), `Dimensions`, `formatTrickplayTime`. Verify each with a quick search before removing.
- [ ] **Step 2: Add the stop button**
In the mini-player's control area there is one button — the play/pause `Pressable` (icon `play`/`pause`). Add a **stop** button immediately before it (so the row reads: stop, play/pause), inside the same controls container:
```tsx
{/* Stop button */}
<Pressable
onPress={(e) => {
e.stopPropagation();
remoteMediaClient?.stop()?.catch((error: unknown) => {
console.error("[CastingMiniPlayer] Stop error:", error);
});
}}
style={{ padding: 8 }}
>
<Ionicons name='stop' size={24} color='white' />
</Pressable>
```
Once the media stops, `mediaStatus.playerState` becomes `IDLE` and the component already returns `null` (it hides itself). `e.stopPropagation()` prevents the row's "open player" press from also firing.
- [ ] **Step 3: Verify**
Run: `bun run typecheck`
Expected: PASS — fully green.
Run: `bunx biome check components/casting/CastingMiniPlayer.tsx`
Expected: PASS.
- [ ] **Step 4: Commit**
```bash
git add components/casting/CastingMiniPlayer.tsx
git commit -m "feat(casting): mini-player trickplay fix and stop button"
```
---
## Task 4: Touch-zone debug overlay
**Files:**
- Create: `utils/casting/debug.ts`
- Modify: `components/casting/player/CastPlayerProgressBar.tsx`
- Modify: `components/casting/player/CastPlayerEpisodeControls.tsx`
- [ ] **Step 1: Create the debug flag**
Create `utils/casting/debug.ts`:
```ts
/**
* Developer flag for visualising touch zones in the casting player.
*
* Flip to `true` to draw red outlines over the slider hit area and the control
* row, run the app, hand-calibrate `panHitSlop`, then flip back to `false`.
* Gate every use with `__DEV__` so it can never render in a release build.
*/
export const DEBUG_TOUCH_ZONES = false;
```
- [ ] **Step 2: Draw the slider hit-zone overlay in `CastPlayerProgressBar.tsx`**
In `components/casting/player/CastPlayerProgressBar.tsx`, add the import:
```tsx
import { DEBUG_TOUCH_ZONES } from "@/utils/casting/debug";
```
The slider sits inside `<View style={{ marginTop: 8, height: 40 }}>`. The slider's
effective touch area is the slider plus its `panHitSlop`. Inside that container
`View`, after the `<Slider .../>`, add a debug overlay that traces the hit area —
use the *same* `panHitSlop` values the `Slider` is given so the box matches:
```tsx
{__DEV__ && DEBUG_TOUCH_ZONES && (
<View
pointerEvents='none'
style={{
position: "absolute",
top: -12,
bottom: -12,
left: -10,
right: -10,
borderWidth: 1,
borderColor: "red",
}}
/>
)}
```
(The `top/bottom/left/right` offsets mirror the `panHitSlop` from Task 2 step 1b —
if `panHitSlop` is changed, change these to match so the overlay stays accurate.)
- [ ] **Step 3: Draw the control-row overlay in `CastPlayerEpisodeControls.tsx`**
In `components/casting/player/CastPlayerEpisodeControls.tsx`, add the import:
```tsx
import { DEBUG_TOUCH_ZONES } from "@/utils/casting/debug";
```
The component's root is a `<View>` (the absolute-positioned button row). As the
last child of that root `View`, add:
```tsx
{__DEV__ && DEBUG_TOUCH_ZONES && (
<View
pointerEvents='none'
style={{
position: "absolute",
top: 0,
bottom: 0,
left: 0,
right: 0,
borderWidth: 1,
borderColor: "lime",
}}
/>
)}
```
- [ ] **Step 4: Verify**
Run: `bun run typecheck`
Expected: PASS — fully green.
Temporarily set `DEBUG_TOUCH_ZONES` to `true`, run `bun run typecheck` again to
confirm both `__DEV__ && DEBUG_TOUCH_ZONES` branches still type-check, then set it
back to `false` before committing.
Run: `bunx biome check utils/casting/debug.ts components/casting/player/CastPlayerProgressBar.tsx components/casting/player/CastPlayerEpisodeControls.tsx`
Expected: PASS on these files.
- [ ] **Step 5: Commit**
```bash
git add utils/casting/debug.ts components/casting/player/CastPlayerProgressBar.tsx components/casting/player/CastPlayerEpisodeControls.tsx
git commit -m "feat(casting): add DEBUG_TOUCH_ZONES overlay for hit-area calibration"
```
---
## Final verification
- [ ] **Checks**
Run: `bun run typecheck` → PASS.
Run: `bun test utils/` → PASS (unchanged suites).
- [ ] **Manual verification** (Android emulator)
- Scrub the main progress bar to the far left and far right — the trickplay
preview is never clipped at the screen edge and tracks the cursor; the time text
is plain white, legible, above the preview.
- Same on the mini-player progress bar.
- The mini-player stop button stops playback and the mini-player disappears.
- The 4 episode-row buttons are tappable (no slider-slop overlap).
- Flip `DEBUG_TOUCH_ZONES` to `true`: red outline on the slider hit area, lime
outline on the control row are visible — use them to confirm / hand-tune
`panHitSlop`, then set the flag back to `false`.
---
## Notes for the implementer
- Line numbers drift — match on quoted code.
- This is UI work; there is no pure logic to unit-test. `bun run typecheck` per task
plus the manual checks are the gate.
- Do NOT add a `Co-Authored-By` trailer to commit messages.
- The `renderBubble` blocks in `CastPlayerProgressBar.tsx` and `CastingMiniPlayer.tsx`
are near-identical today — both are replaced by the shared `CastTrickplayBubble`.
- Out of scope: the custom receiver, the queued feature ideas.

251
docs/superpowers/specs/2026-05-21-chromecast-profiles-design.md
View File

@@ -1,251 +0,0 @@
# Chromecast Device Profiles & Capability Detection — Design
**Date:** 2026-05-21
**Branch:** `refactor-chromecast` (PR #1402)
**Sub-project:** A (cornerstone) of the Chromecast refactor
**Status:** Approved design — pending implementation plan
---
## 1. Problem
Casting to Chromecast crashes for a large class of media:
- `Media control channel status code 2100` (LOAD_FAILED) on movies and high-bitrate media.
- 5.1 / multichannel audio crashes the receiver (issue #1085).
- Casting reportedly only works at video bitrate ≤ 2 Mb/s (issue #1423).
- Movies fail to load entirely; some media loads forever.
**Root cause:** the sender ships a device profile that does not match the actual
Chromecast. Two near-identical static profiles (`utils/profiles/chromecast.ts`,
`utils/profiles/chromecasth265.ts`) are selected by a single global boolean
`enableH265ForChromecast`. A 1st/2nd/3rd-gen Chromecast (H.264-only, 1080p, 2-channel
audio, no HEVC) can receive an HEVC / 10-bit / high-bitrate stream it cannot decode,
producing status 2100.
Secondary defects in the load path:
- `getStreamUrl` defaults `audioStreamIndex` to `0`, which is the video stream — wrong
audio track selection.
- `getStreamUrl` always takes `MediaSources[0]`, ignoring a requested `mediaSourceId`.
- Progress reporting uses `mediaInfo.contentId` (the item id) as `PlaySessionId` — the
Jellyfin dashboard cannot correlate the session.
- The load sequence (`getStreamUrl` → `buildCastMediaInfo` → `client.loadMedia`) is
duplicated in three places: `PlayButton.tsx`, and `casting-player.tsx`
(`reloadWithSettings` and `loadEpisode`).
- `loadMedia` failures are swallowed into `console.error` — the user sees nothing.
## 2. Scope
**In scope**
- Per-device Chromecast capability detection.
- A profile builder replacing the two static profile files.
- A single unified cast-load function.
- The load-path bug fixes listed above.
- Settings migration from `enableH265ForChromecast` to an explicit profile mode.
- Failure resilience (downgrade-on-failure retry, user-visible errors).
- A test matrix to empirically calibrate conservative defaults.
**Out of scope** (later sub-projects)
- Audio / subtitle / quality track switching — sub-project B.
- Splitting the 52 KB `casting-player.tsx` — sub-project C.
- Episode navigation, remote controller, UX features — sub-project D.
- Custom Cast receiver (PR #1521) — separate later sub-project.
## 3. Approach
Approach 3 of the brainstorm: a **profile builder** driven by a **capability
registry** with a **conservative default**, plus **advanced override settings**.
Detection produces smart defaults; power users can override. An unknown device always
falls back to a safe baseline (H.264 / 1080p / 2 channels) that cannot crash the
receiver. The user's test hardware (Chromecast 1/2/3 HD) maps exactly onto that
baseline.
## 4. Architecture
### New modules
| File | Responsibility |
|---|---|
| `utils/casting/capabilities.ts` | `ChromecastCapabilities` type, model registry, `detectCapabilities(device, settings)` |
| `utils/casting/buildProfile.ts` | `buildChromecastProfile(caps)` → Jellyfin `DeviceProfile` |
| `utils/casting/castLoad.ts` | `loadCastMedia(...)` — unified load, used by all call sites |
### Removed
- `utils/profiles/chromecast.ts`
- `utils/profiles/chromecasth265.ts`
### Modified
- `components/PlayButton.tsx` — use `loadCastMedia`.
- `app/(auth)/casting-player.tsx` — `reloadWithSettings` and `loadEpisode` use `loadCastMedia`.
- `utils/atoms/settings.ts` — replace `enableH265ForChromecast`.
- Chromecast settings UI (`ChromecastSettings.tsx` / `ChromecastSettingsMenu.tsx`) — new controls.
## 5. Capability model
```ts
export interface ChromecastCapabilities {
/** HEVC 8-bit (Main profile) decode support. */
hevc: boolean;
/** HEVC 10-bit (Main10) decode support. */
hevc10bit: boolean;
/** Maximum video resolution height. */
maxResolution: 1080 | 2160;
/** Maximum video bitrate in bits/second. */
maxVideoBitrate: number;
/** Maximum audio channels the receiver can output. */
maxAudioChannels: number;
}
```
### Conservative default
Used for any unrecognised device. Equals a 1st/2nd/3rd-gen Chromecast:
```ts
const CONSERVATIVE: ChromecastCapabilities = {
hevc: false,
hevc10bit: false,
maxResolution: 1080,
maxVideoBitrate: 8_000_000, // initial guess — calibrated by the test matrix
maxAudioChannels: 2,
};
```
> `maxVideoBitrate` starts at 8 Mb/s. Issue #1423 (≤ 2 Mb/s) is suspicious — 2 Mb/s is
> below any real hardware limit and likely points to a transcode-readiness or HLS
> issue rather than a bitrate ceiling. The test matrix (§9) confirms the true value
> before this number is finalised.
### Registry
Keyed by `device.modelName`. Initial entries:
- `"Chromecast"` — gen 1/2/3 → conservative baseline.
- `"Chromecast Ultra"` — HEVC, 2160p, higher bitrate, multichannel passthrough.
- `"Chromecast with Google TV"` — HEVC, HEVC 10-bit.
- `"Google TV Streamer"` — HEVC, HEVC 10-bit, 2160p.
`modelName` is ambiguous (gen 1/2/3 all report `"Chromecast"`, and Google TV devices
may report a TV model string). This is acceptable: the registry only *upgrades* away
from the conservative baseline for confidently-identified devices; everything else
stays safe.
### `detectCapabilities(device, settings)`
1. Look up `device.modelName` in the registry; fall back to `CONSERVATIVE`.
2. Apply advanced settings overrides:
- `chromecastProfile: "force-hevc"` → `hevc: true`.
- `chromecastProfile: "force-h264"` → `hevc: false, hevc10bit: false`.
- `chromecastMaxBitrate` set → clamp `maxVideoBitrate`.
3. Return the merged capabilities.
## 6. Profile builder
`buildChromecastProfile(caps)` returns a Jellyfin `DeviceProfile`:
- **Video codecs:** `h264` always; `hevc` only when `caps.hevc`. When `hevc` is
enabled but `caps.hevc10bit` is false, add a codec condition rejecting 10-bit so the
server transcodes 10-bit sources down.
- **Audio:** both `DirectPlayProfiles` and `CodecProfiles` constrained to
`caps.maxAudioChannels`. This forces multichannel audio to transcode to stereo —
fixes the 5.1 crash (#1085). The current profiles only constrain `CodecProfiles`,
leaving a direct-play path open.
- **Bitrate:** `MaxStreamingBitrate` / `MaxStaticBitrate` = `caps.maxVideoBitrate`.
- **Resolution:** codec condition capping height at `caps.maxResolution`.
- Subtitle and container profiles preserved from the current working profile.
## 7. Unified cast load
```ts
loadCastMedia({
client, // RemoteMediaClient
device, // Cast Device — for capability detection
api, item, userId,
settings,
options: { audioStreamIndex?, subtitleStreamIndex?, maxBitrate?, mediaSourceId?, startPositionMs? },
}): Promise<{ ok: true } | { ok: false; error }>
```
Sequence:
1. `detectCapabilities(device, settings)` → `buildChromecastProfile`.
2. `getStreamUrl` with the built profile.
3. `buildCastMediaInfo`.
4. `client.loadMedia`.
Replaces all three duplicated call sites. Bug fixes folded in:
- **Audio index:** when `options.audioStreamIndex` is absent, resolve the media
source's `DefaultAudioStreamIndex` (or the first `Audio`-type stream) instead of
defaulting to `0`.
- **Media source:** pass and honour `mediaSourceId`; select the matching
`MediaSource` rather than `[0]`.
- **PlaySessionId:** use the real `PlaySessionId` returned by `getStreamUrl`'s
`getPlaybackInfo` call, not `contentId`.
## 8. Settings
Replace `enableH265ForChromecast: boolean` with:
| Setting | Type | Default |
|---|---|---|
| `chromecastProfile` | `"auto" \| "force-hevc" \| "force-h264"` | `"auto"` |
| `chromecastMaxBitrate` | `number \| undefined` | `undefined` |
**No migration.** `enableH265ForChromecast` is removed outright — no migration code.
`chromecastProfile` defaults to `"auto"`, the correct behaviour for almost every user.
Anyone who had H265 forced reconfigures it once. Avoids carrying migration logic for a
niche setting.
UI: a profile-mode selector and an optional max-bitrate field in the Chromecast
settings screen. `"auto"` is presented as the recommended default; the overrides are
advanced controls.
## 9. Resilience
- **Downgrade-on-failure:** if `client.loadMedia` rejects with status 2100, retry
exactly once with a forced conservative profile (`force-h264`, 2 channels, low
bitrate). Handles unknown / mis-detected devices gracefully. A second failure
surfaces to the user.
- **User-visible errors:** a failed load shows an alert with an actionable message
instead of a silent `console.error`.
## 10. Verification — test matrix
A document, `docs/chromecast-test-matrix.md`, lists sample-file casting tests run
against the Chromecast HD test device:
| Dimension | Values |
|---|---|
| Video codec | H.264, HEVC 8-bit, HEVC 10-bit |
| Audio | AAC stereo, AAC 5.1, AC3 5.1, DTS, TrueHD |
| Container | MP4, MKV, TS |
| Bitrate | low, ~8 Mb/s, ~16 Mb/s, source-max |
Each row records: direct-play vs transcode, load result (OK / 2100 / infinite), notes.
Results calibrate `CONSERVATIVE.maxVideoBitrate` and confirm the true cause of #1423
and the 5.1 crash before the conservative defaults are finalised.
## 11. Success criteria
- A movie that previously failed with 2100 plays on the Chromecast HD.
- 5.1 / multichannel media plays (transcoded to stereo) without crashing.
- High-bitrate media plays or transcodes cleanly within the calibrated limit.
- Audio track defaults to the correct (non-video) stream.
- The Jellyfin dashboard shows a correctly correlated cast session.
- The load sequence exists in exactly one place.
- `bun run typecheck` and `bun run check` pass.
## 12. Risks
- The true cause of #1423 / the 5.1 crash is not yet confirmed; the test matrix
(§10) is the gate before defaults are locked. If the cause is HLS handling rather
than a profile mismatch, the design extends with a targeted fix at that point.
- `modelName` ambiguity limits registry precision — mitigated by the conservative
default never producing an unplayable stream.

222
docs/superpowers/specs/2026-05-21-chromecast-track-switching-design.md
View File

@@ -1,222 +0,0 @@
# Chromecast Track Switching & Multi-Version — Design
**Date:** 2026-05-21
**Branch:** `refactor-chromecast` (PR #1402)
**Sub-project:** B of the Chromecast refactor
**Status:** Approved design — pending implementation plan
---
## 1. Problem
Audio, subtitle, and quality switching on the Chromecast player are unreliable. The
visible symptom: the UI labels a track (e.g. Japanese audio) while the cast actually
plays a different one (e.g. French).
Root cause — track selection is built on React state that desyncs from what is
actually loaded on the receiver:
- **Audio.** `selectedAudioTrackIndex` is reset to `null` by `loadEpisode`. It is
re-initialised only by a `useEffect` keyed on `fetchedItem`, which does **not**
refresh on an episode change (`currentItem` updates from cast `customData`, not a
refetch). So after an episode change the index stays `null` and the menu falls back
to `availableAudioTracks[0]` — an arbitrary track, not the server default that is
actually playing.
- **Quality.** `selectedMediaSource` is hardcoded to `availableMediaSources[0]`
("Max"). There is no state for it at all — picking a quality never updates the UI.
- **`availableMediaSources` is fake.** It is a list of synthetic bitrate variants
(Max / 8 / 4 / 2 / 1 Mb/s) dressed up as `MediaSource` objects. The item's real
`MediaSources` (multi-version files) are ignored — only `[0]` is ever used.
- **No source of truth.** A transcoded cast stream collapses to a single baked-in
audio track, so the only truth for "what is selected" is the set of indices last
sent to `getStreamUrl`. Today that truth is scattered across React state that drifts.
## 2. Scope
**In scope**
- Reliable switching of audio track, subtitle track, quality (bitrate cap), and
version (real `MediaSource`).
- A single source of truth for the active selection, so the UI always reflects what
is actually loaded on the cast.
- A real multi-version selector built from the item's actual `MediaSources`,
separated from the bitrate "Quality" axis.
**Out of scope** (other sub-projects)
- Subtitle rendering and styling — sub-project: custom receiver.
- Sidecar VTT vs burned-in vs receiver-rendered subtitle delivery — a single
decision belonging to the custom-receiver sub-project (see §10).
- Splitting `casting-player.tsx` (52 KB) — sub-project C.
- Remote-control panel, episode navigation — sub-project D.
## 3. Subtitle delivery
Sub-project B keeps the **current burned-in** delivery: the server burns the chosen
subtitle into the transcoded video; a change triggers a stream reload like any other.
B treats a subtitle purely as an index in the selection model — it is **receiver
delivery-agnostic** and contains no burned-in/sidecar branching.
The burned-in vs sidecar-VTT vs receiver-rendered decision is deferred in full to the
custom-receiver sub-project, where an actual receiver type exists to detect. This
mirrors sub-project A, which decoupled the custom receiver from the crash fixes.
## 4. The selection model
A single object represents everything loaded on the cast:
```ts
export interface CastSelection {
/** Which MediaSource (version) is playing. */
mediaSourceId: string;
/** Absolute MediaStream index of the audio track. */
audioStreamIndex: number;
/** Absolute MediaStream index of the subtitle track; -1 = subtitles off. */
subtitleStreamIndex: number;
/** Quality cap in bits/second; undefined = unconstrained. */
maxBitrate?: number;
}
```
`resolveSelection(item, partial)` produces a complete `CastSelection` from a partial
one by filling missing fields with server defaults:
- `mediaSourceId` → the requested source, else the item's first `MediaSource`.
- `audioStreamIndex` → `resolveDefaultAudioIndex(item, mediaSourceId)` (the helper
added in sub-project A — reuse it).
- `subtitleStreamIndex` → the source's `DefaultSubtitleStreamIndex`, else `-1`.
- `maxBitrate` → passed through (`undefined` allowed).
Used on first load and on every episode change. On an explicit switch the caller
already holds the full current selection, so it merges `{...current, ...partial}`.
## 5. Source of truth — customData (approach A3)
`loadCastMedia` knows the exact `CastSelection` it sent. It embeds the resolved
selection into the Cast `customData`, exactly as sub-project A did with
`playSessionId`. `buildCastMediaInfo`'s slim `customData` gains `selection`.
The Default Media Receiver echoes `customData` back in `mediaStatus.mediaInfo`.
`casting-player` reads `mediaStatus.mediaInfo.customData.selection` — that is the
**truth**: what is actually loaded on the cast. It cannot desync, it survives
leaving and re-entering the player, and it survives app backgrounding.
### Optimistic pending state
A switch triggers a stream reload (re-transcode), which takes a few seconds. To keep
the UI responsive:
1. The user picks a track. The UI sets a local `pendingSelection` (the chosen value)
and triggers the reload.
2. The UI renders `pendingSelection` immediately.
3. When the new `mediaStatus` arrives with a `customData.selection` that matches the
request, `pendingSelection` is cleared and the UI reads the truth again.
4. If the reload fails, `pendingSelection` is cleared and the UI reverts to the truth.
The UI's effective selection is: `pendingSelection ?? customData.selection ??
<default derived from currentItem>`.
## 6. `useCastSelection` hook
A new hook, `hooks/useCastSelection.ts`, encapsulates approach A3:
- Reads `customData.selection` from `mediaStatus` as the truth.
- Holds the `pendingSelection` and clears it on reconciliation or failure.
- Exposes `currentSelection` (the effective selection) and `applySelection(partial)`,
which merges the partial into the current selection, sets pending, and invokes a
caller-supplied reload callback.
The reload itself stays in `casting-player` (it owns `remoteMediaClient`,
`castDevice`, `api`). The hook owns only selection state. This keeps `casting-player`
thinner and gives sub-project C (the file split) a clean unit to extract.
## 7. `casting-player.tsx` rework
- **Remove:** raw `selectedAudioTrackIndex` / `selectedSubtitleTrackIndex` state, the
synthetic `availableMediaSources` bitrate generator, the hardcoded
`selectedMediaSource={availableMediaSources[0]}`, and the `setSelected…(null)` calls
in `loadEpisode`.
- **Add:** `useCastSelection` for the active selection.
- `availableVersions` — the item's real `currentItem.MediaSources` (id, name,
bitrate, container).
- `availableQualities` — the bitrate-cap options, a **separate axis** from version;
this is the real `maxStreamingBitrate` transcode cap, no longer disguised as media
sources. It reuses the app-wide `BITRATES` constant
(`components/BitrateSelector.tsx`) — no cast-specific list — and `BITRATES` is
expanded to the fuller Jellyfin Android TV bitrate ladder so every surface (cast,
native player, downloads) gains the extra tiers. The cast menu filters `BITRATES`
to tiers at or below **both** the connected device's `maxVideoBitrate` (from
sub-project A's `detectCapabilities`) and the media's own bitrate, so only
meaningful tiers are shown.
- `availableAudioTracks` / `availableSubtitleTracks` — derived from the **selected
version's** `MediaStreams`, not always `MediaSources[0]`.
- Every "selected" indicator reads from `currentSelection`.
## 8. `ChromecastSettingsMenu.tsx` rework
Distinct sections: **Version** (shown only when the item has more than one
`MediaSource`), **Quality** (bitrate cap), **Audio**, **Subtitles**, **Speed**. Each
section's selected row is driven by `currentSelection` — the `[0]` fallback is gone.
## 9. Episode change
`loadEpisode` calls `loadCastMedia`, which resolves the new episode's defaults via
`resolveSelection` and embeds them in `customData`. `useCastSelection` reads the new
`customData.selection`, so the UI re-syncs automatically. The `setSelected…(null)`
calls are removed. This fixes the "UI says Japanese, plays French" bug at its root.
## 10. Reload semantics
Every audio / subtitle / quality / version change is a `loadCastMedia` reload
(re-transcode) that resumes at the current position — the same mechanism
`loadEpisode` already uses. Burned-in subtitles mean a subtitle change reloads too;
this is consistent with audio. The `pendingSelection` covers the re-buffer gap.
## 11. Files
| File | Change |
|---|---|
| `utils/casting/types.ts` | Add `CastSelection` |
| `utils/casting/castLoad.ts` | Add `resolveSelection`; embed the resolved selection in the load |
| `utils/casting/mediaInfo.ts` | `buildCastMediaInfo` customData carries `selection` |
| `hooks/useCastSelection.ts` | New — A3 selection state (truth + pending) |
| `app/(auth)/casting-player.tsx` | Replace track state with `useCastSelection`; real versions + separate quality axis |
| `components/chromecast/ChromecastSettingsMenu.tsx` | Separate Version / Quality sections; selected rows from `currentSelection` |
| `components/BitrateSelector.tsx` | Expand the shared `BITRATES` ladder (Jellyfin Android TV tiers) |
The `BITRATES` expansion is a one-array change to a shared constant. It is
deliberately app-wide: the native player and downloads bitrate menus gain the same
tiers, which is the requested behaviour.
## 12. Testing
Pure, unit-testable with `bun test`:
- `resolveSelection` — default resolution for each field, partial merge.
- The effective-selection merge (`pending ?? truth ?? default`).
UI and integration paths are verified by `bun run typecheck` and manual casting.
## 13. Success criteria
- Switching audio: the UI label always matches the track that actually plays.
- Switching subtitle, quality, and version all reflect in the UI and apply to the
stream.
- After an episode change, the UI shows the new episode's real default tracks — the
Japanese/French desync is gone.
- Leaving and re-entering the casting player preserves the correct selection display.
- A multi-version item shows a working Version selector.
- `bun run typecheck` passes; `bun test utils/casting/` passes.
## 14. Risks
- The customData round-trip depends on the receiver echoing `customData` in
`mediaStatus` — confirmed working in sub-project A via `playSessionId`.
- During a reload there is a brief window where `customData` is stale; the
`pendingSelection` overlay covers it.
- Multi-version **episodes** require Jellyfin 12.0 (PR #16828); multi-version
**movies** work on current Jellyfin. The Version selector simply shows whatever
`MediaSources` the item exposes, so it degrades gracefully on older servers.
- The downgrade-on-failure retry (sub-project A) clamps bitrate internally; the
`customData.selection` reflects the user's intended selection, not the retry's
internal clamp. This is intentional — the selection model represents user choice.

176
docs/superpowers/specs/2026-05-22-chromecast-autoplay-countdown-design.md
View File

@@ -1,176 +0,0 @@
# Chromecast Autoplay & Next-Episode Countdown — Design
**Date:** 2026-05-22
**Branch:** `refactor-chromecast` (PR #1402)
**Sub-project:** Autoplay + countdown, of the Chromecast refactor
**Status:** DEFERRED — paused pending the chapters sub-project.
> This design is sound but on hold. During brainstorming it became clear the
> autoplay trigger should fire at the **Outro / credits media segment** (so the
> countdown runs over the credits, no black screen), not only at the hard
> `IDLE + FINISHED` end. That trigger builds naturally on chapter / media-segment
> work, so the **chapters sub-project is being done first**. When resuming:
> revise §3 to a two-path trigger — (a) playback enters the Outro segment when
> `skipOutro` is not `auto`, (b) `IDLE + FINISHED` as fallback — and fold §9 into
> §3. The next episode's intro is already auto-skipped by the existing
> `useSegmentSkipper` (`skipIntro`), so binge-watching needs no extra intro work.
---
## 1. Problem & goal
When an episode finishes on the Chromecast, playback stops — there is no
auto-advance to the next episode. Binge-watching requires the user to pick up the
phone and load the next episode manually.
**Goal:** when a cast episode finishes, automatically continue to the next episode,
with a cancellable countdown. This must work **whenever casting**, regardless of
which app screen the phone shows — the video is on the TV, the phone may be on the
home screen or locked.
## 2. Scope
**In scope:** detect a finished cast episode, resolve the next episode, run a
cancellable countdown, load the next episode, honour the shared autoplay settings.
**Out of scope (future evolution — see §9):** triggering the prompt at the start of
the credits/outro instead of at the hard end of the episode; a "skip credits"
button. These depend on chapter / media-segment work not yet in place.
## 3. Episode-end detection
A watcher subscribes to `useMediaStatus()` from `react-native-google-cast`.
- An episode has **finished** when `playerState === MediaPlayerState.IDLE` **and**
`idleReason === MediaPlayerIdleReason.FINISHED`. Other idle reasons
(`CANCELLED`, `INTERRUPTED`, `ERROR`) mean the user stopped or a failure — **no
autoplay**.
- At the moment `IDLE` is reported, `mediaStatus.mediaInfo` is already cleared. So
the watcher must **continuously capture the currently-playing item** (and its
series context) while playback is active, and use that captured item when the
`IDLE + FINISHED` transition fires.
## 4. Always-mounted watcher
Autoplay must fire regardless of the active screen, so the logic cannot live in the
casting-player screen (not always mounted) nor in `CastingMiniPlayer` (it returns
`null` — and unmounts its render — exactly when the episode ends).
- `useCastAutoplay` — a hook holding the watcher logic.
- `CastAutoplayWatcher` — a tiny component that calls `useCastAutoplay()` and
renders `null`. It is mounted once, next to where `CastingMiniPlayer` is mounted
in the layout, so it runs for the whole app lifetime.
On an `IDLE + FINISHED` transition the watcher: confirms the finished item is an
episode, resolves the next episode (§7), checks the settings (§6), and — if all
clear — starts the countdown (§5).
## 5. Countdown & overlay
The countdown state lives in a Jotai atom so the watcher can drive it and any
screen can render it:
```ts
// utils/atoms/castAutoplay.ts
type CastAutoplayState = {
nextEpisode: BaseItemDto;
secondsRemaining: number;
} | null;
```
- The watcher sets the atom to `{ nextEpisode, secondsRemaining: 30 }` and runs a
1-second interval decrementing `secondsRemaining`.
- At `0`: the watcher loads `nextEpisode` on the cast (`loadCastMedia`), increments
`autoPlayEpisodeCount`, and clears the atom.
- **Countdown duration: 30 seconds**, a single named constant.
**Overlay** — `CastAutoplayCountdown`, rendered inside `casting-player.tsx`. When
the atom is set it shows: the next episode's poster + title, "Next episode in
{n}s", and two buttons — **Play now** (load immediately) and **Cancel** (clear the
atom; no load). Because the overlay lives in the casting-player screen, it is
visible only when that screen is open.
When the casting-player screen is **not** open, the watcher still counts down and
loads — there is no intrusive full-screen overlay; a short toast is shown when the
next episode actually loads ("Playing next episode"). The toast fires
unconditionally (harmless when the overlay was also shown).
## 6. Settings (shared with the native player)
Reuse the existing settings in `utils/atoms/settings.ts` — no new settings:
- `autoPlayNextEpisode` (boolean, default `true`) — master on/off. When `false`,
the watcher does nothing.
- `autoPlayEpisodeCount` (number) — running count of consecutive autoplays.
Incremented each time the countdown completes a load.
- `maxAutoPlayEpisodeCount` (`{ key, value }`, default `3`) — when
`autoPlayEpisodeCount >= maxAutoPlayEpisodeCount.value`, the watcher does **not**
start a countdown (autoplay pauses; the user resumes manually). This mirrors the
native player's "are you still watching?" gate.
- The count resets to `0` on any **manual** play — "Play now" in the overlay, or
loading an episode from the episode list. (Manual intent restarts the streak.)
## 7. Next-episode resolution
`useCastEpisodes` already fetches a series' episodes and computes the next one, but
it is tied to the casting-player screen. Extract the reusable part — "given an
episode item, fetch its series' episodes and return the next one" — into a shared
async helper (e.g. `utils/casting/episodes.ts`). Both `useCastEpisodes` and
`useCastAutoplay` use it, so the next-episode logic exists once.
## 8. Units & files
**Created**
- `utils/atoms/castAutoplay.ts` — the countdown-state atom + the duration constant.
- `utils/casting/episodes.ts` — reusable "resolve next episode" helper.
- `hooks/useCastAutoplay.ts` — the watcher hook.
- `components/casting/CastAutoplayWatcher.tsx` — always-mounted host (renders null).
- `components/casting/player/CastAutoplayCountdown.tsx` — the countdown overlay.
**Modified**
- The layout file where `CastingMiniPlayer` is mounted — also mount
`CastAutoplayWatcher`.
- `app/(auth)/casting-player.tsx` — render `CastAutoplayCountdown`.
- `hooks/useCastEpisodes.ts` — use the extracted `utils/casting/episodes.ts` helper.
## 9. Future evolution — credits trigger
The watcher's **trigger point** is deliberately isolated: today it is the
`IDLE + FINISHED` transition. When Jellyfin media-segment / chapter data for
"Outro" / "Credits" is exploited on the cast, the trigger should move to the
**start of the credits** — the countdown overlay appears over the still-playing
credits, with an added "skip credits" action. Only the trigger changes; the
countdown, atom, overlay, settings and load path stay as designed. The
implementation must keep the trigger detection in one clearly-separable place so
this swap is a localised change.
## 10. Testing
- Unit-test the pure logic with `bun test`: the next-episode resolution (given an
episode list + current episode → the correct next episode, or none for the last
episode) and the "should autoplay?" decision (settings + idle reason → start
countdown or not).
- Manual: cast an episode, let it finish — the countdown overlay appears, counts
from 30, and the next episode loads; "Cancel" stops it; "Play now" loads
immediately; with the casting-player screen closed the next episode still loads;
after `maxAutoPlayEpisodeCount` consecutive autoplays it stops.
## 11. Success criteria
- A finished cast episode auto-advances to the next, with a 30s cancellable
countdown, regardless of the active app screen.
- Autoplay respects `autoPlayNextEpisode` and stops after `maxAutoPlayEpisodeCount`.
- `CANCELLED` / `ERROR` idle reasons never trigger autoplay.
- The next-episode resolution lives in one shared helper.
- `bun run typecheck` and `bun test` pass.
## 12. Risks
- The captured-item timing: the watcher must capture the playing item *before*
`IDLE`. Capture it on every `mediaStatus` change while a real item is playing.
- The watcher and the casting-player screen could both react to the same media
state — the atom is the single source of truth; only the watcher writes the
countdown, only the overlay reads it.
- Loading the next episode requires the API/user context outside the player
screen — `loadCastMedia` is a standalone function and the watcher can obtain
`api` / `user` from the Jotai atoms, so this is available app-wide.

118
docs/superpowers/specs/2026-05-22-chromecast-player-split-design.md
View File

@@ -1,118 +0,0 @@
# Chromecast Player Split — Design
**Date:** 2026-05-22
**Branch:** `refactor-chromecast` (PR #1402)
**Sub-project:** C of the Chromecast refactor
**Status:** Approved design — pending implementation plan
---
## 1. Problem
`app/(auth)/casting-player.tsx` is a 1428-line god-component. One file owns: cast SDK
hooks, item fetching, live-progress tracking, slider/scrubbing, trickplay, track
selection, episode/season fetching, segment skipping, the dismiss gesture, and ~780
lines of JSX. It is hard to read, hard to change safely, and every sub-project so far
has had to navigate it.
## 2. Scope
**In scope:** a purely structural decomposition of `casting-player.tsx` into 4 custom
hooks, 6 presentational components, and a thin orchestrator.
**Out of scope — and a hard constraint:** **zero behaviour change.** This is a
mechanical extraction. No bug fixes, no feature changes, no logic edits. Known issues
in this code (the `loadEpisode` / `currentItem` race from sub-project A's review; the
trickplay window truncation, the progress-bar touch overlap, the time-label position)
are explicitly NOT touched here — they belong to a later UX sub-project, and are
easier to fix once the code lives in small focused files.
## 3. Architecture
`casting-player.tsx` becomes an orchestrator (~150-200 lines): it calls the hooks,
assembles the data, and renders the 6 components plus the 3 existing modal components.
State flows orchestrator → components by **props** (approved approach 1) — no React
context. Presentational components take typed props; all logic lives in hooks.
## 4. Hooks (`hooks/`)
| Hook | Extracts | Returns (shape) |
|---|---|---|
| `useCastPlayerItem` | `fetchedItem` state, its fetch effect, the `currentItem` derivation | `{ fetchedItem, currentItem }` |
| `useCastPlayerProgress` | slider shared values, `isScrubbing`, `trickplayTime`, `scrubPercentage`, `liveProgress`, the sync refs/effects, the `useTrickplay` call | slider state, scrub handlers, `progress`, trickplay data |
| `useCastEpisodes` | `episodes` / `nextEpisode` / `seasonData` state, their fetch effects, `loadEpisode` | `{ episodes, nextEpisode, seasonData, loadEpisode }` |
| `useCastDismissGesture` | `translateY`, `context`, `panGesture`, `dismissModal`, `animatedStyle` | `{ panGesture, animatedStyle, dismissModal }` |
Existing hooks are reused unchanged: `useCasting`, `useCastSelection`,
`useChromecastSegments`, `useTrickplay` (the latter called inside
`useCastPlayerProgress`).
`useCastPlayerProgress` is the most intricate hook (shared values, refs, the
live-progress interpolation) — it must be extracted with care and reviewed closely.
## 5. Components (`components/casting/player/`)
| Component | Extracts (JSX section) |
|---|---|
| `CastPlayerHeader` | dismiss chevron, connection indicator, settings button |
| `CastPlayerTitle` | title + episode/season info |
| `CastPlayerPoster` | poster image, buffering overlay, skip intro/credits bar |
| `CastPlayerEpisodeControls` | the 4-button row (Episodes / Previous / Next / Stop) |
| `CastPlayerProgressBar` | slider, trickplay preview, time display |
| `CastPlayerTransportControls` | rewind / play-pause / forward |
Each is a pure presentational component with typed props. The 3 modal components
(`ChromecastDeviceSheet`, `ChromecastEpisodeList`, `ChromecastSettingsMenu`) already
exist and stay as-is — the orchestrator keeps rendering them.
## 6. Constraints
- **Mechanical extraction only.** Each component's / hook's props and returns mirror
exactly what the inline code used. No new logic, no renamed behaviour, no fixes.
- Component prop interfaces are derived from what the extracted JSX references in the
original component scope.
- Follow existing repo conventions: hooks flat in `hooks/`; the new components grouped
under `components/casting/player/`.
## 7. Verification
The casting UI has no unit tests (consistent with the rest of the casting UI — it is
React Native / SDK-heavy). Verification is:
- `bun run typecheck` — green after every task (catches wiring/prop errors).
- `bun test utils/casting/` — stays green (the pure-logic suites are untouched).
- A full **manual re-test** of the cast player after the split: cast a movie and an
episode, switch audio / subtitle / quality / version, navigate episodes, scrub the
progress bar, trigger trickplay, dismiss the player. Behaviour must be identical to
before the split.
## 8. Files
**Created:**
- `hooks/useCastPlayerItem.ts`, `hooks/useCastPlayerProgress.ts`,
`hooks/useCastEpisodes.ts`, `hooks/useCastDismissGesture.ts`
- `components/casting/player/CastPlayerHeader.tsx`, `CastPlayerTitle.tsx`,
`CastPlayerPoster.tsx`, `CastPlayerEpisodeControls.tsx`,
`CastPlayerProgressBar.tsx`, `CastPlayerTransportControls.tsx`
**Modified:**
- `app/(auth)/casting-player.tsx` → thin orchestrator.
## 9. Success criteria
- `casting-player.tsx` is ~150-200 lines and contains no inline logic clusters or
large JSX sections — only hook calls and component composition.
- Each new file has one clear responsibility and a typed interface.
- `bun run typecheck` and `bun test utils/casting/` pass.
- The manual re-test shows behaviour identical to before the split.
## 10. Risks
- The hooks share state (progress feeds the slider, the time display, and segment
skipping). The extraction must preserve the exact data flow and effect ordering.
Mitigation: one hook / component per task, `bun run typecheck` after each, and a
full manual re-test at the end.
- `useCastPlayerProgress` carries reanimated shared values and timing refs — the
highest-risk extraction; its task gets the closest review.
- No unit tests guard the UI — the manual re-test is the only behavioural safety net.

181
docs/superpowers/specs/2026-05-22-chromecast-session-remote-control-design.md
View File

@@ -1,181 +0,0 @@
# Casting Session Reporting & Remote Control — Design
**Date:** 2026-05-22
**Branch:** `refactor-chromecast` (PR #1402)
**Sub-project:** D of the Chromecast refactor
**Status:** Approved design — pending implementation plan
---
## 1. Problem
Three issues plus one missing feature:
- **PlayMethod is wrong.** `useCasting.ts` reports a hardcoded `PlayMethod:
"DirectStream"` for every cast session. When the cast stream is a transcode
(almost always, given a HEVC-heavy library), the Jellyfin dashboard still labels
it "direct-play". The dashboard only reflects what the app reports.
- **Episode buttons are unconditional.** The Previous / Next buttons in the cast
player are always shown and active, even when there is no adjacent episode.
- **`loadEpisode` / `currentItem` race.** During an episode change, `currentItem`
(derived from cast `customData`) briefly still points at the previous episode
while the new one loads — flagged in sub-project B's review.
- **Remote control does not exist.** `WebSocketProvider` advertises
`SupportedCommands: ["Play"]` and handles only the `Play` WebSocket message. The
Jellyfin dashboard's remote-control panel (pause / stop / seek / message) sends
`Playstate` and `GeneralCommand` messages the app ignores — for the native player
too, not just casting. The panel does nothing because the feature was never built.
## 2. Scope
**In scope**
- Report the correct `PlayMethod` (`Transcode` vs `DirectPlay`) for cast sessions.
- Show / hide the Previous / Next episode buttons based on adjacent-episode
availability.
- Fix the `loadEpisode` / `currentItem` stale-window race.
- Implement app-wide Jellyfin remote control: handle `Playstate` and
`GeneralCommand` WebSocket messages (transport + volume + DisplayMessage), routed
to whichever player is active — cast, native video, or music.
**Out of scope**
- Track-switching remote commands (`SetAudioStreamIndex` / `SetSubtitleStreamIndex`).
- The custom Cast receiver.
## 3. The `PlaybackController` contract
The app has no unified playback-control abstraction — `usePlaybackManager` only does
progress reporting and metadata. Remote control needs one. Introduce a single
interface — the canonical control surface every player implements:
```ts
export interface PlaybackController {
playPause(): void;
pause(): void;
unpause(): void;
stop(): void;
/** Absolute seek position in milliseconds. */
seek(positionMs: number): void;
next(): void;
previous(): void;
/** Volume 0–1. */
setVolume(level: number): void;
toggleMute(): void;
}
```
A Jotai atom holds the currently-active controller:
```ts
export const activePlaybackControllerAtom = atom<PlaybackController | null>(null);
```
This is not duplicated code — each player *implements* the same small contract; the
cast already has every method in `useCasting`.
## 4. Registration
Each playback source registers its controller into the atom when it becomes the
active playback, and clears it when it stops:
- **Cast** — a controller built from `useCasting` (`togglePlayPause`, `pause`,
`play`, `stop`, `seek`, `setVolume`) plus episode `next` / `previous`. Registered
while a cast session is playing; cleared on disconnect.
- **Native video player** — `app/(auth)/player/direct-player.tsx` registers a
controller wrapping its player controls on mount; clears on unmount.
- **Music** — `MusicPlayerProvider` registers a controller while music plays.
**Priority:** a cast session takes precedence (if you are casting, the dashboard
controls the cast); then the native video player; then music. In practice only one
plays at a time, so registration is effectively last-active-wins with cast given
precedence.
## 5. WebSocket remote-control handler
A dedicated hook `useRemoteControl`, consumed by `WebSocketProvider`, handles the
incoming messages:
- `Playstate` — map `Data.Command` to the active controller:
`PlayPause`/`Pause`/`Unpause`/`Stop`, `Seek` (uses `Data.SeekPositionTicks`),
`NextTrack`/`PreviousTrack` → `next`/`previous`.
- `GeneralCommand` — `Data.Name`: `SetVolume` (→ `setVolume`, from
`Data.Arguments.Volume`), `ToggleMute`/`Mute`/`Unmute` (→ `toggleMute`),
`DisplayMessage` → an in-app toast via `sonner-native` (no controller involved).
- The existing `Play` handling is preserved unchanged.
- If no controller is registered, transport/volume commands are ignored;
`DisplayMessage` and `Play` still work.
The string→action mapping is a pure function, unit-tested.
## 6. Capabilities
`WebSocketProvider.postFullCapabilities` currently sends `SupportedCommands:
["Play"]`. Expand it to the `GeneralCommandType` values actually handled —
`["DisplayMessage", "SetVolume", "ToggleMute", "Mute", "Unmute"]` (plus `Play`).
`SupportsMediaControl: true` is already set, which is what enables the dashboard to
send `Playstate` commands.
## 7. Small fixes
- **PlayMethod.** `loadCastMedia` already knows whether the resolved stream is a
transcode (`getStreamUrl`'s media source carries a `TranscodingUrl`). Embed a
`playMethod: "Transcode" | "DirectPlay"` in the cast `customData` — the same
pattern as `playSessionId` and `selection` from sub-projects A and B. `useCasting`
reads it and reports it in `reportPlaybackStart` / `reportPlaybackProgress`
instead of the hardcoded `"DirectStream"`.
- **Conditional episode buttons.** `CastPlayerEpisodeControls` already receives
`episodes` and `nextEpisode`. Hide (or disable) Previous when the current item is
the first episode, and Next when there is no next episode.
- **`loadEpisode` race.** While an episode load is in flight, guard against acting
on a stale `currentItem`: track the loading episode id and treat `currentItem` as
pending until the cast `customData` reflects the new episode.
## 8. Files
**Created**
- `utils/playback/playbackController.ts` — the `PlaybackController` interface and
`activePlaybackControllerAtom`.
- `hooks/useRemoteControl.ts` — the WebSocket remote-control message handler.
**Modified**
- `providers/WebSocketProvider.tsx` — consume `useRemoteControl`; expand
`SupportedCommands`.
- `hooks/useCasting.ts` — report the real `PlayMethod`.
- `utils/casting/castLoad.ts`, `utils/casting/mediaInfo.ts` — embed `playMethod` in
`customData`.
- `components/casting/player/CastPlayerEpisodeControls.tsx` — conditional buttons.
- `app/(auth)/casting-player.tsx` — register the cast `PlaybackController`; fix the
`loadEpisode` race.
- `app/(auth)/player/direct-player.tsx` — register the native-video controller.
- `providers/MusicPlayerProvider.tsx` — register the music controller.
## 9. Testing
Unit-testable with `bun test`:
- The remote-command mapping (WS `Command` / `Name` string → controller action).
Routing, registration, capabilities, and the `DisplayMessage` toast are verified by
`bun run typecheck` and manual testing (drive the cast and native player from the
Jellyfin dashboard's remote-control panel).
## 10. Success criteria
- The Jellyfin dashboard shows `Transcode` for a transcoded cast session.
- The dashboard remote panel's pause / stop / seek / next / previous / volume
buttons control the active player (cast or native).
- A dashboard "Send message" appears as an in-app toast.
- Previous / Next cast buttons are hidden or disabled when no adjacent episode
exists.
- Changing episode no longer briefly shows the previous episode's data.
- `bun run typecheck` and `bun test utils/` pass.
## 11. Risks
- The native video player is screen-scoped; its controller is only registered while
the player screen is mounted. Remote commands arriving when no player is open are
correctly ignored — this is intended, not a bug.
- Multiple sources playing at once (e.g. music plus an idle cast session) is an
edge case; the cast-precedence rule resolves it deterministically.
- `customData` round-trip for `playMethod` relies on the receiver echoing
`customData` — already confirmed working in sub-project B.

129
docs/superpowers/specs/2026-05-22-chromecast-ux-player-design.md
View File

@@ -1,129 +0,0 @@
# Chromecast Player UX — Trickplay, Bubble & Mini-Player — Design
**Date:** 2026-05-22
**Branch:** `refactor-chromecast` (PR #1402)
**Sub-project:** UX player, of the Chromecast refactor
**Status:** Approved design — pending implementation plan
---
## 1. Problem
- **Trickplay preview is truncated.** When the scrub position is far right, the
trickplay preview window is cut off at the screen edge and does not track the
cursor cleanly. Root cause: `renderBubble` in `CastPlayerProgressBar.tsx` (and the
identical copy in `CastingMiniPlayer.tsx`) does its **own** absolute positioning
(`position: "absolute", left: clampedLeft`) on top of the slider's bubble
placement. `react-native-awesome-slider` already clamps the bubble within the
track **if `bubbleWidth` is set** — but the code never sets it, so the library
centres the bubble on the thumb with no clamp, and the manual offset fights it.
- **Duplication.** The ~110-line `renderBubble` block is copy-pasted between
`CastPlayerProgressBar.tsx` and `CastingMiniPlayer.tsx`.
- **Time bubble is heavy.** The scrub-time indicator is a purple
(`protocolColor`-background) bubble that takes too much visible space.
- **Touch zone overlaps.** The progress slider's `panHitSlop` is generous
(`top: 30` main / `top: 20` mini), so its touch area overlaps the 4-button
episode row — the buttons become hard or impossible to tap. The exact slop
values need hand-calibration on a device.
- **Mini-player has no stop button.** `CastingMiniPlayer` exposes only play/pause.
## 2. Scope
**In scope:** fix the trickplay/scrub-bubble positioning on both progress bars,
extract the duplicated bubble into a shared component, lighten the time display,
add a stop button to the mini-player, and add a developer overlay that visualises
the touch zones so `panHitSlop` can be hand-calibrated.
**Out of scope:** the custom Cast receiver, any visual redesign beyond the items
above, the queued feature ideas (autoplay countdown, sleep timer, …).
## 3. Bubble positioning fix
`react-native-awesome-slider`'s `<Slider>` accepts `bubbleWidth?: number` — "if you
set this value, bubble positioning left & right will be clamped." The fix:
- Set `bubbleWidth` on both sliders, **dynamically**: the trickplay tile width when
trickplay is available, the time-text width otherwise.
- `renderBubble` returns **only the bubble content** — no `position: "absolute"`,
no `left: clampedLeft`, no `thumbPosition` / `minLeft` / `maxLeft` maths. All of
that manual positioning is deleted; the slider clamps the bubble itself.
Result: the trickplay preview is never truncated, it tracks the cursor, and it is
clamped to the track at the edges.
## 4. Shared `CastTrickplayBubble` component
Create `components/casting/player/CastTrickplayBubble.tsx` — a single presentational
component that renders **either** the trickplay tile **or** the plain time text,
given the trickplay data and the current scrub time. Both `CastPlayerProgressBar`
and `CastingMiniPlayer` use it via `renderBubble`, with a `tileWidth` prop (220 for
the main player, 140 for the mini-player). This removes the ~220 lines of duplicated
`renderBubble` code and means the positioning is fixed in one place.
## 5. Time display
The scrub-time indicator becomes **plain white text** — no purple background bubble.
It is positioned **above** the preview: above the trickplay tile when trickplay is
shown, above the thumb otherwise. The purple `protocolColor` background bubble is
removed. The static current/ending/total time row below the slider is unchanged.
## 6. Mini-player stop button
`CastingMiniPlayer` gains a **stop** button (`stop-circle` icon) beside the existing
play/pause button. It calls `remoteMediaClient.stop()`; once the media stops the
mini-player hides itself (it already returns `null` on the `IDLE` state). The button
stops `stopPropagation` so it does not also trigger the row's "open player" press.
## 7. Touch-zone debug overlay
To let the touch zones be hand-calibrated, add a developer overlay:
- A module-level constant `DEBUG_TOUCH_ZONES`, default `false`, and gated by
`__DEV__` so it can never be active in a release build.
- When enabled, the casting player renders coloured-border overlay `View`s
(`pointerEvents: "none"` — they capture nothing, they only draw) tracing the
touch zones that matter for the overlap: the progress slider's effective hit area
(the slider box expanded by its `panHitSlop`) and the 4-button episode row.
- The developer flips the flag on, runs the Android emulator, sees the red-bordered
zones, adjusts `panHitSlop` until correct, then flips the flag back off.
`panHitSlop` itself is given a sensible default in this work; the precise values are
expected to be hand-tuned by the user with the overlay.
## 8. Files
**Created**
- `components/casting/player/CastTrickplayBubble.tsx` — shared trickplay/time bubble.
**Modified**
- `components/casting/player/CastPlayerProgressBar.tsx` — use `CastTrickplayBubble`,
set `bubbleWidth`, drop the manual positioning, plain-text time, sane `panHitSlop`.
- `components/casting/CastingMiniPlayer.tsx` — same bubble fix; add the stop button.
- `app/(auth)/casting-player.tsx` — the `DEBUG_TOUCH_ZONES` overlay.
## 9. Testing
This is UI work with no pure logic to unit-test. Verification is `bun run typecheck`
and manual testing on the Android emulator:
- Trickplay preview at the far-left and far-right of the bar — never truncated,
tracks the cursor.
- Time text reads clearly above the cursor.
- Mini-player stop button stops playback and hides the mini-player.
- With `DEBUG_TOUCH_ZONES` on, the touch zones are visible and `panHitSlop` can be
calibrated so the 4 buttons are reliably tappable.
## 10. Success criteria
- The trickplay window is never clipped at the screen edges and follows the cursor.
- The time indicator is unobtrusive plain text above the cursor.
- The 4 episode-row buttons are reliably tappable (no slider-slop overlap).
- The mini-player has a working stop button.
- The duplicated `renderBubble` code exists in exactly one place.
- `bun run typecheck` passes.
## 11. Risks
- `bubbleWidth` is a single value but the bubble has two sizes (trickplay tile vs
time text); it is set dynamically per render, which the slider supports.
- The debug overlay must be genuinely inert in release builds — the `__DEV__` gate
plus the default-`false` constant ensures it neither renders nor ships active.