ytplayer/CLAUDE.md

ytplayer — project facts for agents

What this is

Ad-free YouTube player. Three shells share frontend/: web PWA (Bun + Hono in server/, the production deployment), Tauri (Windows), zero-native (Linux/macOS). The PWA is what runs in production; legacy/ holds the old native-only docs.

Repo map

Path	What lives there
frontend/app.js	The entire UI (~3.6k lines, no framework): player, playlists, search, settings, sync
frontend/sw.js + frontend/sw-update.js	Service worker + update flow (FRAGILE — see below)
frontend/opfs.js / opfs-worker.js	OPFS offline audio cache
frontend/fingerprint.js	Browser fingerprint used as the sync key
frontend/async-guard.js	Stale-async-response guard (unit-tested)
server/server.js	Bun + Hono backend — endpoint list is in its header comment
server/db.js	libsql schema/queries (users, profiles, video_history, media_cache…)
server/media-cache.js	Server-side video cache: background fetch jobs, validation gate, x264 lane, LRU
bin/yt-dlp	Downloaded by npm run setup, gitignored
scripts/	icon generation, yt-dlp setup, push helper
tests/	Playwright e2e specs · unit tests live next to sources in frontend/*.test.js
legacy/	Old native-shell docs — do not treat as current

API endpoints (notes/admin routes are listed in the header of server/notes.js): GET /api/search|channel|streams|download/:id|version|user/data|profile/load, GET /api/media/:id|media/:id/status|media/stats, POST /api/media/:id/redownload, POST /api/user/sync|profile/create|profile/save, GET /sw.js (BUILD_TAG-injected), GET /* static. JSON shapes mirror the Tauri Rust bridge exactly — don't change one side alone (/api/streams' data.serverCached is additive and web-only).

Long videos (1 h+)

• Bun's default request-body cap is 128 MB — Bun.serve sets maxRequestBodySize to 5 GiB; routes enforce their own limits (uploads 4 GB, intake P2P_INTAKE_MAX_BYTES 3 GiB). Without it every large upload/intake died with 413.
• Admin uploads use PUT /api/admin/uploads/stream?name=… (raw body → disk in chunks, browser sends the File itself); cover images go to PUT /api/admin/uploads/:id/art. The multipart POST /api/admin/uploads parses the whole body in memory — scripts with small files only.
• Videos over transcode.maxSeconds are never re-encoded (lane would be tied up for hours).
• Deferred ideas (Cloudflare Worker fetch, Android device download, ffmpeg.wasm client editing): docs/deferred-ideas.md.

Save to device + "On other devices"

• exportToDevice(video) (app.js, helpers in frontend/export.js): puts the file in Photos / Files / Downloads. Source order: copy saved in OPFS → server copy (GET /api/export/:id?name=, attachment + Range; direct download on desktop, via OPFS + share sheet on phones) → online P2P holder → normal save via server. Buttons appear only once the file is ready: navigator.share needs a fresh tap.
• GET /api/p2p/available + view {type:'p2p'} = the "📡 On other devices" list (sidebar, web only): verified files with ≥1 sharing holder, online first, stale flagged. Rows play, export, or go to a playlist.

Layout themes + Glass Stage

• Settings → Layout theme sets html[data-layout]; rules live in styles.css (older ones) and frontend/theme-glass.css (glass-stage: frosted cards, coral glow). Glass Stage also changes layout: overlay on the video (quality chip, Video / Audio-only, −10 / play / +10, shown when paused or after a tap), deck row prev · −10 · play · +10 · next, volume pod + labelled mode pill, quick-setting chips (#deckChips, refreshed every 1.5 s by the glassStage IIFE), four stacked icon tiles and secondary actions as a pill row, floating mini player. Elements that only this theme shows (.stg-overlay, .skip10, .deck-chips, .vol-pod extras, .mode-name) are in the shared markup and hidden by default.
• Now-playing tiles are [svg.ti][span.tl]; change state text with setTile(btn, label), never textContent.

Saved searches + caching notes

• SearchLibrary (app.js) keeps every search: metadata index in localStorage ytpSearchIndex (sync, ~250 KB), result lists in IndexedDB ytpSearchLibrary (≤1000 queries × 100 results incl. thumbnail URLs; get() is async). A saved copy is trusted 15 days (FRESH_MS): a fresh one is shown with NO network call, an older one is shown then refreshed. The "Update search" button (#searchMeta) calls API.search(q,{refresh:true}) → /api/search?refresh=1 which skips every server cache. The search box's recent list and its "Clear this list" only touch ytpRecentSearches; results are deleted ONLY in Settings → Saved searches. Thumbnails are warmed into the SW ytplayer-thumbs cache (THUMB_CACHE_MAX 25000, trimmed every 100th put — cache.keys() is costly at that size). Browse view: {type:'savedSearches'}. Web Workers were NOT added: IndexedDB/fetch are already async off-thread I/O and postMessage would clone the same data; DOM rendering can't move to a worker.
• Server /api/search (server/search-cache.js, tables search_cache + video_meta): memory (200, 10 min fresh) → libsql (up to 200 YouTube cards per query via innertube.searchDeep continuation paging; ≤250,000 queries AND SEARCH_CACHE_MAX_BYTES 2 GiB, LRU) → YouTube. Stale copies are served for 15 days while refreshing in the background. Every card seen is also stored in video_meta (≤500k); GET /api/search/local?q= matches known videos by title/channel (all words) + uploads in ms, and the app paints them while the real search loads. yt-dlp fallback still returns 25.
• Static files: index.html is stamped with ?v=<BUILD_TAG> on local css/js (indexHtml()); a request whose v equals the running build is immutable, max-age=1y, anything else no-cache. The SW cacheFirst matches ?v= URLs with ignoreSearch against the plain-URL precache. A new build = new URLs, so old ones simply get evicted. /fonts and /icons are cached 30 days.

SHA-256 in WebAssembly (frontend/sha256.js)

• Sha256.create() runs its block function as WebAssembly (frontend/wasm/sha256.c → scripts/build-sha256-wasm.sh → generated frontend/sha256-wasm.js, base64, ~2 KB) and falls back to pure JS if WebAssembly is missing, the CSP refuses it, or the load-time self-test ("abc") fails. ~150 MB/s vs ~65 MB/s in JS (Node/Chromium; phones are slower but the ratio holds). It is synchronous on purpose (callers aren't async) — fine because the module is under 4 KB.
• Needs 'wasm-unsafe-eval' in index.html's CSP script-src. Workers pull the blob in with importScripts('/sha256-wasm.js') from inside sha256.js; the file is in the SW SHELL list. After editing the C file, re-run the build script and commit both. Sha256.engine() says which one is active; create({js:true}) forces JS (tests).

Server media cache (server/media-cache.js)

• Every played (/api/streams, LOW priority, ≤ MEDIA_AUTO_MAX_SECONDS, default 3 h) or saved (/api/download, HIGH, ≤ 3 h) video gets ONE copy: $MEDIA_DIR/<id>.<gen>.mp4 (≤720p H.264 8-bit + AAC, faststart) + <id>.<gen>.m4a audio sidecar for audio-only mode. MEDIA_DIR defaults to ./data/media (the ytplayer-data volume in prod).
• Jobs are server-owned — never pass a request AbortSignal into them; a client closing its tab must not kill a fetch. Downloads still run inside withSaveSlot.
• Validation gate (validateMedia): h264 yuv420p + AAC, container/stream durations cover the source, a full -c copy demux pass with zero stderr, head + tail decode. The demux pass is what catches a faststart file whose index is intact but whose data is cut. Nothing reaches the cache dir without passing it; failures back off (15 min · 2^n, max 24 h) and saves fall back to the legacy per-request path.
• gen is in the filename and URL (/api/media/<id>?g=<gen>): a URL never serves different bytes. A replaced gen is kept 30 min so in-flight Range playback survives.
• Compression lane (rev OPT_REV = 2): niced x265 8-bit -preset medium -crf 28, hvc1 tag, anime-style tuning (X265_TUNING), -fpsmax 30, audio copied — kept only if ≥15% smaller, and the copy's vcodec becomes hevc. Sample-first: videos ≥60 s get two 10-s windows encoded first and compared with the source's own packet bytes over the same timestamps; the full encode only runs if the prediction clears the 15% bar (a skip costs ~20 s of video; a full encode ~2× realtime on the homelab). Why: re-encoding YouTube's already-compressed H.264 usually needs MORE bits for LOWER quality (generation loss) — on prod 0 of 5 videos shrank at CRF 28, one grew 25% (VMAF 93.6 at 126% of source; capping to 60–70% drops VMAF to ~84–87). Only videos where YouTube over-spent bits win (a live worship video: −34%). AnimeOut-style sizes come from pristine Blu-ray sources, which YouTube never gives us. Bumping OPT_REV re-queues every cached copy once at boot.
• HEVC gating: an HEVC copy is served only to clients that send ?hevc=1 on /api/streams and /api/download (app.js hevcCapable() = canPlayType hvc1, minus a per-device ytpNoHevc flag set when an HEVC copy fails to play). Everyone else gets the pre-cache behaviour (YouTube proxy / legacy H.264 save). Verified: iPhone XR, Galaxy S10, Windows Chrome play HEVC; AV1 fails on the XR (no decoder), so it isn't used. The validation gate requires hvc1 (Safari refuses hev1) and 8-bit 4:2:0.
• Budget: MEDIA_CACHE_MAX_BYTES (10 GiB) LRU by last_access (anything played in the last 10 min is protected) + MEDIA_MIN_FREE_BYTES (5 GiB) disk guard → skip, stream.
• Broken: POST /api/media/:id/redownload (now-playing ⚠ Broken button). When a client falls back from a cached copy (/api/streams?nocache=1) the server also re-validates its copy and refetches it if it fails — never trusts one device's error.
• Ops: curl https://worship.hesed.sbs/api/media/stats; files under /app/data/media in the container.

Lyrics · chapters · bookmarks (server/notes.js, frontend/lyrics-core.js)

• Shared per video (every user sees the same copy): video_notes holds the live lyrics / chapters doc per (video_id, kind); every save also lands in video_note_revs as a full snapshot (history + undo). A daily JSON dump of all live notes goes to <DB dir>/backups/notes-YYYY-MM-DD.json (30 kept).
• Who writes: a user linked to an online profile (body profile must exist — same trust level as the profile API), a script with an API token (Authorization: Bearer ytp_…, only a SHA-256 is stored), or the admin (signed httpOnly cookie). Saves are optimistic: client sends baseRev, gets 409 + current if someone saved in between (UI asks "Keep mine / Load theirs").
• Personal, not shared: bookmarks (data.bookmarks[videoId]) and the per-song sync offset (data.lyricOffsets[videoId]) — both ride the profile sync. Line shows at t + doc.offset + personal offset (positive = later).
• Editor text format = LRC superset: [1:23.45] line, # Section, ! band cue, @ Key G, 70 BPM tags, multi-stamp LRC lines and [offset:±ms] accepted.
• Captions: GET /api/notes/:id/captions (preview) and token/admin-only POST /api/notes/:id/lyrics/auto pick human subs first, else the auto track in the spoken language (*-orig), never a machine translation. Auto captions of music are mostly junk ("oh", "n to") — expect to hand-fix or paste lyrics.
• Admin: /admin (frontend/admin.html, never cached by the SW) — tokens, edit feed with view/restore, caption injection, JSON export, API examples. Disabled unless ADMIN_PASSWORD is set (Dokploy Environment tab; compose passes ${ADMIN_PASSWORD:-}). Login is rate-limited per IP.
• Service mode → 🎵 Lyrics (data.settings.serviceLyrics, serviceLyricsAutoscroll): lyrics-only view; the sung line is centred, highlighted and sized to the largest font that fits ONE row. Sizing is measured with a hidden real .sl-line in TWO passes — Bricolage Grotesque has an optical-size axis, so glyphs get relatively wider at small sizes and a single 100px measurement over-fits on phones. Re-fit (in place, never rebuilding rows — that would move the scroll position) on resize, document.fonts load, and +900 ms. Lyrics-only and the 📺 video panel are mutually exclusive.
• Free batch transcription: scripts/lyrics/auto_lyrics.py (faster-whisper large-v3-turbo int8 on CPU, no API key/credits; venv at ~/.local/share/lyrics-asr/.venv). --missing uses GET /api/admin/media (admin or token). Measured on the 16-core laptop: ~0.3–0.65× real time; openai-whisper medium was ~2.5×. vad_filter must stay False — VAD calls sung music non-speech and returns an empty transcript. Karaoke/minus-one tracks have no vocals (reported "instrumental?"); their lyrics were read from the on-screen text (frame sampling + OCR), not audio. ElevenLabs Scribe also works but spends the TTS credit balance (free tier = 10k/month).
• Offline: the last-seen notes per video are cached in localStorage (ytpNotesCache, 200 videos), so saved songs keep their lyrics offline.
• Toast cap bug (fixed with this feature): toast() used while (children.length > 3) with a deferred remove — the 4th toast spun forever and Chrome killed the tab ("Target crashed" in Playwright, no JS error). Never cap with a loop whose exit depends on a deferred removal.

Playlist transitions + waveform (Transition / Wave in app.js)

• data.settings.transition = off | gapless | crossfade (crossfadeSec, default 6); the ↦/⇥/⤨ button cycles it with a 6-s toast. Applies only to playlist/queue playback with a next song, not with loop-one or an A-B loop.
• A hidden bridge <audio> preloads the next song's audio ~25 s early (offline copy, else /api/streams). Crossfade starts it crossfadeSec early and ramps both volumes; gapless starts it when the song ends. Then the queue advances normally with Player._handoff set: _startPlayback() seeks the new track to the bridge's position, plays, and releases the bridge on playing (failsafe 5 s / 20 s). afterLoad skips resume/A-marker seeks during a handoff; onTrackEnded ignores ended while one runs.
• iOS ignores element.volume, so crossfade degrades to gapless there.
• End-of-song race (fixed): the song's last timeupdate arrives with the element already paused (it ended), and ended can beat the fade timer. Both used to look like "user paused" → the crossfade was cancelled and the next song restarted from 0. tick() and onTrackEnded (Transition.onEnded()) now finish the handoff when a fade is running at the end.
• Waveform: GET /api/media/:id/peaks = 400 RMS buckets (0..100, ^0.7 so quiet verses stay visible) from ffmpeg over the server-cached copy, memoised per file path (gen). Audio-only mode draws it on #waveCanvas BEHIND the range input (made transparent, still the control), + hover time tooltip and "⚡ Jump to the loudest part" (loudest ~5 s window). Not cached on the server → plain seek bar. Envelopes are kept in localStorage (ytpPeaks, 80 songs).
• Tested with real audio: a local server whose media_cache holds 20-s clips (upsertMedia rows + <id>.1.m4a/.mp4 files) — Playwright's Chromium plays AAC; launch with --autoplay-policy=no-user-gesture-required.

Uploads + web lyrics

• Uploads (server/uploads.js, UPLOAD_DIR, table uploads): an admin posts a file to /api/admin/uploads (multipart, ≤ 4 GB, admin cookie or API token). ffprobe runs ONCE and gives everything: title/artist/album tags, duration, whether there is a REAL video stream (a cover picture also appears as a video stream — check disposition.attached_pic), the cover itself (extracted to <id>.art.jpg; an uploaded image wins) and embedded lyrics tags (LYRICS / lyrics-eng / UNSYNCEDLYRICS / ©lyr) which are parsed with parseLrc and saved as that song's shared lyrics (synced when in LRC form). Ids are upl_<12 hex> and are accepted anywhere a video id is: /api/streams (audio → audioUrl + art, video → one "Original" quality), /api/download, peaks/gif/clip (audioSourcePath/videoSourcePath), notes. /api/search puts the library first and still answers when yt-dlp fails. The app: 📁 Library view, isUploadId/isMediaId helpers, audio uploads force audio mode so the cover art shows where the video would be.
• Web lyrics: POST /api/notes/:id/lyrics/web asks LRCLIB (free, key-less, often SYNCED) using a cleaned title/artist + duration (cleanTitle/cleanArtist/pickLrclib, ± 6 s). Profile users, tokens and admins may call it; the lyrics worker tries it BEFORE transcribing. scripts/lyrics/web_lyrics.py --missing --agy adds an agy web-search fallback (plain text → untimed lines, to be timed with Tap-sync). Gotcha fixed here: a /g regex reused for .test() skips every other call (lastIndex) — cleanTitle keeps a stateless copy.

Watch party, sharing, playback extras (all in app.js unless noted)

• Lyrics instead of the video (Notes.stageLyrics, #stageLyrics inside .player-stage): a per-device view for watch parties and sing-alongs — data.settings.stageLyrics / stageLyricsAutoscroll. It reuses the service-mode machinery (fitLyricLines, LyricsCore.activeIndex, the same .sl-line classes) and is driven from the normal playback tick. The <video> is only hidden (visibility), never unloaded, so playback, audio and party sync carry on untouched — that is why it is safe for a guest to switch views mid-party. Toggle from the watch-party panel or the bar inside the stage (hover on desktop, always visible on touch).
• Watch party (server/party.js, Party): /ws/party (Bun has ONE websocket handler — sockets are tagged ws.data.hub = 'party' and routed in server.js). Host drives; guests extrapolate the host's state from the server-stamped ts (clock offset from hello.now), seek when > 1.5 s off, mirror play/pause. Guest actions within the 1.5 s "quiet" window after a sync are ignored; later ones → a cmd (if the host allows control) or "off sync" (Re-sync button). playNext/playPrev → Party.intercept, and guests never auto-advance or crossfade. Chat is relayed (≤ 500 chars, 400 ms flood guard, last 60 kept). Voice = WebRTC mesh, the smaller pid offers, STUN only (no TURN — strict NATs won't connect). Host resumes after a reload with the secret from hello (party survives 5 min without its host).
• Timestamp sharing (Share): /?v=<id>&t=<sec> deep links (handled at boot via playVideoAt), YouTube youtu.be/<id>?t=, GIFs from GET /api/media/:id/gif (palettegen, ≤ 6 s, server-cached videos only) and soundbites from GET /api/media/:id/clip?fmt=mp3|m4r (m4r ≤ 40 s, written to a temp file so it's a normal faststart MP4 — iPhones reject fragmented ones).
• External players (External): hands out /api/media/<id> (the single-file server copy) via Android intent: (VLC / MX / chooser), iOS vlc-x-callback, desktop vlc://, or an .m3u (this video or the queue's cached songs).
• Notes: bookmarks with kind:'note' hold multi-line text (≤ 2000) and carry vt/vc (video title/channel); the 📝 Notes view lists them all, exports Markdown. Transcript search = 🔎 tab over the lyrics or the YouTube captions (/api/notes/:id/captions, cached per video).
• PiP mirrors the PiP window's play/pause onto the whole player (dual mode's sound is on <audio>). EQ: 5 BiquadFilters; media elements are wired in only once a non-flat curve is picked (irreversible), disabled on iOS (Web Audio suspends on lock → would kill background audio). Sleep timer: fade over sleepFade s, then pause / "close" (window.close, falls back) / black curtain; "end of this song" also blocks Transition. Gestures: double-tap thirds ±10 s / play, pinch 1–3× (CSS transform), vertical swipes for volume / brightness (CSS filter) only in fullscreen or body.landscape-fs (inline the page keeps touch-action: pan-y so it still scrolls).
• Local media tests: seed media_cache rows + <id>.1.m4a/.mp4 files; the Playwright channel: 'chromium' build plays H.264/AAC; --use-fake-device-for-media-stream gives WebRTC a fake mic.

Presenter view, stats, lyrics worker

• Presenter (Presenter in app.js, /?present=<code>): a lyrics-only projector/TV screen. Pairs through the phone-remote relay like a phone (listen-only); the host's state carries v.id, cur, rate, paused and off (the host's personal lyric offset), and the presenter extrapolates the position between the ~1/s updates. Host modal → "Open presenter window here" opens a popup to drag onto a second display; /api/remote/qr/<code>?kind=present is its QR. Keys: F / double-click fullscreen, B blank screen. Forced dark tokens so it stays readable if the device is in light theme.
• fitLyricLines(list) is the shared one-row font fitter for service-mode lyrics and the presenter — re-run it on font load, resize and +900 ms (first fit on a fresh page happens before Bricolage loads).
• Stats (frontend/stats-core.js, pure + tested; StatsTrack + renderStats): data.stats.days[YYYY-MM-DD] = {s, p, songs:{id:plays}} (local days, 400 kept) synced with the profile. Seconds = media-time deltas while playing (seeks/pauses excluded, divided by playback rate); a play = 30 s heard in one load; commits every 60 s / on play / on page hide to avoid profile-push spam. Streak = consecutive days ≥ 5 min (today may still be pending).
• lyrics-worker (compose service, scripts/lyrics/Dockerfile): runs auto_lyrics.py --missing --watch 300 forever — one song per cycle, nice 10, cpus: 2, mem_limit: 3g, audio fetched from http://ytplayer:3000 over the private lyrics network (never the WAN). Auth = env LYRICS_WORKER_TOKEN (≥ 24 chars) accepted by notes.js as api:lyrics-worker without a DB row; unset → the worker idles. /data/state.json remembers instrumentals (never retried) and failures (backoff 15 min·2^n). Model (~1.6 GB) downloads to the lyrics-models volume on first start.

Phone remote (server/remote.js, Remote in app.js)

• Desktop tab playing to a TV = host; phone = remote. Both are browser tabs of this app, so the server relays over /ws/remote (Bun server.upgrade in the Bun.serve fetch wrapper, before Hono). Mockup: docs/mockups/mock-06-remote-control.html (it assumed a LAN host + mDNS; the web app can't do that, so it's a server relay + a 6-digit code instead).
• Host secret lives in the desktop's localStorage (ytpRemoteHost); room id = hash(secret). Pairing (POST /api/remote/pair) is a one-time 6-digit code (10 min) → phone gets token = HMAC(secret, remoteId) (ytpRemotePair). Nothing about phones is stored server-side: tokens are re-checked against the connected host's secret, so server restarts / desktop reloads keep phones paired, and "Unpair all" (new secret) revokes every phone at once.
• The host pushes state (≤1/s, deduped) and queue ({items, idx} of the live queue/queueIndex); commands are whitelisted server-side (REMOTE_COMMANDS) and run by runCommand() on the host with the same functions the UI uses.
• REMOTE_SAME_NETWORK=1 = pairing requires the phone and desktop to share a public IP (first X-Forwarded-For hop). Off by default — verify that the VPS→homelab Traefik chain forwards the real client IP before turning it on.
• QR: GET /api/remote/qr/:code (server-side SVG via qrcode) encodes <origin>/?pair=<code>; the app consumes and strips ?pair= at boot.

Local dev

npm run setup            # download bin/yt-dlp (once)
cd server && bun install
ln -s ../frontend public # once — the server serves ONLY ./public (Docker copies frontend/ there)
bun --hot server.js      # http://localhost:3000
node --test frontend/    # unit tests (run from repo root)
npx playwright test      # e2e (see Testing below)

Local DB file: server/data/ytplayer.db (gitignored). BUILD_TAG is computed from ./public contents.

Production deployment (web PWA)

• URL: https://worship.hesed.sbs (Traefik label in docker-compose.yml)
• Runs on the homelab Dokploy remote node; control plane is Dokploy on the VPS (193.160.119.172, API key in ~/development/.secrets/dokploy-api.env).
• Compose ID: wprYCM8T51f7JtSHb983p (project ytplayer, env production).
• Pushing to git does NOT deploy. Trigger explicitly (build ≈ 5–6 min):

  ssh -i ~/.ssh/tmp_vps/dokploy_session root@193.160.119.172 \
    "curl -s -X POST -H 'x-api-key: $KEY' -H 'Content-Type: application/json' \
     -d '{\"composeId\":\"wprYCM8T51f7JtSHb983p\"}' http://localhost:3000/api/compose.deploy"
  # poll composeStatus via /api/compose.one?composeId=... until done|error
  

• Confirm the deploy landed: curl https://worship.hesed.sbs/api/version — the buildTag (content hash of every file under ./public) must change.
• Homelab node is NOT always reachable on LAN; SSH via the VPS hop: ssh root@193.160.119.172 → ssh root@10.8.0.2 (WireGuard). Container name: ytplayer-main-1dihzn-ytplayer-1. DB: libsql file /app/data/ytplayer.db (query with docker exec <c> bun -e '...' using @libsql/client).

Update-flow architecture (fragile — read before touching)

• GET /sw.js is served by the server with the real BUILD_TAG injected by regex over the fallback expression in frontend/sw.js. Never switch back to an exact-string replace: when the fallback literal was bumped (v1.0.3→v1.0.4) the exact match silently failed, the SW version froze, and no client ever received another update while /api/version kept announcing one — the "Update available keeps showing" bug.
• BUILD_TAG hashes every file under ./public recursively. Don't reduce it to a file subset; a change to an unlisted shell file would stop busting caches.
• The banner has ONE rule (maybeShowUpdateBanner in app.js): show it only when the build this page runs differs from /api/version. The server stamps the running build into index.html (<meta name="ytp-build">, at request time like sw.js's BUILD_TAG); the SW caches that index.html with the rest of the shell, so the meta always describes the code in the tab. The poll, a waiting worker and the SW_UPDATE_AVAILABLE broadcast are only prompts to re-check. This loop was "fixed" three times by chasing individual triggers — don't add a trigger that calls showUpdateBanner() directly.
• Background download + instant swap (added 2026-09-22). A new worker precaches the whole shell during install, so by the time the user presses "Refresh UI" the build is usually already on disk. applyUpdate asks the waiting worker CACHE_STATUS over a MessageChannel; when it answers ready: true (it re-checks every SHELL url, since a cache can be evicted) the download is skipped entirely and the swap is immediate. Two rules keep this safe: the probe is opt-in (askStatus) — never implicit, because a probe awaiting a reply hangs forever if the caller injects a setTimeout that never fires (the existing tests do exactly that) — and any doubt (no reply, timeout, thrown error, ready: false) falls back to the all-or-nothing download below, which is still what guarantees correctness. maybeShowUpdateBanner also calls prefetchUpdate() → registration.update() so the download starts the moment a new build is seen rather than when the user clicks.
• Refresh UI (frontend/sw-update.js): refreshShellInPlace() re-downloads every file the shell caches hold — cache-busted (?__ytpfresh=) so even an OLD worker's cache-first handler can't answer from its cache, 3 tries per file, all-or-nothing — and writes them into every versioned shell cache; then it activates a waiting worker (SKIP_WAITING) if any and reloads once. A failed download shows an error toast and re-offers later; it never reloads into the old shell. checkUpdateOutcome() verifies after the reload (sessionStorage, max 3 attempts) instead of looping.
• Why it kept looping on prod: the VPS→homelab link is slow and drops requests. The SW install (cache.addAll, all-or-nothing) failed, Refresh UI reloaded into the old cached shell, and the partial ytplayer-<tag> cache left by the failed install later made activate broadcast "update available" to pages that were already current. sw.js now precaches with cache: 'reload', retries each file, and deletes its partial cache on failure.
• Reproduce with the throttling/stalling proxy approach: WebKit (Playwright on the Windows side) or Chrome over CDP against a scratch copy of the server, stalling every Nth shell request after "deploying" v2. A fast local link never shows the bug.

Cache layout & offline thumbnails

• Three cache families, and the split matters on activate: the versioned shell cache ytplayer-<BUILD_TAG> is evicted on every deploy, while the utility caches ytplayer-thumbs and ytplayer-fonts are listed in UTILITY_CACHES and deliberately survive it. Adding a new utility cache means adding it there too, or it gets wiped on the next deploy.
• Thumbnails are cache-first, not stale-while-revalidate — a given thumbnail URL is immutable, so revalidating just burns a round trip per image per launch.
• The opaque-response trap (this silently emptied the thumb cache for months). An <img> to another origin is a no-cors request, so fetch(request) in the SW resolves to an opaque response with status === 0 — not 200. The old guard was if (r.status === 200) cache.put(...), which rejected every single thumbnail, so ytplayer-thumbs was permanently empty and offline showed broken images (measured on prod: 0 entries after browsing pages full of visible thumbs). Fix in thumbnail(): re-issue the request in cors mode — ytimg/ggpht all send Access-Control-Allow-Origin: * — and cache that readable response; an opaque one is accepted only as a last resort. Never reintroduce a bare status === 200 check on a cross-origin subresource.
• Thumbnail hosts live in THUMB_HOSTS. An unlisted host doesn't error — it just bypasses the cache and breaks offline, so add mirrors/avatar hosts there.
• The thumb cache is capped at THUMB_CACHE_MAX (800, oldest-first via the insertion-ordered cache.keys()). Keep a cap: CacheStorage and the OPFS offline audio share one origin quota, and opaque entries are padded to ~7 MB each for quota accounting, so an unbounded thumb cache can evict saved audio.
• App side (app.js): warmThumb() pulls artwork through the SW when a video is saved offline, and warmOfflineThumbs() runs a bounded launch backfill (THUMB_WARM_MAX = 400, 4 at a time) over cached ids + playlist videos so libraries saved before this fix repair themselves. Thumbnails only cache when something requests them — a device needs one online launch to get offline art.
• staleWhileRevalidate() (fonts) must not return cached || networkFetch bare: the fetch resolves to null offline and respondWith(null) throws. It ends with || Response.error().

Section rail + foldable cards (phones)

SectionRail in app.js draws a floating right-hand rail on phones with one icon per visible card (player · now playing · lyrics · related · list). It follows the scroll, a tap jumps to that card, and a tap on the card you are already on folds/unfolds it (data.settings.foldedCards, per device). Folding hides a card's body but never its header, so it stays a landmark you can scroll to and reopen; the Related card's own +/− button routes through SectionRail.setFolded so the two can never disagree.

Two things about this page that break naive implementations:

• The document does not scroll. .player-pane is the scroll container in the browser, but the installed PWA in portrait scrolls .body instead (.player-pane becomes overflow-y: visible there). scrollerOf() walks up to whichever ancestor actually scrolls, and viewBox() measures against it.
• Scroll events do not bubble, so a window scroll listener never fires for an element scroller — the listener is on document with capture: true. Cards also appear outside render() (Related arrives with the video's related list), so onScroll re-runs build(), which is a no-op unless the visible set changed; without that the rail could highlight nothing at all.

First paint vs. the network (launch)

boot() used to await the profile pull and the shared-playlist inbox before the first render(), so on a slow link the sidebar stayed empty for as long as the network took. Everything the device knows is already in localStorage, so it now paints immediately and reconciles afterwards:

• ?list= / ?profile= share links still run before the first paint — they replace the synced slice, so painting first would flash the old playlists and swap them out. They are skipped entirely when the parameter is absent.
• syncOnLaunch() then runs the network pass with a spinner (#syncSpinner, beside the Playlists header, setSyncing() is counted so the last finisher clears it) and re-renders only if playlistFingerprint() changed — a needless render would drop the sidebar's scroll position.

Data model quirks

• Client state persists in localStorage key _ytpdata and syncs (debounced 400 ms) to POST /api/user/sync, keyed by a browser fingerprint.
• A-B loop markers are per-song-per-playlist: stored on the playlist's own copy of the video (entry.ab = {a, b}) when playback source is that playlist; data.abMarkers[videoId] is only the fallback for non-playlist playback.
• Online profiles (profiles table, /api/profile/*): named cross-device sync where the lowercase profile NAME is the only credential (passkey-style, by design). Client stores data.profile = {name, syncedAt}; sync is last-write-wins — push debounced on every persist(), pull on app launch when the server's updated_at is newer than the local syncedAt.
• Profile share links: ?profile=<name> is consumed by adoptProfileFromUrl() at boot, before any rendering. It strips the param via replaceState (so a reload can't re-fire it) and confirms first when the device already has playlists/history or another profile — adopting replaces the synced slice. The name comes off the URL untrusted, hence escapeHtml() on it.
• Empty-home playlist grid: renderHomePlaylists() swaps the branding hero in #playerPlaceholder for the user's playlists (hero is the no-playlists fallback). It is driven from the tail of renderSidebar() — not from render() — so every playlist mutation refreshes both in one place.

Testing

• Unit: node --test frontend/*.test.js (sw, sw-update, async-guard, video-edit, lyrics-core, stats-core, sha256). Server: cd server && bun run test — runs each file in its own process (db.js is a singleton, so two test files in one bun test run share one temp DB; bare bun test also drags in the frontend node tests via the public symlink). media-cache needs a 60 s hook timeout for its ffmpeg fixtures. Local e2e needs a CURRENT yt-dlp — a 2-month-old one 403s on every download. The directory form node --test frontend/ fails on Node 22 with Cannot find module .../frontend — it resolves the dir as a module, not a test glob. That's the harness, not the tests.
• E2E: npx playwright test — WebKit iPhone-12 profile against a static serve of frontend/ (needs npx playwright install webkit). A spurious update banner will make the settings-panel specs fail with #modal intercepts pointer events — that failure mode is a real app bug, not test flake. On the WSL laptop the WebKit install fails host validation (missing libgtk-4, libgstreamer*, …, needs sudo npx playwright install-deps); chromium is already downloaded, so ad-hoc rendering/offline checks can drive it directly instead.
• Service-worker behaviour (thumb caching, offline) is only provable in a real browser: serve frontend/ statically, let the SW take control (needs a second reload), then context.setOffline(true) and assert img.naturalWidth > 0 plus the ytplayer-thumbs entry count. Asserting against the browser's own HTTP cache proves nothing — check the Cache API entry count.
• Test records on prod use Probe */Recon * names; clean via the container DB, children (video_history) first.

