From 4fd68ae88e7639ffe4ab7060ab81b0e8a848e90d Mon Sep 17 00:00:00 2001 From: Jonathan Sykes Date: Sun, 16 Aug 2026 08:48:50 +0000 Subject: [PATCH] Document cache layout, offline thumbnails and test invocation --- CLAUDE.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 55 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 1d2e225..dae73e8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -73,6 +73,39 @@ Local DB file: `server/data/ytplayer.db` (gitignored). `BUILD_TAG` is computed f from the `/api/version` poll), it calls `reg.update()`, waits for `installed`, posts SKIP_WAITING, waits for `controllerchange`, then reloads once. +## Cache layout & offline thumbnails +- Three cache families, and the split matters on activate: the **versioned shell + cache** `ytplayer-` is evicted on every deploy, while the **utility + caches** `ytplayer-thumbs` and `ytplayer-fonts` are listed in `UTILITY_CACHES` + and deliberately survive it. Adding a new utility cache means adding it there + too, or it gets wiped on the next deploy. +- **Thumbnails are cache-first, not stale-while-revalidate** — a given thumbnail + URL is immutable, so revalidating just burns a round trip per image per launch. +- **The opaque-response trap (this silently emptied the thumb cache for months).** + An `` to another origin is a **no-cors** request, so `fetch(request)` in the + SW resolves to an **opaque** response with `status === 0` — not 200. The old + guard was `if (r.status === 200) cache.put(...)`, which rejected every single + thumbnail, so `ytplayer-thumbs` was permanently empty and offline showed broken + images (measured on prod: 0 entries after browsing pages full of visible thumbs). + Fix in `thumbnail()`: re-issue the request in `cors` mode — ytimg/ggpht all send + `Access-Control-Allow-Origin: *` — and cache that readable response; an opaque + one is accepted only as a last resort. **Never reintroduce a bare `status === 200` + check on a cross-origin subresource.** +- Thumbnail hosts live in `THUMB_HOSTS`. An unlisted host doesn't error — it just + bypasses the cache and breaks offline, so add mirrors/avatar hosts there. +- The thumb cache is capped at `THUMB_CACHE_MAX` (800, oldest-first via the + insertion-ordered `cache.keys()`). Keep a cap: CacheStorage and the OPFS offline + audio share one origin quota, and opaque entries are padded to ~7 MB each for + quota accounting, so an unbounded thumb cache can evict saved audio. +- App side (`app.js`): `warmThumb()` pulls artwork through the SW when a video is + saved offline, and `warmOfflineThumbs()` runs a bounded launch backfill + (`THUMB_WARM_MAX` = 400, 4 at a time) over cached ids + playlist videos so + libraries saved before this fix repair themselves. Thumbnails only cache when + something requests them — a device needs one online launch to get offline art. +- `staleWhileRevalidate()` (fonts) must not `return cached || networkFetch` bare: + the fetch resolves to `null` offline and `respondWith(null)` throws. It ends + with `|| Response.error()`. + ## Data model quirks - Client state persists in localStorage key **`_ytpdata`** and syncs (debounced 400 ms) to `POST /api/user/sync`, keyed by a browser fingerprint. @@ -84,13 +117,33 @@ Local DB file: `server/data/ytplayer.db` (gitignored). `BUILD_TAG` is computed f by design). Client stores `data.profile = {name, syncedAt}`; sync is last-write-wins — push debounced on every persist(), pull on app launch when the server's `updated_at` is newer than the local `syncedAt`. +- **Profile share links**: `?profile=` is consumed by `adoptProfileFromUrl()` + at boot, before any rendering. It strips the param via `replaceState` (so a + reload can't re-fire it) and confirms first when the device already has + playlists/history or another profile — adopting *replaces* the synced slice. + The name comes off the URL untrusted, hence `escapeHtml()` on it. +- **Empty-home playlist grid**: `renderHomePlaylists()` swaps the branding hero in + `#playerPlaceholder` for the user's playlists (hero is the no-playlists + fallback). It is driven from the tail of `renderSidebar()` — not from + `render()` — so every playlist mutation refreshes both in one place. ## Testing -- Unit: `node --test frontend/` (sw, sw-update, async-guard). +- Unit: **`node --test frontend/*.test.js`** (sw, sw-update, async-guard, video-edit). + The directory form `node --test frontend/` fails on Node 22 with + `Cannot find module .../frontend` — it resolves the dir as a module, not a test + glob. That's the harness, not the tests. - E2E: `npx playwright test` — WebKit iPhone-12 profile against a static serve of `frontend/` (needs `npx playwright install webkit`). A spurious update banner will make the settings-panel specs fail with `#modal intercepts pointer events` - — that failure mode is a real app bug, not test flake. + — that failure mode is a real app bug, not test flake. On the WSL laptop the + WebKit install fails host validation (missing `libgtk-4`, `libgstreamer*`, …, + needs `sudo npx playwright install-deps`); chromium is already downloaded, so + ad-hoc rendering/offline checks can drive it directly instead. +- Service-worker behaviour (thumb caching, offline) is only provable in a real + browser: serve `frontend/` statically, let the SW take control (needs a second + reload), then `context.setOffline(true)` and assert `img.naturalWidth > 0` plus + the `ytplayer-thumbs` entry count. Asserting against the browser's own HTTP + cache proves nothing — check the Cache API entry count. - Test records on prod use `Probe */Recon *` names; clean via the container DB, children (`video_history`) first.