twitch4steamdeck/CLAUDE_PROGRESS.md

# Twitch4SteamDeck — Fortschritts-Snapshot

> Stand: **2026-04-09 (Session 5)**. Diese Datei dient als Übergabe zwischen Sessions.
> **Lies zuerst:** diese Datei + `todo.md` + `plan.md`.

**Aktueller Stand:** Phase 0–5.6 abgeschlossen & verifiziert. Phase 6 (Flatpak-Packaging): Manifest + Hilfs-Dateien geschrieben, wartet auf User-Verifikation in WSL2 + Steam Deck.

---

## Bereits abgeschlossen

### ✅ Phase 0 — Projekt-Skelett
### ✅ Phase 1 — Twitch OAuth Device Code Flow
### ✅ Phase 2 — Twitch Helix-Client + Sidebar-Layout
Alle drei End-to-End verifiziert 2026-04-07.

---

### ✅ Phase 3 — Streamlink + mpv (Live-Wiedergabe)

Verifiziert 2026-04-08.

#### Architektur-Entscheidungen:
- `--twitch-api-header` wird **nicht** übergeben — Twitch lehnt den Device-Code-Token für
  streamlinks interne GQL-API ab. Öffentliche Streams funktionieren ohne Auth-Header.
- `resolveMpvBin()` löst den mpv-Pfad explizit auf (`C:\Program Files\MPV Player\mpv.exe`),
  da Electron den User-PATH nicht vollständig erbt.
- `--twitch-disable-ads` ist von streamlink deaktiviert worden (deprecated) — kein Ad-Bypass
  im Moment. Post-MVP-Problem.

---

### ✅ Phase 4 — VOD-Browsing + -Wiedergabe

Verifiziert 2026-04-08.

#### Architektur-Entscheidungen:
- **VODs:** streamlink `--stream-url` liefert HLS-URL → mpv wird **direkt** mit der URL
  gespawnt (nicht via `--player`-Flag). Grund: Piped-Streams sind nicht seekable.
  Direktes mpv-Spawnen ermöglicht Seeking + funktionierendes IPC.
- **Live-Streams:** weiterhin via `--player mpv --player-args "--fullscreen"`. Kein IPC
  nötig (kein Seeking, kein Position-Tracking bei Live).
- VOD-Shelf im `ChannelScreen` (untere Hälfte, horizontal, oberer Hero-Bereich fix).
  Navigation: ↓ → Shelf, ←/→ zwischen VODs, ↑ → zurück, Enter → abspielen.

---

### ✅ Phase 5 — Lokaler VOD-Verlauf (Resume)

Verifiziert 2026-04-08.

#### Neue Dateien:
- `src/main/store/db.ts` — SQLite via better-sqlite3, WAL-Modus, Migration
- `src/main/store/historyRepo.ts` — `upsertVod`, `updatePosition`, `markCompleted`,
  `getPosition`, `getProgressMap`

#### Architektur-Entscheidungen:
- mpv IPC funktioniert jetzt zuverlässig (da mpv direkt gespawnt wird).
  `MpvController.observeTimePos()` parst eingehende JSON-Lines, Throttling auf 5s.
- Resume-Position wird beim `startVod()`-Aufruf automatisch aus DB gelesen.
- Auto-Complete bei >95% Fortschritt.
- `„Continue Watching"-Reihe` wurde bewusst weggelassen (vom User nicht gewünscht).
- VOD-Karte zeigt: Fortschrittsbalken (lila), `0:16 von 6:22`, `Vor X Min.`,
  Completed-Overlay mit Kreis-Checkmark.

---

### ✅ Phase 5.5 — Browse-Menü: Kategorien + Top Live-Streams

Verifiziert 2026-04-08.

