fix: surface service worker update prompt

byteworthy · byteworthy · commit 72a5fe8eed01 · 2026-04-26T19:38:09.000-05:00
diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md
@@ -90,6 +90,7 @@ Updated: 2026-04-27
 - [x] **PWA-05**: IndexedDB is not proxied through service worker.
 - [x] **PWA-06**: Outdated cache cleanup is enabled.
 - [x] **PWA-07**: Install prompt component exists.
+- [x] **PWA-08**: Service-worker update prompt renders and disables reload during an active survey.
 - [x] **A11Y-01**: Brand colors are checked for WCAG contrast.
 - [x] **A11Y-02**: 44px tap target baseline exists.
 - [ ] **A11Y-03**: Lighthouse accessibility gate runs in CI.
diff --git a/.planning/STATE.md b/.planning/STATE.md
@@ -11,8 +11,8 @@ See `.planning/PROJECT.md`.
 ## Current Position
 
 Phase: 7
-Status: Launch Kit implemented locally; verification/deploy pending
-Last activity: 2026-04-27 - Added a functional viral marketing workbench that generates share artifacts, AI citation text, clinical pilot outreach, contributor prompts, and remix links from real app routes.
+Status: Launch Kit implemented and deployed; service-worker update prompt added locally for stale-client refresh
+Last activity: 2026-04-27 - Added a functional viral marketing workbench that generates share artifacts, AI citation text, clinical pilot outreach, contributor prompts, and remix links from real app routes; then added the SW update prompt so returning visitors can refresh into new launch surfaces.
 
 Progress: [█████████░] 90%
 
@@ -54,6 +54,7 @@ Phase 7 success means attention converts into functional use:
 - Aggregate submission is implemented but disabled by default and non-blocking.
 - Phase 6 turns the demo into an operator tool: synthetic outcomes planning and local config forging.
 - Phase 7 treats marketing as product functionality: share copy and launch briefs must be generated from working demo/proof/studio/forge/poster routes.
+- Returning visitors need a visible service-worker update prompt; otherwise old cached shells can hide new launch routes until a manual hard refresh.
 
 ## Open Blockers
 
diff --git a/.planning/phases/07-viral-functionality-and-marketing-loop/07-SUMMARY.md b/.planning/phases/07-viral-functionality-and-marketing-loop/07-SUMMARY.md
@@ -10,6 +10,8 @@
 - Added locale keys for the new route.
 - Added `docs/VIRALITY-PLAYBOOK.md`.
 - Added a GitHub issue template for weird functional experiments.
+- Rendered the service-worker update prompt so returning visitors can refresh
+  into new launch surfaces without reloading mid-survey.
 - Updated README, public roadmap, Curiosity Lab docs, requirements, roadmap,
   and project state.
 
diff --git a/.planning/phases/07-viral-functionality-and-marketing-loop/07-VERIFICATION.md b/.planning/phases/07-viral-functionality-and-marketing-loop/07-VERIFICATION.md
@@ -2,7 +2,7 @@
 
 ## Automated
 
-Passed on 2026-04-27:
+Passed on 2026-04-27 after Launch Kit and SW update prompt changes:
 
 ```bash
 npm run verify
@@ -28,6 +28,7 @@ Passed locally on 2026-04-27 at `http://127.0.0.1:5173/#/launch`:
 - Confirm artifact selector and default artifact render.
 - Confirm launch brief download action is present.
 - Desktop and mobile viewport accessibility snapshots rendered the route.
+- Route smoke still passed after adding the virtual PWA update-registration module.
 
 ## Deployment
 
diff --git a/README.md b/README.md
@@ -24,6 +24,7 @@ The working app includes:
 - Follow-up calendar export with local `.ics` generation.
 - Follow-up reminder scheduling helpers and in-app reminder banner.
 - PWA manifest, icons, service worker, and install prompt.
