gui-video-clipper/docs/superpowers/specs/2026-09-22-v020-player-mode-design.md

# v0.2.0 — Player Mode Design Spec

**Date:** 2026-09-22  
**Version target:** 0.2.0  
**Scope:** Add a dedicated "Player" mode alongside the existing "Clipper" mode, transforming the app into a clean, minimal video player when clipping isn't needed.

---

## 1. Overview

The app currently operates exclusively as a video clipper. This spec adds a second mode — **Player** — that strips away clipping UI and presents a focused video playback experience (think QuickTime / VLC). Users toggle between modes with a toolbar button or keyboard shortcut; the switch preserves all session state (playhead position, loaded video, clips, waveform data).

**Architecture approach:** Single `App.svelte` with conditional rendering. The `<video>` element inside `VideoPlayer.svelte` is never destroyed during mode switches — only the surrounding chrome changes. New Player-specific components (`PlayerControls`, `PlayerTimeline`, `SpeedSelector`) stay focused and small.

---

## 2. State & Preferences

### New preference field

Add `appMode: 'clipper' | 'player'` to the `Preferences` interface in `preferences.svelte.ts`. Default: `'clipper'`. Persisted via the Tauri store so it survives relaunches.

### New store helper

- `setAppMode(mode: 'clipper' | 'player')` — updates `preferences.appMode` and saves.

### Mode switching invariant

Toggling between modes **preserves all session state**: playhead position, loaded video, playback state (playing/paused), clips, waveform data, captions, volume, speed — everything. The `<video>` element itself never unmounts, so playback state is inherently preserved (same principle as the existing clip list layout toggle).

---

## 3. Keyboard Shortcuts

### New shortcuts

| Key | Action | Available in |
|-----|--------|-------------|
| `p` | Switch to Player mode | Both modes |
| `c` | Switch to Clipper mode | Both modes |
| `f` | Toggle fullscreen | Player mode only |

### Existing shortcuts by mode

| Key | Action | Clipper | Player |
|-----|--------|---------|--------|
| `Space` / `k` | Play/Pause | ✓ | ✓ |
| `←` / `→` | Seek ±5s (±1s with Shift) | ✓ | ✓ |
| `,` / `.` | Frame step back/forward (works when paused) | ✓ | ✓ |
| `Shift+,` / `Shift+.` | Keyframe jump | ✓ | ✓ |
| `j` / `l` | Shuttle speed down/up | ✓ | ✓ |
| `i` / `o` | Mark in/out point | ✓ | No-op |
| `Delete` / `Backspace` | Delete selected clip | ✓ | No-op |
| `Cmd+E` | Export dialog | ✓ | No-op |

---

## 4. App Layout

### Clipper mode (unchanged)

Renders exactly as v0.1.x: toolbar → video player → transport controls → resizable timeline → clip list (bottom or sidebar).

### Player mode

The layout collapses to a single full-bleed video area with auto-hiding overlays:

```
┌──────────────────────────────────┐
│  Toolbar (auto-hides)            │  ← slides down from top on cursor proximity
├──────────────────────────────────┤
│                                  │
│         VideoPlayer              │  ← fills all available space
│    (floating controls overlay)   │
│                                  │
├──────────────────────────────────┤
│  PlayerTimeline (auto-hides)     │  ← slides up from bottom on cursor proximity
└──────────────────────────────────┘
```

**Hidden in Player mode:**
- `TransportControls` bar (replaced by floating `PlayerControls`)
- `ClipList` (both bottom and sidebar variants)
- Timeline resize handle
- Minimap
- Timeline clip rendering
- I/O mark buttons

**Visible in Player mode:**
- `VideoPlayer.svelte` (unchanged, always mounted)
- `StatusBar` at the bottom (stays visible in both modes)
- `PlayerControls` (floating overlay)
- `PlayerTimeline` (auto-hiding simplified timeline)

**CSS:** Player mode sets a different `grid-template` on `.content` that gives the video area `1fr` and collapses the lower/clip-list rows to `0`. The auto-hiding panels use `position: absolute` within the app shell.

---

## 5. Mode Toggle Button

- **Position:** In the toolbar, between the URL input and the existing layout toggle button.
- **Appearance:** Text label showing current mode — `Clipper` or `Player` — styled as a small pill/badge button.
- **Click:** Toggles between modes.
- **Tooltip:** "Switch to Player (P)" or "Switch to Clipper (C)".

---

## 6. Floating Player Controls (`PlayerControls.svelte`)

An absolutely-positioned overlay rendered over the video area. Designed as a semi-transparent frosted-glass panel.

### Show/hide logic

- **Show** when: mouse moves anywhere over the video area, OR video is paused.
- **Hide** when: mouse is still for 2.5 seconds AND video is playing.
- **Transition:** fade in/out over ~200ms using CSS opacity + pointer-events.
- **Fullscreen:** Same show/hide behavior applies when video is in fullscreen mode.

### Panel layout