#### Neue/geänderte Dateien:
- `src/main/twitch/types.ts` — `HelixGame`, `GameInfo`, `game_id`+`language` in `HelixStream`
- `src/main/twitch/helixClient.ts` — `getTopGames(limit, cursor?)`, `getTopStreams(opts?)`
- `src/main/ipc/handlers.ts` — `twitch:get-top-games`, `twitch:get-top-streams`
- `src/preload/index.ts` — `GameInfo`-Typ + neue API-Methoden
- `src/renderer/src/types/t4sd.d.ts` — `GameInfo`, T4sdApi erweitert
- `src/renderer/src/input/gamepad.ts` — Button 2 (X) → `'x'`, Button 3 (Y) → `'y'`
- `src/renderer/src/screens/BrowseScreen.tsx` — Shelf (Top Live) + Kategorien-Grid
- `src/renderer/src/screens/CategoryScreen.tsx` — neu: Streams-Grid pro Kategorie
- `src/renderer/src/screens/AppShell.tsx` — `selectedCategory`-Routing

#### Key-Mapping Browse + Category:
- **Enter / A**: Stream → direkt Live starten · Kategorie → Drilldown
- **X**: Stream-Karte → ChannelScreen öffnen (VOD-Shelf + Live-Button)
- **Y**: Refresh
- **Escape / B**: Category → zurück zu Browse · Browse → Sidebar

#### Wichtige Implementierungsdetails:
- `getTopGames()` macht 40 parallele `/streams?game_id=<id>&first=100` Calls für Zuschauerzahlen
  (Top-100-Streams pro Kategorie summiert → ~85-95% Genauigkeit vs. Twitch-Website).
- Pagination: `getTopGames()` gibt `{ games, cursor }` zurück. BrowseScreen lädt automatisch
  nächste 40 Kategorien wenn letztes Grid-Element fokussiert wird.
- `getTopStreams()` global mit `limit: 100` für den Shelf.
- Zuschauerzahlen auf Kategorien zeigen `n.toLocaleString('de-DE')` Format.

---

### ✅ Phase 5.6 — Einstellungen-Menü + Sprach-Badge/Flagge

Verifiziert 2026-04-08.

#### Neue Dateien:
- `src/renderer/src/context/SettingsContext.tsx` — `SettingsProvider`, `useSettings()` Hook,
  localStorage-Persistenz (`t4sd:settings`), Fallback auf Default bei korrupten Werten
- `src/renderer/src/components/LanguageBadge.tsx` — rendert Badge/Flagge/Beides je nach Mode;
  38 Sprachen gemappt (pragmatische Twitch-Dominanz-Zuordnung)
- `src/renderer/src/screens/SettingsScreen.tsx` — 4 Optionen, gamepad-navigierbar

#### Geänderte Dateien:
- `src/main/twitch/types.ts` — `language` in `HelixStream` + `FollowedChannelInfo`
- `src/main/twitch/helixClient.ts` — `language` in beiden Stream-Mappern
- `src/preload/index.ts` + `t4sd.d.ts` — `language?: string` in `FollowedChannelInfo`
- `src/renderer/src/components/Icons.tsx` — `SettingsIcon` (Zahnrad)
- `src/renderer/src/components/Sidebar.tsx` — 4. Tab `'settings'`
- `src/renderer/src/components/FocusableCard.tsx` — `<LanguageBadge>` unten-rechts im Thumb
- `src/renderer/src/screens/BrowseScreen.tsx` — `<LanguageBadge>` in Shelf-Cards
- `src/renderer/src/screens/AppShell.tsx` — `tab === 'settings'` → SettingsScreen
- `src/renderer/src/main.tsx` — `<SettingsProvider>` um App

#### Architektur-Entscheidungen:
- Settings in `localStorage` (nicht SQLite) — reine UI-Präferenz, kein IPC nötig,
  synchron lesbar (kein Flicker beim Start).
- Default-Mode: `'language'` (Kürzel wie DE/EN) — funktioniert auf Windows Dev-Host sicher.
  Flaggen-Emojis (Unicode Regional Indicators) werden erst auf Steam Deck (Linux/Noto Emoji)
  korrekt gerendert — auf Windows Dev-Host ggf. Rechtecke statt Flaggen.
