feat(pwa): retirement kill-switch, offline-version binding guard, and dev teardown flag

[BigSimmo]

Summary

• Close the three open PWA-hardening findings from the 2026-07-17 PWA setup review, with zero cache-semantics change (no CACHE_VERSION bump; public/sw.js untouched):
  • Commit the retirement kill-switch worker required by docs/pwa.md rule 6 (public/sw-kill-switch.js): skipWaiting on install (the documented retirement exception), deletes every clinical-kb-pwa-* cache including unknown future versions, unregisters itself, registers no fetch listener. Locked by 5 new tests in tests/pwa-kill-switch.test.ts, including prefix-parity with the live worker.
  • Kill the offline.html drift trap: tests/pwa-manifest.test.ts now binds the public/offline.html sha256 to the sw.js CACHE_VERSION pairing, so an offline-document edit cannot ship without a fresh, never-reused version bump.
  • Resolve the ?pwa-dev=1 cleanup friction: ?pwa-dev=0 on local hosts unregisters the dev-session worker and deletes owned caches (production and non-local hosts ignore the flag); a new dom test proves foreign workers and caches are untouched.
• docs/pwa.md updated: rules 1 and 6 now point at the committed guards; the local-dev cleanup step documents the opt-out flag.

Verification

• Focused Vitest (npm run test -- tests/pwa-service-worker.test.ts tests/pwa-manifest.test.ts tests/pwa-lifecycle.dom.test.tsx tests/pwa-kill-switch.test.ts) — 53/53 passed on the rebased branch.
• npm run verify:cheap — green except one pre-existing failure unrelated to this diff: tests/pdf-extraction-budget.test.ts fails identically on a clean checkout of main in this remote container (child-process SIGKILL semantics); baselined by clean re-run.
• npm run ensure + npm run test:e2e:pwa — the offline-fallback/CacheStorage-privacy journey passes; the installability test fails only in this container with Chromium's sole complaint "in-incognito", reproduced identically from a detached clean-main worktree with its own server — an environment artifact of the preinstalled Chromium, not this diff. Hosted CI Chromium (which runs this spec in the Production UI job) is authoritative.
• npm run verify:ui — 218 passed (7.7m); 2 failures, both reproduced identically on a clean-main (54229f0) detached worktree, i.e. pre-existing and container-local: the ui-pwa installability test above, and the ui-smoke "document viewer puts the PDF preview first…" mobile test (flagged separately as a possible upstream regression — not introduced here).
• npm run verify:pr-local — unit stage: 2764 passed / 1 failed, the same twice-baselined container-only pdf-extraction-budget failure, which stops the local chain; the conditional production-build/client-bundle stages are covered authoritatively by this PR's blocking hosted CI Build job (bundle budget enforced). npm run format:check clean for repo files.

Clinical Governance Preflight

Not applicable — no ingestion, answer generation, search/ranking, source rendering, document access, privacy-boundary, production env, or clinical output behavior changes. The service-worker privacy contract is unchanged (no new cached content classes; the existing CacheStorage-inventory e2e and worker policy suite prove it).

Risk and rollout

• Risk: low — the kill-switch worker is inert unless deliberately deployed over /sw.js; the lifecycle change adds a localhost-only opt-out branch ahead of an otherwise unchanged registration path; remaining changes are tests and docs.
• Rollback: revert this commit; no cache version moved, so installed clients are unaffected.

Notes

• Phase 1 of the approved PWA perfection plan. Phase 0 (pr-policy checkout resilience + the Set-Cookie worker-test case) landed on main independently and is not repeated here.
• Branch review ledger row recorded in the follow-up commit 2b1c365 on this branch.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EXsJcLrbZUXwnBeG91cVo9

Summary by CodeRabbit

• New Features
  • Added a PWA “kill switch” retirement mechanism to retire the existing service worker and clear only the app’s own caches in a single deployment.
  • Added local development opt-out support with ?pwa-dev=0, automatically unregistering the worker and removing owned caches.
• Documentation
  • Updated PWA versioning and retirement guidance, including how cache-semantics changes require a version bump.
• Bug Fixes
  • Added safeguards to preserve unrelated service workers and caches during teardown.
  • Added verification to ensure offline content is synchronized with the PWA cache version.

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: c37d54e8-e9f1-4033-961b-875321cc02f9

📥 Commits

Reviewing files that changed from the base of the PR and between 57a2f6b and 8406bc4.

📒 Files selected for processing (2)

• src/components/pwa-lifecycle.tsx
• tests/pwa-lifecycle.dom.test.tsx

🚧 Files skipped from review as they are similar to previous changes (2)

• tests/pwa-lifecycle.dom.test.tsx
• src/components/pwa-lifecycle.tsx

---

📝 Walkthrough

Walkthrough

The PR adds a PWA retirement service worker, local ?pwa-dev=0 teardown, an offline document hash/version check, and documentation and ledger updates covering deployment, verification, and operational behavior.

Changes

PWA hardening

Layer / File(s)	Summary
Retirement worker and behavioral lock public/sw-kill-switch.js, tests/pwa-kill-switch.test.ts, docs/pwa.md	Adds a worker that skips waiting, deletes owned caches, unregisters, claims clients, and has no fetch handler; tests cover cache targeting, failure handling, and lifecycle behavior.
Local PWA opt-out teardown src/components/pwa-lifecycle.tsx, tests/pwa-lifecycle.dom.test.tsx, docs/pwa.md	Adds local-host ?pwa-dev=0 teardown for owned workers and caches, with tests preserving foreign registrations and unrelated caches.
Offline cache-version binding and records tests/pwa-manifest.test.ts, docs/pwa.md, docs/branch-review-ledger.md	Binds the offline document hash to CACHE_VERSION and records the hardening implementation, verification results, and operational guidance.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Browser
  participant PwaLifecycle
  participant ServiceWorker
  participant CacheStorage
  Browser->>PwaLifecycle: load PWA lifecycle
  PwaLifecycle->>ServiceWorker: register or tear down based on environment and query flag
  ServiceWorker->>CacheStorage: delete owned caches during retirement
  ServiceWorker-->>PwaLifecycle: unregister and claim clients

Loading

Possibly related PRs

• BigSimmo/Database#702: Provides the existing PWA service-worker caching scheme whose cache prefix and offline semantics are validated by this PR.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main PWA hardening changes.
Description check	✅ Passed	The description covers summary, verification, risk, notes, and clinical preflight, matching the template well enough.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/clinical-kb-pwa-review-asi3wb

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/components/pwa-lifecycle.tsx`:
- Around line 72-77: Update the service-worker filtering in the registration
cleanup flow to compare each worker’s scriptURL exactly against the absolute URL
produced by new URL(SERVICE_WORKER_URL, window.location.origin).href, rather
than using endsWith. Also update the foreign-worker test fixture to use a nested
/.../sw.js URL so it verifies unrelated workers are preserved.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 1fb8e633-480f-4921-a037-47d93ab9ac58

📥 Commits

Reviewing files that changed from the base of the PR and between bf9534c and 57a2f6b.

📒 Files selected for processing (7)

• docs/branch-review-ledger.md
• docs/pwa.md
• public/sw-kill-switch.js
• src/components/pwa-lifecycle.tsx
• tests/pwa-kill-switch.test.ts
• tests/pwa-lifecycle.dom.test.tsx
• tests/pwa-manifest.test.ts