[Audit 23/32][P2][PWA] Improve Install App, offline-state, and cache-clearing UX

[baixiangcpp]

Recommended execution order

23 of 32. Do after local data controls, because PWA cache controls should share the same mental model.

Evidence level

Static page observation.

Problem

Install App explains PWA installation, offline support, and cached app files, but the cache-clearing entry point is not prominent and the install prompt may show as unavailable depending on browser. Offline-state behavior was not fully verified.

Why this matters

PWA and offline capability are core differentiators. Users should understand what works offline, what requires network, and how to refresh or clear cached app files.

Recommended implementation

• Make install status and browser-specific instructions clearer.
• Add PWA install CTA on home/tool pages where supported.
• Add visible cache management link in navigation/settings.
• Add offline banner and external-request offline error messages.
• Explain update behavior and refresh flow.

Acceptance criteria

• Install App page clearly distinguishes Chrome, Safari, Edge, Firefox, Android, and iOS instructions.
• If install prompt is unavailable, the UI explains why and gives next steps.
• Cache clearing is reachable from Install App and Settings/Local Data Controls.
• Offline local tools work after cache warm-up.
• External-request tools show a clear offline error.
• Update availability is communicated without losing tool input unexpectedly.
• Manual PWA tests run on at least Chrome Desktop, Android Chrome, iOS Safari, and Edge.

[baixiangcpp]

Progress update: PR #291 merged PWA install/offline/cache UX improvements in 03f38ab.\n\nCovered in code and automation:\n- Added explicit Safari/macOS install guidance alongside Chrome Desktop, Edge, Firefox, Android, and iOS Safari.\n- Added localized global offline banner with a link to the offline support matrix.\n- Kept cache clearing reachable from Install App and Local Data Controls.\n- Added guard/component coverage for install guide coverage, offline banner copy, cache controls, external-request offline boundaries, and user-triggered service-worker update activation.\n- Stabilized and passed the PWA Playwright smoke for service worker, cache buckets, offline fallback, and manual cache clear.\n\nValidation run locally and in CI: focused Vitest guards/components, check:types, lint, validate, build:app, build:post, and test:e2e:pwa.\n\nRemaining before closing this issue: real manual PWA install/offline checks on Chrome Desktop, Android Chrome, iOS Safari, and Edge. I intentionally used Refs rather than Closes in the PR because those device/browser manual checks were not genuinely run in this environment.

[baixiangcpp]

PR #300 landed the remaining manual closure runbook in docs/accessibility/audit-23-25-26-manual-closure-runbook.md and guard coverage to keep the #260 closure criteria from drifting.

Current status:

• Automated PWA/offline/cache/update coverage is already in CI via npm run test:e2e:pwa, guards, validate, and the normal build checks.
• The remaining acceptance criteria are real browser/device checks: Chrome Desktop, Edge Desktop, Android Chrome, and iOS Safari install/offline/cache/update behavior.
• The issue should stay open until those real-device checks are run and the closure comment template from the runbook is filled in here.

Latest validation for the runbook PR passed in CI: Cloudflare Pages and build (20.x).

[baixiangcpp]

Automated verification refresh on 2026-06-27 for main@eb58faca5f805e6a437f3ebc64de8385a98f7651.

Passed locally:

• npm run test:e2e:pwa

This covered the current exported app shell with Playwright Chromium for service worker activation/control, Byteflow cache buckets, offline fallback, local JSON Formatter offline flow, HAR Sanitizer/Pipeline Builder cache warm-up, external-request cache exclusion, and manual cache clear behavior.

Also confirmed after PR #301 merge:

• CI on main passed: build (20.x) run 28285679896.

Keeping #260 open because the remaining close criteria still require real browser/device PWA checks in Chrome Desktop, Edge Desktop, Android Chrome, and iOS Safari, including install-window/home-screen behavior and user-visible update behavior in those browsers.

[baixiangcpp]

Automated verification refresh on 2026-06-29 for current main.

Passed locally:

• npm run check:audit:prod-high passed. The production high/critical gate remains green; the known Next bundled PostCSS finding remains moderate and is tracked separately in Track upstream fix for Next bundled PostCSS advisory #7.
• npm test -- --run tests/guards/pwa-install-offline-issue-260.test.ts tests/guards/mobile-a11y-audit-issues-262-263.test.ts tests/guards/next-postcss-advisory-runbook.test.ts passed: 3 files, 11 tests.
• npm run test:e2e:pwa passed.
• npm run lint passed.
• npm run check:types passed.
• npm run validate passed.

Relevant #260 coverage refreshed by the PWA run:

• Service worker activation/control.
• Byteflow cache bucket checks.
• Offline fallback behavior.
• Local JSON Formatter offline flow.
• HAR Sanitizer/Pipeline Builder cache warm-up coverage through the PWA smoke path.
• External-request cache exclusion.
• Manual cache clear behavior.
• Mobile review matrix still passes no-overflow and touch-target checks.
• Representative accessibility checks still report no serious or critical axe violations as part of the shared smoke matrix.

Recent remote evidence:

• Latest confirmed main CI run is green: 28374709014.

Boundary for closure:

• This refresh does not satisfy the manual acceptance criteria.
• [Audit 23/32][P2][PWA] Improve Install App, offline-state, and cache-clearing UX #260 should stay open until real browser/device PWA checks are run on Chrome Desktop, Edge Desktop, Android Chrome, and iOS Safari, including install-window/home-screen behavior, offline behavior after cache warm-up, cache clearing, and user-visible update behavior.