```
┌─────────────────────────────────────────────────────────────┐
│  ▁▂▃▅▃▂▁▂▃▅▇▅▃▂▁▂▃▅▃▂▁  ●───────────────────              │  ← seek bar
├─────────────────────────────────────────────────────────────┤
│  ▶❚❚  ◀◀  ▶▶   🔊━━━━     0:32 / 4:15    1.0×  CC  ⧉  ⛶  │  ← controls row
└─────────────────────────────────────────────────────────────┘
```

#### Top row — Seek bar

- Full-width thin progress bar spanning the entire panel width.
- Shows playback progress as a filled track (`var(--accent)`) against a dark unfilled track.
- Hovering shows a time tooltip above the cursor position.
- Click or drag to seek (reuses `seekTo()` from `playback.ts`).
- Track height: 4px, expanding to 6px on hover (CSS transition).
- Thumb: 12px circle, visible only on hover.

#### Bottom row — Controls

Three groups arranged with flexbox `space-between`:

**Left group (playback):**
- Play/Pause — primary action button, `▶` / `❚❚`
- Skip back 10s — `⏪` button, calls `seekBy(-10)`
- Skip forward 10s — `⏩` button, calls `seekBy(10)`

**Center group (time):**
- Time display: `0:32 / 4:15` in monospace font (`var(--font-mono)`), slightly dimmed

**Right group (settings):**
- Speed — shows current rate (e.g. `1×`, `1.5×`). Click opens `SpeedSelector` popup. Sets `videoElement.playbackRate` directly.
- CC — `CC` text button, highlighted when captions active. Click toggles captions. Right-click opens `CaptionSettingsPanel`.
- PiP — `⧉` icon. Click enters/exits Picture-in-Picture. Active state: accent color.
- Fullscreen — `⛶` icon. Click enters/exits fullscreen. Swaps to exit icon when active.

### Visual styling

- **Background:** `rgba(0, 0, 0, 0.75)` with `backdrop-filter: blur(8px)` (frosted glass)
- **Border radius:** `12px` on top corners only (bottom flush with video edge)
- **Padding:** `12px 16px`, `8px` gap between rows
- **Buttons:** Borderless, icon-only, `color: var(--text-primary)`, hover: `color: var(--accent)`. ~32px tap targets.
- **Pointer events:** Panel has `pointer-events: auto`; surrounding overlay has `pointer-events: none` so clicks pass through to the video.

### Video click/double-click behavior

- Single click on video (outside controls) → toggles play/pause
- Double-click on video → toggles fullscreen

---

## 7. Speed Selector (`SpeedSelector.svelte`)

A small vertical popup menu triggered by clicking the speed button in `PlayerControls`.

- Options: 0.5×, 0.75×, 1×, 1.25×, 1.5×, 2×
- Current rate has a checkmark indicator
- Click an option to set rate, popup closes
- Click outside popup to dismiss
- Popup appears above the speed button, anchored to its position
- Sets `videoElement.playbackRate` directly
- JKL shuttle keys continue to work independently (they adjust `playbackRate` too)

---

## 8. Simplified Player Timeline (`PlayerTimeline.svelte`)

A lightweight timeline component for Player mode. Shows only waveform and timestamps — no clips, thumbnails, clip handles, or minimap.

### Auto-hide behavior

- **Show** when cursor is within ~80px of the bottom edge of the video area.
- **Hide** when cursor moves away from bottom edge AND video is playing.
- **Stays visible** when video is paused.
- **Transition:** slides up from below + fades in over ~200ms.
- **Relationship to floating controls:** The floating controls and the player timeline have overlapping but distinct triggers. The floating controls show on *any* mouse movement over the video area; the player timeline shows only on bottom-edge proximity (~80px). When the cursor is near the bottom, both are visible and they appear together as a cohesive unit. When the cursor moves elsewhere over the video, only the floating controls appear (not the timeline).

### Layout

- **Fixed height:** ~50px (not user-resizable)
- **Position:** Bottom of the player area, below the floating controls panel
- **Background:** Semi-transparent dark, matching floating controls (`rgba(0, 0, 0, 0.6)`, `backdrop-filter: blur(4px)`)

### Rendering

- **Waveform:** Reuses `drawWaveform()` from `waveformRenderer.ts`, rendered at full duration (always zoom level 1, no pan).
- **Timestamps:** Reuses timestamp tick rendering from `renderer.ts`, simplified to major ticks only (no clip lanes).
- **Playhead:** Vertical white line showing current position.
- **Click-to-seek:** Clicking anywhere seeks to that position.
- **No zoom/pan:** Always shows the full duration.

---

## 9. Toolbar Auto-Hide (Player Mode)

### Clipper mode

Toolbar always visible (no change).

### Player mode

- **Show** when cursor is within ~50px of the top edge of the window.
- **Hide** when cursor moves away from top edge AND video is playing.
- **Stays visible** when video is paused.
- **Transition:** slides down from above + fades in (~200ms), matching the bottom HUD timing.
- **Content:** Same as Clipper mode (URL input, mode toggle, about, preferences).

