Skip to content

Polish the responsive PWA install lifecycle#1976

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
BigSimmo merged 21 commits into from
Aug 15, 2026
Merged

Polish the responsive PWA install lifecycle #1976

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
41d0049
feat(pwa): polish responsive install lifecycle
BigSimmo Aug 14, 2026
3c00952
fix(pwa): keep install surface clear and reachable
BigSimmo Aug 15, 2026
c82c06b
Merge branch main into codex/pwa-install-polish-20260815
BigSimmo Aug 15, 2026
b029592
docs: record final PWA base update
BigSimmo Aug 15, 2026
1becd70
Merge branch 'main' into codex/pwa-install-polish-20260815
BigSimmo Aug 15, 2026
5866920
docs: record PWA base sync
BigSimmo Aug 15, 2026
63c82fe
Merge main into codex/pwa-install-polish-20260815
BigSimmo Aug 15, 2026
c78bbf6
docs(ledger): record PWA base sync
BigSimmo Aug 15, 2026
4aaa701
style(pwa): format style contract exemptions
BigSimmo Aug 15, 2026
c3c260c
docs(ledger): record PWA formatter follow-up
BigSimmo Aug 15, 2026
6898088
style(pwa): keep narrow exemptions inline
BigSimmo Aug 15, 2026
31bfa60
docs(ledger): record PWA exemption formatter follow-up
BigSimmo Aug 15, 2026
7369945
Merge branch 'main' into codex/pwa-install-polish-20260815
BigSimmo Aug 15, 2026
80eb8f6
docs(ledger): record PWA base sync
BigSimmo Aug 15, 2026
6a1ef9e
fix(pwa): reuse design-system roles in notice styles
BigSimmo Aug 15, 2026
0dd4b7e
fix(pwa): limit compact install layout shift
BigSimmo Aug 15, 2026
e466505
fix(pwa): keep install sheet clear of phone search
BigSimmo Aug 15, 2026
8bb76ce
Merge branch 'main' into codex/pwa-install-polish-20260815
BigSimmo Aug 15, 2026
5432759
fix(pwa): keep phone install card clear of search
BigSimmo Aug 15, 2026
81c44ae
fix(pwa): prevent install prompt layout shift
BigSimmo Aug 15, 2026
d7449c7
test(ui): register compact PWA styles
BigSimmo Aug 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions ...ords/2fed40a238cbd6e5803e25f6c4778648494337db0a6927d4b2f55c077e60c173.record.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
| 2026-08-15 | codex/pwa-install-polish-20260815 | 6a1ef9ef020ff41165a9d02245367052a68bd7b3 | PWA mobile root CLS budget remediation | Narrowed install-sheet root-content repositioning from all phone widths to the documented <=359px compact layout, preserving the 320px overflow safeguard while avoiding the confirmed mobile-root shift. | git diff --check; Lighthouse CI log diagnosis: mobile-root CLS +0.105 confirmed in 3/3 samples; local Lighthouse intentionally not run |
1 change: 1 addition & 0 deletions ...ords/497a7b26ad6568692b3dbc9e939c1e7d35a1a50108e2c0268cbf41ee612eaa76.record.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
| 2026-08-15 | codex/pwa-install-polish-20260815 | c6d8c2829ddd2fc52441a3696aed56fbd0262917 | required base sync through main 17402395 | Approved — required main update merged; prior PWA lifecycle review and style-inventory repair remain applicable with no PR-path conflict | git diff --check; ci-change-scope self-test; ledger/inbox/outstanding/discipline guards passed |
1 change: 1 addition & 0 deletions ...ords/4a51a80a457f85c939048278f01e3a3059d5509bfd975096af94b63ef16e825a.record.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
| 2026-08-15 | codex/pwa-install-polish-20260815 | 80fd6c04afdfa30e92c1cdf2ea5ba9d3d32a02c6 | PWA style-contract formatter follow-up | Formatted the PWA style-contract exemption entries reported by changed-file formatting. Targeted registry test unavailable because this isolated worktree has no node_modules/vitest; Lighthouse was not run locally by instruction. | node --check tests/helpers/style-contracts.ts; git diff --check; ledger-inbox; outstanding-issues; branch-review-ledger; ledger-write-discipline; ci-change-scope --self-test |
1 change: 1 addition & 0 deletions ...ords/534a1703b8963c66fe43de4889cf3f33e6bc83a7ebc8734fba8c6c71148e0d6f.record.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
| 2026-08-15 | codex/pwa-install-polish-20260815 | aa041fd15f902dce172ea0d2707f3f81cb8f160c | PWA install lifecycle: final current-base merge | Merged latest required base after validated PWA registry fix; no merge conflicts | git diff --check; ledger-inbox; outstanding-issues; branch-review-ledger; ledger-write-discipline; static PWA registry assertion |
1 change: 1 addition & 0 deletions ...ords/615deb9148ec106e31cf72902d4a1b2710987b3597aeef62b9a2fb964975dd5b.record.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
| 2026-08-15 | 1976 | 54327591bb89f6f9f25f6834fbefc277a9bff80b | review-and-fix | P2 fixed: native install prompt now avoids hero reflow, composer overlap, and prompt-induced CLS | pwa DOM 10/10; PWA Chromium 5/5; format; exact-head merge-tree |
1 change: 1 addition & 0 deletions ...ords/63bb22a3ea42c41966caaa63a61b73a2bba0026f0898a8f6e3afae6123075fce.record.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
| 2026-08-15 | codex/pwa-install-polish-20260815 | 80fd6c04afdfa30e92c1cdf2ea5ba9d3d32a02c6 | PR #1976 PWA exemption formatter follow-up | Corrected two exemption descriptions that were under the 120-column formatter width and must remain single-line properties. | git diff --check; ledger/outstanding/branch-ledger/ledger-discipline guards; ci-change-scope self-test passed; npm test -- tests/style-contract-registry.test.ts unavailable: node_modules/vitest/vitest.mjs absent. |
1 change: 1 addition & 0 deletions ...ords/7620543101feadcebdc49427ad0395f1f4c8a0d304ec3a5251f1920d023b06c0.record.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
| 2026-08-15 | 1976 | 8bb76ce085f212d47a0918b9242cb412e8a9a3f7 | review-and-fix | fixed phone install-sheet overlap on current-base head | pwa regression 1/1; lifecycle DOM 10/10; verify:phone-chrome 437/437 UI |
1 change: 1 addition & 0 deletions ...ords/a9f750bbfb5bbb2857e2cdbb97a2dc446b1851cec993f8a91dd526fcbc750d25.record.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
| 2026-08-15 | codex/pwa-install-polish-20260815 | dd687f20c2143466b40d51ce2831542130964af4 | PWA install lifecycle: style-contract registry and current-base merge | Fixed PR-introduced unregistered PWA visual classes; stale install-sheet exemption removed; merged current base | git diff --check; ledger-inbox; outstanding-issues; branch-review-ledger; ledger-write-discipline; static PWA registry assertion; targeted Vitest unavailable (node_modules absent) |
1 change: 1 addition & 0 deletions ...ords/b3523668f8839bde68f1fae4de2e7e8275b5cabc1802d1b6511b30323adad6ad.record.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
| 2026-08-15 | codex/pwa-install-polish-20260815 | 80fd6c04afdfa30e92c1cdf2ea5ba9d3d32a02c6 | PR #1976 base sync | Merged main 6f7b7deefaf7e0cd062b748f18fc6ca8988093f6 into the reviewed PR head; merge tree was clean. | git merge-tree --write-tree exact-head main: clean; git diff --check; ledger guards. |
1 change: 1 addition & 0 deletions ...ords/bde56718d14d5138e7a29a72d16402b4445bd109c6f2bfcffd686c6e436d8c74.record.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
| 2026-08-15 | codex/pwa-install-polish-20260815 | 80eb8f6d1c332ee5c32a27da93eb026fb6d9b0d1 | PWA stylesheet design-token contract remediation | Replaced PR-introduced raw PWA motion, padding, radius, gap, and line-height declarations with scoped semantic roles and existing design tokens; preserved rendered values. | git diff --check; manual CSS-contract audit (no new raw guarded declarations); static gate unavailable locally: @typescript/typescript6 not installed |
1 change: 1 addition & 0 deletions ...ords/c56fc20eb8b758bec749726901ef79ce50012974b924d01bcc5b55b6dc00d1ad.record.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
| 2026-08-15 | 1976 | 81c44aee0b788a5aa93522a09092cddcd12b0bf0 | review-and-fix | CI blocker fixed: register compact native-install CSS selectors in the unlayered style inventory | style-contract registry 15/15; PWA DOM 10/10; PWA Chromium 5/5; Lighthouse exact-head green |
1 change: 1 addition & 0 deletions ...ords/cebd03715e584420f2fb63b757718fd8f04e9dfb00089261c37800f7d8edf694.record.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
| 2026-08-15 | codex/pwa-install-polish-20260815 | 80fd6c04afdfa30e92c1cdf2ea5ba9d3d32a02c6 | PWA phone install/composer overlap regression | Restored the shared phone composer reserve for mode-home install sheets after the exact-head production UI geometry test found a 390px overlap. | git diff --check 0dd4b7e9be293815ec3d06f3b57682a1578bafe4; node scripts/ledger-inbox.mjs check; node scripts/check-outstanding-issues.mjs; node scripts/ci-change-scope.mjs --self-test; exact-head production UI geometry failure reviewed |
1 change: 1 addition & 0 deletions ...ords/fe8542d735a4d0a26e76906a700a861925da55131c0caacbaab18ac81507cd0d.record.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
| 2026-08-15 | codex/pwa-install-polish-20260815 | 233047f36f210f0e9ea4846183b2368ca67fa338 | Required base sync through main d301d8f4 | approved | git diff --check; CI scope self-test; ledger and issue guards |
20 changes: 12 additions & 8 deletions docs/pwa.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -52,9 +52,13 @@ registered service worker. Localhost is the browser's secure-context development
is shown only when the browser emits `beforeinstallprompt`; browsers that do not expose that event retain their own
install/Add to Home Screen flow.

