# Architectural Decisions - pureplayer

Append-only log of architectural and design decisions made during development.

## Format

Each entry follows this structure:

| Date | Decision | Rationale |
|------|----------|-----------|
| {YYYY-MM-DD} | {What was decided} | {Why this choice was made} |

## Decisions

| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-06-19 | Bootstrap stack = Tauri 2 + React 19/TS + Vite + TanStack Router/Query/Hotkeys + shadcn/Tailwind v4 + Vitest. Mirrors sibling repo `requi` but **drops TanStack Table & Form**. | A video player is keyboard-driven (Hotkeys), needs routing (Router) and async/IPC state (Query), but has no data-grid or multi-field-form surface. Carrying Table/Form would be unused deps (YAGNI). Add them only when a feature needs them. |
| 2026-06-19 | Code-based TanStack routes (not file-based). | Fewer build plugins; matches `requi`. |
| 2026-06-19 | Pure scaffold - no real `<video>` playback in bootstrap. | Keeps bootstrap = tooling foundation only; first playback feature lands separately so scaffold and feature concerns stay unmixed. |
| 2026-06-20 | Real playback feature: playlist is built from native-picker file paths and **replaces** prior list (no append, no persistence); app boots with an empty playlist (mock data dropped from the default). | Simplest real-player model; matches "open these files, watch them" intent. Append/persistence are separable later features (YAGNI). |
| 2026-06-20 | Playback follows selection: opening files, clicking a row, and prev/next all **auto-play**. `isPlaying` stays a distinct field but those verbs set it true. | User chose auto-play; keeps selection vs play-state separable in the model while giving instant playback UX. |
| 2026-06-20 | Live playback figures (current/duration) live in `WorkspaceProvider` state, pushed up from the `<video>` element's `timeupdate`/`loadedmetadata` events - not stored on `VideoNode`. | Element is the source of truth for time; storing on the node would duplicate/desync. Context already owns UI state (no prop drilling). |
| 2026-06-20 | All Tauri IPC for this feature funnels through `src/lib/tauri.ts` (`openVideoFiles`, `toAssetUrl`, `toggleFullscreen`). | Single mockable boundary; tests stub this module instead of the system under test, keeping jsdom (no real media/IPC) viable. |
| 2026-06-20 | Fullscreen = **native window** fullscreen via Tauri `setFullscreen`, triggered by viewport double-click only (no hotkey/palette command). | User chose native window over the browser Fullscreen API; double-click is the requested gesture. |
| 2026-06-20 | `VideoNode` drops `resolution`/`durationSec`; `SortField` drops the matching `duration`/`resolution` keys (kept only `title`/`type`). | Picker-sourced files have no upfront metadata; duration is live from the `<video>` element. The dropped sort keys were UI-unreachable (the selector only ever exposed Title/Type) - removing them deletes dead code rather than feature. |
| 2026-06-20 | Universal playback needs a real engine, but the **mpv-embed approach was tried and abandoned**. mpv renders into a GPU surface under a *transparent* webview; on macOS that transparency broke the whole window (chrome bled through) and the embed plugin (`tauri-plugin-libmpv`) is Windows-tested / macOS-untested. Reverted to the working `<video>` player. | The render-API-under-transparent-webview compositing is the fragile part on macOS (Stremio had to hand-write their own macOS render integration). Too high-risk/multi-day for the value; chose the simpler standalone path instead (next row). |
| 2026-06-20 | Universal playback via a **bundled ffmpeg sidecar**: the webview `<video>` stays the renderer; ffmpeg (one statically-linked binary shipped inside the app, like VLC bundles libvlc) remuxes/transcodes any input to a webview-playable stream. | Standalone (zero external installs) was a hard requirement. A single bundled binary is far simpler + lower-risk than embedding a media engine + 22 dylibs under a transparent window. Trade-off: VP9/AV1/HEVC need a transcode step (latency); remuxable containers (MKV/AVI/H.264) are near-instant. See [spec-ffmpeg.md](features/20260620004905-real-playback/spec-ffmpeg.md). |
| 2026-06-20 | ffmpeg/ffprobe **bundled as Tauri sidecars** (`externalBin` + `tauri-plugin-shell` `app.shell().sidecar()`), not resolved via manual `current_exe()` path-joining. Binaries fetched by `scripts/fetch-ffmpeg.sh` (SHA-256 pinned, gitignored, not committed). | Realises the standalone goal (zero PATH install). The shell plugin already handles dev-vs-bundle dir + `-<triple>` suffix + `.exe`; reimplementing that resolution is error-prone. Fetch-not-commit keeps ~1GB of binaries out of git. |
| 2026-06-20 | Bundled binary licensing: **macOS = GPLv3** (ffmpeg.martin-riedl.de 8.1.1), **Windows = LGPLv3** (BtbN 8.1.2). | No off-the-shelf LGPL *static* macOS ffmpeg exists - every prebuilt static macOS build configures `--enable-gpl` with x264/x265. Self-compiling an LGPL macOS build is multi-hour/brittle and out of scope. Consequence (user-accepted): the distributed app inherits GPL terms on macOS; fine for a personal/source-available player, revisit before any closed distribution. |
| 2026-06-20 | The streaming-transcode loop drains the sidecar stdout/stderr receiver in a detached task and reads termination from `CommandEvent::Terminated` (not `child.try_wait()`). | `tauri-plugin-shell` `.spawn()` force-pipes into a `channel(1)`; an undrained pipe stalls the background encode once the OS buffer fills. The bare `std::process::Command` it replaced inherited stderr and had no such constraint - the sidecar introduces it. |
| 2026-06-20 | Asset protocol enabled with a **broad local scope** so arbitrary user-picked files can be served to the `<video>` element. | A general file picker can return any path; a narrow scope would block legitimate selections. Trade-off: broad read exposure via the asset protocol, acceptable for a local single-user desktop player. Revisit if multi-window/remote content is ever added. |
| 2026-06-20 | **Reverses the fragmented-streaming `<1s` start** (rows above): `prepare_media` now produces a COMPLETE, finalized MP4 (`+faststart`) and awaits ffmpeg before returning, instead of serving a growing fragmented file. | The asset protocol serves the on-disk byte length once, so a still-growing fragmented MP4 made `<video>` report a long clip as `00:01`. Correct duration + whole-clip playback outweigh start latency. Remuxables stay fast (stream-copy); only true re-encodes are slow (spinner). |
| 2026-06-20 | Playback decision is a **container-aware per-stream ADT** `plan_media(container, vcodec, acodec) -> Passthrough \| Convert{VideoAction, AudioAction}`, replacing codec-only `is_directly_playable`. | MKV/h264/aac was wrongly "direct" and served raw, but WKWebView can't play MKV/AVI. Per-stream actions remux when only the container is wrong and re-encode only the stream that needs it (h264+opus = audio only; vp9+aac = video only) - faster, and the branching is one pure unit-tested fn, not ifology in the spawn path. |
| 2026-06-20 | Queue modes = **repeat enum (`off`/`all`/`one`) + an orthogonal shuffle toggle**, not a single cycling mode; repeat=off **stops at the last video** (no wrap); shuffle drives **both** auto-advance and manual next/prev. | The universal media-player model (VLC/Spotify): repeat and shuffle compose independently. Stop-at-end is the "play my queue once" default - repeat-all is what loops. One "what plays next" concept everywhere avoids next/prev disagreeing with auto-advance. The on-ended decision is a pure ADT `decideOnEnded(order, activeId, mode) -> advance\|replay\|stop` and shuffle is a pure `shuffleIds`/`reconcileOrder` pair (RNG-injected), so verbs carry no ifology and shuffle is deterministically testable. |
| 2026-06-20 | The frozen shuffle order is **reconciled** against the live id set (`reconcileOrder`) on each step, not reshuffled. | Appending videos (drop/open) or changing the sort while shuffling must not reshuffle or lose the cursor: new ids slot in at the end, removed ids drop out, existing order is preserved. Reshuffling on every list change would be jarring and non-deterministic. |
| 2026-06-20 | FR-7 settings subsystem **mirrors the sibling `requi` repo** (`Settings` ADT + defensive `mergeSettings`, `tauri-plugin-store` `LazyStore` persistence behind a `SettingsStore` seam with an in-memory test impl, `SettingsProvider`, pure `resolveShortcuts`/`findConflict`/`safeNormalize`, capture-keystroke `ShortcutRow`) rather than inventing a new design. | `requi` already ships a battle-tested, identical-stack (`@tanstack/react-hotkeys` same version) version of this exact feature. Reuse cuts risk and keeps the two repos' settings/shortcuts conventions aligned. Persistence = `tauri-plugin-store` (user choice) over localStorage, matching `requi`. |
| 2026-06-20 | `WorkspaceProvider` stays **DI-pure** (no settings/IPC dependency): persisted prefs enter as optional `initial*` props and persistence is wired by a thin **route-level bridge** that reads `useSettings()` and calls the savers. | Keeps the ~13 existing `WorkspaceProvider` tests untouched (only the 4 tests rendering `<Workspace/>` need a `SettingsProvider` wrapper). The provider already had `initialSortKeys`/`initialSortDirection` seam props - this extends the same pattern instead of coupling the workspace to the store. |
| 2026-06-20 | Persist playback (volume/mute/rate) + UI (sidebar/transport/sort) prefs + hotkeys; do NOT persist `repeatMode`/`isShuffling` or playlist/session. | YAGNI scope cut: queue modes and playlist/session restore are separable (playlist = FR-5, skipped). Fullscreen's transient chrome-hiding overrides at runtime and is explicitly NOT persisted (only the user's windowed sidebar/transport choice is). |
| 2026-06-21 | Also persist the resizable **panel layout** (`settings.layout`, a `{panelId->size}` map) - `WorkspaceLayout` reads `settings.layout` as the group's `defaultLayout` and wires `onLayoutChanged -> saveLayout`, mirroring `requi`. | Added after user feedback: `requi` persists split sizes and the original FR-7 spec wrongly cut it as YAGNI. pureplayer has a single sidebar/content split (one `layout` map, not requi's 3-group `layouts`). The whole `Settings` object already serializes through `tauri-plugin-store`, so no store change was needed - just the merge guard + the layout field + the `WorkspaceLayout` wiring. |
| 2026-06-21 | Reveal-transport-on-hover = a hover-tracked **bottom-edge overlay** in `Content` (absolute, over the video), NOT a docked row that pushes layout; flag `revealTransportOnHover` persisted, default ON. `Content` reads `useSettings()` directly (like `WorkspaceLayout` reads `layout`), no `WorkspaceProvider` coupling. | User chose overlay (player-standard, no layout shift / video resize on every hover) over docked. Default ON per user. Overlay keeps the `<video>` size stable - a docked reveal would shrink/grow it on each mouse enter/leave. pureplayer-specific (no `requi` precedent). Hover state is local UI state in `Content`, not workspace state - so it doesn't touch the provider or its tests. |
| 2026-06-21 | The reveal overlay is driven by **mouse MOVE + an idle timer** (`IDLE_HIDE_MS`, tuned to 3000ms; move shows + resets timer, idle hides, leave hides immediately), not a plain enter/leave hover. `toggle-fullscreen` (`Mod+Shift+F`) and `toggle-reveal-transport` (`Mod+Shift+H`) became first-class registry actions (palette + hotkey); the registry gained an optional `keywords` field threaded into cmdk so non-obvious names are searchable. | User asked for video-player-style auto-hide (idle-based), and that the palette expose every action. Fullscreen was previously double-click-only (ADR row above); promoting it to the registry makes it palette/hotkey-runnable + rebindable for free. `keywords` fixes "I searched 'bottom bar' and the transport toggle didn't show" - cmdk filters name+value only, so the alias must be explicit. |
| 2026-06-21 | The video title overlay is a 5s intro card, not a permanent watermark - it shows for 5s after the active video changes then hides; switching re-shows it. Implemented with a `titleHiddenForId` state (set by a per-id 5s timer), title visible while `titleHiddenForId !== activeVideo.id`. | User wanted the name as a brief intro, not a persistent overlay over the picture. Used a "hidden-for-id" state rather than a synchronous `setVisible(true)` in the switch effect because the eslint `react-hooks` rule flags synchronous setState-in-effect (cascading renders); keying visibility off the id avoids the reset-write entirely - a new id is shown by default, the timer only ever writes the hide. |
| 2026-06-21 | The idle auto-hide is FROZEN while the cursor is over the bar: the overlay's `onMouseEnter` clears the timer + sets an `isOverBar` ref, `onMouseLeave` restarts it; `handleMouseMove` early-returns when `isOverBar` so a move bubbling up from the bar to the wrapper doesn't re-arm the hide. | User: "don't hide the bar if my mouse is on it." Mouse events from the bar bubble to the video wrapper's `onMouseMove`, so an enter/leave flag alone isn't enough - the move handler must also ignore moves originating on the bar, hence the `isOverBar` ref guard (a ref, not state, so it doesn't re-render or stale-close over the handler). |
| 2026-06-21 | **REVERSES the "complete MP4 + faststart" decision (FR-13 era) for non-passthrough files**: `prepare_media` now STREAMS via HLS - ffmpeg writes an `index.m3u8` + progressive TS segments into a temp dir, served over a loopback `tiny_http` server, and `<video>` plays `http://localhost:PORT/.../index.m3u8` starting on the first segment (~0.2s). The persistent transcode cache is removed entirely. Passthrough (mp4/h264/aac) stays on `asset://`. | User goal: "instant like VLC". Pre-transcoding the whole file blocked playback for ~11s on a 32-min MKV; VLC is instant because it decodes on the fly. HLS = play-while-encode. HARD constraint: WKWebView routes HLS through AVFoundation, which IGNORES Tauri custom schemes (`asset://`), so HLS needs a real `http://localhost` - hence the loopback server (`tiny_http`, bound `127.0.0.1:0`, serves only the HLS temp root with a path-traversal guard). EVENT playlist declares segment durations, fixing the old fragmented-MP4 duration bug without awaiting the full encode. Cache dropped per user request, which also kills the FR-13 stale-cache/`.part`-muxer bug class. |
| 2026-06-21 | Cross-platform release = a **manual (`workflow_dispatch`) GitHub Actions matrix** using `tauri-apps/tauri-action@v0`, publishing to a **draft GitHub Release** (3 files: universal macOS `.dmg`, Windows installer, Linux `.AppImage`). Unsigned for now. | Official action handles per-OS bundling + multi-job upload to one release; hand-rolling `cargo tauri build` + `gh release upload` reinvents the fragile part. GitHub Release chosen over workflow artifacts for delivery: public no-login direct links, deletable later by removing the release/tag (kills future downloads). Signing/notarization deferred (YAGNI, needs paid certs). |
| 2026-06-21 | macOS release ships a **single universal binary** (`--target universal-apple-darwin`), and CI **`lipo`-combines** the two per-arch ffmpeg/ffprobe sidecars into a `*-universal-apple-darwin` pair before building. | User chose 1 universal `.dmg` over 2 per-arch files (exactly 3 outputs total). Tauri does NOT auto-fatten `externalBin` sidecars for the universal target - it resolves `binaries/ffmpeg-universal-apple-darwin`, so the fat binary must be built explicitly. |
| 2026-06-21 | Linux ffmpeg/ffprobe sidecar added to `fetch-ffmpeg.sh` from **BtbN `linux64-lgpl` (LGPLv3 static)** - the same release already used for Windows. | The Linux `cargo` build fails without the host-triple sidecar (`externalBin`). Reusing the already-pinned BtbN autobuild keeps one source/version for both non-mac platforms; LGPL (not GPL) because, unlike macOS, a prebuilt LGPL static Linux build exists. |
| 2026-06-22 | **REVERSES the HLS-streaming decision (row above) as the primary non-passthrough path**: `prepare_media` is now a 3-way `MediaStrategy` derived from the plan. **Whenever the video can be stream-copied (h264) it produces a COMPLETE MP4 on disk** (asset protocol) so `<video>` gets a finite duration + native random-access seeking. `CompleteRemux` (h264 + ok/no audio) = one fast remux (~0.3s, both tracks copied). `VideoThenAudio` (h264 + bad audio, e.g. Opus) = emit a silent video-only MP4 instantly, then re-encode audio in the background and swap `src` via a `media://audio-ready` event (FE preserves currentTime + play state). HLS (`HlsStream`) survives ONLY for true video re-encodes (VP9/AV1). | Root cause of the "seek jumps back" bug: an HLS EVENT playlist is progressive - `<video>.seekable.end` is `Infinity`/clamped mid-encode, so a click past the encoded point snapped back. A whole file on disk has full random access, so seeking is natively instant (proven by a throwaway WKWebView POC). The source's video was already h264 (WKWebView-native) - HLS only ever existed to dodge **codecs**, and the only real blocker was Opus **audio**. So copy the video (instant, perfect seek) and deal with audio separately instead of streaming the whole thing. The mpv-embed alternative (real player, instant everything) was re-validated and re-rejected: same transparent-webview compositing break as the 2026-06-20 row (POC showed desynced OSC + desktop bleed-through). |
| 2026-06-22 | The two-phase background audio re-encode uses **ALAC (Apple Lossless) on macOS**, not AAC. | AAC is lossy and its encoder prepends a ~20ms priming frame; muxed against the copied video that's a fixed A/V desync, and parallel-chunking to cut the ~14s encode only multiplied the priming across seams (cumulative drift, measured +178ms at 10 chunks). Trying to compensate the priming requires a full decode+re-encode, erasing the parallel speedup. ALAC is lossless → **zero priming → 0ms A/V offset**, and being a simpler codec it encodes ~3x faster (32-min file: 14s→5s) single-shot, no fragile chunk/concat machinery. Cost: larger temp file (lossless, ~320MB vs ~70MB) - acceptable for a transient swap file. AVFoundation decodes ALAC natively; Chromium (WebView2) / WebKitGTK don't reliably, so off macOS the fast AAC software coder stays. |
| 2026-07-19 | **REVERSES the "BtbN dated autobuild tag" source (2026-06-21 row) for Windows + Linux ffmpeg/ffprobe.** The two raw LGPLv3 binaries per platform (BtbN build `N-125658-g0869e710e6`) are now **self-mirrored to a dedicated, published (non-draft) pureplayer GitHub Release** (`ffmpeg-sidecars-n8.1-btbn`), and `fetch-ffmpeg.sh` downloads the raw binary directly from that stable URL (no zip/tar unpack, no inner-dir `find`). SHA-256 pinning is retained. macOS keeps the martin-riedl mirror. | BtbN **prunes its dated `autobuild-YYYY-MM-DD-HH-MM` tags after ~weeks**, so the pinned URL 404s and the release CI's Windows+Linux jobs fail (macOS was unaffected - it uses the stable martin-riedl mirror). BtbN's only non-pruned tag is `latest`, which changes nightly and is incompatible with SHA-pinning. Self-mirroring gives the same durability macOS already relies on while keeping the integrity check. The mirror release must **not** be deleted (referenced by the fetch script); it is separate from the versioned app releases. |
| 2026-07-21 | Theme custom colors are **edited as raw JSON in a CodeMirror editor** (not a hex picker or per-token inputs), **applied as inline CSS vars on `<html>`**, and **split into a separate `theme.json`** (mode stays in `settings.json`). Mirrors sibling `purerequest`, but PP drops purerequest's editor-syntax theming (no content editors) and uses an explicit Save button instead of Mod+S/an active-editor registry. | User chose CodeMirror ("jak w innych apkach") + the file split ("jak w purerequest"). Inline vars beat the `:root`/`.dark` rules so only the active mode's sparse overrides need writing and Tailwind's `@theme inline` re-derives `--color-*` for free; raw `oklch(...)` strings round-trip verbatim (no color-space conversion, no alpha loss on the two dark alpha tokens). `theme.json` split makes a color scheme device-syncable independently of device-local UI state, matching the existing keymap-split convention. Hard-to-reverse (adds the CodeMirror dep surface + a second store file + makes the dead `.dark` block live), so logged here. |