The result you are building

Finished Result:

A PWA policy and test suite that defines which assets/data work offline, versions service-worker updates, queues only safe mutations, resolves conflicts, protects sensitive caches, and proves install, update, offline, reconnect, and recovery behavior.

Use this guide when

A web tool must work on unreliable mobile networks or be installable.
Users create drafts or actions while offline.
Service-worker caching currently causes stale releases or broken assets.

Do not use it as a substitute for

Caching every request, authenticated response, or API mutation by default.
Promising offline completion for actions that require current authorization, price, inventory, chain state, or server confirmation.

Before you change anything

Collect these items first. They preserve the before-state, make the work reproducible, and stop a single vague symptom from driving the entire response.

Supported browsers/devices, install scope, origin, manifest, and service-worker version.
Route/resource classification, cache key, TTL, version, size, sensitivity, and fallback.
Offline read/write contract, local data encryption, queue, idempotency, and conflict policy.
Update activation, migration, cache cleanup, storage pressure, logout, and revocation behavior.
Cold install, upgrade, airplane, flaky, duplicate, conflict, eviction, and recovery test evidence.

Stop Before Proceeding:

Do not queue or claim completion for payment, trading, account, recipient, permission, inventory, or other high-impact writes whose current server state and authorization cannot be verified.

Understand the system before fixing it

Observe before mutating Capture state, logs, versions, ownership, and dependency health before restarting, reinstalling, deleting, or rotating anything.

Recovery must be exercised A backup, rollback command, or spare endpoint is only a claim until a controlled restore or failover test proves it works.

Offline is a product contract State clearly what is available, how old it may be, which actions are only drafts/pending, and what requires reconnection.

Service workers can preserve broken releases Version assets atomically, handle old/new clients, avoid mixed bundles, and keep a recovery/unregister path.

Evidence-to-decision map

Start with the row that most closely matches the evidence. The first test isolates a layer; it is not permission to
make every available change.

   Evidence                   Likely layer     First decisive check             What the result means

   App breaks after           Version/updat    Inspect service worker and       Old shell references removed assets or mixed versions are
   deploy until cache         e                asset manifest versions          active.
   clear

   Offline write              Queue/idempo     Replay same local operation      Sync retries lack stable operation identity.
   duplicates on              tency            and server key
   reconnect

   Logged-out user            Sensitive        Test logout/revocation offline   Authenticated responses are stored without identity/lifecycle
   sees cached private        cache            and next user                    isolation.
   data

   Pending edit               Conflict         Compare base version and         Last-write-wins hides concurrent change.
   overwrites newer                            server revision
   server data

   Install works but          Precache/runti   Cold install, close, clear       Required shell/runtime dependencies were not cached correctly.
   offline first load fails   me               network, reopen

Step-by-step procedure

Work in order and retain the output from each step. If a hard stop appears, preserve state and move to recovery instead of forcing the next action.

01 Define the offline capability matrix Why: A precise boundary prevents a plausible fix from solving the wrong problem.

Do: For each route/action, declare online-only, cached read with max age, local draft, queued mutation, or unsupported; include security and business consequence.

Read the result: UI and docs accurately label available, stale, draft, pending, and confirmed states.