Harness

Skills live in .agents/skills/ (symlinked into .claude/skills/):

• deploy-prod — the Dokploy deploy + buildTag verification flow (manual-only; use for any "deploy"/"release" request).
• mobile-app-ui-design — UI/UX design work on the PWA screens.
• lyrics-lookup — fill in songs that have NO lyrics (LRCLIB → agy web search → local faster-whisper).
• lyrics-regenerate — back up, then replace wrong/mistimed lyrics from LRCLIB (scripts/lyrics/lrclib_regen.py).
• lyrics-agy — last resort when LRCLIB has nothing: agy (flat-rate) searches the web and often returns LRC-timed lyrics (scripts/lyrics/agy_lyrics.py). Also the --from-file path for pasting lyrics you already have. agy is NOT deterministic — the script asks up to --tries times and keeps the best (timed > untimed > longer). Its answer arrives on stderr, long answers are truncated behind a keep_id, and a quota-failed instance returns error prose inside a STATUS: ok envelope that will parse as lyrics if you let it.

Matching a song on LRCLIB (learned the hard way)

/api/streams gives the YouTube channel, not the artist, so a title+artist query finds nothing for a lyric-video channel ("Integrity Worship", "Christian Lyrics") — lrclib_lookup falls back to a title-only search and then ranks candidates whose artist verifies 50 points above those that don't. Two guards sit on the result, and both exist because they caught a real wrong song:

