ytplayer/docs/improvement-plan.md

# ytplayer — Improvement Plan (2026-09-29)

Grounded in the current tree: `frontend/app.js` 9.8k lines / 30+ module objects,
`styles.css` 4.3k, `server/server.js` 1.9k with ~30 routes, 11 unit/server test
files (~110 cases), 5 Playwright specs, **no CI**, no lint/format config.
The feature set is already broad (lyrics, party, remote, presenter, stats,
transitions, uploads). The biggest returns now come from **hardening and
maintainability**, not more features.

Priority key: **P0** do next · **P1** this quarter · **P2** when there's room.
Effort: S ≤ ½ day · M 1–3 days · L a week+.

---

## Phase 1 — Safety net (P0)

Nothing below is safe to refactor without it; the CLAUDE.md history (update
banner "fixed three times", the thumb-cache opaque trap, the toast-loop tab
crash) shows regressions have repeatedly shipped silently.

| # | Item | Effort | Done when |
|---|------|--------|-----------|
| 1.1 | **GitHub Actions CI**: `node --test frontend/*.test.js`, `cd server && bun run test`, Playwright chromium smoke specs. Run on every push/PR. | S | Red CI blocks a merge; badge in README. |
| 1.2 | Fix root `npm test` — it runs `node --test frontend/`, which CLAUDE.md says fails on Node 22. Change to `node --test frontend/*.test.js` and add `test:server`, `test:e2e`, `test:all`. | S | `npm run test:all` green locally and in CI. |
| 1.3 | **Lint + format**: Biome (one binary, zero config sprawl) with `no-unused-vars`, `no-undef`, `useAwait`, `noFallthrough`. Start with `--diagnostic-level=error` so it lands without a mass reformat commit. | S | CI step; existing code passes. |
| 1.4 | **Regression tests for the known fragile paths**: (a) `/sw.js` BUILD_TAG regex injection survives a bumped fallback literal; (b) `maybeShowUpdateBanner` single-rule behaviour; (c) thumb cache accepts CORS-mode responses (status 0 opaque trap); (d) `toast()` cap with deferred removal terminates. | M | Each has a test that fails on the historical bug. |
| 1.5 | **Server route contract tests** for `/api/streams`, `/api/search`, `/api/user/sync`, `/api/profile/*` against a stubbed yt-dlp binary (a script that prints fixture JSON). Guards the "JSON shapes mirror the Tauri bridge" rule. | M | Shape snapshot per endpoint. |

## Phase 2 — Security & abuse hardening (P0/P1)

| # | Item | Pri | Effort | Notes |
|---|------|-----|--------|-------|
| 2.1 | **Rate-limit expensive routes.** `/api/search`, `/api/channel`, `/api/streams`, `/api/playlist/expand`, `/api/download` each spawn yt-dlp/ffmpeg with no per-IP limit — a trivial loop can exhaust CPU and get the homelab IP bot-gated by YouTube (which already degrades saves to 360p, see BACKLOG). Token bucket per first `X-Forwarded-For` hop, plus a global concurrency cap on yt-dlp spawns with a small queue. | P0 | M | Reuse the IP logic already written for `REMOTE_SAME_NETWORK`. |
| 2.2 | **Profile name enumeration.** Names are the only credential and may be 3 chars (`PROFILE_NAME_RE`), so `/api/profile/load` + `/api/playlist/inbox` are brute-forceable and nothing throttles them. Minimum: strict per-IP limit on 404s from those routes + raise the minimum for *new* profiles to ~10 chars or suggest a generated passphrase. Optional later: an opt-in per-profile PIN (hash stored) that `save` requires. | P0 | S–M | Keep "name = passkey" UX for existing profiles. |
| 2.3 | **Security headers** via `hono/secure-headers`: CSP (self + ytimg/ggpht images + the listed CDNs), `X-Content-Type-Options`, `Referrer-Policy`, `frame-ancestors 'self'`. Start CSP in `Report-Only` for a week — app.js builds a lot of `innerHTML` (124 sites). | P1 | M | Admin page gets a stricter policy. |
| 2.4 | **innerHTML audit**: lint rule / grep gate that every interpolation into `innerHTML` goes through `escapeHtml` (67 call sites today vs 124 innerHTML writes). Convert the risky ones (titles, channel names, chat, notes, profile names from URLs) to `textContent` or a tiny `html\`\`` tagged template that escapes by default. | P1 | M | Party chat + shared playlists carry attacker-controlled text. |
| 2.5 | Body-size limits on every JSON POST (profile already has `PROFILE_MAX_BYTES`; check `/api/user/sync`, notes, party/remote WS frames). | P1 | S | |
| 2.6 | Finish the **cookies jar** backlog item (mount `YTDLP_COOKIES` via a compose volume + an admin-page "cookies expire in N days" warning) — only if 360p fallback saves are noticed. | P2 | S | Already documented in BACKLOG. |

