ytplayer/plans/phase3-plan.md

Phase 3 — lazy groups and staged asset delivery

Start from Phase 2 tip 4950d3e on codex/phase3. Implement master §3.3, §2c and §6/6b; preserve the production client's explicit Refresh UI exception.

1. Add tests first for embedded build-local group URLs, ordered/idempotent lazy loading, selected-layout bootstrap under the existing CSP, stale fallback, contract blocking, background warming and playback guards.
2. Extend server/asset-manifest.js and index stamping with inert JSON group data (exclude derived index/SW hashes to avoid self-reference). Add frontend/lazy.js as an external head script; read _ytpdata safely and insert selected CSS before paint. Update assets.json and shell-consistency/static-delivery tests deliberately.
3. Remove background layout/feature tags from index.html. Adapt app.js feature entry points and Settings layout switching; inspect each module's init and dependencies. Preserve eager playlist/settings/service mode/lyrics editor, saved audio processing and automatic device sharing. Keep pure settings metadata eager where synchronous player defaults require it; load DSP on intent.
4. Extend asset-sync-core.js, sw.js and sw-update.js for active-layout blocking, idle/save-data-aware warming, exact hashed N-1 fallback with contract checks, and build-local URLs. Preserve atomic commit, resumability, retention and the explicit-message-only activation/playback protections. Never replace running playback code. Document any seam requiring an owner decision before proceeding.
5. Add perf/lazy.mjs real-Bun Chromium/WebKit checks: warmed offline features with zero network on first use, selected offline layout and layout switch, staged update and contract guard, and playback-protected Refresh UI. Recheck migration. Run reduced baseline cold/warm/offline against after-phase0; report compressed initial JS/CSS bytes and boot-done. Target less initial JS/CSS by removed lazy groups; first paint no worse; eager features immediate. Explain measured gaps.
6. Review the whole diff against §6/6b, commit a report of at most 350 words and measurements, then overwrite queue-assets/signal with DONE03 and the final hash.

Each logical implementation commit must pass node --test frontend/*.test.js and server bun install + bun run test. No push/deploy or main-checkout edits. Risks: classic-script initialization/TDZ, lazy settings registrations, remembered DSP, old-tab URL affinity and safe replacement of already executing feature modules. Rollback: revert Phase 3 commits; ASSET_SYNC=0 / ASSET_HASHING=0 keep their tested legacy cache behavior. Retain the full legacy SHELL, adding only new eager helpers.