• artist_ok() ignores GENERIC words. Channel "Christian Lyrics" once vouched for a track featuring Christian Burns (Nicky Romero, "Still the Same Man"). Never verify an artist on a word that says nothing about who recorded the song.
• title_run() compares whole words, never substrings — "Still" is a substring of "(You Can Still) Rock in America", and a one-word title is rejected outright. It gates the LENGTH rule (same title, within 3 s of the same length ⇒ accept even when the artist can't be checked). An unverified match is printed as UNSURE and skipped; --loose overrides that and is almost always the wrong answer.

Admin lyric editor (frontend/admin.html)

/admin?v=<id> (or the Edit/Lyrics buttons) opens a song with its audio from /api/streams, the waveform from /api/media/:id/peaks, and one row per line: Set stamps the playhead, ±0.2 s nudges, Tap mode stamps the highlighted line on Space and walks down, plus shift-all, line/section/cue kinds, a ✎ Text LRC view and a ⤓ LRCLIB pull. Saves are optimistic (baseRev, 409 → keep mine / load theirs). Rows are built once per load and then only their classes and values change — re-rendering on every tick would steal focus from the field being typed in and reset the scroll position.

Commit rules

One changeset = one commit, single-line imperative message, no AI attribution of any kind (global rule). git push origin main pushes to both remotes.