The install card is not shown in standalone mode. Choosing **Not now**, or dismissing the browser prompt, suppresses
the custom prompt for 30 days using `clinical-kb-pwa-install-dismissed-at` in localStorage. `appinstalled` clears that
value. Storage failures are treated as non-fatal progressive-enhancement failures.
The install card is not shown in standalone mode. It stays non-blocking and lower-right on wide screens; on phones it
becomes a compact sheet positioned clear of the current composer owner (above a bottom dock or below an in-flow home
composer) and the safe area. The benefit list is deliberately limited to quick access, app-like launch, and the
familiar Clinical KB workspace. It does not imply offline clinical access.
Choosing **Not now**, using **Dismiss**, or dismissing the browser prompt suppresses the custom prompt for 30 days
using `clinical-kb-pwa-install-dismissed-at` in localStorage. `appinstalled` clears that value. Storage failures are
treated as non-fatal progressive-enhancement failures.

iOS and iPadOS never emit `beforeinstallprompt`, so outside standalone mode those platforms get a one-time manual
hint instead (Safari: Share, then Add to Home Screen). **Not now** suppresses it for 30 days via
Expand DownExpand Up@@ -155,11 +159,11 @@ clinical actions remain network-dependent.

### Update UX

- An already-waiting worker, or an installing worker that reaches `installed` while a controller exists, shows **An
update is ready**.
- An already-waiting worker, or an installing worker that reaches `installed` while a controller exists, shows
**Update available**.
- When the page becomes visible or connectivity returns, the registration may check for an update. App-triggered
checks are throttled to at most once per hour; there is no background polling timer.
- **Refresh now** sends `SKIP_WAITING`. The page reloads once after `controllerchange`, so it cannot loop.
- **Reload** sends `SKIP_WAITING`. The page reloads once after `controllerchange`, so it cannot loop.
- **Later** hides the update for the current lifecycle instance. A later page load can surface the waiting update
again.
- If another tab activates the update, an already-controlled tab receives `controllerchange` and offers its own
Expand DownExpand Up@@ -232,7 +236,7 @@ resource problem by weakening the page CSP or adding a provider origin to the wo

## Accessibility, theme, and device fit

- Lifecycle notices use a polite live region, labelled status/region containers, real buttons, 44 px minimum target
- Lifecycle notices use a polite live region, labelled status/region containers, real buttons, 48 px minimum target
height, and visible focus treatment.
- The notice stack does not take page scroll ownership. Its cards restore pointer events while the container remains
transparent to unrelated interaction.
Expand DownExpand Up@@ -299,7 +303,7 @@ explicitly authorized.
document must appear and must not reveal prior content. Restore connectivity and verify the restored notice.
- [ ] Confirm an offline API/document/media request is not answered from a PWA cache.
- [ ] Deploy a worker with a new cache version in a staging environment. Verify the update waits, **Later** does not
force a refresh, **Refresh now** activates it, every older tab is offered a refresh, and only the two newest
force a refresh, **Reload** activates it, every older tab is offered a refresh, and only the two newest
prior static caches remain for lazy-chunk compatibility.
- [ ] Check keyboard focus, screen-reader announcements, forced colours, light/dark theme, portrait/landscape, display
cutouts, and the standalone home-indicator area at phone and desktop breakpoints.
Expand Down
Loading
Loading