- `StreamBadgeMode`: `'off' | 'language' | 'flag' | 'both'`
- LanguageBadge Position: `bottom: 10px; right: 10px` im Thumbnail (gegenüber Viewer-Count
  unten-links). Font-Size 15px (FocusableCard) / 14px (Browse-Shelf) > 13px Viewer-Count.
- Unbekannte Sprachen / `'other'` → kein Badge.

---

## Phase 6 — Flatpak-Packaging (in Arbeit, wartet auf WSL2 + Steam Deck)

Ziel: App läuft auf dem Steam Deck als Flatpak.

#### Neue Dateien (Phase 6):
- `flatpak/tv.twitch4steamdeck.App.yml` — Flatpak-Manifest (mpv + streamlink als Module)
- `flatpak/twitch4steamdeck.sh` — Launcher mit `zypak-wrapper` (Electron-Sandbox)
- `flatpak/tv.twitch4steamdeck.App.desktop` — Desktop-Eintrag
- `flatpak/build-flatpak.sh` — Build-Skript für WSL2 (prüft deps, füllt SHA256, baut)
- `resources/icons/icon.svg` — App-Icon (Platzhalter, konvertiert zu PNG beim Build)

#### Architektur-Entscheidungen:
- **Pre-Build in WSL2:** `npm install` + `@electron/rebuild` + `npm run build` laufen
  AUSSERHALB von flatpak-builder in WSL2. Das Manifest kopiert nur die Artefakte.
  → Vermeidet npm-im-Flatpak-Sandbox-Probleme.
- **Electron-Binary aus npm:** Das Electron-Binary kommt aus `node_modules/electron/dist/electron`
  (npm install für Linux), NICHT aus dem BaseApp. BaseApp liefert nur Chrome-Runtime-Libs + zypak.
- **zypak-wrapper:** Ersetzt Chrome-Setuid-Sandbox für Flatpak-Kompatibilität.
- **mpv:** Aus Sources gebaut, libplacebo deaktiviert (entfernt Vulkan-Abhängigkeitskette),
  ffmpeg/libass/libva kommen aus freedesktop SDK 24.08.
- **streamlink:** Via pip install ins Flatpak gebaut. Für sauberen Offline-Build:
  `flatpak-pip-generator` für Python-Dependencies verwenden (TODO beim echten Build).
- **better-sqlite3:** Muss für Linux x64 rebuilt werden (Steam Deck = AMD Zen2 x86_64,
  NICHT ARM64 — die alte ARM64-Notiz war falsch).
- **IPC-Socket:** `os.tmpdir()` → `/tmp` — beide Prozesse (Electron-Main + mpv-Child)
  teilen denselben Flatpak-Sandbox-Namespace. Kein Code-Fix nötig.
- **VAAPI:** `--hwdec=vaapi` bereits implementiert für non-win32 in `streamlink.ts:73`.
- **Flaggen-Emojis erst hier testbar** (Noto Color Emoji aus freedesktop Platform Runtime)

#### Noch ausstehend (User):
1. WSL2-Setup: `sudo apt install flatpak flatpak-builder librsvg2-bin`
2. `bash flatpak/build-flatpak.sh` (in WSL2, aus `/mnt/c/Projekte/twitch4steamdeck`)
3. Verifikation auf Steam Deck: Login, Live, VOD, Resume, Gamepad, Gaming Mode

---

## Technische Baseline

- Electron 33, electron-vite, TypeScript 5.5, React 18
- better-sqlite3 12.x (native, rebuilt für Electron via `@electron/rebuild`)
- streamlink 8.x unter `%LOCALAPPDATA%\Programs\Streamlink\bin\streamlink.exe`
- mpv v0.41.0 unter `C:\Program Files\MPV Player\mpv.exe`
- Dev-Host: **Windows**. Target: **Steam Deck (Linux / Flatpak)**

### Wichtiges Projekt-Memo
- Bei **allen Architekturänderungen** `plan.md` updaten.
- Nach **jeder Subaufgabe** Checkbox in `todo.md` setzen und Update hier.
- Dev-Host: **Windows**. Target: **Steam Deck (Linux / Flatpak)**.
- **Nicht** mit Speculative Abstractions aufblähen.