fix(sw): complete cache-clearing + add controllerchange auto-reload

All cache-clearing buttons and the IDAA clear-caches page previously
cleared IDB/localStorage but left service worker registrations and Cache
Storage intact. On the next reload the SW re-served the old JS bundle,
leaving users stuck on stale code despite appearing to reload. This
caused recurring stale-state reports from IDAA and other clients for
4+ months.

Two gaps closed:
1. Every clear path (root page buttons, sys bar, help tech, idaa/clear-caches)
   now unregisters SW registrations and clears Cache Storage before touching
   IDB and localStorage. Order: SW → Cache Storage → IDB → localStorage.
2. Added controllerchange listener in +layout.svelte effect 4. When the new
   SW activates and calls clients.claim(), this listener reloads the page so
   open tabs run the new JS bundle instead of keeping old code in memory
   indefinitely. Without this, skipWaiting + clients.claim work correctly on
   the SW side but the page side never picks up the update.

Also added thorough code comments and updated REFERENCE__Common_Agent_Mistakes
(#15) and BOOTSTRAP doc (#8) to document the full root cause so this cannot
be silently re-broken by a future agent or refactor.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Scott Idem
2026-06-22 12:17:51 -04:00
parent 468ed61b39
commit 81874ffa5d
7 changed files with 197 additions and 28 deletions

View File

@@ -299,7 +299,11 @@ Read this section first, then open the reference doc when your task touches one
5. **Sorting and search correctness**`tmp_sort_*` comparator direction and Dexie sorting caveats.
6. **Network reliability** — retry classification in `api_*_object.ts` and timeout behavior.
7. **JSON field safety**`*_json` null reads/writes and wrapper serialization behavior.
8. **Service worker rollout behavior** — stale-tab symptoms, activation expectations, and trade-offs.
8. **Service worker + cache clearing — MANDATORY four-layer wipe** — clearing IDB/localStorage
alone is a placebo. The SW Cache Storage is separate and must be cleared first or the SW
re-serves the old JS bundle on the very next reload. The `controllerchange` event listener in
`+layout.svelte` (effect 4) is also required or open tabs stay on old code after deploys.
See mistake #15 in the reference doc — this caused a recurring client issue for 4+ months.
9. **Local/remote config sync** — shadow fields that silently bypass an admin-synced master
field, SWR-await-after-write races, and stateful/conditional sync gates that desync local
state from history rather than current config. See the Pres Mgmt Config sync overhaul