# Live Installability and Offline Verification Protocol

Use this reference for the step-by-step manual test procedure that turns a static-file read into an evidence-backed verdict, and for interpreting divergence between the Lighthouse PWA category score and live browser behavior.

## What people get wrong

The naive story is:

> "Lighthouse gave the PWA category a 100, so it's installable and offline-ready."

Wrong, or at least insufficient. Lighthouse's PWA audit historically diverges from live installability criteria for several documented reasons: it can run against a cached or stale service-worker state, it evaluates a fixed audit checklist that has changed across Lighthouse versions (some historical PWA-specific badge criteria were deprecated/removed from newer Lighthouse releases entirely), and — critically — it does not reproduce the actual `beforeinstallprompt` event firing in a live user session, which is the real signal a browser uses to decide whether to show an install affordance. A high Lighthouse score is a corroborating signal, not proof.

## Step-by-step protocol

### 1. Confirm HTTPS on the actual deployed origin

Check the origin Lighthouse (or any static review) was run against versus the actual production/target origin. It is a common gap for a review to validate a staging or preview URL that differs in TLS configuration from the real deployment target. Record this as `live evidence` only if checked against the real target origin; otherwise label `documentation-based` / `inference`.

### 2. Confirm service-worker registration reaches `activate`

In a real browser session (DevTools > Application > Service Workers), confirm:
- a service worker is listed for the correct scope,
- its status is `activated and is running` (not merely `installed` or stuck in `waiting`),
- there are no registration errors in the console (common causes of registration failure: scope mismatch between the registering script's location and the intended `scope`, a JavaScript error thrown during script evaluation, or an incorrect MIME type served for the service-worker script causing the browser to refuse it).

A service worker that never reaches `activate` cannot serve precached content or a fallback route, regardless of what the source code says it should do.

### 3. Listen for `beforeinstallprompt` directly

In a real browser session on the target origin, add a listener before any other interaction:

```js
window.addEventListener('beforeinstallprompt', (e) => {
  console.log('beforeinstallprompt fired', e);
});
```

If this event never fires despite all manifest and service-worker criteria appearing correct on paper, treat that as the authoritative negative signal and re-check (in order): `display` value, HTTPS on the exact origin under test, service-worker `activate` state, and whether the browser under test has already recorded a prior install/dismissal for this origin (some browsers suppress repeat prompts for a cooldown period after a user dismisses one — check for a documented per-browser dismissal-cooldown behavior before concluding the app itself is broken).

### 4. Offline-throttle navigation test (the non-negotiable step)

This is the step most reviews skip, and skipping it is the single most common cause of a false "offline-ready" verdict.

1. Load the app normally first (to allow the service worker to install/activate and precache assets).
2. In DevTools > Network, set throttling to **Offline** (not just slow 3G — must be a hard offline state to exercise the fallback path, not a slow-network path).
3. Navigate to a route the user has **not** previously visited in this session (revisiting an already-cached page proves only that specific page's cache entry works, not the fallback mechanism).
4. Observe what renders:
   - **The browser's default offline error page (e.g., the dinosaur game / "No internet" interstitial)** — the fallback route/catch-handler is missing, misconfigured, or the fallback document itself was not precached. This is a hard fail; report per `references/offline-fallback-precache-pattern.md`.
   - **The app's designed offline page** — record as `live evidence` pass. Additionally confirm the page rendered with its full intended styling/images (a fallback page that renders as unstyled HTML because its CSS was not precached is a partial fail, not a full pass).
5. While still offline, attempt navigation to a second previously-unvisited route to confirm the fallback is not a one-off fluke tied to a specific route's cache warm state.

### 5. Confirm the fallback page's own dependencies

With DevTools still offline, inspect the rendered fallback page's network panel for any failed sub-resource requests (fonts, inline API calls, tracking scripts). A fallback page that fails to render its intended appearance because of an uncached font or a blocking synchronous API call is a partial failure — report it distinctly from a fully missing fallback.

## Interpreting Lighthouse-vs-live divergence

| Lighthouse PWA signal | Live signal | Verdict |
|---|---|---|
| High score | `beforeinstallprompt` fires, offline test passes | Corroborated pass — cite both. |
| High score | `beforeinstallprompt` never fires | Live signal wins. Report the divergence explicitly and investigate `display`, origin mismatch, or per-browser dismissal-cooldown before concluding a manifest defect. |
| High score | Offline navigation shows default browser error page | Live signal wins. This is the checklist-theater failure mode this skill exists to catch — report as a blocker regardless of the Lighthouse score. |
| Low/missing score | Live signals pass | Investigate why Lighthouse diverges (stale audit run, outdated Lighthouse version, audit run against wrong origin) before treating the live pass as unreliable — a passing live test is still the stronger evidence. |

## Verdict discipline

Never present a Lighthouse score alone as proof of either installability or offline readiness in the final response. Every "offline-ready" or "installable" verdict in the response must cite the specific live test performed (service-worker activation check, `beforeinstallprompt` listener result, offline-throttle navigation outcome) as the primary evidence, with Lighthouse noted only as a secondary, corroborating data point.

# W3C Manifest Installability Checklist

Use this reference when validating a `manifest.json` field-by-field against W3C installability criteria, or when diagnosing why an install prompt never appears.

## What people get wrong

The common bad assumption is:

> "My `manifest.json` validates against the schema, so my app is installable."

That is incomplete. Schema validity (correct JSON shape, valid enum values) and installability (the specific subset of fields and runtime conditions a browser actually requires before it will fire `beforeinstallprompt`) are different bars. A manifest can be perfectly schema-valid and still never trigger an install prompt, because installability additionally depends on:

1. **transport** — the manifest and its origin must be served over HTTPS,
2. **service-worker presence** — most implementing browsers additionally require an active, fetch-handling service worker before treating the app as installable, not the manifest alone,
3. **specific field values**, not just field presence — a `display` value of `browser` is schema-valid but disqualifies the install flow by design.

## Field-by-field checklist (W3C manifest spec)

Work through each field and record a pass/fail with evidence label (`spec-cited`, `live evidence`, `documentation-based`, or `inference`):

- **`name` / `short_name`** — at least one must be present and non-empty; `short_name` is used where display space is constrained (home-screen label). Missing both is an outright installability blocker.
- **`icons`** — at least one icon meeting the browser's minimum size requirement (commonly a 192×192 and/or 512×512 PNG/SVG/WebP entry is expected by major implementations, though the spec itself does not hardcode a single universal minimum — cite the specific browser's documented threshold, do not assume one number applies everywhere). Check `purpose` values (`any`, `maskable`, `monochrome`) are correctly set — a maskable-only icon set with no `any` fallback can render badly on platforms that do not support maskable icons.
- **`start_url`** — must resolve to a same-origin (or explicitly permitted scope-relative) URL. Verify it is not a URL that 404s or redirects to a different origin.
- **`scope`** — must contain `start_url`. If `scope` is narrower than the app's actual navigable routes, navigations outside `scope` will open in a regular browser tab/window even from an installed app, breaking the installed-app experience.
- **`display`** — must be one of `standalone`, `fullscreen`, or `minimal-ui` for the app to be eligible for the install-prompt flow at all. `display: browser` is spec-valid but is explicitly the "opt out of app-like display" value; if found, treat it as a deliberate choice to confirm with the user, not a bug to silently patch.
- **`theme_color` / `background_color`** — not installability-blocking per spec, but their absence produces a visibly broken splash-screen/status-bar experience during install and first launch; flag as a quality issue, not a hard blocker.
- **`id`** (where supported) — used to distinguish app identity across updates to `start_url`; note if absent on a manifest that has changed `start_url` historically, since that can cause duplicate installs.

## HTTPS is not optional

The W3C manifest spec and every major implementing browser refuse to treat an app as installable over plain HTTP (the common documented exception is `localhost` for local development). This is a transport-layer precondition, not a manifest field — check it first, separately from the field-by-field pass, because no amount of manifest correctness compensates for a missing HTTPS origin.

## Service worker as a co-requirement

A manifest satisfying every field above does not by itself make most browsers fire `beforeinstallprompt`. The commonly documented additional requirement is a registered service worker that reaches the `activate` lifecycle state and handles at least the `fetch` event for the page. Confirm activation state directly (see `references/live-verification-protocol.md`) rather than assuming registration code in the source implies a running, activated worker in the deployed environment.

## Common false negatives to rule out before blaming the manifest

- The manifest `<link rel="manifest">` tag is present in HTML but points to a 404 or a path blocked by CSP/robots rules.
- The manifest is served with an incorrect `Content-Type` that the browser refuses to parse as a manifest.
- A framework PWA plugin (see `references/offline-fallback-precache-pattern.md`) generated a manifest with `display: browser` as its own default, unrelated to any explicit app configuration — verify the plugin's current documented default via Context7 before concluding the app team made this choice deliberately.

# Offline Fallback Precache Patterns

Use this reference when reviewing how an app's offline-fallback route is registered and guaranteed-precached, across hand-rolled Workbox, `vite-plugin-pwa`, and `next-pwa` conventions. Query Context7 for the specific plugin/version in scope before asserting a default (see the Context7 Documentation Protocol in `SKILL.md`) — the exact config keys and default file paths below are current as queried, but plugin defaults change across major versions.

## What people get wrong

The naive story is:

> "I have a service worker and it precaches my app shell, so offline works."

Wrong. Precaching an asset and having a route match a failed navigation to a fallback are two independent mechanisms. An app can precache a hundred files and still show the browser's default offline error page on every dropped-network navigation, because nothing registered a catch handler that serves a specific fallback document for failed `document`-destination requests. Conversely, an app can have a beautifully designed `/offline.html` page that is never precached, so the one time it is needed — when the network is down — the browser cannot fetch it either.

Both halves — a precached fallback document, and a route/catch-handler that serves it on navigation failure — must be verified independently.

## Officially grounded shape (per queried sources)

### Hand-rolled Workbox (`workbox-recipes` `offlineFallback` / `workbox-routing` `setCatchHandler`)

The documented pattern (`workbox-recipes/src/offlineFallback.ts`) sets a global catch handler keyed on `request.destination`:

- for `document` (navigation) requests, it looks up the fallback page first via `matchPrecache(pageFallback)`, then falls back to a secondary `workbox-offline-fallbacks` cache,
- optionally does the same for `image` and `font` destinations,
- returns `Response.error()` if neither matches — meaning if the fallback page itself was never precached and never separately cached, the catch handler produces a network error rather than a rendered page.

Review checklist for a hand-rolled implementation:
- Confirm the fallback page path passed to `offlineFallback()` (or an equivalent hand-written `setCatchHandler`) is one of the entries in the `precacheAndRoute()` manifest, not just a same-looking path.
- Confirm `precacheAndRoute()` was actually called (not just `precache()` alone) — `precache()` without `addRoute()`/`precacheAndRoute()` populates the cache but does not register the intercepting route, meaning normal navigations to precached pages would fall through to network first (relevant to caching-strategy review, but also affects whether the fallback lookup via `matchPrecache` finds a served entry).
- Confirm the catch handler is registered globally (`setCatchHandler`), not only on a subset of routes, or navigations outside those routes will surface the raw browser error page.

### `vite-plugin-pwa` (Vite / `generateSW` or `injectManifest`)

`vite-plugin-pwa` does not auto-designate an offline-fallback page by default — precache coverage is controlled by `workbox.globPatterns` (which files get swept into the precache manifest) and `workbox.maximumFileSizeToCacheInBytes` (default documented ceiling around 2 MiB; assets above it are silently excluded from precache even if `globPatterns` would otherwise match them). Review checklist:
- Confirm the offline-fallback HTML file's glob pattern is actually included in `globPatterns` (a common gap: `globPatterns: ['**/*.{js,css,html}']` looks like it covers an `offline.html`, but if the file lives outside the configured `public`/build output directory scanned by the plugin, it will not appear in the manifest).
- Confirm the fallback file is under the size ceiling, or that `maximumFileSizeToCacheInBytes` was explicitly raised for it.
- Because `vite-plugin-pwa` does not wire the catch-handler/fallback-routing logic for you by default under `generateSW`, confirm the project either uses `injectManifest` with a custom service-worker source implementing `offlineFallback`/`setCatchHandler`, or has added equivalent `runtimeCaching` navigation-fallback configuration. Do not assume "precached" implies "served as a navigation fallback" — verify the routing half separately, per the "what people get wrong" framing above.

### `next-pwa` (`@ducanh2912/next-pwa`)

This plugin's documented `fallbacks` option explicitly separates fallback routes by destination (`document`, `data`, `image`, `audio`, `video`, `font`), each pointing to a precached path, e.g.:

```js
fallbacks: {
  document: "/~offline",
  data: "/fallback.json",
  image: "/fallback.webp",
}
```

Its internal fallback handler (`self.fallback`) branches on `request.destination` and matches against those precached paths via `caches.match(fallbackResponse, { ignoreSearch: true })`, returning `Response.error()` if no destination-specific fallback is configured. Review checklist:
- If no explicit `fallbacks.document` is configured, confirm whether the project instead relies on the plugin's documented convention path (`pages/_offline.tsx` or `app/~offline/page.tsx`) — the plugin auto-wires a default at that conventional location if the file exists; absence of explicit config is not automatically a gap if the convention file is present.
- If neither explicit `fallbacks.document` nor the convention file exists, the app has no navigation fallback at all — this is the direct cause of a raw browser offline error page and should be reported as a blocker, not a style nit.
- Confirm the fallback path itself is excluded from any auth-gating middleware — a fallback route that requires authentication to render defeats its own purpose during an offline navigation.

## Minimal safe verification flow

1. Identify which of the three patterns above (hand-rolled Workbox, `vite-plugin-pwa`, `next-pwa`) the project uses; do not assume, check the dependency and config file.
2. Confirm the specific fallback document path is present in the generated/inspectable precache manifest (build output, or DevTools Application > Cache Storage after first load).
3. Confirm a catch-handler/fallback route actually exists and targets that exact path — not merely that the path is precached.
4. Run the live offline-throttle navigation test from `references/live-verification-protocol.md` to confirm the fallback actually renders end to end; steps 1–3 alone are necessary but not sufficient proof.

## High-risk assumptions to kill

- "It's in the precache manifest, so offline works." — precache and fallback-routing are separate mechanisms; both must be verified.
- "The plugin handles this by default." — only true for the specific documented convention path/config key for that plugin and version; verify via Context7, do not assume parity across `vite-plugin-pwa` and `next-pwa` defaults.
- "The fallback page has no external dependencies, so it's safe offline." — verify this; a fallback page pulling a web font from a CDN, or making an inline API call for personalization, fails exactly when offline.