# v0.2.0 Player Mode — Design & Implementation Plan

**Date:** 2026-09-22 18:58  
**Task:** Brainstorm and plan a "Player" mode for the video clipper app (v0.2.0)

## Changes Made

### Design Spec
- Created `docs/superpowers/specs/2026-09-22-v020-player-mode-design.md`
- 14 sections covering: state/preferences, keyboard shortcuts, layout, mode toggle, floating controls, speed selector, player timeline, toolbar auto-hide, PiP, fullscreen, transitions, file map, version bump

### Implementation Plan
- Created `docs/superpowers/plans/2026-09-22-v020-player-mode.md`
- 9 tasks with TDD steps, exact code, and commands:
  1. Preferences store — `appMode` field
  2. Playback helpers — PiP, fullscreen, playbackRate
  3. SpeedSelector component
  4. PlayerControls floating overlay
  5. PlayerTimeline simplified waveform
  6. App.svelte — mode switching, layout, auto-hide, shortcuts
  7. VideoPlayer.svelte — conditional CC, click-to-play
  8. FLIP transitions for mode switching
  9. Version bump to 0.2.0

## Key Design Decisions

- **Architecture:** Single `App.svelte` with conditional rendering (not separate layout components or windows)
- **Video element preservation:** `<VideoPlayer>` always mounted outside conditionals — only surrounding chrome changes
- **PiP:** Web API (`requestPictureInPicture`) — uses native macOS PiP via WKWebView. Player mode only.
- **Fullscreen:** Standard webview fullscreen (`requestFullscreen` + webkit fallback). Player mode only.
- **Speed control:** Both JKL shuttle keys + visible speed selector popup in floating controls
- **Auto-hide:** Floating controls show on any mouse movement (2.5s timeout), toolbar on top-edge proximity (~50px), timeline on bottom-edge proximity (~80px). All visible when paused.
- **Transitions:** Svelte `fly`/`fade` directives + CSS grid transitions + manual FLIP on video container. ~300ms budget.
- **Mode persistence:** `appMode` saved to Tauri store, restored on relaunch
- **Shortcuts:** `P` → Player, `C` → Clipper, `F` → fullscreen (Player only). Clipper-only shortcuts (I/O/Delete/Cmd+E) become no-ops in Player mode. Frame-step (`,`/`.`) works in both modes.

## Follow-up Items

- Execute the implementation plan (9 tasks)
- Tasks 1, 2, 3 can be parallelized
- Task 6 is the largest (App.svelte layout overhaul) — depends on Tasks 1, 4, 5
- Task 8 (transitions) may need visual tuning after initial implementation

## Lessons Learned

- When conditionally rendering different layouts that share a component (like `<VideoPlayer>`), the component must live outside the `{#if}` branches to avoid Svelte destroying and recreating it on branch switch
- WKWebView supports the standard PiP API — no need for native AVPlayer FFI
- Grid template transitions work in modern browsers but require explicit `transition` properties on the grid container