familysync/.planning/milestones/v1.0-phases/03-event-write-back-pwa-install/03-07-PLAN.md at c2f89bd55f0bd701b292af6c9d39450f77ae8ae6

Files

T

Lucas Berger 982438dc10 style(13-03): apply Prettier formatting across repo

Mechanical reformat — no logic changes. 398 files changed, 19125
insertions(+), 16457 deletions(-). Prettier 3.8.4 with .prettierrc
(singleQuote:true, semi:true, tabWidth:2, trailingComma:all,
printWidth:100). Isolated per D-13-08 for reviewability.

2026-06-11 20:35:18 -04:00

12 KiB

Raw Blame History

phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, user_setup, must_haves

phase

plan

type

wave

depends_on

files_modified

autonomous

requirements

user_setup

must_haves

03-event-write-back-pwa-install

execute

03-01

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

true

PWA-01

PWA-02

truths

artifacts

key_links

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)

path	provides	contains
apps/pwa/vite.config.ts	VitePWA manifest + SW config with auth-safe denylist	navigateFallbackDenylist

path	provides	min_lines
apps/pwa/src/components/InstallPrompt.tsx	iOS walkthrough banner/sheet + Android beforeinstallprompt banner	80

from	to	via	pattern
apps/pwa/vite.config.ts	OIDC /callback	navigateFallbackDenylist excludes /callback	callback

from	to	via	pattern
apps/pwa/src/components/InstallPrompt.tsx	iOS standalone detection	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.

<execution_context> @$HOME/.claude/get-shit-done/workflows/execute-plan.md @$HOME/.claude/get-shit-done/templates/summary.md </execution_context>

@.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.

12 KiB Raw Blame History Unescape Escape

Trust Boundaries

STRIDE Threat Register

12 KiB

Raw Blame History