Plan phase 3: Load layouts and features on demand

plans/phase3-plan.md

@@ -0,0 +1,37 @@
+# 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.