---

## 10. Picture-in-Picture

- **API:** `HTMLVideoElement.requestPictureInPicture()` — uses the native macOS PiP window via WKWebView.
- **Scope:** Player mode only. No PiP button in Clipper mode.
- **Button:** `⧉` icon in `PlayerControls`. Active state shown with accent color.
- **Events:** Listens for `enterpictureinpicture` and `leavepictureinpicture` on the video element to track state.
- **Exiting PiP:** Returns focus to the app window.

### New playback helpers

Add to `playback.ts`:
- `requestPiP()` — calls `videoElement.requestPictureInPicture()`
- `exitPiP()` — calls `document.exitPictureInPicture()`
- `isPiPActive(): boolean` — checks `document.pictureInPictureElement`

---

## 11. Fullscreen

- **API:** `videoElement.requestFullscreen()` with fallback to `videoElement.webkitEnterFullscreen()` for WKWebView compatibility. WKWebView's webkit-prefixed API fullscreens the video natively (similar to Safari's behavior).
- **Scope:** Player mode only. Keyboard shortcut `f`.
- **Button:** `⛶` icon in `PlayerControls`. Swaps to exit-fullscreen icon when active.
- **Events:** Listens for `fullscreenchange` to track state.
- **Controls in fullscreen:** The floating `PlayerControls` overlay remains functional in fullscreen mode with the same auto-hide behavior.

### New playback helpers

Add to `playback.ts`:
- `toggleFullscreen()` — enters or exits fullscreen on the video element
- `isFullscreenActive(): boolean` — checks `document.fullscreenElement`

---

## 12. Transitions (FLIP Animations)

### Clipper ↔ Player mode switch

1. **Video player area** — FLIP animation: the video container smoothly expands to fill the full area (Clipper→Player) or shrinks back to its grid cell (Player→Clipper). Manual FLIP: snapshot bounding rect before mode change, apply mode, snapshot new rect, animate from old→new using CSS `transform`.

2. **Transport controls / Clip list** — fade + slide out downward when switching to Player, fade + slide back in when returning to Clipper. Duration ~250ms, eased.

3. **Floating controls** — fade in after video expansion completes (staggered ~100ms delay).

4. **Toolbar** — slides up and fades out (Clipper→Player), slides back down (Player→Clipper).

### Implementation approach

- CSS custom properties + `transition` for grid layout changes (grid rows/columns animate in modern browsers).
- Svelte `transition:` directives (`fly`, `fade`, `slide`) for elements entering/leaving the DOM.
- Manual FLIP on the video container for the expansion/contraction.
- Total transition budget: ~300ms.

### Edge cases

- Mid-transition mode switch: new transition takes over from current interpolated position (CSS transitions handle this naturally).
- No video loaded: transition still runs (placeholder area expands/contracts).

---

## 13. New & Modified Files

### New files

| File | Purpose |
|------|---------|
| `src/lib/components/PlayerControls.svelte` | Floating controls overlay (seek bar, play/pause, volume, speed, CC, PiP, fullscreen, time display) |
| `src/lib/components/PlayerTimeline.svelte` | Simplified auto-hiding timeline (waveform + timestamps only) |
| `src/lib/components/SpeedSelector.svelte` | Speed popup menu used by PlayerControls |

### Modified files

| File | Changes |
|------|---------|
| `src/lib/stores/preferences.svelte.ts` | Add `appMode` field, `setAppMode()`, persist/load |
| `src/App.svelte` | Mode toggle button, conditional layout, auto-hide toolbar, `p`/`c`/`f` shortcuts, FLIP transitions |
| `src/lib/components/VideoPlayer.svelte` | PiP/fullscreen event listeners, expose PiP/fullscreen state, conditional CC toggle rendering (Clipper only; Player delegates to PlayerControls) |
| `src/lib/transport/playback.ts` | Add `requestPiP()`, `exitPiP()`, `isPiPActive()`, `toggleFullscreen()`, `isFullscreenActive()`, `setPlaybackRate()` |
| `src/app.css` | CSS variables/classes for player mode transitions, auto-hide panels |

### Unchanged files

- `Timeline.svelte` — used only in Clipper mode
- `ClipList.svelte` — hidden in Player mode
- `TransportControls.svelte` — hidden in Player mode
- All Rust backend code — no backend changes
- `StatusBar.svelte` — visible in both modes

### Testing

- Existing tests unaffected (timeline interactions, clips store, time utilities).
- New tests: PlayerControls show/hide logic, speed selector state, mode switching preserves session state.

---

## 14. Version Bump

Bump version from `0.1.3` to `0.2.0` in:
- `package.json`
- `src-tauri/tauri.conf.json`
- `src-tauri/Cargo.toml`
- `VERSION` file

Use the existing `scripts/bump-version.sh` if it handles all locations, otherwise update manually.