isIOSSafariNonStandalone + display-mode media query
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 `<head>` 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.
@.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 `<head>` 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.
<threat_model>
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
</threat_model>
- `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.
<success_criteria>
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).
</success_criteria>
Create `.planning/phases/03-event-write-back-pwa-install/03-07-SUMMARY.md` when done.