## Phase 3 — Break up `app.js` (P1)

9.8k lines in one file is the main drag on every change (and on AI-assisted
edits, which have to re-read huge ranges). The modules are already
IIFE-shaped (`Notes`, `Remote`, `Transition`, `Wave`, `Party`, `Presenter`,
`SectionRail`, `EQ`, …), so the split is mechanical.

1. **Native ES modules, no bundler.** `<script type="module" src="app.js">`,
   one file per existing module under `frontend/modules/`. No build step keeps
   the Tauri / zero-native shells and the SW precache simple.
2. **Order of extraction** (lowest coupling first): `RecentSearches`, `EQ`,
   `PiP`, `Gestures`, `External`, `Share`, `StatsTrack`, `Wave`,
   `Transition`, `SectionRail`, `Presenter`, `Remote`, `Party`, `Notes`,
   then `Player` and the render/sidebar core last.
3. Shared state (`data`, `queue`, `queueIndex`, `persist()`, `toast()`,
   `API`) moves to `frontend/modules/state.js` and is imported, not global.
4. **SW precache list** must be generated, not hand-maintained: have the
   server (which already walks `./public` for `BUILD_TAG`) inject the shell
   file list into `/sw.js` alongside the tag. Otherwise a new module file
   missing from `SHELL` breaks offline — the exact class of bug CLAUDE.md
   warns about.
5. Move pure logic out as testable units the way `lyrics-core.js` and
   `stats-core.js` already are: queue/shuffle math, A-B marker resolution
   (per-playlist vs fallback), party clock extrapolation, sync merge.
6. Same treatment for `server/server.js`: split into `routes/search.js`,
   `routes/streams.js`, `routes/profile.js`, `routes/playlist.js`,
   `ytdlp.js` (spawn + `runYtdlpResilient`), mirroring how `notes.js` /
   `uploads.js` already register their routes.

**Done when:** no frontend file > 1.5k lines, no server file > 600, all
tests + e2e green, SW offline check passes (the real-browser procedure in
CLAUDE.md → Testing).

## Phase 4 — Reliability & observability (P1)

| # | Item | Effort |
|---|------|--------|
| 4.1 | **Structured logs** (JSON lines: route, status, ms, videoId, yt-dlp client used, error class) instead of ad-hoc `console.*`. | S |
| 4.2 | **`/api/health`** that actually checks: DB writable, `MEDIA_DIR` free space, yt-dlp version + age, last successful extraction time, queue depth. Point the Docker healthcheck at it (today it pings `/api/version`, which stays green while yt-dlp is broken). | S |
| 4.3 | **yt-dlp staleness**: the image fetches `latest` only at build time, and "a 2-month-old one 403s on every download". Add a nightly in-container self-update (`yt-dlp -U` into the data volume, fall back to the baked binary) or a scheduled rebuild. | S |
| 4.4 | **Client error reporting**: `window.onerror` + `unhandledrejection` + media element `error` events → throttled `POST /api/client-log` (build tag, UA, route). Surfaces the iOS/HEVC/playback failures that currently only show up when a user complains. Visible in `/admin`. | M |
| 4.5 | **DB backups**: notes already get a daily JSON dump; do the same (or a `VACUUM INTO` copy) for `profiles`, `users`, `uploads`. Document a restore drill. | S |
| 4.6 | **Deploy on merge**: a GitHub Action that calls the Dokploy deploy API (key as a repo secret) after CI passes on `main`, then polls `/api/version` for the new `buildTag`. Replaces the manual SSH hop; keep the `deploy-prod` skill as the manual fallback. | M |

