feat(pwa): manifest launch/display fallbacks, monochrome icons, iOS install hint

[BigSimmo]

Summary

Phase 2 of the approved PWA plan — install-experience polish with cache semantics untouched (public/sw.js unchanged, no CACHE_VERSION move):

• src/app/manifest.ts: launch_handler: { client_mode: ["navigate-existing", "auto"] } (focus the open app window instead of spawning duplicates) and display_override: ["standalone", "minimal-ui"] (graceful fallback, never fullscreen); two new monochrome icon entries.
• src/app/icons/[variant]/route.tsx + src/lib/brand-image.tsx: monochrome-192/512 variants rendered from the single shared brand mark as a white alpha-only silhouette (BRAND_MONOCHROME) that platforms recolour for badges/themed icons.
• src/components/pwa-lifecycle.tsx: one-time iOS/iPadOS Add to Home Screen hint (those platforms never emit beforeinstallprompt) — shown only outside standalone mode, dismissible with a 30-day clinical-kb-pwa-ios-install-dismissed-at key mirroring the existing install-card pattern; eligibility check is timer-deferred to satisfy react-hooks/set-state-in-effect and avoid hydration divergence.
• docs/pwa.md Installability section updated. Manifest screenshots remain deliberately deferred per the documented production-capture precondition.

Verification

• Focused Vitest (4 PWA files) — 55/55 passed (new: launch/display fallback assertions, monochrome icon assertions, iOS-hint show/dismiss/persistence test).
• npm run verify:cheap — 2773 passed / 1 failed: the known container-only tests/pdf-extraction-budget.test.ts artifact (fails identically on clean main in this remote container; passed on hosted CI for feat(pwa): retirement kill-switch, offline-version binding guard, and dev teardown flag #826).
• npm run ensure + npm run test:e2e:pwa — offline/CacheStorage-privacy journey passes; the installability test's icon probes cover the two new monochrome PNGs (200, image/png, correct dimensions) and the CDP manifest parse reports zero errors; the final installability poll fails only with the container-local "in-incognito" artifact (baselined on clean main; hosted CI Chromium authoritative).
• npm run verify:ui — 219 passed / 2 failed (5.3m): exactly the two clean-main-baselined container artifacts (ui-pwa installability, ui-smoke PDF-canvas mobile), both of which passed on hosted CI for feat(pwa): retirement kill-switch, offline-version binding guard, and dev teardown flag #826. No new failures.
• npm run verify:pr-local — unit stage 2773 passed / 1 failed (same known artifact, stops the local chain); production build + bundle budget covered by this PR's blocking hosted CI Build job. 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 changes. The service-worker privacy contract is untouched; /icons/* was already allow-listed with a PNG MIME expectation, so the new variants introduce no new cached content class.

Risk and rollout

• Risk: low — manifest additions are additive fields with identity (id/scope/start_url) untouched, so no reinstall churn; the manifest revalidates immediately (max-age=0); the iOS hint is a self-contained dismissible card behind an iOS-only heuristic.
• Rollback: revert the commit; additive manifest fields disappear on the next manifest revalidation and no cache version moved.

Notes

• Phase 2 of the plan; Phases 0–1 are on main (feat(pwa): retirement kill-switch, offline-version binding guard, and dev teardown flag #826). Ledger row follows in a branch commit.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EXsJcLrbZUXwnBeG91cVo9

---

Generated by Claude Code

Summary by CodeRabbit

• New Features

  • Added improved PWA launch behavior to reuse existing app windows and avoid duplicate tabs.
  • Added monochrome icons for better platform and launcher support.
  • Added iOS/iPadOS “Add to Home Screen” guidance when automatic installation prompts are unavailable.
  • Added a “Not now” option that suppresses the iOS installation hint for 30 days.

• Documentation

  • Updated PWA installation documentation with icon, display, launch, and iOS guidance.

• Tests

  • Added coverage for iOS installation guidance and updated manifest behavior checks.

[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]

📝 Walkthrough

Walkthrough

Updates PWA manifest launch and display metadata, adds monochrome icon generation, introduces an iOS/iPadOS installation hint with dismissal persistence, and adds corresponding tests and documentation.

Changes

PWA install and icon polish

Layer / File(s)	Summary
Manifest and monochrome icon support src/lib/brand-image.tsx, src/app/icons/..., src/app/manifest.ts, tests/pwa-manifest.test.ts	Adds monochrome brand palettes and icon variants, configures display_override and launch_handler, and tests the resulting manifest metadata.
iOS installation hint flow src/components/pwa-lifecycle.tsx, tests/pwa-lifecycle.dom.test.tsx	Adds iOS detection, a manual installation hint, 30-day dismissal persistence, and DOM coverage for dismissal and remount behavior.
Installability documentation and review record docs/pwa.md, docs/branch-review-ledger.md	Documents updated manifest and iOS installation behavior and records the PR’s verification results.

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

Possibly related PRs

• BigSimmo/Database#702: Also modifies PWA manifest install and UX metadata.
• BigSimmo/Database#741: Also appends a review record to docs/branch-review-ledger.md.

Suggested reviewers: claude

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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.
Title check	✅ Passed	The title clearly matches the PR’s main PWA install-experience changes and stays concise.
Description check	✅ Passed	The description follows the template closely, with Summary, Verification, Risk, Clinical Governance, and Notes all covered.

✨ 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.}