catacomb/HANDOFF.md

# Session handoff — Catacomb

> Working notes for continuing this work in another session/agent (e.g. Codex).
> Written 2026-06-19. Delete or update freely; this is not a tracked spec.

## TL;DR — where things are

- Project: `catacomb` — one Rust binary that is **both** an egui desktop GUI
  and an axum web server wrapping `yt-dlp`. See [CLAUDE.md](CLAUDE.md) for the
  authoritative architecture; [ROADMAP.md](ROADMAP.md) for the plan.
- Recent work has been almost entirely on the **web UI** (`src/web_ui/index.html`,
  a single `include_str!`-baked SPA) plus a few `web.rs`/`database.rs` changes.
- Branch: `main`. Last commit: `2f95e7f` (unified cinematic video player).
- A dev web server is usually running on **:8081** against the user's real
  library. It keeps getting reaped between turns — just restart it (see below).

## How to build / run / test

```bash
cargo build --release                 # ~1.5 min (opt-level=3 + thin LTO)
cargo test --release                  # 128 unit + 11 integration (tests/api.rs); no network
./target/release/catacomb --web 8081  # headless web server (what the user uses)
./target/release/catacomb             # desktop GUI (default)
```

### CRITICAL gotchas (learned this session)

1. **The web SPA is one big embedded file** — `src/web_ui/index.html`, baked in
   at compile time via `include_str!`. **Editing it requires a `cargo build`** to
   take effect. A JS syntax error there will NOT be caught by `cargo build` (the
   HTML is just a string), so after every edit:
   ```bash
   awk '/<script>/{f=1;next}/<\/script>/{f=0}f' src/web_ui/index.html > /tmp/spa.js && node --check /tmp/spa.js
   ```
2. **DB location**: the server opens the DB at `channels_root.join("catacomb.db")`
   (`web.rs` ~L3127), i.e. **`<backup.directory>/catacomb.db`**. For this user
   that's `/mnt/InannaBeloved/youtube-backup/catacomb.db` (~64 MB, real data —
   do NOT clobber). `config.toml` is read from the **process CWD**. A stray
   0-byte `catacomb.db` may sit in the repo dir; it is unused — ignore it.
3. **Offline-first**: this is a self-hosted, possibly-no-internet archiver.
   **Never load fonts/CSS/JS from a CDN.** UI fonts are embedded as base64 woff2
   (SIL OFL) directly in the `<style>` block. Keep it that way.
4. **All 10 themes** are driven by 7 CSS variables (`--bg --panel --card --accent
   --text --muted --border`) set per `.theme-*` class. Any new UI must use those
   vars (and the design-layer tokens below) so every theme inherits it.
5. **Background server reaping**: in the sandbox, `run_in_background` servers get
   killed between turns and shell `&`/`nohup` is unreliable. Just relaunch
   `./target/release/catacomb --web 8081` each time you need it up. `pkill -f`
   first to avoid a port clash.
6. **Verifying UI visually without a browser driver** (no puppeteer/playwright):
   extract the relevant CSS/JS from `index.html` into a `/tmp/*.html` harness with
   a mock payload and screenshot with headless chromium:
   ```bash
   chromium --headless=new --no-sandbox --disable-gpu --hide-scrollbars \
     --window-size=1100,1300 --virtual-time-budget=3000 \
     --screenshot=/tmp/out.png "file:///tmp/harness.html"
   ```
   Note: `--virtual-time-budget` can capture entry animations mid-flight; add a
   "settle" override (disable transitions, force final state) for a clean shot.

## Settings flow (the easy thing to get wrong)

Adding a setting touches **five** places (grep an existing one like
`dedup_enabled` or `sponsorblock_mode` end-to-end first):
1. `config.rs` — field + `Default` + `default_with_dir()`.
2. `download_options.rs` — `Option<…>` per-channel override (None = use global).
3. `downloader.rs` — resolver merging global+override + a `pub` field on `Downloader`.
4. Both UIs: `app.rs` (egui Settings + channel-options dialog) AND
   `web_ui/index.html` (Settings modal + channel dialog) AND `web.rs`
   `SettingsPayload` (GET reads config, POST writes config + pushes to live `Downloader`).
5. Seed the `Downloader` field at construction AND on settings-save, in BOTH
   `app.rs` and `web.rs`.

## What this session shipped (committed)

Newest first (all on `main`):

- `2f95e7f` **Unified cinematic video player.** Replaced native `<video controls>`
  (direct `/files/` playback) with ONE custom player for both direct + transcode.
  Custom scrubber (played/buffered/chapter-ticks/hover tooltip, drag-to-seek via
  pointer events, commits on release), playback-speed popover (0.5–2×), persistent
  volume/speed/captions (localStorage `plPrefs`), CC toggle, PiP, fullscreen,
  auto-hiding controls + center play/pause flash, expanded keyboard
  (space/k j/l ←→ ↑↓ m c p f `<` `>` 0–9). All seeking routes through the
  existing `playerSeek`/`effTime` so the transcode reload-at-offset path is intact.
  CSS prefix `.pl-*`; JS around `playVideo`/`updateVctrl`/`plBindScrubber`.
