Record offline completeness and recovery verification

# Conflicts:
#	frontend/index.html

.gitignore

@@ -28,6 +28,7 @@ node_modules/
 # runtime/local artifacts
 server/data/
 test-results/
+.impeccable/review/
 .claude/worktrees/
 server/public
 
@@ -37,3 +38,9 @@ legacy/releases/
 
 # python caches from scripts/lyrics
 __pycache__/
+plans/codex-shots*/
+plans/codex-report*.md
+
+# performance harness artifacts and temp files
+perf/fixtures/
+perf/.tmp/

.impeccable/config.json

@@ -0,0 +1,27 @@
+{
+  "buildPath": "code",
+  "detector": {
+    "ignoreRules": [],
+    "ignoreFiles": [],
+    "ignoreValues": [
+      {
+        "rule": "broken-image",
+        "value": "*",
+        "files": [
+          "frontend/index.html"
+        ],
+        "createdAt": "2026-10-02T23:14:10.804Z",
+        "reason": "Agent verified all three matching images are hidden dynamic artwork targets (artImg, serviceArt, rvThumb); app.js assigns their src when media metadata is available."
+      },
+      {
+        "rule": "layout-transition",
+        "value": "*",
+        "files": [
+          "frontend/theme-f7.css"
+        ],
+        "createdAt": "2026-10-05T18:33:43.625Z",
+        "reason": "Framework7 swipeout reveal retains its existing width transition for the action area"
+      }
+    ]
+  }
+}

.impeccable/critique/2026-10-05T20-14-49Z__frontend-index-html.md

@@ -0,0 +1,69 @@
+---
+target_identity: "file:/home/josh/development/personal/ytplayer/frontend/index.html"
+target_fingerprint: "sha256:5f16cc1d66caa47d5d1ae35afe92b5206825e66772d974d72fd90effac161d27"
+target_path: /home/josh/development/personal/ytplayer/frontend/index.html
+timestamp: 2026-10-05T20-14-49Z
+slug: frontend-index-html
+---
+Method: dual-agent (A: /root/critique_design · B: /root/critique_evidence)
+
+# Design Health Score
+
+| # | Heuristic | Score | Key issue |
+|---|---|---:|---|
+| 1 | Visibility of System Status | 3/4 | Active tab and playback state are clear; row actions depend on an undisclosed swipe. |
+| 2 | Match System / Real World | 3/4 | Grouped lists, bottom tabs and sheet use familiar iOS patterns. |
+| 3 | User Control and Freedom | 3/4 | Player and sheets can be collapsed or closed; long swipe removal remains a high consequence gesture. |
+| 4 | Consistency and Standards | 3/4 | F7 components now share the same token-based visual treatment; some underlying CSS layers overlap. |
+| 5 | Error Prevention | 2/4 | Long-left removes a row without a confirmation step. |
+| 6 | Recognition Rather Than Recall | 2/4 | Swipe row actions are not apparent before discovery. |
+| 7 | Flexibility and Efficiency | 3/4 | Gestures and bottom tabs offer quick navigation for touch users. |
+| 8 | Aesthetic and Minimalist Design | 3/4 | Light, dark and contrast treatments stay restrained; row actions can obscure content while open. |
+| 9 | Error Recovery | 2/4 | No explicit undo is provided for a swipe removal. |
+| 10 | Help and Documentation | 1/4 | Only the mini-player has a visual gesture affordance; row and tab gestures lack a persistent hint. |
+| **Total** | | **25/40** | **Acceptable; interaction discovery is the main gap.** |
+
+# Design Specificity Verdict
+
+**LLM assessment:** The F7 layout now reads as a media player: native line icons, an inset media list, accent-led controls, glass navigation and a sheet for Up Next. The large title hierarchy and player/list relationship fit the product. It is no longer just the mini-player that changes. The remaining weakest point is that row actions and tab movement rely on gesture knowledge users may not have.
+
+**Deterministic scan:** The scoped Impeccable detector scan across `frontend/index.html`, `frontend/app.js`, `frontend/f7-layout.js`, `frontend/fullscreen-orientation.css`, `frontend/fullscreen-orientation.js` and `frontend/theme-f7.css` reported 129 findings: 60 warnings and 69 advisories. Categories: low contrast 22, design-system-radius 35, undersized-ui-text 22, design-system-font-size 20, thin-border/wide-shadow 10, dark-glow 4, design-system-color 4, clipped overflow 3, gradient text 2, layout transition 2, tiny text 2, marquee 2, pulsing dot 1. It found no issues in the two gesture/fullscreen logic modules. Most radius/type findings refer to the intended F7 control scale or circular/icon controls; many remaining findings point to shared prototype content and pre-existing theme variants in the large single HTML document. The contrast findings around bright accent fills and dim secondary text merit future contextual review, especially against the detector's assumed body-text size.
+
+**Browser visualization:** The detector overlay could not be injected into the selected live page. The available browser inspection loaded the default Classic layout and returned `Unexpected token '<'` from API/script requests served as HTML, so no reliable user-visible overlay is available. Separate Playwright captures were made on the static frontend with the F7 layout enabled and inspected directly.
+
+# Cognitive Load
+
+The tab bar reduces destination recall to six visible choices. The list header, filter and grouped items scan predictably. Hidden row actions and swipe-to-change-tab are not discoverable from the screen itself; the small grabber only hints at mini-player movement and does not label what the movement does. No screen presents more than four primary decision points at once.
+
+# Emotional Journey
+
+Search and queue selection are direct, and the full-player sheet preserves the sense of continuity while browsing. Filling the screen with a real video makes fullscreen feel intentional. A long swipe that removes a row can create a negative surprise because the outcome is not previewed or recoverable.
+
+# What's Working
+
+- The F7 treatment now spans search, sidebar, home, list, settings, player, mini-player, tabs, sheets and auxiliary panels.
+- Fill/Fit is explicit, persisted, and also toggles by center double-tap or multi-touch.
+- The classic regression pair is pixel-identical at 390×844.
+
+# Priority Issues
+
+1. **[P2] Row gestures are hard to discover.** Users see an ellipsis, but do not know that left/right reveals Playlist, Remove and Queue. Add a one-time, dismissible hint or a small visible interaction cue. Suggested command: `/impeccable clarify`.
+2. **[P2] Swipe removal has weak recovery.** A long left swipe removes immediately, with no Undo affordance. Give the toast a short Undo action or reduce the destructive gesture to a normal revealed button. Suggested command: `/impeccable harden`.
+
+# Persona Red Flags
+
+- **Jordan (First-Timer):** Can find Search and Queue from the bottom bar, but cannot infer that a song row can be swiped to add it to a playlist or remove it.
+- **Alex (Power User):** Can move quickly through tabs and the mini-player, but a long-left removal has no quick undo if the wrong row is removed.
+- **Morgan (Accessibility-focused listener):** Touch actions have generous targets, but gestures have no equivalent hint and depend on a screen reader user discovering the menu path.
+
+# Minor Observations
+
+- The critique found overlapping F7 declarations in `theme-f7.css`; current precedence is predictable but the file would be easier to maintain if these layers were consolidated.
+- The queue/settings duplicate heading and the redundant settings list filter were fixed during this pass; Queue's Play action is now the filled primary action.
+- The section rail remains usable as a compact floating control above the tab bar.
+- The detector's font-size advisories in compact badges and section labels are intentional density choices; check any future increase in text scale against them.
+
+# Questions to Consider
+
+- Would a single dismissible swipe hint be enough, or should Queue/Playlist/Remove stay visible behind each row menu?
+- Should long-left remove remain as a shortcut if the toast gains Undo, or should removal require tapping the revealed action?

.impeccable/design.json

@@ -0,0 +1,328 @@
+{
+  "schemaVersion": 2,
+  "generatedAt": "2026-10-02T21:37:12.817947+00:00",
+  "title": "Design System: YT Player — Classic",
+  "extensions": {
+    "colorMeta": {
+      "accent": {
+        "role": "primary",
+        "displayName": "Accent"
+      },
+      "accent-bright": {
+        "role": "primary",
+        "displayName": "Accent Bright"
+      },
+      "accent-deep": {
+        "role": "primary",
+        "displayName": "Accent Deep"
+      },
+      "bg": {
+        "role": "neutral",
+        "displayName": "Bg"
+      },
+      "bg-1": {
+        "role": "neutral",
+        "displayName": "Bg 1"
+      },
+      "bg-2": {
+        "role": "neutral",
+        "displayName": "Bg 2"
+      },
+      "bg-3": {
+        "role": "neutral",
+        "displayName": "Bg 3"
+      },
+      "line": {
+        "role": "neutral",
+        "displayName": "Line"
+      },
+      "line-soft": {
+        "role": "neutral",
+        "displayName": "Line Soft"
+      },
+      "text": {
+        "role": "neutral",
+        "displayName": "Text"
+      },
+      "text-2": {
+        "role": "neutral",
+        "displayName": "Text 2"
+      },
+      "text-dim": {
+        "role": "neutral",
+        "displayName": "Text Dim"
+      },
+      "on-primary": {
+        "role": "neutral",
+        "displayName": "On Primary"
+      },
+      "on-play": {
+        "role": "neutral",
+        "displayName": "On Play"
+      },
+      "light-bg": {
+        "role": "neutral",
+        "displayName": "Light Bg"
+      },
+      "light-bg-1": {
+        "role": "neutral",
+        "displayName": "Light Bg 1"
+      },
+      "light-bg-2": {
+        "role": "neutral",
+        "displayName": "Light Bg 2"
+      },
+      "light-bg-3": {
+        "role": "neutral",
+        "displayName": "Light Bg 3"
+      },
+      "light-line": {
+        "role": "neutral",
+        "displayName": "Light Line"
+      },
+      "light-line-soft": {
+        "role": "neutral",
+        "displayName": "Light Line Soft"
+      },
+      "light-text": {
+        "role": "neutral",
+        "displayName": "Light Text"
+      },
+      "light-text-2": {
+        "role": "neutral",
+        "displayName": "Light Text 2"
+      },
+      "light-text-dim": {
+        "role": "neutral",
+        "displayName": "Light Text Dim"
+      },
+      "light-accent": {
+        "role": "primary",
+        "displayName": "Light Accent"
+      },
+      "light-accent-bright": {
+        "role": "primary",
+        "displayName": "Light Accent Bright"
+      },
+      "light-accent-deep": {
+        "role": "primary",
+        "displayName": "Light Accent Deep"
+      },
+      "contrast-bg": {
+        "role": "neutral",
+        "displayName": "Contrast Bg"
+      },
+      "contrast-bg-2": {
+        "role": "neutral",
+        "displayName": "Contrast Bg 2"
+      },
+      "contrast-bg-3": {
+        "role": "neutral",
+        "displayName": "Contrast Bg 3"
+      },
+      "contrast-line": {
+        "role": "neutral",
+        "displayName": "Contrast Line"
+      },
+      "contrast-line-soft": {
+        "role": "neutral",
+        "displayName": "Contrast Line Soft"
+      },
+      "contrast-text-dim": {
+        "role": "neutral",
+        "displayName": "Contrast Text Dim"
+      },
+      "contrast-accent": {
+        "role": "primary",
+        "displayName": "Contrast Accent"
+      },
+      "contrast-accent-bright": {
+        "role": "primary",
+        "displayName": "Contrast Accent Bright"
+      }
+    },
+    "typographyMeta": {
+      "display": {
+        "displayName": "Display",
+        "purpose": "Empty-home heading."
+      },
+      "headline": {
+        "displayName": "Headline",
+        "purpose": "Now-playing media title."
+      },
+      "title": {
+        "displayName": "Title",
+        "purpose": "Browsing heading."
+      },
+      "body": {
+        "displayName": "Body",
+        "purpose": "Interface text."
+      },
+      "label": {
+        "displayName": "Label",
+        "purpose": "Suggestion chips."
+      },
+      "media-title": {
+        "displayName": "Media Title",
+        "purpose": "Browsing media titles."
+      },
+      "time": {
+        "displayName": "Time",
+        "purpose": "Tabular transport timestamps."
+      }
+    },
+    "shadows": [
+      {
+        "name": "dialog-dark",
+        "value": "0 18px 50px -12px rgba(0, 0, 0, 0.7)",
+        "purpose": "Inherited dialog and sheet elevation in dark mode."
+      },
+      {
+        "name": "dialog-light",
+        "value": "0 18px 50px -18px rgba(0, 0, 0, 0.25)",
+        "purpose": "Inherited dialog and sheet elevation in light mode."
+      },
+      {
+        "name": "playing-edge",
+        "value": "inset 2px 0 var(--accent)",
+        "purpose": "Selected media row indicator, not ambient elevation."
+      }
+    ],
+    "motion": [
+      {
+        "name": "ease",
+        "value": "cubic-bezier(0.22, 1, 0.36, 1)",
+        "purpose": "Inherited interface easing."
+      },
+      {
+        "name": "color-state",
+        "value": "background 0.16s, color 0.16s",
+        "purpose": "Recurring inherited color state transition."
+      },
+      {
+        "name": "reduced-duration",
+        "value": "0.001ms",
+        "purpose": "Explicit preference and operating-system reduced motion."
+      }
+    ],
+    "breakpoints": [
+      {
+        "name": "stacked-max",
+        "value": "1200px"
+      },
+      {
+        "name": "mobile-max",
+        "value": "860px"
+      },
+      {
+        "name": "xl-navigation-max",
+        "value": "420px"
+      },
+      {
+        "name": "narrow-thumbnail-max",
+        "value": "380px"
+      },
+      {
+        "name": "transport-wide-container-min",
+        "value": "620px"
+      },
+      {
+        "name": "transport-narrow-container-max",
+        "value": "300px"
+      }
+    ]
+  },
+  "components": [
+    {
+      "name": "Filled action",
+      "kind": "button",
+      "refersTo": "button-primary",
+      "description": "Classic list action.",
+      "html": "<button class=\"ds-primary\">Play all</button>",
+      "css": ".ds-primary { background:var(--accent-deep,#c6442f);color:#fff;border:0;border-radius:8px;min-height:44px;padding:8px 12px;font:800 14px var(--ui,\"Hanken Grotesk\",system-ui,sans-serif);cursor:pointer;transition:background .16s,color .16s; }.ds-primary:focus-visible { outline:2px solid var(--accent,#f06b53);outline-offset:3px; }"
+    },
+    {
+      "name": "Search action",
+      "kind": "button",
+      "refersTo": "button-search",
+      "description": "Quiet search submission, accented on hover.",
+      "html": "<button class=\"ds-search\">Search</button>",
+      "css": ".ds-search { background:var(--bg-3,#2b2e33);color:var(--text,#f3f1ed);border:0;border-radius:8px;min-height:46px;padding:0 22px;font:600 14px var(--ui,\"Hanken Grotesk\",system-ui,sans-serif);cursor:pointer;transition:background .16s,color .16s; }.ds-search:hover { background:var(--accent-deep,#c6442f);color:#fff; }.ds-search:focus-visible { outline:2px solid var(--accent,#f06b53);outline-offset:3px; }"
+    },
+    {
+      "name": "Play control",
+      "kind": "button",
+      "refersTo": "button-play",
+      "description": "Circular primary transport.",
+      "html": "<button class=\"ds-play\" aria-label=\"Play\"><svg width=\"24\" height=\"24\" viewBox=\"0 0 24 24\" aria-hidden=\"true\"><path d=\"m8 5 11 7-11 7z\" fill=\"currentColor\"/></svg></button>",
+      "css": ".ds-play { display:grid;place-items:center;width:64px;height:64px;border:0;border-radius:50%;background:var(--accent,#f06b53);color:#171719;cursor:pointer;transition:background .16s; }.ds-play:hover { background:var(--accent-bright,#ff947e); }.ds-play:focus-visible { outline:2px solid var(--accent,#f06b53);outline-offset:3px; }"
+    },
+    {
+      "name": "Search field",
+      "kind": "input",
+      "refersTo": "input-search",
+      "description": "Full-width media query field.",
+      "html": "<input class=\"ds-input\" aria-label=\"Search media\" placeholder=\"Search YouTube…\">",
+      "css": ".ds-input { background:var(--bg-1,#18191c);color:var(--text,#f3f1ed);border:1px solid var(--line,#42464d);border-radius:8px;min-height:46px;padding:11px 14px;font:16px var(--ui,\"Hanken Grotesk\",system-ui,sans-serif);caret-color:var(--accent,#f06b53);transition:border-color .2s,background .2s; }.ds-input::placeholder { color:var(--text-dim,#a1a5ac);opacity:1; }.ds-input:focus-visible { outline:2px solid var(--accent,#f06b53);outline-offset:3px; }"
+    },
+    {
+      "name": "Suggestion chip",
+      "kind": "chip",
+      "refersTo": "chip",
+      "description": "Media search suggestion.",
+      "html": "<button class=\"ds-chip\">Jazz</button>",
+      "css": ".ds-chip { min-height:44px;padding:10px 14px;background:var(--bg-2,#202226);border:1px solid var(--line-soft,#2b2e33);border-radius:8px;color:var(--text,#f3f1ed);font:500 14px var(--ui,\"Hanken Grotesk\",system-ui,sans-serif);cursor:pointer;transition:background .16s,border-color .16s; }.ds-chip:hover { border-color:var(--accent,#f06b53); }.ds-chip:focus-visible { outline:2px solid var(--accent,#f06b53);outline-offset:3px; }"
+    },
+    {
+      "name": "Active navigation",
+      "kind": "nav",
+      "refersTo": "nav-active",
+      "description": "Sidebar selection with stroked SVG.",
+      "html": "<button class=\"ds-nav\" aria-current=\"page\"><svg width=\"20\" height=\"20\" viewBox=\"0 0 24 24\" aria-hidden=\"true\"><circle cx=\"10.5\" cy=\"10.5\" r=\"6.5\"/><path d=\"m16 16 5 5\"/></svg>Search</button>",
+      "css": ".ds-nav { display:flex;align-items:center;gap:12px;min-height:44px;padding:10px 12px;border:0;border-radius:var(--radius-sm,8px);background:var(--bg-3,#2b2e33);color:var(--text,#f3f1ed);font:14px var(--ui,\"Hanken Grotesk\",system-ui,sans-serif);cursor:pointer;transition:color .18s,background .18s; }.ds-nav svg { fill:none;stroke:var(--accent,#f06b53);stroke-width:1.7;stroke-linecap:round;stroke-linejoin:round; }.ds-nav:focus-visible { outline:2px solid var(--accent,#f06b53);outline-offset:3px; }"
+    },
+    {
+      "name": "Playing media row",
+      "kind": "card",
+      "refersTo": "media-row",
+      "description": "Divider-separated selected media without a raster fixture.",
+      "html": "<div class=\"ds-row\" tabindex=\"0\"><div class=\"ds-thumb\" aria-label=\"Media thumbnail area\"></div><div><div class=\"ds-title\">Media title</div><div class=\"ds-channel\">Channel</div></div><button class=\"ds-row-menu\" aria-label=\"Media actions\"><svg width=\"20\" height=\"20\" viewBox=\"0 0 24 24\" aria-hidden=\"true\"><circle cx=\"12\" cy=\"5\" r=\"1.5\"/><circle cx=\"12\" cy=\"12\" r=\"1.5\"/><circle cx=\"12\" cy=\"19\" r=\"1.5\"/></svg></button></div>",
+      "css": ".ds-row { display:grid;grid-template-columns:88px minmax(0,1fr) 44px;gap:12px;padding:12px 8px;border-bottom:1px solid var(--line-soft,#2b2e33);background:var(--bg-3,#2b2e33);box-shadow:inset 2px 0 var(--accent,#f06b53);color:var(--text,#f3f1ed);font-family:var(--ui,\"Hanken Grotesk\",system-ui,sans-serif); }.ds-thumb { width:88px;aspect-ratio:16/9;border-radius:6px;background:var(--bg-2,#202226); }.ds-title { font-size:14px;font-weight:600;line-height:1.45; }.ds-channel { font-size:12px;color:var(--text-dim,#a1a5ac);margin-top:5px; }.ds-row-menu { min-width:44px;min-height:44px;background:transparent;color:var(--text,#f3f1ed);border:0;cursor:pointer; }.ds-row-menu svg { fill:currentColor; }.ds-row:focus-visible { outline:2px solid var(--accent,#f06b53);outline-offset:3px; }.ds-row-menu:focus-visible { outline:2px solid var(--accent,#f06b53);outline-offset:3px; }"
+    }
+  ],
+  "narrative": {
+    "northStar": "Quiet Media Studio",
+    "overview": "Classic is a matte charcoal media workspace with warm white type and restrained vermilion. Watching and listening share the same visual priority; playback, browsing, and library controls remain legible together. This system applies only when the Classic layout is selected. Other theme families retain their own visual authority.\n\nThe implemented world uses tonal surfaces, fine dividers, bundled typography, and generous control targets. Light, high contrast, text scale, compact density, and reduced motion are supported appearance preferences. Source evidence is frontend/theme-classic.css, with inherited typography and preference values from frontend/styles.css and frontend/refresh.css; the approved direction lives in .impeccable/surfaces/frontend-theme-classic-css.md.",
+    "keyCharacteristics": [
+      "Matte tonal layers and fine dividers.",
+      "Restrained vermilion for playback, actions, and selection.",
+      "Bricolage headings, Hanken interface text, JetBrains timing.",
+      "Responsive workspace with persistent access to playback."
+    ],
+    "rules": [
+      {
+        "name": "The Classic Scope Rule",
+        "body": "Apply these rules only to Classic; shared markup does not make them rules for other layout families.",
+        "section": "colors"
+      },
+      {
+        "name": "The Tonal Surface Rule",
+        "body": "Use surface tone and fine dividers for resting depth; reserve the inherited ambient shadow for dialogs and sheets.",
+        "section": "elevation"
+      }
+    ],
+    "dos": [
+      "Do keep Classic overrides scoped to the selected Classic layout.",
+      "Do use tonal surfaces and fine dividers for workspace hierarchy.",
+      "Do preserve light, high contrast, text scale, density, safe areas, and reduced motion.",
+      "Do use inline SVG for navigation icons and retain visible keyboard focus.",
+      "Do use media thumbnails as user content."
+    ],
+    "donts": [
+      "Don't add ambient glow or grain to Classic.",
+      "Don't force empty home into the video aspect ratio.",
+      "Don't hide row actions until hover or reduce established control targets to fit a crowded layout.",
+      "Don't transfer this visual world to other layout families."
+    ]
+  }
+}

.impeccable/surfaces/frontend-theme-classic-css.md

@@ -0,0 +1,26 @@
+---
+version: 1
+slug: "frontend-theme-classic-css"
+primary_target: "frontend/theme-classic.css"
+related_targets: ["frontend/index.html","frontend/app.js"]
+---
+
+# Classic surface
+
+Mode: Operate. Scope: Classic in the shared web frontend, mobile browser/PWA and desktop. Preserve features and all other layout themes. User approved code-first implementation of the full redesign plan.
+
+## Direction contract
+
+THESIS: A quiet media workspace gives watching and listening equal attention. Empty home is useful content, never content trapped in a video frame.
+
+OWN-WORLD: Matte charcoal, warm white type, restrained vermilion, 12px corners, fine dividers. Bundled Hanken UI, Bricolage headings, JetBrains timing. No ambient glow or grain. Respect light and high-contrast preferences.
+
+STORY: Search or choose a playlist, play, then browse without losing playback. Existing features and factual copy survive.
+
+FIRST VIEWPORT: Desktop has a 232px library sidebar, flexible video/workspace and 340–420px browsing pane under search. Phones have search above content, centered transport under video, and existing navigation at the bottom. Empty home replaces the video proportions with a fully visible introduction or playlist collection.
+
+FORM: User-pinned quiet studio workspace; concept seed 6fcc153a was run, but its assignment and catalog alternatives do not override the explicitly approved plan. Signature interaction: scrolling from playback into browsing reveals the existing mini-player above navigation; selecting it returns to playback without moving the document viewport.
+
+FINISH: unreviewed and undocumented is unfinished; this build ends with the finish review, the verdict, DESIGN.md, and every shipping raster carrying its provenance
+
+Constraints: no generated artwork needed; existing media thumbnails are user content. Existing untracked mockups remain untouched. No deployment.

CLAUDE.md

@@ -54,6 +54,12 @@ JSON shapes mirror the Tauri Rust bridge exactly — don't change one side alone
   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.
+- **f7-swipe** (`frontend/f7-layout.js` + `theme-f7.css`): classic look + Framework7 gestures. Loads
+  `vendor/framework7-swipe.min.js` (F7 9.2.0 core+Store+Swipeout+Modal+Sheet, rebuilt from
+  `vendor/framework7-swipe.entry.js`) only when picked. Cards are wrapped in `li.swipeout` (Queue / Playlist /
+  Remove, via `card._video`), swipe up on the mini bar = F7 "Up next" sheet, sideways = next/prev, left-edge
+  swipe = sidebar. F7's touch module swallows programmatic `.click()`s, so `app.off('click')` +
+  `app.off('touchend')` run after init — keep that, or app.js buttons driven by `.click()` silently stop working.
 - Now-playing tiles are `[svg.ti][span.tl]`; change state text with `setTile(btn, label)`, never `textContent`.
 
 ## Saved searches + caching notes
@@ -554,3 +560,5 @@ 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.
+
+- Server code must not import `../frontend/...` directly: the Docker image copies frontend/ to `server/public/`. Use the existsSync fallback pattern (see piano.js / direct-relay.js).

DESIGN.md

@@ -0,0 +1,243 @@
+---
+name: "YT Player — Classic"
+description: "Quiet matte studio for watching and listening; applies only to the Classic layout."
+colors:
+  accent: "#f06b53"
+  accent-bright: "#ff947e"
+  accent-deep: "#c6442f"
+  bg: "#121315"
+  bg-1: "#18191c"
+  bg-2: "#202226"
+  bg-3: "#2b2e33"
+  line: "#42464d"
+  line-soft: "#2b2e33"
+  text: "#f3f1ed"
+  text-2: "#c3c4c7"
+  text-dim: "#a1a5ac"
+  on-primary: "#ffffff"
+  on-play: "#171719"
+  light-bg: "#f4f2ee"
+  light-bg-1: "#ffffff"
+  light-bg-2: "#efece6"
+  light-bg-3: "#e5e0d8"
+  light-line: "#d8d2c8"
+  light-line-soft: "#e6e1d9"
+  light-text: "#1b1a18"
+  light-text-2: "#4a4843"
+  light-text-dim: "#625e59"
+  light-accent: "#ff4b32"
+  light-accent-bright: "#ff6a52"
+  light-accent-deep: "#b43623"
+  contrast-bg: "#000000"
+  contrast-bg-2: "#0a0a0a"
+  contrast-bg-3: "#161616"
+  contrast-line: "#ffffff"
+  contrast-line-soft: "#9a9a9a"
+  contrast-text-dim: "#d8d8d8"
+  contrast-accent: "#ff5a3c"
+  contrast-accent-bright: "#ff8a6c"
+typography:
+  display:
+    fontFamily: "\"Bricolage Grotesque\", Georgia, serif"
+    fontSize: "clamp(36px, 4vw, 60px)"
+    fontWeight: 800
+    lineHeight: 1.05
+    letterSpacing: "-0.035em"
+  headline:
+    fontFamily: "\"Bricolage Grotesque\", Georgia, serif"
+    fontSize: "clamp(22px, 2vw, 30px)"
+    fontWeight: 700
+    lineHeight: 1.25
+    letterSpacing: "-0.02em"
+  title:
+    fontFamily: "\"Bricolage Grotesque\", Georgia, serif"
+    fontSize: "26px"
+    fontWeight: 700
+    lineHeight: 1.2
+  body:
+    fontFamily: "\"Hanken Grotesk\", system-ui, sans-serif"
+    fontSize: "14px"
+    lineHeight: 1.45
+  label:
+    fontFamily: "\"Hanken Grotesk\", system-ui, sans-serif"
+    fontSize: "14px"
+    fontWeight: 500
+  media-title:
+    fontFamily: "\"Hanken Grotesk\", system-ui, sans-serif"
+    fontSize: "14px"
+    fontWeight: 600
+    lineHeight: 1.45
+  time:
+    fontFamily: "\"JetBrains Mono\", ui-monospace, monospace"
+    fontSize: "12px"
+rounded:
+  flat: "0px"
+  thumbnail: "6px"
+  sm: "8px"
+  md: "12px"
+  circle: "50%"
+spacing:
+  small: "8px"
+  control-gap: "14px"
+  compact: "16px"
+  standard: "24px"
+components:
+  button-primary:
+    backgroundColor: "{colors.accent-deep}"
+    textColor: "{colors.on-primary}"
+    rounded: "{rounded.sm}"
+    padding: "8px 12px"
+  button-search:
+    backgroundColor: "{colors.bg-3}"
+    textColor: "{colors.text}"
+    rounded: "{rounded.sm}"
+    padding: "0 22px"
+  button-play:
+    backgroundColor: "{colors.accent}"
+    textColor: "{colors.on-play}"
+    rounded: "{rounded.circle}"
+    width: "64px"
+    height: "64px"
+  input-search:
+    backgroundColor: "{colors.bg-1}"
+    textColor: "{colors.text}"
+    rounded: "{rounded.sm}"
+    padding: "11px 14px"
+  chip:
+    backgroundColor: "{colors.bg-2}"
+    textColor: "{colors.text}"
+    typography: "{typography.label}"
+    rounded: "{rounded.sm}"
+    padding: "10px 14px"
+  nav-active:
+    backgroundColor: "{colors.bg-3}"
+    textColor: "{colors.text}"
+    padding: "10px 12px"
+  media-row:
+    textColor: "{colors.text}"
+    rounded: "{rounded.flat}"
+    padding: "12px 8px"
+  panel:
+    backgroundColor: "{colors.bg-1}"
+    rounded: "{rounded.md}"
+---
+
+# Design System: YT Player — Classic
+
+## Overview
+
+**Creative North Star: "Quiet Media Studio"**
+
+Classic is a matte charcoal media workspace with warm white type and restrained vermilion. Watching and listening share the same visual priority; playback, browsing, and library controls remain legible together. This system applies only when the Classic layout is selected. Other theme families retain their own visual authority.
+
+The implemented world uses tonal surfaces, fine dividers, bundled typography, and generous control targets. Light, high contrast, text scale, compact density, and reduced motion are supported appearance preferences. Source evidence is frontend/theme-classic.css, with inherited typography and preference values from frontend/styles.css and frontend/refresh.css; the approved direction lives in .impeccable/surfaces/frontend-theme-classic-css.md.
+
+**Key Characteristics:**
+- Matte tonal layers and fine dividers.
+- Restrained vermilion for playback, actions, and selection.
+- Bricolage headings, Hanken interface text, JetBrains timing.
+- Responsive workspace with persistent access to playback.
+
+## Colors
+
+The default palette is matte charcoal with warm white text and a restrained vermilion accent. Frontmatter values are normative; unprefixed tokens describe Classic dark mode, while light and contrast tokens record implemented preference variants.
+
+### Primary
+
+- **Vermilion:** accent marks playback, focus, active navigation icons, selection, and the playing row edge. Accent bright is the play hover and active lyric emphasis; accent deep is the filled action and brand surface.
+- **Action white / play charcoal:** the two implemented foregrounds for filled actions and circular transport.
+
+### Neutral
+
+- **Studio charcoal:** bg is the workspace; bg-1 is sidebar, browsing, fields, and support panels; bg-2 is chips, secondary actions, and mini-player; bg-3 carries active navigation, tabs, and playing rows.
+- **Fine dividers:** line-soft separates rows and regions; line marks stronger edges, including the mini-player boundary.
+- **Warm white / secondary / muted:** text, text-2, and text-dim distinguish titles, supporting copy, and metadata.
+- **Light preference:** warm paper workspace, white panels, pale neutral layers, and dark text. Classic overrides muted text and deep accent for this preference; the other light accent values are inherited.
+- **High contrast preference:** black primary surfaces, white foregrounds and strong lines; bg-1 inherits the same black as bg, text and text-2 inherit white, and accent-deep shares contrast-accent. These aliases are not separate color primitives.
+
+**The Classic Scope Rule.** Apply these rules only to Classic; shared markup does not make them rules for other layout families.
+
+## Typography
+
+**Display Font:** bundled Bricolage Grotesque, with Georgia and serif fallbacks.
+**Body Font:** bundled Hanken Grotesk, with system-ui and sans-serif fallbacks.
+**Label/Mono Font:** bundled JetBrains Mono, with ui-monospace and monospace fallbacks, for timing and data.
+
+Headings provide character; interface text stays compact and readable. Timing uses tabular numerals.
+
+### Hierarchy
+
+- **Display:** empty-home heading; the frontmatter clamp becomes a fixed (42px) on the mobile layout.
+- **Headline:** now-playing title, with wrapping permitted for long media names.
+- **Title:** browsing heading; playlist home uses (28px), reducing to (26px) on mobile.
+- **Body:** interface baseline; empty-home supporting copy uses (17px), (1.65) leading, and (45ch) maximum width, reducing to (16px) on mobile.
+- **Label:** chips and related compact actions; navigation captions stay at 11px, including narrow screens.
+- **Media title:** semibold titles in browsing rows; supporting channel metadata uses (12px).
+- **Time:** transport timestamps in the mono family with tabular numbers.
+
+Font preferences scale the whole UI to (0.9), (1), (1.12), or (1.26). Classic compensates the application height for that zoom.
+
+## Layout
+
+Desktop uses a (232px) library sidebar, a flexible playback workspace, and a browsing pane sized with `clamp(340px, 29%, 420px)`. Search spans up to (860px). Workspace padding is the standard spacing token; compact density uses the compact token and halves row block padding from (12px) to (6px).
+
+At viewport widths of (1200px) and below, playback and browsing stack in one scrolling body. At (860px) and below, the workspace becomes one column with mobile navigation and safe-area-aware padding. Home playlists use a two-column grid on mobile; desktop uses automatically filled columns with a (138px) minimum. Empty home has natural height rather than video proportions. Above (1200px), the playing video width is capped at `min(100%, calc(42dvh * 16 / 9))`.
+
+Transport responds to its own container: at (620px) and above it uses two columns with seek and quick actions spanning both; at (300px) and below it uses five equal transport columns and (44px) controls. At (420px) and below with extra-large text, bottom navigation becomes a three-column grid. Below (380px), the thumbnail width remains (88px); navigation captions retain (11px).
+
+Browsing rows use an (88px) thumbnail column, flexible text, and a (44px) action column. Most actions have at least (44px) targets; search uses (46px), quick transport actions (48px), and mobile navigation at least (58px) height. The main play control uses the frontmatter size, reduces to (56px) in the wide transport container, and (44px) in the narrowest container.
+
+The mini-player sits above mobile navigation and below the desktop workspace. Navigation, mini-player, and section-rail heights feed a combined clearance used by content and toasts. Returning from the mini-player brings playback into view without changing the document viewport.
+
+## Elevation & Depth
+
+Resting workspace surfaces are flat. Classic disables ambient bleed, grain, blur on navigation and mini-player, hero animation, card entrance animation, and thumbnail hover zoom. The playing row uses a narrow inset accent edge rather than a glow. Dialogs, shortcut panels, and more sheets retain the inherited soft ambient shadow; dark and light shadow values are recorded in the sidecar.
+
+**The Tonal Surface Rule.** Use surface tone and fine dividers for resting depth; reserve the inherited ambient shadow for dialogs and sheets.
+
+## Shapes
+
+Panels and the video stage use the medium radius; fields, chips, action buttons, tabs, and navigation details use the small radius. Thumbnails use the thumbnail radius. Browsing rows have flat corners and a bottom divider. The primary transport remains circular. The section rail rounds only its upper corners; mini-player surfaces remain flat across their width.
+
+## Components
+
+### Buttons
+
+Quiet surface buttons use bg-2 or bg-3 with primary text. The search action changes from bg-3 to accent-deep with white text on hover. Filled list and empty-state actions use accent-deep and white. Circular play uses accent with its dark foreground and changes to accent-bright on hover. Controls keep their established target sizes. Keyboard focus uses an accent outline (2px) with (3px) offset.
+
+### Chips
+
+Suggestion chips use bg-2, primary text, a line-soft border, the small radius, and label typography. Home capability descriptors remain unboxed text rather than duplicating action-chip surfaces.
+
+### Cards / Containers
+
+Media results are divider-separated rows rather than floating cards. Actions stay visible. The playing row uses bg-3 and an inset accent line (2px). Notes, up-next, and related containers use bg-1 and the medium radius; playlist collections keep natural height with no fading overflow mask.
+
+### Inputs / Fields
+
+Search uses bg-1, primary text, the small radius, and a (46px) minimum height. Placeholder text uses text-dim at full opacity and the caret uses accent. Settings fields retain at least (44px) height. Focus receives the shared visible outline.
+
+### Navigation
+
+Sidebar entries have (44px) minimum height, restrained spacing, inline stroked SVG icons (20px), and no decorative leading active marker. Active entries use bg-3 with primary text and an accent icon. Mobile navigation uses a matte bg-1 surface, muted inactive text, and an accent icon in the active entry; safe-area padding and text-scale layout remain part of the component.
+
+### Playback and Mini-player
+
+Playback combines a video stage, centered compact transport, timing, wrapped quick actions, and metadata. The mini-player uses bg-2 with a top line, no blur or shadow, and usable (44px) targets. The section rail and toast placement share the measured bottom clearance. Classic section-rail actions use the same inline stroked SVG vocabulary as navigation; other layouts retain their existing icons.
+
+State transitions inherit the existing short interface timings; the sidecar records the inherited easing and recurring color transition. Explicit reduced motion and the operating-system preference reduce animation and transition durations to (0.001ms), with one animation iteration. The explicit preference also sets automatic scrolling.
+
+## Do's and Don'ts
+
+### Do:
+- **Do** keep Classic overrides scoped to the selected Classic layout.
+- **Do** use tonal surfaces and fine dividers for workspace hierarchy.
+- **Do** preserve light, high contrast, text scale, density, safe areas, and reduced motion.
+- **Do** use inline SVG for navigation icons and retain visible keyboard focus.
+- **Do** use media thumbnails as user content.
+
+### Don't:
+- **Don't** add ambient glow or grain to Classic.
+- **Don't** force empty home into the video aspect ratio.
+- **Don't** hide row actions until hover or reduce established control targets to fit a crowded layout.
+- **Don't** transfer this visual world to other layout families.

PRODUCT.md

@@ -0,0 +1,36 @@
+# YT Player
+
+<!-- impeccable:product-schema 1 -->
+
+## Platform
+
+web
+
+## Users
+
+People watching videos and listening to music on desktop and mobile. The confirmed Classic brief gives watching and listening equal priority.
+
+## Product Purpose
+
+Search and play YouTube media, organize playlists, and keep saved media available offline. The web PWA and desktop wrappers share the same frontend.
+
+The web home and Search views also recommend familiar favorites and discoveries from server-collected metadata and listening summaries. Metadata and artwork collection cover search results and playlists as well as played videos, independently of media-file caching.
+
+## Capabilities and Constraints
+
+Preserve playback, playlists, queue, lyrics, notes, A–B loops, audio-only mode, offline storage, sharing, and settings. The frontend is plain HTML, CSS, and JavaScript with a Bun/Hono web backend. Classic is the default layout; other layouts share markup and must retain their behavior. Appearance settings include dark, light, contrast, font scale, density, performance, and reduced motion.
+
+## Brand Commitments
+
+Keep the YT Player name and existing factual copy. The approved Classic redesign uses a quiet dark studio direction. Other layout themes remain independent.
+
+## Evidence on Hand
+
+Existing frontend, bundled fonts, local icons, and browser tests. No invented customer claims or production data.
+
+## Product Principles
+
+- Playback and browsing must remain reachable together.
+- Mobile browser and installed PWA should offer consistent Classic navigation.
+- Empty, populated, and playing states each need an appropriate layout.
+- User data and appearance preferences survive theme changes.

docker-compose.yml

@@ -13,6 +13,8 @@ services:
       - /mnt/data/ytplayer:/app/bulk
     environment:
       PORT: "3000"
+      PIANO_WORKER_ENABLED: "${PIANO_WORKER_ENABLED:-0}"
+      PIANO_WORKER_TOKEN: "${PIANO_WORKER_TOKEN:-}"
       MEDIA_DIR: "/app/bulk/media"
       MEDIA_VOLUME_MARKER: "/app/bulk/.hl-data"
       MEDIA_CACHE_MAX_BYTES: "268435456000"   # 250 GiB of the 458 GiB drive
@@ -79,7 +81,7 @@ services:
       - "traefik.http.routers.ytplayer-https.tls.certresolver=letsencrypt"
       - "traefik.http.services.ytplayer-svc.loadbalancer.server.port=3000"
 
-  # Transcribes saved songs that have no lyrics yet, one at a time, with
+  # Handles requested Whisper drafts and transcribes saved songs without lyrics, with
   # faster-whisper on CPU (no API keys, no credits). Separate container so it
   # never competes with playback/downloads: capped CPU + memory, low priority,
   # and it fetches audio from the ytplayer service over the private network.
@@ -102,9 +104,27 @@ services:
     networks:
       - lyrics
 
+  # Optional high-fidelity transcription. Never starts without --profile piano.
+  piano-worker:
+    profiles: ["piano"]
+    build: ./scripts/piano
+    restart: unless-stopped
+    depends_on: [ytplayer]
+    environment:
+      YTP_BASE: "http://ytplayer:3000"
+      YTP_TOKEN: "${PIANO_WORKER_TOKEN:-}"
+      PIANO_THREADS: "2"
+    volumes:
+      - piano-models:/models
+    cpus: "2"
+    mem_limit: 6g
+    networks: [lyrics]
+
 volumes:
   ytplayer-data:
     driver: local
+  piano-models:
+    driver: local
   lyrics-models:
     driver: local
   lyrics-state:

docs/admin-lyrics-and-analytics.md

@@ -0,0 +1,122 @@
+# Lyrics and server analytics
+
+## Whisper drafts
+
+In `/admin#editor`, every song has a Whisper button alongside its Open button.
+The loaded song also has **Transcribe with Whisper**. Both enqueue the same
+server job; duplicate active requests reuse that job. The existing CPU
+faster-whisper container polls explicit requests every ten seconds and returns
+a timed draft even when that song already has lyrics. Manual requests always
+use Whisper, bypassing LRCLIB.
+
+**Use transcript in editor** loads the draft for review. **Save lyrics** publishes
+it through the existing revision history and conflict checks. Until saved,
+shared lyrics remain unchanged. Applying a draft can be undone, including the
+original sync offset. Queued/running jobs survive restarts; worker leases expire
+after two minutes and heartbeat every 25 seconds. After three failed worker
+attempts the job reports a failure. Completed/failed drafts are retained for
+30 days; cleanup runs when workers report progress.
+
+A YouTube video must already have a ready server media copy; uploads are also
+supported. The existing maximum of one hour and 40 MiB audio input applies.
+Songs without enough recognized vocals fail visibly. Transcription accuracy
+and word timing depend on the singing and audio mix; review before saving.
+
+Deploy the updated server and rebuild the `lyrics-worker` image. Both need the
+same `LYRICS_WORKER_TOKEN` (at least 24 characters; compose passes it to the
+worker as `YTP_TOKEN`). A configured token permits queuing; the status endpoint
+also reports whether a worker has recently polled. No paid transcription API
+is involved.
+
+Admin endpoints (admin cookie or API token):
+
+- `POST /api/admin/transcriptions/:video` queues a draft.
+- `GET /api/admin/transcriptions/:video` returns the latest draft/progress.
+
+Worker-only endpoints require the worker token:
+
+- `POST /api/lyrics-worker/claim` claims one job.
+- `POST /api/lyrics-worker/jobs/:job` reports progress/results with its lease.
+
+## Grouped lyric lines
+
+One lyric cue can contain multiple visual lines with one timestamp. In the
+admin editor, **Shift+Enter** inserts a tight line break. On phones, select the
+cue and use **Line break** in its options. Ordinary Enter or **Below** adds a
+separate cue with its own timing. Both visual lines of a grouped cue highlight
+and seek together in service mode, with a smaller internal gap than the space
+between cues. The player panel, stage and presenter views also preserve breaks.
+
+Text editing/export uses a continuation prefix to preserve the grouping:
+
+```text
+[0:12.00] Because You are God
+| You can do anything
+[0:18.00] Another separate cue
+```
+
+The continuation belongs to the preceding cue. JSON stores its text as
+`"Because You are God\nYou can do anything"`. Saving, revisions and text
+round trips retain the single timestamp. Reporting a wrong lyric also preserves the grouped text. Existing single-line lyrics work
+unchanged.
+
+## Server analytics and metadata collector
+
+Open **Stats** (`/admin#analytics`). It shows cached video and upload totals,
+recorded plays, discovery sources, metadata/thumbnail payload sizes, and
+available filesystem space for media, uploads and the database. Paths on the
+same device share their free space; their capacities must not be added.
+Media totals come from library records and exclude temporary files and
+filesystem overhead. Metadata bytes exclude indexes and SQLite overhead.
+
+The collector accepts a search, a total unique-video limit (1–500), and depth:
+
+- **0:** only the specified search.
+- **1:** also search channels and tags found in its results.
+- **2/3:** follow up to two/three related rounds.
+
+The total limit applies across every round. The collector reserves result
+budget for deeper rounds, deduplicates video IDs and related queries, and stops
+after at most 24 searches. Duplicate, unavailable or empty results can produce
+fewer videos than requested. Up to three collections may be queued/running;
+one executes at a time per server. Atomic ownership leases prevent two
+servers from claiming the same job. Progress is saved after each discovery
+batch and video. An expired interrupted job resumes its pending items.
+**Stop collection** cancels future work; an extraction already in progress
+can finish its network request before the cancellation is observed.
+
+Discovery cards enter the same catalog used for recommendations. Each video
+is then enriched through yt-dlp without downloading media. The server stores
+full descriptive fields (including descriptions, dates, engagement counts,
+language, tags, chapters, thumbnail variants and format specifications) in
+`video_details`. Expiring media URLs and request headers are excluded. Details
+are capped at 500 KB per video and follow catalog eviction. Thumbnail image
+bytes use the existing durable thumbnail queue, host restrictions and budget
+(default 512 MiB). Failures stay visible in job history; successful cards remain
+stored even when enrichment fails. Refresh analytics to update the aggregate
+numbers after collection; job progress polls automatically while this tab is
+open.
+
+The metadata library supports title/channel/tag filtering, 50-row pages and a
+raw descriptive metadata view. Admin cookie or API token is required for:
+
+- `GET /api/admin/analytics`
+- `GET /api/admin/metadata?q=...&offset=...`
+- `GET /api/admin/metadata/:id`
+- `GET /api/admin/collections`
+- `POST /api/admin/collections` with `{query,maxVideos,depth}`
+- `POST /api/admin/collections/:id/cancel`
+
+## Verification
+
+Run `bun run test` in `server`, `npm test` at the repo root,
+`python3 -m unittest discover -s scripts/lyrics -p test_auto_lyrics.py`, and
+`npx playwright test -c playwright.admin.config.js`. Admin browser fixtures
+cover Whisper review/save/undo, unsaved edits, failures, mobile actions,
+grouped cues and service highlighting, and analytics collector controls.
+
+Design review fixed the primary action’s white-on-gradient contrast by using a
+solid purple fill, and fixed tablet navigation overflow. No new findings were
+suppressed. Existing admin play/tap gradient contrast and decorative glow
+findings remain outside these controls. Real viewport captures passed the
+mobile dashboard/collector and desktop visual checks.

docs/classic-redesign-verification.md

@@ -0,0 +1,22 @@
+# Classic redesign verification
+
+## Scope
+
+Classic's responsive web UI, including desktop, mobile browser and simulated installed-PWA navigation. Synthetic playlist/media metadata was used for browser checks and screenshots; no production profiles or playlists were changed. No deployment was performed.
+
+## Automated checks
+
+- `npx playwright test --config playwright.classic.config.js`: 11 passed. Covers empty home at 320/390/768/1024/1280/1440px, navigation during a populated player state, mini-player return, advanced controls, theme switching, rotation, extra-large text at 320px, and cached Classic CSS on offline reload.
+- `node --test --test-isolation=none frontend/*.test.js`: 72 passed after rebasing onto the latest remote changes (65 passed before the rebase). Explicitly disabling process isolation exposes individual test results in this environment; the default isolated runner initially reported only nine file-level passes. The latest suite ran outside the sandbox because the WebAssembly fallback test spawns Node.
+- Existing portrait-PWA, viewport-anchor and fullscreen smoke tests run in Chromium: 9 passed, 4 failed. The same tests against unchanged HEAD frontend assets produced the identical 9/4 result. The four baseline failures are the fullscreen fallback/audio-only expectations and the portrait rotation/wide layout checks that expect the empty-home list pane to be visible.
+- `node --check frontend/app.js` and `git diff --check` passed.
+
+## Visual evidence
+
+Local browser captures live under `.impeccable/review/` (ignored build evidence): desktop/mobile player and empty home, mobile playlists and settings, desktop light appearance, and a 320px phone with extra-large text. They use labeled synthetic preview artwork. The final capture pass measured no main-pane or control-deck horizontal overflow and an app height equal to the viewport for every captured size.
+
+Impeccable's detector ran once against the changed UI targets. Its findings refer to the shared index and inherited styling, including other themes; the report is not proof of active Classic contrast or full accessibility conformance. The independent reviewer requested SVG section shortcuts and readable footer captions. Both fixes were confirmed resolved with a `ship` verdict covering the scored fixes, recorded in `.impeccable/review/finish-review.md`. The replacement reviewer inspected local captures directly after the external vision tool stalled; the original reviewer had stopped at a usage limit.
+
+## Limits
+
+No real iOS/Android device or WebKit browser run was available. Media fixture checks validate layout/navigation, not a live YouTube stream, audio synchronization, or native fullscreen. Other layout themes retain their styles; regression checks cover switching and data preservation, not exhaustive visual audits of every theme.

docs/design/f7-swipe-contrast.json

@@ -0,0 +1,904 @@
+{
+ "title": "YT Player \u2014 Framework7 Swipe (contrast)",
+ "brief": "Ad-free YouTube/worship player PWA. Framework7 iOS-style layout with swipe gestures, built on the app's own tokens.",
+ "frame": "phone",
+ "platform": "web",
+ "paletteKey": "coral",
+ "theme": {
+  "dark": true,
+  "bothModes": false,
+  "contrast": "high",
+  "shape": "rounded",
+  "font": "system",
+  "emphasized": false,
+  "motion": "expressive"
+ },
+ "frames": [
+  {
+   "id": "search",
+   "name": "Search",
+   "x": 0,
+   "y": 0,
+   "note": "Home + search results. Big title, rounded search field, results as an inset grouped list.",
+   "swipe": {
+    "left": "queue"
+   }
+  },
+  {
+   "id": "queue",
+   "name": "Queue",
+   "x": 492,
+   "y": 0,
+   "note": "Queued songs. Swipe a row left for Playlist/Remove (long swipe removes), right for Queue. Swipe sideways on empty space to change tab.",
+   "swipe": {
+    "right": "search"
+   }
+  },
+  {
+   "id": "player",
+   "name": "Now playing",
+   "x": 984,
+   "y": 0,
+   "note": "Video on top, Apple Music\u2013style transport, icon action row. Swipe down to collapse to the mini player.",
+   "swipe": {
+    "down": "queue"
+   }
+  },
+  {
+   "id": "upnext",
+   "name": "Up next",
+   "x": 1476,
+   "y": 0,
+   "note": "Bottom sheet opened by swiping up on the mini player. Half height, drag up for full, down to close."
+  },
+  {
+   "id": "fullscreen",
+   "name": "Fullscreen",
+   "x": 1968,
+   "y": 0,
+   "note": "Edge-to-edge video (Fill by default). Minimal icon-only controls over a soft bottom gradient; auto-hide.",
+   "bg": "inverseSurface"
+  }
+ ],
+ "groups": [
+  {
+   "id": "g2",
+   "x": 0,
+   "y": 0,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i1",
+     "kind": "topAppBar",
+     "label": "Search",
+     "icon": "menu",
+     "variant": "filled",
+     "icon2": "directions_car",
+     "note": "Translucent navbar; menu opens the sidebar (also left-edge swipe)."
+    }
+   ]
+  },
+  {
+   "id": "g4",
+   "x": 16,
+   "y": 96,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i3",
+     "kind": "searchBar",
+     "label": "Search YouTube",
+     "icon": null,
+     "variant": "filled",
+     "icon2": "mic",
+     "note": "Rounded F7 searchbar with inline mic; Enter searches."
+    }
+   ]
+  },
+  {
+   "id": "g8",
+   "x": 16,
+   "y": 164,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i5",
+     "kind": "chip",
+     "label": "lofi beats",
+     "icon": null,
+     "variant": "filled"
+    },
+    {
+     "id": "i6",
+     "kind": "chip",
+     "label": "live news",
+     "icon": null,
+     "variant": "filled"
+    },
+    {
+     "id": "i7",
+     "kind": "chip",
+     "label": "worship",
+     "icon": null,
+     "variant": "filled"
+    }
+   ]
+  },
+  {
+   "id": "g10",
+   "x": 16,
+   "y": 212,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i9",
+     "kind": "text",
+     "label": "Results",
+     "icon": null,
+     "variant": "filled",
+     "size": 28,
+     "bold": true
+    }
+   ]
+  },
+  {
+   "id": "g15",
+   "x": 16,
+   "y": 260,
+   "axis": "y",
+   "items": [
+    {
+     "id": "i11",
+     "kind": "listItem",
+     "label": "Goodness of God",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Bethel Music \u00b7 5:12",
+     "icon2": "more_horiz",
+     "action": {
+      "to": "player",
+      "transition": "slide"
+     }
+    },
+    {
+     "id": "i12",
+     "kind": "listItem",
+     "label": "Way Maker",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Leeland \u00b7 3:12",
+     "icon2": "more_horiz",
+     "action": {
+      "to": "player",
+      "transition": "slide"
+     }
+    },
+    {
+     "id": "i13",
+     "kind": "listItem",
+     "label": "Build My Life",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Housefires \u00b7 6:04",
+     "icon2": "more_horiz",
+     "action": {
+      "to": "player",
+      "transition": "slide"
+     }
+    },
+    {
+     "id": "i14",
+     "kind": "listItem",
+     "label": "Graves Into Gardens",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Elevation \u00b7 6:41",
+     "icon2": "more_horiz",
+     "action": {
+      "to": "player",
+      "transition": "slide"
+     }
+    }
+   ]
+  },
+  {
+   "id": "g17",
+   "x": 16,
+   "y": 700,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i16",
+     "kind": "listItem",
+     "label": "Way Maker",
+     "icon": "music_note",
+     "variant": "tonal",
+     "supporting": "Leeland \u00b7 3:12",
+     "icon2": "play_arrow",
+     "action": {
+      "to": "player",
+      "transition": "slideUp"
+     },
+     "note": "Floating glass mini player. Tap opens the player, swipe left/right = next/previous, swipe up = Up next sheet."
+    }
+   ]
+  },
+  {
+   "id": "g19",
+   "x": 0,
+   "y": 788,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i18",
+     "kind": "bottomNav",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "tabs": [
+      {
+       "icon": "search",
+       "label": "Search"
+      },
+      {
+       "icon": "queue_music",
+       "label": "Queue"
+      },
+      {
+       "icon": "history",
+       "label": "History"
+      },
+      {
+       "icon": "download_done",
+       "label": "Saved"
+      },
+      {
+       "icon": "more_horiz",
+       "label": "More"
+      }
+     ],
+     "selected": 0,
+     "actions": {
+      "tab:0": {
+       "to": "search",
+       "transition": "fade"
+      },
+      "tab:1": {
+       "to": "queue",
+       "transition": "fade"
+      }
+     },
+     "note": "Translucent blurred tab bar; badge on Queue."
+    }
+   ]
+  },
+  {
+   "id": "g21",
+   "x": 492,
+   "y": 0,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i20",
+     "kind": "topAppBar",
+     "label": "Queue",
+     "icon": "menu",
+     "variant": "filled",
+     "icon2": "checklist"
+    }
+   ]
+  },
+  {
+   "id": "g24",
+   "x": 508,
+   "y": 96,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i22",
+     "kind": "button",
+     "label": "Play queue",
+     "icon": "play_arrow",
+     "variant": "filled",
+     "size": 182
+    },
+    {
+     "id": "i23",
+     "kind": "button",
+     "label": "Clear",
+     "icon": "clear_all",
+     "variant": "tonal",
+     "size": 182
+    }
+   ]
+  },
+  {
+   "id": "g29",
+   "x": 508,
+   "y": 168,
+   "axis": "y",
+   "items": [
+    {
+     "id": "i25",
+     "kind": "listItem",
+     "label": "Way Maker",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Leeland \u00b7 3:12",
+     "icon2": "drag_handle",
+     "note": "Swipe right \u2192 Queue (accent action)."
+    },
+    {
+     "id": "i26",
+     "kind": "listItem",
+     "label": "Build My Life",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Housefires \u00b7 6:04",
+     "icon2": "drag_handle",
+     "note": "Swipe left \u2192 Playlist + Remove pills."
+    },
+    {
+     "id": "i27",
+     "kind": "listItem",
+     "label": "Graves Into Gardens",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Elevation \u00b7 6:41",
+     "icon2": "drag_handle",
+     "note": "Long swipe left removes the row."
+    },
+    {
+     "id": "i28",
+     "kind": "listItem",
+     "label": "Goodness of God",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Bethel Music \u00b7 5:12",
+     "icon2": "drag_handle",
+     "note": ""
+    }
+   ]
+  },
+  {
+   "id": "g32",
+   "x": 508,
+   "y": 480,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i30",
+     "kind": "button",
+     "label": "Playlist",
+     "icon": "playlist_add",
+     "variant": "tonal"
+    },
+    {
+     "id": "i31",
+     "kind": "button",
+     "label": "Remove",
+     "icon": "delete",
+     "variant": "filled"
+    }
+   ]
+  },
+  {
+   "id": "g34",
+   "x": 508,
+   "y": 548,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i33",
+     "kind": "text",
+     "label": "Swipe actions revealed (example row)",
+     "icon": null,
+     "variant": "filled",
+     "size": 14
+    }
+   ]
+  },
+  {
+   "id": "g36",
+   "x": 508,
+   "y": 700,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i35",
+     "kind": "listItem",
+     "label": "Way Maker",
+     "icon": "music_note",
+     "variant": "tonal",
+     "supporting": "Leeland \u00b7 3:12",
+     "icon2": "play_arrow",
+     "action": {
+      "to": "player",
+      "transition": "slideUp"
+     },
+     "note": "Floating glass mini player. Tap opens the player, swipe left/right = next/previous, swipe up = Up next sheet."
+    }
+   ]
+  },
+  {
+   "id": "g38",
+   "x": 492,
+   "y": 788,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i37",
+     "kind": "bottomNav",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "tabs": [
+      {
+       "icon": "search",
+       "label": "Search"
+      },
+      {
+       "icon": "queue_music",
+       "label": "Queue"
+      },
+      {
+       "icon": "history",
+       "label": "History"
+      },
+      {
+       "icon": "download_done",
+       "label": "Saved"
+      },
+      {
+       "icon": "more_horiz",
+       "label": "More"
+      }
+     ],
+     "selected": 1,
+     "actions": {
+      "tab:0": {
+       "to": "search",
+       "transition": "fade"
+      },
+      "tab:1": {
+       "to": "queue",
+       "transition": "fade"
+      }
+     },
+     "note": "Translucent blurred tab bar; badge on Queue."
+    }
+   ]
+  },
+  {
+   "id": "g40",
+   "x": 984,
+   "y": 0,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i39",
+     "kind": "topAppBar",
+     "label": "Now playing",
+     "icon": "keyboard_arrow_down",
+     "variant": "filled",
+     "icon2": "more_horiz",
+     "actions": {
+      "icon": {
+       "to": "back",
+       "transition": "slideDown"
+      }
+     }
+    }
+   ]
+  },
+  {
+   "id": "g42",
+   "x": 984,
+   "y": 88,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i41",
+     "kind": "image",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "size": 412,
+     "note": "16:9 video stage; the fullscreen button opens Fullscreen."
+    }
+   ]
+  },
+  {
+   "id": "g44",
+   "x": 1000,
+   "y": 320,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i43",
+     "kind": "text",
+     "label": "Way Maker",
+     "icon": null,
+     "variant": "filled",
+     "size": 24,
+     "bold": true
+    }
+   ]
+  },
+  {
+   "id": "g46",
+   "x": 1000,
+   "y": 356,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i45",
+     "kind": "text",
+     "label": "Leeland",
+     "icon": null,
+     "variant": "filled",
+     "size": 16
+    }
+   ]
+  },
+  {
+   "id": "g48",
+   "x": 1000,
+   "y": 396,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i47",
+     "kind": "slider",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "value": 35,
+     "note": "Thin seek track, accent fill."
+    }
+   ]
+  },
+  {
+   "id": "g54",
+   "x": 1048,
+   "y": 456,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i49",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "skip_previous",
+     "variant": "text"
+    },
+    {
+     "id": "i50",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "replay_10",
+     "variant": "text"
+    },
+    {
+     "id": "i51",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "play_arrow",
+     "variant": "filled"
+    },
+    {
+     "id": "i52",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "forward_10",
+     "variant": "text"
+    },
+    {
+     "id": "i53",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "skip_next",
+     "variant": "text"
+    }
+   ]
+  },
+  {
+   "id": "g61",
+   "x": 1024,
+   "y": 540,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i55",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "playlist_add",
+     "variant": "text"
+    },
+    {
+     "id": "i56",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "download",
+     "variant": "text"
+    },
+    {
+     "id": "i57",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "lyrics",
+     "variant": "text"
+    },
+    {
+     "id": "i58",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "share",
+     "variant": "text"
+    },
+    {
+     "id": "i59",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "fullscreen",
+     "variant": "text",
+     "action": {
+      "to": "fullscreen",
+      "transition": "expand"
+     }
+    },
+    {
+     "id": "i60",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "more_horiz",
+     "variant": "text"
+    }
+   ]
+  },
+  {
+   "id": "g63",
+   "x": 984,
+   "y": 788,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i62",
+     "kind": "bottomNav",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "tabs": [
+      {
+       "icon": "search",
+       "label": "Search"
+      },
+      {
+       "icon": "queue_music",
+       "label": "Queue"
+      },
+      {
+       "icon": "history",
+       "label": "History"
+      },
+      {
+       "icon": "download_done",
+       "label": "Saved"
+      },
+      {
+       "icon": "more_horiz",
+       "label": "More"
+      }
+     ],
+     "selected": 1,
+     "actions": {
+      "tab:0": {
+       "to": "search",
+       "transition": "fade"
+      },
+      "tab:1": {
+       "to": "queue",
+       "transition": "fade"
+      }
+     },
+     "note": "Translucent blurred tab bar; badge on Queue."
+    }
+   ]
+  },
+  {
+   "id": "g65",
+   "x": 1476,
+   "y": 0,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i64",
+     "kind": "topAppBar",
+     "label": "Queue",
+     "icon": "menu",
+     "variant": "filled"
+    }
+   ]
+  },
+  {
+   "id": "g67",
+   "x": 1476,
+   "y": 380,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i66",
+     "kind": "box",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "size": 412,
+     "size2": 512,
+     "checked": true,
+     "fill": "surfaceContainerHigh",
+     "note": "F7 sheet with grab handle; backdrop tap closes."
+    }
+   ]
+  },
+  {
+   "id": "g69",
+   "x": 1492,
+   "y": 404,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i68",
+     "kind": "text",
+     "label": "Up next",
+     "icon": null,
+     "variant": "filled",
+     "size": 20,
+     "bold": true
+    }
+   ]
+  },
+  {
+   "id": "g73",
+   "x": 1492,
+   "y": 448,
+   "axis": "y",
+   "items": [
+    {
+     "id": "i70",
+     "kind": "listItem",
+     "label": "Build My Life",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Housefires \u00b7 6:04",
+     "action": {
+      "to": "player",
+      "transition": "fade"
+     }
+    },
+    {
+     "id": "i71",
+     "kind": "listItem",
+     "label": "Graves Into Gardens",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Elevation \u00b7 6:41",
+     "action": {
+      "to": "player",
+      "transition": "fade"
+     }
+    },
+    {
+     "id": "i72",
+     "kind": "listItem",
+     "label": "Goodness of God",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Bethel Music \u00b7 5:12",
+     "action": {
+      "to": "player",
+      "transition": "fade"
+     }
+    }
+   ]
+  },
+  {
+   "id": "g75",
+   "x": 1968,
+   "y": 0,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i74",
+     "kind": "box",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "size": 412,
+     "size2": 892,
+     "fill": "inverseSurface",
+     "note": "Video fills the screen (object-fit cover). Fit/Fill toggle in the controls."
+    }
+   ]
+  },
+  {
+   "id": "g77",
+   "x": 1984,
+   "y": 24,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i76",
+     "kind": "text",
+     "label": "Way Maker \u2014 Leeland",
+     "icon": null,
+     "variant": "filled",
+     "size": 14
+    }
+   ]
+  },
+  {
+   "id": "g79",
+   "x": 2316,
+   "y": 12,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i78",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "fullscreen_exit",
+     "variant": "text",
+     "action": {
+      "to": "player",
+      "transition": "fade"
+     }
+    }
+   ]
+  },
+  {
+   "id": "g81",
+   "x": 1984,
+   "y": 790,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i80",
+     "kind": "slider",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "value": 35
+    }
+   ]
+  },
+  {
+   "id": "g85",
+   "x": 1984,
+   "y": 828,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i82",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "pause",
+     "variant": "text"
+    },
+    {
+     "id": "i83",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "screen_rotation",
+     "variant": "text"
+    },
+    {
+     "id": "i84",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "fit_screen",
+     "variant": "text",
+     "note": "Fit \u2194 Fill."
+    }
+   ]
+  }
+ ]
+}

docs/design/f7-swipe-dark.json

@@ -0,0 +1,904 @@
+{
+ "title": "YT Player \u2014 Framework7 Swipe (dark)",
+ "brief": "Ad-free YouTube/worship player PWA. Framework7 iOS-style layout with swipe gestures, built on the app's own tokens.",
+ "frame": "phone",
+ "platform": "web",
+ "paletteKey": "coral",
+ "theme": {
+  "dark": true,
+  "bothModes": true,
+  "contrast": "standard",
+  "shape": "rounded",
+  "font": "system",
+  "emphasized": false,
+  "motion": "expressive"
+ },
+ "frames": [
+  {
+   "id": "search",
+   "name": "Search",
+   "x": 0,
+   "y": 0,
+   "note": "Home + search results. Big title, rounded search field, results as an inset grouped list.",
+   "swipe": {
+    "left": "queue"
+   }
+  },
+  {
+   "id": "queue",
+   "name": "Queue",
+   "x": 492,
+   "y": 0,
+   "note": "Queued songs. Swipe a row left for Playlist/Remove (long swipe removes), right for Queue. Swipe sideways on empty space to change tab.",
+   "swipe": {
+    "right": "search"
+   }
+  },
+  {
+   "id": "player",
+   "name": "Now playing",
+   "x": 984,
+   "y": 0,
+   "note": "Video on top, Apple Music\u2013style transport, icon action row. Swipe down to collapse to the mini player.",
+   "swipe": {
+    "down": "queue"
+   }
+  },
+  {
+   "id": "upnext",
+   "name": "Up next",
+   "x": 1476,
+   "y": 0,
+   "note": "Bottom sheet opened by swiping up on the mini player. Half height, drag up for full, down to close."
+  },
+  {
+   "id": "fullscreen",
+   "name": "Fullscreen",
+   "x": 1968,
+   "y": 0,
+   "note": "Edge-to-edge video (Fill by default). Minimal icon-only controls over a soft bottom gradient; auto-hide.",
+   "bg": "inverseSurface"
+  }
+ ],
+ "groups": [
+  {
+   "id": "g2",
+   "x": 0,
+   "y": 0,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i1",
+     "kind": "topAppBar",
+     "label": "Search",
+     "icon": "menu",
+     "variant": "filled",
+     "icon2": "directions_car",
+     "note": "Translucent navbar; menu opens the sidebar (also left-edge swipe)."
+    }
+   ]
+  },
+  {
+   "id": "g4",
+   "x": 16,
+   "y": 96,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i3",
+     "kind": "searchBar",
+     "label": "Search YouTube",
+     "icon": null,
+     "variant": "filled",
+     "icon2": "mic",
+     "note": "Rounded F7 searchbar with inline mic; Enter searches."
+    }
+   ]
+  },
+  {
+   "id": "g8",
+   "x": 16,
+   "y": 164,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i5",
+     "kind": "chip",
+     "label": "lofi beats",
+     "icon": null,
+     "variant": "filled"
+    },
+    {
+     "id": "i6",
+     "kind": "chip",
+     "label": "live news",
+     "icon": null,
+     "variant": "filled"
+    },
+    {
+     "id": "i7",
+     "kind": "chip",
+     "label": "worship",
+     "icon": null,
+     "variant": "filled"
+    }
+   ]
+  },
+  {
+   "id": "g10",
+   "x": 16,
+   "y": 212,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i9",
+     "kind": "text",
+     "label": "Results",
+     "icon": null,
+     "variant": "filled",
+     "size": 28,
+     "bold": true
+    }
+   ]
+  },
+  {
+   "id": "g15",
+   "x": 16,
+   "y": 260,
+   "axis": "y",
+   "items": [
+    {
+     "id": "i11",
+     "kind": "listItem",
+     "label": "Goodness of God",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Bethel Music \u00b7 5:12",
+     "icon2": "more_horiz",
+     "action": {
+      "to": "player",
+      "transition": "slide"
+     }
+    },
+    {
+     "id": "i12",
+     "kind": "listItem",
+     "label": "Way Maker",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Leeland \u00b7 3:12",
+     "icon2": "more_horiz",
+     "action": {
+      "to": "player",
+      "transition": "slide"
+     }
+    },
+    {
+     "id": "i13",
+     "kind": "listItem",
+     "label": "Build My Life",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Housefires \u00b7 6:04",
+     "icon2": "more_horiz",
+     "action": {
+      "to": "player",
+      "transition": "slide"
+     }
+    },
+    {
+     "id": "i14",
+     "kind": "listItem",
+     "label": "Graves Into Gardens",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Elevation \u00b7 6:41",
+     "icon2": "more_horiz",
+     "action": {
+      "to": "player",
+      "transition": "slide"
+     }
+    }
+   ]
+  },
+  {
+   "id": "g17",
+   "x": 16,
+   "y": 700,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i16",
+     "kind": "listItem",
+     "label": "Way Maker",
+     "icon": "music_note",
+     "variant": "tonal",
+     "supporting": "Leeland \u00b7 3:12",
+     "icon2": "play_arrow",
+     "action": {
+      "to": "player",
+      "transition": "slideUp"
+     },
+     "note": "Floating glass mini player. Tap opens the player, swipe left/right = next/previous, swipe up = Up next sheet."
+    }
+   ]
+  },
+  {
+   "id": "g19",
+   "x": 0,
+   "y": 788,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i18",
+     "kind": "bottomNav",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "tabs": [
+      {
+       "icon": "search",
+       "label": "Search"
+      },
+      {
+       "icon": "queue_music",
+       "label": "Queue"
+      },
+      {
+       "icon": "history",
+       "label": "History"
+      },
+      {
+       "icon": "download_done",
+       "label": "Saved"
+      },
+      {
+       "icon": "more_horiz",
+       "label": "More"
+      }
+     ],
+     "selected": 0,
+     "actions": {
+      "tab:0": {
+       "to": "search",
+       "transition": "fade"
+      },
+      "tab:1": {
+       "to": "queue",
+       "transition": "fade"
+      }
+     },
+     "note": "Translucent blurred tab bar; badge on Queue."
+    }
+   ]
+  },
+  {
+   "id": "g21",
+   "x": 492,
+   "y": 0,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i20",
+     "kind": "topAppBar",
+     "label": "Queue",
+     "icon": "menu",
+     "variant": "filled",
+     "icon2": "checklist"
+    }
+   ]
+  },
+  {
+   "id": "g24",
+   "x": 508,
+   "y": 96,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i22",
+     "kind": "button",
+     "label": "Play queue",
+     "icon": "play_arrow",
+     "variant": "filled",
+     "size": 182
+    },
+    {
+     "id": "i23",
+     "kind": "button",
+     "label": "Clear",
+     "icon": "clear_all",
+     "variant": "tonal",
+     "size": 182
+    }
+   ]
+  },
+  {
+   "id": "g29",
+   "x": 508,
+   "y": 168,
+   "axis": "y",
+   "items": [
+    {
+     "id": "i25",
+     "kind": "listItem",
+     "label": "Way Maker",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Leeland \u00b7 3:12",
+     "icon2": "drag_handle",
+     "note": "Swipe right \u2192 Queue (accent action)."
+    },
+    {
+     "id": "i26",
+     "kind": "listItem",
+     "label": "Build My Life",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Housefires \u00b7 6:04",
+     "icon2": "drag_handle",
+     "note": "Swipe left \u2192 Playlist + Remove pills."
+    },
+    {
+     "id": "i27",
+     "kind": "listItem",
+     "label": "Graves Into Gardens",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Elevation \u00b7 6:41",
+     "icon2": "drag_handle",
+     "note": "Long swipe left removes the row."
+    },
+    {
+     "id": "i28",
+     "kind": "listItem",
+     "label": "Goodness of God",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Bethel Music \u00b7 5:12",
+     "icon2": "drag_handle",
+     "note": ""
+    }
+   ]
+  },
+  {
+   "id": "g32",
+   "x": 508,
+   "y": 480,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i30",
+     "kind": "button",
+     "label": "Playlist",
+     "icon": "playlist_add",
+     "variant": "tonal"
+    },
+    {
+     "id": "i31",
+     "kind": "button",
+     "label": "Remove",
+     "icon": "delete",
+     "variant": "filled"
+    }
+   ]
+  },
+  {
+   "id": "g34",
+   "x": 508,
+   "y": 548,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i33",
+     "kind": "text",
+     "label": "Swipe actions revealed (example row)",
+     "icon": null,
+     "variant": "filled",
+     "size": 14
+    }
+   ]
+  },
+  {
+   "id": "g36",
+   "x": 508,
+   "y": 700,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i35",
+     "kind": "listItem",
+     "label": "Way Maker",
+     "icon": "music_note",
+     "variant": "tonal",
+     "supporting": "Leeland \u00b7 3:12",
+     "icon2": "play_arrow",
+     "action": {
+      "to": "player",
+      "transition": "slideUp"
+     },
+     "note": "Floating glass mini player. Tap opens the player, swipe left/right = next/previous, swipe up = Up next sheet."
+    }
+   ]
+  },
+  {
+   "id": "g38",
+   "x": 492,
+   "y": 788,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i37",
+     "kind": "bottomNav",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "tabs": [
+      {
+       "icon": "search",
+       "label": "Search"
+      },
+      {
+       "icon": "queue_music",
+       "label": "Queue"
+      },
+      {
+       "icon": "history",
+       "label": "History"
+      },
+      {
+       "icon": "download_done",
+       "label": "Saved"
+      },
+      {
+       "icon": "more_horiz",
+       "label": "More"
+      }
+     ],
+     "selected": 1,
+     "actions": {
+      "tab:0": {
+       "to": "search",
+       "transition": "fade"
+      },
+      "tab:1": {
+       "to": "queue",
+       "transition": "fade"
+      }
+     },
+     "note": "Translucent blurred tab bar; badge on Queue."
+    }
+   ]
+  },
+  {
+   "id": "g40",
+   "x": 984,
+   "y": 0,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i39",
+     "kind": "topAppBar",
+     "label": "Now playing",
+     "icon": "keyboard_arrow_down",
+     "variant": "filled",
+     "icon2": "more_horiz",
+     "actions": {
+      "icon": {
+       "to": "back",
+       "transition": "slideDown"
+      }
+     }
+    }
+   ]
+  },
+  {
+   "id": "g42",
+   "x": 984,
+   "y": 88,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i41",
+     "kind": "image",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "size": 412,
+     "note": "16:9 video stage; the fullscreen button opens Fullscreen."
+    }
+   ]
+  },
+  {
+   "id": "g44",
+   "x": 1000,
+   "y": 320,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i43",
+     "kind": "text",
+     "label": "Way Maker",
+     "icon": null,
+     "variant": "filled",
+     "size": 24,
+     "bold": true
+    }
+   ]
+  },
+  {
+   "id": "g46",
+   "x": 1000,
+   "y": 356,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i45",
+     "kind": "text",
+     "label": "Leeland",
+     "icon": null,
+     "variant": "filled",
+     "size": 16
+    }
+   ]
+  },
+  {
+   "id": "g48",
+   "x": 1000,
+   "y": 396,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i47",
+     "kind": "slider",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "value": 35,
+     "note": "Thin seek track, accent fill."
+    }
+   ]
+  },
+  {
+   "id": "g54",
+   "x": 1048,
+   "y": 456,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i49",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "skip_previous",
+     "variant": "text"
+    },
+    {
+     "id": "i50",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "replay_10",
+     "variant": "text"
+    },
+    {
+     "id": "i51",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "play_arrow",
+     "variant": "filled"
+    },
+    {
+     "id": "i52",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "forward_10",
+     "variant": "text"
+    },
+    {
+     "id": "i53",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "skip_next",
+     "variant": "text"
+    }
+   ]
+  },
+  {
+   "id": "g61",
+   "x": 1024,
+   "y": 540,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i55",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "playlist_add",
+     "variant": "text"
+    },
+    {
+     "id": "i56",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "download",
+     "variant": "text"
+    },
+    {
+     "id": "i57",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "lyrics",
+     "variant": "text"
+    },
+    {
+     "id": "i58",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "share",
+     "variant": "text"
+    },
+    {
+     "id": "i59",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "fullscreen",
+     "variant": "text",
+     "action": {
+      "to": "fullscreen",
+      "transition": "expand"
+     }
+    },
+    {
+     "id": "i60",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "more_horiz",
+     "variant": "text"
+    }
+   ]
+  },
+  {
+   "id": "g63",
+   "x": 984,
+   "y": 788,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i62",
+     "kind": "bottomNav",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "tabs": [
+      {
+       "icon": "search",
+       "label": "Search"
+      },
+      {
+       "icon": "queue_music",
+       "label": "Queue"
+      },
+      {
+       "icon": "history",
+       "label": "History"
+      },
+      {
+       "icon": "download_done",
+       "label": "Saved"
+      },
+      {
+       "icon": "more_horiz",
+       "label": "More"
+      }
+     ],
+     "selected": 1,
+     "actions": {
+      "tab:0": {
+       "to": "search",
+       "transition": "fade"
+      },
+      "tab:1": {
+       "to": "queue",
+       "transition": "fade"
+      }
+     },
+     "note": "Translucent blurred tab bar; badge on Queue."
+    }
+   ]
+  },
+  {
+   "id": "g65",
+   "x": 1476,
+   "y": 0,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i64",
+     "kind": "topAppBar",
+     "label": "Queue",
+     "icon": "menu",
+     "variant": "filled"
+    }
+   ]
+  },
+  {
+   "id": "g67",
+   "x": 1476,
+   "y": 380,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i66",
+     "kind": "box",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "size": 412,
+     "size2": 512,
+     "checked": true,
+     "fill": "surfaceContainerHigh",
+     "note": "F7 sheet with grab handle; backdrop tap closes."
+    }
+   ]
+  },
+  {
+   "id": "g69",
+   "x": 1492,
+   "y": 404,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i68",
+     "kind": "text",
+     "label": "Up next",
+     "icon": null,
+     "variant": "filled",
+     "size": 20,
+     "bold": true
+    }
+   ]
+  },
+  {
+   "id": "g73",
+   "x": 1492,
+   "y": 448,
+   "axis": "y",
+   "items": [
+    {
+     "id": "i70",
+     "kind": "listItem",
+     "label": "Build My Life",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Housefires \u00b7 6:04",
+     "action": {
+      "to": "player",
+      "transition": "fade"
+     }
+    },
+    {
+     "id": "i71",
+     "kind": "listItem",
+     "label": "Graves Into Gardens",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Elevation \u00b7 6:41",
+     "action": {
+      "to": "player",
+      "transition": "fade"
+     }
+    },
+    {
+     "id": "i72",
+     "kind": "listItem",
+     "label": "Goodness of God",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Bethel Music \u00b7 5:12",
+     "action": {
+      "to": "player",
+      "transition": "fade"
+     }
+    }
+   ]
+  },
+  {
+   "id": "g75",
+   "x": 1968,
+   "y": 0,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i74",
+     "kind": "box",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "size": 412,
+     "size2": 892,
+     "fill": "inverseSurface",
+     "note": "Video fills the screen (object-fit cover). Fit/Fill toggle in the controls."
+    }
+   ]
+  },
+  {
+   "id": "g77",
+   "x": 1984,
+   "y": 24,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i76",
+     "kind": "text",
+     "label": "Way Maker \u2014 Leeland",
+     "icon": null,
+     "variant": "filled",
+     "size": 14
+    }
+   ]
+  },
+  {
+   "id": "g79",
+   "x": 2316,
+   "y": 12,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i78",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "fullscreen_exit",
+     "variant": "text",
+     "action": {
+      "to": "player",
+      "transition": "fade"
+     }
+    }
+   ]
+  },
+  {
+   "id": "g81",
+   "x": 1984,
+   "y": 790,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i80",
+     "kind": "slider",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "value": 35
+    }
+   ]
+  },
+  {
+   "id": "g85",
+   "x": 1984,
+   "y": 828,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i82",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "pause",
+     "variant": "text"
+    },
+    {
+     "id": "i83",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "screen_rotation",
+     "variant": "text"
+    },
+    {
+     "id": "i84",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "fit_screen",
+     "variant": "text",
+     "note": "Fit \u2194 Fill."
+    }
+   ]
+  }
+ ]
+}

docs/design/f7-swipe-light.json

@@ -0,0 +1,904 @@
+{
+ "title": "YT Player \u2014 Framework7 Swipe (light)",
+ "brief": "Ad-free YouTube/worship player PWA. Framework7 iOS-style layout with swipe gestures, built on the app's own tokens.",
+ "frame": "phone",
+ "platform": "web",
+ "paletteKey": "coral",
+ "theme": {
+  "dark": false,
+  "bothModes": true,
+  "contrast": "standard",
+  "shape": "rounded",
+  "font": "system",
+  "emphasized": false,
+  "motion": "expressive"
+ },
+ "frames": [
+  {
+   "id": "search",
+   "name": "Search",
+   "x": 0,
+   "y": 0,
+   "note": "Home + search results. Big title, rounded search field, results as an inset grouped list.",
+   "swipe": {
+    "left": "queue"
+   }
+  },
+  {
+   "id": "queue",
+   "name": "Queue",
+   "x": 492,
+   "y": 0,
+   "note": "Queued songs. Swipe a row left for Playlist/Remove (long swipe removes), right for Queue. Swipe sideways on empty space to change tab.",
+   "swipe": {
+    "right": "search"
+   }
+  },
+  {
+   "id": "player",
+   "name": "Now playing",
+   "x": 984,
+   "y": 0,
+   "note": "Video on top, Apple Music\u2013style transport, icon action row. Swipe down to collapse to the mini player.",
+   "swipe": {
+    "down": "queue"
+   }
+  },
+  {
+   "id": "upnext",
+   "name": "Up next",
+   "x": 1476,
+   "y": 0,
+   "note": "Bottom sheet opened by swiping up on the mini player. Half height, drag up for full, down to close."
+  },
+  {
+   "id": "fullscreen",
+   "name": "Fullscreen",
+   "x": 1968,
+   "y": 0,
+   "note": "Edge-to-edge video (Fill by default). Minimal icon-only controls over a soft bottom gradient; auto-hide.",
+   "bg": "inverseSurface"
+  }
+ ],
+ "groups": [
+  {
+   "id": "g2",
+   "x": 0,
+   "y": 0,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i1",
+     "kind": "topAppBar",
+     "label": "Search",
+     "icon": "menu",
+     "variant": "filled",
+     "icon2": "directions_car",
+     "note": "Translucent navbar; menu opens the sidebar (also left-edge swipe)."
+    }
+   ]
+  },
+  {
+   "id": "g4",
+   "x": 16,
+   "y": 96,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i3",
+     "kind": "searchBar",
+     "label": "Search YouTube",
+     "icon": null,
+     "variant": "filled",
+     "icon2": "mic",
+     "note": "Rounded F7 searchbar with inline mic; Enter searches."
+    }
+   ]
+  },
+  {
+   "id": "g8",
+   "x": 16,
+   "y": 164,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i5",
+     "kind": "chip",
+     "label": "lofi beats",
+     "icon": null,
+     "variant": "filled"
+    },
+    {
+     "id": "i6",
+     "kind": "chip",
+     "label": "live news",
+     "icon": null,
+     "variant": "filled"
+    },
+    {
+     "id": "i7",
+     "kind": "chip",
+     "label": "worship",
+     "icon": null,
+     "variant": "filled"
+    }
+   ]
+  },
+  {
+   "id": "g10",
+   "x": 16,
+   "y": 212,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i9",
+     "kind": "text",
+     "label": "Results",
+     "icon": null,
+     "variant": "filled",
+     "size": 28,
+     "bold": true
+    }
+   ]
+  },
+  {
+   "id": "g15",
+   "x": 16,
+   "y": 260,
+   "axis": "y",
+   "items": [
+    {
+     "id": "i11",
+     "kind": "listItem",
+     "label": "Goodness of God",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Bethel Music \u00b7 5:12",
+     "icon2": "more_horiz",
+     "action": {
+      "to": "player",
+      "transition": "slide"
+     }
+    },
+    {
+     "id": "i12",
+     "kind": "listItem",
+     "label": "Way Maker",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Leeland \u00b7 3:12",
+     "icon2": "more_horiz",
+     "action": {
+      "to": "player",
+      "transition": "slide"
+     }
+    },
+    {
+     "id": "i13",
+     "kind": "listItem",
+     "label": "Build My Life",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Housefires \u00b7 6:04",
+     "icon2": "more_horiz",
+     "action": {
+      "to": "player",
+      "transition": "slide"
+     }
+    },
+    {
+     "id": "i14",
+     "kind": "listItem",
+     "label": "Graves Into Gardens",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Elevation \u00b7 6:41",
+     "icon2": "more_horiz",
+     "action": {
+      "to": "player",
+      "transition": "slide"
+     }
+    }
+   ]
+  },
+  {
+   "id": "g17",
+   "x": 16,
+   "y": 700,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i16",
+     "kind": "listItem",
+     "label": "Way Maker",
+     "icon": "music_note",
+     "variant": "tonal",
+     "supporting": "Leeland \u00b7 3:12",
+     "icon2": "play_arrow",
+     "action": {
+      "to": "player",
+      "transition": "slideUp"
+     },
+     "note": "Floating glass mini player. Tap opens the player, swipe left/right = next/previous, swipe up = Up next sheet."
+    }
+   ]
+  },
+  {
+   "id": "g19",
+   "x": 0,
+   "y": 788,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i18",
+     "kind": "bottomNav",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "tabs": [
+      {
+       "icon": "search",
+       "label": "Search"
+      },
+      {
+       "icon": "queue_music",
+       "label": "Queue"
+      },
+      {
+       "icon": "history",
+       "label": "History"
+      },
+      {
+       "icon": "download_done",
+       "label": "Saved"
+      },
+      {
+       "icon": "more_horiz",
+       "label": "More"
+      }
+     ],
+     "selected": 0,
+     "actions": {
+      "tab:0": {
+       "to": "search",
+       "transition": "fade"
+      },
+      "tab:1": {
+       "to": "queue",
+       "transition": "fade"
+      }
+     },
+     "note": "Translucent blurred tab bar; badge on Queue."
+    }
+   ]
+  },
+  {
+   "id": "g21",
+   "x": 492,
+   "y": 0,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i20",
+     "kind": "topAppBar",
+     "label": "Queue",
+     "icon": "menu",
+     "variant": "filled",
+     "icon2": "checklist"
+    }
+   ]
+  },
+  {
+   "id": "g24",
+   "x": 508,
+   "y": 96,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i22",
+     "kind": "button",
+     "label": "Play queue",
+     "icon": "play_arrow",
+     "variant": "filled",
+     "size": 182
+    },
+    {
+     "id": "i23",
+     "kind": "button",
+     "label": "Clear",
+     "icon": "clear_all",
+     "variant": "tonal",
+     "size": 182
+    }
+   ]
+  },
+  {
+   "id": "g29",
+   "x": 508,
+   "y": 168,
+   "axis": "y",
+   "items": [
+    {
+     "id": "i25",
+     "kind": "listItem",
+     "label": "Way Maker",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Leeland \u00b7 3:12",
+     "icon2": "drag_handle",
+     "note": "Swipe right \u2192 Queue (accent action)."
+    },
+    {
+     "id": "i26",
+     "kind": "listItem",
+     "label": "Build My Life",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Housefires \u00b7 6:04",
+     "icon2": "drag_handle",
+     "note": "Swipe left \u2192 Playlist + Remove pills."
+    },
+    {
+     "id": "i27",
+     "kind": "listItem",
+     "label": "Graves Into Gardens",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Elevation \u00b7 6:41",
+     "icon2": "drag_handle",
+     "note": "Long swipe left removes the row."
+    },
+    {
+     "id": "i28",
+     "kind": "listItem",
+     "label": "Goodness of God",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Bethel Music \u00b7 5:12",
+     "icon2": "drag_handle",
+     "note": ""
+    }
+   ]
+  },
+  {
+   "id": "g32",
+   "x": 508,
+   "y": 480,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i30",
+     "kind": "button",
+     "label": "Playlist",
+     "icon": "playlist_add",
+     "variant": "tonal"
+    },
+    {
+     "id": "i31",
+     "kind": "button",
+     "label": "Remove",
+     "icon": "delete",
+     "variant": "filled"
+    }
+   ]
+  },
+  {
+   "id": "g34",
+   "x": 508,
+   "y": 548,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i33",
+     "kind": "text",
+     "label": "Swipe actions revealed (example row)",
+     "icon": null,
+     "variant": "filled",
+     "size": 14
+    }
+   ]
+  },
+  {
+   "id": "g36",
+   "x": 508,
+   "y": 700,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i35",
+     "kind": "listItem",
+     "label": "Way Maker",
+     "icon": "music_note",
+     "variant": "tonal",
+     "supporting": "Leeland \u00b7 3:12",
+     "icon2": "play_arrow",
+     "action": {
+      "to": "player",
+      "transition": "slideUp"
+     },
+     "note": "Floating glass mini player. Tap opens the player, swipe left/right = next/previous, swipe up = Up next sheet."
+    }
+   ]
+  },
+  {
+   "id": "g38",
+   "x": 492,
+   "y": 788,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i37",
+     "kind": "bottomNav",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "tabs": [
+      {
+       "icon": "search",
+       "label": "Search"
+      },
+      {
+       "icon": "queue_music",
+       "label": "Queue"
+      },
+      {
+       "icon": "history",
+       "label": "History"
+      },
+      {
+       "icon": "download_done",
+       "label": "Saved"
+      },
+      {
+       "icon": "more_horiz",
+       "label": "More"
+      }
+     ],
+     "selected": 1,
+     "actions": {
+      "tab:0": {
+       "to": "search",
+       "transition": "fade"
+      },
+      "tab:1": {
+       "to": "queue",
+       "transition": "fade"
+      }
+     },
+     "note": "Translucent blurred tab bar; badge on Queue."
+    }
+   ]
+  },
+  {
+   "id": "g40",
+   "x": 984,
+   "y": 0,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i39",
+     "kind": "topAppBar",
+     "label": "Now playing",
+     "icon": "keyboard_arrow_down",
+     "variant": "filled",
+     "icon2": "more_horiz",
+     "actions": {
+      "icon": {
+       "to": "back",
+       "transition": "slideDown"
+      }
+     }
+    }
+   ]
+  },
+  {
+   "id": "g42",
+   "x": 984,
+   "y": 88,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i41",
+     "kind": "image",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "size": 412,
+     "note": "16:9 video stage; the fullscreen button opens Fullscreen."
+    }
+   ]
+  },
+  {
+   "id": "g44",
+   "x": 1000,
+   "y": 320,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i43",
+     "kind": "text",
+     "label": "Way Maker",
+     "icon": null,
+     "variant": "filled",
+     "size": 24,
+     "bold": true
+    }
+   ]
+  },
+  {
+   "id": "g46",
+   "x": 1000,
+   "y": 356,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i45",
+     "kind": "text",
+     "label": "Leeland",
+     "icon": null,
+     "variant": "filled",
+     "size": 16
+    }
+   ]
+  },
+  {
+   "id": "g48",
+   "x": 1000,
+   "y": 396,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i47",
+     "kind": "slider",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "value": 35,
+     "note": "Thin seek track, accent fill."
+    }
+   ]
+  },
+  {
+   "id": "g54",
+   "x": 1048,
+   "y": 456,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i49",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "skip_previous",
+     "variant": "text"
+    },
+    {
+     "id": "i50",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "replay_10",
+     "variant": "text"
+    },
+    {
+     "id": "i51",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "play_arrow",
+     "variant": "filled"
+    },
+    {
+     "id": "i52",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "forward_10",
+     "variant": "text"
+    },
+    {
+     "id": "i53",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "skip_next",
+     "variant": "text"
+    }
+   ]
+  },
+  {
+   "id": "g61",
+   "x": 1024,
+   "y": 540,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i55",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "playlist_add",
+     "variant": "text"
+    },
+    {
+     "id": "i56",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "download",
+     "variant": "text"
+    },
+    {
+     "id": "i57",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "lyrics",
+     "variant": "text"
+    },
+    {
+     "id": "i58",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "share",
+     "variant": "text"
+    },
+    {
+     "id": "i59",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "fullscreen",
+     "variant": "text",
+     "action": {
+      "to": "fullscreen",
+      "transition": "expand"
+     }
+    },
+    {
+     "id": "i60",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "more_horiz",
+     "variant": "text"
+    }
+   ]
+  },
+  {
+   "id": "g63",
+   "x": 984,
+   "y": 788,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i62",
+     "kind": "bottomNav",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "tabs": [
+      {
+       "icon": "search",
+       "label": "Search"
+      },
+      {
+       "icon": "queue_music",
+       "label": "Queue"
+      },
+      {
+       "icon": "history",
+       "label": "History"
+      },
+      {
+       "icon": "download_done",
+       "label": "Saved"
+      },
+      {
+       "icon": "more_horiz",
+       "label": "More"
+      }
+     ],
+     "selected": 1,
+     "actions": {
+      "tab:0": {
+       "to": "search",
+       "transition": "fade"
+      },
+      "tab:1": {
+       "to": "queue",
+       "transition": "fade"
+      }
+     },
+     "note": "Translucent blurred tab bar; badge on Queue."
+    }
+   ]
+  },
+  {
+   "id": "g65",
+   "x": 1476,
+   "y": 0,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i64",
+     "kind": "topAppBar",
+     "label": "Queue",
+     "icon": "menu",
+     "variant": "filled"
+    }
+   ]
+  },
+  {
+   "id": "g67",
+   "x": 1476,
+   "y": 380,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i66",
+     "kind": "box",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "size": 412,
+     "size2": 512,
+     "checked": true,
+     "fill": "surfaceContainerHigh",
+     "note": "F7 sheet with grab handle; backdrop tap closes."
+    }
+   ]
+  },
+  {
+   "id": "g69",
+   "x": 1492,
+   "y": 404,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i68",
+     "kind": "text",
+     "label": "Up next",
+     "icon": null,
+     "variant": "filled",
+     "size": 20,
+     "bold": true
+    }
+   ]
+  },
+  {
+   "id": "g73",
+   "x": 1492,
+   "y": 448,
+   "axis": "y",
+   "items": [
+    {
+     "id": "i70",
+     "kind": "listItem",
+     "label": "Build My Life",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Housefires \u00b7 6:04",
+     "action": {
+      "to": "player",
+      "transition": "fade"
+     }
+    },
+    {
+     "id": "i71",
+     "kind": "listItem",
+     "label": "Graves Into Gardens",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Elevation \u00b7 6:41",
+     "action": {
+      "to": "player",
+      "transition": "fade"
+     }
+    },
+    {
+     "id": "i72",
+     "kind": "listItem",
+     "label": "Goodness of God",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Bethel Music \u00b7 5:12",
+     "action": {
+      "to": "player",
+      "transition": "fade"
+     }
+    }
+   ]
+  },
+  {
+   "id": "g75",
+   "x": 1968,
+   "y": 0,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i74",
+     "kind": "box",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "size": 412,
+     "size2": 892,
+     "fill": "inverseSurface",
+     "note": "Video fills the screen (object-fit cover). Fit/Fill toggle in the controls."
+    }
+   ]
+  },
+  {
+   "id": "g77",
+   "x": 1984,
+   "y": 24,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i76",
+     "kind": "text",
+     "label": "Way Maker \u2014 Leeland",
+     "icon": null,
+     "variant": "filled",
+     "size": 14
+    }
+   ]
+  },
+  {
+   "id": "g79",
+   "x": 2316,
+   "y": 12,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i78",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "fullscreen_exit",
+     "variant": "text",
+     "action": {
+      "to": "player",
+      "transition": "fade"
+     }
+    }
+   ]
+  },
+  {
+   "id": "g81",
+   "x": 1984,
+   "y": 790,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i80",
+     "kind": "slider",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "value": 35
+    }
+   ]
+  },
+  {
+   "id": "g85",
+   "x": 1984,
+   "y": 828,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i82",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "pause",
+     "variant": "text"
+    },
+    {
+     "id": "i83",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "screen_rotation",
+     "variant": "text"
+    },
+    {
+     "id": "i84",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "fit_screen",
+     "variant": "text",
+     "note": "Fit \u2194 Fill."
+    }
+   ]
+  }
+ ]
+}

docs/design/f7-swipe.json

@@ -0,0 +1,904 @@
+{
+ "title": "YT Player \u2014 Framework7 Swipe",
+ "brief": "Ad-free YouTube/worship player PWA. Framework7 iOS-style layout with swipe gestures, built on the app's own tokens.",
+ "frame": "phone",
+ "platform": "web",
+ "paletteKey": "coral",
+ "theme": {
+  "dark": true,
+  "bothModes": true,
+  "contrast": "standard",
+  "shape": "rounded",
+  "font": "system",
+  "emphasized": false,
+  "motion": "expressive"
+ },
+ "frames": [
+  {
+   "id": "search",
+   "name": "Search",
+   "x": 0,
+   "y": 0,
+   "note": "Home + search results. Big title, rounded search field, results as an inset grouped list.",
+   "swipe": {
+    "left": "queue"
+   }
+  },
+  {
+   "id": "queue",
+   "name": "Queue",
+   "x": 492,
+   "y": 0,
+   "note": "Queued songs. Swipe a row left for Playlist/Remove (long swipe removes), right for Queue. Swipe sideways on empty space to change tab.",
+   "swipe": {
+    "right": "search"
+   }
+  },
+  {
+   "id": "player",
+   "name": "Now playing",
+   "x": 984,
+   "y": 0,
+   "note": "Video on top, Apple Music\u2013style transport, icon action row. Swipe down to collapse to the mini player.",
+   "swipe": {
+    "down": "queue"
+   }
+  },
+  {
+   "id": "upnext",
+   "name": "Up next",
+   "x": 1476,
+   "y": 0,
+   "note": "Bottom sheet opened by swiping up on the mini player. Half height, drag up for full, down to close."
+  },
+  {
+   "id": "fullscreen",
+   "name": "Fullscreen",
+   "x": 1968,
+   "y": 0,
+   "note": "Edge-to-edge video (Fill by default). Minimal icon-only controls over a soft bottom gradient; auto-hide.",
+   "bg": "inverseSurface"
+  }
+ ],
+ "groups": [
+  {
+   "id": "g2",
+   "x": 0,
+   "y": 0,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i1",
+     "kind": "topAppBar",
+     "label": "Search",
+     "icon": "menu",
+     "variant": "filled",
+     "icon2": "directions_car",
+     "note": "Translucent navbar; menu opens the sidebar (also left-edge swipe)."
+    }
+   ]
+  },
+  {
+   "id": "g4",
+   "x": 16,
+   "y": 96,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i3",
+     "kind": "searchBar",
+     "label": "Search YouTube",
+     "icon": null,
+     "variant": "filled",
+     "icon2": "mic",
+     "note": "Rounded F7 searchbar with inline mic; Enter searches."
+    }
+   ]
+  },
+  {
+   "id": "g8",
+   "x": 16,
+   "y": 164,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i5",
+     "kind": "chip",
+     "label": "lofi beats",
+     "icon": null,
+     "variant": "filled"
+    },
+    {
+     "id": "i6",
+     "kind": "chip",
+     "label": "live news",
+     "icon": null,
+     "variant": "filled"
+    },
+    {
+     "id": "i7",
+     "kind": "chip",
+     "label": "worship",
+     "icon": null,
+     "variant": "filled"
+    }
+   ]
+  },
+  {
+   "id": "g10",
+   "x": 16,
+   "y": 212,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i9",
+     "kind": "text",
+     "label": "Results",
+     "icon": null,
+     "variant": "filled",
+     "size": 28,
+     "bold": true
+    }
+   ]
+  },
+  {
+   "id": "g15",
+   "x": 16,
+   "y": 260,
+   "axis": "y",
+   "items": [
+    {
+     "id": "i11",
+     "kind": "listItem",
+     "label": "Goodness of God",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Bethel Music \u00b7 5:12",
+     "icon2": "more_horiz",
+     "action": {
+      "to": "player",
+      "transition": "slide"
+     }
+    },
+    {
+     "id": "i12",
+     "kind": "listItem",
+     "label": "Way Maker",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Leeland \u00b7 3:12",
+     "icon2": "more_horiz",
+     "action": {
+      "to": "player",
+      "transition": "slide"
+     }
+    },
+    {
+     "id": "i13",
+     "kind": "listItem",
+     "label": "Build My Life",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Housefires \u00b7 6:04",
+     "icon2": "more_horiz",
+     "action": {
+      "to": "player",
+      "transition": "slide"
+     }
+    },
+    {
+     "id": "i14",
+     "kind": "listItem",
+     "label": "Graves Into Gardens",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Elevation \u00b7 6:41",
+     "icon2": "more_horiz",
+     "action": {
+      "to": "player",
+      "transition": "slide"
+     }
+    }
+   ]
+  },
+  {
+   "id": "g17",
+   "x": 16,
+   "y": 700,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i16",
+     "kind": "listItem",
+     "label": "Way Maker",
+     "icon": "music_note",
+     "variant": "tonal",
+     "supporting": "Leeland \u00b7 3:12",
+     "icon2": "play_arrow",
+     "action": {
+      "to": "player",
+      "transition": "slideUp"
+     },
+     "note": "Floating glass mini player. Tap opens the player, swipe left/right = next/previous, swipe up = Up next sheet."
+    }
+   ]
+  },
+  {
+   "id": "g19",
+   "x": 0,
+   "y": 788,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i18",
+     "kind": "bottomNav",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "tabs": [
+      {
+       "icon": "search",
+       "label": "Search"
+      },
+      {
+       "icon": "queue_music",
+       "label": "Queue"
+      },
+      {
+       "icon": "history",
+       "label": "History"
+      },
+      {
+       "icon": "download_done",
+       "label": "Saved"
+      },
+      {
+       "icon": "more_horiz",
+       "label": "More"
+      }
+     ],
+     "selected": 0,
+     "actions": {
+      "tab:0": {
+       "to": "search",
+       "transition": "fade"
+      },
+      "tab:1": {
+       "to": "queue",
+       "transition": "fade"
+      }
+     },
+     "note": "Translucent blurred tab bar; badge on Queue."
+    }
+   ]
+  },
+  {
+   "id": "g21",
+   "x": 492,
+   "y": 0,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i20",
+     "kind": "topAppBar",
+     "label": "Queue",
+     "icon": "menu",
+     "variant": "filled",
+     "icon2": "checklist"
+    }
+   ]
+  },
+  {
+   "id": "g24",
+   "x": 508,
+   "y": 96,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i22",
+     "kind": "button",
+     "label": "Play queue",
+     "icon": "play_arrow",
+     "variant": "filled",
+     "size": 182
+    },
+    {
+     "id": "i23",
+     "kind": "button",
+     "label": "Clear",
+     "icon": "clear_all",
+     "variant": "tonal",
+     "size": 182
+    }
+   ]
+  },
+  {
+   "id": "g29",
+   "x": 508,
+   "y": 168,
+   "axis": "y",
+   "items": [
+    {
+     "id": "i25",
+     "kind": "listItem",
+     "label": "Way Maker",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Leeland \u00b7 3:12",
+     "icon2": "drag_handle",
+     "note": "Swipe right \u2192 Queue (accent action)."
+    },
+    {
+     "id": "i26",
+     "kind": "listItem",
+     "label": "Build My Life",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Housefires \u00b7 6:04",
+     "icon2": "drag_handle",
+     "note": "Swipe left \u2192 Playlist + Remove pills."
+    },
+    {
+     "id": "i27",
+     "kind": "listItem",
+     "label": "Graves Into Gardens",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Elevation \u00b7 6:41",
+     "icon2": "drag_handle",
+     "note": "Long swipe left removes the row."
+    },
+    {
+     "id": "i28",
+     "kind": "listItem",
+     "label": "Goodness of God",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Bethel Music \u00b7 5:12",
+     "icon2": "drag_handle",
+     "note": ""
+    }
+   ]
+  },
+  {
+   "id": "g32",
+   "x": 508,
+   "y": 480,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i30",
+     "kind": "button",
+     "label": "Playlist",
+     "icon": "playlist_add",
+     "variant": "tonal"
+    },
+    {
+     "id": "i31",
+     "kind": "button",
+     "label": "Remove",
+     "icon": "delete",
+     "variant": "filled"
+    }
+   ]
+  },
+  {
+   "id": "g34",
+   "x": 508,
+   "y": 548,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i33",
+     "kind": "text",
+     "label": "Swipe actions revealed (example row)",
+     "icon": null,
+     "variant": "filled",
+     "size": 14
+    }
+   ]
+  },
+  {
+   "id": "g36",
+   "x": 508,
+   "y": 700,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i35",
+     "kind": "listItem",
+     "label": "Way Maker",
+     "icon": "music_note",
+     "variant": "tonal",
+     "supporting": "Leeland \u00b7 3:12",
+     "icon2": "play_arrow",
+     "action": {
+      "to": "player",
+      "transition": "slideUp"
+     },
+     "note": "Floating glass mini player. Tap opens the player, swipe left/right = next/previous, swipe up = Up next sheet."
+    }
+   ]
+  },
+  {
+   "id": "g38",
+   "x": 492,
+   "y": 788,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i37",
+     "kind": "bottomNav",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "tabs": [
+      {
+       "icon": "search",
+       "label": "Search"
+      },
+      {
+       "icon": "queue_music",
+       "label": "Queue"
+      },
+      {
+       "icon": "history",
+       "label": "History"
+      },
+      {
+       "icon": "download_done",
+       "label": "Saved"
+      },
+      {
+       "icon": "more_horiz",
+       "label": "More"
+      }
+     ],
+     "selected": 1,
+     "actions": {
+      "tab:0": {
+       "to": "search",
+       "transition": "fade"
+      },
+      "tab:1": {
+       "to": "queue",
+       "transition": "fade"
+      }
+     },
+     "note": "Translucent blurred tab bar; badge on Queue."
+    }
+   ]
+  },
+  {
+   "id": "g40",
+   "x": 984,
+   "y": 0,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i39",
+     "kind": "topAppBar",
+     "label": "Now playing",
+     "icon": "keyboard_arrow_down",
+     "variant": "filled",
+     "icon2": "more_horiz",
+     "actions": {
+      "icon": {
+       "to": "back",
+       "transition": "slideDown"
+      }
+     }
+    }
+   ]
+  },
+  {
+   "id": "g42",
+   "x": 984,
+   "y": 88,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i41",
+     "kind": "image",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "size": 412,
+     "note": "16:9 video stage; the fullscreen button opens Fullscreen."
+    }
+   ]
+  },
+  {
+   "id": "g44",
+   "x": 1000,
+   "y": 320,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i43",
+     "kind": "text",
+     "label": "Way Maker",
+     "icon": null,
+     "variant": "filled",
+     "size": 24,
+     "bold": true
+    }
+   ]
+  },
+  {
+   "id": "g46",
+   "x": 1000,
+   "y": 356,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i45",
+     "kind": "text",
+     "label": "Leeland",
+     "icon": null,
+     "variant": "filled",
+     "size": 16
+    }
+   ]
+  },
+  {
+   "id": "g48",
+   "x": 1000,
+   "y": 396,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i47",
+     "kind": "slider",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "value": 35,
+     "note": "Thin seek track, accent fill."
+    }
+   ]
+  },
+  {
+   "id": "g54",
+   "x": 1048,
+   "y": 456,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i49",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "skip_previous",
+     "variant": "text"
+    },
+    {
+     "id": "i50",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "replay_10",
+     "variant": "text"
+    },
+    {
+     "id": "i51",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "play_arrow",
+     "variant": "filled"
+    },
+    {
+     "id": "i52",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "forward_10",
+     "variant": "text"
+    },
+    {
+     "id": "i53",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "skip_next",
+     "variant": "text"
+    }
+   ]
+  },
+  {
+   "id": "g61",
+   "x": 1024,
+   "y": 540,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i55",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "playlist_add",
+     "variant": "text"
+    },
+    {
+     "id": "i56",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "download",
+     "variant": "text"
+    },
+    {
+     "id": "i57",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "lyrics",
+     "variant": "text"
+    },
+    {
+     "id": "i58",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "share",
+     "variant": "text"
+    },
+    {
+     "id": "i59",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "fullscreen",
+     "variant": "text",
+     "action": {
+      "to": "fullscreen",
+      "transition": "expand"
+     }
+    },
+    {
+     "id": "i60",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "more_horiz",
+     "variant": "text"
+    }
+   ]
+  },
+  {
+   "id": "g63",
+   "x": 984,
+   "y": 788,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i62",
+     "kind": "bottomNav",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "tabs": [
+      {
+       "icon": "search",
+       "label": "Search"
+      },
+      {
+       "icon": "queue_music",
+       "label": "Queue"
+      },
+      {
+       "icon": "history",
+       "label": "History"
+      },
+      {
+       "icon": "download_done",
+       "label": "Saved"
+      },
+      {
+       "icon": "more_horiz",
+       "label": "More"
+      }
+     ],
+     "selected": 1,
+     "actions": {
+      "tab:0": {
+       "to": "search",
+       "transition": "fade"
+      },
+      "tab:1": {
+       "to": "queue",
+       "transition": "fade"
+      }
+     },
+     "note": "Translucent blurred tab bar; badge on Queue."
+    }
+   ]
+  },
+  {
+   "id": "g65",
+   "x": 1476,
+   "y": 0,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i64",
+     "kind": "topAppBar",
+     "label": "Queue",
+     "icon": "menu",
+     "variant": "filled"
+    }
+   ]
+  },
+  {
+   "id": "g67",
+   "x": 1476,
+   "y": 380,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i66",
+     "kind": "box",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "size": 412,
+     "size2": 512,
+     "checked": true,
+     "fill": "surfaceContainerHigh",
+     "note": "F7 sheet with grab handle; backdrop tap closes."
+    }
+   ]
+  },
+  {
+   "id": "g69",
+   "x": 1492,
+   "y": 404,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i68",
+     "kind": "text",
+     "label": "Up next",
+     "icon": null,
+     "variant": "filled",
+     "size": 20,
+     "bold": true
+    }
+   ]
+  },
+  {
+   "id": "g73",
+   "x": 1492,
+   "y": 448,
+   "axis": "y",
+   "items": [
+    {
+     "id": "i70",
+     "kind": "listItem",
+     "label": "Build My Life",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Housefires \u00b7 6:04",
+     "action": {
+      "to": "player",
+      "transition": "fade"
+     }
+    },
+    {
+     "id": "i71",
+     "kind": "listItem",
+     "label": "Graves Into Gardens",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Elevation \u00b7 6:41",
+     "action": {
+      "to": "player",
+      "transition": "fade"
+     }
+    },
+    {
+     "id": "i72",
+     "kind": "listItem",
+     "label": "Goodness of God",
+     "icon": "smart_display",
+     "variant": "filled",
+     "supporting": "Bethel Music \u00b7 5:12",
+     "action": {
+      "to": "player",
+      "transition": "fade"
+     }
+    }
+   ]
+  },
+  {
+   "id": "g75",
+   "x": 1968,
+   "y": 0,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i74",
+     "kind": "box",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "size": 412,
+     "size2": 892,
+     "fill": "inverseSurface",
+     "note": "Video fills the screen (object-fit cover). Fit/Fill toggle in the controls."
+    }
+   ]
+  },
+  {
+   "id": "g77",
+   "x": 1984,
+   "y": 24,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i76",
+     "kind": "text",
+     "label": "Way Maker \u2014 Leeland",
+     "icon": null,
+     "variant": "filled",
+     "size": 14
+    }
+   ]
+  },
+  {
+   "id": "g79",
+   "x": 2316,
+   "y": 12,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i78",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "fullscreen_exit",
+     "variant": "text",
+     "action": {
+      "to": "player",
+      "transition": "fade"
+     }
+    }
+   ]
+  },
+  {
+   "id": "g81",
+   "x": 1984,
+   "y": 790,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i80",
+     "kind": "slider",
+     "label": "",
+     "icon": null,
+     "variant": "filled",
+     "value": 35
+    }
+   ]
+  },
+  {
+   "id": "g85",
+   "x": 1984,
+   "y": 828,
+   "axis": "x",
+   "items": [
+    {
+     "id": "i82",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "pause",
+     "variant": "text"
+    },
+    {
+     "id": "i83",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "screen_rotation",
+     "variant": "text"
+    },
+    {
+     "id": "i84",
+     "kind": "iconButton",
+     "label": "",
+     "icon": "fit_screen",
+     "variant": "text",
+     "note": "Fit \u2194 Fill."
+    }
+   ]
+  }
+ ]
+}

docs/device-play-backfill.md

@@ -0,0 +1,11 @@
+# Backfill songs played from device storage
+
+A web player's first actual playback of a YouTube video in a session reports its known title, artist/channel, duration and thumbnail to `POST /api/media/:id/meta`. Local OPFS playback therefore no longer depends on `/api/streams` being called. Offline plays are held in memory until the browser returns online. Uploads and edited copies are excluded. Playback never waits for the report.
+
+The server accepts only 11-character YouTube IDs, bounded strings, numeric duration and approved HTTPS YouTube artwork (local catalog artwork maps to the canonical thumbnail). Bodies are capped at 8 KB. Reports are limited to 20 per IP per minute and 100 globally, with a maximum of 32 outstanding backfill fetches. A response contains `{ok, known, cache}`; `known` describes whether a media row existed before the report, and `cache` is ready, queued, downloading, validating, unavailable or busy. Metadata can be registered even when the cache volume is offline or the queue is busy.
+
+Device hints fill missing media fields with an atomic SQLite merge; existing titles, artists, durations, art and richer metadata are retained. Catalog ingestion also fills gaps and queues the existing bounded thumbnail collector. Admin's song list includes metadata-only entries, so its lyric tools have a title and artist before downloading completes. Inclusion in that list does not imply cached media is ready; `cacheStatus` reports the actual state.
+
+Missing copies use the normal low-priority automatic `ensureCached` job, including its deduplication, single fetch lane, yt-dlp path, validation, duration/backoff limits, LRU byte budget, disk guard and USB volume marker. No parallel downloader or cache directory is introduced. Existing copies and in-progress jobs are skipped. Download failure keeps song metadata; the usual cache retry policy applies on later sessions. Offline-volume and busy responses do not force a fetch or bypass safety limits.
+
+Verification: server validation/merge/route tests, admin metadata-only listing test, frontend once-per-session/offline reporter tests, all frontend unit tests, app syntax and server build. On a real phone, play a previously unknown OPFS song, inspect `/api/admin/media`, then verify a normal media-cache job and lyrics lookup. Repeat the play to confirm no second report; also test with the server's cache volume unavailable.

docs/equalizer.md

@@ -0,0 +1,7 @@
+# Equalizer and stereo width
+
+`frontend/eq-core.js` is the single band/preset definition for both live EQ and EqRender: 31, 62, 125, 250, 500, 1000, 2000, 4000, 8000 and 16000 Hz. Existing five-band curves migrate by logarithmic frequency interpolation; edge gains extend to the new endpoints. Migration preserves user curves instead of replacing them with a new preset.
+
+The headphone widener is off by default. It delays the right channel by up to 15 ms (Haas effect); it can colour speaker playback and mono mixes. Live EQ and saved-song renders use the same widener graph, vocal matrix and bands. Render signatures include all three, so changed settings invalidate old processed copies. iPhone streams still require the existing Live sound processing opt-in; saved copies use OfflineAudioContext. A new rendered copy is used on a subsequent playback.
+
+Review with actual headphones and an iPhone: centre image at 0%, mono compatibility at higher values, rendered/live EQ correspondence, and lock-screen playback of saved songs. Model-based separation is outside this feature; see vocal-stems.md.

docs/feature-ideas.md

@@ -0,0 +1,304 @@
+# ytplayer — Feature Ideas & Enhancement Roadmap
+
+> **Status:** Research & Proposed Roadmap  
+> **Target:** Web PWA, Tauri (Windows), zero-native (macOS / Linux)  
+> **Date:** October 2026  
+
+---
+
+## 1. Context & Architecture Baseline
+
+`ytplayer` is an ad-free, privacy-preserving media engine with a dual identity:
+1. **Ad-Free Media Player & Offline PWA**: Built with vanilla JS on the frontend and Bun + Hono on the backend (libsql SQLite database). It uses `yt-dlp` and InnerTube for direct stream extraction without Google accounts, and caches media locally (OPFS in browser, single-file H.264/HEVC faststart on server, WebRTC P2P mesh between devices).
+2. **Live Worship & Stage Performance Tool**: Equipped with **Service Mode** (wake-locked setlist view, auto-scaling lyric fonts, per-song arrangement notes), synchronized LRC lyrics with section/cue tags, and a **Presenter screen** (`/?present=<code>`) with QR pairing.
+
+This document synthesizes high-value feature opportunities gathered from research into modern YouTube frontends (FreeTube, ReVanced, SmartTube, Namida), modern music players (Plexamp, Spotube), and live stage tools (Planning Center Music Stand, OnSong, MultiTracks Playback).
+
+---
+
+## 2. Feature Proposals by Domain
+
+### Domain 1: Smart YouTube & Playback Experience
+
+#### 1.1 SponsorBlock & Non-Music Segment Skipping
+* **The Concept**: Automatically skip or visually mark sponsored segments, self-promos, interaction reminders, and non-music sections.
+* **Why it matters**: Music videos frequently feature skits, prolonged silent pauses, or spoken intros. Skipping `music_offtopic` ensures the music starts immediately.
+* **Technical Path**:
+  * Free, unauthenticated REST API: `GET https://sponsor.ajay.app/api/skipSegments?videoID=<id>&categories=["sponsor","intro","outro","music_offtopic","selfpromo"]`.
+  * Highlight segments as color-coded spans over the seek bar (`#timeline` / Glass Stage scrubber).
+  * During the playback tick in `frontend/app.js`, if `currentTime` enters a skippable segment and auto-skip is enabled in Settings, seek to the segment end and show an "Unskip" toast.
+  * Server media cache can optionally apply `--sponsorblock-mark` during ffmpeg intake.
+
+#### 1.2 Automatic YouTube Chapter Extraction & Interactive Scrubber
+* **The Concept**: Automatically parse video chapters from YouTube metadata and display chapter splits on the progress bar.
+* **Why it matters**: Currently, chapters are only created manually. Full albums, sermons, conference talks, and live sets already have timestamps in video descriptions.
+* **Technical Path**:
+  * In `server/server.js` (`/api/streams`), expose `chapters: [{ start_time, end_time, title }]` directly from InnerTube or `yt-dlp`.
+  * Render tick marks / gaps on the progress scrubber for each chapter boundary.
+  * Display the current chapter title next to the timestamp.
+  * Add keyboard shortcuts: `[` (previous chapter) and `]` (next chapter).
+
+#### 1.3 Return YouTube Dislike (RYD) & Quality Rating
+* **The Concept**: Show community like/dislike ratios and ratings for videos.
+* **Why it matters**: Helps identify misleading arrangements, clickbait, poor audio rips, or broken videos before playback.
+* **Technical Path**:
+  * Query `https://returnyoutubedislikeapi.com/votes?videoId=<id>` (public, CORS-enabled).
+  * Display a discreet like ratio bar or percentage badge on the video card and now-playing details.
+
+#### 1.4 On-Screen Subtitles & Closed Captions (CC) Overlay
+* **The Concept**: Render synchronized captions directly over the video playback stage.
+* **Why it matters**: `ytplayer` currently only uses captions for transcript search or importing into lyrics. Spoken sermons, tutorials, foreign tracks, and non-musical videos need readable on-screen subtitles.
+* **Technical Path**:
+  * Add a `CC` button on the player controls.
+  * Fetch timed lines from `/api/notes/:id/captions`.
+  * Render an HTML overlay synchronized to `Player.master.currentTime` with settings for font size, background opacity, and positioning.
+
+#### 1.5 Silence Skipping (Talk & Sermon Mode)
+* **The Concept**: Automatically speed up or skip past silent gaps in spoken-word media.
+* **Why it matters**: Long sermons, podcasts, and talks often have pauses; skipping silence saves 10–20% of listening time without altering speech tone.
+* **Technical Path**:
+  * Connect an `AnalyserNode` or `AudioWorklet` in the Web Audio graph.
+  * If audio energy (RMS) stays below -45 dB for >800 ms, ramp `playbackRate` to 2.5× until speech resumes.
+
+---
+
+### Domain 2: Audiophile & Music Player Polish
+
+#### 2.1 EBU R128 / LUFS Loudness Normalization
+* **The Concept**: Eliminate jarring volume jumps between tracks in playlists and queues.
+* **Why it matters**: YouTube master volumes vary widely (-24 LUFS to -8 LUFS). Normalization ensures consistent listening levels.
+* **Technical Path**:
+  * When generating waveform peaks in `server/media-cache.js`, run ffmpeg's `ebur128` filter once to measure integrated loudness (LUFS).
+  * Store `lufs` in the database and pass it via `/api/streams` and `/api/media/:id`.
+  * In `frontend/app.js`, apply a Web Audio `GainNode` to normalize tracks to a standard -14 LUFS target.
+
+#### 2.2 Real-Time Pitch Shifting & Independent Tempo Adjustment
+* **The Concept**: Transpose playback key (±6 semitones) without altering tempo, or slow down tempo without changing pitch.
+* **Why it matters**: Singers and worship teams often need to adapt songs to a band's vocal key. Instrumentalists need to slow down fast sections to learn them.
+* **Technical Path**:
+  * Use an AudioWorklet running a Phase Vocoder or `SoundTouchJS` DSP processor.
+  * Provide stepper controls for semitone transposition and tempo percentage (0.5×–1.5×).
+
+#### 2.3 Ambient Glow / Reactive Lighting Mode
+* **The Concept**: A soft dynamic glow behind the video player that mirrors current video colors (similar to YouTube Ambient Mode or Apple Music dynamic art).
+* **Technical Path**:
+  * Render video frames onto an offscreen 16×16 `<canvas>` at ~10 FPS.
+  * Display a blurred canvas (`filter: blur(50px)`) directly behind the player container with smooth CSS opacity.
+  * Auto-disable when `settings.perfMode` is active or under `prefers-reduced-motion`.
+
+#### 2.4 Smart Autoplay Radio / Endless Mix
+* **The Concept**: Keep playing related songs when the active playlist or queue concludes.
+* **Technical Path**:
+  * Fetch candidate related tracks via InnerTube `next` continuity tokens.
+  * Re-rank candidates using the client's local `StatsTrack` (`playCount`, listening duration, and skips) to favor familiar favorites while avoiding immediate repeats.
+
+#### 2.5 Audio Stem Separation & Vocal Attenuator (Karaoke / Rehearsal Mode)
+* **The Concept**: Mute or attenuate lead vocals in real time (`🎤 Vocal: 100% ────● 0%`), or isolate the vocal track for harmony practice.
+* **Why it matters**: Gives singers clean backing tracks for rehearsal and live events even when official minus-one recordings do not exist.
+* **Technical Path**:
+  * Client-side: Run `demucs-onnx` with WebGPU acceleration to process saved OPFS tracks offline.
+  * Server-side: Provide `GET /api/media/:id/stems` (caching `.vocals.m4a` and `.instrumental.m4a` alongside the existing `.m4a` audio sidecar in `server/media-cache.js`).
+  * Frontend: Two synchronized audio elements or Web Audio `GainNode` faders for seamless real-time blending.
+
+#### 2.6 10-Band Graphic Equalizer & Spatial Hall Simulation
+* **The Concept**: Upgrade the existing 5-band filter in `EQ` (`frontend/app.js`) to a full 10-band graphic equalizer with acoustic presets and spatial audio widening.
+* **Technical Path**:
+  * 10 `BiquadFilterNode` bands (31Hz, 62Hz, 125Hz, 250Hz, 500Hz, 1kHz, 2kHz, 4kHz, 8kHz, 16kHz).
+  * Presets: *Vocal Clarity (speech presence boost), Acoustic Warmth, Worship Stage, Bass Punch, and Flat*.
+  * Spatial stereo widener using a Haas-effect micro-delay and `StereoPannerNode` for an immersive headphone soundstage.
+
+---
+
+### Domain 3: Live Worship, Band & Stage Performance Engine
+
+#### 3.1 Interactive ChordPro Sheets & Live Transposition
+* **The Concept**: Display chords inline or above lyrics with 1-tap live transposition and capo calculation.
+* **Why it matters**: Replaces the need for external music stand apps (Planning Center Music Stand, OnSong) on stage.
+* **Technical Path**:
+  * Extend `frontend/lyrics-core.js` to parse ChordPro directives (`[G]`, `[D/F#]`, `{key: G}`).
+  * Add a Transpose controller (+1 / -1 semitone, Capo selector) that dynamically recalculates chord symbols in real time.
+  * Add a view toggle: "Lyrics Only" vs. "Chords & Lyrics".
+
+#### 3.2 Bluetooth Foot Pedal / Page-Turner Support
+* **The Concept**: Hands-free navigation for musicians on stage using standard Bluetooth foot pedals (AirTurn, PageFlip, Donner, Stomp).
+* **Why it matters**: Musicians cannot remove their hands from instruments while playing.
+* **Technical Path**:
+  * Standard foot pedals map to keyboard keys: `PageDown`, `PageUp`, `ArrowUp`, `ArrowDown`.
+  * Extend the global `keydown` listener in `frontend/app.js` to handle pedal events in Service Mode:
+    * `PageDown` / `PageUp`: Scroll down / up by one lyric section.
+    * Configurable actions: Next/Previous track, trigger A-B loop, or jump to Chorus.
+
+#### 3.3 Confidence Monitor & Stage Clock (Presenter Mode)
+* **The Concept**: A high-visibility stage display mode for the Presenter screen (`/?present=<code>`).
+* **Why it matters**: Singers and worship leaders need glanceable cues for upcoming lyrics, section names, and remaining time.
+* **Technical Path**:
+  * In `Presenter` (`frontend/app.js`), provide a **Confidence Monitor** layout:
+    * **Current Line**: Extra-large, high-contrast text.
+    * **Next Line Preview**: Smaller, dimmed text directly underneath.
+    * **Section Badge**: Prominent label (e.g. `# CHORUS 2`).
+    * **Stage Clock & Timer**: Current wall clock plus elapsed/remaining song timer.
+
+#### 3.4 Broadcast Lower-Third Overlay for OBS & Live Streams
+* **The Concept**: A dedicated live stream output URL (`/?present=<code>&mode=lowerthird`) designed to be added as a transparent Browser Source in OBS, vMix, or ATEM.
+* **Why it matters**: Enables churches and streamers to overlay synchronized lower-third lyrics onto their video feed without separate presentation software.
+* **Technical Path**:
+  * Transparent background (`background: transparent;`).
+  * Auto-updating 2-line broadcast graphic with smooth slide/fade transitions and drop-shadows.
+  * Driven in real-time by the host or phone remote via the existing WebSocket relay in `server/remote.js`.
+
+#### 3.5 Section Quick-Jump Pad
+* **The Concept**: A grid of buttons representing song sections (`[Intro]`, `[Verse 1]`, `[Chorus]`, `[Bridge]`, `[Outro]`).
+* **Why it matters**: Worship teams often repeat choruses or spontaneously transition between sections during live services.
+* **Technical Path**:
+  * Parse `# Section` headers from synced lyrics in `frontend/lyrics-core.js`.
+  * Render an arrangement button strip in Service Mode.
+  * Tapping a section immediately seeks playback to that section's start timestamp.
+
+#### 3.6 Hardware MIDI Controller Integration (Web MIDI API)
+* **The Concept**: Direct plug-and-play support for hardware USB/Bluetooth MIDI pedalboards (Morningstar MC3/MC6, Looptimus, Behringer FCB1010) without native drivers.
+* **Technical Path**:
+  * Use the browser `navigator.requestMIDIAccess()` API.
+  * Map MIDI Note-On and CC messages to player actions (Play/Pause, Next Track, Chorus Repeat, Tap Tempo, Mute).
+
+#### 3.7 Planning Center Services (PCO) & SongSelect Setlist Importer
+* **The Concept**: One-click setlist and chord chart importing from Planning Center Services and CCLI SongSelect.
+* **Technical Path**:
+  * Import setlist text or CSV files from PCO.
+  * Auto-match titles with YouTube media, attaching keys (`@ Key E`) and chord sheets directly to playlist entries.
+
+#### 3.8 Bilingual & Phonetic Lyrics (Romanization / Transliteration)
+* **The Concept**: Simultaneous dual-language or phonetic pronunciation lyrics (e.g. Mandarin with Pinyin, Spanish/English).
+* **Technical Path**:
+  * Extend `frontend/lyrics-core.js` to parse secondary translation lines.
+  * Display translations or romanized cues in smaller muted text under the primary lyric line.
+
+#### 3.9 Visual Metronome & Count-In Click
+* **The Concept**: Visual flash or gentle audio click count-in before track playback begins.
+* **Why it matters**: Enables the band to start playing on beat before the recorded track introduces audio.
+* **Technical Path**:
+  * When `@ 70 BPM` metadata is present in song notes, offer an optional 4-beat visual flash on the stage frame or Web Audio click before playback starts.
+
+---
+
+### Domain 4: Interactive Piano Transcription, Sheet Music & Practice Engine
+
+#### 4.1 Automatic Audio-to-Piano Transcription (Polyphonic Audio to Score)
+* **The Concept**: Transcribe piano melodies and chords from recorded audio into polyphonic note events (MIDI / MusicXML).
+* **Why it matters**: Allows musicians, vocalists, and students to learn the exact piano parts played in any YouTube song or uploaded track.
+* **Technical Path**:
+  * **Option A (Client-Side WASM / WebGPU)**: Run Spotify's **Basic Pitch** model (`@spotify/basic-pitch`) in the browser via TensorFlow.js or ONNX Runtime Web. It performs polyphonic pitch prediction directly on decoded audio frames without server compute.
+  * **Option B (Server-Side Worker, like `lyrics-worker`)**: Run ByteDance's `piano_transcription_inference` (High-Resolution Piano Transcription on PyTorch/ONNX) inside a container worker. Saves `<id>.notes.json` / `<id>.mid` to the cache directory.
+  * Output data shape: Array of note events `[{ pitch: 60, start: 1.25, end: 1.85, velocity: 84 }]`.
+
+#### 4.2 Sheet Music Generation & Real-Time Scrolling Score
+* **The Concept**: Convert transcribed note events into standard grand staff sheet music (Treble and Bass clefs) rendered on screen.
+* **Technical Path**:
+  * Render sheet notation on an HTML5 `<canvas>` or `<svg>` using **VexFlow** or **OpenSheetMusicDisplay (OSMD)**.
+  * Display a vertical playhead cursor that scrolls synchronously with `Player.master.currentTime`.
+  * Support instant transposition: adjusting the song key shifts the musical notation and key signature on the fly.
+
+#### 4.3 Interactive Virtual Piano & Falling Notes (Synthesia Style)
+* **The Concept**: A responsive 88-key or 61-key virtual piano keyboard that visualizes which keys to press in sync with playback.
+* **Visual Modes**:
+  * **Falling Notes Mode**: Vertical roll above the keyboard where color-coded note bars fall downward toward the keys (Treble notes in Amber/Coral, Bass notes in Cyan/Blue). When a bar hits the key line, the corresponding piano key illuminates and depresses.
+  * **Sheet Music + Lit Keys Mode**: Traditional score at the top, illuminated keyboard at the bottom highlighting active notes in real time.
+* **Technical Path**:
+  * Canvas-rendered piano keyboard with responsive key sizing that fits desktop, tablet, and mobile orientations.
+  * Note rendering loop tied to `requestAnimationFrame` and driven by the current playback timestamp.
+
+#### 4.4 Queued Song & Section Learning Mode
+* **The Concept**: A dedicated learning queue and practice loop system that guides users step-by-step through mastering a song.
+* **Features**:
+  * **Queue Practice Sessions**: Queue an entire song, specific sections (e.g. `[Intro]`, `[Verse 1]`, `[Chorus]`), or arbitrary A-B loop bars into the practice queue.
+  * **Tempo Slowdown (Pitch-Preserved)**: Slow down playback to 50%, 65%, 75%, or 90% speed without altering key.
+  * **Speed Ramp Auto-Trainer**: Start a looped section at 60% speed; each time the user completes the loop, speed automatically increases by +5% until 100% full tempo is achieved.
+  * **Loop Pause Interval**: A configurable 1–2 beat pause between repetitions to allow players to reset their hand position.
+
+#### 4.5 Interactive "Wait-for-Note" Practice via Hardware MIDI Input
+* **The Concept**: Connect any USB or Bluetooth digital piano / MIDI keyboard to the computer or tablet. The player pauses and waits for the user to press the correct key(s) before advancing!
+* **Technical Path**:
+  * Listen to incoming MIDI `noteon` events via the Web MIDI API (`navigator.requestMIDIAccess()`).
+  * Compare the user's played MIDI note number against active notes in the transcription dataset.
+  * If the note is correct, turn the key green and resume playback to the next note event. If incorrect, turn the key red and provide visual guidance on the virtual keyboard.
+
+#### 4.6 Technical Feasibility Analysis
+
+| Component | Technical Feasibility | Resource Cost & Constraints | Recommendation |
+|:---|:---|:---|:---|
+| **Audio-to-MIDI Transcription** | **High (Proven)** | Basic Pitch: ~15 MB model file, runs on client WebGPU/CPU in ~0.3×–0.8× real time. ByteDance: higher accuracy, requires ~1.5 GB PyTorch model on server. | Use **Basic Pitch (WASM/ONNX)** on client for instant preview; offload to homelab server worker for full-song high-fidelity scores. |
+| **Piano Roll / Virtual Keyboard** | **High (Straightforward)** | Pure HTML5 Canvas rendering. Minimal CPU overhead (~60 FPS with <5% CPU usage). | Built natively into frontend without heavy external dependencies. |
+| **Sheet Music Engraving** | **High (Proven)** | **VexFlow** (~180 KB minified) renders standard grand staff notation cleanly from JSON notes. | Dynamic import (`import()`) of VexFlow only when the user opens Sheet View. |
+| **Interactive MIDI Feedback** | **High (Zero-latency)** | Web MIDI API is supported natively in Chrome, Edge, and Opera (and via polyfill in Firefox/Safari). Latency is sub-5ms. | Native browser event listeners listening to MIDI input. |
+
+---
+
+### Domain 5: Collaboration, Windowing & Mobile Experience
+
+#### 5.1 Document Picture-in-Picture (Always-On-Top Lyrics & Chords)
+* **The Concept**: An always-on-top floating desktop window containing interactive synchronized lyrics, chords, and transport controls.
+* **Technical Path**:
+  * Use the Chrome/Edge `documentPictureInPicture.requestWindow({ width: 420, height: 500 })` API.
+  * Moves the active `#stageLyrics` or ChordPro view into the floating window with full DOM interactivity.
+
+#### 5.2 Voice Search & Driving Car Mode
+* **The Concept**: A hands-free, distraction-free interface for driving or kitchen listening.
+* **Features**:
+  * **Voice Search**: Microphone button on the search bar powered by `webkitSpeechRecognition` for real-time speech-to-query search.
+  * **Car Mode**: One-tap toggle for a simplified layout with giant 100px touch buttons (Play/Pause, Next, Previous, 15s Rewind) and disabled scroll lists.
+
+#### 5.3 Collaborative Setlists & Playlists
+* **The Concept**: Multiple devices editing a single playlist simultaneously with live sync.
+* **Technical Path**:
+  * Extend playlist sync in `server/db.js` with shared write keys.
+  * Broadcast item reordering and song additions over the existing WebSocket hub in `server/party.js`.
+
+#### 5.4 Watch Party DJ Mode & Upvote Queue
+* **The Concept**: Allow guests in a watch party (`/ws/party`) to submit song requests that the group can upvote.
+* **Technical Path**:
+  * Add a "Suggested Queue" tab in the watch party drawer.
+  * Upvotes dynamically sort songs; when current playback finishes, the highest-voted song plays next.
+
+---
+
+### Domain 6: Library, Offline & Sync Innovations
+
+#### 6.1 Visual Download Manager & Storage Dashboard
+* **The Concept**: A unified management dashboard in Settings for offline media.
+* **Technical Path**:
+  * Show active download tasks with real-time progress bars.
+  * List storage usage grouped by playlist, audio vs. video format, and OPFS vs. server cache.
+  * Add controls: "Pause All", "Resume All", and "Retry Failed".
+
+#### 6.2 Smart Auto-Offline Favorites
+* **The Concept**: Keep a user's most essential songs available offline automatically.
+* **Technical Path**:
+  * Setting: *"Keep Top 25 Most-Played Songs Offline"* or *"Keep Active Setlist Offline"*.
+  * Automated background routine checks local `playCount` and triggers cache downloads for missing items during idle time.
+
+#### 6.3 Self-Contained Offline Playlist Bundling (Zip Export)
+* **The Concept**: Export a full offline bundle containing playlist JSON plus the saved audio/video files for complete air-gapped device migration.
+
+---
+
+## 3. Implementation Matrix & Recommended Phases
+
+| Phase | Feature | Effort | Prerequisites & Reused Modules |
+|:---|:---|:---:|:---|
+| **Phase 1: Quick Wins** | **SponsorBlock & Non-Music Skip** | Low | Free SponsorBlock API, playback tick in `frontend/app.js` |
+| | **Automatic YouTube Chapter Ticks** | Low | InnerTube metadata in `server/server.js`, timeline scrubber |
+| | **Bluetooth Foot Pedal Shortcuts** | Low | Keydown event listener in `frontend/app.js` |
+| | **Section Quick-Jump Pad** | Low | Lyric section parser in `frontend/lyrics-core.js` |
+| | **Voice Search (SpeechRecognition)** | Low | Web Speech API, search input handler |
+| **Phase 2: Stage & Audio** | **EBU R128 LUFS Normalization** | Medium | ffmpeg `ebur128` in `server/media-cache.js`, Web Audio GainNode |
+| | **ChordPro Display & Transpose** | Medium | `frontend/lyrics-core.js`, chord parser |
+| | **Confidence Monitor Stage View** | Medium | `Presenter` & `fitLyricLines` in `frontend/app.js` |
+| | **OBS Lower-Third Overlay** | Low-Med | `server/remote.js` WebSocket relay, transparent route |
+| | **On-Screen Subtitles (CC)** | Medium | `/api/notes/:id/captions`, overlay renderer |
+| **Phase 3: Piano & Interactive Learning** | **Interactive Piano Roll & Key Visualizer** | Medium | HTML5 Canvas keyboard renderer, note event synchronizer |
+| | **Audio-to-MIDI Transcription** | Medium-High | Spotify Basic Pitch (WASM) / ByteDance transcription worker |
+| | **Sheet Music View (VexFlow)** | Medium | VexFlow dynamic import, MusicXML / MIDI generator |
+| | **Wait-for-Note Practice (Web MIDI)**| Medium | Web MIDI API (`navigator.requestMIDIAccess`), practice queue |
+| **Phase 4: Advanced Engine** | **Audio Stem Separation (Karaoke)** | High | ONNX Runtime Web / server Demucs |
+| | **Pitch Shift & Tempo Worklet** | High | AudioWorklet / `SoundTouchJS` DSP |
+| | **Document Picture-in-Picture** | Low-Med | Chrome Document PiP API |
+| | **Collaborative Setlists** | High | WebSocket hub in `server/party.js` |

docs/fullscreen-background-audio.md

@@ -0,0 +1,88 @@
+# Fullscreen orientation and iPhone audio continuity
+
+## Task A — done
+
+Settings → Listening → Video & fullscreen offers Auto (follow device), Landscape,
+and Portrait. The choice persists on this device and can be cycled from the
+fullscreen controls. Supported browsers request fullscreen and then lock the
+selected orientation; Auto leaves orientation unlocked. Exit releases our lock.
+
+When orientation locking or element fullscreen is unavailable, the player uses a
+viewport overlay. A portrait viewport with Landscape selected rotates the existing
+stage and its controls 90 degrees; Portrait in a landscape viewport rotates it
+in the opposite direction. Safe-area padding follows the rotated axes. Touch
+seeking, double-tap seeking, volume/brightness swipes and pinch movement use
+inverse coordinates. The video stays in its existing DOM position to avoid
+interrupting WebKit playback. Controls and browser fullscreen exit restore the
+inline surface, including when a native orientation lock was rejected.
+
+Safari's custom overlay fills the available dynamic viewport; it cannot force
+Safari to hide browser chrome or change the phone's physical orientation. An
+installed PWA has no browser toolbar occupying that viewport.
+
+Files: `frontend/fullscreen-orientation.js`, `.css`, `.test.js`, small hooks in
+`app.js`, `index.html`, `sw.js`, `tests/fullscreen-orientation.spec.js` and
+`playwright.fullscreen.config.js`.
+
+## Task B — done; physical iPhone verification remains
+
+The previous progressive handoff loaded the audio source and sought it only when
+the page was hidden, then paused the video before transferring master ownership.
+That required a cold audio decoder start and allowed pause-handler re-entry.
+Foreground recovery also sought the video, whose shared seeking handler then
+sought the still-playing audio. Repeated play/playing/focus/watchdog handlers
+could independently issue the same audio play/seek requests.
+
+On iPhone, progressive playback now uses the existing dual playback path from the
+start: a muted video and an audible audio element. Saved files use the same local
+source; streams prefer their audio-only URL, falling back to the muxed source.
+EQ-render playback already used this path and remains unchanged. Locking promotes
+the already-playing audio to master without loading, seeking or restarting it.
+Unlocking aligns only the silent video; its internal seek does not propagate to
+the audible audio. Pending play requests are shared, small drift does not cause
+seeks, and the watchdog never seeks an element to itself. Hidden focus events do
+not restore the video prematurely. The audio clock still owns background progress
+and ended events, preserving auto-advance and lock-screen playback intent.
+
+This uses an audio decoder alongside video while visible. Audio-only playback
+and tracks that start while already backgrounded retain their existing paths.
+Browsers other than iPhone retain their foreground progressive path. Their cold
+handoff fallback now sets master ownership before media events and waits for audio
+to play before pausing video; returning keeps that audio playing while video resumes.
+
+Files: `frontend/audio-continuity.js`, `.test.js`, player/event hooks in `app.js`,
+`index.html`, `sw.js`, `tests/audio-continuity.spec.js`, and
+`playwright.audio-continuity.config.js`.
+
+## Validation and hardware review
+
+- 132 frontend unit tests pass, including orientation mapping, source selection,
+  small-drift policy, concurrent play deduplication, autoplay rejection retry, and
+  stale pending requests after pause/source reset.
+- `node --check frontend/app.js` and `bun build --no-bundle server/server.js` pass.
+- Eight fullscreen browser cases pass in Chromium/WebKit at 390 × 844, covering
+  Classic and Glass Stage overlays, visible controls, quick toggle, exit/restore,
+  lock/unlock calls and browser exit after lock rejection.
+- Four audio browser cases use real local PCM media in Chromium/WebKit, with an
+  iPhone user agent, covering saved and streamed progressive attachments. Repeated
+  visibility/pagehide/focus/pageshow events keep the same advancing audio element
+  with zero audio loads, pauses, seeks or additional play calls.
+- All 155 server tests pass with `YTDLP_PATH=/tmp/ytplayer-test-yt-dlp` (the existing
+  local test ZIPAPP). The initial default run failed because the system Python
+  environment lacked `yt_dlp`; no server changes were necessary.
+
+Review on an actual iPhone in Safari and installed PWA: saved MP4, streamed songs,
+EQ renders, multiple lock/unlock and app switches, auto-advance while locked,
+Media Session controls, seeking and PiP. Test Landscape/Portrait with safe areas,
+rotation and touch swipes in both themes. On Android/PWA, verify an actual native
+orientation lock and release; browser tests verify API calls with a controlled
+orientation implementation.
+
+iOS may suspend JavaScript, pause media or interrupt the audio session during lock,
+app switching, route changes or incoming calls. A web app cannot guarantee a zero
+OS-level gap. These tests demonstrate removal of application-induced source
+reloads and audio seeks; desktop WebKit cannot simulate physical iOS suspension.
+Tracks first started in the background still reattach their picture on return;
+that existing transition also needs hardware review.
+
+No server imports were added, and nothing was pushed or deployed.

docs/glass-controls-polish.md

@@ -0,0 +1,18 @@
+# Glass Stage control consistency
+
+Glass navigation and browsing controls now use Now Playing's existing vocabulary: 20 px SVGs with rounded 1.9 strokes, translucent tile surfaces, 18 px button corners, muted foregrounds, coral active/destructive states, and visible focus rings. Navigation badges use the same palette with readable 11 px counts.
+
+The stylesheet is entirely scoped to `html[data-layout="glass-stage"]`. Existing hidden navigation SVGs are reused. A small Glass-only module draws legacy button glyphs without changing IDs, listeners or existing accessible labels; switching away restores the original glyphs and removes its temporary accessibility labels. It observes page updates only while Glass is selected. The existing Now Playing design remains the reference.
+
+Coverage: bottom tabs and badges, sidebar rows, search/queue/history/playlist row actions, saved-file actions, download controls, Settings navigation/buttons, notes tabs and mini-player buttons. Glass row actions reserve space so long titles remain readable. Section shortcuts sit lower-left rather than covering right-hand file actions. Downloads' bottom-tab label stays fully visible.
+
+Validation:
+
+- 115 frontend unit tests; app/module syntax; server no-bundle build.
+- Browser coverage for Classic and Glass at 390 and 1440 px across seven page states; keyboard button commands, focus, theme restoration, mini-player controls, settings reachability and file-action hit testing.
+- Fourteen Classic before/after screenshots compare against the same fixture with the new assets disabled. Control geometry and computed styles match exactly. PNG comparison allows at most 16 isolated browser rasterization pixels in the entire screenshot (roughly 0.005% at phone size); no layout/theme difference is tolerated.
+- Batched visual review and a single confirmation of the label/shortcut corrections. The apparent clipped Settings row is within its normal scroll container; a test reaches the final row.
+
+Captures are local files under `/tmp/glass-polish-before-*` and `/tmp/glass-polish-after-*`, plus `/tmp/glass-polish-navigation-notes-mini.png` and `/tmp/glass-polish-settings-end.png`. Before/after fixtures suppress animations and automatic saving so playback/network timing cannot change the comparison. The installed bottom navigation is exposed in one isolated fixture because ordinary Chromium is not an installed PWA.
+
+Reviewer: check a real installed iPhone PWA's bottom bar, mini-player clearance and theme switching, plus keyboard/hover behavior on desktop. No playback implementation, Classic stylesheet, credentials or deployment was changed.

docs/glass-stage-iphone-followup.md

@@ -0,0 +1,67 @@
+# Glass Stage iPhone layout follow-up
+
+The supplied production screenshots came from build `16c08b099a31`, before the
+Task A/B changes. This follow-up preserves the Glass Stage colours, glass tiles,
+stroke icons and all existing control ids/actions. Every CSS rule is scoped to
+`html[data-layout="glass-stage"]`; Classic retains its original rail and labels.
+
+## Panel shortcuts and bottom chrome
+
+The Glass section rail was a fixed horizontal overlay positioned above the mini
+player. Clearing the player did not clear a panel heading or filter underneath.
+`glass-panel-layout.js` moves that same rail, with its existing listeners, into
+`#listPane` before the heading. It restores the original location when leaving
+Glass Stage. The rail now occupies its own row instead of covering content.
+
+The module measures the visible fixed bottom navigation and mini player. The
+navigation's measured height already contains the home-indicator safe area;
+the mini player sits eight pixels above that height. Scroll clearance includes
+both bars and a 16 px gap, without counting the safe area twice. Portrait uses
+one shared scroller and reserves that clearance once at its tail; desktop panes
+reserve it individually. The mini player's outer card clips the progress strip
+inside its rounded border, rather than leaving a separate line below it.
+
+## Bottom navigation
+
+The uploaded rightward icon shift is reproduced by the pre-Task-A CSS from
+`f2c9459`: installed-PWA padding of `4px 16px` remained on a fixed-width icon box.
+Task A (`79a3c28`) already resets that padding to zero. The new regression test
+runs an iPhone 13 browser profile at 390 px, including 34 px bottom safe-area
+allowance, Queue/Downloads badges and an active pill. In both Chromium and
+WebKit, SVG and icon-box centres match label centres within 0.6 CSS px. The old
+CSS shifts every icon more than eight CSS px. No further nav CSS change was
+needed; this is committed verification of the existing fix.
+
+## Notes toolbar
+
+The toolbar's Glass override explicitly enabled `flex-wrap:wrap`. It now keeps
+one row. Container queries respond to the player card's available width, even
+when a desktop player column is narrow. Spacing tightens first, the longer
+Chapters & bookmarks label becomes icon/count at narrow card widths, and all
+labels become icon-only on the smallest cards. Full accessible names and title
+hints remain. Every action retains a minimum 44 px target, and the fold chevron
+stays at the row's right end. Status text truncates within the remaining space.
+Glass label wrappers and added names restore exactly when switching to Classic.
+
+## Verification
+
+- 125 frontend unit tests pass, including measured chrome-clearance logic.
+- `node --check frontend/app.js` and `bun build --no-bundle server/server.js` pass.
+- Chromium and WebKit: all five panel shortcuts at 390 and 1440 px; final list
+  row clears playback chrome; progress strip stays inside its card.
+- Classic geometry and before/after screenshot comparisons pass in both browsers
+  at 390 and 1440 px, within the 32-pixel isolated rasterization tolerance.
+- iPhone-profile navigation alignment/badges pass in both engines at 390 px.
+- Toolbar stays one row at 320, 360, 390, 430 and 1440 px in both engines, including
+  long status text and chapter counts; theme round-trip restoration passes.
+- Batched visual review of six WebKit captures found no overlap, alignment,
+  clipping or wrapping defects in the requested areas.
+
+Run `npx playwright test -c playwright.glass-panel.config.js` for the 22 browser
+cases. WebKit was installed locally for these checks; these are browser/iPhone
+profile tests, not tests on physical iPhone hardware. Review the installed PWA
+on an actual iPhone after the reviewer deploys, particularly when the mini
+player appears/disappears and after rotating the phone.
+
+Before/after captures are saved under
+`/home/josh/deliverables/ytplayer-done9/`. No push or deployment was performed.

docs/lyric-languages.md

@@ -0,0 +1,12 @@
+# Translations and pronunciation
+
+A cue can contain a primary lyric and translation separated by ` / `:
+
+```
+[1:23.45] 主你的恩典 / Your grace is enough
+!pinyin: zhǔ nǐ de ēndiǎn
+```
+
+The translation and phonetic text share the primary cue timestamp. They are smaller and muted beneath it in stage lyrics, Service mode, Presenter and OBS. The notes API preserves optional `secondary` and `phonetic` fields. Existing documents with only text, timing and kind remain unchanged.
+
+Use `| ` continuation lines (or Shift+Enter in the editor) for tight breaks within a cue. A continuation can also carry `Primary / Translation`. Multiple timestamps copy translations and pronunciation to every occurrence. A slash without surrounding spaces, such as `and/or`, remains literal. Ordinary `! Band cue` lines retain their existing meaning.

docs/now-playing-return-regression.md

@@ -0,0 +1,36 @@
+# Now Playing list return regression
+
+The shared browsing list retains the last page independently of the live playback
+queue. Search home hides `#listPane`; the mini-player previously only removed
+`home-over` and scrolled. It did not reset that hidden flag or replace the previous
+page with the playing playlist. At 390 px the original code fails in both Classic
+and Glass Stage with `#listPane` still hidden after tapping the mini-player.
+The separate `#upnext` card remained intact in this reproduction.
+
+Returning now rebuilds the source playlist and Up next. If its source playlist
+was removed (or playback came from search/channel/history), the list displays the
+live queue, without replacing it with the unrelated editable saved queue.
+Mini-player, close, Player jump, user-picked track/deep-link reveal and browser
+history returns share the restoration. Auto-advance still skips the reveal hook.
+History entries retain browsing views, and Settings section entries remain owned
+by Settings. Repeated restoration does not add duplicate player history entries.
+
+Run `npx playwright test --config playwright.now-playing.config.js`.
+The 20 cases cover both themes at 390/1440 px, return controls, Back/Forward,
+missing source playlists, stale Up next DOM, repeated returns and an exhausted
+queue. Synthetic tracks avoid dependence on YouTube decoding/network; the
+track-reveal case exercises the shared post-load hook, rather than real media
+loading. Headless Chromium exposes the mini-player via test CSS because it is
+not an installed phone PWA. The Player jump is tested only at phone width,
+where that navigation exists.
+
+Validation: 115 frontend unit tests, app syntax check, server build and 20 browser
+cases pass. Replaying the 390 px mini-player tests with the original app script
+fails in both themes at the hidden list assertion; the patched script passes.
+No server implementation or tests changed.
+
+On a real iPhone, confirm the same browse/return sequence in Safari and the
+installed PWA, plus Back/Forward and an actual shared video deep link. Confirm
+playback keeps its position and the page scrolls to the player without shifting
+the document viewport. Desktop checks cover both themes; no playback/background,
+playlist action layout or device-export implementation was changed.

docs/p2p-transfer.md

@@ -0,0 +1,153 @@
+# Direct device media transfers
+
+## Existing paths (audit before implementation)
+
+| Path | Existing media-byte route | Relevant code |
+| --- | --- | --- |
+| Paired remote | Controls only; the host plays its own source. No existing file-send action. | `frontend/app.js` Remote; `server/remote.js` |
+| Presenter and OBS | Lyrics, timing and metadata only; neither currently plays host media. | Presenter and overlay modules; remote relay |
+| Watch Party playback | Each guest loads independently through normal server/YouTube playback, unless already saved locally. | Party `applyState`, `Player.loadVideo`; `server/party.js` |
+| Watch Party voice | Direct WebRTC audio; server forwards SDP/ICE only. | Party voice mesh, party `rtc` relay |
+| On other devices / failed playback | Existing verified-file DataChannel download, 64 KiB frames, SHA-256 validation, worker writes OPFS. Only offered after server failure in playback. | `p2p-transfer.js`, `p2p-recv-worker.js`, `getFromPeers` |
+| Save / preload | Server download first, then OPFS. | `preload`, `API.cacheDownload`, download endpoints |
+| Export to Files / Photos | Local OPFS first, server URL next, peer fallback last. Native share is an OS export, not paired-device transfer. | `exportToDevice`, `export.js` |
+| Profile / playlist share and send | Metadata only. Sending a playlist does not transfer its media files. | Profile/playlist sync APIs |
+| Verify & share | Explicit device upload to server intake; hash and media validation admit it into the server cache. | `P2PClient.contribute`, `p2p-intake.js` |
+| Automatic rehydration | Server requests a holder to upload its full file to intake. This is an implicit media-byte server path. | `createRehydrator`, client `upload-request` handler |
+| Admin uploads / original YouTube downloads | Intentional server ingestion of original media; separate from direct device transfer. | Upload and media-cache endpoints |
+| VLC / external player URLs | HTTP server media URLs; these players cannot consume this application's DataChannel. | External player actions |
+
+The current file protocol has no resume: its receiver truncates partial files and
+removes them on failure. Connection timeout is 20 seconds per holder. Device
+signalling authenticates a device, but does not constrain its destination to a
+verified profile or paired room. Profile names supplied at device registration
+are not proof of profile membership. Existing server-verified holdings also
+exclude files whose bytes the server has never admitted.
+
+## Implementation design
+
+Reuse ordered RTCDataChannel transfers with public STUN only. The WebSocket
+server carries bounded, validated signalling and metadata, never file chunks.
+Pair authorization must come from an authenticated remote/party room or a
+verified profile session, not an arbitrary client-supplied profile name.
+
+A receiver explicitly accepts an invitation before saving. A cryptographically
+random, expiring, one-use invitation binds sender, receiver and file identity;
+subsequent signalling remains bound to that pair. Reject replay, mismatched
+identities, binary WebSocket messages and unrecognized protocol fields.
+
+Send 64 KiB chunks with bufferedAmount backpressure. Persist a partial OPFS file
+and resume at its exact committed byte offset. Rehash the retained prefix before
+continuing and verify total size and SHA-256 before promoting the file into the
+saved store; only then record metadata. A changed hash/size cannot reuse a partial.
+
+Use a 10-second connection deadline and an explicit, clearly labelled server
+fallback offer. Direct mode must not silently rehydrate server media from a
+device. Register “Direct device transfer (P2P)” in Settings, default on.
+
+Party playback should request a host's saved file when announced, then play the
+receiver's OPFS copy. Remote controls and presenter lyrics retain their existing
+behaviour; add explicit receive/play actions rather than automatically starting
+media in a control-only screen. A manual send action targets authenticated peers.
+
+Ordinary faststart MP4 cannot safely be appended as arbitrary MediaSource chunks.
+Progressive playback requires supported fragmented media and codec detection;
+otherwise use the completed, verified file (including iOS). Do not claim that
+raw MP4 chunks provide progressive playback.
+
+## Verification required before release
+
+Pure tests cover protocol parsing, chunk bounds, offsets, invitation replay and
+pair authorization. A two-page localhost browser test must transfer real bytes
+into OPFS through WebRTC and assert that server HTTP/WS logs contain only
+signalling and metadata. Exercise interruption/resume and explicit fallback.
+Review real iPhone foreground/background behaviour and restrictive NAT failure.
+
+## Implemented behaviour
+
+- `direct-protocol.js` strips unexpected fields and validates file claims and
+  bounded signalling; `direct-relay.js` binds invitations to authenticated room
+  members. Accepting an invitation is one-use, and only the bound pair can signal.
+- Remote, presenter and party relays carry the new protocol. Presenter and OBS
+  still display lyrics/control metadata; they do not automatically play media.
+  A presenter can explicitly accept a file sent by its paired host.
+- Settings → Direct device transfer provides the default-on toggle and send
+  buttons for currently connected paired/party/profile peers. Send the currently
+  playing **saved** song; the receiving device confirms every copy.
+- The paired remote has “Play here from paired screen” when its host has saved
+  media. Party guests and ordinary playback resolve an advertised direct source
+  before loading media. Saves and exports do the same; the existing OS export
+  sheet is preserved.
+- `/ws/p2p` now has a profile-scoped, ephemeral file-id directory. Protected
+  profiles require password/key proof, checked against the server profile hash.
+  Unprotected profiles retain their existing name-based access policy. Claims
+  are **not** admitted as server-verified media. Each device advertises at most
+  1,000 local ids per directory update; use paired-room sending for larger libraries.
+- The legacy unconfirmed global signalling path is refused. Older clients need
+  to reload the updated application to transfer files. This closes a bypass of
+  receiver confirmation and room/profile membership.
+- `direct-media.js` uses public STUN, ordered 64 KiB DataChannel chunks and
+  bufferedAmount backpressure. `direct-recv-worker.js` writes partials directly
+  to OPFS, rehashes their retained prefix and verifies exact size plus SHA-256
+  before promotion. File extensions are preserved. A disconnected partial can
+  be resumed by sending/requesting the same file again, including non-aligned offsets.
+- The 10-second deadline covers connection establishment. Prefix rehashing and
+  final verification do not consume it. Idle transfer timeout is 30 seconds.
+  Failures retain partial data and offer an explicit **Use server copy** action.
+  Automatic holder-to-server rehydration is blocked while direct mode is on;
+  **Verify & share** remains an intentional, explicit server upload.
+- `direct-stream.js` supports progressive preview for compatible fragmented
+  H.264 MP4 through MediaSource. Ordinary faststart MP4, unsupported codecs,
+  unavailable MediaSource and preview buffer exhaustion use the complete file.
+  iPhone playback should be reviewed using that completed-file path. A preview
+  is interactive and independent of the main player's host clock; main party
+  playback follows the host after the verified copy is ready.
+
+## Paths that still use server media
+
+Original YouTube acquisition, server uploads, intentional Verify & share intake,
+external VLC/M3U HTTP URLs and explicitly accepted server fallbacks still use the
+server. If no connected device advertises a local copy, normal original-source
+playback/download is preserved; this is not a transfer of another device's file.
+Profile/playlist shares, chapters, lyrics, presenter state and OBS state remain
+metadata/control only. Direct discovery requires an online paired room or an
+existing profile, and the browser must remain available to serve its OPFS file.
+No TURN service, deployment change or secret configuration is required.
+
+## Checks and reviewer follow-up
+
+Run:
+
+```sh
+node --test frontend/*.test.js
+node --check frontend/app.js
+bun build --no-bundle server/server.js
+bun test server/direct-relay.test.js server/p2p-hub.test.js server/remote.test.js server/party.test.js
+npx playwright test -c playwright.direct.config.js
+npx playwright test -c playwright.glass-navigation.config.js
+```
+
+The two-page localhost test uses the production relay and transport, separate
+browser stores, a real RTCDataChannel and actual OPFS writes. It resumes a 2 MB
+file at byte 12,345, verifies the resulting SHA-256 and asserts that the server
+log contains only invitation/acceptance/signalling/completion. A second case
+adds 12 seconds of resume preparation to prove it is outside the 10-second
+connection deadline. This is a local transport proof, not proof that arbitrary
+NATs will connect.
+
+Check real iPhone foreground/background suspension, large-file quota and final
+promotion, iOS completed-file playback, restrictive/symmetric NAT fallback,
+paired screen playback, party host changes during a copy, protected-profile
+credential changes/reconnect, OS export gestures, and an actual fragmented MP4
+MediaSource preview on desktop. Public STUN cannot overcome every NAT; declined
+invitations do not start media acquisition. Peer directories update when the
+presence socket connects and when local saves complete, rather than promising
+availability of offline/backgrounded devices.
+
+Final verification on 2026-10-03: 123 frontend unit tests, 22 touched server
+ tests (including remote and party), app syntax and server build, 8 Glass/Classic
+navigation browser tests at 390/1440 px, and both direct-transfer browser cases
+passed. The first navigation run lost its reused localhost server; a fresh-server
+rerun passed all eight cases without a code change. Classic screenshot comparisons
+remain within the test's rasterization tolerance. No real iPhone or restrictive
+NAT test was performed here, and no code was pushed or deployed.

docs/piano-transcription.md

@@ -0,0 +1,28 @@
+# Piano transcription
+
+Commit 258aad8 added ideas, not runtime code. The implementation is now opt-in under Settings → Piano transcription.
+
+## What runs where
+
+- **Browser:** `frontend/piano-engine.mjs` imports pinned Spotify Basic Pitch 1.0.1 and TensorFlow.js 4.22.0 only after “Transcribe in browser”. It resamples to mono 22,050 Hz in OfflineAudioContext, prefers WebGPU, and falls back to WebGL/CPU. Dependencies load from esm.sh; model/weights load from jsDelivr. Neither the engine nor model is in the service-worker install shell. No audio is uploaded by this path. Processing still needs a network on first use. File/device/server-cached audio is limited to 100 MB and 15 minutes. Basic Pitch is instrument-agnostic, not piano stem separation; mixtures may produce inaccurate notes.
+- **Device cache:** IndexedDB `ytp-piano/notes`, per video id, stores the engine label and compact JSON sequence. Export produces `<id>.notes.json`. Each note is `{pitch,start,end,velocity,hand}`. Timing is in seconds; velocity is 1–127. Missing hands use a middle-C split (pitch < 60 = left), which is a visual aid, not reliable fingering. Settings shows an 88-key synced visualizer and a manual practice queue of 8-second A–B loops.
+- **Server:** optional `server/piano.js` queues authenticated jobs in SQLite; `scripts/piano/worker.py` downloads server media on the private compose network and runs ByteDance's `piano_transcription_inference` on CPU. This does not run in the web server. Model loading happens at the first claimed job. The worker is off by default and the compose `piano` profile is inactive by default. The checkpoint is about 165 MB; runtime memory needs substantially more (container limit 6 GB).
+
+## Enable the optional worker
+
+Configure a dedicated random `PIANO_WORKER_TOKEN` of at least 24 characters and `PIANO_WORKER_ENABLED=1` for the app and worker. Enable the compose `piano` profile and build/start the worker during a separately approved deployment. It shares the existing private `lyrics` network, keeps its checkpoint in `piano-models`, and is limited to two CPUs. Nothing is pushed or deployed by these changes.
+
+Use an admin API token in the Settings server-request field (kept only in the mounted UI, not persisted), or call the contract directly. Save the song on the server first. “Load server result” retrieves the finished sequence and stores it on the device. Worker jobs survive server restarts, have heartbeat leases and three attempts; expired workers cannot publish. Queue capacity is ten. Replacing a server media generation marks its old sequence stale.
+
+## API contract
+
+- `GET /api/media/:id/piano`: public `{ok,enabled,job}`; `job` is null or `{videoId,status,notes,error,updatedAt}`. Notes are available only after completion. Status: queued/running/ready/failed/stale.
+- `POST /api/media/:id/piano`: existing admin session/API-token authentication. Returns an existing valid job or queues one (202). Worker off → 503; uncached source → 409; duration over 15 minutes → 422; queue full → 429.
+- `POST /api/piano-worker/claim`: dedicated Bearer worker token; returns a job with lease and server-relative audioPath, or null. Claims are atomic.
+- `POST /api/piano-worker/:id`: dedicated worker token plus JSON `{lease,action}`. Actions: heartbeat; complete with `notes`; fail with `error`. Invalid/expired leases → 409. Results are bounded and validated before saving.
+
+The model path is based on [Spotify's browser API](https://github.com/spotify/basic-pitch-ts) and [ByteDance's inference package](https://github.com/qiuqiangkong/piano_transcription_inference). Their upstream licences apply. The browser's TFJS dependency override is pinned and tested with a synthetic WAV; review GPU performance and accuracy with real recordings.
+
+## Review on devices
+
+Verify no model request before Transcribe, GPU/CPU fallback, mobile memory limits, cache survival after reload, JSON export, keyboard alignment with seeking, and A–B practice loop timing. Run the optional worker against a short known piano recording before enabling it for users; heavy-model/container inference is not covered by ordinary unit tests. This version does not provide model-based stem separation, score notation, pedal transcription display, or MIDI wait-for-note practice.

docs/recommendations.md

@@ -0,0 +1,59 @@
+# Recommendations and the video catalog
+
+Home and the Search menu show **Recommended for you**, with play, queue, playlist actions, refresh, and an explanation per pick. Saved picks remain available when the server cannot be reached. Cold starts explain how to get recommendations without blocking search.
+
+## Server collection
+
+`video-catalog.js` owns collection independently of downloaded media and the search-result cache. It preserves richer fields when sparse cards arrive and serializes writes so simultaneous discoveries cannot erase each other's metadata.
+
+| Source | Collection path |
+| --- | --- |
+| Fresh YouTube searches | Awaited ingestion in `fetchYoutube`, including background refreshes; Innertube cards or yt-dlp fallback cards |
+| Memory/persistent search hits | Successful JSON response collector |
+| Browser saved searches | `/api/catalog/collect`, including the IndexedDB-only fast path; pending query keys retry on launch, reconnect, and every minute |
+| Channels, expanded/shared playlists, related-video searches | Successful JSON response collector |
+| Played, warmed, or saved videos | Full yt-dlp extraction in `resolveStreamsUncached`, plus cached-stream responses |
+| Local/imported playlists, queue, history, linked profiles | Successful sync/profile/share requests and read responses |
+| Other GET APIs surfacing video cards | Shared successful-JSON response collector; recommendations themselves are excluded |
+| Older server data | Durable paged backfill of known cards, search results, media metadata, history, playlists, shared playlists, and profiles |
+
+The catalog records YouTube video IDs, titles, channels, duration, thumbnail URL, available tags/categories, description excerpts, and extractor view counts. It tracks discovery source separately from listening counts. Local uploads already have server metadata/art in the upload tables; custom device-only edits are excluded from the public YouTube catalog.
+
+Thumbnail **bytes** are stored in SQLite, not merely URLs. Two workers fetch allowed HTTPS YouTube image hosts, reject redirects, allow JPEG/PNG/WebP, cap images at 1 MiB, and time out after eight seconds. Failed jobs persist with backoff up to one day and resume after restart. `/api/catalog/:id/thumbnail` serves stored images; recommendation and local-search cards prefer this URL once ready. The service worker caches these URLs for offline images.
+
+Retention is bounded: `VIDEO_META_MAX` defaults to 500,000 videos and `VIDEO_THUMB_MAX_BYTES` to 512 MiB of image data. Metadata trimming prefers unplayed entries and cleans up associated jobs/source/channel rows. Image eviction preserves metadata, disables automatic re-download, and permits re-fetch on a new discovery. SQLite can reuse freed pages; the byte budget measures live image data, not the physical database file. Failed or evicted images fall back to the original thumbnail URL. Existing source images can be unavailable; metadata collection does not require successful image retrieval.
+
+## Listening and ranking
+
+The existing StatsCore tracker counts a play after **30 seconds actually listened**, rather than counting search appearances, stream requests, or media-cache hits. `/api/user/sync` submits daily per-video snapshots. The server uses monotonic maximum counts per listener/day/video so repeated saves, retries, and reloads do not multiply plays. It retains 400 days and caps ingestion at 10,000 day/video entries per sync.
+
+Anonymous listeners use device fingerprints. Linked listeners use the profile name and existing profile password/key gate. Linking devices merges earlier anonymous daily summaries into the profile with maxima and removes the device copies, so synchronized profile history is counted once. Recommendations and browser snapshots switch with the active profile. This uses the app's cumulative daily statistics; it does not introduce event-level reconciliation of independently edited or concurrently modified profile histories.
+
+The algorithm runs on the server in `recommendations.js`:
+
+1. Select up to 300 globally most-played videos, 100 personal favorites, and 600 recent discoveries. Fetch older candidates from up to ten favorite channels using an indexed channel table.
+2. Build channel and title/tag/category interests from the listener's top 20 videos.
+3. Score with logarithmic weights for personal plays, channel affinity, shared metadata tokens, global plays, and plays in the last 30 days.
+4. Keep at most three videos from a channel and reserve up to half the picks for familiar favorites when discoveries exist.
+5. Return playable cards and plain-language reasons; prefer stored thumbnail URLs.
+
+There is no `media_cache` filter or dependency. Unplayed search results and cached or uncached videos all qualify. An empty listener history falls back to global most-played videos, then recent discoveries. A completely empty catalog returns an empty list; recommendations do not launch unsolicited extraction searches.
+
+## API
+
+- `GET /api/recommendations?fp=<fingerprint>[&profile=<name>][&limit=12]`: `{ok, results}`; limit 1–24. Protected profiles require `X-Profile-Secret`. Personal responses use `Cache-Control: no-store`.
+- `POST /api/catalog/collect`: `{cards: [...]}`, at most 500 cards and 512,000 request characters. Normalized cards reject unsafe IDs and arbitrary thumbnail hosts.
+- `GET /api/catalog/:id/thumbnail`: stored image bytes or 404.
+- `/api/user/sync` additionally accepts `stats` and `profileName`; protected profiles use the existing secret header.
+
+## Verification
+
+- 16 Bun catalog/recommendation tests: all pass, covering source collection, richer-field preservation, concurrency, cache eviction, thumbnails, durable retry/backfill, ranking, indexed retrieval of older channel matches, idempotent analytics, profile scope and deduplication.
+- 9 Chromium recommendation UI tests: all pass, covering 320/390/1440px, caption contrast >=4.5:1, actions, Search navigation during playback, saved-search submission, offline retries, failure states and profile switching.
+- Existing 11 Classic browser checks and 72 frontend unit tests: all pass.
+- Isolated live Bun server: protected-profile access, recommendation persistence across restart, two-device deduplication (eight plays remain eight), and a real 21,011-byte YouTube thumbnail stored and served after restart all pass. No production profiles or media were changed.
+- Visual review: desktop cards and both mobile section captures are readable and reachable. Initial mobile captures were taken after scrolling to the final action; corrected captures show the section heading and first cards. Desktop retained visible Try chips because its content did not need to scroll; this is a capture expectation difference, not a clipping defect.
+
+Design-hook triage: the new recommendation stylesheet has no findings and measured Classic caption contrast passes. One file/value exception suppresses the shared HTML's three intentionally empty, hidden dynamic artwork images; JavaScript supplies their `src`. The other 15 inherited shared-shell findings (legacy contrast, gradient/glow styling, 11px captions, and intentional app scroll-container clipping) remain unsuppressed and outside this feature's styling changes.
+
+No real mobile device/WebKit run or production deployment was performed.

docs/related-video-recovery.md

@@ -0,0 +1,39 @@
+# Related-video recovery
+
+The old Now Playing related loader called `/api/search` with the complete title.
+That endpoint follows up to 14 InnerTube pages to collect 200 results, then uses
+resilient yt-dlp if necessary. Related displayed only eight cards. It had no
+alternate query or catalog fallback, silently caught failures, and hid its panel.
+It also read mutable `current` after awaiting the request, allowing a previous
+song's response to populate the next song's recommendations.
+
+A read-only production probe (`/api/search?q=Rock Medley&refresh=1`) returned 200
+results successfully during this investigation. No persistent IP/account/region
+block was reproduced, and no privileged production logs or credentials were used.
+The exact intermittent upstream YouTube rejection cannot be established from
+that successful probe. The failure handling and request coupling above are
+verified directly in the previous code and reproduced in tests.
+
+The new `/api/related` endpoint first reads one InnerTube watch-next response,
+including compact and modern lockup video cards. A local real request for
+`wZzRoXymOUU` parsed 20 recommendations. Failures/empty results fall back to bounded
+single-page title/channel searches, then the existing resilient yt-dlp search
+path, then videos already known to the server. It excludes the current song,
+deduplicates, returns eight cards, shares in-flight work and caches successful
+results. Failed responses are not cached; Retry bypasses the success cache.
+The YouTube work has an 18-second total budget with per-operation timeouts.
+The existing `SEARCH_INNERTUBE=0` switch still disables InnerTube.
+
+Every new discovery goes through the existing metadata catalog/thumbnail collector.
+A metadata persistence failure cannot hide otherwise playable cards. Related's
+client snapshots the song and ignores superseded responses. When all sources are
+unavailable, its panel stays visible with a friendly message and Retry, rather
+than disappearing. Catalog fallback is explicitly labelled.
+
+Validation: frontend loader tests cover filtering, errors, retry refresh and stale
+responses. Server tests cover renderer parsing, next/search/catalog fallbacks,
+metadata collection, cache/in-flight deduplication, deadline exhaustion, and route
+validation. Browser tests in both themes, Chromium and WebKit at 390 px, exercise
+503 → Retry → results and assert that the section rail retains its parent.
+
+No changes to the Glass section rail; no push or deployment.

docs/remaining-features-review.md

@@ -0,0 +1,17 @@
+# Remaining features and screen refinement
+
+All changes are local commits on main. Nothing was pushed or deployed.
+
+| Feature | Status | Main files | Validation / reviewer checks |
+| --- | --- | --- | --- |
+| 9. Ten-band EQ | Done | frontend/eq-core.js, eq-core.test.js, app.js, styles.css; docs/equalizer.md | Five-band curves migrate; live playback and EqRender share bands/presets/widening. Unit and four Classic/Glass browser cases passed. Check headphones, mono compatibility, and saved versus live processing on a real iPhone. |
+| 10. Bilingual lyrics | Done | frontend/lyrics-core.js, lyrics-display.js and tests; lower-third.js, app.js, server/notes.js and tests; docs/lyric-languages.md | Primary/secondary/phonetic text preserves timing and round trips. Service, stage, Presenter and OBS use shared display logic. Frontend and 18 server notes tests passed. Check font coverage, multiline fitting and remote output on real devices. |
+| 11. Piano transcription | Done; optional heavy worker awaits real inference validation | frontend/piano-core.js, piano-engine.mjs, piano.js and tests; server/piano.js and tests; scripts/piano/; docs/piano-transcription.md | Browser Basic Pitch/TFJS loads only on request, chooses WebGPU where available with WebGL/CPU fallback, caches compact notes with hand heuristic, and supports visualizer/practice queue. Real repeated browser inference passed without growing tensor count. Four server and two Python worker tests passed. ByteDance worker scaffolding, leased API contract and optional compose profile are implemented and off by default; no heavy container was started. Check a known piano recording before enabling it. |
+| Downloads polish | Done | frontend/downloads-page.js and tests, offline-pages.css, downloads.js, small app.js hooks; tests/offline-pages.spec.js | Drawn SVG empty state, no empty filter, storage information and Saved link. Active/queued/paused/failed groups reuse the existing manager and confirmed cancellation. Classic/Glass at 390 and 1440 px checked. Test real slow downloads, pause/resume, failure/retry and navigation while saving. |
+| Saved polish | Done | frontend/saved-page.js and test, saved-page.css, renderSaved hooks; tests/offline-pages.spec.js | Storage summary and confirmed Clear all share one row. Export/delete have separate horizontal 44 px targets and SVG icons; long titles truncate. Individual deletions confirm, and failed storage operations retain records. Existing save-to-device sheet is called unchanged. Check iPhone export/share and real storage removal. |
+
+Common asset changes are registered in frontend/index.html and the service-worker shell list. The protected background playback methods, Classic playlist actions and save-to-device sheet were not edited.
+
+Final checks: every frontend/*.test.js, app.js syntax, server no-bundle build, and the offline-page browser suite. Feature-specific server and Python tests were run with their respective feature commits. The 21-case settings suite and real Basic Pitch inference also passed. Offline-page tests cover all four layout/width combinations, filtering, cancellation, delete failure and action geometry.
+
+Impeccable context loading, polish and craft-floor references were followed. Batched screenshots were assessed; final screenshots wait for the incumbent card reveal animation to finish. The manual detector found one advisory: the restrained Downloads empty-state heading is 20 px, intentionally smaller than the browsing title; no global typography change was made. The pre-existing design sidecar was reported stale and left outside this refinement.

docs/theme-bento-hub.md

@@ -0,0 +1,80 @@
+# New Bento Hub theme
+
+The old Bento rules in `frontend/styles.css` have been removed. The replacement
+is `frontend/theme-bento-hub.css`, scoped to `html[data-layout="bento-hub"]`.
+The stylesheet, small theme helper, and self-hosted Plus Jakarta Sans fonts are
+included in the service-worker shell cache. Classic remains the default.
+
+## Match to the reference
+
+The reference is `docs/mockups/bento-hub/index.html` and `SPEC.md` (local design
+sources). The implementation uses their obsidian surfaces, solar-gold primary
+controls, cyan listening/status cues, Plus Jakarta Sans and JetBrains Mono,
+16px outer / 10px inner corners, stroke SVG icons, search capsule, playlist
+artwork collages, bordered collection rows, and floating mini player.
+
+Coverage includes the desktop sidebar and phone navigation, Home and search,
+Now Playing, all three notes tabs, stage lyrics, up next, playlist and channel
+views, Queue and batch selection, History, Saved, all download states and their
+Retry/Cancel controls, Settings overview and sections, Service mode, modals,
+control sheets, and empty states. Floating chrome has measured clearance;
+content scrolls inside the remaining viewport. `#sectionRail` stays fixed and
+attached directly to `body`. It is never moved into a panel or scroll container.
+
+## Deliberate differences
+
+- Content and navigation remain the real app's. Home shows actual playlists
+  and recommendations. Counts, artwork, progress, lyrics and wake-lock state
+  come from existing data; there are no invented verification badges, transfer
+  speeds, subscriber counts, or guarantees that the screen will stay awake.
+- The desktop sidebar uses the spec's 260px width rather than the HTML mockup's
+  240px. The drawer extends through 1023px. The existing app stacks its player
+  at phone widths; its browsing and player controls remain accessible there.
+- Now Playing keeps the real control deck, playlist panel, volume, looping,
+  fullscreen, notes and More controls. Notes remain with the player instead of
+  reproducing the mockup's separate static lyrics column. Service keeps its
+  view, autoscroll, floating lyrics, reporting and text-size controls; these
+  wrap when necessary rather than overlapping.
+- Settings keeps its section registry, back/history behavior, live summaries,
+  search and desktop two-pane navigation. Layout selection remains the existing
+  select rather than duplicating it with mockup-only theme chips.
+- Functional text has an 11px floor and controls have 44px minimum targets.
+  Muted dark text and the light-theme gold were adjusted for contrast. Existing
+  font scaling, density, contrast, reduced-motion and performance preferences
+  continue to apply. Service lyrics keep their adjustable sizing.
+- Mockup frames omit the shell on several screens and contain empty space or
+  sample rows. Real pages retain the full shell and scrollable content. Video
+  fixture art is synthetic; a real playing video fills the video stage.
+
+## Verification and screenshots
+
+Run `node scripts/test-bento-theme.js` for a reproducible comparison. It extracts
+pre-Bento commit `04b620e` into a temporary directory, captures Classic and Glass
+before shots, then checks the current app. It does not modify the checkout.
+`BENTO_BASE_COMMIT` can select another baseline; `BENTO_SCREENSHOT_DIR` can select
+an output directory. Default output is `~/deliverables/ytplayer-done13/`.
+
+The Playwright matrix covers 23 screens at 390px and 1440px in Chromium and
+WebKit. It also checks centered navigation icons, download action appearance,
+fixed rail ownership, sidebar and mini-player navigation, floating clearance,
+theme switching restoration, and light/high-contrast appearance. The reference
+is opened at both widths and each reference frame is captured when the local
+mockup is present. No local mockup files are added to these implementation
+commits. Static fixtures freeze the Classic mini-player's initial observer and
+native indeterminate progress to avoid unrelated animation/scroll races.
+Before/after comparisons allow at most 40 subpixel rasterization differences
+in a whole screenshot; substantial geometry or styling differences fail. The
+additional theme-switch check tolerates one RGB level per channel to account
+for Chromium recompositing rounded corners, while retaining the 40-pixel limit.
+
+Frontend unit tests include floating-chrome clearance with and without safe
+areas/hidden bars and Bento-only SVG mapping without changing Glass glyphs.
+The usual frontend tests, app syntax check and server build are run after each
+screen group. Server source and imports are unchanged.
+
+On a real iPhone, review safe-area clearance in Safari and installed mode,
+keyboard and orientation changes, the floating rail, mini-player return,
+Service controls, and actual video playback. On desktop, review long titles,
+sidebar drawer at tablet widths, keyboard focus, Settings navigation and theme
+switching. WebKit automation checks layout; it does not emulate all iOS media
+or safe-area behavior. Nothing was pushed or deployed.

docs/vocal-stems.md

@@ -0,0 +1,5 @@
+# Vocal reduction and future stems
+
+The Vocal control uses a stereo mid/side matrix, not source separation. The same `frontend/vocal-reducer.js` graph runs in live Web Audio and EqRender's OfflineAudioContext. At 100% it is identity; at 0% it retains the stereo side and removes the centre. Centred instruments are reduced too, and mono can disappear. Live processing on iPhone requires the existing opt-in; saved songs render in the background and keep lock-screen playback.
+
+TODO: add optional Demucs source separation. Follow the lyrics-worker deployment pattern, with its own model volume, token and resource limits. Suggested contract: `POST /api/media/:id/stems` starts an idempotent job, `GET /api/media/:id/stems` returns queued/running/ready/failed plus vocal/instrumental URLs. The worker fetches server audio over the private network, runs Demucs, atomically publishes stems and retains model/version/source-hash provenance. Authenticate job creation, cap concurrency and file size, and never fetch arbitrary user URLs. Keep the worker and feature off by default. No stems API or model currently runs.

docs/youtube-save-unavailable.md

@@ -0,0 +1,109 @@
+# Rock Medley save investigation
+
+Video: `wZzRoXymOUU` — **Rock Medley**, Petra - Topic, 605 seconds.
+Investigation date: 2026-10-03. Main was pulled with `--ff-only` before changes.
+No production shell, credentials, cookies, vault, deployment or proxy was used.
+
+## Evidence
+
+YouTube's public oEmbed endpoint returns HTTP 200, the correct title/artist and
+thumbnail. This confirms the ID, but not playback permission. The watch page's
+initial player response on this development machine returns:
+
+```json
+{"status":"UNPLAYABLE","reason":"Video unavailable"}
+```
+
+The server's metadata invocation (`-J --no-warnings URL`) and the exact cache
+save invocation fail with `ERROR: [youtube] wZzRoXymOUU: Video unavailable`.
+Providing Bun as the JS runtime mirrors the Docker image's `/etc/yt-dlp.conf`.
+The error occurs during player extraction, before selecting/downloading a
+format. The server uses a ladder of selectors, not a hard-coded format ID.
+
+| Local extractor | Default result |
+| --- | --- |
+| PATH yt-dlp 2026.07.04 | Video unavailable |
+| Repository binary 2026.08.19 | Video unavailable |
+| Downloaded nightly 2026.09.27.232945 | Video unavailable |
+
+With 2026.08.19, explicit `web_embedded`, `web_safari`, `tv_simply`, `android_vr`,
+`mweb` and `web_music` clients all fail for this song too. A control video
+(`0gfX0dFLaBc`) succeeds from the same machine/runtime. This is video-specific
+upstream playability refusal, not a demonstrated stale-extractor, missing-format
+or broken-JS-runtime problem. It is **not exclusively reproducible on prod**.
+The generic response does not establish region, IP, account or licensing as the
+specific cause. Cookies or PO tokens were not requested or tested.
+
+Upstream release notes: [2026.08.19](https://github.com/yt-dlp/yt-dlp/releases/tag/2026.08.19).
+[yt-dlp documentation](https://github.com/yt-dlp/yt-dlp#dependencies) describes
+runtime dependencies; no dependency update resolved this local reproduction.
+The Dockerfile is unchanged because an update alone is not a proven remedy.
+Its existing release-download layer is cached by Docker, so a future intentional
+extractor update must rebuild that layer, rather than assume new app code updates
+it automatically.
+
+## Changes
+
+1. Shared extraction now tries a bounded client ladder for generic unavailable
+   and missing-format errors, as well as bot checks. This covers both metadata
+   probes and actual saves. Explicit private/member/age/country/removal errors,
+   local disk errors, cancellation and explicit client overrides do not trigger
+   that ladder. The final diagnostic preserves the original failure and lists
+   attempted clients; it does not mislabel the song as deleted.
+2. Explicit Retry POSTs `/api/download/:id/retry` before preparing a device save.
+   It clears stale preparation/stream hints and calls the normal cache with
+   `force:true` to bypass a **failed row's** cooldown. It does not delete ready
+   media or duplicate running jobs. USB-volume, free-space/budget, duration and
+   validation rules still belong to the existing cache. Repeated failed retries
+   are limited to one per song per 15 seconds. Normal automatic resumes do not
+   force a retry. Manual Retry follows the same new client ladder.
+3. Downloads, Settings → Downloads & storage, and save-failure toasts use plain
+   language. Expandable “Technical details” retains the raw tool error as text,
+   never HTML. Controls remain usable in both themes at 390/1440 px.
+
+## Remaining reviewer check
+
+**These changes do not demonstrate a successful download of Rock Medley.**
+The local default and all tested clients still receive YouTube's refusal.
+To establish the production-specific reason, the reviewer should compare:
+
+- Actual yt-dlp version and the invocation below inside the deployed container.
+- Logged-out YouTube playback on the homelab's outbound network versus the
+  working phone network; repeat with the phone on that same network if possible.
+- If only authenticated playback works, confirm whether the video needs account
+  access before considering the existing optional read-only cookies mechanism.
+  Do not assume a PO token is required without extractor diagnostics saying so.
+- If the failure tracks a network/region, use a permitted outbound network where
+  the video is available, or a permitted alternate source/upload/device copy.
+  Merely changing a region hint does not prove actual playback eligibility.
+
+No network, cookies, token, Docker or deployment workaround was guessed or
+silently enabled. After any confirmed environment correction, Retry now starts
+a genuine fresh attempt instead of just returning the old backoff failure.
+
+```sh
+# Metadata probe, same as the server (Docker config supplies the Bun runtime)
+yt-dlp -J --no-warnings 'https://www.youtube.com/watch?v=wZzRoXymOUU'
+
+# Cache save, same selector/merge/rate args as the server's defaults
+yt-dlp 'https://www.youtube.com/watch?v=wZzRoXymOUU' --no-warnings --no-playlist \
+  -f 'bv*[height<=720][vcodec^=avc1]+ba[ext=m4a]/bv*[height<=720][vcodec^=avc1]+ba/b[ext=mp4][vcodec^=avc1]/bv*[height<=720]+ba/b[ext=mp4]/b' \
+  --merge-output-format mp4 --limit-rate 2M -o /tmp/rock-medley-check.mp4
+```
+
+Tests: `node --test frontend/*.test.js`; app syntax check; unbundled server build;
+`bun test server/ytdlp-resilience.test.js server/download-retry.test.js
+server/media-cache.test.js`; and
+`npx playwright test --config playwright.download-retry.config.js`.
+The existing pool tests additionally need an importable yt-dlp zipapp:
+`YTDLP_PATH=/path/to/zipapp bun test server/ytdlp-pool.test.js`. The installed
+PATH executable here is a Python entry-point script, not an importable zipapp;
+providing the downloaded nightly zipapp makes all pool tests pass without any
+production code or environment changes.
+
+Final validation: **118 frontend unit tests, 44 server tests and 13 browser cases
+pass**, plus the app syntax check and server build. Browser cases cover the real
+Retry controls in both Downloads and Settings, normal resumes, friendly failures,
+44 px details controls, safe raw text and overflow at phone/desktop widths.
+A real iPhone Safari/PWA save should still be checked after deployment, especially
+pause/resume of a partial copy and retry after a network change.

frontend/admin.html

@@ -92,7 +92,7 @@
     }
     .btn:hover { background: rgba(255,255,255,.1); }
     .btn:active { transform: scale(.97); }
-    .btn.pri { border: 0; background: var(--grad); color: #fff; box-shadow: 0 10px 26px -10px var(--a1); }
+    .btn.pri { border: 0; background: #6143cf; color: #fff; box-shadow: none; }
     .btn.pri:hover { filter: brightness(1.1); }
     .btn.ok { border: 0; background: var(--ok); color: #06210f; }
     .btn.dng { color: var(--bad); border-color: rgba(255,107,107,.35); background: rgba(255,107,107,.07); }
@@ -109,6 +109,45 @@
     .newtoken { margin-top: 12px; padding: 12px; border: 1px solid var(--ok); border-radius: 12px; background: rgba(74,222,128,.07); word-break: break-all; }
     .src { font: 11px var(--mono); color: var(--text-dim); } .src.api, .src.auto { color: var(--warn); } .src.restore { color: var(--ok); }
 
+    /* ---------- upload card ---------- */
+    .sr-file { position: absolute; width: 1px; height: 1px; opacity: 0; overflow: hidden; clip: rect(0 0 0 0); }
+    .up-form { display: grid; gap: 14px; }
+    .drop {
+      position: relative; display: flex; align-items: center; gap: 14px; min-height: 76px; padding: 14px 16px;
+      border: 1.5px dashed var(--line-2); border-radius: 16px; background: rgba(0,0,0,.22); cursor: pointer;
+      transition: border-color .15s, background .15s;
+    }
+    .drop:hover, .drop.over { border-color: var(--a1); background: rgba(124,92,255,.08); }
+    .drop:focus-within { outline: 2px solid var(--a1); outline-offset: 2px; }
+    .drop.has { border-style: solid; border-color: rgba(34,211,238,.45); background: rgba(34,211,238,.06); }
+    .drop-ico { flex: none; width: 40px; height: 40px; padding: 9px; border-radius: 12px; background: rgba(255,255,255,.06);
+      fill: none; stroke: var(--a2); stroke-width: 1.8; stroke-linecap: round; stroke-linejoin: round; }
+    .drop-text { flex: 1 1 auto; min-width: 0; display: grid; gap: 2px; }
+    .drop-text strong { font-size: 15px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+    .drop-text span { font-size: 13px; color: var(--text-dim); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+    .drop-btn { flex: none; height: 36px; padding: 0 14px; display: inline-flex; align-items: center; border-radius: 11px;
+      border: 1px solid var(--line-2); background: rgba(255,255,255,.06); font-weight: 700; font-size: 13px; }
+    .up-meta { display: grid; grid-template-columns: 1fr 1fr auto; gap: 12px; align-items: end; }
+    .fl { display: grid; gap: 6px; min-width: 0; }
+    .fl > span:first-child { font: 700 11px/1 var(--ui); letter-spacing: .08em; text-transform: uppercase; color: var(--text-dim); }
+    .fl .field { width: 100%; }
+    .cover-pick { cursor: pointer; }
+    .cover-box { height: 44px; display: inline-flex; align-items: center; gap: 8px; padding: 0 12px 0 6px; border-radius: 13px;
+      border: 1px solid var(--line-2); background: rgba(0,0,0,.28); max-width: 220px; }
+    .cover-box svg { flex: none; width: 32px; height: 32px; padding: 5px; border-radius: 9px; background: rgba(255,255,255,.06);
+      fill: none; stroke: var(--text-2); stroke-width: 1.6; stroke-linecap: round; stroke-linejoin: round; }
+    .cover-box img { flex: none; width: 32px; height: 32px; border-radius: 8px; object-fit: cover; }
+    .cover-box em { font-style: normal; font-size: 13.5px; color: var(--text-2); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+    .cover-pick:hover .cover-box { border-color: var(--a1); }
+    .cover-pick:focus-within .cover-box { outline: 2px solid var(--a1); outline-offset: 1px; }
+    .up-actions { display: flex; align-items: center; gap: 14px; flex-wrap: wrap; }
+    .up-actions .btn.pri { min-width: 132px; }
+    @media (max-width: 640px) {
+      .up-meta { grid-template-columns: 1fr; }
+      .cover-box { max-width: none; width: 100%; }
+      .drop-btn { display: none; }
+    }
+
     /* ---------- login ---------- */
     .gate { max-width: 420px; margin: 12vh auto 0; text-align: center; }
     .gate .brand { justify-content: center; margin-bottom: 18px; font-size: 22px; }
@@ -125,6 +164,13 @@
     .song-row small { color: var(--text-dim); font-size: 12px; }
     .song-row .st { flex: none; font: 700 11px var(--ui); padding: 3px 9px; border-radius: 99px; border: 1px solid var(--line-2); color: var(--text-dim); }
     .song-row .st.has { color: var(--ok); border-color: rgba(74,222,128,.4); }
+    .song-open { display: flex; align-items: center; gap: 10px; min-width: 0; flex: 1; padding: 0; border: 0; background: none; color: inherit; text-align: left; }
+    .whisper-request { min-height: 44px; flex: none; }
+    .whisper-draft { margin-block: 14px; }
+    .whisper-draft pre { white-space: pre-wrap; overflow-wrap: anywhere; max-height: 180px; overflow: auto; font: 400 14px/1.55 var(--ui); color: var(--text); }
+    #whisperStatus { color: var(--text-dim); font-size: 14px; margin-block: 10px; }
+    .song { flex-wrap: wrap; }
+    @media (max-width: 480px) { .song-row { flex-wrap: wrap; } .song-open { flex-basis: 100%; min-height: 44px; } }
     .chips { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 12px; }
     .chip { height: 34px; padding: 0 13px; border-radius: 99px; border: 1px solid var(--line-2); background: rgba(255,255,255,.04); font-size: 13px; font-weight: 600; color: var(--text-2); max-width: 100%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
     .chip:hover { color: var(--text); border-color: var(--a1); }
@@ -172,7 +218,7 @@
     }
     .tc:hover { border-color: var(--a2); color: var(--text); }
     .ln.untimed .tc { color: var(--warn); border-style: dashed; border-color: rgba(255,180,84,.55); }
-    .ln-text { flex: 1 1 auto; min-width: 0; height: 38px; padding: 0 8px; border: 0; border-radius: 9px; background: transparent; font-size: 16px; }
+    .ln-text { flex: 1 1 auto; min-width: 0; min-height: 38px; height: auto; padding: 7px 8px; resize: vertical; overflow: hidden; line-height: 1.3; border: 0; border-radius: 9px; background: transparent; font-size: 16px; }
     .ln.section .ln-text { font-weight: 800; text-transform: uppercase; letter-spacing: .06em; font-size: 13px; color: var(--a2); }
     .ln.cue .ln-text { font-style: italic; color: var(--warn); }
     .ln.now { background: rgba(124,92,255,.16); border-color: rgba(124,92,255,.55); box-shadow: 0 0 0 1px rgba(124,92,255,.25), 0 10px 30px -16px var(--a1); }
@@ -218,6 +264,26 @@
     .tap small { display: block; font-weight: 600; opacity: .8; font-size: 11px; letter-spacing: 0; max-width: 84px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
     .tap:active { transform: scale(.93); }
 
+    .analytics-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 12px; margin: 20px 0; }
+    .metric { padding: 18px; background: var(--bg-2); border: 1px solid var(--line-2); border-radius: 14px; }
+    .metric b { display: block; font-size: 26px; margin: 4px 0; }
+    .metric small, .metric span { color: var(--text-2); }
+    .analytics-form { display: flex; flex-wrap: wrap; align-items: end; gap: 12px; }
+    .analytics-form label { display: grid; gap: 5px; min-width: 0; }
+    .analytics-form .query { flex: 1 1 250px; }
+    .analytics-form .field { width: 100%; min-width: 0; }
+    .analytics-form button { min-height: 44px; }
+    .analytics-table { overflow-x: auto; margin-top: 12px; }
+    .analytics-table table { width: 100%; }
+    .collection-job { padding: 14px 0; border-bottom: 1px solid var(--line-2); overflow-wrap: anywhere; }
+    .collection-job p { margin: 4px 0; color: var(--text-2); }
+    #metadataDetail { white-space: pre-wrap; overflow-wrap: anywhere; max-height: 400px; overflow: auto; font-size: 13px; }
+    @media (max-width: 480px) { .analytics-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); } .metric { padding: 12px; } .metric b { font-size: 22px; } }
+    @media (min-width: 761px) and (max-width: 1100px) {
+      .top { flex-wrap: wrap; }
+      .tabs { order: 2; width: 100%; margin-left: 0; overflow-x: auto; }
+      .tabs .tab { flex: none; }
+    }
     .nav { display: none; }
     @media (max-width: 760px) {
       .tabs, .top .ghost.desk { display: none; }
@@ -308,6 +374,7 @@
           <div class="ring" id="ring"><span id="ringTxt">0/0</span></div>
           <div style="min-width:0"><h1 id="songTitle"></h1><small id="songMeta"></small></div>
           <span class="grow"></span>
+          <button class="btn sm whisper-request" id="whisperBtn" type="button">Transcribe with Whisper</button>
           <button class="ghost" id="closeSong" type="button">Change song</button>
         </div>
 
@@ -347,8 +414,15 @@
         </div>
 
         <div id="msg" class="msg"></div>
+        <p id="whisperStatus" role="status" aria-live="polite"></p>
+        <div id="whisperResult" class="card whisper-draft hidden">
+          <h2 style="font-size:18px;margin:0 0 8px">Whisper transcript ready</h2>
+          <p class="muted">Saved lyrics stay unchanged until you review and save this draft.</p>
+          <pre id="whisperPreview"></pre>
+          <button id="whisperUse" class="btn" type="button">Use transcript in editor</button>
+        </div>
         <div id="lines" class="lines"></div>
-        <textarea id="raw" class="hidden" spellcheck="false"></textarea>
+        <textarea id="raw" aria-label="Lyrics as text; prefix continuation lines with vertical bar and space" class="hidden" spellcheck="false"></textarea>
         <div class="row" style="margin-top:14px">
           <button class="btn sm" id="addLine" type="button">＋ Add line</button>
           <span class="muted" style="font-size:12.5px">Shortcuts: <code>Space</code> stamp (Tap-sync) · <code>S</code> stamp selected · <code>K</code> play · <code>↑↓</code> select · <code>⌘/Ctrl S</code> save</span>
@@ -378,12 +452,28 @@
       <div class="card">
         <h2>Upload video / audio</h2>
         <p class="muted">Title, artist, duration, cover art and embedded lyrics are read from the file. A cover image or manual title/artist override them.</p>
-        <form id="upForm" class="row">
-          <input class="field" type="file" id="upFile" accept="video/*,audio/*" required />
-          <input class="field" type="text" id="upTitle" placeholder="Title (optional)" />
-          <input class="field" type="text" id="upArtist" placeholder="Artist (optional)" />
-          <label class="muted" style="display:flex;gap:8px;align-items:center;font-size:13px">Cover <input type="file" id="upArt" accept="image/*" /></label>
-          <button class="btn pri" type="submit">Upload</button>
+        <form id="upForm" class="up-form" novalidate>
+          <label class="drop" id="upDrop">
+            <input class="sr-file" type="file" id="upFile" accept="video/*,audio/*" />
+            <svg class="drop-ico" viewBox="0 0 24 24" aria-hidden="true"><path d="M12 15V4m-4.5 4.5L12 4l4.5 4.5M5 14v4.5A1.5 1.5 0 0 0 6.5 20h11a1.5 1.5 0 0 0 1.5-1.5V14"/></svg>
+            <span class="drop-text">
+              <strong id="upFileName">Choose a video or audio file</strong>
+              <span id="upFileMeta">or drop it here · mp4, mov, webm, mkv, mp3, m4a, flac, wav…</span>
+            </span>
+            <span class="drop-btn" aria-hidden="true">Browse</span>
+          </label>
+          <div class="up-meta">
+            <label class="fl"><span>Title</span><input class="field" type="text" id="upTitle" placeholder="From the file" autocomplete="off" /></label>
+            <label class="fl"><span>Artist</span><input class="field" type="text" id="upArtist" placeholder="From the file" autocomplete="off" /></label>
+            <label class="fl cover-pick" title="Cover image (optional)">
+              <span>Cover</span>
+              <input class="sr-file" type="file" id="upArt" accept="image/*" />
+              <span class="cover-box" id="upArtBox"><svg viewBox="0 0 24 24" aria-hidden="true"><rect x="3.5" y="3.5" width="17" height="17" rx="3"/><circle cx="9" cy="9.5" r="1.6"/><path d="m20 15-4.5-4.5L6 20"/></svg><em id="upArtName">Add image</em></span>
+            </label>
+          </div>
+          <div class="up-actions">
+            <button class="btn pri" type="submit" id="upSubmit">Upload</button>
+          </div>
         </form>
         <div id="upProgress" class="msg"></div>
         <div class="scroll"><table class="tbl" id="upTable"></table></div>
@@ -425,6 +515,35 @@
     </section>
 
     <!-- ================= ACCESS ================= -->
+    <section id="p-analytics" class="panel">
+      <h1 class="page">Server analytics</h1>
+      <p class="lead">Video storage, listening activity and the metadata library.</p>
+      <button class="btn" type="button" id="analyticsRefresh">Refresh analytics</button>
+      <p id="analyticsStatus" role="status" aria-live="polite"></p>
+      <div class="analytics-grid" id="analyticsMetrics"></div>
+      <div class="card"><h2>Remaining disk space</h2><div id="analyticsVolumes"></div><p class="muted">Volumes on the same device share the reported free space. Stored media totals exclude temporary files and filesystem overhead.</p></div>
+      <div class="card"><h2>Metadata collector</h2>
+        <p class="muted">Search and save descriptive video metadata and thumbnails. Video and audio files are not downloaded.</p>
+        <form id="collectorForm" class="analytics-form">
+          <label class="query">Search<input id="collectorQuery" class="field" type="search" maxlength="200" required placeholder="Cathedral of Praise Worship" /></label>
+          <label>Total video limit<input id="collectorLimit" class="field" type="number" min="1" max="500" value="30" required /></label>
+          <label>Related-search depth<select id="collectorDepth" class="field"><option value="0">0 · Search only</option><option value="1">1 · Channels and topics</option><option value="2">2 · Two related rounds</option><option value="3">3 · Three related rounds</option></select></label>
+          <button class="btn pri" type="submit" id="collectorStart">Collect metadata</button>
+        </form>
+        <p class="muted">The limit applies across every round. Depth follows channels and tags found in video metadata, with at most 24 searches. A collection can return fewer videos when results repeat or sources are unavailable. Thumbnails follow the server’s storage budget.</p>
+        <p id="collectorStatus" role="status" aria-live="polite"></p><div id="collectionJobs"></div>
+      </div>
+      <div class="card"><h2>Metadata library</h2>
+        <form id="metadataFilterForm" class="analytics-form"><label class="query">Filter saved metadata<input id="metadataFilter" class="field" type="search" maxlength="200" placeholder="Title, channel or tag" /></label><button class="btn" type="submit">Filter</button></form>
+        <p id="metadataCount" class="muted"></p>
+        <div class="analytics-table"><table id="metadataTable"></table></div>
+        <div class="row"><button id="metadataPrev" class="btn" type="button">Previous</button><button id="metadataNext" class="btn" type="button">Next</button></div>
+        <details id="metadataDetails" class="hidden"><summary>Video metadata</summary><pre id="metadataDetail"></pre></details>
+      </div>
+      <div class="card"><h2>Discovery sources</h2><div class="analytics-table"><table id="analyticsSources"></table></div></div>
+      <div class="card"><h2>Most played</h2><div id="analyticsTop"></div></div>
+    </section>
+
     <section id="p-access" class="panel">
       <h1 class="page">API access</h1>
       <p class="lead">Tokens let scripts write shared lyrics and chapters. A token is shown once — store it in your secrets vault.</p>
@@ -450,6 +569,7 @@
   <nav class="nav" id="tabsBottom" role="tablist"></nav>
 </div>
 
+<script src="lyrics-core.js"></script>
 <script>
 (function () {
   'use strict';
@@ -482,9 +602,10 @@
     library: '<path d="M9 18V6l10-2v12"/><circle cx="6.5" cy="18" r="2.5"/><circle cx="16.5" cy="16" r="2.5"/>',
     peers: '<circle cx="6" cy="12" r="2.5"/><circle cx="18" cy="6" r="2.5"/><circle cx="18" cy="18" r="2.5"/><path d="M8.3 10.9l7.4-3.8M8.3 13.1l7.4 3.8"/>',
     history: '<path d="M3 12a9 9 0 109-9 9 9 0 00-6.4 2.6L3 8"/><path d="M3 3v5h5M12 7v5l3 2"/>',
+    analytics: '<path d="M4 20h16M7 16V9M12 16V4M17 16v-5"/>',
     access: '<circle cx="8" cy="15" r="4"/><path d="M11 12l9-9M16 7l3 3M14 9l2 2"/>',
   };
-  const TABS = [['editor', 'Editor'], ['reports', 'Reports'], ['library', 'Library'], ['peers', 'P2P'], ['history', 'History'], ['access', 'API']];
+  const TABS = [['editor', 'Editor'], ['reports', 'Reports'], ['library', 'Library'], ['peers', 'P2P'], ['history', 'History'], ['analytics', 'Stats'], ['access', 'API']];
   let tab = 'editor';
   function buildTabs() {
     const html = TABS.map(([k, l]) => `<button class="tab" role="tab" data-tab="${k}" aria-selected="false"><svg viewBox="0 0 24 24">${ICONS[k]}</svg><span>${l}</span>${k === 'reports' ? '<span class="badge hidden" data-badge>0</span>' : ''}</button>`).join('');
@@ -503,6 +624,7 @@
     if (name === 'peers') loadP2p();
     if (name === 'library') loadUploads();
     if (name === 'access') loadTokens();
+    if (name === 'analytics') loadAnalytics();
     window.scrollTo({ top: 0 });
   }
   function setBadge(n) {
@@ -541,6 +663,67 @@
   });
   $('logoutBtn').addEventListener('click', async () => { await api('/api/admin/logout', { method: 'POST' }); showLogin(); });
 
+  /* ---------------- server analytics / metadata collection ---------------- */
+  let analyticsTimer = null, metadataOffset = 0;
+  const bytes = value => { let size = Number(value) || 0, unit = 0; const units = ['B','KB','MB','GB','TB']; while (size >= 1024 && unit < 4) { size /= 1024; unit++; } return `${size.toFixed(unit ? 1 : 0)} ${units[unit]}`; };
+  async function loadAnalytics() {
+    $('analyticsStatus').textContent = 'Loading server analytics…';
+    try {
+      const j = await api('/api/admin/analytics');
+      if (!j.ok) throw Error(j.error || 'Analytics unavailable.');
+      const ready = j.media.find(row => row.status === 'ready') || {}, uploadBytes = j.uploads.reduce((total, row) => total + Number(row.bytes), 0);
+      const metrics = [
+        ['Stored media', bytes(Number(ready.bytes || 0) + uploadBytes), `${ready.count || 0} cached videos · ${j.uploads.reduce((sum, row) => sum + Number(row.count), 0)} uploads`],
+        ['Metadata videos', Number(j.catalog.videos).toLocaleString(), `${j.details.videos} with detailed extractor metadata`],
+        ['Saved thumbnails', Number(j.thumbnails.saved || 0).toLocaleString(), `${bytes(j.thumbnails.bytes)} · ${j.thumbnails.pending || 0} awaiting download`],
+        ['Recorded plays', Number(j.listening.plays).toLocaleString(), `${j.listening.videos} different videos`],
+        ['Cached video size', bytes(ready.bytes), `${Math.round(Number(ready.seconds || 0) / 3600)} hours of audio/video`],
+        ['Upload size', bytes(uploadBytes), 'Server media library'],
+        ['Metadata size', bytes(Number(j.catalog.bytes) + Number(j.details.bytes)), 'JSON payloads; database indexes excluded'],
+        ['Cache queue', j.media.filter(row => row.status !== 'ready').reduce((sum, row) => sum + Number(row.count), 0), j.media.filter(row => row.status !== 'ready').map(row => `${row.status}: ${row.count}`).join(' · ') || 'No pending downloads'],
+      ];
+      $('analyticsMetrics').innerHTML = metrics.map(([label, value, detail]) => `<div class="metric"><span>${esc(label)}</span><b>${esc(value)}</b><small>${esc(detail)}</small></div>`).join('');
+      $('analyticsVolumes').innerHTML = j.volumes.map(v => `<p><b>${esc(v.label)}</b> · ${v.unavailable ? 'Storage unavailable' : `${bytes(v.free)} available of ${bytes(v.total)} · device ${esc(v.device)}`}</p>`).join('');
+      $('analyticsSources').innerHTML = '<tr><th>Source</th><th>Videos</th><th>Discoveries</th></tr>' + j.sources.map(row => `<tr><td>${esc(row.source)}</td><td>${esc(row.videos)}</td><td>${esc(row.discoveries)}</td></tr>`).join('');
+      $('analyticsTop').innerHTML = j.topPlayed.length ? j.topPlayed.map(row => `<p>${esc(row.title)} · <b>${esc(row.plays)} plays</b></p>`).join('') : '<p class="muted">No listening activity recorded yet.</p>';
+      $('analyticsStatus').textContent = 'Updated ' + new Date().toLocaleTimeString();
+      await Promise.all([loadCollections(), loadMetadata()]);
+    } catch (error) { $('analyticsStatus').textContent = error.message || 'Could not load server analytics.'; }
+  }
+  async function loadCollections() {
+    try {
+      const j = await api('/api/admin/collections'); if (!j.ok) return;
+      $('collectionJobs').innerHTML = j.jobs.length ? j.jobs.map(job => `<div class="collection-job"><b>${esc(job.query)}</b> · ${esc(job.status)}<p>${job.collected}/${job.maxVideos} videos collected · ${job.enriched} enriched · ${job.failed} failed · ${job.searches} searches · depth ${job.depth}</p>${job.current ? `<p>Working on ${esc(job.current)}</p>` : ''}${job.error ? `<p>${esc(job.error)}</p>` : ''}${job.errors?.length ? `<details><summary>Extraction errors</summary>${job.errors.map(e => `<p>${esc(e.id)}: ${esc(e.error)}</p>`).join('')}</details>` : ''}${['queued','running'].includes(job.status) ? `<button class="btn" type="button" data-cancel-collection="${esc(job.id)}">Stop collection</button>` : ''}</div>`).join('') : '<p class="muted">No collections yet.</p>';
+      clearTimeout(analyticsTimer); analyticsTimer = null;
+      if (tab === 'analytics' && j.jobs.some(job => ['queued','running'].includes(job.status))) analyticsTimer = setTimeout(loadCollections, 4000);
+    } catch { $('collectorStatus').textContent = 'Connection interrupted. Collection continues on the server.'; }
+  }
+  async function loadMetadata() {
+    const j = await api(`/api/admin/metadata?q=${encodeURIComponent($('metadataFilter').value)}&offset=${metadataOffset}`); if (!j.ok) return;
+    $('metadataCount').textContent = `${j.total} saved videos · ${j.total ? metadataOffset + 1 : 0}–${metadataOffset + j.videos.length}`;
+    $('metadataTable').innerHTML = '<tr><th>Video</th><th>Metadata</th><th>Thumbnail</th></tr>' + j.videos.map(v => `<tr><td><button class="btn sm" type="button" data-metadata-id="${esc(v.id)}">${esc(v.title)}</button><br><small>${esc(v.channel)} · ${Number(v.duration) > 0 ? Math.round(Number(v.duration)) + 's' : 'Duration unavailable'}</small></td><td>${v.enriched ? 'Detailed' : 'Search card'}</td><td>${v.thumbnailBytes ? bytes(v.thumbnailBytes) : 'Pending / unavailable'}</td></tr>`).join('');
+    $('metadataPrev').disabled = metadataOffset === 0; $('metadataNext').disabled = metadataOffset + 50 >= j.total;
+  }
+  $('analyticsRefresh').addEventListener('click', loadAnalytics);
+  $('collectorForm').addEventListener('submit', async e => {
+    e.preventDefault(); $('collectorStart').disabled = true; $('collectorStatus').textContent = 'Queuing collection…';
+    try {
+      const j = await api('/api/admin/collections', { method: 'POST', body: { query: $('collectorQuery').value, maxVideos: Number($('collectorLimit').value), depth: Number($('collectorDepth').value) } });
+      $('collectorStatus').textContent = j.ok ? 'Collection queued. You can leave this page while it runs.' : j.error || 'Could not start collection.';
+      if (j.ok) await loadCollections();
+    } catch { $('collectorStatus').textContent = 'Could not reach the server.'; }
+    finally { $('collectorStart').disabled = false; }
+  });
+  $('collectionJobs').addEventListener('click', async e => { const btn = e.target.closest('[data-cancel-collection]'); if (!btn) return; await api('/api/admin/collections/' + btn.dataset.cancelCollection + '/cancel', { method: 'POST', body: {} }); await loadCollections(); });
+  $('metadataFilterForm').addEventListener('submit', e => { e.preventDefault(); metadataOffset = 0; loadMetadata(); });
+  $('metadataPrev').addEventListener('click', () => { metadataOffset = Math.max(0, metadataOffset - 50); loadMetadata(); });
+  $('metadataNext').addEventListener('click', () => { metadataOffset += 50; loadMetadata(); });
+  $('metadataTable').addEventListener('click', async e => {
+    const btn = e.target.closest('[data-metadata-id]'); if (!btn) return;
+    const j = await api('/api/admin/metadata/' + btn.dataset.metadataId); if (!j.ok) return;
+    $('metadataDetail').textContent = JSON.stringify(j.metadata, null, 2); $('metadataDetails').classList.remove('hidden'); $('metadataDetails').open = true;
+  });
+
   /* ---------------- tokens / inject ---------------- */
   async function loadTokens() {
     const j = await api('/api/admin/tokens');
@@ -633,9 +816,38 @@
     $('upTable').innerHTML = rows ? `<tr><th></th><th>Title</th><th>Kind</th><th>Size</th><th>Id</th><th></th></tr>${rows}` : '<tr><td class="muted">Nothing uploaded yet.</td></tr>';
     return j.uploads || [];
   }
+  // Upload card: show the chosen file / cover, accept drag-and-drop.
+  const fmtSize = (n) => n >= 1073741824 ? (n / 1073741824).toFixed(1) + ' GB' : n >= 1048576 ? (n / 1048576).toFixed(1) + ' MB' : Math.max(1, Math.round(n / 1024)) + ' KB';
+  function paintUpFile() {
+    const f = $('upFile').files[0];
+    $('upDrop').classList.toggle('has', !!f);
+    $('upFileName').textContent = f ? f.name : 'Choose a video or audio file';
+    $('upFileMeta').textContent = f ? `${fmtSize(f.size)} · ${f.type || 'media file'} · click to change` : 'or drop it here · mp4, mov, webm, mkv, mp3, m4a, flac, wav…';
+  }
+  function paintUpArt() {
+    const f = $('upArt').files[0];
+    const box = $('upArtBox');
+    const old = box.querySelector('img'); if (old) { URL.revokeObjectURL(old.src); old.remove(); }
+    box.querySelector('svg').style.display = f ? 'none' : '';
+    $('upArtName').textContent = f ? f.name : 'Add image';
+    if (f) { const img = document.createElement('img'); img.alt = ''; img.src = URL.createObjectURL(f); box.prepend(img); }
+  }
+  $('upFile').addEventListener('change', paintUpFile);
+  $('upArt').addEventListener('change', paintUpArt);
+  $('upForm').addEventListener('reset', () => setTimeout(() => { paintUpFile(); paintUpArt(); }, 0));
+  ['dragenter', 'dragover'].forEach((t) => $('upDrop').addEventListener(t, (e) => { e.preventDefault(); $('upDrop').classList.add('over'); }));
+  ['dragleave', 'drop'].forEach((t) => $('upDrop').addEventListener(t, () => $('upDrop').classList.remove('over')));
+  $('upDrop').addEventListener('drop', (e) => {
+    e.preventDefault();
+    const f = e.dataTransfer && e.dataTransfer.files && e.dataTransfer.files[0];
+    if (!f) return;
+    const dt = new DataTransfer(); dt.items.add(f); $('upFile').files = dt.files; paintUpFile();
+  });
+
   $('upForm').addEventListener('submit', (e) => {
     e.preventDefault();
-    const f = $('upFile').files[0]; if (!f) return;
+    const f = $('upFile').files[0];
+    if (!f) { const m = $('upProgress'); m.className = 'msg err'; m.textContent = 'Choose a video or audio file first.'; $('upDrop').focus(); $('upFile').click(); return; }
     const qs = new URLSearchParams({ name: f.name });
     if ($('upTitle').value.trim()) qs.set('title', $('upTitle').value.trim());
     if ($('upArtist').value.trim()) qs.set('artist', $('upArtist').value.trim());
@@ -692,13 +904,18 @@
   function paintSongs() {
     const q = $('songFilter').value.trim().toLowerCase();
     const rows = SONGS.filter((r) => !q || (r.title + ' ' + (r.sub || '')).toLowerCase().includes(q));
-    $('songList').innerHTML = rows.length ? rows.map((r) => `<button type="button" class="song-row" data-open="${esc(r.id)}">
+    $('songList').innerHTML = rows.length ? rows.map((r) => `<div class="song-row"><button type="button" class="song-open" data-open="${esc(r.id)}">
       <span style="min-width:0;flex:1"><b>${esc(r.title)}</b><small>${esc(r.sub || '')}</small></span>
-      <span class="st ${r.lines > 0 ? 'has' : ''}">${r.lines > 0 ? `${r.lines} lines` : r.lines === 0 ? 'no lyrics' : 'open'}</span></button>`).join('')
+      <span class="st ${r.lines > 0 ? 'has' : ''}">${r.lines > 0 ? `${r.lines} lines` : r.lines === 0 ? 'no lyrics' : 'open'}</span></button>
+      <button type="button" class="btn sm whisper-request" data-whisper="${esc(r.id)}" aria-label="Transcribe ${esc(r.title)} with Whisper">Whisper</button></div>`).join('')
       : '<div class="muted" style="padding:10px">Nothing matches — paste a link above to open any YouTube song.</div>';
+    paintWhisper();
   }
   $('songFilter').addEventListener('input', paintSongs);
-  $('songList').addEventListener('click', (e) => { const b = e.target.closest('[data-open]'); if (b) leOpen(b.dataset.open); });
+  $('songList').addEventListener('click', (e) => {
+    const whisper = e.target.closest('[data-whisper]'); if (whisper) { startWhisper(whisper.dataset.whisper); return; }
+    const b = e.target.closest('[data-open]'); if (b) leOpen(b.dataset.open);
+  });
   $('recentChips').addEventListener('click', (e) => { const b = e.target.closest('[data-open]'); if (b) leOpen(b.dataset.open); });
 
   /* ---------------- p2p ---------------- */
@@ -823,6 +1040,67 @@
     $('save').disabled = !on;
     $('discard').disabled = !on;
   }
+
+  const whisperJobs = new Map(), whisperStarting = new Set();
+  let whisperTimer = null;
+  const activeWhisper = job => job && (job.status === 'queued' || job.status === 'running');
+  function paintWhisper() {
+    document.querySelectorAll('[data-whisper]').forEach(btn => {
+      const job = whisperJobs.get(btn.dataset.whisper);
+      btn.disabled = whisperStarting.has(btn.dataset.whisper) || activeWhisper(job);
+      btn.textContent = job?.status === 'running' ? 'Transcribing…' : job?.status === 'queued' ? 'Queued' : 'Whisper';
+    });
+    const job = whisperJobs.get(LE.id);
+    $('whisperBtn').disabled = whisperStarting.has(LE.id) || activeWhisper(job);
+    $('whisperBtn').textContent = activeWhisper(job) ? (job.status === 'queued' ? 'Whisper queued' : 'Whisper transcribing…') : 'Transcribe with Whisper';
+    const labels = { 'loading-model': 'Whisper is loading its model…', 'downloading-audio': 'Whisper is reading the song’s audio…', transcribing: 'Whisper is transcribing the vocals. This can take several minutes.' };
+    $('whisperStatus').textContent = job?.status === 'queued' ? 'Queued for Whisper. Waiting for the lyrics worker.'
+      : job?.status === 'running' ? labels[job.stage] || 'Whisper is working…'
+      : job?.status === 'failed' ? 'Whisper could not finish: ' + (job.error || 'Try again.') : '';
+    const ready = job?.status === 'complete' && job.result?.lines?.length;
+    $('whisperResult').classList.toggle('hidden', !ready);
+    $('whisperPreview').textContent = ready ? job.result.lines.map(l => l.text).join('\n') : '';
+  }
+  async function refreshWhisper(id) {
+    try {
+      const result = await api('/api/admin/transcriptions/' + encodeURIComponent(id));
+      if (result.ok) whisperJobs.set(id, result.job);
+      paintWhisper(); scheduleWhisper();
+    } catch { /* a reconnect or another poll can recover the durable job */ }
+  }
+  function scheduleWhisper() {
+    if (whisperTimer || ![...whisperJobs.values()].some(activeWhisper)) return;
+    whisperTimer = setTimeout(async () => {
+      whisperTimer = null;
+      for (const [id, job] of whisperJobs) if (activeWhisper(job)) await refreshWhisper(id);
+      scheduleWhisper();
+    }, 5000);
+  }
+  async function startWhisper(id) {
+    if (!id || whisperStarting.has(id) || activeWhisper(whisperJobs.get(id))) return;
+    whisperStarting.add(id); paintWhisper();
+    try {
+      if (LE.id !== id || !LE.loaded) { const opened = await leOpen(id); if (opened === false) return; }
+      const result = await api('/api/admin/transcriptions/' + encodeURIComponent(id), { method: 'POST', body: {} });
+      if (!result.ok) { say(result.error || 'Whisper could not start.', 'err'); return; }
+      whisperJobs.set(id, result.job); paintWhisper(); scheduleWhisper();
+    } catch { say('Could not reach Whisper. Try again when connected.', 'err'); }
+    finally { whisperStarting.delete(id); paintWhisper(); }
+  }
+  $('whisperBtn').addEventListener('click', () => startWhisper(LE.id));
+  $('whisperUse').addEventListener('click', () => {
+    const job = whisperJobs.get(LE.id); if (job?.status !== 'complete' || !job.result?.lines?.length) return;
+    if (LE.dirty && !confirm('Replace your unsaved editor text with the Whisper draft? Undo can restore it.')) return;
+    edit(() => {
+      LE.lines = job.result.lines.map(l => ({ ...l })); LE.offset = 0;
+      LE.tags = [...LE.tags.filter(t => !/^(from |auto-transcribed)/i.test(t)), ...job.result.tags];
+      LE.raw = false; $('raw').classList.add('hidden'); $('lines').classList.remove('hidden');
+      $('rawBtn').textContent = '✎ Edit as text'; $('tags').value = LE.tags.join(', ');
+    });
+    render(); draw(); syncBars();
+    $('whisperResult').classList.add('hidden');
+    say('Whisper draft loaded. Check the words and timing, then Save to publish; Undo restores the previous text.', 'ok');
+  });
   function progress() {
     const timed = LE.lines.filter((l) => l.kind === 'line' && l.t != null).length;
     const all = LE.lines.filter((l) => l.kind === 'line').length;
@@ -835,10 +1113,10 @@
   }
 
   /* undo / redo — whole-document snapshots, typing is coalesced */
-  const snap = () => JSON.stringify({ l: LE.lines, t: LE.tags });
+  const snap = () => JSON.stringify({ l: LE.lines, t: LE.tags, o: LE.offset });
   function pushUndo() { LE.undo.push(snap()); if (LE.undo.length > 100) LE.undo.shift(); LE.redo = []; undoBtns(); }
   function undoBtns() { $('bUndo').disabled = !LE.undo.length; $('bRedo').disabled = !LE.redo.length; }
-  function restore(s) { const o = JSON.parse(s); LE.lines = o.l; LE.tags = o.t; $('tags').value = LE.tags.join(', '); render(); setDirty(true); undoBtns(); }
+  function restore(s) { const o = JSON.parse(s); LE.lines = o.l; LE.tags = o.t; LE.offset = o.o ?? LE.offset; $('tags').value = LE.tags.join(', '); render(); setDirty(true); undoBtns(); }
   function doUndo() { if (!LE.undo.length) return; LE.redo.push(snap()); restore(LE.undo.pop()); say('Undone'); }
   function doRedo() { if (!LE.redo.length) return; LE.undo.push(snap()); restore(LE.redo.pop()); say('Redone'); }
   let typing = null;
@@ -873,6 +1151,7 @@
     $('raw').classList.add('hidden'); $('lines').classList.remove('hidden'); $('rawBtn').textContent = '✎ Edit as text';
     await loadFlags();
     render(); setDirty(false); undoBtns(); syncBars();
+    paintWhisper(); refreshWhisper(id);
     say('');
     if (!keepAudio) initAudio(id, streams);
     draw();
@@ -909,7 +1188,7 @@
     row.innerHTML = `
       <div class="ln-main">
         <button class="tc" data-act="chip" type="button"></button>
-        <input class="ln-text" value="${esc(line.text)}" placeholder="Type the line…" aria-label="Line text" />
+        <textarea class="ln-text" rows="1" placeholder="Type the line… (Shift+Enter for a line break)" aria-label="Line text">${esc(line.text)}</textarea>
         <span class="flagchip hidden" data-flag><svg viewBox="0 0 24 24"><path d="M5 21V4M5 4h11l-2 4 2 4H5"/></svg><b></b></span>
         <button class="more" data-act="more" type="button" aria-label="Line options">⋯</button>
       </div>
@@ -921,9 +1200,12 @@
         <button class="btn" data-act="nudge" data-d="-0.2" type="button">−0.2</button>
         <button class="btn" data-act="nudge" data-d="0.2" type="button">+0.2</button>
         <select class="mini" data-kind aria-label="Line type"><option value="line">Line</option><option value="section">Section</option><option value="cue">Cue</option></select>
+        <button class="btn" data-act="break" type="button" title="Same timestamp, both lines highlight together">↵ Line break</button>
         <button class="btn" data-act="add" type="button">＋ Below</button>
         <button class="btn dng" data-act="del" type="button">Delete</button>
       </div>`;
+    const text = row.querySelector('.ln-text');
+    text.rows = Math.max(1, line.text.split('\n').length);
     row.querySelector('[data-kind]').value = line.kind;
     return row;
   }
@@ -952,6 +1234,9 @@
     LE.rows = LE.lines.map((l, i) => { const r = rowEl(l, i); box.appendChild(r); return r; });
     if (!LE.lines.length) box.innerHTML = '<div class="empty">No lines yet — press “＋ Add line”, paste text with ✎ Edit as text, or pull them from LRCLIB (⋯ tools).</div>';
     LE.lines.forEach((_, i) => paintRow(i));
+    const fields = LE.rows.map(row => row.querySelector('.ln-text'));
+    const heights = fields.map(field => field.scrollHeight);
+    fields.forEach((field, i) => { field.style.height = heights[i] + 'px'; });
     paintFlags(); progress(); lastIdx = -2; tick(); tapLabel();
     $('songMeta').textContent = $('songMeta').textContent.replace(/\d+ lines/, `${LE.lines.length} lines`);
   }
@@ -1025,6 +1310,13 @@
     else if (act === 'set') stamp(i);
     else if (act === 'seek') { seek((LE.lines[i].t || 0) + LE.offset); if (LE.audio && LE.audio.paused) LE.audio.play().catch(() => {}); }
     else if (act === 'nudge') { if (LE.lines[i].t == null) return; edit(() => { LE.lines[i].t = r2(Math.max(0, LE.lines[i].t + Number(btn.dataset.d))); }); paintRow(i); draw(); }
+    else if (act === 'break') {
+      const text = LE.rows[i].querySelector('.ln-text');
+      const pos = text.selectionStart;
+      edit(() => { LE.lines[i].text = text.value.slice(0, pos) + '\n' + text.value.slice(text.selectionEnd); });
+      render(); select(i);
+      const target = LE.rows[i].querySelector('.ln-text'); target.focus(); target.setSelectionRange(pos + 1, pos + 1);
+    }
     else if (act === 'add') { edit(() => LE.lines.splice(i + 1, 0, { t: null, text: '', kind: 'line' })); render(); select(i + 1); LE.rows[i + 1].querySelector('.ln-text').focus(); }
     else if (act === 'del') { edit(() => LE.lines.splice(i, 1)); LE.sel = -1; render(); draw(); }
     else if (act === 'resolve') {
@@ -1034,7 +1326,7 @@
   });
   $('lines').addEventListener('input', (e) => {
     const row = e.target.closest('.ln'); if (!row) return; const i = Number(row.dataset.i);
-    if (e.target.classList.contains('ln-text')) { typed(); LE.lines[i].text = e.target.value; setDirty(true); tapLabel(); }
+    if (e.target.classList.contains('ln-text')) { typed(); LE.lines[i].text = e.target.value; e.target.rows = Math.max(1, e.target.value.split('\n').length); e.target.style.height = 'auto'; e.target.style.height = e.target.scrollHeight + 'px'; setDirty(true); tapLabel(); }
   });
   $('lines').addEventListener('change', (e) => {
     const row = e.target.closest('.ln'); if (!row) return; const i = Number(row.dataset.i);
@@ -1044,6 +1336,7 @@
   $('lines').addEventListener('focusin', (e) => { const row = e.target.closest('.ln'); if (row && Number(row.dataset.i) !== LE.sel) select(Number(row.dataset.i)); });
   $('lines').addEventListener('keydown', (e) => {
     if (e.key !== 'Enter' || !e.target.classList.contains('ln-text')) return;
+    if (e.shiftKey) return; // Native textarea break stays in the current timed cue.
     e.preventDefault();
     const i = Number(e.target.closest('.ln').dataset.i);
     edit(() => LE.lines.splice(i + 1, 0, { t: null, text: '', kind: LE.lines[i].kind === 'section' ? 'line' : LE.lines[i].kind }));
@@ -1115,17 +1408,10 @@
     $('raw').classList.toggle('hidden', !LE.raw); $('lines').classList.toggle('hidden', LE.raw);
     $('rawBtn').textContent = LE.raw ? '≡ Back to lines' : '✎ Edit as text';
     if (LE.raw) {
-      $('raw').value = LE.lines.map((l) => (l.t == null ? '' : `[${fmtT(l.t)}] `) + (l.kind === 'section' ? '# ' : l.kind === 'cue' ? '! ' : '') + l.text).join('\n');
+      $('raw').value = LyricsCore.toText({ lines: LE.lines });
     } else {
       pushUndo();
-      LE.lines = $('raw').value.split('\n').map((raw) => {
-        let rest = raw.trim(), t = null;
-        const m = rest.match(/^\[(\d{1,3}):(\d{1,2}(?:[.:]\d{1,3})?)\]\s*/);
-        if (m) { t = r2(Number(m[1]) * 60 + Number(m[2].replace(':', '.'))); rest = rest.slice(m[0].length); }
-        let kind = 'line';
-        if (rest.startsWith('# ')) { kind = 'section'; rest = rest.slice(2); } else if (rest.startsWith('! ')) { kind = 'cue'; rest = rest.slice(2); }
-        return { t, text: rest, kind };
-      }).filter((l) => l.text);
+      LE.lines = LyricsCore.fromText($('raw').value).lines;
       setDirty(true); render(); draw();
     }
     syncBars();
@@ -1158,12 +1444,12 @@
     leOpen(id);
   });
   function leOpen(id, focusText) {
-    if (LE.dirty && id !== LE.id && !confirm('Discard the unsaved changes to the song you have open?')) return;
+    if (LE.dirty && id !== LE.id && !confirm('Discard the unsaved changes to the song you have open?')) return false;
     showTab('editor');
     if (id === LE.id && LE.loaded && focusText) {
       const i = LE.lines.findIndex((l) => l.text === focusText); if (i >= 0) select(i, true, true); return;
     }
-    leLoad(id, false, focusText);
+    return leLoad(id, false, focusText);
   }
 
   function renderDocs() {

frontend/app-seams.test.js

@@ -0,0 +1,85 @@
+const {test}=require('node:test');
+const assert=require('node:assert/strict');
+const {readFileSync}=require('node:fs');
+const {createHash}=require('node:crypto');
+const {join}=require('node:path');
+const app=readFileSync(join(__dirname,'app.js'),'utf8');
+test('Phase 4 preserves the exact player, continuity, tracking and queue bodies',()=>{
+ {const start=app.indexOf("const Player = {");assert.ok(start>=0,"Player");const body=app.slice(start,start+30343);assert.equal(createHash('sha256').update(body).digest('hex'),"373df46f4f994717472d26a6bac07449f6ca0a930cb666bfe3895d1dc65aa351","Player body unchanged");}
+ {const start=app.indexOf("const Transition = (() => {");assert.ok(start>=0,"Transition");const body=app.slice(start,start+8588);assert.equal(createHash('sha256').update(body).digest('hex'),"71997a537078308a41f0cbf8e29fd1658fb3a199c4f5a25d8af0931f1c2a6d50","Transition body unchanged");}
+ {const start=app.indexOf("const Wave = (() => {");assert.ok(start>=0,"Wave");const body=app.slice(start,start+5241);assert.equal(createHash('sha256').update(body).digest('hex'),"7252f4e856c59aef8aabfcd394ce4bcba656110cbd01a1a8af662eeb48166a3c","Wave body unchanged");}
+ {const start=app.indexOf("const StatsTrack = (() => {");assert.ok(start>=0,"StatsTrack");const body=app.slice(start,start+1462);assert.equal(createHash('sha256').update(body).digest('hex'),"9aae2631ba3bfad918319579b7120814af06c84949394d04e52c65345332d514","StatsTrack body unchanged");}
+ {const start=app.indexOf("function wirePlayerEvents() {");assert.ok(start>=0,"wirePlayerEvents");const body=app.slice(start,start+4913);assert.equal(createHash('sha256').update(body).digest('hex'),"1c5a2b5ce310f6aef6764325eda85a95f47e4f507f2049036ce1da206379908c","wirePlayerEvents body unchanged");}
+ {const start=app.indexOf("function updatePlayBtn() {");assert.ok(start>=0,"updatePlayBtn");const body=app.slice(start,start+522);assert.equal(createHash('sha256').update(body).digest('hex'),"1326233af07ae92a5ecc81cc211bd98d21ed5f291dc4eb59d040b8df9baba8c8","updatePlayBtn body unchanged");}
+ {const start=app.indexOf("function persist() {");assert.ok(start>=0,"persist");const body=app.slice(start,start+147);assert.equal(createHash('sha256').update(body).digest('hex'),"01e5c5dbc80616266db09b3829dc45b66476a3256b1c169d8e44f4983b24ac45","persist body unchanged");}
+ {const start=app.indexOf("function playFromList(list, index, source = '', { playFull = false } = {}) {");assert.ok(start>=0,"playFromList");const body=app.slice(start,start+401);assert.equal(createHash('sha256').update(body).digest('hex'),"f8009c9674b3478959997dca881fb7b9e1ab3708c98e5abdf1958d752e47ee41","playFromList body unchanged");}
+ {const start=app.indexOf("function advanceQueue() {");assert.ok(start>=0,"advanceQueue");const body=app.slice(start,start+596);assert.equal(createHash('sha256').update(body).digest('hex'),"be405b9c163e3d41a949ef11f6022ef13115b04083e3b6ad21d97beba1f45ae6","advanceQueue body unchanged");}
+ {const start=app.indexOf("function playNext() {");assert.ok(start>=0,"playNext");const body=app.slice(start,start+143);assert.equal(createHash('sha256').update(body).digest('hex'),"859d2ffd2e8c89a8d9c0dd0cf429fd403675452cedba2e34aa3dc72683d4f8c6","playNext body unchanged");}
+ {const start=app.indexOf("function playPrev() {");assert.ok(start>=0,"playPrev");const body=app.slice(start,start+268);assert.equal(createHash('sha256').update(body).digest('hex'),"ece8d33bd03c8146a6a702534c8fed50ff606170685b08d730b19d9d3c68cf48","playPrev body unchanged");}
+ {const start=app.indexOf("function onTrackEnded() {");assert.ok(start>=0,"onTrackEnded");const body=app.slice(start,start+702);assert.equal(createHash('sha256').update(body).digest('hex'),"d6e147238ad9656fa1c2335973b37597749bcfd02df1a66390b306fe1194ae0d","onTrackEnded body unchanged");}
+ {const start=app.indexOf("function sleepFadeSec() {");assert.ok(start>=0,"sleepFadeSec");const body=app.slice(start,start+138);assert.equal(createHash('sha256').update(body).digest('hex'),"3f986c8cc474d8313476e9c209b9264e3724011ffaee887f47178bb5155a4d77","sleepFadeSec body unchanged");}
+ {const start=app.indexOf("function applySleepFade(remaining) {");assert.ok(start>=0,"applySleepFade");const body=app.slice(start,start+346);assert.equal(createHash('sha256').update(body).digest('hex'),"9bd0fa697b271c6b80c128ff1d0a7b00afcb3ccf08f98b5c7e7dc86fd4329681","applySleepFade body unchanged");}
+ {const start=app.indexOf("function startSleepTimer(minutes, { endOfSong = false } = {}) {");assert.ok(start>=0,"startSleepTimer");const body=app.slice(start,start+487);assert.equal(createHash('sha256').update(body).digest('hex'),"f0a93401ab90196096074cb607b28d52c5903e11dbdfb8ddb95114e143af2409","startSleepTimer body unchanged");}
+ {const start=app.indexOf("function cancelSleepTimer() {");assert.ok(start>=0,"cancelSleepTimer");const body=app.slice(start,start+253);assert.equal(createHash('sha256').update(body).digest('hex'),"cf396ab758a70eede6af7444539a82ca15af801a9a57024dd5542067e9fa771a","cancelSleepTimer body unchanged");}
+ {const start=app.indexOf("function finishSleep() {");assert.ok(start>=0,"finishSleep");const body=app.slice(start,start+662);assert.equal(createHash('sha256').update(body).digest('hex'),"7ee93bf760bad5f39f4644339963918c5b369b2acc554b8e561c1a1f070ac6fb","finishSleep body unchanged");}
+ {const start=app.indexOf("const EQ = (() => {");assert.ok(start>=0,"EQ");const body=app.slice(start,start+7917);assert.equal(createHash('sha256').update(body).digest('hex'),"f0cba011c94f33e6fd0ab778021f4c97238262dfa0a8dd40bf3f17149c227528","EQ body unchanged");}
+ {const start=app.indexOf("const EqRender = (() => {");assert.ok(start>=0,"EqRender");const body=app.slice(start,start+5912);assert.equal(createHash('sha256').update(body).digest('hex'),"f014dd41dafebc33f09e87be866074afd7a2443c5bb452103a435585353a828f","EqRender body unchanged");}
+ {const start=app.indexOf("const Level = (() => {");assert.ok(start>=0,"Level");const body=app.slice(start,start+3892);assert.equal(createHash('sha256').update(body).digest('hex'),"e48ad7797384ac31bb8b864662fc2a546b04470b981042f016874ba750957226","Level body unchanged");}
+});
+
+test('eager shell and Settings definitions load before app state and defer reading it',()=>{
+ const html=readFileSync(join(__dirname,'index.html'),'utf8');
+ for(const file of ['shell-core.js','views-core.js','section-rail.js']) {
+  assert.ok(html.indexOf('src="'+file+'"')<html.indexOf('src="app.js"'));
+  const vm=require('node:vm');const context=vm.createContext({window:{},document:{}});
+  // Evaluation before any data/$/els/Player declaration must be safe.
+  vm.runInContext(readFileSync(join(__dirname,file),'utf8'),context);
+ }
+ const views=readFileSync(join(__dirname,'views-core.js'),'utf8');
+ assert.ok(views.includes('async function renderSettings()'));
+});
+
+test('remote facade preserves synchronous no-session and loaded changed hooks',()=>{
+ const source=app.match(/\/\* Remote facade \*\/([\s\S]*?)\/\* End remote facade \*\//)?.[1];
+ assert.ok(source,'remote facade is present');
+ const context=require('node:vm').createContext({window:{},Lazy:{proxy:()=>({}),onLoad(){}}});
+ require('node:vm').runInContext(source+';globalThis.api=Remote;',context);
+ assert.equal(context.api.changed(),undefined);
+ let calls=0;context.window.YT={Remote:{changed:()=>{calls++;return 'sync';}}};
+ assert.equal(context.api.changed(),'sync');assert.equal(calls,1);
+});
+
+test('watch-party facade keeps playback decisions synchronous before and after loading',()=>{
+ const source=app.match(/\/\* Party facade \*\/([\s\S]*?)\/\* End party facade \*\//)?.[1];assert.ok(source);
+ const context=require('node:vm').createContext({window:{},Lazy:{proxy:()=>({}),onLoad(){}}});
+ require('node:vm').runInContext(source+';globalThis.api=Party;',context);
+ for(const method of ['guestActive','intercept','nextDJ'])assert.equal(context.api[method]('next'),false);
+ context.window.YT={Party:{guestActive:()=>true,intercept:action=>action==='next',nextDJ:()=>true}};
+ for(const method of ['guestActive','intercept','nextDJ'])assert.equal(context.api[method]('next'),true);
+});
+
+test('Share and External stay behind lazy entry proxies',()=>{
+ assert.match(app,/const Share = Lazy\.proxy\('feature:share-external'/);
+ assert.match(app,/const External = Lazy\.proxy\('feature:share-external'/);
+ const chunk=readFileSync(join(__dirname,'share-external.js'),'utf8');
+ const context=require('node:vm').createContext({window:{},navigator:{userAgent:''},location:{origin:'https://fixture.test'},isUploadId:()=>false});
+ require('node:vm').runInContext(chunk,context);
+ assert.equal(typeof context.window.YT.Share.open,'function');
+ const text=context.window.YT.External.m3u([{id:'benchmedia01',title:'Fixture'}]);
+ assert.match(text,/#EXTM3U/);assert.match(text,/benchmedia01/);
+});
+
+test('listening tracking does not pull in the lazy Stats view',()=>{
+ const {groups}=JSON.parse(readFileSync(join(__dirname,'assets.json'),'utf8'));
+ assert.deepEqual(groups['feature:stats-view'].files,['/stats-view.js']);
+ assert.deepEqual(groups['feature:stats-view'].dependencies,['feature:stats']);
+ assert.deepEqual(groups['feature:stats'].files,['/stats-core.js']);
+ assert.match(app,/Lazy\.proxy\('feature:stats-view', \['render'\], 'StatsView'\)/);
+});
+
+test('an unavailable Stats chunk reports an error without rejecting the UI navigation',async()=>{
+ const source=app.match(/function renderStats\(\) \{[\s\S]*?\n\}/)?.[0];assert.ok(source);
+ const seen=[],context=require('node:vm').createContext({Lazy:{proxy:()=>({render:()=>Promise.reject(new Error('Unavailable fixture chunk'))})},toast:text=>seen.push(text)});
+ require('node:vm').runInContext(source+';globalThis.render=renderStats;',context);
+ await context.render();assert.deepEqual(seen,['Unavailable fixture chunk']);
+});

frontend/asset-sync-core.js

@@ -0,0 +1,201 @@
+/* Exact, resumable asset synchronization shared by pages and workers. */
+(function (root) {
+  'use strict';
+  const CACHE = 'ytplayer-assets';
+  const STATE = '/__ytp_asset_state';
+  const url = (path, file) => path + '?v=' + file.h;
+
+  function paths(manifest) {
+    return Object.keys(manifest.files).sort();
+  }
+
+  function blocking(manifest, previous, activeLayout) {
+    const names = new Set(Object.entries(manifest.groups)
+      .filter(([name, group]) => name === 'core' || !group.background ||
+        name === 'layout:' + activeLayout ||
+        (previous?.groups[name] && previous.groups[name].contract !== group.contract))
+      .map(([name]) => name));
+    for (const name of names) for (const dependency of manifest.groups[name].dependencies || []) names.add(dependency);
+    return [...new Set([...names].flatMap(name => manifest.groups[name].files))].sort();
+  }
+
+  function plan(manifest, keys) {
+    const held = new Set(keys);
+    return {
+      missing: paths(manifest).map(path => url(path, manifest.files[path])).filter(key => !held.has(key)),
+      blocking: blocking(manifest).map(path => url(path, manifest.files[path])),
+    };
+  }
+
+  function retained(current, previous) {
+    const currentPaths = new Set(paths(current));
+    const keep = new Set([...currentPaths].map(path => url(path, current.files[path])));
+    if (previous) for (const path of paths(previous)) {
+      if (!currentPaths.has(path) || current.files[path]?.h !== previous.files[path].h) keep.add(url(path, previous.files[path]));
+    }
+    return keep;
+  }
+
+  function fallback(manifest, previous, path) {
+    if (!manifest.files[path] || !previous?.files[path]) return null;
+    const group = Object.keys(manifest.groups).find(name => manifest.groups[name].files.includes(path));
+    if (!group || !previous.groups[group]?.files.includes(path) ||
+        manifest.groups[group].contract !== previous.groups[group].contract) return null;
+    return url(path, previous.files[path]);
+  }
+
+  async function state(cache) {
+    const response = await cache.match(STATE);
+    return response ? response.json() : null;
+  }
+
+  function verifiedProbe(response, hash) {
+    if (!response) return false;
+    const valid = response.headers.get('X-Asset-Hash') === hash;
+    // Metadata checks must release Blob/data-pipe readers. They never consume
+    // asset bytes, and cancelling this response does not remove its cache entry.
+    response.body?.cancel().catch(() => {});
+    return valid;
+  }
+
+  async function status(manifest, cache, { previous, activeLayout, offline = true } = {}) {
+    const found = await Promise.all(blocking(manifest, previous, activeLayout).map(async path => {
+      const response = await cache.match(url(path, manifest.files[path]));
+      return verifiedProbe(response, manifest.files[path].h);
+    }));
+    const missing = found.filter(value => !value).length;
+    return { ready: missing === 0, missing, version: manifest.buildTag, ...(offline ? await completeness(manifest, cache) : {}) };
+  }
+
+  // All concurrent messages/layout jobs in this worker share six download slots.
+  let downloads = 0;
+  const waiters = [];
+  async function downloadSlot(task) {
+    if (downloads >= 6) await new Promise(resolve => waiters.push(resolve));
+    else downloads++;
+    try { return await task(); }
+    finally { const next = waiters.shift(); if (next) next(); else downloads--; }
+  }
+
+  const pendingDownloads = new Map();
+  async function sharedDownload(key, task) {
+    while (pendingDownloads.has(key)) await pendingDownloads.get(key).catch(() => {});
+    const promise = downloadSlot(task);
+    pendingDownloads.set(key, promise);
+    try { return await promise; }
+    finally { pendingDownloads.delete(key); }
+  }
+
+  async function syncAssets(manifest, { cache, fetchFn, concurrency = 6, attempts = 3, activeLayout, groups, all = false }) {
+    const previous = (await state(cache))?.current;
+    const missing = [];
+    const selected = all ? paths(manifest) : groups ? [...new Set(groups.flatMap(name => manifest.groups[name]?.files || []))].sort()
+      : blocking(manifest, previous, activeLayout);
+    for (const path of selected) {
+      const key = url(path, manifest.files[path]);
+      const response = await cache.match(key);
+      if (!verifiedProbe(response, manifest.files[path].h)) missing.push(key);
+    }
+    const count = missing.length;
+    let failure;
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(6, concurrency, count)) }, async () => {
+      while (missing.length) {
+        const key = missing.shift();
+        try { await sharedDownload(key, async () => {
+        const held = await cache.match(key);
+        if (verifiedProbe(held, key.split('v=')[1])) return;
+        let error;
+        for (let attempt = 0; attempt < Math.min(3, attempts); attempt++) {
+          const controller = new AbortController();
+          const timer = setTimeout(() => controller.abort(), 30000);
+          try {
+            const response = await fetchFn(key, { credentials: 'same-origin', signal: controller.signal });
+            if (!response.ok || response.headers.get('X-Asset-Hash') !== key.split('v=')[1]) {
+              throw new Error('Asset hash mismatch: ' + key);
+            }
+            // Keep the timeout through body consumption, not just response headers.
+            await cache.put(key, response);
+            error = null;
+            break;
+          } catch (err) { error = err; }
+          finally { clearTimeout(timer); }
+        }
+        if (error) throw error;
+        }); } catch (error) { failure = error; }
+      }
+    }));
+    if (failure) throw failure;
+    if (!groups && !all && !(await status(manifest, cache, { previous, activeLayout, offline: false })).ready) throw new Error('Incomplete blocking assets');
+    return { refreshed: count, caches: 1 };
+  }
+
+
+  // Verified cache entries are the durable progress journal. Counters are rebuilt
+  // after worker termination or browser eviction; never trust a stored ready bit.
+  async function completeness(manifest, cache) {
+    const files = paths(manifest);
+    const missingFiles = (await Promise.all(files.map(async path => {
+      const response = await cache.match(url(path, manifest.files[path]));
+      return verifiedProbe(response, manifest.files[path].h) ? null : path;
+    }))).filter(Boolean);
+    const total = files.length;
+    return { offlineReady: missingFiles.length === 0, cached: total - missingFiles.length, total, missingFiles };
+  }
+
+  const completionKey = manifest => '/__ytp_completion/' + manifest.buildTag;
+  async function complete(manifest, { cache, fetchFn, cycles = 4, now = Date.now,
+    sleep = ms => new Promise(resolve => setTimeout(resolve, ms)), baseDelay = 1000,
+    maxDelay = 30000, notify = () => {}, force = false } = {}) {
+    const key = completionKey(manifest), saved = await cache.match(key);
+    let job = saved ? await saved.json() : { failures: 0, nextRetryAt: 0 };
+    let snapshot = await completeness(manifest, cache);
+    const publish = async running => {
+      job = { ...job, ...snapshot, running, version: manifest.buildTag };
+      await cache.put(key, Response.json(job));
+      await notify(job);
+    };
+    if (snapshot.offlineReady) { job.failures = 0; job.nextRetryAt = 0; await publish(false); return job; }
+    if (!force && job.nextRetryAt > now()) await sleep(Math.min(maxDelay, job.nextRetryAt - now()));
+    for (let cycle = 0; cycle < cycles; cycle++) {
+      await publish(true);
+      let error;
+      try { await syncAssets(manifest, { cache, fetchFn, all: true }); }
+      catch (failure) { error = failure; }
+      snapshot = await completeness(manifest, cache);
+      if (snapshot.offlineReady) { job.failures = 0; job.nextRetryAt = 0; job.error = null; await publish(false); return job; }
+      job.failures++;
+      const delay = Math.min(maxDelay, baseDelay * 2 ** Math.min(job.failures - 1, 10));
+      job.nextRetryAt = now() + delay;
+      job.error = String(error?.message || 'Incomplete offline cache');
+      await publish(cycle + 1 < cycles);
+      if (cycle + 1 < cycles) await sleep(delay);
+    }
+    return job;
+  }
+
+  async function commit(manifest, cache, { previousClients, activeLayout } = {}) {
+    const old = await state(cache);
+    if (!(await status(manifest, cache, { previous: old?.current, activeLayout, offline: false })).ready) {
+      throw new Error('Incomplete blocking assets');
+    }
+    const sameBuild = old?.current?.buildTag === manifest.buildTag;
+    const previous = sameBuild ? old.previous : old?.current;
+    const next = {
+      current: manifest, previous,
+      previousClients: previousClients || (sameBuild ? old.previousClients : []),
+    };
+    // One state write publishes the complete build and its old-tab affinity.
+    await cache.put(STATE, new Response(JSON.stringify(next), { headers: { 'Content-Type': 'application/json' } }));
+    const keep = retained(manifest, previous);
+    for (const request of await cache.keys()) {
+      const parsed = new URL(request.url);
+      const key = parsed.pathname + parsed.search;
+      if (parsed.searchParams.has('v') && !keep.has(key)) await cache.delete(key);
+    }
+    return next;
+  }
+
+  const api = { CACHE, STATE, url, paths, blocking, plan, retained, fallback, status, completeness, completionKey, complete, syncAssets, state, commit };
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.AssetSyncCore = api;
+})(typeof globalThis !== 'undefined' ? globalThis : this);

frontend/asset-sync-core.test.js

@@ -0,0 +1,98 @@
+const {test}=require('node:test');
+const assert=require('node:assert/strict');
+const core=require('./asset-sync-core');
+const manifest=(a='a',b='b')=>({buildTag:a+b,files:{'/a.js':{h:a},'/index.html':{h:b}},groups:{core:{files:['/a.js','/index.html']}}});
+function cache(){const entries=new Map();return {entries,async match(k){return entries.get(k)?.clone()},async put(k,r){entries.set(k,r.clone())},async keys(){return [...entries.keys()].map(url=>({url:'http://local'+url}))},async delete(k){return entries.delete(k)}}}
+const response=h=>new Response(h,{headers:{'X-Asset-Hash':h}});
+test('exact diff shares unchanged URLs; retains N-1 and prunes N-2',()=>{assert.deepEqual(core.plan(manifest(),['/a.js?v=a']).missing,['/index.html?v=b']);assert.deepEqual([...core.retained(manifest('c'),manifest())].sort(),['/a.js?v=a','/a.js?v=c','/index.html?v=b']);});
+test('interrupted sync resumes verified files and refuses a mismatched hash',async()=>{const c=cache();let fail=true;let calls=[];const fetchFn=async u=>{calls.push(u);if(u.includes('index')&&fail)return response('wrong');return response(u.split('=')[1])};await assert.rejects(core.syncAssets(manifest(),{cache:c,fetchFn}),/hash/);assert.ok(await c.match('/a.js?v=a'));fail=false;calls=[];await core.syncAssets(manifest(),{cache:c,fetchFn});assert.deepEqual(calls,['/index.html?v=b']);await c.delete('/a.js?v=a');assert.equal((await core.status(manifest(),c)).missing,1);});
+test('commit is atomic and pruning keeps only current and previous changed versions',async()=>{const c=cache();await c.put('/a.js?v=z',response('z'));await core.syncAssets(manifest(),{cache:c,fetchFn:async u=>response(u.split('=')[1])});await core.commit(manifest(),c);await core.syncAssets(manifest('c'),{cache:c,fetchFn:async u=>response(u.split('=')[1])});await core.commit(manifest('c'),c);assert.ok(await c.match('/a.js?v=a'));assert.equal(await c.match('/a.js?v=z'),undefined);await core.syncAssets(manifest('d'),{cache:c,fetchFn:async u=>response(u.split('=')[1])});await core.commit(manifest('d'),c);assert.equal(await c.match('/a.js?v=a'),undefined);});
+test('downloads are capped at six and each failure gets three attempts',async()=>{const c=cache(),files={},list=[];for(let i=0;i<13;i++){const p='/'+i+'.js';files[p]={h:String(i)};list.push(p)}const m={buildTag:'pool',files,groups:{core:{files:list}}};let active=0,max=0;const tries={};await core.syncAssets(m,{cache:c,concurrency:20,fetchFn:async u=>{active++;max=Math.max(max,active);await new Promise(r=>setTimeout(r,5));active--;tries[u]=(tries[u]||0)+1;if(tries[u]<3)throw Error('drop');return response(u.split('=')[1])}});assert.equal(max,6);assert.ok(Object.values(tries).every(n=>n===3));});
+test('background files do not block, but active layout and contract changes do',()=>{const m=manifest();m.groups.extra={background:true,contract:2,files:['/extra.js']};m.files['/extra.js']={h:'e'};assert.deepEqual(core.blocking(m),['/a.js','/index.html']);assert.ok(core.blocking(m,{groups:{extra:{contract:1}}}).includes('/extra.js'));m.groups['layout:classic']={background:true,files:['/classic.css']};m.files['/classic.css']={h:'c'};assert.ok(core.blocking(m,null,'classic').includes('/classic.css'));});
+test('removed files survive one previous build for open tabs',()=>{const previous=manifest(),current=manifest('c');delete current.files['/a.js'];current.groups.core.files=['/index.html'];assert.ok(core.retained(current,previous).has('/a.js?v=a'));});
+
+test('staged fallback permits only the previous same-contract version of a shipped group file', () => {
+  const old = manifest(), next = manifest('c');
+  old.groups.core.contract = next.groups.core.contract = 1;
+  assert.equal(core.fallback(next, old, '/a.js'), '/a.js?v=a');
+  next.groups.core.contract = 2;
+  assert.equal(core.fallback(next, old, '/a.js'), null);
+  assert.equal(core.fallback(next, old, '/missing.js'), null);
+});
+
+test('background synchronization fills all groups without publishing a new current manifest', async () => {
+  const c = cache(), m = manifest();
+  m.groups.optional = { contract: 1, background: true, files: ['/extra.js'] };
+  m.files['/extra.js'] = { h: 'e' };
+  const fetchFn = async key => response(key.split('=')[1]);
+  await core.syncAssets(m, { cache: c, fetchFn });
+  assert.equal(await c.match('/extra.js?v=e'), undefined);
+  await core.commit(m, c);
+  const before = await core.state(c);
+  const result = await core.syncAssets(m, { cache: c, fetchFn, groups: ['optional'] });
+  assert.equal(result.refreshed, 1);
+  assert.ok(await c.match('/extra.js?v=e'));
+  assert.deepEqual(await core.state(c), before);
+});
+
+test('active layouts also block on shared dependencies, while other layouts stay background', () => {
+ const m=manifest(); m.groups['layout:glass-stage']={contract:1,background:true,files:['/glass.css'],dependencies:['feature:controls']}; m.groups['feature:controls']={contract:1,background:true,files:['/controls.js']}; m.groups['layout:bento-hub']={contract:1,background:true,files:['/bento.css']};
+ for(const path of ['/glass.css','/controls.js','/bento.css'])m.files[path]={h:'h'};
+ assert.deepEqual(core.blocking(m,null,'glass-stage'),['/a.js','/controls.js','/glass.css','/index.html']);
+});
+
+test('removing group membership retains the old tab URL even if the physical file is still shipped unchanged',()=>{
+ const previous=manifest(),current=manifest();current.groups.core.files=['/index.html'];
+ assert.ok(core.retained(current,previous).has('/a.js?v=a'));
+});
+
+test('completion includes ungrouped runtime files and exposes verified missing paths', async () => {
+ const c=cache(), m=manifest();m.files['/worker.js']={h:'w'};
+ await core.syncAssets(m,{cache:c,fetchFn:async u=>response(u.split('=')[1])});
+ const status=await core.status(m,c);
+ assert.equal(status.ready,true);assert.equal(status.offlineReady,false);
+ assert.deepEqual(status.missingFiles,['/worker.js']);assert.equal(status.cached,2);assert.equal(status.total,3);
+ await core.complete(m,{cache:c,fetchFn:async u=>response(u.split('=')[1])});
+ assert.equal((await core.status(m,c)).offlineReady,true);
+});
+
+test('completion persists backoff and resumes only missing files after a worker restart',async()=>{
+ const c=cache(),m=manifest();let clock=1000;const calls=[];
+ await core.complete(m,{cache:c,cycles:1,now:()=>clock,baseDelay:10,fetchFn:async u=>{if(u.includes('index'))throw Error('offline');return response('a');}});
+ const checkpoint=await(await c.match(core.completionKey(m))).json();
+ assert.equal(checkpoint.running,false);assert.equal(checkpoint.failures,1);assert.equal(checkpoint.nextRetryAt,1010);
+ await core.complete(m,{cache:c,now:()=>clock,sleep:async ms=>{assert.equal(ms,10);clock+=ms;},fetchFn:async u=>{calls.push(u);return response(u.split('=')[1]);}});
+ assert.deepEqual(calls,['/index.html?v=b']);
+ const status=await(await c.match(core.completionKey(m))).json();assert.equal(status.offlineReady,true);assert.equal(status.failures,0);
+ await c.delete('/a.js?v=a');assert.equal((await core.status(m,c)).offlineReady,false);
+});
+
+test('completion retries with exponential backoff and keeps making progress past a failed asset',async()=>{
+ const c=cache(),m=manifest(),delays=[];let tries=0;
+ const job=await core.complete(m,{cache:c,baseDelay:5,sleep:async ms=>delays.push(ms),fetchFn:async u=>{if(u.includes('a.js')&&++tries<=6)throw Error('drop');return response(u.split('=')[1]);}});
+ assert.deepEqual(delays,[5,10]);assert.equal(job.offlineReady,true);assert.ok(await c.match('/index.html?v=b'));
+});
+
+test('overlapping layout and completion jobs share a six-download ceiling',async()=>{
+ const c=cache(),m=manifest();m.groups.extra={background:true,files:[]};
+ for(let i=0;i<15;i++){const p='/extra'+i+'.js';m.files[p]={h:String(i)};m.groups.extra.files.push(p);}
+ let active=0,peak=0;const calls=new Map();
+ const fetchFn=async u=>{active++;peak=Math.max(active,peak);calls.set(u,(calls.get(u)||0)+1);await new Promise(r=>setTimeout(r,3));active--;return response(u.split('=')[1]);};
+ await Promise.all([core.complete(m,{cache:c,fetchFn}),core.syncAssets(m,{cache:c,fetchFn,groups:['extra']})]);
+ assert.ok(peak<=6);assert.ok([...calls.values()].every(count=>count===1));
+});
+
+test('blocking commit never waits on an optional file readiness probe',{timeout:1000},async()=>{
+ const c=cache(),m=manifest();m.files['/extra.js']={h:'extra'};m.groups.extra={files:['/extra.js'],background:true,contract:1};
+ await c.put('/a.js?v=a',response('a'));await c.put('/index.html?v=b',response('b'));
+ const match=c.match;let extraProbes=0;c.match=async key=>{if(key==='/extra.js?v=extra'){extraProbes++;return new Promise(()=>{});}return match(key);};
+ await core.commit(m,c);assert.equal(extraProbes,0);assert.equal((await core.state(c)).current.buildTag,m.buildTag);
+ c.match=match;assert.equal((await core.status(m,c)).offlineReady,false);
+});
+
+test('metadata probes release response streams while stored asset bodies remain readable',async()=>{
+ const c=cache(),m=manifest();await c.put('/a.js?v=a',response('a'));await c.put('/index.html?v=b',response('b'));
+ const match=c.match,probes=[];c.match=async key=>{const r=await match(key);if(r)probes.push(r);return r;};
+ assert.equal((await core.status(m,c)).offlineReady,true);assert.ok(probes.length>0);assert.ok(probes.every(r=>r.bodyUsed));
+ assert.equal(await(await match('/a.js?v=a')).text(),'a');assert.equal(await(await match('/index.html?v=b')).text(),'b');
+});

frontend/asset-worker.test.js

@@ -0,0 +1,58 @@
+const {test}=require('node:test');const assert=require('node:assert/strict');const vm=require('node:vm');const fs=require('node:fs');const core=require('./asset-sync-core');
+function environment(){
+ const stores=new Map(),listeners={},messages=[],skips=[],fetches=[],selfMessages=[];const m={buildTag:'next',files:{'/index.html':{h:'index'},'/app.js':{h:'app'}},groups:{core:{files:['/index.html','/app.js']}}};
+ const storage={async keys(){return [...stores.keys()]},async delete(n){return stores.delete(n)},async open(n){if(!stores.has(n)){const map=new Map();stores.set(n,{async match(k){return map.get(typeof k==='string'?k:new URL(k.url).pathname+new URL(k.url).search)?.clone()},async put(k,r){map.set(k,r.clone())},async keys(){return [...map.keys()].map(k=>({url:'https://local'+k}))},async delete(k){return map.delete(typeof k==='string'?k:new URL(k.url).pathname+new URL(k.url).search)}})}return stores.get(n)}};
+ const sandbox={__BUILD_TAG__:'next',__ASSET_SYNC__:true,AssetSyncCore:core,importScripts:()=>{},caches:storage,URL,Response,Request,Headers,setTimeout,clearTimeout,crypto:require('node:crypto').webcrypto,console,fetch:async u=>{fetches.push(u);return u==='/api/manifest'?Response.json(m):new Response(u,{headers:{'X-Asset-Hash':m.files[u.split('?')[0]]?.h || ''}})},self:{registration:{active:{postMessage:data=>selfMessages.push(data)}},location:{origin:'https://local'},addEventListener:(t,f)=>listeners[t]=f,skipWaiting:()=>skips.push(1),clients:{claim:async()=>{},matchAll:async()=>[{id:'old',postMessage:x=>messages.push(x)}]}}};
+ vm.runInNewContext(fs.readFileSync(__dirname+'/sw.js','utf8'),sandbox);
+ async function dispatch(t,e={}){const tasks=[];listeners[t]({...e,waitUntil:v=>tasks.push(v)});await Promise.all(tasks)}
+ async function request(url,mode='cors',clientId='new'){let p;const tasks=[];listeners.fetch({request:{url:'https://local'+url,method:'GET',mode},clientId,waitUntil:v=>tasks.push(v),respondWith:v=>p=v});const response=await p;await Promise.all(tasks);return response;}
+ return {storage,m,skips,fetches,dispatch,request,sandbox,selfMessages,async complete(){for(const data of selfMessages.splice(0))await dispatch('message',{data});}};
+}
+test('install does not activate or publish; CACHE_STATUS is honest; activation commits and exact requests self-heal',async()=>{const e=environment();await e.dispatch('install');assert.equal(e.skips.length,0);const cache=await e.storage.open(core.CACHE);assert.equal(await core.state(cache),null);let reply;await e.dispatch('message',{data:{type:'CACHE_STATUS'},ports:[{postMessage:r=>reply=r}]});assert.equal(reply.ready,true);await e.dispatch('activate');await e.complete();assert.equal((await core.state(cache)).current.buildTag,'next');assert.equal((await e.request('/playlist/x','navigate')).headers.get('X-Asset-Hash'),'index');await cache.delete('/app.js?v=app');assert.equal((await core.status(e.m,cache)).ready,false);await e.dispatch('message',{data:{type:'CACHE_STATUS'},ports:[{postMessage:r=>reply=r}]});assert.equal((await core.status(e.m,cache)).offlineReady,true);assert.equal(reply.version,'next');assert.equal((await e.request('/app.js')).headers.get('X-Asset-Hash'),'app');assert.ok(await cache.match('/app.js?v=app'));assert.equal(await cache.match('/app.js?v=stale'),undefined);assert.equal((await e.request('/app.js?v=stale')).status,409);});
+test('reported playback defers explicit activation until pause; install never calls skipWaiting',async()=>{const e=environment(),source={id:'p'};await e.dispatch('message',{data:{type:'SKIP_WAITING'}});assert.equal(e.skips.length,0);await e.dispatch('message',{source,data:{type:'PLAYING',value:true}});await e.dispatch('message',{source,data:{type:'SKIP_WAITING'}});assert.equal(e.skips.length,0);await e.dispatch('message',{source,data:{type:'PLAYING',value:false}});assert.equal(e.skips.length,1);});
+
+test('staged same-contract responses use verified N-1 without poisoning the new URL',async()=>{
+ const e=environment(); const cache=await e.storage.open(core.CACHE);
+ const old={buildTag:'old',files:{'/extra.js':{h:'old'}},groups:{core:{files:[],contract:1},'feature:extra':{files:['/extra.js'],contract:1,background:true}}};
+ e.m.groups.core.contract=1; e.m.groups['feature:extra']={files:['/extra.js'],contract:1,background:true}; e.m.files['/extra.js']={h:'new'};
+ await cache.put(core.STATE,Response.json({current:old})); await cache.put('/extra.js?v=old',new Response('old body',{headers:{'X-Asset-Hash':'old'}}));
+ await e.dispatch('install'); await e.dispatch('activate');await e.complete();
+ assert.ok(await cache.match('/extra.js?v=new'));await cache.delete('/extra.js?v=new');
+ assert.equal(await cache.match('/extra.js?v=new'),undefined);
+ const stale=await e.request('/extra.js?v=new'); assert.equal(await stale.text(),'old body');assert.equal(stale.headers.get('X-Asset-Hash'),'old');assert.equal(await cache.match('/extra.js?v=new'),undefined);
+ await e.dispatch('message',{data:{type:'WARM_ASSETS',saveData:true}}); assert.ok(await cache.match('/extra.js?v=new'));
+ await e.dispatch('message',{data:{type:'WARM_ASSETS',saveData:false}}); assert.equal((await cache.match('/extra.js?v=new')).headers.get('X-Asset-Hash'),'new');
+ assert.equal((await e.request('/extra.js?v=new')).headers.get('X-Asset-Hash'),'new');
+});
+
+test('a changed background contract is downloaded before ready and cannot fall back after commit',async()=>{
+ const e=environment(),cache=await e.storage.open(core.CACHE);
+ const old={buildTag:'old',files:{'/extra.js':{h:'old'}},groups:{core:{files:[],contract:1},'feature:extra':{files:['/extra.js'],contract:1,background:true}}};
+ e.m.groups.core.contract=1;e.m.groups['feature:extra']={files:['/extra.js'],contract:2,background:true};e.m.files['/extra.js']={h:'new'};
+ await cache.put(core.STATE,Response.json({current:old}));await cache.put('/extra.js?v=old',new Response('old body',{headers:{'X-Asset-Hash':'old'}}));
+ await e.dispatch('install');assert.equal((await core.state(cache)).current.buildTag,'old');
+ assert.equal((await cache.match('/extra.js?v=new')).headers.get('X-Asset-Hash'),'new');
+ let reply;await e.dispatch('message',{data:{type:'CACHE_STATUS'},ports:[{postMessage:r=>reply=r}]});assert.equal(reply.ready,true);
+ await e.dispatch('activate');await e.complete();await cache.delete('/extra.js?v=new');
+ const response=await e.request('/extra.js?v=new');assert.equal(response.headers.get('X-Asset-Hash'),'new');assert.notEqual(await response.text(),'old body');
+});
+
+test('overlapping idle warm messages share one download pool',async()=>{
+ const e=environment();e.m.files['/extra.js']={h:'extra'};e.m.groups['feature:extra']={files:['/extra.js'],contract:1,background:true};
+ await e.dispatch('install');await e.dispatch('activate');await e.complete();
+ await Promise.all([e.dispatch('message',{data:{type:'WARM_ASSETS',saveData:false}}),e.dispatch('message',{data:{type:'WARM_ASSETS',saveData:false}})]);
+ assert.equal(e.fetches.filter(url=>url==='/extra.js?v=extra').length,1);
+});
+
+test('waiting status does not start completion and activation delegates it to its own event',async()=>{
+ const e=environment();e.m.files['/extra.js']={h:'extra'};e.m.groups['feature:extra']={files:['/extra.js'],contract:1,background:true};
+ await e.dispatch('install');let reply;await e.dispatch('message',{data:{type:'CACHE_STATUS'},ports:[{postMessage:r=>reply=r}]});
+ assert.equal(reply.ready,true);assert.equal(reply.offlineReady,false);assert.ok(!e.fetches.includes('/extra.js?v=extra'));
+ let release,started;const gate=new Promise(r=>release=r),begin=new Promise(r=>started=r),fetch=e.sandbox.fetch;
+ e.sandbox.fetch=async url=>{if(url==='/extra.js?v=extra'){started();await gate;}return fetch(url);};
+ await e.dispatch('activate');const cache=await e.storage.open(core.CACHE);
+ assert.equal((await core.state(cache)).current.buildTag,'next');assert.equal((await core.status(e.m,cache)).ready,true);
+ assert.equal((await core.status(e.m,cache)).offlineReady,false);assert.equal(e.selfMessages[0].type,'COMPLETE_ASSETS');
+ const job=e.complete();await begin;assert.equal(await cache.match('/extra.js?v=extra'),undefined);release();await job;
+ assert.equal((await core.status(e.m,cache)).offlineReady,true);
+});

frontend/assets.json

@@ -0,0 +1,364 @@
+{
+  "groups": {
+    "core": {
+      "contract": 1,
+      "eager": true,
+      "files": [
+        "/index.html",
+        "/styles.css",
+        "/service-ui.css",
+        "/refresh.css",
+        "/layout-base.css",
+        "/recommendations.css",
+        "/flag-ui.js",
+        "/async-guard.js",
+        "/visible-timer.js",
+        "/asset-sync-core.js",
+        "/sw-update.js",
+        "/fingerprint.js",
+        "/opfs.js",
+        "/opfs-worker.js",
+        "/lyrics-core.js",
+        "/lyrics-display.js",
+        "/sha256.js",
+        "/resume-core.js",
+        "/loudness-wasm.js",
+        "/loudness.js",
+        "/sha256-wasm.js",
+        "/settings-sections.js",
+        "/related-videos.js",
+        "/related-videos.css",
+        "/audio-continuity.js",
+        "/fullscreen-orientation.js",
+        "/fullscreen-orientation.css",
+        "/download-actions.js",
+        "/download-actions.css",
+        "/download-errors.js",
+        "/downloads.js",
+        "/downloads-page.js",
+        "/offline-pages.css",
+        "/saved-page.js",
+        "/server-backfill.js",
+        "/saved-page.css",
+        "/prewarm-next.js",
+        "/settings-sections.css",
+        "/app.js",
+        "/manifest.webmanifest",
+        "/icons/icon-192.png",
+        "/icons/icon-512.png",
+        "/fonts/fonts.css",
+        "/fonts/BricolageGrotesque-latin-ext.woff2",
+        "/fonts/BricolageGrotesque-latin.woff2",
+        "/fonts/HankenGrotesk-latin-ext.woff2",
+        "/fonts/HankenGrotesk-latin.woff2",
+        "/fonts/JetBrainsMono-latin-ext.woff2",
+        "/fonts/JetBrainsMono-latin.woff2",
+        "/lazy.js",
+        "/feature-bootstrap.js",
+        "/eq-parameters.js",
+        "/assets.json",
+        "/device-db.js",
+        "/shell-core.js",
+        "/views-core.js",
+        "/section-rail.js"
+      ],
+      "background": false
+    },
+    "layout:glass-stage": {
+      "contract": 1,
+      "eager": false,
+      "files": [
+        "/theme-glass.css",
+        "/theme-glass-panel.css",
+        "/glass-panel-layout.js"
+      ],
+      "background": true,
+      "dependencies": [
+        "feature:layout-controls"
+      ]
+    },
+    "layout:classic": {
+      "contract": 1,
+      "eager": false,
+      "files": [
+        "/theme-classic.css"
+      ],
+      "background": true
+    },
+    "layout:bento-hub": {
+      "contract": 1,
+      "eager": false,
+      "files": [
+        "/theme-bento-hub.css",
+        "/bento-hub.js",
+        "/fonts/PlusJakartaSans-latin.woff2",
+        "/fonts/PlusJakartaSans-latin-ext.woff2"
+      ],
+      "background": true,
+      "dependencies": [
+        "feature:layout-controls"
+      ]
+    },
+    "layout:f7-swipe": {
+      "contract": 1,
+      "eager": false,
+      "files": [
+        "/theme-f7.css",
+        "/vendor/framework7-swipe.min.js",
+        "/f7-layout.js"
+      ],
+      "background": true
+    },
+    "feature:piano": {
+      "contract": 1,
+      "eager": false,
+      "files": [
+        "/piano-core.js",
+        "/piano.js",
+        "/piano-engine.mjs"
+      ],
+      "background": true
+    },
+    "feature:midi": {
+      "contract": 1,
+      "eager": false,
+      "files": [
+        "/midi.js"
+      ],
+      "background": true
+    },
+    "feature:party-dj": {
+      "contract": 1,
+      "eager": false,
+      "files": [
+        "/party-dj.js"
+      ],
+      "background": true
+    },
+    "feature:lyrics-window": {
+      "contract": 1,
+      "eager": false,
+      "files": [
+        "/lyrics-window.js"
+      ],
+      "background": true
+    },
+    "feature:lower-third": {
+      "contract": 1,
+      "eager": false,
+      "files": [
+        "/lower-third.js",
+        "/lower-third.css"
+      ],
+      "background": true
+    },
+    "feature:vocal-reducer": {
+      "contract": 1,
+      "eager": false,
+      "files": [
+        "/vocal-reducer.js"
+      ],
+      "background": true
+    },
+    "feature:eq-core": {
+      "contract": 1,
+      "eager": false,
+      "files": [
+        "/eq-core.js"
+      ],
+      "background": true
+    },
+    "feature:setlist-import": {
+      "contract": 1,
+      "eager": false,
+      "files": [
+        "/setlist-import.js"
+      ],
+      "background": true
+    },
+    "feature:car-mode": {
+      "contract": 1,
+      "eager": false,
+      "files": [
+        "/car-mode.js",
+        "/car-mode.css"
+      ],
+      "background": true
+    },
+    "feature:p2p": {
+      "contract": 1,
+      "eager": false,
+      "files": [
+        "/p2p-core.js",
+        "/p2p-client.js",
+        "/p2p-transfer.js",
+        "/p2p-recv-worker.js",
+        "/hash-worker.js"
+      ],
+      "background": true
+    },
+    "feature:direct": {
+      "contract": 1,
+      "eager": false,
+      "files": [
+        "/direct-protocol.js",
+        "/direct-stream.js",
+        "/direct-media.js",
+        "/direct-media.css",
+        "/direct-recv-worker.js"
+      ],
+      "background": true,
+      "dependencies": [
+        "feature:p2p"
+      ]
+    },
+    "feature:video-edit": {
+      "contract": 1,
+      "eager": false,
+      "files": [
+        "/video-edit.js"
+      ],
+      "background": true
+    },
+    "feature:stats": {
+      "contract": 1,
+      "eager": false,
+      "files": [
+        "/stats-core.js"
+      ],
+      "background": true
+    },
+    "feature:export": {
+      "contract": 1,
+      "eager": false,
+      "files": [
+        "/export.js"
+      ],
+      "background": true
+    },
+    "feature:playlist": {
+      "contract": 1,
+      "eager": true,
+      "files": [],
+      "embeddedIn": [
+        "/app.js"
+      ],
+      "background": false
+    },
+    "feature:settings": {
+      "contract": 1,
+      "eager": true,
+      "files": [],
+      "embeddedIn": [
+        "/app.js",
+        "/settings-sections.js",
+        "/settings-sections.css",
+        "/views-core.js"
+      ],
+      "background": false
+    },
+    "feature:service-mode": {
+      "contract": 1,
+      "eager": true,
+      "files": [],
+      "embeddedIn": [
+        "/app.js",
+        "/service-ui.css"
+      ],
+      "background": false
+    },
+    "feature:lyrics-editor": {
+      "contract": 1,
+      "eager": true,
+      "files": [],
+      "embeddedIn": [
+        "/app.js",
+        "/lyrics-core.js",
+        "/lyrics-display.js"
+      ],
+      "background": false
+    },
+    "feature:layout-controls": {
+      "contract": 1,
+      "eager": false,
+      "background": true,
+      "files": [
+        "/theme-glass-controls.css",
+        "/glass-controls.js"
+      ]
+    },
+    "layout:sanctuary-stage": {
+      "contract": 1,
+      "eager": false,
+      "background": true,
+      "files": []
+    },
+    "layout:liturgical": {
+      "contract": 1,
+      "eager": false,
+      "background": true,
+      "files": []
+    },
+    "layout:living-hymnal": {
+      "contract": 1,
+      "eager": false,
+      "background": true,
+      "files": []
+    },
+    "layout:broadcaster": {
+      "contract": 1,
+      "eager": false,
+      "background": true,
+      "files": []
+    },
+    "layout:contemplative": {
+      "contract": 1,
+      "eager": false,
+      "background": true,
+      "files": []
+    },
+    "feature:presenter": {
+      "contract": 1,
+      "eager": false,
+      "background": true,
+      "files": [
+        "/presenter.js"
+      ]
+    },
+    "feature:remote-client": {
+      "contract": 1,
+      "eager": false,
+      "background": true,
+      "files": [
+        "/remote-client.js"
+      ]
+    },
+    "feature:watch-party": {
+      "contract": 1,
+      "eager": false,
+      "background": true,
+      "files": [
+        "/watch-party-client.js"
+      ]
+    },
+    "feature:share-external": {
+      "contract": 1,
+      "eager": false,
+      "background": true,
+      "files": [
+        "/share-external.js"
+      ]
+    },
+    "feature:stats-view": {
+      "contract": 1,
+      "eager": false,
+      "background": true,
+      "files": [
+        "/stats-view.js"
+      ],
+      "dependencies": [
+        "feature:stats"
+      ]
+    }
+  }
+}

frontend/audio-continuity.js

@@ -0,0 +1,31 @@
+(function (root) {
+  'use strict';
+  function progressiveSource(current, videoSource) {
+    return current?.eqAudioUrl || current?.localUrl || current?.audioUrl || videoSource || '';
+  }
+  function needsAlignment(time, clock, threshold = 0.3) {
+    return Number.isFinite(time) && Number.isFinite(clock) && Math.abs(time - clock) >= threshold;
+  }
+  function create() {
+    const pending = new WeakMap();
+    function play(element) {
+      if (pending.has(element)) return pending.get(element);
+      if (!element.paused) return Promise.resolve();
+      let request;
+      try { request = Promise.resolve(element.play()); } catch (error) { request = Promise.reject(error); }
+      // Preserve the intent to play after an OS interruption; the watchdog retries.
+      request = request.catch(() => {}).finally(() => { if (pending.get(element) === request) pending.delete(element); });
+      pending.set(element, request); return request;
+    }
+    function resume(element, clock) {
+      // An ended element is finished, not interrupted: play() would restart it from 0.
+      if (!element || !element.paused || element.ended || pending.has(element)) return;
+      if (clock && element !== clock && needsAlignment(element.currentTime, clock.currentTime)) element.currentTime = clock.currentTime;
+      return play(element);
+    }
+    return { play, resume, reset: element => pending.delete(element) };
+  }
+  const api = { progressiveSource, needsAlignment, create };
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else { root.AudioContinuity = api; root.audioContinuity = create(); }
+})(globalThis);

frontend/audio-continuity.test.js

@@ -0,0 +1,49 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { progressiveSource, needsAlignment, create } = require('./audio-continuity');
+test('iPhone progressive audio uses saved/EQ sources before remote fallbacks', () => {
+  assert.equal(progressiveSource({ localUrl: 'blob:saved', audioUrl: 'remote' }, 'mux'), 'blob:saved');
+  assert.equal(progressiveSource({ eqAudioUrl: 'blob:eq', localUrl: 'blob:saved' }), 'blob:eq');
+  assert.equal(progressiveSource({ audioUrl: 'audio' }, 'mux'), 'audio');
+  assert.equal(progressiveSource({}, 'mux'), 'mux');
+});
+test('small drift and invalid clocks do not trigger an audible seek', () => {
+  assert.equal(needsAlignment(50.05, 50), false);
+  assert.equal(needsAlignment(49, 50), true);
+  assert.equal(needsAlignment(NaN, 50), false);
+});
+test('simultaneous play, visibility and watchdog resumes share one pending play', async () => {
+  let finish, calls = 0, seeks = 0;
+  const audio = { paused: true, get currentTime() { return 10; }, set currentTime(value) { seeks++; }, play() { calls++; return new Promise(resolve => { finish = resolve; }); } };
+  const controller = create();
+  controller.resume(audio, { currentTime: 10.05 });
+  controller.resume(audio, { currentTime: 12 });
+  const pending = controller.play(audio);
+  assert.equal(calls, 1); assert.equal(seeks, 0);
+  finish(); await pending;
+  controller.resume(audio, audio); // never seek an element to itself
+  assert.equal(seeks, 0); assert.equal(calls, 2); finish();
+});
+test('rejected autoplay can retry and only paused, misaligned secondaries seek', async () => {
+  const controller = create(); let calls = 0;
+  const audio = { paused: true, currentTime: 0, play() { calls++; return Promise.reject(new Error('OS suspension')); } };
+  await controller.play(audio); await controller.resume(audio, { currentTime: 4 });
+  assert.equal(calls, 2); assert.equal(audio.currentTime, 4);
+  audio.paused = false; controller.resume(audio, { currentTime: 10 });
+  assert.equal(audio.currentTime, 4); assert.equal(calls, 2);
+});
+test('a new play after pause/source reset is not blocked by a stale promise', async () => {
+  const controller = create(), finishes = []; let calls = 0;
+  const audio = { paused: true, play() { calls++; return new Promise(resolve => finishes.push(resolve)); } };
+  const old = controller.play(audio); controller.reset(audio);
+  const fresh = controller.play(audio); assert.equal(calls, 2);
+  finishes[0](); await old;
+  assert.equal(controller.play(audio), fresh); // old completion cannot discard the new request
+  finishes[1](); await fresh;
+});
+test('an ended element is never resumed (last song must not restart from 0)', () => {
+  let calls = 0;
+  const audio = { paused: true, ended: true, currentTime: 200, play() { calls++; return Promise.resolve(); } };
+  create().resume(audio, { currentTime: 200 });
+  assert.equal(calls, 0);
+});

frontend/bento-hub.js

@@ -0,0 +1,40 @@
+/* Bento-only artwork and measured clearance. Navigation and player nodes stay put. */
+(function(root){
+ 'use strict';
+ function chromeClearance(height,boxes){
+  const occupied=boxes.filter(b=>b.visible&&b.fixed&&b.height>0&&b.top>=height/2).map(b=>height-b.top);
+  return Math.max(0,...occupied)+16;
+ }
+ function mount(doc){
+  let frame=0,active=false;const html=doc.documentElement;
+  const resize=new root.ResizeObserver(schedule),observer=new root.MutationObserver(schedule);
+  function paint(){
+   frame=0;const on=html.dataset.layout==='bento-hub';
+   if(!on){if(active){resize.disconnect();observer.disconnect();html.style.removeProperty('--bento-bottom-clearance');doc.querySelectorAll('.bento-collage,.bento-search-icon').forEach(n=>n.remove());doc.querySelectorAll('.bento-search-label').forEach(n=>n.replaceWith(...n.childNodes));}active=false;return;}
+   if(!active){active=true;observer.observe(doc.body,{childList:true,subtree:true,attributes:true,attributeFilter:['class','hidden']});for(const id of ['bottomNav','miniBar','sectionRail']){const el=doc.getElementById(id);if(el)resize.observe(el);}}
+   const search=doc.querySelector('.search-btn');
+   if(search&&!search.querySelector('.bento-search-icon')){
+    const label=doc.createElement('span');label.className='bento-search-label';label.append(...search.childNodes);
+    const icon=doc.createElementNS('http://www.w3.org/2000/svg','svg');icon.classList.add('bento-search-icon');icon.setAttribute('aria-hidden','true');icon.setAttribute('viewBox','0 0 24 24');icon.innerHTML='<circle cx="10.5" cy="10.5" r="6.5"/><path d="m16 16 5 5"/>';search.append(label,icon);
+   }
+   const boxes=['bottomNav','miniBar','sectionRail'].map(id=>doc.getElementById(id)).filter(Boolean).map(el=>{const r=el.getBoundingClientRect(),s=root.getComputedStyle(el);return {top:r.top,height:r.height,fixed:s.position==='fixed',visible:s.display!=='none'&&s.visibility!=='hidden'};});
+   const clearance=chromeClearance(root.innerHeight,boxes)+'px';if(html.style.getPropertyValue('--bento-bottom-clearance')!==clearance)html.style.setProperty('--bento-bottom-clearance',clearance);
+   for(const card of doc.querySelectorAll('.home-pl-card')){
+    if(card.querySelector('.bento-collage'))continue;
+    // Use actual playlist artwork; never invent an image or a verification badge.
+    const name=card.querySelector('.home-pl-name')?.textContent;
+    const playlist=root.BentoHub.playlists?.().find(p=>p.name===name);
+    const images=(playlist?.videos||[]).filter(v=>v.thumbnail).slice(0,4);
+    if(images.length<4)continue;
+    const collage=doc.createElement('span');collage.className='bento-collage';collage.setAttribute('aria-hidden','true');
+    for(const video of images){const img=doc.createElement('img');img.src=video.thumbnail;img.alt='';img.loading='lazy';collage.append(img);}
+    card.querySelector('.home-pl-thumb')?.prepend(collage);
+   }
+  }
+  function schedule(){if(!frame)frame=root.requestAnimationFrame(paint);}
+  new root.MutationObserver(schedule).observe(html,{attributes:true,attributeFilter:['data-layout']});root.addEventListener('resize',schedule);paint();
+ }
+ const api={chromeClearance,playlists:null};
+ if(typeof module!=='undefined')module.exports=api;
+ else {root.BentoHub=api; if(root.document.readyState==='loading')root.document.addEventListener('DOMContentLoaded',()=>mount(root.document),{once:true});else mount(root.document);}
+})(typeof window==='undefined'?globalThis:window);

frontend/bento-hub.test.js

@@ -0,0 +1,12 @@
+const test=require('node:test'),assert=require('node:assert/strict');
+const {chromeClearance}=require('./bento-hub');
+test('clearance follows the highest visible floating control, including safe area',()=>{
+ assert.equal(chromeClearance(844,[{visible:true,fixed:true,top:746,height:98},{visible:true,fixed:true,top:666,height:72},{visible:true,fixed:true,top:602,height:56}]),258);
+});
+test('hidden and scrolling content cannot reserve fullscreen bottom space',()=>{
+ assert.equal(chromeClearance(844,[{visible:false,fixed:true,top:602,height:56},{visible:true,fixed:false,top:500,height:100},{visible:true,fixed:true,top:0,height:64}]),16);
+});
+test('desktop mini player reserves its real height and margin; no chrome is 16px',()=>{
+ assert.equal(chromeClearance(844,[{visible:true,fixed:true,top:760,height:72}]),100);
+ assert.equal(chromeClearance(844,[]),16);
+});

frontend/car-mode.css

@@ -0,0 +1,7 @@
+.car-mode { position: fixed; inset: 0; z-index: 20000; background: #070809; color: #fff; padding: max(20px, env(safe-area-inset-top)) max(20px, env(safe-area-inset-right)) max(20px, env(safe-area-inset-bottom)) max(20px, env(safe-area-inset-left)); overflow: auto; display: flex; flex-direction: column; gap: 20px; }
+.car-mode h1 { font: 650 clamp(24px, 4vw, 42px)/1.25 system-ui; margin: auto 0; overflow-wrap: anywhere; text-align: center; }
+.car-controls { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; width: min(100%, 800px); margin: auto; }
+.car-controls button { min-height: 110px; font: 650 clamp(22px, 3vw, 36px)/1.2 system-ui; background: #fff; color: #050607; border: 3px solid #fff; border-radius: 16px; }
+.car-exit { align-self: flex-start; min-height: 52px; padding: 12px 20px; background: #070809; color: #fff; border: 2px solid #fff; border-radius: 8px; }
+.car-mode button:focus-visible { outline: 4px solid #61caff; outline-offset: 4px; }
+.voice-search { flex-shrink: 0; min-width: 44px; min-height: 44px; }

frontend/car-mode.js

@@ -0,0 +1,29 @@
+/* Voice search and a deliberately sparse, high-contrast transport. */
+(function(root) {
+  'use strict';
+  function transcript(event) { let text = ''; for (let i = event.resultIndex || 0; i < (event.results?.length || 0); i++) if (event.results[i].isFinal) text += `${event.results[i][0]?.transcript || ''} `; return text.trim(); }
+  let adapter, overlay, timer, savedFocus, previous = [];
+  function close() { if (!overlay) return; clearInterval(timer); overlay.remove(); overlay = null; for (const [node, inert] of previous) node.inert = inert; previous = []; savedFocus?.focus?.(); }
+  function open() {
+    if (overlay) return;
+    const doc = root.document; savedFocus = doc.activeElement; previous = [...doc.body.children].map(node => [node, node.inert]); previous.forEach(([node]) => { node.inert = true; });
+    overlay = doc.createElement('section'); overlay.className = 'car-mode'; overlay.setAttribute('role', 'dialog'); overlay.setAttribute('aria-modal', 'true'); overlay.setAttribute('aria-label', 'Car mode');
+    const exit = doc.createElement('button'); exit.type = 'button'; exit.className = 'car-exit'; exit.textContent = 'Exit Car mode'; exit.onclick = close;
+    const title = doc.createElement('h1'); const controls = doc.createElement('div'); controls.className = 'car-controls'; let toggle;
+    for (const [label, action] of [['Previous', 'prev'], ['Play / Pause', 'toggle'], ['15 s back', 'back'], ['Next', 'next']]) { const b = doc.createElement('button'); b.type = 'button'; b.textContent = label; b.setAttribute('aria-label', label); b.onclick = () => adapter.action(action); if (action === 'toggle') toggle = b; controls.append(b); }
+    const update = () => { const state = adapter.state(); title.textContent = state.title || 'Choose a song before entering Car mode'; toggle.textContent = state.paused ? 'Play' : 'Pause'; }; update();
+    overlay.append(exit, title, controls); doc.body.append(overlay); timer = setInterval(update, 500); exit.focus();
+    overlay.onkeydown = e => { if (e.key === 'Escape') { e.preventDefault(); close(); } else if (e.key === 'Tab') { const buttons = [...overlay.querySelectorAll('button')], first = buttons[0], last = buttons.at(-1); if (e.shiftKey && doc.activeElement === first) { e.preventDefault(); last.focus(); } else if (!e.shiftKey && doc.activeElement === last) { e.preventDefault(); first.focus(); } } e.stopPropagation(); };
+  }
+  function configure(options) {
+    adapter = options; const doc = root.document, Recognition = root.SpeechRecognition || root.webkitSpeechRecognition;
+    if (Recognition) {
+      const b = doc.getElementById('voiceSearchBtn') || doc.createElement('button'); b.id='voiceSearchBtn'; b.type = 'button'; b.className = 'icon-btn voice-search'; b.title = 'Voice search'; b.setAttribute('aria-label', 'Voice search'); b.innerHTML = '<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" aria-hidden="true"><rect x="9" y="2" width="6" height="12" rx="3"/><path d="M5 10v2a7 7 0 0 0 14 0v-2M12 19v3m-4 0h8"/></svg>'; if(!b.isConnected)adapter.input.after(b);
+      let recognition, listening = false;
+      b.onclick = () => { if (listening) { recognition.abort(); return; } recognition = new Recognition(); recognition.lang = doc.documentElement.lang || root.navigator.language || 'en-US'; recognition.continuous = false; recognition.interimResults = false; recognition.onstart = () => { listening = true; b.setAttribute('aria-pressed', 'true'); b.title = 'Listening… tap to cancel'; }; recognition.onend = () => { listening = false; b.setAttribute('aria-pressed', 'false'); b.title = 'Voice search'; }; recognition.onerror = e => adapter.toast(`Voice search: ${e.error === 'not-allowed' ? 'microphone permission was denied' : e.error}`); recognition.onresult = e => { const query = transcript(e); if (query) { adapter.input.value = query; adapter.search(); } }; try { recognition.start(); } catch (error) { adapter.toast(error.message); } };
+    }
+    const car = doc.getElementById('carModeBtn') || doc.createElement('button'); car.id='carModeBtn'; car.type = 'button'; car.className = 'icon-btn'; car.title = 'Car mode'; car.setAttribute('aria-label', 'Car mode'); car.innerHTML = '<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" aria-hidden="true"><path d="m5 8 2-5h10l2 5M3 8h18v10H3zM5 18v3m14-3v3M6 12h2m8 0h2"/></svg>'; if(!car.isConnected)doc.getElementById('searchForm').after(car); car.onclick = open;
+    root.SettingsSections.register({ id: 'voice-car', title: 'Voice & Car mode', cluster: 'Listening', summary: () => Recognition ? 'Voice search available · Car mode' : 'Car mode · voice unavailable', render(container) { const p = doc.createElement('p'); p.textContent = Recognition ? 'Use the microphone beside Search to speak a query. Recognition availability and processing depend on your browser.' : 'Voice search is unavailable in this browser.'; const b = doc.createElement('button'); b.type = 'button'; b.className = 'settings-back'; b.textContent = 'Enter Car mode'; b.onclick = open; container.append(p, b); } });
+  }
+  const api = { transcript, configure, open, close }; if (typeof module !== 'undefined') module.exports = api; else root.CarMode = api;
+})(typeof window !== 'undefined' ? window : globalThis);

frontend/car-mode.test.js

@@ -0,0 +1,26 @@
+const { test } = require('node:test'), assert = require('node:assert/strict'); const { transcript } = require('./car-mode');
+test('voice search submits only final results from the result index', () => { const interim = [{transcript:'wrong'}]; interim.isFinal = false; const final = [{transcript:'Amazing Grace'}]; final.isFinal = true; assert.equal(transcript({results:[interim, final]}), 'Amazing Grace'); assert.equal(transcript({resultIndex:2,results:[final,final]}), ''); assert.equal(transcript({}), ''); });
+
+test('lazy Car mode keeps four independent transport buttons and the voice entry in place', () => {
+  const vm=require('node:vm'),fs=require('node:fs');
+  class Element {
+    constructor(tag){this.tag=tag;this.children=[];this.inert=false;}
+    append(...nodes){for(const node of nodes){node.remove();node.parent=this;this.children.push(node);}}
+    remove(){if(this.parent){this.parent.children=this.parent.children.filter(n=>n!==this);this.parent=null;}}
+    after(node){this.parent.append(node);}
+    setAttribute(name,value){this[name]=value;}
+    focus(){}
+    get isConnected(){return !!this.parent;}
+  }
+  const body=new Element('body'),input=new Element('input'),form=new Element('form'),voice=new Element('button');form.id='searchForm';voice.id='voiceSearchBtn';body.append(form,input,voice);
+  const all=node=>[node,...node.children.flatMap(all)],doc={body,documentElement:{lang:'en'},createElement:tag=>new Element(tag),getElementById:id=>all(body).find(n=>n.id===id)};
+  let section;const actions=[],root={document:doc,navigator:{},SpeechRecognition:function(){},SettingsSections:{register:s=>section=s}};
+  vm.runInNewContext(fs.readFileSync(__dirname+'/car-mode.js','utf8'),{window:root,setInterval:()=>1,clearInterval:()=>{}});
+  root.CarMode.configure({input,action:action=>actions.push(action),state:()=>({paused:true,title:'Song'})});
+  root.CarMode.open();const overlay=body.children.find(n=>n.className==='car-mode'),controls=overlay.children.find(n=>n.className==='car-controls');
+  assert.equal(controls.children.length,4);assert.equal(new Set(controls.children).size,4);assert.equal(voice.parent,body);
+  controls.children.forEach(b=>b.onclick());assert.deepEqual(actions,['prev','toggle','back','next']);
+  root.CarMode.close();assert.equal(voice.parent,body);assert.equal(body.inert,false);
+  const panel=new Element('section');body.append(panel);section.render(panel);
+  assert.equal(voice.parent,body,'settings must not steal the voice entry');assert.equal(panel.children.at(-1).textContent,'Enter Car mode');
+});

frontend/direct-media.css

@@ -0,0 +1,6 @@
+.direct-transfer-dialog{max-width:min(420px,calc(100vw - 32px));padding:24px;border:1px solid var(--border);border-radius:var(--radius,16px);background:var(--surface,#202026);color:var(--text,#fff)}
+.direct-transfer-dialog::backdrop{background:rgba(0,0,0,.65)}
+.direct-transfer-dialog p{line-height:1.6;color:var(--text-2);overflow-wrap:anywhere}
+.direct-transfer-dialog button,#settings-section-direct-transfer button{min-height:44px;padding:10px 16px;margin:4px;border:1px solid var(--border);border-radius:10px;background:var(--surface-2,#303039);color:var(--text,#fff)}
+.direct-transfer-dialog button:focus-visible,#settings-section-direct-transfer button:focus-visible{outline:2px solid var(--accent);outline-offset:3px}
+#settings-section-direct-transfer label{display:flex;align-items:center;gap:12px;min-height:44px}

frontend/direct-media.js

@@ -0,0 +1,168 @@
+/* Paired-room transport; signalling only goes to the server. */
+(function (root) {
+  'use strict';
+  const waiting = new Map();
+  let profilePeers = [];
+  const rooms = new Map(), transfers = new Map(), pending = new Map();
+  let hooks = { settings: () => ({}), persist() {}, current: () => null, saved() {}, notify() {}, fallback() {} };
+  const enabled = () => hooks.settings().directTransfer !== false && !!root.RTCPeerConnection;
+  function attach(key, room) { rooms.set(key, room); }
+  function send(key, m) { const r = rooms.get(key); if (!r) throw Error('Paired device disconnected'); r.send(m); }
+  function signal(key, token, data) { send(key, { type: 'direct', action: 'signal', token, data }); }
+  async function offer(key, to, meta) {
+    if (!enabled()) throw Error('Direct device transfer is unavailable or turned off');
+    if (!meta?.id) throw Error('Choose a saved song first');
+    if (pending.has(`${key}:${to}:${meta.id}`) || [...transfers.values()].some(s => s.key === key && s.peer === to && s.claim.id === meta.id)) return;
+    const file = await root.OPFS.getFileObject(meta.id);
+    if (!file) throw Error('Save this song on this device before sending it');
+    const hash = root.Sha256.create();
+    for (let at = 0; at < file.size; at += 1024 * 1024) hash.update(new Uint8Array(await file.slice(at, at + 1024 * 1024).arrayBuffer()));
+    const claim = root.DirectProtocol.file({ ...meta, cid: hash.hex(), size: file.size, extension: file.name.split('.').pop().toLowerCase(), streamMime: await root.DirectStream?.inspect(file), title: meta.title || meta.id });
+    if (!claim) throw Error('Unsupported file metadata');
+    const pendingKey = `${key}:${to}:${claim.id}`;
+    const item = { file, claim }; pending.set(pendingKey, item);
+    setTimeout(() => { if (pending.get(pendingKey) === item) pending.delete(pendingKey); }, 60000);
+    send(key, { type: 'direct', action: 'invite', to, file: claim });
+    hooks.notify('Waiting for the receiving device to accept');
+  }
+  function finish(s, error) {
+    if (s.done) return; s.done = true; clearTimeout(s.timer); clearTimeout(s.idle);
+    s.pc?.close(); transfers.delete(s.token);
+    if (error) s.preview?.close(); else s.preview?.end();
+    if (s.worker) { s.worker.postMessage({ op: 'abort' }); setTimeout(() => s.worker.terminate(), 1000); }
+    if (error) { waiting.get(s.claim.id)?.resolve(false); waiting.delete(s.claim.id); hooks.notify(`${error}. Partial copy kept for resume.`); hooks.fallback(s.claim, () => offer(s.key, s.peer, s.claim).catch(e => hooks.notify(e.message))); }
+  }
+  function connection(s, receiver) {
+    clearTimeout(s.timer);
+    const pc = s.pc = new RTCPeerConnection({ iceServers: [{ urls: 'stun:stun.l.google.com:19302' }] });
+    s.ice = s.ice || [];
+    pc.onicecandidate = e => { if (e.candidate) signal(s.key, s.token, { kind: 'ice', candidate: e.candidate.toJSON() }); };
+    s.timer = setTimeout(() => finish(s, 'Direct connection failed after 10 seconds'), 10000);
+    pc.onconnectionstatechange = () => { if (['failed', 'closed'].includes(pc.connectionState)) finish(s, 'Direct connection closed'); };
+    const bump = () => { clearTimeout(s.idle); s.idle = setTimeout(() => finish(s, 'Direct transfer stalled'), 30000); };
+    const channel = dc => {
+      s.dc = dc; dc.binaryType = 'arraybuffer'; dc.bufferedAmountLowThreshold = 1024 * 1024;
+      dc.onopen = () => { clearTimeout(s.timer); bump(); if (receiver && s.offset != null) dc.send(JSON.stringify({ t: 'get', offset: s.offset })); };
+      dc.onclose = () => { if (!s.done && !s.verifying) setTimeout(() => { if (!s.done && !s.verifying) finish(s, 'Direct channel closed'); }, 3000); };
+      dc.onmessage = async e => {
+        bump();
+        try {
+          if (receiver) {
+            if (typeof e.data === 'string') { const m = JSON.parse(e.data); if (m.t === 'end') { s.verifying = true; clearTimeout(s.idle); s.worker.postMessage({ op: 'finish' }); } else throw Error('Unexpected file control'); }
+            else { s.preview?.push(e.data); s.worker.postMessage({ op: 'chunk', buf: e.data }, [e.data]); }
+          } else {
+            if (typeof e.data !== 'string' || s.started) throw Error('Unexpected file request');
+            const m = JSON.parse(e.data); if (m.t !== 'get') throw Error('Unexpected file request');
+            let pos = root.DirectProtocol.offset(m.offset, s.file.size); s.started = true;
+            while (pos < s.file.size && !s.done) {
+              if (dc.bufferedAmount > 4 * 1024 * 1024) await new Promise((resolve, reject) => {
+                const timeout = setTimeout(() => { cleanup(); reject(Error('Peer stopped receiving')); }, 10000);
+                const cleanup = () => { clearTimeout(timeout); dc.removeEventListener('bufferedamountlow', low); dc.removeEventListener('close', closed); };
+                const low = () => { cleanup(); resolve(); }, closed = () => { cleanup(); reject(Error('Peer disconnected')); };
+                dc.addEventListener('bufferedamountlow', low); dc.addEventListener('close', closed);
+              });
+              const range = root.DirectProtocol.nextChunk(pos, s.file.size);
+              dc.send(await s.file.slice(range.start, range.end).arrayBuffer()); pos = range.end; bump();
+            }
+            if (!s.done) { dc.send(JSON.stringify({ t: 'end' })); clearTimeout(s.idle); s.idle = setTimeout(() => finish(s, 'Receiver did not finish verification'), 30 * 60000); }
+          }
+        } catch (err) { finish(s, err.message); }
+      };
+    };
+    if (receiver) channel(pc.createDataChannel('file', { ordered: true })); else pc.ondatachannel = e => channel(e.channel);
+    return pc;
+  }
+  async function accept(key, m) {
+    const s = { key, token: m.token, claim: m.file, peer: m.from, receiver: true }; transfers.set(m.token, s);
+    s.preview = m.file.streamMime ? root.DirectStream?.create(m.file.streamMime, m.file.title) : null;
+    const wait = waiting.get(m.file.id); if (wait) clearTimeout(wait.timer);
+    send(key, { type: 'direct', action: 'accept', token: m.token });
+    s.worker = window.Lazy ? window.Lazy.worker('/direct-recv-worker.js') : new Worker('/direct-recv-worker.js');
+    s.worker.onmessage = async e => {
+      const result = e.data;
+      if (result.op === 'opened') {
+        s.offset = result.offset;
+        connection(s, true);
+        const offer = await s.pc.createOffer(); await s.pc.setLocalDescription(offer); signal(key, m.token, { kind: 'offer', sdp: offer.sdp });
+      } else if (result.op === 'done') {
+        send(key, { type: 'direct', action: 'complete', token: m.token });
+        await hooks.saved(result.file); waiting.get(result.file.id)?.resolve(true); waiting.delete(result.file.id); publish(); hooks.notify(`Saved ${result.file.title} directly from the other device`); finish(s);
+      } else if (result.op === 'error') finish(s, result.error);
+    };
+    s.worker.postMessage({ op: 'open', file: m.file });
+  }
+  async function handle(key, m) {
+    if (m.type !== 'direct') return;
+    if (m.action === 'request') { if (enabled() && hooks.settings().p2pShare !== false) offer(key, m.from, hooks.meta?.(m.id) || { id: m.id, title: m.id }).catch(e => hooks.notify(e.message)); return; }
+    try {
+      if (m.action === 'invite') {
+        if (!enabled() || !root.DirectProtocol.file(m.file)) return send(key, { type: 'direct', action: 'decline', token: m.token });
+        confirmReceive(key, m); return;
+      }
+      if (m.action === 'invited') {
+        const p = pending.get(`${key}:${m.to}:${m.file.id}`); if (!p) return;
+        pending.delete(`${key}:${m.to}:${m.file.id}`);
+        const s = { key, token: m.token, peer: m.to, claim: p.claim, file: p.file }; transfers.set(m.token, s); s.timer = setTimeout(() => finish(s), 60000); return;
+      }
+      const s = transfers.get(m.token); if (!s || s.key !== key || m.from !== s.peer) return;
+      if (m.action === 'accept') { s.accepted = true; clearTimeout(s.timer); s.timer = setTimeout(() => finish(s, 'Receiver stopped preparing the file'), 30 * 60000); }
+      else if (m.action === 'decline' || m.action === 'complete') finish(s);
+      else if (m.action === 'signal') {
+        const d = m.data;
+        if (!s.pc && !s.receiver && s.accepted) { if (d.kind === 'ice') { (s.ice ||= []).push(d.candidate); return; } if (d.kind === 'offer') connection(s, false); }
+        if (!s.pc) return;
+        if (d.kind === 'ice') { if (s.pc.remoteDescription) await s.pc.addIceCandidate(d.candidate); else s.ice.push(d.candidate); }
+        else {
+          await s.pc.setRemoteDescription({ type: d.kind, sdp: d.sdp });
+          for (const c of s.ice.splice(0)) await s.pc.addIceCandidate(c);
+          if (d.kind === 'offer') { const a = await s.pc.createAnswer(); await s.pc.setLocalDescription(a); signal(key, m.token, { kind: 'answer', sdp: a.sdp }); }
+        }
+      }
+    } catch (e) { const s = transfers.get(m.token); if (s) finish(s, e.message); else hooks.notify(e.message); }
+  }
+  function confirmReceive(key, m) {
+    const dialog = document.createElement('dialog'); dialog.className = 'direct-transfer-dialog';
+    const heading = document.createElement('h2'); heading.textContent = 'Save from your paired device?';
+    const text = document.createElement('p'); text.textContent = `${m.file.title} · ${(m.file.size / 1024 ** 2).toFixed(1)} MB. Media travels directly between devices. Keep both screens open. Playback starts after the full copy is verified.`;
+    const yes = document.createElement('button'); yes.textContent = 'Accept & save';
+    const no = document.createElement('button'); no.textContent = 'Decline';
+    const decline = () => { waiting.get(m.file.id)?.resolve(false); waiting.delete(m.file.id); send(key, { type: 'direct', action: 'decline', token: m.token }); dialog.remove(); };
+    yes.onclick = () => { dialog.remove(); accept(key, m).catch(e => hooks.notify(e.message)); }; no.onclick = decline; dialog.oncancel = decline;
+    dialog.append(heading, text, yes, no); document.body.append(dialog); dialog.showModal();
+  }
+  async function publish() {
+    if (!root.P2PClient?.isConnected()) return;
+    const files = await root.OPFS.listVideos({ strict: true });
+    root.P2PClient.send({ type: 'direct-inventory', ids: enabled() && hooks.settings().p2pShare !== false ? files.map(f => f.id) : [] });
+  }
+  function source(id) { if (!enabled()) return null; for (const [key, room] of rooms) { const peer = room.peers().find(p => p.files?.includes(id)); if (peer) return { key, peer }; } return null; }
+  function hasSource(id) { return !!source(id); }
+  function obtain(id) {
+    if (!hasSource(id)) return Promise.resolve(null);
+    if (waiting.has(id)) return waiting.get(id).promise;
+    const { key, peer } = source(id);
+    let resolve; const promise = new Promise(r => { resolve = r; });
+    const wait = { promise, resolve }; waiting.set(id, wait);
+    send(key, { type: 'direct', action: 'request', to: peer.id, id });
+    wait.timer = setTimeout(() => { if (waiting.get(id)?.promise === promise) { waiting.delete(id); resolve(false); hooks.notify('The other device did not accept or is unavailable'); hooks.fallback(hooks.meta?.(id) || { id, title: id }); } }, 60000);
+    return promise;
+  }
+  function configure(h) {
+    hooks = { ...hooks, ...h };
+    if (root.P2PClient) {
+      root.P2PClient.onMessage('hello', () => { attach('profile', { send: root.P2PClient.send, peers: () => profilePeers }); publish(); });
+      root.P2PClient.onMessage('direct-peers', m => { profilePeers = m.peers || []; });
+      root.P2PClient.onMessage('direct', m => handle('profile', m));
+    }
+    root.SettingsSections.register({ id: 'direct-transfer', title: 'Direct device transfer', cluster: 'Library & storage', summary: () => enabled() ? 'On · paired devices only' : 'Off or unsupported', icon: '<path d="M4 6h6v12H4zM14 6h6v12h-6M10 10h4m-4 4h4"/>', render(container) {
+      const label = document.createElement('label'); const toggle = document.createElement('input'); toggle.type = 'checkbox'; toggle.checked = hooks.settings().directTransfer !== false;
+      toggle.onchange = () => { hooks.settings().directTransfer = toggle.checked; hooks.persist(); publish(); }; label.append(toggle, ' Direct device transfer (P2P)');
+      const help = document.createElement('p'); help.textContent = 'Pair through Remote or join a Watch Party, then send your currently playing saved song. The receiver confirms before saving. Keep both devices open. No TURN relay is used.';
+      container.append(label, help);
+      for (const [key, r] of rooms) for (const peer of r.peers()) {
+        const b = document.createElement('button'); b.textContent = `Send saved song to ${peer.name}`; b.style.minHeight = '44px'; b.onclick = () => offer(key, peer.id, hooks.current()).catch(e => hooks.notify(e.message)); container.append(b);
+      }
+    } });
+  }
+  root.DirectMedia = { configure, attach, handle, offer, enabled, obtain, hasSource, publish };
+}(globalThis));

frontend/direct-protocol.js

@@ -0,0 +1,41 @@
+/* Shared bounded control protocol: media bytes belong exclusively on DataChannel. */
+(function (root) {
+  'use strict';
+  const CHUNK = 65536;
+  const text = (v, n) => typeof v === 'string' && v.length <= n && !/[\u0000-\u001f]/.test(v);
+  const id = (v) => text(v, 128) && /^[A-Za-z0-9_-]+$/.test(v);
+  function file(v) {
+    if (!v || !id(v.id) || !/^[a-f0-9]{64}$/.test(v.cid) || !Number.isSafeInteger(v.size) || v.size <= 0 || v.size > 4 * 1024 ** 3) return null;
+    if (!text(v.title, 300) || !text(v.channel || '', 200)) return null;
+    const streamMime = typeof v.streamMime === 'string' && /^video\/mp4; codecs="avc1\.[a-f0-9]{6}(, mp4a\.40\.2)?"$/.test(v.streamMime) ? v.streamMime : '';
+    return { streamMime, extension: /^(mp4|m4a|webm|ogg|opus|mkv|mp3|wav|aac)$/.test(v.extension) ? v.extension : 'mp4', id: v.id, cid: v.cid, size: v.size, title: v.title, channel: v.channel || '', duration: Number.isFinite(v.duration) && v.duration >= 0 ? v.duration : 0 };
+  }
+  function parse(value) {
+    if (typeof value === 'string') { if (value.length > 65536) return null; try { value = JSON.parse(value); } catch { return null; } }
+    if (!value || typeof value !== 'object' || Array.isArray(value) || value.type !== 'direct') return null;
+    const m = { type: 'direct', action: value.action };
+    if (value.action === 'request') return id(value.to) && id(value.id) ? { ...m, to: value.to, id: value.id } : null;
+    if (value.action === 'invite') {
+      const f = file(value.file); if (!id(value.to) || !f) return null;
+      return { ...m, to: value.to, file: f };
+    }
+    if (!['accept', 'decline', 'signal', 'complete'].includes(value.action) || !id(value.token)) return null;
+    m.token = value.token;
+    if (value.action === 'signal') {
+      const d = value.data;
+      if (!d || typeof d !== 'object') return null;
+      if (['offer', 'answer'].includes(d.kind) && typeof d.sdp === 'string' && d.sdp.length <= 60000) m.data = { kind: d.kind, sdp: d.sdp };
+      else if (d.kind === 'ice' && d.candidate && text(d.candidate.candidate, 2048)) {
+        const c = d.candidate;
+        if (!(c.sdpMid == null || text(c.sdpMid, 64)) || !(c.sdpMLineIndex == null || Number.isInteger(c.sdpMLineIndex) && c.sdpMLineIndex >= 0 && c.sdpMLineIndex < 100)) return null;
+        m.data = { kind: 'ice', candidate: { candidate: c.candidate, sdpMid: c.sdpMid ?? null, sdpMLineIndex: c.sdpMLineIndex ?? null } };
+      } else return null;
+    }
+    return m;
+  }
+  function offset(v, size) { if (!Number.isSafeInteger(v) || v < 0 || v > size) throw new Error('Invalid resume offset'); return v; }
+  function nextChunk(pos, size) { offset(pos, size); return { start: pos, end: Math.min(size, pos + CHUNK) }; }
+  const api = { CHUNK, file, parse, offset, nextChunk };
+  if (typeof module !== 'undefined') module.exports = api;
+  root.DirectProtocol = api;
+}(typeof globalThis !== 'undefined' ? globalThis : this));

frontend/direct-protocol.test.js

@@ -0,0 +1,18 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const p = require('./direct-protocol.js');
+test('direct protocol strips unexpected payload and validates file claims', () => {
+  const m = p.parse({ type: 'direct', action: 'invite', to: 'peer', file: { id: 'video', title: 'Song', cid: 'a'.repeat(64), size: 10, bytes: 'secret' }, bytes: 'not relayed' });
+  assert.equal(m.file.size, 10); assert.equal(m.bytes, undefined); assert.equal(m.file.bytes, undefined);
+  assert.equal(p.parse({ ...m, file: { ...m.file, size: Infinity } }), null);
+  assert.equal(p.parse(new Uint8Array(4)), null);
+});
+test('chunks retain exact resume offset and never exceed file end', () => {
+  assert.deepEqual(p.nextChunk(17, 100000), { start: 17, end: 65553 });
+  assert.deepEqual(p.nextChunk(99999, 100000), { start: 99999, end: 100000 });
+  for (const n of [-1, 100001, 0.5, NaN]) assert.throws(() => p.offset(n, 100000));
+});
+test('signalling only admits bounded SDP or ICE, never byte frames', () => {
+  assert.equal(p.parse({ type: 'direct', action: 'signal', token: 'abc', data: { kind: 'bytes', data: [1, 2] } }), null);
+  assert.equal(p.parse({ type: 'direct', action: 'signal', token: 'abc', data: { kind: 'offer', sdp: 'x'.repeat(60001) } }), null);
+});

frontend/direct-recv-worker.js

@@ -0,0 +1,40 @@
+'use strict';
+let dir, handle, access, hash, pos = 0, claim, name;
+let chain = Promise.resolve();
+self.onmessage = e => { chain = chain.then(() => run(e.data)); };
+async function close() { if (access) { access.flush(); access.close(); access = null; } }
+async function run(m) {
+  try {
+    if (!self.Sha256) { self.__ASSET_URLS__=m.assetUrls || {}; importScripts(self.__ASSET_URLS__.sha256 || '/sha256.js'); }
+    if (m.op === 'open') {
+      claim = m.file;
+      if (!/^[A-Za-z0-9_-]{1,128}$/.test(claim.id) || !/^[a-f0-9]{64}$/.test(claim.cid)) throw Error('Invalid file identity');
+      dir = await (await navigator.storage.getDirectory()).getDirectoryHandle('videos', { create: true });
+      name = `${claim.id}.${claim.cid}.direct.part`;
+      handle = await dir.getFileHandle(name, { create: true });
+      access = await handle.createSyncAccessHandle();
+      pos = access.getSize(); if (pos > claim.size) { access.truncate(0); pos = 0; }
+      hash = self.Sha256.create();
+      for (let at = 0; at < pos; at += 1024 * 1024) { const b = new Uint8Array(Math.min(1024 * 1024, pos - at)); access.read(b, { at }); hash.update(b); }
+      self.postMessage({ op: 'opened', offset: pos });
+    } else if (m.op === 'chunk') {
+      const b = new Uint8Array(m.buf);
+      if (!access || b.length > 65536 || pos + b.length > claim.size) throw Error('Invalid file chunk');
+      if (access.write(b, { at: pos }) !== b.length) throw Error('Incomplete OPFS write');
+      hash.update(b); pos += b.length; access.flush();
+      self.postMessage({ op: 'progress', received: pos });
+    } else if (m.op === 'abort') { await close(); self.postMessage({ op: 'closed' }); }
+    else if (m.op === 'finish') {
+      await close();
+      if (pos !== claim.size || hash.hex() !== claim.cid) { await dir.removeEntry(name); throw Error('File verification failed; retry starts from zero'); }
+      const extension = /^(mp4|m4a|webm|ogg|opus|mkv|mp3|wav|aac)$/.test(claim.extension) ? claim.extension : 'mp4';
+      const final = `${claim.id}.${extension}`;
+      // Copy only after verification; existing saved playback remains intact until then.
+      const out = await (await dir.getFileHandle(final, { create: true })).createSyncAccessHandle();
+      try { const f = await handle.getFile(); for (let at = 0; at < f.size; at += 1024 * 1024) out.write(new Uint8Array(await f.slice(at, at + 1024 * 1024).arrayBuffer()), { at }); out.truncate(f.size); out.flush(); } finally { out.close(); }
+      await dir.removeEntry(name);
+      for await (const [old, entry] of dir.entries()) { if (entry.kind === 'file' && old !== final && old.startsWith(claim.id + '.') && /\.(mp4|m4a|webm|ogg|opus|mkv|mp3|wav|aac)$/.test(old)) await dir.removeEntry(old); }
+      self.postMessage({ op: 'done', file: claim });
+    }
+  } catch (e) { await close(); self.postMessage({ op: 'error', error: e.message }); }
+}

frontend/direct-stream.js

@@ -0,0 +1,44 @@
+/* Progressive preview is only safe for fragmented MP4, never ordinary MP4 chunks. */
+(function (root) {
+  'use strict';
+  function inspectBytes(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const str = (at, n) => String.fromCharCode(...bytes.subarray(at, at + n));
+    let at = 0, moov = null;
+    while (at + 8 <= bytes.length) {
+      const size = view.getUint32(at); if (size < 8 || at + size > bytes.length) break;
+      if (str(at + 4, 4) === 'moov') { moov = bytes.subarray(at + 8, at + size); break; }
+      at += size;
+    }
+    if (!moov) return null;
+    const tagAt = (tag) => { for (let i = 4; i + 4 <= moov.length; i++) if (String.fromCharCode(...moov.subarray(i, i + 4)) === tag) return i; return -1; };
+    if (tagAt('mvex') < 0) return null;
+    const avc = tagAt('avcC'), audio = tagAt('mp4a');
+    if (avc < 0 || avc + 8 > moov.length || moov[avc + 4] !== 1) return null;
+    const codec = Array.from(moov.subarray(avc + 5, avc + 8), b => b.toString(16).padStart(2, '0')).join('');
+    return `video/mp4; codecs="avc1.${codec}${audio >= 0 ? ', mp4a.40.2' : ''}"`;
+  }
+  async function inspect(file) { return inspectBytes(new Uint8Array(await file.slice(0, 1024 * 1024).arrayBuffer())); }
+  function create(mime, title) {
+    if (!root.MediaSource?.isTypeSupported(mime)) return null;
+    const media = new MediaSource(), url = URL.createObjectURL(media), queue = [];
+    let buffer, queued = 0, ended = false, stopped = false;
+    const dialog = document.createElement('dialog'); dialog.className = 'direct-transfer-dialog';
+    const heading = document.createElement('h2'); heading.textContent = title;
+    const note = document.createElement('p'); note.textContent = 'Direct preview · the full copy is still being saved and verified. Tap Play when ready.';
+    const video = document.createElement('video'); video.controls = true; video.playsInline = true; video.src = url; video.style.width = '100%';
+    const close = document.createElement('button'); close.textContent = 'Close preview';
+    const dispose = () => { stopped = true; queue.length = 0; video.pause(); video.removeAttribute('src'); video.load(); URL.revokeObjectURL(url); dialog.remove(); };
+    close.onclick = dispose; dialog.oncancel = e => { e.preventDefault(); dispose(); }; dialog.append(heading, note, video, close); document.body.append(dialog); dialog.showModal();
+    function flush() {
+      if (stopped || !buffer || buffer.updating) return;
+      if (queue.length) { const b = queue.shift(); queued -= b.byteLength; try { buffer.appendBuffer(b); } catch { dispose(); } }
+      else if (ended && media.readyState === 'open') { try { media.endOfStream(); } catch {} }
+    }
+    media.addEventListener('sourceopen', () => { try { buffer = media.addSourceBuffer(mime); buffer.addEventListener('updateend', flush); buffer.addEventListener('error', dispose); flush(); } catch { dispose(); } }, { once: true });
+    return { push(bytes) { if (stopped) return; queued += bytes.byteLength; if (queued > 8 * 1024 * 1024) { dispose(); return; } queue.push(bytes.slice(0)); flush(); }, end() { ended = true; flush(); }, close: dispose };
+  }
+  const api = { inspectBytes, inspect, create };
+  if (typeof module !== 'undefined') module.exports = api;
+  root.DirectStream = api;
+}(globalThis));

frontend/direct-stream.test.js

@@ -0,0 +1,12 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { inspectBytes } = require('./direct-stream.js');
+function box(type, payload = Buffer.alloc(0)) { const b = Buffer.alloc(8 + payload.length); b.writeUInt32BE(b.length); b.write(type, 4); payload.copy(b, 8); return b; }
+test('progressive playback only accepts a complete fragmented MP4 initialization', () => {
+  const codec = box('avcC', Buffer.from([1, 0x64, 0, 0x1f]));
+  const fragmented = Buffer.concat([box('ftyp'), box('moov', Buffer.concat([box('mvex'), codec, box('mp4a')]))]);
+  assert.equal(inspectBytes(fragmented), 'video/mp4; codecs="avc1.64001f, mp4a.40.2"');
+  assert.equal(inspectBytes(Buffer.concat([box('ftyp'), box('moov', codec)])), null);
+  assert.equal(inspectBytes(fragmented.subarray(0, fragmented.length - 1)), null);
+  assert.equal(inspectBytes(Buffer.alloc(0)), null);
+});

frontend/download-actions.css

@@ -0,0 +1,11 @@
+/* Shared quiet controls; use each layout's existing surface and focus tokens. */
+:is(.dl-row,.download-job) .download-action { display:inline-flex; align-items:center; justify-content:center; flex:none; gap:8px; height:auto; min-height:44px; min-width:44px; padding:8px 14px; border:1px solid var(--line); border-radius:var(--radius-sm); background:var(--bg-2); color:var(--text); font:600 13px var(--ui); line-height:1.4; cursor:pointer; white-space:nowrap; }
+:is(.dl-row,.download-job) .download-action:hover { background:var(--bg-3); border-color:var(--accent); }
+:is(.dl-row,.download-job) .download-action.danger { color:var(--accent); }
+:is(.dl-row,.download-job) .download-action:focus-visible { outline:2px solid var(--accent); outline-offset:3px; }
+:is(.dl-row,.download-job) .download-action:disabled { opacity:.5; cursor:not-allowed; }
+.download-action-icon { width:20px; height:20px; flex:none; fill:none; stroke:currentColor; stroke-width:1.9; stroke-linecap:round; stroke-linejoin:round; pointer-events:none; }
+html[data-layout="glass-stage"] :is(.dl-row,.download-job) .download-action { border-radius:18px; border-color:var(--glass-line); background:var(--tile); color:var(--text-2); box-shadow:none; }
+html[data-layout="glass-stage"] :is(.dl-row,.download-job) .download-action:hover { border-color:var(--glass-line); background:var(--tile-hi); color:var(--text); }
+html[data-layout="glass-stage"] :is(.dl-row,.download-job) .download-action.danger { color:var(--accent-bright); }
+html[data-layout="glass-stage"] :is(.dl-row,.download-job) .download-action:focus-visible { outline-color:var(--accent-bright); }

frontend/download-actions.js

@@ -0,0 +1,24 @@
+/* One action control for the Downloads page and Settings download manager. */
+(function(root) {
+  'use strict';
+  const paths = {
+    retry: '<path d="M3 11a9 9 0 1 1 2.6 7M3 3v8h8"/>',
+    cancel: '<path d="m6 6 12 12M6 18 18 6"/>',
+    pause: '<path d="M8 5v14M16 5v14"/>',
+    resume: '<path d="m9 5 10 7-10 7z"/>',
+  };
+  function create(doc, action, title) {
+    if (!paths[action]) throw new Error('Unknown download action');
+    const label = action[0].toUpperCase() + action.slice(1);
+    const button = doc.createElement('button'); button.type = 'button';
+    button.className = `dl-act download-action${action === 'cancel' ? ' danger' : ''}`;
+    button.setAttribute('aria-label', `${label} ${title}`);
+    const icon = doc.createElementNS('http://www.w3.org/2000/svg', 'svg');
+    icon.setAttribute('viewBox', '0 0 24 24'); icon.setAttribute('aria-hidden', 'true'); icon.setAttribute('focusable', 'false');
+    icon.classList.add('download-action-icon'); icon.innerHTML = paths[action];
+    const text = doc.createElement('span'); text.textContent = label;
+    button.append(icon, text); return button;
+  }
+  const api = { create };
+  if (typeof module !== 'undefined' && module.exports) module.exports = api; else root.DownloadActions = api;
+})(globalThis);

frontend/download-errors.js

@@ -0,0 +1,28 @@
+/* Plain-language save failures, with the original diagnostic kept on demand. */
+(function(root) {
+  'use strict';
+  function message(error) {
+    const raw = String(error?.message || error || '').trim();
+    if (!raw) return 'Could not save this video. Try Retry.';
+    if (/not available in your country|geo.?restricted/i.test(raw)) return 'This video is unavailable in the server’s region. It may still play on your device.';
+    if (/private video|members.only|join this channel|confirm your age|age.restricted/i.test(raw)) return 'YouTube requires access this server does not have to save this video.';
+    if (/removed by|video has been removed|copyright claim/i.test(raw)) return 'YouTube is no longer making this video available to the server.';
+    if (/sign in to confirm|not a bot/i.test(raw)) return 'YouTube temporarily blocked the server’s download request. Try Retry later.';
+    if (/video unavailable/i.test(raw)) return 'YouTube isn’t letting the server save this video. Try Retry; it may still play on YouTube.';
+    if (/requested format (?:is )?not available|no video formats found/i.test(raw)) return 'No downloadable version was available. Try Retry to check other download methods.';
+    if (/^ERROR:|^WARNING:|Traceback|yt-dlp exited|yt-dlp not found/i.test(raw)) return 'The server could not save this video. Try Retry.';
+    // Existing plain-language connection/quota/validation messages remain useful.
+    return raw.length <= 180 && !raw.includes('\n') ? raw : 'Could not save this video. Try Retry.';
+  }
+  function appendDetails(container, error) {
+    if (!error) return;
+    const doc = container.ownerDocument;
+    const details = doc.createElement('details'); details.className = 'download-error-details';
+    const summary = doc.createElement('summary'); summary.textContent = 'Technical details';
+    const pre = doc.createElement('pre'); pre.textContent = String(error?.message || error);
+    details.append(summary, pre); container.append(details);
+    return details;
+  }
+  const api = { message, appendDetails };
+  if (typeof module !== 'undefined') module.exports = api; else root.DownloadErrors = api;
+})(typeof window !== 'undefined' ? window : globalThis);

frontend/download-errors.test.js

@@ -0,0 +1,24 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { message } = require('./download-errors.js');
+const { formatJobStatus } = require('./downloads-page.js');
+test('unavailable songs get useful copy without claiming that they were removed', () => {
+  const raw = 'ERROR: [youtube] wZzRoXymOUU: Video unavailable\nYouTube clients tried: default, web_embedded, web_safari';
+  assert.equal(message(raw), 'YouTube isn’t letting the server save this video. Try Retry; it may still play on YouTube.');
+  assert.equal(formatJobStatus({ status: 'failed', error: raw }), 'Failed: ' + message(raw));
+});
+test('known restrictions and bot failures have distinct explanations', () => {
+  assert.match(message('Video unavailable. not available in your country'), /server’s region/);
+  assert.match(message('Video unavailable. Private video'), /requires access/);
+  assert.match(message('Video unavailable. Confirm your age'), /requires access/);
+  assert.match(message('Video has been removed'), /no longer/);
+  assert.match(message('Sign in to confirm you are not a bot'), /temporarily blocked/);
+  assert.match(message('Requested format is not available'), /other download methods/);
+});
+test('missing and raw tool failures get a short fallback; existing useful messages survive', () => {
+  assert.equal(message(null), 'Could not save this video. Try Retry.');
+  assert.equal(message('ERROR: mysterious extractor failure'), 'The server could not save this video. Try Retry.');
+  assert.equal(message('Connection lost'), 'Connection lost');
+  assert.equal(message('Please wait a few seconds before trying again.'), 'Please wait a few seconds before trying again.');
+  assert.equal(message('a'.repeat(200)), 'Could not save this video. Try Retry.');
+});

frontend/downloads-page.js

@@ -0,0 +1,296 @@
+/* Downloads page UI module. Grouped jobs, storage info, confirmed cancellation. */
+(function (root) {
+  'use strict';
+  const actionButtons = typeof module !== 'undefined' ? require('./download-actions.js') : root.DownloadActions;
+  const errors = typeof module !== 'undefined' ? require('./download-errors.js') : root.DownloadErrors;
+
+  const bytes = n => {
+    if (typeof n !== 'number' || isNaN(n) || n <= 0) return '0 MB';
+    return n >= 1073741824 ? `${(n / 1073741824).toFixed(1)} GB` : `${(n / 1048576).toFixed(1)} MB`;
+  };
+
+  function escapeHtml(str) {
+    return String(str || '')
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;');
+  }
+
+  function formatJobStatus(job) {
+    if (job.status === 'failed') {
+      return job.error ? `Failed: ${errors.message(job.error)}` : 'Save failed';
+    }
+    if (job.status === 'paused') {
+      return 'Paused — resume when you’re ready';
+    }
+    if (job.status === 'queued') {
+      return 'Waiting for a free slot…';
+    }
+    const p = job.progress;
+    if (p) {
+      if (p.phase === 'waiting') return 'Waiting for a free slot…';
+      if (p.phase === 'preparing') return `Preparing on server… ${Math.round((p.elapsed || 0) / 1000)} s`;
+      if (p.phase === 'verifying') return 'Verifying…';
+      if (p.total) {
+        return `${(p.received / 1048576).toFixed(1)} / ${(p.total / 1048576).toFixed(1)} MB`;
+      }
+    }
+    return 'Saving for offline…';
+  }
+
+  function groupJobs(jobs) {
+    const groups = {
+      active: [],
+      queued: [],
+      paused: [],
+      failed: []
+    };
+    for (const job of jobs || []) {
+      const st = job.status || 'paused';
+      if (groups[st]) {
+        groups[st].push(job);
+      } else {
+        groups.paused.push(job);
+      }
+    }
+    return groups;
+  }
+
+  function confirmCancel(job, options) {
+    const title = job.title || job.id;
+    const message = `Cancel saving “${title}”?`;
+    const subtext = 'The part already downloaded will be deleted.';
+
+    if (options.showModal && typeof options.showModal === 'function') {
+      const body = options.doc ? options.doc.createTextNode(subtext) : subtext;
+      options.showModal(message, body, [
+        { label: 'Keep', onClick: options.closeModal || (() => {}) },
+        {
+          label: 'Cancel save',
+          danger: true,
+          onClick: () => {
+            options.onAction(job.id, 'cancel');
+            if (options.closeModal) options.closeModal();
+            if (options.refresh) options.refresh();
+          }
+        }
+      ]);
+    } else if (typeof root.confirm === 'function') {
+      if (root.confirm(`${message}\n${subtext}`)) {
+        options.onAction(job.id, 'cancel');
+        if (options.refresh) options.refresh();
+      }
+    } else {
+      options.onAction(job.id, 'cancel');
+      if (options.refresh) options.refresh();
+    }
+  }
+
+  let watcher;
+  function render(container, options = {}) {
+    clearInterval(watcher);
+    if (!container) return;
+    const doc = container.ownerDocument || document;
+    const downloadsApi = options.downloadsApi || root.Downloads;
+    const jobs = options.jobs || (downloadsApi && downloadsApi.getJobs ? downloadsApi.getJobs() : []);
+    const onAction = options.onAction || (downloadsApi && downloadsApi.action ? downloadsApi.action.bind(downloadsApi) : () => {});
+    const onNavigateSaved = options.onNavigateSaved || (() => {});
+
+    container.replaceChildren();
+    if (options.isActive && options.refresh) {
+      const state = items => JSON.stringify(items.map(j => [j.id, j.status, j.error]));
+      const signature = state(jobs);
+      watcher = setInterval(() => {
+        if (!options.isActive()) { clearInterval(watcher); return; }
+        if (signature !== state(downloadsApi.getJobs())) options.refresh();
+      }, 1000);
+    }
+
+    const query = (options.filter || '').toLowerCase();
+    const visibleJobs = jobs.filter(job => `${job.title || job.id} ${job.channel || ''}`.toLowerCase().includes(query));
+    if (jobs.length && !visibleJobs.length) {
+      const message = doc.createElement('p'); message.className = 'status'; message.textContent = 'No downloads match your filter.'; container.append(message); return;
+    }
+    if (!jobs.length) {
+      // Calm SVG Empty State
+      const empty = doc.createElement('div');
+      empty.className = 'empty-state dl-empty-state';
+      empty.innerHTML = `
+        <div class="empty-icon dl-empty-icon-wrapper" aria-hidden="true">
+          <svg class="dl-empty-svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+            <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"></path>
+            <polyline points="7 10 12 15 17 10"></polyline>
+            <line x1="12" y1="15" x2="12" y2="3"></line>
+          </svg>
+        </div>
+        <h3 class="empty-title">No active downloads</h3>
+        <p class="empty-desc">Saves in progress appear here with live status. Videos you save land in <strong>Saved</strong>.</p>
+        <p class="dl-how-to-save">Save videos for offline listening using the Save button on any track or playlist.</p>
+        <div class="dl-storage-note">Calculating storage…</div>
+      `;
+
+      const cta = doc.createElement('button');
+      cta.type = 'button';
+      cta.className = 'empty-cta dl-saved-cta';
+      cta.textContent = 'View saved videos';
+      cta.addEventListener('click', onNavigateSaved);
+      empty.appendChild(cta);
+      container.appendChild(empty);
+
+      if (downloadsApi && downloadsApi.getFiles) {
+        Promise.resolve(downloadsApi.getFiles()).then(files => {
+          const storageNote = empty.querySelector('.dl-storage-note');
+          if (storageNote && files) {
+            const playlists = downloadsApi.getPlaylists ? downloadsApi.getPlaylists() : [];
+            const stats = downloadsApi.breakdown ? downloadsApi.breakdown(files, playlists) : null;
+            const totalStr = stats ? bytes(stats.total) : bytes(files.reduce((a, b) => a + (b.size || 0), 0));
+            storageNote.textContent = `Device storage used by saved media: ${totalStr}`;
+          }
+        }).catch(() => {
+          const storageNote = empty.querySelector('.dl-storage-note');
+          if (storageNote) storageNote.textContent = '';
+        });
+      }
+      return;
+    }
+
+    // Summary Header
+    const summary = doc.createElement('div');
+    summary.className = 'saved-summary dl-summary';
+    const totalCount = jobs.length;
+    summary.textContent = `${totalCount} download${totalCount === 1 ? '' : 's'}`;
+
+    const savedLinkBtn = doc.createElement('button');
+    savedLinkBtn.type = 'button';
+    savedLinkBtn.className = 'dl-saved-link';
+    savedLinkBtn.textContent = 'View saved';
+    savedLinkBtn.addEventListener('click', onNavigateSaved);
+    summary.appendChild(savedLinkBtn);
+
+    container.appendChild(summary);
+
+    // Grouped Consistent Rows
+    const groups = groupJobs(visibleJobs);
+    const sections = [
+      { key: 'active', title: 'Active downloads' },
+      { key: 'queued', title: 'Queued' },
+      { key: 'paused', title: 'Paused' },
+      { key: 'failed', title: 'Failed' }
+    ];
+
+    for (const sec of sections) {
+      const secJobs = groups[sec.key];
+      if (!secJobs || !secJobs.length) continue;
+
+      const groupDiv = doc.createElement('div');
+      groupDiv.className = `dl-group dl-group-${sec.key}`;
+
+      const groupHeading = doc.createElement('h4');
+      groupHeading.className = 'dl-group-title';
+      groupHeading.textContent = `${sec.title} (${secJobs.length})`;
+      groupDiv.appendChild(groupHeading);
+
+      for (const job of secJobs) {
+        const isPaused = job.status === 'paused';
+        const isFailed = job.status === 'failed';
+        const isActive = job.status === 'active' || job.status === 'queued';
+
+        const row = doc.createElement('div');
+        row.className = `card downloading dl-row ${isPaused ? 'dl-paused' : ''} ${isFailed ? 'dl-failed' : ''} ${isActive ? 'dl-active' : ''}`;
+        row.dataset.id = job.id;
+
+        const thumbUrl = job.thumbnail || (options.thumbUrlFor ? options.thumbUrlFor(job.id, job) : '');
+
+        const p = job.progress;
+        const pct = p && p.total ? Math.max(1, Math.min(100, (p.received / p.total) * 100)) : null;
+
+        row.innerHTML = `
+          <div class="thumb">
+            <img loading="lazy" decoding="async" src="${escapeHtml(thumbUrl)}" alt="" />
+            <div class="dl-progress"><div class="dl-bar ${pct !== null ? 'determinate' : ''}" style="${pct !== null ? 'width:' + pct + '%' : ''}"></div></div>
+          </div>
+          <div class="card-info">
+            <div class="card-title">${escapeHtml(job.title || job.id)}</div>
+            <div class="card-channel">${escapeHtml(formatJobStatus(job))}</div>
+          </div>
+        `;
+
+        if (isFailed && job.error) errors.appendDetails(row.querySelector('.card-info'), job.error);
+
+        const acts = doc.createElement('div');
+        acts.className = 'dl-actions';
+
+        if (isActive) {
+          const pauseBtn = actionButtons.create(doc, 'pause', job.title || job.id);
+          pauseBtn.setAttribute('aria-label', `Pause ${job.title || job.id}`);
+          pauseBtn.onclick = (e) => {
+            e.stopPropagation();
+            onAction(job.id, 'pause');
+            if (options.refresh) options.refresh();
+          };
+          acts.appendChild(pauseBtn);
+        } else if (isPaused) {
+          const resumeBtn = actionButtons.create(doc, 'resume', job.title || job.id);
+          resumeBtn.setAttribute('aria-label', `Resume ${job.title || job.id}`);
+          resumeBtn.onclick = (e) => {
+            e.stopPropagation();
+            onAction(job.id, 'resume');
+            if (options.refresh) options.refresh();
+          };
+          acts.appendChild(resumeBtn);
+        } else if (isFailed) {
+          const retryBtn = actionButtons.create(doc, 'retry', job.title || job.id);
+          retryBtn.setAttribute('aria-label', `Retry ${job.title || job.id}`);
+          retryBtn.onclick = (e) => {
+            e.stopPropagation();
+            onAction(job.id, 'retry');
+            if (options.refresh) options.refresh();
+          };
+          acts.appendChild(retryBtn);
+        }
+
+        const cancelBtn = actionButtons.create(doc, 'cancel', job.title || job.id);
+        cancelBtn.setAttribute('aria-label', `Cancel ${job.title || job.id}`);
+        cancelBtn.onclick = (e) => {
+          e.stopPropagation();
+          confirmCancel(job, {
+            showModal: options.showModal,
+            closeModal: options.closeModal,
+            doc,
+            onAction,
+            refresh: options.refresh
+          });
+        };
+        acts.appendChild(cancelBtn);
+
+        row.querySelector('.card-info').appendChild(acts);
+        groupDiv.appendChild(row);
+      }
+
+      container.appendChild(groupDiv);
+    }
+
+    if (groups.paused.length && root.OPFS && root.OPFS.listPartials) {
+      root.OPFS.listPartials().then(parts => {
+        for (const p of parts) {
+          const row = container.querySelector(`.card.dl-paused[data-id="${CSS.escape(p.id)}"]`);
+          if (!row || !p.size) continue;
+          const bar = row.querySelector('.dl-bar');
+          if (bar) {
+            bar.classList.add('determinate');
+            bar.style.width = Math.max(1, Math.min(100, (p.received / p.size) * 100)) + '%';
+          }
+          const ch = row.querySelector('.card-channel');
+          if (ch) {
+            ch.textContent = `Paused at ${(p.received / 1048576).toFixed(1)} / ${(p.size / 1048576).toFixed(1)} MB — resume when you’re ready`;
+          }
+        }
+      }).catch(() => {});
+    }
+  }
+
+  const api = { render, groupJobs, formatJobStatus, escapeHtml, bytes };
+  if (typeof module !== 'undefined') module.exports = api; else root.DownloadsPage = api;
+})(typeof window !== 'undefined' ? window : globalThis);

frontend/downloads-page.test.js

@@ -0,0 +1,50 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const DownloadsPage = require('./downloads-page.js');
+
+test('groupJobs categorizes active, queued, paused, and failed jobs correctly', () => {
+  const jobs = [
+    { id: '1', title: 'Job 1', status: 'active' },
+    { id: '2', title: 'Job 2', status: 'queued' },
+    { id: '3', title: 'Job 3', status: 'paused' },
+    { id: '4', title: 'Job 4', status: 'failed', error: 'Network error' }
+  ];
+  const groups = DownloadsPage.groupJobs(jobs);
+  assert.equal(groups.active.length, 1);
+  assert.equal(groups.queued.length, 1);
+  assert.equal(groups.paused.length, 1);
+  assert.equal(groups.failed.length, 1);
+  assert.equal(groups.active[0].id, '1');
+  assert.equal(groups.failed[0].error, 'Network error');
+});
+
+test('formatJobStatus produces plain text labels without emojis for all job states', () => {
+  assert.equal(DownloadsPage.formatJobStatus({ status: 'failed', error: 'Connection lost' }), 'Failed: Connection lost');
+  assert.equal(DownloadsPage.formatJobStatus({ status: 'failed' }), 'Save failed');
+  assert.equal(DownloadsPage.formatJobStatus({ status: 'paused' }), 'Paused — resume when you’re ready');
+  assert.equal(DownloadsPage.formatJobStatus({ status: 'queued' }), 'Waiting for a free slot…');
+  assert.equal(
+    DownloadsPage.formatJobStatus({ status: 'active', progress: { received: 10485760, total: 52428800 } }),
+    '10.0 / 50.0 MB'
+  );
+  assert.equal(
+    DownloadsPage.formatJobStatus({ status: 'active', progress: { phase: 'preparing', elapsed: 3000 } }),
+    'Preparing on server… 3 s'
+  );
+  assert.equal(DownloadsPage.formatJobStatus({ status: 'active', progress: { phase: 'verifying' } }), 'Verifying…');
+  assert.equal(DownloadsPage.formatJobStatus({ status: 'active' }), 'Saving for offline…');
+});
+
+test('bytes formatting handles bytes, MB, GB and invalid input safely', () => {
+  assert.equal(DownloadsPage.bytes(0), '0 MB');
+  assert.equal(DownloadsPage.bytes(10485760), '10.0 MB');
+  assert.equal(DownloadsPage.bytes(1073741824), '1.0 GB');
+  assert.equal(DownloadsPage.bytes(-100), '0 MB');
+  assert.equal(DownloadsPage.bytes(null), '0 MB');
+});
+
+test('escapeHtml escapes dangerous HTML characters', () => {
+  assert.equal(DownloadsPage.escapeHtml('<script>alert("xss")</script>'), '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;');
+  assert.equal(DownloadsPage.escapeHtml('Tom & Jerry'), 'Tom &amp; Jerry');
+});
+

frontend/downloads.js

@@ -0,0 +1,59 @@
+/* Download controls and device storage accounting. */
+(function(root) {
+  'use strict';
+  const actionButtons = typeof module !== 'undefined' ? require('./download-actions.js') : root.DownloadActions;
+  const errors = typeof module !== 'undefined' ? require('./download-errors.js') : root.DownloadErrors;
+  const bytes = n => n >= 1073741824 ? `${(n / 1073741824).toFixed(1)} GB` : `${(n / 1048576).toFixed(1)} MB`;
+  function breakdown(files, playlists) {
+    const kinds = { video: 0, audio: 0, eq: 0 }, byId = new Map();
+    for (const f of files) { const size = Math.max(0, Number(f.size) || 0); kinds[f.kind in kinds ? f.kind : 'video'] += size; byId.set(f.id, (byId.get(f.id) || 0) + size); }
+    return { total: Object.values(kinds).reduce((a, b) => a + b, 0), kinds, playlists: playlists.map(p => ({ id: p.id, name: p.name || p.title || 'Playlist', size: [...new Set((p.videos || []).map(v => v.id))].reduce((n, id) => n + (byId.get(id) || 0), 0) })) };
+  }
+  let adapter, total = 0;
+  function configure(options) {
+    adapter = options;
+    root.SettingsSections.register({ id: 'downloads-storage', title: 'Downloads & storage', cluster: 'Library & storage', description: 'Active queued paused failed saves, disk usage and playlist sizes', icon: '<path d="M12 3v12m-5-5 5 5 5-5M4 17v4h16v-4"/>', summary: () => `${adapter.slots()} at once · ${bytes(total)}`, render(container) {
+      const doc = container.ownerDocument;
+      const heading = doc.createElement('h3'); heading.textContent = 'Downloads & storage';
+      const jobs = doc.createElement('div'); jobs.className = 'download-manager'; jobs.setAttribute('aria-label', 'Download manager');
+      const storage = doc.createElement('div'); storage.className = 'download-storage';
+      container.append(heading, jobs, storage);
+      let alive = true, signature = '';
+      function paint() {
+        const items = adapter.jobs(); const next = JSON.stringify(items); if (next === signature) return; signature = next;
+        jobs.replaceChildren();
+        if (!items.length) { const p = doc.createElement('p'); p.textContent = 'No pending downloads.'; jobs.append(p); }
+        for (const job of items) {
+          const row = doc.createElement('div'); row.className = 'download-job';
+          const title = doc.createElement('b'); title.textContent = job.title || job.id;
+          const status = doc.createElement('small'); status.textContent = job.error ? errors.message(job.error) : job.status;
+          const progress = doc.createElement('progress'); progress.max = job.progress?.total || 1; if (job.progress?.total) progress.value = job.progress.received || 0; progress.setAttribute('aria-label', `Saving ${job.title || job.id}`);
+          const actions = doc.createElement('div');
+          for (const action of [...(['active', 'queued'].includes(job.status) ? ['pause'] : [job.status === 'failed' ? 'retry' : 'resume']), 'cancel']) {
+            const button = actionButtons.create(doc, action, job.title || job.id); button.onclick = () => { adapter.action(job.id, action); signature = ''; paint(); }; actions.append(button);
+          }
+          row.append(title, status, progress, actions);
+          if (job.error) errors.appendDetails(row, job.error);
+          jobs.append(row);
+        }
+      }
+      async function disk() {
+        try {
+          const [files, estimate] = await Promise.all([adapter.files(), root.navigator.storage?.estimate?.() || {}]); if (!alive) return;
+          const stats = breakdown(files, adapter.playlists()); total = stats.total; storage.replaceChildren();
+          for (const text of [`Device media: ${bytes(total)}`, `Video ${bytes(stats.kinds.video)} · Audio ${bytes(stats.kinds.audio)} · EQ renders ${bytes(stats.kinds.eq)}`, estimate.quota ? `Available browser storage: ${bytes(Math.max(0, estimate.quota - (estimate.usage || 0)))}` : 'Available browser storage is not reported.', ...stats.playlists.map(p => `${p.name}: ${bytes(p.size)}`), 'Playlist totals include shared files; device totals count each file once. Browser quota is not total device free space.']) { const p = doc.createElement('p'); p.textContent = text; storage.append(p); }
+          storage.dispatchEvent(new Event('change', { bubbles: true }));
+        } catch { storage.textContent = 'Storage details are unavailable on this device.'; }
+      }
+      paint(); disk(); const timer = setInterval(paint, 1000), diskTimer = setInterval(disk, 15000);
+      return () => { alive = false; clearInterval(timer); clearInterval(diskTimer); };
+    } });
+  }
+  function getJobs() { return adapter && typeof adapter.jobs === 'function' ? adapter.jobs() : []; }
+  function action(id, act) { if (adapter && typeof adapter.action === 'function') return adapter.action(id, act); }
+  function getFiles() { return adapter && typeof adapter.files === 'function' ? adapter.files() : Promise.resolve([]); }
+  function getPlaylists() { return adapter && typeof adapter.playlists === 'function' ? adapter.playlists() : []; }
+  function getSlots() { return adapter && typeof adapter.slots === 'function' ? adapter.slots() : 4; }
+  function snapshot() { return { jobs: getJobs(), slots: getSlots(), playlists: getPlaylists() }; }
+  const api = { configure, breakdown, bytes, getJobs, action, getFiles, getPlaylists, getSlots, snapshot }; if (typeof module !== 'undefined') module.exports = api; else root.Downloads = api;
+})(typeof window !== 'undefined' ? window : globalThis);

frontend/downloads.test.js

@@ -0,0 +1,17 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { breakdown, bytes } = require('./downloads.js');
+test('storage counts media once and shared playlist files within each playlist', () => {
+  const result = breakdown([{ id: 'a', size: 100, kind: 'video' }, { id: 'a', size: 20, kind: 'eq' }, { id: 'b', size: 30, kind: 'audio' }], [{ id: 'one', videos: [{ id: 'a' }, { id: 'a' }] }, { id: 'two', videos: [{ id: 'a' }, { id: 'b' }] }]);
+  assert.equal(result.total, 150); assert.deepEqual(result.kinds, { video: 100, audio: 30, eq: 20 }); assert.deepEqual(result.playlists.map(p => p.size), [120, 150]);
+});
+test('storage ignores invalid and negative sizes', () => { assert.equal(breakdown([{ id: 'a', size: -10 }, { id: 'b', size: 'bad' }], []).total, 0); assert.equal(bytes(1073741824), '1.0 GB'); });
+test('pausing a worker terminates it once and ignores later completion', async () => {
+  const vm = require('node:vm'), fs = require('node:fs'); let worker;
+  class Worker { constructor() { worker = this; this.terminated = 0; } postMessage() {} terminate() { this.terminated++; } }
+  const window = {};
+  vm.runInNewContext(fs.readFileSync(require.resolve('./opfs.js'), 'utf8'), { window, navigator: {}, Worker, URL, AbortController });
+  const controller = new AbortController(); const result = window.OPFS.downloadVideo('video', '/download', { signal: controller.signal });
+  controller.abort(); assert.equal((await result).paused, true); assert.equal(worker.terminated, 1);
+  worker.onmessage({ data: { type: 'done' } }); assert.equal(worker.terminated, 1);
+});

frontend/eq-core.js

@@ -0,0 +1,17 @@
+/* Shared live/offline EQ definitions and legacy curve migration. */
+(function(root) {
+  'use strict';
+  const { bands, presets, migrate, width } = typeof module !== 'undefined' ? require('./eq-parameters') : root.EqParameters;
+  function createWidener(context, source, value = 0) {
+    const splitter = context.createChannelSplitter(2), output = context.createChannelMerger(2), delay = context.createDelay(.05);
+    source.connect(splitter); splitter.connect(output, 0, 0); splitter.connect(delay, 1); delay.connect(output, 0, 1);
+    delay.delayTime.value = width(value) / 100 * .015;
+    return { output, set: next => delay.delayTime.setTargetAtTime(width(next) / 100 * .015, context.currentTime, .03) };
+  }
+  function register(adapter) { root.SettingsSections.register({ id: 'equalizer', title: 'Equalizer & stereo', cluster: 'Listening', summary: () => `${presets[adapter.settings().eq?.preset]?.name || 'Custom'} · ${width(adapter.settings().stereoWidth) ? 'Widened' : 'Original stereo'}`, render(container) {
+    const doc = container.ownerDocument, button = doc.createElement('button'); button.type = 'button'; button.className = 'settings-back'; button.textContent = 'Open ten-band equalizer'; button.onclick = adapter.open;
+    const label = doc.createElement('label'); label.className = 'set-row'; label.textContent = 'Headphone stereo widener (optional)'; const input = doc.createElement('input'); input.type = 'range'; input.min = '0'; input.max = '100'; input.value = String(width(adapter.settings().stereoWidth)); input.setAttribute('aria-label', 'Headphone stereo width'); const out = doc.createElement('output'); out.textContent = `${input.value}%`; input.oninput = () => { adapter.settings().stereoWidth = Number(input.value); out.textContent = `${input.value}%`; adapter.persist(); adapter.apply(); }; label.append(input, out);
+    const note = doc.createElement('p'); note.textContent = 'Off at 0%. Adds up to 15 ms delay to the right channel for headphones. May colour the sound on speakers or when summed to mono. On iPhone, saved songs use processed copies; streamed songs require Live sound processing.'; container.append(button,label,note);
+  } }); }
+  const api = { bands, presets, migrate, width, createWidener, register }; if (typeof module !== 'undefined') module.exports = api; else root.EqCore = api;
+})(typeof window !== 'undefined' ? window : globalThis);

frontend/eq-core.test.js

@@ -0,0 +1,4 @@
+const { test } = require('node:test'), assert = require('node:assert/strict'); const { bands, presets, migrate, width } = require('./eq-core');
+test('ten bands and every preset share one frequency definition', () => { assert.deepEqual(bands.map(b=>b.f), [31,62,125,250,500,1000,2000,4000,8000,16000]); for (const preset of Object.values(presets)) assert.equal(preset.g.length, 10); });
+test('legacy curves interpolate in log frequency and retain anchor values', () => { const result = migrate([6,2,-2,4,0]); assert.equal(result[0],6); assert.equal(result[3],2); assert.equal(result[5],-2); assert.equal(result[7],4); assert.equal(result[9],0); assert.ok(result[4] > -2 && result[4] < 2); assert.deepEqual(migrate([0,0,0,0,0]), presets.flat.g); });
+test('current curves are stable and clamp bad gains; widening defaults off', () => { assert.deepEqual(migrate(presets.acoustic.g), presets.acoustic.g); assert.equal(migrate([99,-99,NaN])[0],12); assert.equal(migrate([99,-99,NaN])[1],-12); assert.equal(width(undefined),0); assert.equal(width(500),100); });

frontend/eq-parameters.js

@@ -0,0 +1,25 @@
+/* Eager settings values; audio graphs remain in lazy feature groups. */
+(function(root) {
+  'use strict';
+  const frequencies = [31,62,125,250,500,1000,2000,4000,8000,16000];
+  const bands = frequencies.map((f,i) => ({ f, label: f >= 1000 ? `${f/1000}k` : String(f), type: i === 0 ? 'lowshelf' : i === 9 ? 'highshelf' : 'peaking' }));
+  const clamp = n => Math.max(-12, Math.min(12, Number(n) || 0));
+  function migrate(values) {
+    if (!Array.isArray(values)) return frequencies.map(() => 0);
+    if (values.length !== 5) return frequencies.map((_,i) => clamp(values[i]));
+    const old = [60,250,1000,4000,12000], curve = values.map(clamp);
+    return frequencies.map(f => { if (f <= old[0]) return curve[0]; if (f >= old[4]) return curve[4]; const i = old.findIndex(x => x >= f), weight = Math.log(f / old[i-1]) / Math.log(old[i] / old[i-1]); return Math.round((curve[i-1] * (1-weight) + curve[i] * weight) * 10) / 10; });
+  }
+  const presets = {
+    flat: { name: 'Flat', g: frequencies.map(() => 0) },
+    bass: { name: 'Bass boost', g: [5,7,5,3,1,0,0,0,0,0] },
+    vocal: { name: 'Vocal clarity', g: [-3,-4,-2,0,1,2,3,4,1,0] },
+    acoustic: { name: 'Acoustic live', g: [-2,-1,0,-2,-1,1,2,2,1,0] },
+    classical: { name: 'Classical', g: migrate([4,2,-1,1,3]) },
+    treble: { name: 'Treble boost', g: [0,0,0,0,0,0,1,3,5,6] },
+  };
+  const width = value => Math.max(0, Math.min(100, Number(value) || 0));
+  const amount = value => Math.max(0, Math.min(100, Number.isFinite(Number(value)) ? Number(value) : 100));
+  const api = { bands, presets, migrate, width, amount };
+  if (typeof module !== 'undefined') module.exports = api; else root.EqParameters = api;
+})(typeof window !== 'undefined' ? window : globalThis);

frontend/f7-layout.js

@@ -0,0 +1,244 @@
+/* Framework7 Swipe layout: the classic design with Framework7 swipe gestures.
+ * Cards become F7 swipeouts, swiping up on the mini bar opens an F7 "Up next"
+ * sheet, and the mini bar / screen edge take horizontal swipes. Framework7 is
+ * loaded only when this layout is first selected. */
+(function(root){
+ 'use strict';
+ const LAYOUT='f7-swipe',F7_SRC='vendor/framework7-swipe.min.js';
+
+ // Which swipe actions a card gets in a given view. Pure, so it is testable.
+ function cardActions(viewType,canDelete){
+  const left=[{act:'queue',label:'Queue'}];
+  const right=[{act:'playlist',label:'Playlist'}];
+  if(canDelete)right.push({act:'remove',label:'Remove',danger:true});
+  return {left,right};
+ }
+ // Classify a finished drag. Returns 'left'|'right'|'up'|'down'|null.
+ function swipeDirection(dx,dy,min){
+  min=min||48;const ax=Math.abs(dx),ay=Math.abs(dy);
+  if(Math.max(ax,ay)<min)return null;
+  if(ax>ay*1.4)return dx<0?'left':'right';
+  if(ay>ax*1.4)return dy<0?'up':'down';
+  return null;
+ }
+ function tabSwipeIndex(active,count,direction){
+  if(direction!=='left'&&direction!=='right'||count<1)return -1;
+  return Math.max(0,Math.min(count-1,active+(direction==='left'?1:-1)));
+ }
+
+ function mount(doc){
+  const html=doc.documentElement;let app=null,loading=null,active=false,sheet=null,cardsObserver=null;
+  const on=()=>html.dataset.layout===LAYOUT;
+  // app.js top-level `let` bindings are shared across classic scripts but are not on window.
+  /* global view, queue, queueIndex, queueSource */
+  const g=(name)=>{try{switch(name){case 'view':return view;case 'queue':return queue;case 'queueIndex':return queueIndex;case 'queueSource':return queueSource;}}catch(_){}return undefined;};
+
+  function loadF7(){
+   if(root.Framework7)return Promise.resolve(root.Framework7);
+   if(!loading)loading=new Promise((res,rej)=>{const s=doc.createElement('script');s.src=root.Lazy?.url('/vendor/framework7-swipe.min.js')||F7_SRC;s.onload=()=>res(root.Framework7);s.onerror=()=>{loading=null;rej(new Error('Framework7 failed to load'));};doc.head.append(s);});
+   return loading;
+  }
+  function ensureApp(){
+   return loadF7().then((F7)=>{
+    if(!app){
+     app=new F7({el:'body',theme:'ios',touch:{activeState:false,touchRipple:false,touchHighlight:false,tapHold:false},swipeout:{noFollow:false,removeElements:false},sheet:{backdrop:true,closeByBackdropClick:true}});
+     // F7's touch module swallows any click whose target isn't the touched element and
+     // cancels the click after a moved touch. app.js relies on programmatic .click()
+     // calls, and F7 can't be torn down, so drop those two app-wide handlers.
+     app.off('click');app.off('touchend');
+    }
+    return app;
+   });
+  }
+
+  // ---- Swipeout cards ----
+  // Framework7 only animates <a> children of the actions box, so these are links acting as buttons.
+  function actionBtn(a){const b=doc.createElement('a');b.setAttribute('role','button');b.tabIndex=0;b.className='swipeout-action f7s-act'+(a.danger?' f7s-danger':'');b.dataset.act=a.act;b.textContent=a.label;return b;}
+  function closeRow(li){
+   if(app){try{app.swipeout.close(li);return;}catch{}}
+   li.classList.remove('f7s-touch-open','swipeout-opened');li.querySelector('.swipeout-content')?.style.removeProperty('transform');
+   li.querySelectorAll('.swipeout-actions-opened').forEach(el=>el.classList.remove('swipeout-actions-opened'));
+   li.querySelectorAll('.f7s-act').forEach(el=>el.style.removeProperty('transform'));
+  }
+  function openRow(li,side){
+   const box=li.querySelector(`.swipeout-actions-${side}`);if(!box)return;
+   doc.querySelectorAll('li.f7s-row.f7s-touch-open').forEach(other=>{if(other!==li)closeRow(other);});
+   if(app){try{app.swipeout.open(li,side);if(li.classList.contains('swipeout-opened'))return;}catch{}}
+   const width=[...box.children].reduce((sum,el)=>sum+el.offsetWidth,0)+16;
+   li.classList.add('f7s-touch-open','swipeout-opened');box.classList.add('swipeout-actions-opened');
+   li.querySelector('.swipeout-content').style.transform=`translate3d(${side==='right'?-width:width}px,0,0)`;
+   box.querySelectorAll('.f7s-act').forEach(el=>el.style.transform='scale(1)');
+  }
+  function wrapCard(card){
+   if(!card.classList||!card.classList.contains('card')||card.closest('li.swipeout')||card.classList.contains('skeleton-card')||!card._video)return;
+   const li=doc.createElement('li');li.className='swipeout f7s-row';
+   card.replaceWith(li);card.classList.add('swipeout-content');li.append(card);
+   const acts=cardActions(g('view')?.type,!!card.querySelector('.card-del'));
+   for(const side of ['left','right']){
+    if(!acts[side].length)continue;
+    const box=doc.createElement('div');box.className='swipeout-actions-'+side;acts[side].forEach(a=>box.append(actionBtn(a)));li.append(box);
+   }
+  }
+  function unwrapAll(){
+   doc.querySelectorAll('li.f7s-row').forEach(li=>{const c=li.querySelector('.swipeout-content');if(c){c.classList.remove('swipeout-content');c.style.transform='';li.replaceWith(c);}else li.remove();});
+  }
+  function wrapAll(){doc.querySelectorAll('#cards .card').forEach(wrapCard);}
+  function onAction(e){
+   const btn=e.target.closest('.f7s-act');if(!btn)return;
+   const li=btn.closest('li.swipeout'),card=li&&li.querySelector('.card'),v=card&&card._video;
+   e.stopPropagation();closeRow(li);if(!v)return;
+   if(btn.dataset.act==='queue')root.addToQueue&&root.addToQueue(v);
+   else if(btn.dataset.act==='playlist')root.openCardMenu&&root.openCardMenu(v);
+   else if(btn.dataset.act==='remove'){const del=card.querySelector('.card-del');if(del)del.click();}
+  }
+
+  // ---- Up next sheet ----
+  function upcoming(){const q=g('queue')||[],i=g('queueIndex');return q.slice((typeof i==='number'?i:-1)+1);}
+  function renderSheet(){
+   const list=sheet.el.querySelector('.f7s-sheet-list'),items=upcoming();
+   list.innerHTML='';
+   if(!items.length){const p=doc.createElement('p');p.className='f7s-empty';p.textContent='Nothing queued after this song.';list.append(p);return;}
+   items.forEach((v,k)=>{
+    const li=doc.createElement('li');li.className='f7s-up';
+    li.innerHTML='<div class="f7s-up-info"><div class="f7s-up-title"></div><div class="f7s-up-ch"></div></div>';
+    if(v.thumbnail){const img=doc.createElement('img');img.alt='';img.loading='lazy';img.decoding='async';img.src=v.thumbnail;li.prepend(img);}
+    li.querySelector('.f7s-up-title').textContent=v.title||'';li.querySelector('.f7s-up-ch').textContent=v.channel||'';
+    li.addEventListener('click',()=>{const q=g('queue')||[],i=g('queueIndex');sheet.close();root.playFromList&&root.playFromList(q,(typeof i==='number'?i:-1)+1+k,g('queueSource'));});
+    list.append(li);
+   });
+  }
+  function openSheet(){
+   ensureApp().then((a)=>{
+    if(!sheet){
+     const el=doc.createElement('div');el.className='sheet-modal f7s-sheet';
+     el.innerHTML='<div class="sheet-modal-inner"><div class="f7s-grab" aria-hidden="true"></div><div class="f7s-sheet-head"><span>Up next</span></div><ul class="f7s-sheet-list"></ul></div>';
+     doc.body.append(el);
+     sheet=a.sheet.create({el,swipeToClose:true,breakpoints:[0.5],backdropBreakpoint:0.5,backdrop:true,closeByBackdropClick:true,swipeHandler:'.f7s-grab, .f7s-sheet-head'});
+    }
+    renderSheet();sheet.open();
+   }).catch(()=>{});
+  }
+  function closeSheet(){
+   const modal=sheet&&sheet.el&&sheet.el.f7Modal;if(!modal)return;
+   sheet.el.classList.remove('f7s-full');modal.setBreakpoint(0);
+   // F7 emits its initial `opened` transition after the sheet animation. If a
+   // very fast drag reaches the handle during that transition, repeat close
+   // after that event so its initial breakpoint cannot reopen the sheet.
+   setTimeout(()=>{if(modal.opened)modal.setBreakpoint(0);},360);
+  }
+
+  // ---- Mini bar + edge swipes (F7 has no component for these) ----
+  let drag=null,swallowClick=false;
+  function down(e){
+   if(!on()||e.pointerType==='touch'||e.pointerType==='mouse'&&e.button!==0)return;
+   const mini=e.target.closest&&e.target.closest('#miniBar');
+   const sidebarOpen=!!doc.querySelector('.app.sidebar-open');
+   const edge=!mini&&e.clientX<22&&!e.target.closest('.player-stage');
+   const inSidebar=sidebarOpen&&e.target.closest&&e.target.closest('#sidebar, #sidebarBackdrop');
+   const inRow=!!(e.target.closest&&e.target.closest('.f7s-row, .card, input, textarea, select, button, a, [role="slider"], #seek, #volume'));
+   const inPlayer=e.target.closest&&e.target.closest('#playerPane:not(.empty)');
+   const inBody=e.target.closest&&e.target.closest('.body');
+   if(!mini&&!edge&&!inSidebar&&(!inBody||inRow)&&!(inPlayer&&!inRow))return;
+   const kind=mini?'mini':edge?'edge':inSidebar?'sidebar':inPlayer?'player':'tabs';
+   drag={x:e.clientX,y:e.clientY,kind};
+  }
+  function up(e){
+   if(!drag)return;const d=drag;drag=null;
+   const dir=swipeDirection(e.clientX-d.x,e.clientY-d.y,d.kind==='mini'?36:56);if(!dir)return;
+   if(d.kind==='mini'){
+    swallowClick=true;setTimeout(()=>{swallowClick=false;},400);
+    if(dir==='left')root.playNext&&root.playNext();
+    else if(dir==='right')root.playPrev&&root.playPrev();
+    else if(dir==='up')openSheet();
+   }else if(d.kind==='sheet'){
+    if(dir==='up'&&sheet){sheet.el.f7Modal.setBreakpoint(1);sheet.el.classList.add('f7s-full');}
+    else if(dir==='down')closeSheet();
+   }else if(d.kind==='edge'&&dir==='right')root.openSidebar&&root.openSidebar();
+   else if(d.kind==='sidebar'&&dir==='left')root.closeSidebar&&root.closeSidebar();
+   else if(d.kind==='tabs'&&(dir==='left'||dir==='right')){
+    const tabs=[...doc.querySelectorAll('#bottomNav .bottom-nav-btn')].filter(b=>!b.disabled&&!b.hidden);
+    const active=Math.max(0,tabs.findIndex(b=>b.classList.contains('active'))),next=tabSwipeIndex(active,tabs.length,dir);
+    if(tabs[next]&&next!==active){swallowClick=true;setTimeout(()=>{swallowClick=false;},400);tabs[next].click();}
+   }else if(d.kind==='player'&&dir==='down'&&innerWidth<=860&&!doc.fullscreenElement&&!doc.querySelector('.orientation-fullscreen')){
+    const search=doc.querySelector('#bottomNav .bottom-nav-btn[data-view="search"]');if(search)search.click();
+   }
+  }
+  function click(e){if(swallowClick&&e.target.closest&&e.target.closest('#miniBar')){e.stopPropagation();e.preventDefault();swallowClick=false;}}
+  let touchDrag=null,rowDrag=null;
+  function touchDown(e){
+   if(!on()||!e.changedTouches.length)return;
+   const t=e.changedTouches[0],target=e.target,mini=target.closest&&target.closest('#miniBar');
+   if(target.closest&&target.closest('.f7s-grab, .f7s-sheet-head')){touchDrag={x:t.clientX,y:t.clientY,kind:'sheet'};rowDrag=null;return;}
+   const row=target.closest&&target.closest('li.f7s-row');
+   if(row){rowDrag={row,x:t.clientX,y:t.clientY};touchDrag=null;return;}
+   const sidebarOpen=!!doc.querySelector('.app.sidebar-open'),edge=!mini&&t.clientX<22&&!target.closest('.player-stage');
+   const inSidebar=sidebarOpen&&target.closest&&target.closest('#sidebar, #sidebarBackdrop');
+   const inRow=!!(target.closest&&target.closest('.f7s-row, .card, input, textarea, select, button, a, [role="slider"], #seek, #volume'));
+   const inPlayer=target.closest&&target.closest('#playerPane:not(.empty)'),inBody=target.closest&&target.closest('.body');
+   if(!mini&&!edge&&!inSidebar&&(!inBody||inRow)&&!(inPlayer&&!inRow))return;
+   touchDrag={x:t.clientX,y:t.clientY,kind:mini?'mini':edge?'edge':inSidebar?'sidebar':inPlayer?'player':'tabs'};
+  }
+  function finish(d,x,y){
+   if(!d)return;const dir=swipeDirection(x-d.x,y-d.y,d.kind==='mini'?36:56);if(!dir)return;
+   if(d.kind==='mini'){
+    swallowClick=true;setTimeout(()=>{swallowClick=false;},400);
+    if(dir==='left')root.playNext&&root.playNext();else if(dir==='right')root.playPrev&&root.playPrev();else if(dir==='up')openSheet();
+   }else if(d.kind==='sheet'){
+    if(dir==='up'&&sheet){sheet.el.f7Modal.setBreakpoint(1);sheet.el.classList.add('f7s-full');}
+    else if(dir==='down')closeSheet();
+   }else if(d.kind==='edge'&&dir==='right')root.openSidebar&&root.openSidebar();
+   else if(d.kind==='sidebar'&&dir==='left')root.closeSidebar&&root.closeSidebar();
+   else if(d.kind==='tabs'&&(dir==='left'||dir==='right')){
+    const tabs=[...doc.querySelectorAll('#bottomNav .bottom-nav-btn')].filter(b=>!b.disabled&&!b.hidden);
+    const active=Math.max(0,tabs.findIndex(b=>b.classList.contains('active'))),next=tabSwipeIndex(active,tabs.length,dir);
+    if(tabs[next]&&next!==active){swallowClick=true;setTimeout(()=>{swallowClick=false;},400);tabs[next].click();}
+   }else if(d.kind==='player'&&dir==='down'&&innerWidth<=860&&!doc.fullscreenElement&&!doc.querySelector('.orientation-fullscreen')){
+    const search=doc.querySelector('#bottomNav .bottom-nav-btn[data-view="search"]');if(search)search.click();
+   }
+  }
+  function touchUp(e){
+   if(!e.changedTouches.length)return;const t=e.changedTouches[0];
+   if(rowDrag){const d=rowDrag;rowDrag=null;const dx=t.clientX-d.x,dy=t.clientY-d.y;
+    if(Math.abs(dx)>Math.max(56,Math.abs(dy)*1.4)){
+     const card=d.row.querySelector('.card');
+     // A long swipe left removes once; F7's own overswipe is not relied on, so this is the only path.
+     if(dx< -170){const remove=card&&card.querySelector('.card-del');if(remove)remove.click();}
+     else if(dx<0)openRow(d.row,'right');
+     else if(d.row.querySelector('.swipeout-actions-left'))openRow(d.row,'left');
+     else {const v=card&&card._video;v&&root.addToQueue&&root.addToQueue(v);}
+    }
+    return;
+   }
+   if(!touchDrag)return;const d=touchDrag;touchDrag=null;finish(d,t.clientX,t.clientY);
+  }
+
+  function activate(){
+   active=true;
+   ensureApp().then(()=>{if(!active)return;wrapAll();}).catch(()=>{});
+   const cards=doc.getElementById('cards');
+   if(cards){cardsObserver=new root.MutationObserver(()=>{if(app)wrapAll();});cardsObserver.observe(cards,{childList:true});}
+   doc.addEventListener('click',onAction,true);
+  }
+  function deactivate(){
+   active=false;if(cardsObserver){cardsObserver.disconnect();cardsObserver=null;}
+   doc.removeEventListener('click',onAction,true);
+   if(sheet&&sheet.opened)sheet.close(false);
+   unwrapAll();
+  }
+  function sync(){if(on()&&!active)activate();else if(!on()&&active)deactivate();}
+  doc.addEventListener('pointerdown',down,{passive:true});
+  doc.addEventListener('pointerup',up,{passive:true});
+  doc.addEventListener('pointercancel',()=>{drag=null;},{passive:true});
+  doc.addEventListener('touchstart',touchDown,{passive:true,capture:true});
+  doc.addEventListener('touchend',touchUp,{passive:true,capture:true});
+  doc.addEventListener('touchcancel',()=>{touchDrag=null;rowDrag=null;},{passive:true,capture:true});
+  doc.addEventListener('click',click,true);
+  doc.addEventListener('click',e=>{if(e.target.classList?.contains('sheet-backdrop'))closeSheet();},true);
+  new root.MutationObserver(sync).observe(html,{attributes:true,attributeFilter:['data-layout']});
+  sync();
+ }
+
+ const api={cardActions,swipeDirection,tabSwipeIndex};
+ if(typeof module!=='undefined')module.exports=api;
+ else {root.F7Swipe=api; if(root.document.readyState==='loading')root.document.addEventListener('DOMContentLoaded',()=>mount(root.document),{once:true});else mount(root.document);}
+})(typeof window==='undefined'?globalThis:window);

frontend/f7-layout.test.js

@@ -0,0 +1,27 @@
+const test = require('node:test');
+const assert = require('node:assert');
+const { cardActions, swipeDirection, tabSwipeIndex } = require('./f7-layout');
+
+test('cardActions: every view gets Queue, removable rows get Playlist and Remove', () => {
+  assert.deepStrictEqual(cardActions('queue', true).left.map((a) => a.act), ['queue']);
+  assert.deepStrictEqual(cardActions('queue', true).right.map((a) => a.act), ['playlist', 'remove']);
+  assert.deepStrictEqual(cardActions('search', false).left.map((a) => a.act), ['queue']);
+  assert.deepStrictEqual(cardActions('search', false).right.map((a) => a.act), ['playlist']);
+});
+
+test('swipeDirection classifies clear swipes and ignores short or diagonal drags', () => {
+  assert.strictEqual(swipeDirection(-80, 5), 'left');
+  assert.strictEqual(swipeDirection(80, -10), 'right');
+  assert.strictEqual(swipeDirection(4, -70), 'up');
+  assert.strictEqual(swipeDirection(10, 20), null);
+  assert.strictEqual(swipeDirection(60, 60), null);
+  assert.strictEqual(swipeDirection(40, 0, 36), 'right');
+});
+
+test('tabSwipeIndex moves between bottom tabs and clamps at either end', () => {
+  assert.strictEqual(tabSwipeIndex(0, 5, 'left'), 1);
+  assert.strictEqual(tabSwipeIndex(3, 5, 'right'), 2);
+  assert.strictEqual(tabSwipeIndex(4, 5, 'left'), 4);
+  assert.strictEqual(tabSwipeIndex(0, 5, 'right'), 0);
+  assert.strictEqual(tabSwipeIndex(2, 5, 'up'), -1);
+});

frontend/feature-bootstrap.js

@@ -0,0 +1,77 @@
+/* Thin eager entries and configuration for optional, stateful feature modules. */
+(function(root) {
+  'use strict';
+  const Lazy = root.Lazy, doc = root.document;
+  if (!Lazy) return;
+  const specs = [
+    ['Piano','piano','configure','piano','Piano transcription','Live & worship','Off · load model on request'],
+    ['MidiPedals','midi','configure','midi','MIDI pedalboard','Live & worship','Off'],
+    ['PartyDJ','party-dj','register','party-dj','Watch party','Live & worship','Shared suggestions · host approval'],
+    ['LyricsWindow','lyrics-window','configure','floating-lyrics','Floating lyrics','Live & worship','Floating lyrics window'],
+    ['LowerThird','lower-third','register','broadcast','Presenter & broadcast','Live & worship','Projector · OBS lower third'],
+    ['EqCore','eq-core','register','equalizer','Equalizer & stereo','Listening','Flat · Original stereo'],
+    ['VocalReducer','vocal-reducer','register','vocal-reducer','Vocal reducer','Listening','100% · centre-panned vocals'],
+    ['SetlistImport','setlist-import','configure','setlist-import','Setlist import','Library & storage','Planning Center · SongSelect · ChordPro'],
+    ['CarMode','car-mode','configure','voice-car','Voice & Car mode','Listening','Voice search · Car mode'],
+    ['DirectMedia','direct','configure','direct-transfer','Direct device transfer','Library & storage','Paired devices only'],
+  ];
+  function button(id, text, anchor, name, action, className='np-btn') {
+    if (!anchor || doc.getElementById(id)) return;
+    const b=doc.createElement('button'); b.id=id; b.type='button'; b.className=className; b.textContent=text; b.setAttribute('aria-label',text);
+    if(id==='carModeBtn')b.innerHTML='<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" aria-hidden="true"><path d="m5 8 2-5h10l2 5M3 8h18v10H3zM5 18v3m14-3v3M6 12h2m8 0h2"/></svg>';
+    if(id==='voiceSearchBtn')b.innerHTML='<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" aria-hidden="true"><rect x="9" y="2" width="6" height="12" rx="3"/><path d="M5 10v2a7 7 0 0 0 14 0v-2M12 19v3m-4 0h8"/></svg>';
+    if(id.startsWith('floating-')){b.title='Open floating lyrics';b.setAttribute('aria-label','Open floating lyrics window');}
+    b.title ||= text;
+    b.onclick=()=>Lazy.load(name).then(action).catch(error=>root.dispatchEvent(new CustomEvent('ytp-lazy-error',{detail:{error}})));
+    anchor.after(b); Lazy.intent(b,name);
+  }
+  for (const [globalName, suffix, setup, id, title, cluster, summary] of specs) {
+    const group='feature:'+suffix;
+    const facade=Lazy.proxy(group,['open','close','obtain','publish','attach','handle','offer','paint','fade'],globalName);
+    let configured=false;
+    facade[setup]=options=>{
+      if (configured) return; configured=true;
+      Lazy.onLoad(group,()=>root[globalName][setup](options));
+      root.SettingsSections.register({id,title,cluster,lazyGroup:group,summary:()=>{
+          const s=options?.settings?.() || {};
+          if(globalName==='Piano')return s.pianoEnabled?'On · browser or optional worker':'Off · load model on request';
+          if(globalName==='MidiPedals')return s.midiEnabled?'On · pedal mappings':'Off';
+          if(globalName==='EqCore')return `${root.EqParameters.presets[s.eq?.preset]?.name || 'Custom'} · ${root.EqParameters.width(s.stereoWidth)?'Widened':'Original stereo'}`;
+          if(globalName==='VocalReducer')return `${root.EqParameters.amount(s.vocalLevel ?? 100)}% · centre-panned vocals`;
+          if(globalName==='DirectMedia')return facade.enabled()?'On · paired devices only':'Off or unsupported';
+          if(globalName==='CarMode')return root.SpeechRecognition||root.webkitSpeechRecognition?'Voice search available · Car mode':'Car mode · voice unavailable';
+          if(globalName==='LyricsWindow')return root.documentPictureInPicture?.requestWindow?'Interactive window available':root.HTMLCanvasElement?.prototype.captureStream&&doc.pictureInPictureEnabled?'Lyric video PiP available':'Not supported on this browser';
+          return summary;
+        },
+        render(container,context) {
+          let disposed=false, cleanup;
+          container.textContent='Loading…';
+          Lazy.load(group).then(()=>{
+            if (disposed || !container.isConnected) return;
+            container.replaceChildren(); cleanup=root.SettingsSections.get(id).render(container,context);
+          }).catch(error=>{if(!disposed)container.textContent=error.message;});
+          return ()=>{disposed=true; if(typeof cleanup==='function')cleanup();};
+        },
+      });
+      if (globalName==='CarMode') {
+        button('carModeBtn','Car mode',doc.getElementById('searchForm'),group,()=>root.CarMode.open(),'icon-btn');
+        if(root.SpeechRecognition||root.webkitSpeechRecognition)button('voiceSearchBtn','Voice search',options.input,group,()=>doc.getElementById('voiceSearchBtn').click(),'icon-btn voice-search');
+      }
+      if (globalName==='LyricsWindow' && (root.documentPictureInPicture?.requestWindow || (root.HTMLCanvasElement?.prototype.captureStream && doc.pictureInPictureEnabled))) {
+        for(const anchor of ['stageLyricsAuto','serviceAutoscrollBtn','pipBtn'])button('floating-'+anchor,'⧉ Lyrics',doc.getElementById(anchor),group,()=>doc.getElementById('floating-'+anchor).click());
+      }
+    };
+    if(globalName==='LowerThird') {
+      facade.active=()=>new URLSearchParams(root.location.search).get('overlay')==='lowerthird';
+      facade.url=(origin,code)=>{const u=new URL('/',origin);u.searchParams.set('overlay','lowerthird');u.searchParams.set('code',String(code));return u.href;};
+    }
+    if(globalName==='DirectMedia') {
+      let settings=()=>({}); const configure=facade.configure;
+      facade.configure=options=>{settings=options.settings;configure(options);};
+      facade.enabled=()=>settings().directTransfer!==false && !!root.RTCPeerConnection;
+      facade.hasSource=()=>false;
+    }
+    if(globalName==='LyricsWindow')facade.element=()=>null;
+    root[globalName]=facade;
+  }
+})(typeof window !== 'undefined' ? window : globalThis);

frontend/fonts/PlusJakartaSans-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The Plus Jakarta Sans Project Authors (https://github.com/tokotype/PlusJakartaSans)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

frontend/fullscreen-orientation.css

@@ -0,0 +1,75 @@
+/* Shared fullscreen surface; inline player styling is unchanged. */
+.orientation-fullscreen .fullscreen-hud[hidden] { display: none; }
+.orientation-fullscreen .fullscreen-hud {
+  --hud-ink: var(--text, #fff);
+  position: absolute; z-index: 20; right: max(12px, env(safe-area-inset-right));
+  bottom: max(8px, env(safe-area-inset-bottom)); left: max(12px, env(safe-area-inset-left));
+  display: flex; flex-direction: column; align-items: stretch; gap: 2px; padding: 4px 2px 2px;
+  color: #fff; background: linear-gradient(to bottom, transparent, rgb(0 0 0 / .45));
+  opacity: 1; transition: opacity .22s ease;
+}
+.fullscreen-top { display: flex; align-items: center; justify-content: space-between; min-height: 38px; }
+.fullscreen-top .fullscreen-title { min-width: 0; max-width: calc(100% - 52px); overflow: hidden; white-space: nowrap; text-overflow: ellipsis; font-size: 13px; font-weight: 500; color: #fff; text-shadow: 0 1px 5px #000; }
+.fullscreen-controls { display: flex; align-items: center; gap: 6px; }
+.fullscreen-top button { width: 38px; min-width: 38px; height: 38px; min-height: 38px; }
+.orientation-fullscreen .fullscreen-hud.hud-hidden { opacity: 0; pointer-events: none; }
+.fullscreen-hud button {
+  display: grid; place-items: center; flex: none;
+  width: 44px; min-width: 44px; height: 44px; min-height: 44px; padding: 0;
+  border: 0; border-radius: 50%; background: transparent;
+  color: var(--hud-ink, #fff); font: inherit; cursor: pointer;
+  filter: drop-shadow(0 1px 3px rgb(0 0 0 / .8));
+  -webkit-tap-highlight-color: transparent;
+}
+.fullscreen-hud button:hover { background: rgb(255 255 255 / .12); }
+.fullscreen-hud button:active { transform: scale(.94); }
+.fullscreen-hud button svg { width: 20px; height: 20px; fill: none; stroke: currentColor; stroke-width: 1.8; stroke-linecap: round; stroke-linejoin: round; }
+.fullscreen-hud button .fill { fill: currentColor; stroke: none; }
+.fullscreen-hud button:focus-visible { outline: 2px solid var(--accent, #fff); outline-offset: 2px; }
+.fullscreen-hud input { min-width: 40px; min-height: 18px; height: 18px; flex: 1; margin: 0 4px; accent-color: var(--accent, #fff); touch-action: none; appearance: none; background: transparent; }
+.fullscreen-hud input::-webkit-slider-runnable-track { height: 3px; border-radius: 2px; background: linear-gradient(to right, var(--accent, #fff) 0 var(--seek-progress, 0%), rgb(255 255 255 / .55) var(--seek-progress, 0%) 100%); }
+.fullscreen-hud input::-webkit-slider-thumb { appearance: none; width: 9px; height: 9px; margin-top: -3px; border-radius: 50%; background: #fff; box-shadow: 0 1px 4px #000; }
+.fullscreen-hud input:active::-webkit-slider-runnable-track { height: 5px; }
+.fullscreen-hud input::-moz-range-track { height: 3px; border-radius: 2px; background: rgb(255 255 255 / .55); }
+.fullscreen-hud input::-moz-range-progress { height: 3px; background: var(--accent, #fff); }
+.fullscreen-hud input::-moz-range-thumb { width: 9px; height: 9px; border: 0; border-radius: 50%; background: #fff; }
+.player-stage.orientation-fullscreen { background: #000; }
+.player-stage.orientation-overlay {
+  position: fixed !important; z-index: 10000 !important; inset: 0 !important;
+  width: 100dvw !important; height: 100dvh !important;
+  min-width: 0 !important; min-height: 0 !important;
+  max-width: none !important; max-height: none !important;
+  aspect-ratio: auto !important; margin: 0 !important; padding: 0 !important;
+  border: 0 !important; border-radius: 0 !important; box-shadow: none !important;
+}
+.player-stage.orientation-overlay[data-fullscreen-rotation="90"],
+.player-stage.orientation-overlay[data-fullscreen-rotation="-90"] {
+  inset: auto !important; left: 50% !important; top: 50% !important;
+  width: 100dvh !important; height: 100dvw !important;
+  transform: translate(-50%, -50%) rotate(90deg) !important;
+}
+.player-stage.orientation-overlay[data-fullscreen-rotation="-90"] { transform: translate(-50%, -50%) rotate(-90deg) !important; }
+.orientation-fullscreen video {
+  flex: none !important; width: 100% !important; height: 100% !important;
+  max-width: none !important; max-height: none !important; object-fit: cover;
+}
+.orientation-fullscreen[data-fullscreen-fit="fit"] video { object-fit: contain; }
+.orientation-fullscreen[data-fullscreen-fit="fill"] video { object-fit: cover; }
+.orientation-fullscreen #stgOverlay { display: none !important; }
+.orientation-overlay[data-fullscreen-rotation="90"] .fullscreen-hud {
+  bottom: max(12px, env(safe-area-inset-left)); left: max(12px, env(safe-area-inset-top)); right: max(12px, env(safe-area-inset-bottom));
+}
+.orientation-overlay[data-fullscreen-rotation="-90"] .fullscreen-hud {
+  bottom: max(12px, env(safe-area-inset-right)); left: max(12px, env(safe-area-inset-bottom)); right: max(12px, env(safe-area-inset-top));
+}
+@media (max-width: 460px) {
+  .orientation-fullscreen .fullscreen-hud { gap: 2px; padding: 4px 2px 2px; }
+  .fullscreen-hud button { width: 44px; min-width: 44px; height: 44px; min-height: 44px; }
+}
+/* Raise existing ancestry instead of moving a playing video in WebKit. */
+body.landscape-fs .orientation-ancestor { z-index: 10001 !important; transform: none !important; filter: none !important; overflow: visible !important; }
+body.landscape-fs { overflow: hidden; }
+/* While the app's own fullscreen is up, nothing of the app may show around or over it. */
+body.landscape-fs .orientation-ancestor { -webkit-backdrop-filter: none !important; backdrop-filter: none !important; contain: none !important; will-change: auto !important; perspective: none !important; clip-path: none !important; isolation: auto !important; }
+body.landscape-fs :is(.topbar, #bottomNav, #miniBar, #sectionRail, #toastContainer, .sheet-backdrop, .f7s-sheet) { visibility: hidden !important; }
+body.landscape-fs > .player-stage.orientation-overlay { z-index: 2147483000 !important; }

frontend/fullscreen-orientation.js

@@ -0,0 +1,124 @@
+(function (root) {
+  'use strict';
+  const choices = ['auto', 'landscape', 'portrait'];
+  const normalize = value => choices.includes(value) ? value : 'auto';
+  function rotation(value, width, height) {
+    value = normalize(value);
+    return value === 'landscape' && width < height ? 90 : value === 'portrait' && width > height ? -90 : 0;
+  }
+  function coordinates(x, y, rect, angle = 0) {
+    if (angle === 90) return { x: y - rect.top, y: rect.right - x, width: rect.height, height: rect.width };
+    if (angle === -90) return { x: rect.bottom - y, y: x - rect.left, width: rect.height, height: rect.width };
+    return { x: x - rect.left, y: y - rect.top, width: rect.width, height: rect.height };
+  }
+  function normalizeFit(value) { return value === 'fit' ? 'fit' : 'fill'; }
+  function create(options) {
+    const { stage, settings, persist, toggle, seek, state } = options;
+    let active = false, custom = false, native = false, locked = false, angle = 0, timer, hideTimer;
+    const ancestors = [];
+    for (let el = stage.parentElement; el && el !== document.body; el = el.parentElement) ancestors.push(el);
+    // iOS (no element fullscreen) draws its own fixed overlay. Any ancestor with a filter,
+    // backdrop-filter, containment or clipping traps a fixed child, which showed the app
+    // around the video on iPhone. Lift the stage to <body> for the overlay and put it back after.
+    let home = null;
+    function lift() { if (home || stage.parentElement === document.body) return; home = { parent: stage.parentElement, next: stage.nextSibling }; document.body.append(stage); }
+    function unlift() { if (!home) return; const { parent, next } = home; home = null; if (next && next.parentNode === parent) parent.insertBefore(stage, next); else parent.append(stage); }
+    const hud = document.createElement('div'); hud.className = 'fullscreen-hud'; hud.hidden = true;
+    hud.innerHTML = '<div class="fullscreen-top"><div class="fullscreen-title" aria-live="polite"></div><button type="button" aria-label="Exit fullscreen" title="Exit fullscreen"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M9 4H4v5m0-5 6 6m5 9h5v-5m0 5-6-6"/></svg></button></div><div class="fullscreen-controls"><button type="button" aria-label="Play or pause" title="Play or pause"><svg class="fill" viewBox="0 0 24 24" aria-hidden="true"><path d="M8 5v14l11-7z"/></svg></button><input type="range" min="0" max="1000" value="0" aria-label="Seek video"><button type="button" class="fullscreen-orientation" aria-label="Change fullscreen orientation" title="Change fullscreen orientation"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M4 8V4h4M20 16v4h-4M4 4l6 6m4 4 6 6M20 8V4h-4M4 16v4h4M20 4l-6 6m-4 4-6 6"/></svg></button><button type="button" class="fullscreen-fit" aria-label="Change video fit" title="Change video fit"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M4 7V4h3M17 4h3v3M20 17v3h-3M7 20H4v-3M7 9h10v6H7z"/></svg></button></div>';
+    stage.append(hud);
+    const play = hud.querySelector('button[aria-label="Play or pause"]'), orientation = hud.querySelector('.fullscreen-orientation'), fitButton = hud.querySelector('.fullscreen-fit'), exit = hud.querySelector('button[aria-label="Exit fullscreen"]'), range = hud.querySelector('input');
+    const title = hud.querySelector('.fullscreen-title');
+    function setFit(value) {
+      const fit = normalizeFit(value); settings().fullscreenFit = fit; persist();
+      stage.dataset.fullscreenFit = fit;
+      fitButton.setAttribute('aria-label', `Video fill mode: ${fit === 'fill' ? 'Fill' : 'Fit'}`);
+      fitButton.title = `${fit === 'fill' ? 'Fill' : 'Fit'} video frame`;
+    }
+    function revealControls() {
+      if (!active) return;
+      hud.classList.remove('hud-hidden'); clearTimeout(hideTimer);
+      hideTimer = setTimeout(() => {
+        if (!hud.contains(document.activeElement)) hud.classList.add('hud-hidden');
+      }, 3200);
+    }
+    stage.addEventListener('pointerdown', revealControls, { passive: true });
+    stage.addEventListener('pointermove', event => { if (event.pointerType === 'mouse') revealControls(); }, { passive: true });
+    hud.addEventListener('focusin', () => { clearTimeout(hideTimer); hud.classList.remove('hud-hidden'); });
+    hud.addEventListener('focusout', () => setTimeout(revealControls, 0));
+    hud.addEventListener('click', revealControls);
+    play.onclick = toggle; exit.onclick = leave;
+    fitButton.onclick = () => setFit(settings().fullscreenFit === 'fill' ? 'fit' : 'fill');
+    // Fit/Fill is only the HUD button: a centre double-tap is play/pause and two fingers pinch-zoom (app.js Gestures).
+    function layout() {
+      if (!active) return;
+      angle = custom ? rotation(settings().fullscreenOrientation, innerWidth, innerHeight) : 0;
+      stage.dataset.fullscreenRotation = String(angle);
+      title.textContent = state().title || '';
+      orientation.setAttribute('aria-label', `Change fullscreen orientation (currently ${normalize(settings().fullscreenOrientation)})`);
+      orientation.title = `Orientation: ${normalize(settings().fullscreenOrientation)}`;
+    }
+    async function orient() {
+      if (locked) { screen.orientation?.unlock?.(); locked = false; }
+      const value = normalize(settings().fullscreenOrientation);
+      if (!custom && value !== 'auto') {
+        try { await screen.orientation.lock(value); locked = true; if (!active) { screen.orientation.unlock(); locked = false; return; } }
+        catch { if (!active) return; custom = true; lift(); stage.classList.add('orientation-overlay'); }
+      }
+      layout();
+    }
+    orientation.onclick = () => { settings().fullscreenOrientation = choices[(choices.indexOf(normalize(settings().fullscreenOrientation)) + 1) % choices.length]; persist(); orient(); };
+    range.oninput = () => seek(Number(range.value) / 1000 * (state().duration || 0));
+    // Explicit inverse coordinates also work for rotated range controls on WebKit.
+    const rangeSeek = event => {
+      const point = coordinates(event.clientX, event.clientY, range.getBoundingClientRect(), angle);
+      seek(Math.max(0, Math.min(1, point.x / point.width)) * (state().duration || 0));
+    };
+    range.onpointerdown = event => { event.preventDefault(); range.setPointerCapture(event.pointerId); rangeSeek(event); };
+    range.onpointermove = event => { if (range.hasPointerCapture(event.pointerId)) rangeSeek(event); };
+    hud.addEventListener('pointerdown', event => event.stopPropagation());
+    hud.addEventListener('pointerup', event => event.stopPropagation());
+    function cleanup() {
+      active = false; custom = false; native = false; angle = 0; clearInterval(timer); clearTimeout(hideTimer);
+      ancestors.forEach(el => el.classList.remove('orientation-ancestor'));
+      hud.hidden = true; hud.classList.remove('hud-hidden'); stage.classList.remove('orientation-overlay', 'orientation-fullscreen');
+      delete stage.dataset.fullscreenRotation; document.body.classList.remove('landscape-fs');
+      delete stage.dataset.fullscreenFit;
+      unlift();
+      if (locked) { screen.orientation?.unlock?.(); locked = false; }
+    }
+    function leave() {
+      if (document.fullscreenElement === stage) document.exitFullscreen().catch(() => {});
+      cleanup();
+    }
+    async function enter() {
+      if (active) { leave(); return; }
+      active = true; ancestors.forEach(el => el.classList.add('orientation-ancestor')); stage.classList.add('orientation-fullscreen'); hud.hidden = false; revealControls();
+      setFit(normalizeFit(settings().fullscreenFit));
+      document.body.classList.add('landscape-fs');
+      try {
+        if (!stage.requestFullscreen) throw new Error('Custom fullscreen');
+        await stage.requestFullscreen();
+        native = true;
+      } catch { custom = true; lift(); stage.classList.add('orientation-overlay'); }
+      if (!active) return;
+      await orient();
+      if (!active) return;
+      timer = setInterval(() => {
+        const s = state();
+        range.value = String(s.duration ? s.time / s.duration * 1000 : 0);
+        range.style.setProperty('--seek-progress', `${s.duration ? Math.min(100, s.time / s.duration * 100) : 0}%`);
+        play.setAttribute('aria-label', s.paused ? 'Play video' : 'Pause video');
+        play.title = s.paused ? 'Play' : 'Pause';
+        play.innerHTML = s.paused
+          ? '<svg class="fill" viewBox="0 0 24 24" aria-hidden="true"><path d="M8 5v14l11-7z"/></svg>'
+          : '<svg class="fill" viewBox="0 0 24 24" aria-hidden="true"><path d="M6 5h4v14H6zm8 0h4v14h-4z"/></svg>';
+      }, 250);
+    }
+    document.addEventListener('fullscreenchange', () => { if (active && !document.fullscreenElement && native) cleanup(); });
+    document.addEventListener('keydown', event => { if (active && event.key === 'Escape') leave(); });
+    window.addEventListener('resize', layout);
+    return { enter, leave, point: event => coordinates(event.clientX, event.clientY, stage.getBoundingClientRect(), angle) };
+  }
+  const api = { normalize, normalizeFit, rotation, coordinates, create };
+  if (typeof module !== 'undefined' && module.exports) module.exports = api; else root.FullscreenOrientation = api;
+})(globalThis);

frontend/fullscreen-orientation.test.js

@@ -0,0 +1,22 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { normalize, normalizeFit, rotation, coordinates } = require('./fullscreen-orientation');
+test('fullscreen fit defaults safely to fill and accepts fit', () => {
+  assert.equal(normalizeFit(undefined), 'fill');
+  assert.equal(normalizeFit('fit'), 'fit');
+  assert.equal(normalizeFit('unexpected'), 'fill');
+});
+test('orientation defaults and only rotates mismatched viewports', () => {
+  assert.equal(normalize('invalid'), 'auto');
+  assert.equal(rotation('auto', 390, 844), 0);
+  assert.equal(rotation('landscape', 390, 844), 90);
+  assert.equal(rotation('landscape', 844, 390), 0);
+  assert.equal(rotation('portrait', 844, 390), -90);
+});
+test('rotated touch coordinates preserve local seek and swipe axes', () => {
+  const rect = { left: 10, top: 20, right: 400, bottom: 864, width: 390, height: 844 };
+  assert.deepEqual(coordinates(400, 20, rect, 90), { x: 0, y: 0, width: 844, height: 390 });
+  assert.deepEqual(coordinates(10, 864, rect, 90), { x: 844, y: 390, width: 844, height: 390 });
+  assert.deepEqual(coordinates(10, 864, rect, -90), { x: 0, y: 0, width: 844, height: 390 });
+  assert.deepEqual(coordinates(205, 442, rect), { x: 195, y: 422, width: 390, height: 844 });
+});

frontend/glass-controls.js

@@ -0,0 +1,96 @@
+/* Draw legacy control glyphs in Glass and Bento; restore them on theme changes. */
+(function(root) {
+  'use strict';
+  const paths = {
+    trash:'<path d="M3 6h18M9 6V3h6v3M5 6l1 15h12l1-15M10 10v7M14 10v7"/>',
+    music:'<path d="M9 18V5l11-2v13M9 8l11-2"/><ellipse cx="6" cy="18" rx="3" ry="2"/><ellipse cx="17" cy="16" rx="3" ry="2"/>',
+    add:'<path d="M12 5v14M5 12h14"/>', close:'<path d="m6 6 12 12M18 6 6 18"/>',
+    search:'<circle cx="10.5" cy="10.5" r="6.5"/><path d="m16 16 5 5"/>',
+    save:'<path d="M12 3v12m-5-5 5 5 5-5M4 17v4h16v-4"/>',
+    play:'<path d="m8 5 11 7-11 7z"/>', pause:'<path d="M8 5v14M16 5v14"/>',
+    next:'<path d="m5 5 10 7-10 7zM19 5v14"/>', previous:'<path d="m19 5-10 7 10 7zM5 5v14"/>',
+    repeat:'<path d="m17 2 4 4-4 4M3 11V8a2 2 0 0 1 2-2h16M7 22l-4-4 4-4m14-1v3a2 2 0 0 1-2 2H3"/>',
+    edit:'<path d="m14 5 5 5M4 20l5-1L21 7l-4-4L5 15z"/>',
+    lyrics:'<rect x="9" y="3" width="6" height="11" rx="3"/><path d="M5 10v2a7 7 0 0 0 14 0v-2M12 19v3M8 22h8"/>',
+    share:'<path d="M12 16V3m-4 4 4-4 4 4M5 12v9h14v-9"/>',
+    copy:'<rect x="8" y="8" width="12" height="13" rx="2"/><path d="M16 8V3H3v13h5"/>',
+    check:'<path d="m5 12 4 4L19 6"/>', folder:'<path d="M3 7V5h7l2 3h9v12H3z"/>',
+    settings:'<path d="M4 6h16M4 12h16M4 18h16"/><circle cx="8" cy="6" r="2"/><circle cx="16" cy="12" r="2"/><circle cx="10" cy="18" r="2"/>',
+    chapters:'<rect x="4" y="3" width="16" height="18" rx="2"/><path d="M8 7h8M8 12h8M8 17h5"/>',
+    clock:'<circle cx="12" cy="12" r="9"/><path d="M12 7v5l3 2"/>',
+    shuffle:'<path d="m18 3 3 3-3 3M3 6h3c5 0 7 12 12 12h3m-3-3 3 3-3 3M3 18h3c2 0 4-3 6-6s4-6 6-6h3"/>',
+    down:'<path d="m6 9 6 6 6-6"/>', right:'<path d="m9 6 6 6-6 6"/>', back:'<path d="M20 12H4m6-6-6 6 6 6"/>', more:'<circle cx="5" cy="12" r="1"/><circle cx="12" cy="12" r="1"/><circle cx="19" cy="12" r="1"/>',
+    television:'<rect x="3" y="4" width="18" height="13" rx="2"/><path d="M8 21h8m-4-4v4"/>', pin:'<path d="M9 3h6l-1 6 4 4H6l4-4zM12 13v8"/>',
+    devices:'<rect x="3" y="4" width="14" height="12" rx="2"/><path d="M7 20h6M10 16v4"/><rect x="17" y="10" width="5" height="11" rx="1"/>'
+  };
+  const glyphs = {'＋':'add','✕':'close','×':'close','✖':'close','🔍':'search','🔎':'search','⬇':'save','⤓':'save','💾':'save','▶':'play','⏸':'pause','⏭':'next','⏮':'previous','↻':'repeat','↺':'repeat','✎':'edit','✏':'edit','📝':'edit','🎤':'lyrics','↗':'share','⧉':'copy','✓':'check','📁':'folder','⚙':'settings','📋':'chapters','🕘':'clock','🔀':'shuffle','📡':'devices','▾':'down','▸':'right','←':'back','⋯':'more','⋮':'more','🗑':'trash','🎵':'music'};
+  function leadingGlyph(text,bento=false) {
+    const mapping=bento?{...glyphs,'📺':'television','⏱':'clock','⇅':'settings','📌':'pin','🎧':'music','📚':'folder'}:glyphs;
+    const prefix = text.match(/^\s*/)[0], rest = text.slice(prefix.length);
+    const glyph = Object.keys(mapping).find(key => rest.startsWith(key));
+    if (!glyph) return null;
+    const length = glyph.length + (rest[glyph.length] === '\uFE0F' ? 1 : 0);
+    return { kind:mapping[glyph], original:prefix+rest.slice(0,length), rest:rest.slice(length) };
+  }
+  function mount(doc) {
+    const decorations = new Set(), tabLabels = new Map(); let scheduled=false;
+    const selector = '#listPane button, .sidebar button, .smart-item .pl-name, .notes-tab, .notes-fold, .mini-btn, .sidebar .playlist-item:not(.smart-item), .pl-offline-badge.all, .home-pl-offline.all, .home-pl-play, .home-pl-thumb-fallback';
+    const svg = kind => { const icon=doc.createElementNS('http://www.w3.org/2000/svg','svg'); icon.setAttribute('viewBox','0 0 24 24');icon.setAttribute('aria-hidden','true');icon.classList.add('glass-control-icon');icon.innerHTML=paths[kind];return icon; };
+    const observer=new root.MutationObserver(schedule), themeObserver=new root.MutationObserver(schedule);
+    function restore(record) {
+      record.svg.remove(); if(record.original.isConnected)record.original.replaceWith(doc.createTextNode(record.original.textContent));
+      if(record.addedLabel && record.parent.isConnected)record.parent.removeAttribute('aria-label');
+    }
+    function restoreTab(parent, record) {
+      for(const label of record.labels)if(label.isConnected)label.replaceWith(doc.createTextNode(label.textContent));
+      for(const [name,value] of Object.entries(record.attributes)) { if(value===null)parent.removeAttribute(name);else parent.setAttribute(name,value); }
+    }
+    function paint() {
+      scheduled=false;observer.disconnect();
+      const bento=doc.documentElement.dataset.layout==='bento-hub';
+      const active=bento || doc.documentElement.dataset.layout==='glass-stage';
+      for(const [parent,record] of tabLabels)if(!active || !parent.isConnected){restoreTab(parent,record);tabLabels.delete(parent);}
+      for(const record of decorations)if(!active || !record.svg.isConnected){restore(record);decorations.delete(record);}
+      if(active) for(const parent of doc.querySelectorAll(selector+(bento?', .service-btn, .np-btn, .ctrl, .empty-icon, .dl-saved-cta, .brand-mark, .upnext-head button, .ph-logo, .saved-badge':''))) {
+        // Existing SVGs already express the action; only legacy glyphs change.
+        if(parent.querySelector('svg:not(.glass-control-icon),.legacy-nav-icon'))continue;
+        for(const node of [...parent.childNodes]) {
+          if(node.nodeType!==3)continue;const match=leadingGlyph(node.textContent,bento);if(!match)continue;
+          const icon=svg(match.kind);
+          if(parent.matches('.pl-offline-badge,.home-pl-offline')) { icon.removeAttribute('aria-hidden'); icon.setAttribute('role','img'); icon.setAttribute('aria-label',parent.title || 'Available offline'); }
+          const original=doc.createElement('span'); original.className='glass-original-glyph';original.textContent=match.original;
+          node.textContent=match.rest;parent.insertBefore(icon,node);parent.insertBefore(original,node);
+          const addedLabel=parent.tagName==='BUTTON'&&!parent.hasAttribute('aria-label')&&!parent.textContent.replace(match.original,'').trim();
+          if(addedLabel)parent.setAttribute('aria-label',parent.title || ({play:'Play',pause:'Pause',close:'Close',add:'Add',save:'Save'}[match.kind] || match.kind));
+          decorations.add({parent,svg:icon,original,addedLabel});break;
+        }
+        if(parent.matches('.sidebar .playlist-item:not(.smart-item)')&&!parent.querySelector('svg')) {
+          const icon=svg('folder'); parent.prepend(icon);
+          decorations.add({parent,svg:icon,original:doc.createElement('span'),addedLabel:false});
+        }
+        if(parent.matches('.notes-tab')&&!parent.querySelector('svg')&&paths[parent.dataset.tab==='markers'?'chapters':parent.dataset.tab]) {
+          const kind=parent.dataset.tab==='markers'?'chapters':parent.dataset.tab,icon=svg(kind);parent.prepend(icon);
+          const original=doc.createElement('span');decorations.add({parent,svg:icon,original,addedLabel:false});
+        }
+      }
+      if(active)for(const parent of doc.querySelectorAll('.notes-tab')) {
+        if(tabLabels.has(parent))continue;
+        const record={labels:[],attributes:{'aria-label':parent.getAttribute('aria-label'),title:parent.getAttribute('title')}};
+        const name=parent.dataset.tab==='markers'?'Chapters & bookmarks':parent.dataset.tab==='lyrics'?'Lyrics':'Search';
+        if(!parent.hasAttribute('aria-label'))parent.setAttribute('aria-label',name);
+        if(!parent.hasAttribute('title'))parent.setAttribute('title',name);
+        for(const node of [...parent.childNodes])if(node.nodeType===3 && node.textContent.trim()) {
+          const label=doc.createElement('span');label.className='glass-tab-label';node.replaceWith(label);label.append(node);record.labels.push(label);
+        }
+        tabLabels.set(parent,record);
+      }
+      if(active)observer.observe(doc.body,{childList:true,subtree:true,characterData:true});
+    }
+    function schedule(){if(!scheduled){scheduled=true;root.queueMicrotask(paint);}}
+    themeObserver.observe(doc.documentElement,{attributes:true,attributeFilter:['data-layout']});paint();
+    return ()=>{observer.disconnect();themeObserver.disconnect();for(const record of decorations)restore(record);for(const [parent,record] of tabLabels)restoreTab(parent,record);};
+  }
+  if(typeof module!=='undefined')module.exports={leadingGlyph,paths};
+  else if(root.document.readyState==='loading')root.document.addEventListener('DOMContentLoaded',()=>mount(root.document),{once:true});
+  else mount(root.document);
+})(typeof window!=='undefined'?window:globalThis);

frontend/glass-controls.test.js

@@ -0,0 +1,22 @@
+const test=require('node:test'),assert=require('node:assert/strict');
+const {leadingGlyph}=require('./glass-controls.js');
+test('glass icon substitution preserves leading whitespace and remaining labels',()=>{
+ assert.deepEqual(leadingGlyph('  ⬇ Save'),{kind:'save',original:'  ⬇',rest:' Save'});
+ assert.deepEqual(leadingGlyph('⚙️ Settings'),{kind:'settings',original:'⚙️',rest:' Settings'});
+ assert.equal(leadingGlyph('A song with 🔍 in its title'),null);
+ assert.equal(leadingGlyph('Clear all'),null);
+ assert.equal(leadingGlyph('⏸').kind,'pause');
+});
+
+test('playlist trash, menu and music glyphs use drawn glass icons',()=>{
+ assert.equal(leadingGlyph('🗑️ Delete').kind,'trash');
+ assert.equal(leadingGlyph('⋮').kind,'more');
+ assert.equal(leadingGlyph('🎵').kind,'music');
+});
+
+test('Bento-only legacy icons leave the Glass glyph set unchanged',()=>{
+ assert.equal(leadingGlyph('📺 Show video'),null);
+ assert.deepEqual(leadingGlyph('📺 Show video',true),{kind:'television',original:'📺',rest:' Show video'});
+ assert.equal(leadingGlyph('⏱ Tap-sync',true).kind,'clock');
+ assert.equal(leadingGlyph('📌 Bookmark',true).kind,'pin');
+});

frontend/glass-panel-layout.js

@@ -0,0 +1,41 @@
+/* Glass Stage: measure the bottom chrome so panels keep clear of it. The
+   section rail stays a fixed floating bar (body-level); never move it into a
+   scrolling container or it scrolls with the content. */
+(function (root) {
+  'use strict';
+  function bottomClearance(viewport, boxes, gap = 16) {
+    const occupied = boxes.reduce((height, b) => b.fixed && b.height > 0 && b.top < viewport && b.bottom > 0 ? Math.max(height, viewport - b.top) : height, 0);
+    return Math.ceil(occupied + (occupied ? gap : 0));
+  }
+  function mount(doc) {
+    const win = doc.defaultView, html = doc.documentElement;
+    let frame = 0;
+    function active() { return html.dataset.layout === 'glass-stage'; }
+    function schedule() { if (!frame) frame = win.requestAnimationFrame(measure); }
+    function set(name, value) { if (html.style.getPropertyValue(name) !== value) html.style.setProperty(name, value); }
+    function box(el) { const r = el.getBoundingClientRect(); return { top: r.top, bottom: r.bottom, height: el.classList.contains('hidden') ? 0 : r.height, fixed: win.getComputedStyle(el).position === 'fixed' }; }
+    function measure() {
+      frame = 0; if (!active()) return;
+      const nav = doc.getElementById('bottomNav'), mini = doc.getElementById('miniBar');
+      const navBox = box(nav);
+      set('--glass-nav-height', `${Math.ceil(navBox.height)}px`);
+      // Read again after nav-height changes: the mini player's bottom depends on it.
+      set('--glass-bottom-clearance', `${bottomClearance(win.innerHeight, [box(nav), box(mini)])}px`);
+    }
+    function sync() {
+      if (active()) schedule();
+      else {
+        html.style.removeProperty('--glass-nav-height'); html.style.removeProperty('--glass-bottom-clearance');
+      }
+    }
+    const observer = new MutationObserver(sync); observer.observe(html, { attributes: true, attributeFilter: ['data-layout'] });
+    const chrome = [doc.getElementById('bottomNav'), doc.getElementById('miniBar')].filter(Boolean);
+    const changes = new MutationObserver(schedule); chrome.forEach(el => changes.observe(el, { attributes: true, attributeFilter: ['class', 'style'] }));
+    const resize = typeof win.ResizeObserver === 'function' ? new win.ResizeObserver(schedule) : null; chrome.forEach(el => resize?.observe(el));
+    win.addEventListener('resize', schedule); win.addEventListener('orientationchange', schedule); win.visualViewport?.addEventListener('resize', schedule);
+    sync();
+  }
+  if (typeof module !== 'undefined') module.exports = { bottomClearance };
+  else if (root.document.readyState === 'loading') root.document.addEventListener('DOMContentLoaded', () => mount(root.document), { once: true });
+  else mount(root.document);
+}(typeof window !== 'undefined' ? window : globalThis));

frontend/glass-panel-layout.test.js

@@ -0,0 +1,10 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { bottomClearance } = require('./glass-panel-layout.js');
+test('clearance covers stacked floating chrome and includes its viewport inset once', () => {
+  assert.equal(bottomClearance(844, [{ fixed: true, top: 740, bottom: 844, height: 104 }, { fixed: true, top: 668, bottom: 732, height: 64 }]), 192);
+  assert.equal(bottomClearance(844, [{ fixed: true, top: 740, bottom: 844, height: 104 }]), 120);
+});
+test('hidden, nonfixed and offscreen elements do not reserve chrome space', () => {
+  assert.equal(bottomClearance(844, [{ fixed: true, top: 740, bottom: 844, height: 0 }, { fixed: false, top: 668, bottom: 732, height: 64 }, { fixed: true, top: 900, bottom: 964, height: 64 }]), 0);
+});

frontend/hash-worker.js

@@ -6,11 +6,11 @@
 ^ * Out: { ok: true, sha256, size, engine } | { ok: false, error }
  * ========================================================================== */
 'use strict';
-importScripts('/sha256.js');
 
 self.onmessage = async (e) => {
   const { name } = e.data || {};
   try {
+    if (!self.Sha256) { self.__ASSET_URLS__=e.data.assetUrls || {}; importScripts(self.__ASSET_URLS__.sha256 || '/sha256.js'); }
     const root = await navigator.storage.getDirectory();
     const dir = await root.getDirectoryHandle('videos');
     const file = await (await dir.getFileHandle(String(name))).getFile();

frontend/layout-base.css

@@ -0,0 +1,11 @@
+/* Shared markup defaults stay eager when individual layouts load on demand. */
+.stg-overlay, .skip10, .deck-chips, .vol-pct, .mode-name { display: none; }
+.np-btn .ti, .np-btn .tl { pointer-events: none; }
+.np-btn .ti { width: 20px; height: 20px; flex: none; fill: none; stroke: currentColor; stroke-width: 1.9; stroke-linecap: round; stroke-linejoin: round; }
+.np-btn .i-done { display: none; }
+.np-btn.done .i-save { display: none; }
+.np-btn.done .i-done { display: inline; }
+.stg-bot, .ch-badge, .upnext-clear, .list-sub, .p2p-strip { display: none; }
+.sleep-status .sl-ic, .sleep-status .sl-sub { display: none; }
+.ab-group { display: contents; }
+.mc-tune { display: none; }

frontend/lazy.js

@@ -0,0 +1,146 @@
+/* Build-local classic-script loader. The inert manifest precedes this head script. */
+(function (root) {
+  'use strict';
+  const doc = root.document;
+  let manifest;
+  try { manifest = JSON.parse(doc.getElementById('ytp-assets').textContent); }
+  catch { return; } // The index must supply this map; never fetch one during boot.
+  const assets = new Map(), groups = new Map(), hooks = new Map();
+  const css = new Set([...doc.querySelectorAll('link[data-lazy-css]')].map(link => link.dataset.lazyCss));
+  const selected = new Map();
+  const url = path => selected.get(path) || (manifest.files[path]?.h ? path + '?v=' + manifest.files[path].h : './' + path.replace(/^\//,''));
+  function reloadRequired(name) {
+    api.reloadRequired = true;
+    if (root.CustomEvent) root.dispatchEvent?.(new root.CustomEvent('ytp-reload-required', { detail: { group: name } }));
+  }
+  function compatible(name, current, seen = new Set()) {
+    if(seen.has(name))return true;
+    seen.add(name);
+    const built=manifest.groups[name], newer=current.groups[name];
+    if(!built || !newer || built.contract!==newer.contract)return false;
+    return (newer.dependencies || []).every(dependency=>(built.dependencies || []).includes(dependency)&&compatible(dependency,current,seen));
+  }
+  async function select(name) {
+    if (!root.caches) return;
+    try {
+      const cache = await root.caches.open('ytplayer-assets');
+      const response = await cache.match('/__ytp_asset_state');
+      const current = response && (await response.json()).current;
+      const built = manifest.groups[name], newer = current?.groups[name];
+      // The active layout's CSS already executed in the parser before app boot.
+      if(name === 'layout:'+api.layout) return;
+      if (!newer || current.buildTag === manifest.buildTag) return;
+      if (!compatible(name,current)) { reloadRequired(name); return; }
+      const changedList = newer.files.join('\n') !== built.files.join('\n');
+      const available = new Map();
+      for (const path of changedList ? newer.files : built.files) {
+        // Membership and contract must both match the running core's expectation.
+        if (!newer.files.includes(path) || !current.files[path]) continue;
+        const key = path + '?v=' + current.files[path].h;
+        const held = await cache.match(key);
+        if (held?.headers.get('X-Asset-Hash') === current.files[path].h) available.set(path, key);
+      }
+      if(changedList && available.size !== newer.files.length)return;
+      for(const [path,key] of available)selected.set(path,key);
+      if(changedList)return newer;
+    } catch { /* Private browsing/cache eviction: keep the embedded build-local map. */ }
+  }
+  function inject(path) {
+    if (assets.has(path)) return assets.get(path);
+    const style = /\.css$/.test(path);
+    if (style && css.has(path)) return Promise.resolve();
+    if (!style && !/\.js$/.test(path)) return Promise.resolve(); // workers/imports/fonts are not page scripts
+    const task = new Promise((resolve, reject) => {
+      const node = doc.createElement(style ? 'link' : 'script');
+      if (style) { node.rel = 'stylesheet'; node.href = url(path); }
+      else { node.async = false; node.src = url(path); }
+      node.onload = resolve;
+      node.onerror = () => reject(new Error('Unable to load ' + path));
+      doc.head.append(node);
+    });
+    assets.set(path, task);
+    task.catch(() => assets.delete(path));
+    return task;
+  }
+  function load(name) {
+    if (groups.has(name)) return groups.get(name);
+    const group = manifest.groups[name];
+    if (!group) return Promise.reject(new Error('Unknown asset group: ' + name));
+    const task = (async () => {
+      for (const dependency of group.dependencies || []) await load(dependency);
+      const selectedGroup = await select(name) || group;
+      for (const path of selectedGroup.files) if (!/-worker\.js$/.test(path)) await inject(path);
+      for (const fn of hooks.get(name) || []) await fn();
+      group.executed = true;
+    })();
+    groups.set(name, task);
+    task.catch(error => {
+      groups.delete(name);
+      if (root.CustomEvent) root.dispatchEvent?.(new root.CustomEvent('ytp-lazy-error', { detail: { group: name, error } }));
+    });
+    return task;
+  }
+  const api = {
+    load, prefetch: load, loaded: name => !!manifest.groups[name]?.executed, url,
+    manifest, layout: 'classic', reloadRequired: false,
+    worker(path) {
+      const worker=new root.Worker(url(path)), post=worker.postMessage.bind(worker); let first=true;
+      worker.postMessage=(message,transfer)=>{
+        if(first) { first=false; message={...message,assetUrls:{sha256:url('/sha256.js'),wasm:url('/sha256-wasm.js'),resume:url('/resume-core.js')}}; }
+        post(message,transfer);
+      };
+      return worker;
+    },
+    reportLayout(registration) {
+      const send = reg => {
+        const workers = new Set([root.navigator.serviceWorker.controller, reg?.installing, reg?.waiting, reg?.active]);
+        for(const worker of workers) worker?.postMessage({type:'LAYOUT',value:api.layout});
+      };
+      if(registration)send(registration);
+      else root.navigator.serviceWorker?.getRegistration().then(send).catch(()=>{});
+    },
+    warm() {
+      if (!root.navigator.serviceWorker || root.navigator.onLine === false) return;
+      root.navigator.serviceWorker.ready.then(reg => {
+        for (const worker of new Set([reg.active, reg.waiting])) worker?.postMessage({type:'COMPLETE_ASSETS'});
+      }).catch(()=>{});
+    },
+    onLoad(name, fn) {
+      if(api.loaded(name)) { Promise.resolve().then(fn).catch(error=>{if(root.CustomEvent)root.dispatchEvent?.(new root.CustomEvent('ytp-lazy-error',{detail:{group:name,error}}));}); return; }
+      const list = hooks.get(name) || []; list.push(fn); hooks.set(name, list);
+    },
+    proxy(name, methods, globalName) {
+      return Object.fromEntries(methods.map(method => [method, async (...args) => {
+        await load(name);
+        const key = globalName || name.split(':')[1];
+        const target = root.YT?.[key] || root[key];
+        if (typeof target?.[method] !== 'function') throw new Error('Missing lazy method: ' + method);
+        return target[method](...args);
+      }]));
+    },
+    intent(element, name) {
+      if (!element) return;
+      for (const type of ['pointerenter', 'focus', 'touchstart']) element.addEventListener(type, () => load(name).catch(() => {}), { once: true, passive: true });
+    },
+  };
+  root.Lazy = api;
+  root.navigator.serviceWorker?.addEventListener('message',event=>{
+    if(event.data?.type==='ASSET_LAYOUT_REQUEST') event.source?.postMessage({type:'LAYOUT',value:api.layout});
+    if(event.data?.type==='SW_UPDATE_AVAILABLE') api.warm();
+  });
+  root.navigator.serviceWorker?.addEventListener('controllerchange',()=>{api.reportLayout();api.warm();});
+  root.addEventListener?.('online',()=>api.warm());
+  api.warm();
+  let settings={};
+  try { settings=JSON.parse(root.localStorage.getItem('_ytpdata') || '{}').settings || {}; api.layout=settings.layout || 'classic'; } catch {}
+  Object.assign(doc.documentElement.dataset,{layout:api.layout,theme:settings.theme || 'dark',font:settings.fontScale || 'normal',density:settings.density || 'comfortable',perf:settings.perfMode?'on':'off',motion:settings.reduceMotion?'reduced':'full'});
+  const layoutName = manifest.groups['layout:' + api.layout] ? 'layout:'+api.layout : 'layout:classic';
+  const layoutGroups = new Set([layoutName]);
+  for(const name of layoutGroups) for(const dependency of manifest.groups[name]?.dependencies || []) layoutGroups.add(dependency);
+  if (doc.readyState === 'loading') for (const path of [...layoutGroups].flatMap(name=>manifest.groups[name]?.files || [])) {
+    if (!/\.css$/.test(path) || css.has(path)) continue;
+    // Parser-inserted CSS blocks rendering; dynamic head links do not on all WebKit versions.
+    css.add(path);
+    doc.write('<link rel="stylesheet" href="' + url(path) + '" data-lazy-css="' + path + '">');
+  }
+})(typeof window !== 'undefined' ? window : globalThis);

frontend/lazy.test.js

@@ -0,0 +1,97 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { readFileSync } = require('node:fs');
+const vm = require('node:vm');
+function fixture(current, held = []) {
+  const inserted = [], listeners = {}, writes = [];
+  const manifest = { buildTag: 'own', groups: { core: { files: [] }, 'layout:classic': { files: ['/classic.css'] }, 'layout:glass-stage': { files: ['/glass.css', '/one.js', '/two.js'] }, 'feature:test': { contract:1, files: ['/one.js', '/two.js'] } }, files: { '/classic.css': {h:'c'}, '/glass.css':{h:'g'}, '/one.js':{h:'1'}, '/two.js':{h:'2'} } };
+  const doc = { readyState:'loading', documentElement: { dataset:{} }, getElementById: () => ({ textContent:JSON.stringify(manifest) }), querySelectorAll: () => [], createElement: tag => ({ tagName:tag.toUpperCase() }), write: value => writes.push(value), addEventListener: (t,f) => listeners[t]=f };
+  doc.head = { append: node => { inserted.push(node); queueMicrotask(() => node.onload?.()); } };
+  const root = { document:doc, localStorage:{ getItem:() => '{"settings":{"layout":"glass-stage"}}' }, console, Promise, URL, setTimeout, clearTimeout, navigator:{}, addEventListener(){} };
+  if (current) root.caches = { open: async () => ({ match: async key => key === '/__ytp_asset_state' ? new Response(JSON.stringify({current})) : held.includes(key) ? new Response('', {headers:{'X-Asset-Hash':key.split('=')[1]}}) : undefined }) };
+  root.window=root; root.globalThis=root;
+  vm.runInNewContext(readFileSync(require.resolve('./lazy.js'),'utf8'), root);
+  return { root, inserted, writes, listeners, manifest };
+}
+test('external head bootstrap selects remembered CSS before paint without fetching a manifest', () => {
+  const {root,writes}=fixture();
+  assert.equal(root.document.documentElement.dataset.layout,'glass-stage');
+  assert.deepEqual(writes,['<link rel="stylesheet" href="/glass.css?v=g" data-lazy-css="/glass.css">']);
+});
+test('lazy groups execute ordered classic scripts once, sharing concurrent calls and dependencies', async () => {
+  const {root,inserted}=fixture();
+  const one=root.Lazy.load('feature:test'), two=root.Lazy.load('feature:test');
+  await Promise.all([one,two]);
+  assert.deepEqual(inserted.map(n=>n.src),['/one.js?v=1','/two.js?v=2']);
+  assert.equal(root.Lazy.loaded('feature:test'),true);
+  await root.Lazy.load('layout:glass-stage');
+  assert.equal(inserted.filter(n=>n.tagName==='SCRIPT').length,2);
+});
+test('failed injection can retry and proxy dispatches only after execution', async () => {
+  const {root,inserted}=fixture();
+  const append=root.document.head.append;
+  root.document.head.append=n=>{inserted.push(n);queueMicrotask(()=>n.onerror?.());};
+  await assert.rejects(root.Lazy.load('feature:test'),/one.js/);
+  root.document.head.append=append;
+  root.TestApi={open:value=>value+1};
+  const proxy=root.Lazy.proxy('feature:test',['open'],'TestApi');
+  assert.equal(await proxy.open(4),5);
+  assert.equal(root.Lazy.url('/two.js'),'/two.js?v=2');
+  await assert.rejects(root.Lazy.load('feature:missing'),/Unknown/);
+});
+
+test('executing groups are pinned even after a newer compatible manifest arrives', async () => {
+  const f=fixture(); await f.root.Lazy.load('feature:test');
+  const newer=JSON.parse(JSON.stringify(f.manifest)); newer.files['/one.js'].h='new';
+  f.root.caches={open:async()=>({match:async key=>key==='/__ytp_asset_state'?new Response(JSON.stringify({current:newer})):new Response('',{headers:{'X-Asset-Hash':'new'}})})};
+  await f.root.Lazy.load('feature:test');
+  assert.deepEqual(f.inserted.map(n=>n.src),['/one.js?v=1','/two.js?v=2']);
+});
+test('unexecuted compatible group immediately uses newly cached file URLs', async () => {
+  const next=fixture().manifest; next.buildTag='new'; next.files['/one.js'].h='new';
+  const f=fixture(next,['/one.js?v=new','/two.js?v=2']);
+  await f.root.Lazy.load('feature:test');
+  assert.deepEqual(f.inserted.map(n=>n.src),['/one.js?v=new','/two.js?v=2']);
+  assert.equal(f.root.Lazy.reloadRequired,false);
+});
+test('unexecuted incompatible group keeps its running-build N-1 URLs and requires reload', async () => {
+  const next=fixture().manifest; next.buildTag='new'; next.files['/one.js'].h='new'; next.groups['feature:test'].contract=2;
+  const f=fixture(next,['/one.js?v=new','/two.js?v=2']);
+  const events=[]; f.root.CustomEvent=class {constructor(type,opts){this.type=type;this.detail=opts.detail}}; f.root.dispatchEvent=e=>events.push(e.type);
+  await f.root.Lazy.load('feature:test');
+  assert.deepEqual(f.inserted.map(n=>n.src),['/one.js?v=1','/two.js?v=2']);
+  assert.equal(f.root.Lazy.reloadRequired,true);
+  assert.ok(events.includes('ytp-reload-required'));
+});
+
+test('workers receive the pinned import URL map in their first message', () => {
+ const f=fixture(), sent=[]; f.root.Worker=class { constructor(url){this.url=url;} postMessage(message,transfer){sent.push({message,transfer});} };
+ f.manifest.files['/worker.js']={h:'w'}; f.root.Lazy.manifest.files['/worker.js']={h:'w'};
+ const worker=f.root.Lazy.worker('/worker.js');worker.postMessage({op:'open'},['transfer']);worker.postMessage({op:'finish'});
+ assert.equal(worker.url,'/worker.js?v=w');assert.equal(sent[0].message.assetUrls.sha256,f.root.Lazy.url('/sha256.js'));assert.equal(sent[0].message.assetUrls.wasm,f.root.Lazy.url('/sha256-wasm.js'));assert.deepEqual(sent[0].transfer,['transfer']);assert.equal(sent[1].message.assetUrls,undefined);
+});
+
+test('new group files with a changed dependency contract cannot run against the old dependency',async()=>{
+ const next=fixture().manifest;next.buildTag='next';next.groups['feature:test'].dependencies=['feature:dep'];next.groups['feature:dep']={contract:2,files:[]};next.files['/one.js'].h='new';
+ const f=fixture(next,['/one.js?v=new','/two.js?v=2']);f.root.Lazy.manifest.groups['feature:test'].dependencies=['feature:dep'];f.root.Lazy.manifest.groups['feature:dep']={contract:1,files:[]};
+ await f.root.Lazy.load('feature:test');assert.deepEqual(f.inserted.map(n=>n.src),['/one.js?v=1','/two.js?v=2']);assert.equal(f.root.Lazy.reloadRequired,true);
+});
+
+test('classic chunk registry proxies use window.YT and keep the executed singleton pinned',async()=>{
+ const {root,inserted}=fixture();root.YT={TestApi:{open:n=>n+2}};
+ const proxy=root.Lazy.proxy('feature:test',['open'],'TestApi');
+ assert.equal(await proxy.open(3),5);
+ const singleton=root.YT.TestApi;await root.Lazy.load('feature:test');
+ assert.equal(root.YT.TestApi,singleton);assert.equal(inserted.length,2);
+});
+
+
+test('online launches request worker completion even with Save-Data and skip offline messages',async()=>{
+ const f=fixture(),sent=[];
+ const active={postMessage:m=>sent.push(m)},waiting={postMessage:m=>sent.push(m)};
+ f.root.navigator.connection={saveData:true};f.root.navigator.onLine=true;
+ f.root.navigator.serviceWorker={ready:Promise.resolve({active,waiting})};
+ f.root.Lazy.warm();await Promise.resolve();
+ assert.deepEqual(sent.map(m=>m.type),['COMPLETE_ASSETS','COMPLETE_ASSETS']);
+ f.root.navigator.onLine=false;f.root.Lazy.warm();await Promise.resolve();assert.equal(sent.length,2);
+});

frontend/loudness-wasm.js

@@ -0,0 +1,6 @@
+/* GENERATED by scripts/build-loudness-wasm.sh from frontend/wasm/loudness.c — do not edit.
+ * WebAssembly K-weighting + 100 ms energy steps for EBU R128 loudness (see loudness.js). */
+(function (root) {
+  root.LOUDNESS_WASM_B64 = 'AGFzbQEAAAABHQRgAX8Bf2AAAX9gDH9/fHx8fHx8fHx8fABgAX8AAwYFAAEBAgMFAwEAQgYIAX8BQYDAAAsHMQYGbWVtb3J5AgAFaW5idWYAAAVzdGVwcwABBWNvdW50AAIFc2V0dXAAAwRmZWVkAAQK2QoFEQBBgMCAgABBgMCQgAAgABsLCABBgMCggAALCwBBACgCgOjjgQAL5wIAQQBCADcDkOjjgQBBACACOQOg6OOBAEEAIAM5A6jo44EAQQAgBDkDsOjjgQBBACAFOQO46OOBAEEAIAY5A8Do44EAQQAgBzkD0OjjgQBBACAIOQPY6OOBAEEAIAk5A+Do44EAQQAgCjkD6OjjgQBBACALOQPw6OOBAEEAQgA3A/jp44EAQQBCADcD8OnjgQBBAEIANwPo6eOBAEEAQgA3A+Dp44EAQQBCADcD2OnjgQBBAEIANwPQ6eOBAEEAQgA3A8jp44EAQQBCADcDwOnjgQBBAEIANwO46eOBAEEAQgA3A7Dp44EAQQBCADcDqOnjgQBBAEIANwOg6eOBAEEAQgA3A5jp44EAQQBCADcDkOnjgQBBAEIANwOI6eOBAEEAQgA3A4Dp44EAQQAgAUEBIAFBAUobNgKI6OOBAEEAQQJBASAAQQFKGzYChOjjgQBBAEEANgKM6OOBAEEAQQA2AoDo44EAC8YHDgN/CHwBfwd8An8EfAJ/BHwCfwF8An8BfAF/A3wCQCAAQQFIDQAgAEGAgAQgAEGAgARIGyEBQQAoAoTo44EAIgJBf2ohA0EAKwO46eOBACEEQQArA7Dp44EAIQVBACsDqOnjgQAhBkEAKwOg6eOBACEHQQArA5jp44EAIQhBACsDkOnjgQAhCUEAKwOI6eOBACEKQQArA4Dp44EAIQtBACgCiOjjgQAhDEEAKwPg6OOBACENQQArA9jo44EAIQ5BACsD0OjjgQAhD0EAKwOw6OOBACEQQQArA6jo44EAIRFBACsDoOjjgQAhEkEAKwOQ6OOBACETQQAoAozo44EAIRRBACgCgOjjgQAhFUEAKwPw6OOBAJohFkEAKwPo6OOBAJohF0EAKwPA6OOBAJohGEEAKwO46OOBAJohGSACQQFIIRpBACEbA0ACQAJAIBpFDQBEAAAAAAAAAAAhHAwBC0EAIAs5A4jp44EAQQAgCTkDmOnjgQBBACAHOQOo6eOBAEEAIAU5A7jp44EAQQAgG0ECdCIAKgKAwJCAALsiHTkDgOnjgQBBACAYIAiiIBkgCaIgECAKoiASIB2iIBEgC6KgoKCgIh45A5Dp44EAQQAgHjkDoOnjgQBBACAWIASiIBcgBaIgDSAGoiAPIB6iIA4gB6KgoKCgIh85A7Dp44EAIB8gH6JEAAAAAAAAAACgIRwCQCACQQFGDQAgACoCgMCAgAC7IQRBgOnjgQAhACADISADQCAAQcgAaiIhKwMAISIgISAAQcAAaiIjKwMAIgY5AwAgAEHYAGoiISsDACEIICEgAEHQAGoiJCsDACIKOQMAICMgBDkDACAAQegAaiIhKwMAISUgISAAQeAAaiImKwMAIic5AwAgAEH4AGoiISsDACEoICEgAEHwAGoiACsDACIpOQMAICQgGCAIoiAZIAqiIBAgIqIgEiAEoiARIAaioKCgoCIiOQMAICYgIjkDACAAIBYgKKIgFyApoiANICWiIA8gIqIgDiAnoqCgoKAiIjkDACAiICKiIBygIRwgIyEAICBBf2oiIA0ACwsgBSEEIB8hBSAHIQYgHiEHIAkhCCAeIQkgCyEKIB0hCwsgHCAToCEiAkACQCAUQQFqIhQgDEYNACAiIRMMAQtEAAAAAAAAAAAhE0EAIRQgFUH/tBhKDQBBACEUQQAgFUEBaiIANgKA6OOBACAVQQN0QYDAoIAAaiAiOQMAIAAhFQsgG0EBaiIbIAFHDQALQQAgFDYCjOjjgQBBACATOQOQ6OOBAAsL';
+  if (typeof module !== 'undefined' && module.exports) module.exports = root.LOUDNESS_WASM_B64;
+})(typeof globalThis !== 'undefined' ? globalThis : this);

frontend/loudness.js

@@ -0,0 +1,122 @@
+/* ============================================================================
+ * loudness — EBU R128 integrated loudness (LUFS), measured in the browser.
+ *
+ * The per-sample work (two K-weighting biquads + 100 ms energy steps) runs in
+ * WebAssembly (loudness-wasm.js, built from wasm/loudness.c); a plain JS loop
+ * with identical math is the fallback. Gating (400 ms blocks, 75 % overlap,
+ * absolute -70 LUFS, relative -10 LU) is done here on the step energies.
+ *
+ * Plain <script> global `Loudness` in the browser; `require`-able by node.
+ * ========================================================================== */
+(function (root) {
+  'use strict';
+
+  const CHUNK = 65536;
+
+  // ITU-R BS.1770-4 K-weighting, recomputed for any sample rate.
+  function coefficients(fs) {
+    let f0 = 1681.974450955533, G = 3.999843853973347, Q = 0.7071752369554196;
+    let K = Math.tan(Math.PI * f0 / fs);
+    const Vh = Math.pow(10, G / 20), Vb = Math.pow(Vh, 0.4996667741545416);
+    let a0 = 1 + K / Q + K * K;
+    const s1 = [(Vh + Vb * K / Q + K * K) / a0, 2 * (K * K - Vh) / a0, (Vh - Vb * K / Q + K * K) / a0,
+      2 * (K * K - 1) / a0, (1 - K / Q + K * K) / a0];
+    f0 = 38.13547087602444; Q = 0.5003270373238773;
+    K = Math.tan(Math.PI * f0 / fs);
+    a0 = 1 + K / Q + K * K;
+    const s2 = [1, -2, 1, 2 * (K * K - 1) / a0, (1 - K / Q + K * K) / a0];
+    return [s1, s2];
+  }
+
+  // Gating over per-100 ms energies (already summed over channels).
+  function integrate(stepE, n, stepLen) {
+    const blocks = [];
+    for (let i = 0; i + 4 <= n; i++) {
+      const z = (stepE[i] + stepE[i + 1] + stepE[i + 2] + stepE[i + 3]) / (4 * stepLen);
+      if (z > 0) blocks.push(z);
+    }
+    const L = (z) => -0.691 + 10 * Math.log10(z);
+    const abs = blocks.filter((z) => L(z) > -70);
+    if (!abs.length) return null;
+    const rel = L(abs.reduce((a, b) => a + b, 0) / abs.length) - 10;
+    const gated = abs.filter((z) => L(z) > rel);
+    if (!gated.length) return null;
+    return L(gated.reduce((a, b) => a + b, 0) / gated.length);
+  }
+
+  // ---- engines: { setup(nch, stepLen, s1, s2), input(ch) → Float32Array, feed(n), result() } ----
+  function wasmEngine() {
+    const b64 = root.LOUDNESS_WASM_B64;
+    if (!b64 || typeof WebAssembly === 'undefined') return null;
+    try {
+      const bin = typeof atob === 'function'
+        ? Uint8Array.from(atob(b64), (c) => c.charCodeAt(0))
+        : Uint8Array.from(Buffer.from(b64, 'base64'));
+      const inst = new WebAssembly.Instance(new WebAssembly.Module(bin), {});
+      const x = inst.exports;
+      const mem = () => x.memory.buffer;
+      return {
+        engine: 'wasm',
+        setup(nch, stepLen, s1, s2) { x.setup(nch, stepLen, ...s1, ...s2); },
+        input(ch) { return new Float32Array(mem(), x.inbuf(ch), CHUNK); },
+        feed(n) { x.feed(n); },
+        steps() { return [new Float64Array(mem(), x.steps(), x.count()), x.count()]; },
+      };
+    } catch { return null; }
+  }
+
+  function jsEngine() {
+    const buf = [new Float32Array(CHUNK), new Float32Array(CHUNK)];
+    let nch = 1, stepLen = 1, stepPos = 0, acc = 0, k1, k2, st;
+    const out = [];
+    return {
+      engine: 'js',
+      setup(c, sl, s1, s2) { nch = c > 1 ? 2 : 1; stepLen = sl; stepPos = 0; acc = 0; k1 = s1; k2 = s2; st = [new Float64Array(8), new Float64Array(8)]; out.length = 0; },
+      input(ch) { return buf[ch]; },
+      feed(n) {
+        for (let i = 0; i < n; i++) {
+          let e = 0;
+          for (let c = 0; c < nch; c++) {
+            const s = st[c], x = buf[c][i];
+            const y = k1[0] * x + k1[1] * s[0] + k1[2] * s[1] - k1[3] * s[2] - k1[4] * s[3];
+            s[1] = s[0]; s[0] = x; s[3] = s[2]; s[2] = y;
+            const z = k2[0] * y + k2[1] * s[4] + k2[2] * s[5] - k2[3] * s[6] - k2[4] * s[7];
+            s[5] = s[4]; s[4] = y; s[7] = s[6]; s[6] = z;
+            e += z * z;
+          }
+          acc += e;
+          if (++stepPos === stepLen) { out.push(acc); acc = 0; stepPos = 0; }
+        }
+      },
+      steps() { return [out, out.length]; },
+    };
+  }
+
+  let _engine = null;
+  function engine(prefer) {
+    if (prefer === 'js') return jsEngine();
+    if (!_engine) _engine = wasmEngine() || jsEngine();
+    return _engine;
+  }
+
+  /** Integrated loudness (LUFS) of channel data, or null for silence. */
+  function measureChannels(channels, sampleRate, { prefer } = {}) {
+    const e = engine(prefer);
+    const nch = Math.min(2, channels.length);
+    const stepLen = Math.max(1, Math.round(sampleRate / 10));
+    const [s1, s2] = coefficients(sampleRate);
+    e.setup(nch, stepLen, s1, s2);
+    const len = channels[0].length;
+    for (let pos = 0; pos < len; pos += CHUNK) {
+      const n = Math.min(CHUNK, len - pos);
+      for (let c = 0; c < nch; c++) e.input(c).set(channels[c].subarray(pos, pos + n));
+      e.feed(n);
+    }
+    const [steps, n] = e.steps();
+    return integrate(steps, n, stepLen);
+  }
+
+  const Loudness = { coefficients, integrate, measureChannels, engineName: () => engine().engine, TARGET: -14 };
+  if (typeof module !== 'undefined' && module.exports) module.exports = Loudness;
+  else root.Loudness = Loudness;
+})(typeof globalThis !== 'undefined' ? globalThis : this);

frontend/loudness.test.js

@@ -0,0 +1,37 @@
+'use strict';
+const { test } = require('node:test');
+const assert = require('node:assert');
+globalThis.LOUDNESS_WASM_B64 = require('./loudness-wasm.js');
+const L = require('./loudness');
+
+const sine = (amp, freq, fs, secs) => { const a = new Float32Array(fs * secs); for (let i = 0; i < a.length; i++) a[i] = amp * Math.sin(2 * Math.PI * freq * i / fs); return a; };
+const dbfs = (db) => Math.pow(10, db / 20);
+
+test('EBU Tech 3341 case: 1 kHz stereo sine at -23 dBFS measures -23.0 LUFS (wasm and js)', () => {
+  for (const fs of [48000, 44100, 22050]) {
+    const s = sine(dbfs(-23), 1000, fs, 20);
+    const w = L.measureChannels([s, s], fs);
+    const j = L.measureChannels([s, s], fs, { prefer: 'js' });
+    assert.ok(Math.abs(w - -23) < 0.1, `wasm ${fs}: ${w}`);
+    assert.ok(Math.abs(j - w) < 1e-6, `js ${j} vs wasm ${w}`);
+  }
+  assert.strictEqual(L.engineName(), 'wasm');
+});
+
+test('EBU Tech 3341 case: -33 dBFS measures -33.0 LUFS', () => {
+  const s = sine(dbfs(-33), 1000, 48000, 20);
+  assert.ok(Math.abs(L.measureChannels([s, s], 48000) - -33) < 0.1);
+});
+
+test('gating ignores silence around the music', () => {
+  const fs = 48000, s = sine(dbfs(-23), 1000, fs, 10);
+  const padded = new Float32Array(fs * 30); padded.set(s, fs * 10);
+  // 20 s of silence would read about -27.8 ungated; only the partial 400 ms
+  // blocks at the tone's edges still count, which is correct R128 behaviour.
+  assert.ok(Math.abs(L.measureChannels([padded, padded], fs) - -23) < 0.2);
+});
+
+test('silence is null', () => {
+  const z = new Float32Array(48000 * 5);
+  assert.strictEqual(L.measureChannels([z, z], 48000), null);
+});

frontend/lower-third.css

@@ -0,0 +1,10 @@
+html.obs-overlay, .obs-overlay body, .obs-overlay #presenterView { background: transparent !important; }
+.obs-overlay body > *:not(#presenterView):not(#obsLowerThird) { display: none !important; }
+.obs-overlay #presenterView { pointer-events: none; }
+.obs-overlay #presenterView > * { visibility: hidden; }
+#obsLowerThird { position: fixed; inset: auto 6vw 7vh; z-index: 10000; text-align: center; color: white; font-family: system-ui, sans-serif; font-weight: 650; font-size: clamp(24px, 3.4vw, 70px); line-height: 1.15; text-shadow: 0 2px 4px #000, 0 0 14px #000, 0 0 3px #000; pointer-events: none; }
+.obs-line { white-space: pre-line; animation: obs-cue-in 220ms ease-out; }
+.obs-next { font-size: .7em; opacity: .8; margin-top: .3em; }
+.obs-line small { display: block; font-size: .65em; opacity: .8; margin-top: .15em; }
+@keyframes obs-cue-in { from { opacity: 0; transform: translateY(12px); } to { transform: translateY(0); } }
+@media (prefers-reduced-motion: reduce) { .obs-line { animation: none; } }

frontend/lower-third.js

@@ -0,0 +1,16 @@
+/* Broadcast lyrics rendered through the existing presenter relay. */
+(function(root) {
+  'use strict';
+  function cuePair(lines, index) { const current = lines[index]?.kind === 'line' ? lines[index] : null; const next = lines.slice(Math.max(0, index + 1)).find(l => l.kind === 'line') || null; return { current, next }; }
+  function url(origin, code) { const u = new URL('/', origin); u.searchParams.set('overlay', 'lowerthird'); u.searchParams.set('code', String(code)); return u.href; }
+  const active = () => new URLSearchParams(root.location?.search).get('overlay') === 'lowerthird';
+  let box, signature = '';
+  function paint(lines, index) {
+    if (!box) { box = root.document.createElement('div'); box.id = 'obsLowerThird'; box.setAttribute('aria-live', 'polite'); root.document.body.append(box); }
+    const pair = cuePair(lines, index), key = JSON.stringify(pair); if (key === signature) return; signature = key;
+    box.replaceChildren();
+    for (const [role, cue] of Object.entries(pair)) { const p = root.document.createElement('div'); p.className = `obs-line obs-${role}`; const parts = root.LyricsCore.display(cue); p.textContent = parts.text; if (parts.secondary || parts.phonetic) { const secondary = root.document.createElement('small'); secondary.textContent = [parts.secondary, parts.phonetic].filter(Boolean).join(' · '); p.append(secondary); } box.append(p); }
+  }
+  function register(open) { root.SettingsSections.register({ id: 'broadcast', title: 'Presenter & broadcast', cluster: 'Live & worship', summary: () => 'Projector · OBS lower third', render(container) { const doc = container.ownerDocument, p = doc.createElement('p'); p.textContent = 'Start a remote-controlled screen, then copy its OBS browser-source URL. Set the browser source to 1920 × 1080. The output follows the host and remains transparent. Pairing codes expire; an already paired source reconnects until you unpair it.'; const b = doc.createElement('button'); b.type = 'button'; b.className = 'settings-back'; b.textContent = 'Open presenter & remote controls'; b.onclick = open; container.append(p, b); } }); }
+  const api = { active, paint, cuePair, url, register }; if (typeof module !== 'undefined') module.exports = api; else { root.LowerThird = api; if (active()) root.document.documentElement.classList.add('obs-overlay'); }
+})(typeof window !== 'undefined' ? window : globalThis);

frontend/lower-third.test.js

@@ -0,0 +1,3 @@
+const { test } = require('node:test'), assert = require('node:assert/strict'); const { cuePair, url } = require('./lower-third');
+test('lower third skips section headings for next lyrics and does not invent current lyrics', () => { const lines = [{ kind: 'line', text: 'First' }, { kind: 'section', text: 'Chorus' }, { kind: 'line', text: 'Second' }]; assert.equal(cuePair(lines, 0).next.text, 'Second'); assert.equal(cuePair(lines, 1).current, null); assert.equal(cuePair(lines, -1).next.text, 'First'); assert.equal(cuePair(lines, 2).next, null); });
+test('OBS output URL encodes the code without adding host credentials', () => { const u = new URL(url('https://example.test/subpath', '123456')); assert.equal(u.pathname, '/'); assert.equal(u.searchParams.get('overlay'), 'lowerthird'); assert.equal(u.searchParams.get('code'), '123456'); });

frontend/lyrics-core.js

@@ -11,6 +11,7 @@
  *   @ Key G, Capo 2 (Play F), 70 BPM                    tags
  *   [00:12.00][01:30.00] repeated line                  LRC multi-stamp
  *   [offset:+500]                                       LRC offset (ms, + = sooner)
+ *   | You can do anything                              continuation, same cue
  * Other LRC headers ([ar:], [ti:], …) are ignored.
  *
  * Sync offset: a line is shown at (t + offset) seconds of playback, so a
@@ -55,14 +56,31 @@
     return String(s).split(/[,|·]/).map((x) => x.trim()).filter(Boolean);
   }
 
+  function display(line) {
+    const text = String(line?.text || ''), divider = text.indexOf(' / ');
+    return { text: divider < 0 ? text : text.slice(0, divider).trim(), secondary: line?.secondary || (divider < 0 ? '' : text.slice(divider + 3).trim()), phonetic: line?.phonetic || '' };
+  }
+
   // Editor text → { lines, tags, offset }.
   function fromText(text) {
     const lines = [];
     const tags = [];
     let offset = null;
+    let group = [];
     for (const rawLine of String(text || '').replace(/\r/g, '').split('\n')) {
       let rest = rawLine.trim();
       if (!rest) continue;
+      if (/^!pinyin:\s*/i.test(rest) && group.some(l => l.kind === 'line')) {
+        const value = rest.replace(/^!pinyin:\s*/i, '').trim();
+        for (const line of group) if (value) line.phonetic = line.phonetic ? line.phonetic + '\n' + value : value;
+        continue;
+      }
+      if (rest.startsWith('| ') && group.length) {
+        const extra = display({ text: rest.slice(2).trim() });
+        for (const line of group) { line.text += '\n' + extra.text; if (extra.secondary) line.secondary = line.secondary ? line.secondary + '\n' + extra.secondary : extra.secondary; }
+        continue;
+      }
+      group = [];
       const header = rest.match(HEADER_RE);
       if (header && !/^\d/.test(header[1])) {
         if (header[1].toLowerCase() === 'offset') {
@@ -83,8 +101,10 @@
       if (rest.startsWith('#')) { kind = 'section'; rest = rest.replace(/^#+/, '').trim(); }
       else if (rest.startsWith('!')) { kind = 'cue'; rest = rest.slice(1).trim(); }
       if (!rest) continue;
-      if (!stamps.length) lines.push({ t: null, text: rest, kind });
-      for (const t of stamps) lines.push({ t: Math.round(t * 100) / 100, text: rest, kind });
+      group = stamps.length ? stamps.map(t => ({ t: Math.round(t * 100) / 100, text: rest, kind }))
+        : [{ t: null, text: rest, kind }];
+      if (kind === 'line') for (const line of group) { const parts = display(line); line.text = parts.text; if (parts.secondary) line.secondary = parts.secondary; }
+      lines.push(...group);
     }
     // A fully timed sheet (typical .lrc with repeated-chorus stamps) is put in
     // time order; a partly timed one keeps the order it was written in.
@@ -100,7 +120,11 @@
     for (const l of (doc && doc.lines) || []) {
       const stamp = l.t === null || l.t === undefined ? '' : `[${fmtStamp(l.t)}] `;
       const mark = l.kind === 'section' ? '# ' : l.kind === 'cue' ? '! ' : '';
-      out.push(stamp + mark + l.text);
+      const parts = (l.kind === 'line' ? display(l) : { text: l.text || '', secondary: '' });
+      const primary = parts.text.split('\n'), secondary = parts.secondary.split('\n');
+      const combined = primary.map((part, i) => part + (secondary[i] ? ' / ' + secondary[i] : ''));
+      out.push(stamp + mark + combined[0], ...combined.slice(1).map(part => '| ' + part));
+      if (l.phonetic) out.push(...String(l.phonetic).split('\n').map(part => '!pinyin: ' + part));
     }
     return out.join('\n');
   }
@@ -153,7 +177,7 @@
   }
 
   const LyricsCore = {
-    parseStamp, fmtStamp, fmtClock, fromText, toText,
+    parseStamp, fmtStamp, fmtClock, fromText, toText, display,
     activeIndex, activeSection, timedCount, activeMarker, toYouTubeTimestamps,
   };
 

frontend/lyrics-core.test.js

@@ -78,3 +78,26 @@ test('YouTube export adds a 0:00 entry only when needed', () => {
   assert.strictEqual(LC.activeMarker(items, 60).title, 'Intro');
   assert.strictEqual(LC.activeMarker(items, 10), null);
 });
+
+
+test('multiline cues round-trip without adding timestamps or active rows', () => {
+  const doc = { lines: [{ t: 12, text: 'Because You are God\nYou can do anything', kind: 'line' }, { t: 18, text: 'Next lyric', kind: 'line' }], tags: [] };
+  const copy = LC.fromText(LC.toText(doc));
+  assert.deepStrictEqual(copy.lines, doc.lines);
+  assert.strictEqual(LC.activeIndex(copy.lines, 15, 0), 0);
+  assert.strictEqual(LC.activeIndex(copy.lines, 18, 0), 1);
+  assert.strictEqual(LC.timedCount(copy.lines), 2);
+  const repeated = LC.fromText('[0:12][0:30] Because You are God\n| You can do anything');
+  assert.strictEqual(repeated.lines.length, 2);
+  assert.strictEqual(repeated.lines[1].text, doc.lines[0].text);
+});
+test('bilingual lyrics and pinyin share one timed cue and round-trip', () => {
+  const doc = LC.fromText('[1:23.45] 主你的恩典 / Your grace is enough\n!pinyin: zhǔ nǐ de ēndiǎn');
+  assert.equal(doc.lines.length, 1); assert.equal(doc.lines[0].t,83.45); assert.equal(doc.lines[0].secondary,'Your grace is enough'); assert.equal(doc.lines[0].phonetic,'zhǔ nǐ de ēndiǎn');
+  assert.deepEqual(LC.fromText(LC.toText(doc)).lines, doc.lines);
+});
+test('translations preserve grouped breaks, multi-stamps and legacy slash text', () => {
+  const doc = LC.fromText('[0:01][0:10] 主 / Lord\n| 恩典 / Grace\n!pinyin: zhǔ\n!pinyin: ēndiǎn');
+  assert.equal(doc.lines.length,2); assert.equal(doc.lines[1].secondary,'Lord\nGrace'); assert.equal(doc.lines[1].phonetic,'zhǔ\nēndiǎn'); assert.deepEqual(LC.fromText(LC.toText(doc)).lines, doc.lines);
+  assert.equal(LC.fromText('and/or').lines[0].text,'and/or'); assert.equal(LC.fromText('! Band cue').lines[0].kind,'cue');
+});

frontend/lyrics-display.js

@@ -0,0 +1,8 @@
+(function(root) {
+  'use strict';
+  const core = typeof module !== 'undefined' ? require('./lyrics-core') : root.LyricsCore;
+  const escape = value => String(value || '').replace(/[&<>"']/g, c => ({ '&':'&amp;', '<':'&lt;', '>':'&gt;', '"':'&quot;', "'":'&#39;' })[c]);
+  function html(line) { const parts = core.display(line); return `<span class="lyric-primary">${escape(parts.text)}</span>${parts.secondary ? `<small class="lyric-secondary">${escape(parts.secondary)}</small>` : ''}${parts.phonetic ? `<small class="lyric-secondary lyric-phonetic">${escape(parts.phonetic)}</small>` : ''}`; }
+  function register() { root.SettingsSections.register({ id: 'lyrics-language', title: 'Lyric languages', cluster: 'Live & worship', summary: () => 'Translations · phonetic lines', render(container) { const p = container.ownerDocument.createElement('p'); p.textContent = 'In the lyrics editor, write “Primary lyric / Translation” in one timed cue. Add “!pinyin: pronunciation” immediately below it. Both secondary lines follow the primary timestamp and appear smaller in Service, stage lyrics, Presenter and OBS output. Shift+Enter still creates a tight line break within one cue.'; container.append(p); } }); }
+  const api = { html, register }; if (typeof module !== 'undefined') module.exports = api; else root.LyricsDisplay = api;
+})(typeof window !== 'undefined' ? window : globalThis);

frontend/lyrics-display.test.js

@@ -0,0 +1,2 @@
+const { test } = require('node:test'), assert = require('node:assert/strict'); const { html } = require('./lyrics-display');
+test('primary and muted secondary lyric markup escape all content', () => { const result = html({ text:'<主>', secondary:'Grace & mercy', phonetic:'"zhǔ"' }); assert.match(result,/lyric-primary">&lt;主&gt;/); assert.match(result,/lyric-secondary">Grace &amp; mercy/); assert.match(result,/lyric-phonetic">&quot;zhǔ&quot;/); assert.doesNotMatch(result,/<主>/); });

frontend/lyrics-window.js

@@ -0,0 +1,40 @@
+/* Floating synced lyrics; opt-in and feature detected. */
+(function(root) {
+  'use strict';
+  function support(environment) { return environment.documentPiP ? 'document' : environment.canvas && environment.videoPiP ? 'video' : null; }
+  function wrap(text, measure, width) { const result = []; for (const paragraph of String(text || '').split('\n')) { let line = ''; for (const word of paragraph.split(/\s+/)) { const next = line ? `${line} ${word}` : word; if (line && measure(next) > width) { result.push(line); line = word; } else line = next; } result.push(line); } return result; }
+  let pipWindow = null, cleanup = () => {}, adapter;
+  const mode = () => support({ documentPiP: !!root.documentPictureInPicture?.requestWindow, canvas: !!root.HTMLCanvasElement?.prototype.captureStream, videoPiP: root.document?.pictureInPictureEnabled && !!root.HTMLVideoElement?.prototype.requestPictureInPicture });
+  async function open() {
+    if (pipWindow || root.document.pictureInPictureElement?.dataset.lyricsPip) { cleanup(); return; }
+    if (!mode()) return;
+    try {
+      adapter.prepare();
+      if (mode() === 'document') {
+        pipWindow = await root.documentPictureInPicture.requestWindow({ width: 420, height: 500 });
+        const doc = pipWindow.document; doc.documentElement.dataset.layout = root.document.documentElement.dataset.layout; doc.documentElement.dataset.theme = root.document.documentElement.dataset.theme;
+        for (const link of root.document.querySelectorAll('link[rel="stylesheet"]')) { const copy = doc.createElement('link'); copy.rel = 'stylesheet'; copy.href = link.href; doc.head.append(copy); }
+        const style = doc.createElement('style'); style.textContent = 'body{margin:0;background:var(--bg,#151719);color:var(--text,#fff);display:flex;flex-direction:column;height:100vh;overflow:hidden}.lyrics-floating-view{position:relative!important;inset:auto!important;flex:1;min-height:0;display:flex!important;flex-direction:column!important;width:100%!important}.lyrics-floating-view .sl-list{flex:1;min-height:0;height:auto!important}.lyrics-floating-controls{display:flex;gap:8px;padding:12px}.lyrics-floating-controls button{flex:1;min-height:48px;background:var(--bg-2,#25292d);color:inherit;border:1px solid var(--line,#555);border-radius:8px}'; doc.head.append(style);
+        const view = adapter.view(), marker = root.document.createComment('floating lyrics'); view.before(marker); view.classList.add('lyrics-floating-view'); doc.body.append(view);
+        const controls = doc.createElement('div'); controls.className = 'lyrics-floating-controls';
+        for (const [label, action] of [['Play / Pause', adapter.toggle], ['Next', adapter.next]]) { const b = doc.createElement('button'); b.type = 'button'; b.textContent = label; b.onclick = action; controls.append(b); } doc.body.append(controls);
+        const win = pipWindow; let restored = false;
+        cleanup = () => { if (restored) return; restored = true; marker.replaceWith(view); view.classList.remove('lyrics-floating-view'); pipWindow = null; adapter.refresh(); if (!win.closed) win.close(); };
+        win.addEventListener('pagehide', cleanup, { once: true }); win.addEventListener('resize', adapter.refresh); adapter.refresh();
+      } else {
+        const canvas = root.document.createElement('canvas'); canvas.width = 840; canvas.height = 500; const ctx = canvas.getContext('2d');
+        const draw = () => { ctx.fillStyle = '#141619'; ctx.fillRect(0, 0, canvas.width, canvas.height); ctx.fillStyle = '#fff'; ctx.font = '32px system-ui'; ctx.textAlign = 'center'; const lines = wrap(adapter.line(), t => ctx.measureText(t).width, 760); lines.slice(0, 8).forEach((line, i) => ctx.fillText(line, 420, 250 + (i - (Math.min(lines.length, 8) - 1) / 2) * 40)); };
+        draw(); const stream = canvas.captureStream(10), video = root.document.createElement('video'); video.dataset.lyricsPip = '1'; video.muted = true; video.playsInline = true; video.srcObject = stream; video.style.cssText = 'position:fixed;width:1px;height:1px;opacity:0;pointer-events:none'; root.document.body.append(video);
+        const timer = setInterval(draw, 100); let closed = false;
+        cleanup = () => { if (closed) return; closed = true; clearInterval(timer); stream.getTracks().forEach(t => t.stop()); video.srcObject = null; video.remove(); if (root.document.pictureInPictureElement === video) root.document.exitPictureInPicture().catch(() => {}); };
+        video.addEventListener('leavepictureinpicture', cleanup, { once: true }); await video.play(); await video.requestPictureInPicture();
+      }
+    } catch (error) { cleanup(); adapter.toast(`Floating lyrics: ${error.message}`); }
+  }
+  function configure(options) {
+    adapter = options; const supported = !!mode();
+    for (const id of ['stageLyricsAuto', 'serviceAutoscrollBtn', 'pipBtn']) { const anchor = root.document.getElementById(id); if (!anchor || !supported) continue; const button = root.document.getElementById('floating-'+id) || root.document.createElement('button'); button.id='floating-'+id; button.type = 'button'; button.className = 'np-btn'; button.textContent = '⧉ Lyrics'; button.title = 'Open floating lyrics'; button.setAttribute('aria-label', 'Open floating lyrics window'); button.onclick = open; if(!button.isConnected)anchor.after(button); }
+    root.SettingsSections.register({ id: 'floating-lyrics', title: 'Floating lyrics', cluster: 'Live & worship', summary: () => mode() === 'document' ? 'Interactive window available' : mode() ? 'Lyric video PiP available' : 'Not supported on this browser', render(container) { const p = container.ownerDocument.createElement('p'); p.textContent = mode() === 'document' ? 'Open synced lyrics with seeking, Play/Pause and Next in an always-on-top window.' : mode() ? 'This browser supports a lyric-video window. Playback controls remain in the player.' : 'Floating lyrics are not supported on this browser.'; container.append(p); if (supported) { const b = container.ownerDocument.createElement('button'); b.type = 'button'; b.className = 'settings-back'; b.textContent = 'Open floating lyrics'; b.onclick = open; container.append(b); } } });
+  }
+  const api = { configure, support, wrap, element: id => pipWindow?.document.getElementById(id) || null }; if (typeof module !== 'undefined') module.exports = api; else root.LyricsWindow = api;
+})(typeof window !== 'undefined' ? window : globalThis);

frontend/lyrics-window.test.js

@@ -0,0 +1,4 @@
+const { test } = require('node:test'), assert = require('node:assert/strict');
+const { support, wrap } = require('./lyrics-window');
+test('floating lyrics prefer document PiP, fall back only when capture and video PiP work', () => { assert.equal(support({ documentPiP: true }), 'document'); assert.equal(support({ canvas: true, videoPiP: true }), 'video'); assert.equal(support({ canvas: true }), null); });
+test('canvas lyric wrapping preserves cue line breaks', () => { assert.deepEqual(wrap('Because You are God\nYou can do anything', t => t.length, 12), ['Because You', 'are God', 'You can do', 'anything']); });

frontend/manifest.webmanifest

@@ -8,7 +8,10 @@
   "scope": "/",
   "theme_color": "#1a1311",
   "background_color": "#1a1311",
-  "categories": ["music", "entertainment"],
+  "categories": [
+    "music",
+    "entertainment"
+  ],
   "icons": [
     {
       "src": "/icons/icon-192.png",
@@ -29,13 +32,135 @@
       "name": "Search",
       "short_name": "Search",
       "url": "/?view=search",
-      "description": "Search YouTube"
+      "description": "Search YouTube",
+      "icons": [
+        {
+          "src": "/icons/icon-192.png",
+          "sizes": "192x192",
+          "type": "image/png"
+        }
+      ]
+    },
+    {
+      "name": "Queue",
+      "short_name": "Queue",
+      "url": "/?view=queue",
+      "description": "What plays next",
+      "icons": [
+        {
+          "src": "/icons/icon-192.png",
+          "sizes": "192x192",
+          "type": "image/png"
+        }
+      ]
+    },
+    {
+      "name": "Saved",
+      "short_name": "Saved",
+      "url": "/?view=saved",
+      "description": "Videos saved for offline",
+      "icons": [
+        {
+          "src": "/icons/icon-192.png",
+          "sizes": "192x192",
+          "type": "image/png"
+        }
+      ]
+    },
+    {
+      "name": "Downloads",
+      "short_name": "Downloads",
+      "url": "/?view=downloads",
+      "description": "Saves in progress and paused",
+      "icons": [
+        {
+          "src": "/icons/icon-192.png",
+          "sizes": "192x192",
+          "type": "image/png"
+        }
+      ]
     },
     {
       "name": "History",
       "short_name": "History",
       "url": "/?view=history",
-      "description": "Recently watched videos"
+      "description": "Recently watched videos",
+      "icons": [
+        {
+          "src": "/icons/icon-192.png",
+          "sizes": "192x192",
+          "type": "image/png"
+        }
+      ]
+    },
+    {
+      "name": "Library",
+      "short_name": "Library",
+      "url": "/?view=library",
+      "description": "Your playlists",
+      "icons": [
+        {
+          "src": "/icons/icon-192.png",
+          "sizes": "192x192",
+          "type": "image/png"
+        }
+      ]
+    },
+    {
+      "name": "Lyrics & notes",
+      "short_name": "Notes",
+      "url": "/?view=notes",
+      "description": "Lyrics, chapters and notes",
+      "icons": [
+        {
+          "src": "/icons/icon-192.png",
+          "sizes": "192x192",
+          "type": "image/png"
+        }
+      ]
+    },
+    {
+      "name": "Settings",
+      "short_name": "Settings",
+      "url": "/?view=settings",
+      "description": "App settings",
+      "icons": [
+        {
+          "src": "/icons/icon-192.png",
+          "sizes": "192x192",
+          "type": "image/png"
+        }
+      ]
     }
-  ]
+  ],
+  "share_target": {
+    "action": "/share-target",
+    "method": "POST",
+    "enctype": "multipart/form-data",
+    "params": {
+      "title": "title",
+      "text": "text",
+      "url": "url",
+      "files": [
+        {
+          "name": "media",
+          "accept": [
+            "audio/*",
+            "video/*",
+            ".mp3",
+            ".m4a",
+            ".aac",
+            ".wav",
+            ".flac",
+            ".ogg",
+            ".opus",
+            ".mp4",
+            ".mov",
+            ".webm",
+            ".mkv"
+          ]
+        }
+      ]
+    }
+  }
 }

frontend/midi.js

@@ -0,0 +1,37 @@
+/* MIDI pedal learning. No MIDI access until explicitly enabled. */
+(function(root) {
+  'use strict';
+  const actions = { toggle: 'Play / Pause', next: 'Next in setlist', repeat: 'Repeat current section', loop: 'Set / toggle A–B loop', panic: 'Panic — fade to silence' };
+  function decode(data) { if (!data || data.length < 3) return null; const type = data[0] & 240, channel = data[0] & 15; if (![128,144,176].includes(type)) return null; return { key: `${type === 176 ? 'cc' : 'note'}:${channel}:${data[1]}`, down: type === 176 ? data[2] >= 64 : type === 144 && data[2] > 0 }; }
+  function createGate() { const held = new Set(); return { accept(port, message) { const key = `${port}:${message.key}`; const was = held.has(key); if (message.down) held.add(key); else held.delete(key); return message.down && !was; }, reset() { held.clear(); } }; }
+  let adapter, access, learning = '', status = '', panelRefresh = () => {}, panicTimer;
+  const gate = createGate();
+  function receive(event) {
+    if (!adapter.settings().midiEnabled) return;
+    const message = decode(event.data); if (!message || !gate.accept(event.target?.id || '', message)) return;
+    const settings = adapter.settings();
+    if (learning) { const mappings = { ...(settings.midiMappings || {}) }; for (const [action, key] of Object.entries(mappings)) if (key === message.key) delete mappings[action]; mappings[learning] = message.key; settings.midiMappings = mappings; learning = ''; adapter.persist(); status = 'Mapping saved'; panelRefresh(); return; }
+    const action = Object.keys(actions).find(action => settings.midiMappings?.[action] === message.key); if (action) adapter.action(action);
+  }
+  function attach() { gate.reset(); for (const input of access.inputs.values()) input.onmidimessage = input.state === 'disconnected' ? null : receive; status = `${[...access.inputs.values()].filter(p => p.state !== 'disconnected').length} MIDI input(s) connected`; panelRefresh(); }
+  async function enable(on) {
+    adapter.settings().midiEnabled = on; adapter.persist(); learning = ''; gate.reset();
+    if (!on) { if (access) for (const input of access.inputs.values()) input.onmidimessage = null; status = 'MIDI is off'; panelRefresh(); return; }
+    try { access ||= await root.navigator.requestMIDIAccess({ sysex: false }); access.onstatechange = attach; attach(); }
+    catch (error) { adapter.settings().midiEnabled = false; adapter.persist(); status = `MIDI access unavailable: ${error.message}`; panelRefresh(); }
+  }
+  function fade({ volume, setVolume, pause, restore }) { clearInterval(panicTimer); const start = Date.now(); panicTimer = setInterval(() => { const fraction = Math.max(0, 1 - (Date.now() - start) / 1000); setVolume(volume * fraction); if (!fraction) { clearInterval(panicTimer); pause(); restore(); } }, 25); }
+  function configure(options) {
+    adapter = options;
+    root.SettingsSections.register({ id: 'midi', title: 'MIDI pedalboard', cluster: 'Live & worship', summary: () => adapter.settings().midiEnabled ? 'On · pedal mappings' : 'Off', render(container) {
+      const doc = container.ownerDocument;
+      if (!root.navigator.requestMIDIAccess) { const p = doc.createElement('p'); p.textContent = 'Web MIDI is unavailable in this browser. iPhone and iPad browsers do not support Web MIDI.'; container.append(p); return; }
+      const label = doc.createElement('label'); label.className = 'set-row'; label.textContent = 'Enable MIDI pedalboard'; const toggle = doc.createElement('input'); toggle.type = 'checkbox'; toggle.checked = !!adapter.settings().midiEnabled; toggle.onchange = () => enable(toggle.checked); label.append(toggle);
+      const info = doc.createElement('p'); info.setAttribute('role', 'status'); const rows = doc.createElement('div'); container.append(label, info, rows);
+      const paint = () => { toggle.checked = !!adapter.settings().midiEnabled; info.textContent = learning ? `Press the pedal for ${actions[learning]}` : status || 'Enable MIDI to connect a pedalboard.'; rows.replaceChildren(); for (const [action, title] of Object.entries(actions)) { const row = doc.createElement('div'); row.className = 'download-job'; const text = doc.createElement('b'); text.textContent = `${title} · ${adapter.settings().midiMappings?.[action] || 'Unassigned'}`; const buttons = doc.createElement('div'); for (const name of ['Learn', 'Clear']) { const b = doc.createElement('button'); b.type = 'button'; b.textContent = name; b.disabled = name === 'Learn' && !adapter.settings().midiEnabled; b.setAttribute('aria-label', `${name} MIDI ${title}`); b.onclick = () => { if (name === 'Learn') { learning = learning === action ? '' : action; gate.reset(); } else { delete adapter.settings().midiMappings?.[action]; adapter.persist(); } paint(); }; buttons.append(b); } row.append(text, buttons); rows.append(row); } };
+      panelRefresh = paint; paint(); return () => { if (panelRefresh === paint) panelRefresh = () => {}; learning = ''; };
+    } });
+    if (adapter.settings().midiEnabled && root.navigator.requestMIDIAccess) enable(true);
+  }
+  const api = { configure, decode, createGate, fade }; if (typeof module !== 'undefined') module.exports = api; else root.MidiPedals = api;
+})(typeof window !== 'undefined' ? window : globalThis);

frontend/midi.test.js

@@ -0,0 +1,4 @@
+const { test } = require('node:test'), assert = require('node:assert/strict');
+const { decode, createGate } = require('./midi');
+test('MIDI note-off and zero velocity release notes; CC uses switch threshold', () => { assert.deepEqual(decode([0x92, 60, 80]), { key: 'note:2:60', down: true }); assert.equal(decode([0x82, 60, 64]).down, false); assert.equal(decode([0x92, 60, 0]).down, false); assert.equal(decode([0xb0, 64, 63]).down, false); assert.equal(decode([0xb0, 64, 64]).down, true); assert.equal(decode([0xf8]), null); });
+test('held pedals trigger once, releases re-arm, different devices remain independent', () => { const gate = createGate(), down = decode([0xb0, 64, 127]), up = decode([0xb0, 64, 0]); assert.equal(gate.accept('one', down), true); assert.equal(gate.accept('one', down), false); assert.equal(gate.accept('two', down), true); gate.accept('one', up); assert.equal(gate.accept('one', down), true); gate.reset(); assert.equal(gate.accept('two', down), true); });

frontend/offline-pages.css

@@ -0,0 +1,33 @@
+/* Downloads uses the same quiet row rhythm as the surrounding library. */
+.dl-empty-state { max-width:440px; margin:24px auto; padding:24px 16px; }
+.dl-empty-state .dl-empty-icon-wrapper { width:auto; height:auto; border:0; border-radius:0; background:none; color:var(--text-2); margin-bottom:16px; box-shadow:none; }
+.dl-empty-svg { width:32px; height:32px; }
+.dl-empty-state .empty-title { font-size:20px; color:var(--text); }
+.dl-empty-state .empty-desc, .dl-how-to-save, .dl-storage-note { color:var(--text-2); font-size:14px; line-height:1.5; }
+.dl-how-to-save { margin:8px 0 16px; }
+.dl-storage-note { margin-bottom:16px; font-variant-numeric:tabular-nums; }
+.dl-saved-cta, .dl-saved-link, .dl-row .dl-act { min-height:44px; min-width:44px; padding:0 14px; border:1px solid var(--line); border-radius:var(--radius-sm,8px); background:var(--bg-2); color:var(--text); font:inherit; cursor:pointer; }
+.dl-saved-cta:hover, .dl-saved-link:hover, .dl-row .dl-act:hover { background:var(--bg-3); }
+.dl-saved-cta:focus-visible, .dl-saved-link:focus-visible, .dl-row .dl-act:focus-visible { outline:2px solid var(--accent); outline-offset:3px; }
+.dl-summary { display:flex; align-items:center; justify-content:space-between; gap:12px; padding:8px 0 16px; font-size:14px; color:var(--text-2); }
+.dl-group { margin-bottom:20px; }
+.dl-group-title { font-size:14px; font-weight:600; color:var(--text); margin:12px 0 6px; }
+html[data-layout] .card.dl-row { display:grid; grid-template-columns:72px minmax(0,1fr); gap:12px; padding:12px 8px; }
+html[data-layout] .dl-row .thumb { grid-column:1; grid-row:1; width:72px; align-self:start; margin-top:3px; }
+html[data-layout] .dl-row .card-info { grid-column:2; grid-row:1; min-width:0; }
+.dl-row .card-title { overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+.dl-row .card-channel { overflow-wrap:anywhere; color:var(--text-2); }
+.dl-row .dl-actions { display:flex; flex-wrap:wrap; gap:8px; margin-top:8px; }
+.dl-row .dl-act.danger { color:var(--accent); background:transparent; }
+.dl-row .dl-act:disabled { opacity:.5; cursor:wait; }
+@media(min-width:900px) { html[data-layout] .card.dl-row { grid-template-columns:88px minmax(0,1fr); } html[data-layout] .dl-row .thumb { width:88px; } }
+
+/* Save failures remain readable; raw extractor output is opt-in, never HTML. */
+.dl-failed .card-channel { white-space:normal; line-height:1.5; }
+.download-error-details { min-width:0; color:var(--text-2); font:12px/1.5 var(--ui); }
+.download-error-details summary { min-height:44px; padding:12px 0; cursor:pointer; }
+.download-error-details summary:focus-visible { outline:2px solid var(--accent); outline-offset:2px; border-radius:4px; }
+.download-error-details pre { white-space:pre-wrap; overflow-wrap:anywhere; max-height:240px; overflow:auto; margin:0 0 8px; font:12px/1.5 var(--mono); }
+.download-job { grid-template-columns:minmax(0,1fr); }
+.download-job > div { flex-wrap:wrap; }
+.download-job progress { min-width:0; }

frontend/opfs-worker.js

@@ -34,8 +34,7 @@
 
 // Incremental SHA-256 (frontend/sha256.js): the file is hashed while it is
 // written, so the device knows its content id without re-reading the file.
-try { importScripts('/sha256.js'); } catch { /* hashing unavailable — save still works */ }
-importScripts('/resume-core.js');
+
 
 async function getVideosDir() {
   const root = await navigator.storage.getDirectory();
@@ -185,7 +184,33 @@ async function resumableSave(videoId, url, target) {
   self.postMessage({ type: 'done', ext: target.ext || 'mp4', sha256, expectedSha, size: target.size });
 }
 
+// Write a whole file into an OPFS sub-directory (sync access handle: works on
+// iOS Safari, where main-thread createWritable is missing). Used for the
+// iPhone EQ/levelling renders (EqRender in app.js).
+async function writeFile(dirName, name, buffer) {
+  const root = await navigator.storage.getDirectory();
+  const dir = await root.getDirectoryHandle(dirName, { create: true });
+  const h = await dir.getFileHandle(name, { create: true });
+  const a = await h.createSyncAccessHandle();
+  try {
+    const bytes = new Uint8Array(buffer);
+    a.truncate(0);
+    a.write(bytes, { at: 0 });
+    a.truncate(bytes.byteLength);
+    a.flush();
+  } finally { a.close(); }
+}
+
 self.onmessage = async (e) => {
+  self.__ASSET_URLS__=e.data?.assetUrls || {};
+  try { if(!self.Sha256)importScripts(self.__ASSET_URLS__.sha256 || '/sha256.js'); } catch { /* hashing unavailable — legacy save still works */ }
+  try { if(!self.ResumeCore)importScripts(self.__ASSET_URLS__.resume || '/resume-core.js'); }
+  catch(error) { self.postMessage({type:'error',error:error.message}); return; }
+  if (e.data && e.data.op === 'write') {
+    try { await writeFile(e.data.dir, e.data.name, e.data.buffer); self.postMessage({ type: 'written' }); }
+    catch (err) { self.postMessage({ type: 'error', error: err && err.message ? err.message : String(err) }); }
+    return;
+  }
   const { videoId, url, resumable } = e.data || {};
 
   if (

frontend/opfs.js

@@ -151,15 +151,21 @@
       return new Promise((resolve) => {
         let worker;
         try {
-          worker = new Worker('/opfs-worker.js');
+          worker = window.Lazy ? window.Lazy.worker('/opfs-worker.js') : new Worker('/opfs-worker.js');
         } catch {
           resolve({ ok: false, fallback: true });
           return;
         }
+        let settled = false;
+        const abort = () => finish({ ok: false, paused: true });
         const finish = (result) => {
+          if (settled) return; settled = true;
+          opts.signal?.removeEventListener('abort', abort);
           worker.terminate();
           resolve(result);
         };
+        if (opts.signal?.aborted) { abort(); return; }
+        opts.signal?.addEventListener('abort', abort, { once: true });
         worker.onmessage = (e) => {
           const m = e.data || {};
           if (m.type === 'done')             finish({ ok: true, sha256: m.sha256 || null, expectedSha: m.expectedSha || null, size: m.size || 0 });

frontend/p2p-client.js

@@ -72,7 +72,7 @@
   function hashInWorker(name) {
     return new Promise((resolve) => {
       let w;
-      try { w = new Worker('/hash-worker.js'); } catch { resolve(null); return; }
+      try { w = window.Lazy ? window.Lazy.worker('/hash-worker.js') : new Worker('/hash-worker.js'); } catch { resolve(null); return; }
       w.onmessage = (e) => { w.terminate(); resolve(e.data && e.data.ok ? e.data : null); };
       w.onerror = () => { w.terminate(); resolve(null); };
       w.postMessage({ name });
@@ -216,7 +216,7 @@
     ws = sock;
     let ping = null;
     sock.onopen = () => {
-      sock.send(JSON.stringify({ type: 'auth', device: d.deviceId, secret: d.secret }));
+      sock.send(JSON.stringify({ type: 'auth', device: d.deviceId, secret: d.secret, profile: hooks.getProfile(), profileSecret: hooks.getProfileSecret?.() || '' }));
       // The server drops sockets idle for 120 s (server.js websocketHandler).
       ping = setInterval(() => { try { sock.send('{"type":"ping"}'); } catch { /* closing */ } }, 50_000);
     };
@@ -285,7 +285,7 @@
   // and only for the exact cid this device holds.
   let restoring = false;
   onMessage('upload-request', async (m) => {
-    if (restoring || hooks.getSettings().p2pShare === false) return;
+    if (restoring || hooks.getSettings().p2pShare === false || hooks.getSettings().directTransfer !== false) return;
     const rec = window.DeviceDB ? await window.DeviceDB.getFile(m.videoId) : null;
     if (!rec || rec.cid !== m.cid) return;
     restoring = true;
@@ -296,7 +296,7 @@
   function start(h) {
     hooks = { ...hooks, ...(h || {}) };
     const idle = window.requestIdleCallback || ((fn) => setTimeout(fn, 1));
-    setTimeout(() => idle(() => sync()), 8000);
+    setTimeout(() => idle(() => sync()), h?.initialDelay ?? 8000);
     document.addEventListener('visibilitychange', () => {
       if (document.visibilityState === 'visible' && Date.now() - lastSync > RESYNC_MS) sync();
     });
@@ -304,6 +304,7 @@
 
   window.P2PClient = {
     start, changed, sync, device, authHeaders, config, contribute, unknownVideos,
+    send: m => { if (!ws || ws.readyState !== 1) return false; ws.send(JSON.stringify(m)); return true; },
     onMessage, signal, peer: () => myPeer, isConnected: () => !!(ws && ws.readyState === 1 && myPeer),
   };
 }());