From 895f20a4c901c1611ccf4b76f16d5476b3f7c308 Mon Sep 17 00:00:00 2001 From: Jonathan Sykes Date: Thu, 8 Oct 2026 00:27:50 +0800 Subject: [PATCH] Plan phase 3: Load layouts and features on demand --- plans/phase3-plan.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 plans/phase3-plan.md diff --git a/plans/phase3-plan.md b/plans/phase3-plan.md new file mode 100644 index 0000000..e40f014 --- /dev/null +++ b/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.