- `816da05` **Persist login sessions in SQLite.** New `sessions(token, issued_at)`
  table; in-memory map switched `Instant`→`u64` unix secs; insert on login, delete
  on logout, clear on password change, rehydrate at startup via `load_sessions()`.
  Fixes "restart logs everyone out". (`database.rs` + `web.rs`.)
- `dd48e89` **api() 401 → reload to login** instead of a cryptic "error" toast.
- `615c088` **Maintenance modal → "diagnostics console"** (CSS prefix `.mx-*`):
  pulsing health verdict + status tiles + instrument-panel sections. Presentation
  only; all handler ids/classes (`dup-chk` `sim-chk` `at-chk` `dedup-area`
  `autotag-area`, polling) untouched.
- `6f61821` **Stats modal → "observatory" dashboard** (CSS prefix `.sx-*`):
  count-up metric cards, self-drawing SVG area chart (Catmull-Rom), growing
  histogram, ranked leaderboard with Size/Count toggle.
- `c8cb700` **"Cinematheque" reskin**: embedded Instrument Serif + Hanken Grotesk
  (base64 OFL), accent aurora + film-grain atmosphere, cinematic card hover,
  recording-dot wordmark. Design-layer CSS appended after the functional rules so
  it overrides by source order; everything flows through the theme variables.
- `983864f` **macOS osxcross packaging path** (`scripts/package.sh mac` → `.app`
  zip; local-only, not in CI — needs osxcross + SDK).
- `207013e` **Windows shippable**: cross-compiled `.zip` via mingw + console
  reattach fix (`attach_windows_console` in `main.rs`) + Windows build in the
  Forgejo release CI.
- `8b25787` **Library sorting**: download-date sort (file mtime) + grouped sort
  options, both UIs.
- earlier: `015d037` scan leaves one core free; `5ffdb17` download-modal
  diff-aware repaint + Retry-all; `9ed6293` download cancel/retry/queue + dedup
  off-switch.

### Design-layer conventions (web UI)
- CSS is appended near the end of the `<style>` block, AFTER the functional
  rules, so equal-specificity overrides win by source order. Prefixes:
  `.sx-*` = stats observatory, `.mx-*` = maintenance console, `.pl-*` = player.
- Reveal animations gate behind a class added post-layout (e.g. `.sx-go`) so they
  play once per open, not on every re-render. All honor
  `@media (prefers-reduced-motion: reduce)` (a global rule at the end of `<style>`).
- Fonts: `--font-display` (Instrument Serif), `--font-body` (Hanken Grotesk).
  Extra tokens: `--radius`, `--radius-sm`, `--ring`, `--glow`, `--shadow`, `--hair`.

## Uncommitted changes (REVIEW + COMMIT before continuing)

`git status` shows modified-but-uncommitted (mostly docs, made by the user/linter
— do NOT revert, just review and commit):
- Docs/prose: `AGENTS.md`, `CLAUDE.md`, `README.md`, `ROADMAP.md`,
  `SECURITY_AUDIT.md`, `docs/src/{architecture,first-run,installation,packaging}.md`
- Small code touches: `src/database.rs` (~4 lines — schema doc/comment),
  `src/web_ui/index.html` (6/6 — minor).

Run `git diff` to confirm these are intended, then commit them. They look like
documentation catch-up for the session's features.

## Suggested next steps (pick up here)

Highest-leverage, all buildable + verifiable locally:
1. **Login page reskin** — `LOGIN_HTML` in `web.rs` is a plain form and is the one
   surface that still clashes with the cinematheque aesthetic. Small, high impact.
2. **Search overlay** (`openSearch` in the SPA) — could become a command-palette
   experience to match the new players.
3. Commit the pending doc changes (above).

Roadmap "surpass" items still open (see [ROADMAP.md](ROADMAP.md) §3):
- **3.1 macOS binary** — osxcross scaffolding done (`scripts/package.sh mac`);
  needs the toolchain + SDK installed, then verify. Windows already ships.
- **3.2 Android client** (big), **3.8 plugin/scripting hooks** (architectural).
- Phase 4 blue-sky: AI transcript summarisation (FTS transcript index already
  exists), TV-mode layout, multi-user accounts.
- Federation follow-up (3.5): in-UI "add remote" editor (peers are config-only).

## Watch-outs / open questions

- The video player's seek/speed/captions are verified by code-path review +
  static chrome screenshot, NOT live playback (no headless video). Worth a real
  click-through in the app.
- Session persistence: the user's *current* browser cookie predates the
  persistence commit, so they must log in once more; logins after that survive
  restarts. (They may have a download password set or not — it has toggled during
  testing; that's user-driven, not a bug.)
- Don't commit `cookies.txt`, `config.toml`, or `catacomb.db` (all gitignored;
  contain creds / the Argon2 password hash).