--- phase: 03-event-write-back-pwa-install plan: 07 type: execute wave: 3 depends_on: ["03-01"] files_modified: - apps/pwa/vite.config.ts - apps/pwa/index.html - apps/pwa/public/icon-192.png - apps/pwa/public/icon-512.png - apps/pwa/public/apple-touch-icon.png - apps/pwa/src/components/InstallPrompt.tsx - apps/pwa/src/components/CalendarShell.tsx autonomous: true requirements: [PWA-01, PWA-02] user_setup: [] must_haves: truths: - "The production build emits a valid manifest.webmanifest with name/icons/display:standalone/scope:/ and a service worker" - "The service worker's navigateFallbackDenylist excludes /callback, /api/, /health so the OIDC redirect is never intercepted (Gate 2 risk)" - "On iOS Safari non-standalone, a first-visit install banner appears with a 5-step annotated Add-to-Home-Screen walkthrough" - "On Android, an Install banner appears only when beforeinstallprompt fires and triggers the native prompt" - "Neither install surface renders when the app is already installed (display-mode: standalone)" artifacts: - path: "apps/pwa/vite.config.ts" provides: "VitePWA manifest + SW config with auth-safe denylist" contains: "navigateFallbackDenylist" - path: "apps/pwa/src/components/InstallPrompt.tsx" provides: "iOS walkthrough banner/sheet + Android beforeinstallprompt banner" min_lines: 80 key_links: - from: "apps/pwa/vite.config.ts" to: "OIDC /callback" via: "navigateFallbackDenylist excludes /callback" pattern: "callback" - from: "apps/pwa/src/components/InstallPrompt.tsx" to: "iOS standalone detection" via: "isIOSSafariNonStandalone + display-mode media query" pattern: "standalone" --- Make FamilySync installable (PWA-01) and guide first-time install (PWA-02): add the `vite-plugin-pwa` manifest + service worker with an auth-safe `navigateFallbackDenylist`, the required iOS `` meta/icons, the PWA icon assets, and the `InstallPrompt` component handling both the iOS annotated Add-to-Home-Screen walkthrough and the Android `beforeinstallprompt` flow. Purpose: PWA-01/02 are prerequisites for Phase 5 Web Push — the non-technical member must be able to install unassisted. The single hard constraint is that the service worker MUST NOT intercept the OIDC `/callback` (Gate 2 / Pitfall 1) or break iOS standalone login. Output: configured VitePWA build, install icons + meta, InstallPrompt mounted in the shell. @$HOME/.claude/get-shit-done/workflows/execute-plan.md @$HOME/.claude/get-shit-done/templates/summary.md @.planning/phases/03-event-write-back-pwa-install/03-UI-SPEC.md @.planning/phases/03-event-write-back-pwa-install/03-RESEARCH.md @.planning/phases/03-event-write-back-pwa-install/03-PATTERNS.md @apps/pwa/vite.config.ts Task 1: VitePWA manifest + service worker (auth-safe denylist) + iOS head/icons apps/pwa/vite.config.ts, apps/pwa/index.html, apps/pwa/public/icon-192.png, apps/pwa/public/icon-512.png, apps/pwa/public/apple-touch-icon.png - apps/pwa/vite.config.ts (existing — keep the proxy block incl. /callback verbatim; add VitePWA to plugins) - .planning/phases/03-event-write-back-pwa-install/03-RESEARCH.md (§Pattern 5 — full VitePWA config; required icons; head meta; §Pitfall 1 /callback denylist; §Pitfall 6 dev-mode SW caveat) - .planning/phases/03-event-write-back-pwa-install/03-UI-SPEC.md (§PWA Manifest Contract — exact field values; §SW critical denylist) - apps/pwa/index.html (existing head to extend) Add the `VitePWA` plugin to the existing `plugins` array in vite.config.ts per RESEARCH.md Pattern 5: `registerType:'autoUpdate'`; `workbox.navigateFallback:'/index.html'`; `workbox.navigateFallbackDenylist: [/^\/callback/, /^\/api\//, /^\/health/]` (CRITICAL — OIDC + API must reach the server); `workbox.runtimeCaching: []` (no API caching). `manifest`: name "FamilySync", short_name "FamilySync", description "Family calendar and lists", theme_color "#4A90D9", background_color "#FFFFFF", display "standalone", scope "/", start_url "/", icons 192/512/512-maskable per the contract. Keep the existing `server.proxy` block (including `/callback`) exactly as-is. Generate the three icon PNGs into apps/pwa/public/: `icon-192.png` (192×192), `icon-512.png` (512×512), `apple-touch-icon.png` (180×180). Create a simple solid `#4A90D9` background with a white "F" / calendar glyph using an available CLI tool (ImageMagick `convert`, `sharp` via a one-off node script, or similar). If no image tool is available, set autonomous:false is NOT needed — emit minimal valid PNGs programmatically (node Buffer / sharp). The icons must be valid PNGs at the exact pixel dimensions. Add to apps/pwa/index.html `` the five entries from RESEARCH.md Pattern 5: apple-touch-icon link (180×180), theme-color meta (#4A90D9), apple-mobile-web-app-capable yes, apple-mobile-web-app-status-bar-style default, apple-mobile-web-app-title FamilySync. cd /home/luc/Projects/familysync && pnpm --filter @familysync/pwa build && test -f apps/pwa/dist/manifest.webmanifest && node -e "const m=require('./apps/pwa/dist/manifest.webmanifest');if(m.display!=='standalone'||m.scope!=='/'||!m.icons.some(i=>i.sizes==='512x512'))process.exit(1)" && grep -q "navigateFallbackDenylist" apps/pwa/vite.config.ts && grep -q "apple-touch-icon" apps/pwa/index.html - Production build emits `apps/pwa/dist/manifest.webmanifest` with display:standalone, scope:/, and a 512×512 icon. - `grep -c "/^\\\\/callback/" apps/pwa/vite.config.ts` ≥1 (denylist present) — and `/callback` is in navigateFallbackDenylist. - Three icon PNGs exist in apps/pwa/public at the correct dimensions (`file apps/pwa/public/icon-192.png` reports 192 x 192). - index.html contains the five iOS head entries. Build produces a valid installable manifest + auth-safe SW; iOS icons/meta present. Task 2: InstallPrompt — iOS walkthrough banner/sheet + Android beforeinstallprompt apps/pwa/src/components/InstallPrompt.tsx, apps/pwa/src/components/CalendarShell.tsx - apps/pwa/src/components/InstallPrompt.test.tsx (RED stubs from Plan 01 — isIOSSafariNonStandalone + useAndroidInstallPrompt contract) - .planning/phases/03-event-write-back-pwa-install/03-RESEARCH.md (§Pattern 6 iOS detection + 5-step walkthrough; §Pattern 7 useAndroidInstallPrompt; §Code Examples isInstalled display-mode check) - .planning/phases/03-event-write-back-pwa-install/03-UI-SPEC.md (§InstallPrompt iOS banner/sheet + Android banner; §Copywriting install strings; §Interaction Contract iOS/Android install; localStorage installPromptDismissed) - apps/pwa/src/components/EmptyState.tsx (partial analog — informational surface, token usage) - apps/pwa/src/components/EventDetailPopover.tsx (token + lucide icon import conventions) Tests (InstallPrompt.test.tsx → GREEN): `isIOSSafariNonStandalone()` true for a mock iOS Safari non-standalone UA, false in standalone; `useAndroidInstallPrompt` sets `canInstall=true` when a mock `beforeinstallprompt` dispatches and calls preventDefault; the component renders nothing when `display-mode: standalone` matches; the iOS banner renders the heading "Install FamilySync" with a "How to install" link; the Android banner renders an "Install" button only when canInstall. Implement `InstallPrompt.tsx` with `isIOSSafariNonStandalone()` and `useAndroidInstallPrompt()` per RESEARCH.md Patterns 6/7. Render nothing if already installed (`window.matchMedia('(display-mode: standalone)').matches` or `navigator.standalone`). iOS branch: a dismissible first-visit banner (Smartphone icon, heading/body/CTA per UI-SPEC copy) gated by `localStorage.installPromptDismissed`; "How to install" opens a full-screen bottom-sheet with the 5 annotated steps (exact step copy from UI-SPEC; annotation overlay color `--color-member-2` #F5A623; "Done" closes). Android branch: banner shown only when `canInstall`, with an "Install" button calling `triggerInstall()` then dismiss. Use tokens for all spacing/color, 44px touch targets, plain-text JSX children, `role="banner"`, dismiss `aria-label="Dismiss install prompt"`. Mount `` in CalendarShell (top-level, below nav). Annotated screenshot images may be placeholder assets referenced by path under public/ (real screenshots can be dropped in later); the component structure and copy must be complete and correct. cd /home/luc/Projects/familysync && pnpm --filter @familysync/pwa test -- InstallPrompt && grep -q "InstallPrompt" apps/pwa/src/components/CalendarShell.tsx && grep -q "display-mode: standalone" apps/pwa/src/components/InstallPrompt.tsx && pnpm --filter @familysync/pwa exec tsc --noEmit - InstallPrompt.test.tsx GREEN (iOS detection, Android prompt capture, standalone-hides, banner copy). - `grep -q "isIOSSafariNonStandalone" apps/pwa/src/components/InstallPrompt.tsx`. - InstallPrompt mounted in CalendarShell. - Full PWA suite green; tsc --noEmit passes. iOS guided walkthrough + Android prompt work; nothing shows when already installed; mounted in the shell. ## Trust Boundaries | Boundary | Description | |----------|-------------| | service worker → navigation | The SW can intercept navigations including the OIDC callback | ## STRIDE Threat Register | Threat ID | Category | Component | Disposition | Mitigation Plan | |-----------|----------|-----------|-------------|-----------------| | T-03-20 | Spoofing | SW serving a cached shell for /callback, breaking OIDC code exchange / iOS standalone login | mitigate | `navigateFallbackDenylist: [/^\/callback/, /^\/api\//, /^\/health/]`; verified against a production build (Pitfall 1/6); Gate 2 confirms end-to-end (Plan 08) | | T-03-21 | Tampering | SW caching authenticated API responses | mitigate | `runtimeCaching: []` — no /api caching; /api in denylist | | T-03-22 | Information Disclosure | manifest/icons leaking nothing sensitive | accept | Static public assets only; no secrets in manifest | - `pnpm --filter @familysync/pwa build` emits valid manifest.webmanifest + SW. - `/callback`, `/api/`, `/health` all in navigateFallbackDenylist. - `pnpm --filter @familysync/pwa test` green (InstallPrompt + existing); tsc --noEmit passes. - PWA-01: app installs to Home Screen (manifest + SW, standalone) on iOS and Android. - PWA-02: first-time guided install (iOS walkthrough + Android prompt); never shown when installed. - OIDC `/callback` is never SW-intercepted (Gate 2 prerequisite). Create `.planning/phases/03-event-write-back-pwa-install/03-07-SUMMARY.md` when done.