[baixiangcpp]

PR #336 merged as cb8b4ab with the #260 implementation preserved in commit 3f78843.

Additional automated coverage completed in this batch:

• A single pre-hydration owner now captures the one-shot beforeinstallprompt and shares it between the global CTA and Install App page.
• Consuming the prompt on either surface removes it from both, while stale async consumers cannot clear a newer prompt.
• A fresh browser prompt clears stale installed state without resetting the once-per-session gate.
• appinstalled is persisted even before the deferred React runtime mounts.
• Service-worker updates reload only after an explicit user activation request.
• PWA smoke now has a 20-second service-worker-ready failure boundary and a dedicated 30-minute CI job.
• Browser/platform guidance and unique 1280x720 install screenshots are covered by guards.

Validation passed locally and remotely: Node 20 unit/coverage/validate/build/post-build, full Playwright smoke, independent PWA smoke, Cloudflare Pages, build (20.x), and the dedicated pwa job. Codex review found no actionable issues.

Keeping #260 open because real install-window/home-screen validation is still required on Chrome Desktop, Edge Desktop, Android Chrome, and iOS Safari. Chromium automation does not substitute for those device/browser checks.

[baixiangcpp]

Closure-environment audit refresh on 2026-07-16 for main@df9dae7.

Current automated baseline is green: post-merge CI run 29532382529 passed the production moderate audit, lint, unit/coverage, validate, build/post-build, full Playwright smoke, route-width matrix, and dedicated PWA smoke. Cloudflare production also deployed successfully.

Environment available on this host:

• Chrome Desktop 150.0.7871.124.
• Edge Desktop 150.0.4078.65.

Environment not available:

• No physical Android device, adb, Android SDK/emulator, or Android Chrome device session.
• No iPhone, iOS Safari/simulator, or Apple tooling on this Windows host.
• No BrowserStack/Sauce/LambdaTest/Device Farm credentials.

A desktop-only pass cannot satisfy this issue's required physical Android Chrome and iOS Safari install-to-home-screen, standalone launch, airplane-mode offline, cache-clear, and update evidence. No new code defect was found; keep #260 open until those device sessions are actually recorded.

[baixiangcpp]

Desktop PWA evidence update - 2026-07-16

Validated production main@df9dae774bad03c515ebb2c4b8545dfac198a4c7 on Windows NT 10.0.26200 with:

• Chrome 150.0.7871.46
• Edge 150.0.4078.65

Passed in both browsers

• Opened /en/install-app in an isolated browser profile and used the page Install now CTA to open the native browser install dialog.
• Invoked the native Install button through Windows UI Automation. This exercised the real browser UI install path; PWA.install was not used for acceptance.
• Confirmed the installed window reports matchMedia('(display-mode: standalone)').matches === true and browser mode false.
• Confirmed all six Byteflow cache buckets after warm-up.
• Confirmed offline installed-app workflows for JSON Formatter, HAR Viewer & Sanitizer, and Pipeline Builder.
• Confirmed an external-request tool keeps Preview disabled while offline and shows This external-request action needs network access. Reconnect and try again. together with the offline banner.
• Confirmed Install App cache clearing removes all Byteflow cache buckets (6 -> 0).
• Created a real waiting service worker using a same-origin /sw.js?manual-update-probe=<id> registration. The update prompt appeared, JSON input remained intact before user confirmation, and clicking Refresh activated the waiting worker and produced a reload navigation.
• Uninstalled the test PWAs and removed isolated profiles, shortcuts, and temporary registration state after validation.

Edge's CDP offline emulation resets across navigation, so its offline routes were each verified independently with online warm -> setOffline(true) -> assert navigator.onLine === false -> offline reload. The resulting standalone JSON/HAR/Pipeline and external-request checks passed. Chrome passed the equivalent continuous installed-app flow.

No Byteflow product defect was found in the desktop acceptance paths.

Remaining closure boundary

This does not satisfy the physical-device criteria. The native install dialog was operated by Windows UI Automation rather than a human mouse, network offline state was applied through browser CDP rather than Windows airplane mode, and the waiting worker used a same-origin query-URL probe rather than a real new deployment. This host still has no physical Android Chrome or iOS Safari session. Keep #260 open until the required Android and iPhone install-to-home-screen, standalone launch, airplane-mode offline, cache-clear, and real deployed-update evidence is recorded.

[baixiangcpp]

PR #340 merged via merge commit b570118; the #260 implementation is commit a2e2310.

Fixed a remaining install-state inconsistency:

• The global install CTA and Install App page now use the same display-mode, iOS standalone, and persisted appinstalled evidence reader.
• A normal browser-tab reload now shows both Install App CTAs as Already installed instead of incorrectly reporting that the install prompt is unavailable.
• A fresh beforeinstallprompt clears stale persisted evidence and restores both Install now CTAs.
• Storage-denied and server-render paths remain safely handled.

Evidence:

• 7 focused files / 40 tests passed.
• Real Chromium reload regression passed: 2 Already installed CTAs, then fresh prompt cleared the key and restored Install now.
• Full build and 1534-page export passed.
• Local and remote PWA smoke passed.
• Remote build (20.x), pwa, and Cloudflare Pages passed.
• Codex reviewed a2e2310 and found no major issues; independent review found no findings.

Keeping #260 open because the runbook still requires physical Android Chrome and iPhone Safari install-to-home-screen, standalone launch, airplane-mode offline, external-request messaging, cache clearing, and a real deployed service-worker update.