+- Service-worker update prompt so returning visitors can refresh into new routes without losing an active survey.
 - Optional aggregate submission module, disabled by default.
 
 Remaining launch blockers:
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -42,6 +42,8 @@ Routes:
 - `src/lib/aggregate/`: optional de-identified aggregate submit path, disabled by default.
 - `src/lib/pdf/`: snapshots the chart canvas and calls `window.print()`.
 - `src/lib/notifications/`: computes follow-up reminders and notification caps.
+- `src/routes/SwUpdatePrompt.svelte`: renders the service-worker refresh prompt and
+  disables reload while a survey is active.
 
 ## Data Model
 
diff --git a/src/App.svelte b/src/App.svelte
@@ -12,6 +12,7 @@
   import Poster from './routes/Poster.svelte';
   import LocaleSwitcher from './routes/LocaleSwitcher.svelte';
   import InAppReminderBanner from './routes/InAppReminderBanner.svelte';
+  import SwUpdatePrompt from './routes/SwUpdatePrompt.svelte';
   import {
     loadPracticeConfig,
     applyBrandingToDocument,
@@ -141,6 +142,8 @@
     </div>
   </header>
 
+  <SwUpdatePrompt {t} busy={route === 'survey'} />
+
   <main>
     {#if route === 'home'}
       <InAppReminderBanner {t} onstart={() => navigate('survey')} />
diff --git a/src/pwa.d.ts b/src/pwa.d.ts
@@ -0,0 +1,11 @@
+declare module 'virtual:pwa-register' {
+  export interface RegisterSWOptions {
+    immediate?: boolean;
+    onNeedRefresh?: () => void;
+    onOfflineReady?: () => void;
+    onRegisteredSW?: (swUrl: string, registration: ServiceWorkerRegistration | undefined) => void;
+    onRegisterError?: (error: unknown) => void;
+  }
+
+  export function registerSW(options?: RegisterSWOptions): (reloadPage?: boolean) => Promise<void>;
+}
diff --git a/src/routes/SwUpdatePrompt.svelte b/src/routes/SwUpdatePrompt.svelte
@@ -0,0 +1,84 @@
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import { registerSW } from 'virtual:pwa-register';
+
+  type T = (k: string, p?: Record<string, string | number>) => string;
+
+  interface Props {
+    t: T;
+    busy: boolean;
+  }
+
+  let { t, busy }: Props = $props();
+  let visible = $state(false);
+  let updateSW = $state<((reloadPage?: boolean) => Promise<void>) | null>(null);
+
+  onMount(() => {
+    updateSW = registerSW({
+      immediate: true,
+      onNeedRefresh() {
+        visible = true;
+      },
+    });
+  });
+
+  async function reload(): Promise<void> {
+    if (!updateSW || busy) return;
+    await updateSW(true);
+  }
+
+  function dismiss(): void {
+    visible = false;
+  }
+</script>
+
+{#if visible}
+  <aside class="sw-update" role="status" aria-live="polite">
+    <div>
+      <strong>{t('swupdate.title')}</strong>
+      <p>{busy ? t('swupdate.body.busy') : t('swupdate.body.ready')}</p>
+    </div>
+    <div class="actions">
+      <button class="primary" disabled={busy} onclick={() => { void reload(); }}>
+        {t('swupdate.cta')}
+      </button>
+      <button onclick={dismiss}>{t('swupdate.dismiss')}</button>
+    </div>
+  </aside>
+{/if}
+
+<style>
+  .sw-update {
+    max-width: var(--max-content);
+    margin: 0.75rem auto 0;
+    border: 1px solid var(--accent);
+    border-radius: 8px;
+    padding: 0.9rem 1rem;
+    display: grid;
+    gap: 0.75rem;
+    background: var(--bg);
+  }
+  .sw-update strong {
+    display: block;
+    margin-bottom: 0.15rem;
+  }
+  .sw-update p {
+    margin: 0;
+    color: var(--muted);
+    font-size: 0.9rem;
+  }
+  .actions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+  }
+  .actions button {
+    padding: 0.5rem 0.8rem;
+  }
+  @media (min-width: 560px) {
+    .sw-update {
+      grid-template-columns: 1fr auto;
+      align-items: center;
+    }
+  }
+</style>