## Phase 5 — Performance (P1/P2)

- **First load**: measure with Lighthouse on a throttled mobile profile.
  `app.js` + `styles.css` are ~14k lines parsed on every cold start; after the
  Phase 3 split, lazy-`import()` the rarely used modules (Party, Presenter,
  Remote, EQ, admin-ish editors) on first use.
- **Server search cache** (3 min, just added) → also cache `/api/streams`
  metadata (not the signed URLs) and `/api/channel` briefly.
- **CSS**: split per feature alongside the modules; drop dead selectors
  (run a coverage pass in Chromium DevTools over the main flows).
- **DB**: check indexes for the hot queries (`video_history` has one;
  verify `media_cache.last_access` for LRU, `video_note_revs(video_id, kind)`).
- **Media cache**: expose hit rate in `/api/media/stats` so the 10 GiB budget
  and `MEDIA_AUTO_MAX_SECONDS` can be tuned from data.

## Phase 6 — UX & accessibility (P1/P2)

- **Accessibility pass** (only ~40 `aria-` attributes across index.html +
  styles): labelled icon-only buttons (transport, ↦/⇥/⤨, ⚠ Broken, rail
  icons), focus-visible styles, `prefers-reduced-motion`, keyboard access to
  drag-reorder, live-region announcements for toasts and track changes.
  Add `@axe-core/playwright` to CI on the main screens.
- **Onboarding**: the app now has many power features that are hard to
  discover (service mode, presenter, remote, party, transitions, EQ). One
  "What's new / Tips" sheet tied to the build tag, dismissible.
- **Settings organisation**: group into Playback · Lyrics & service · Sync &
  profile · Offline & storage · Advanced; add search within settings.
- **Offline clarity**: global indicator when offline + which views work,
  and a storage screen showing OPFS vs thumb cache vs quota.
- **Profile security UX** (pairs with 2.2): "Your profile name is your
  password" hint + generate-a-strong-name button.

## Phase 7 — Feature ideas (P2, after 1–4)

Ranked by fit with the worship/service use case:
1. **Set-list planning**: date-stamped service plans (songs + key + notes +
   order), shareable read-only link for the band, one-tap into service mode.
2. **Chord charts** alongside lyrics (ChordPro import, transpose using the
   existing `@ Key G` tag).
3. **Per-song key/tempo playback** (pitch-preserving rate already exists;
   add pitch shift via a Web Audio worklet, desktop only because of iOS).
4. **Presenter themes** (background image/video, font, safe-area margins)
   and a stage/confidence-monitor view showing the next line.
5. **Multi-user admin** (roles instead of one `ADMIN_PASSWORD`).

## Phase 8 — Docs & housekeeping (P2)

- `CLAUDE.md` is excellent but ~400 lines and growing; move per-feature
  deep dives to `docs/architecture/*.md` and keep CLAUDE.md as the index +
  the "never do X" rules.
- README: quickstart, screenshots, env var table (currently only in compose
  comments).
- Retire or clearly quarantine the Tauri/zero-native shells if they're no
  longer shipped — every JSON-shape change currently has to consider them.
- Version: `APP_VERSION` is hard-coded `1.0.0` in three places; derive it
  from one source or drop it in favour of `buildTag`.

---

## Suggested order

1. Week 1: 1.1, 1.2, 1.3, 2.1, 2.2, 4.2, 4.3
2. Week 2: 1.4, 1.5, 2.5, 4.1, 4.4, 4.5
3. Weeks 3–5: Phase 3 split (server first — smaller and better tested),
   with 2.3/2.4 riding along as modules move
4. Then: 4.6 auto-deploy, Phase 5 perf, Phase 6 a11y/UX
5. Features (Phase 7) once CI + the split are in place

Each item is sized to be one commit per CLAUDE.md's commit rules, and most
can be queued with the `plan-queue` skill for step-by-step execution.