ytplayer/plans/phase1-plan.md

Phase 1 — per-file asset hashes and server manifest

1. Add tests first in server/asset-manifest.test.js, deliberately extend server/static-delivery.test.js and frontend/shell-consistency.test.js.
2. Describe the existing shell in frontend/assets.json: ordered file groups, contract 1, eager core/settings/playlist/service-mode/lyrics-editor. Preserve index script order and both service-worker sources byte-for-byte.
3. Add importable server/asset-manifest.js; integrate boot-time recursive hashing, stamped index, manifest endpoint, per-file headers and rollback into server/server.js. Register module tests in server/package.json.
4. Stamp HTML CSS/JS resource URLs. Keep font preloads consistent with fonts.css and retain the existing webmanifest URL. Retain plain JS-created worker/import URLs: introducing a new helper would require modifying the unchanged worker's shell or frontend callers. Inventory these exceptions explicitly in the report. Hash every recursively served file, including files outside the shell, so the banner never misses a change.
5. Extract b77938a using perf/make-shell-fixture.sh with an explicitly computed expected tag (never query production). Add perf/migration.mjs and instructions to perf/README.md; test old-client Refresh UI, a single banner, complete new cache, no loop, offline reload, and legacy URL bodies on Chromium and WebKit. Run reduced LTE cold/warm/offline baselines.
6. Review against master plan §3.1/§6b; commit plans/phase1-report.md (≤350 words) with commit IDs, measurements, exceptions and iPhone checks; write DONE01 to the queue signal only after verification succeeds.

Hash self-reference: stamp resource URLs first; hash a canonical index with its build-meta placeholder intact to derive the manifest build tag. Stamp that tag and expose the actual final index byte hash. Canonical tag computation normalizes only this derived index field, avoiding a cryptographic fixed-point requirement. SW response hashing must likewise describe injected bytes rather than raw source.

Rollback: ASSET_HASHING=0 restores the existing recursive build tag and legacy single-tag CSS/JS stamping/header behavior. Default ON; test both modes. Risks: old-worker ignoreSearch, stalled installation, mutable stale URLs, recursive paths, derived HTML/SW hashes, shared iOS cache/audio quota.

Acceptance: both unit suites green after each implementation commit; no weakened characterization tests; migration passes in both browsers; reduced baseline cold, warm and offline boot succeeds with no first-paint regression. Phase 1 still fetches the whole shell on update; <30 KB CSS-only updates belong to Phase 2.