# Pathrule Pattern: PWA and Offline-First Service Workers (1.0.0) # ::pathrule:package:pwa-service-workers ### [RULE] Cache only responses with an explicit ownership policy (path: /src/service-worker) A service worker sees credentials, redirects, partial responses, and failures that ordinary static caching guidance does not cover. A broad cache-first handler can persist user-specific or invalid content across sessions. - Precache only build-owned immutable shell assets from a generated manifest; do not discover and cache arbitrary responses during install. - Use separate named caches for shell, public runtime data, and other bounded classes so deletion and retention policies cannot erase unrelated content. - Do not cache authenticated or user-specific responses unless the cache key and logout deletion contract isolate them by user and product policy explicitly permits storage. - Reject non-success, opaque, partial, and unexpectedly redirected responses from cache insertion unless the endpoint has a reviewed reason to keep them. See /src/offline for the adjacent decision or procedure that completes this constraint. --- ### [RULE] Replay offline mutations with stable operation identity (path: /src/offline) An offline client can submit the same queued command after browser restart, network ambiguity, or a failed acknowledgement. Without stable identity, one user action can create several orders, comments, or updates. - Assign the logical action an idempotency key before local acceptance and store that key with the queued payload and actor context. - Encrypt or avoid sensitive queued payloads according to the local-data policy, and remove them on sign-out or account removal. - Replay in dependency order with bounded retry and a terminal conflict state; do not loop forever on validation, authorization, or obsolete commands. - Reconcile the authoritative server result back into local state by operation identity and surface conflicts the product cannot merge automatically. See /tests/pwa for the adjacent decision or procedure that completes this constraint. --- ### [MEMORY] Activation is a compatibility negotiation with open clients (path: /src/service-worker) Calling immediate activation feels like a fast update, but it can put a new network proxy underneath an old JavaScript bundle. Requests, routes, and cached schemas may no longer agree. - Notify open clients that an update is waiting and let product policy choose a user prompt, safe reload point, or controlled mandatory refresh. - Use immediate activation only when the shell, API, cache, and local-data contracts are backward compatible across the open-client window. - Delete obsolete caches after activation with a version allowlist, while retaining assets still required by supported clients when compatibility demands it. - After controller change, reload or reinitialize the application through one deliberate path instead of letting half the view continue with the prior bundle. See /tests/pwa for the rule or workflow that puts this decision into practice. --- ### [MEMORY] Navigation fallback serves the application shell, not every failed request (path: /src/service-worker) A catch-all fallback that returns HTML for a missing script, JSON endpoint, or image turns a clear network error into confusing parse and content failures elsewhere in the application. - Check request mode, destination, method, and URL scope before using the application-shell fallback. - Exclude API, authentication, upload, payment, callback, and asset routes from document fallback unless each has an explicit offline representation. - Preserve server redirects and not-found behavior where the application does not own the route. - Provide a bounded offline document for navigations that cannot use the shell, and make its retry behavior independent from a stale cached application. See /src/offline for the rule or workflow that puts this decision into practice. --- ### [SKILL] test-pwa-update-and-offline (path: /) --- name: test-pwa-update-and-offline description: Test a PWA or service-worker release under lifecycle and network failure conditions. --- # Test Pwa Update And Offline Run this procedure when the affected surface changes, before the result is promoted to production. Record evidence for every step instead of accepting a plausible-looking result. 1. Install from a clean browser, load representative routes, then update while one old tab, one background tab, and one newly opened tab remain active. 2. Switch offline before and after install and verify shell, owned routes, excluded APIs, missing assets, and true not-found responses behave distinctly. 3. Queue mutations, terminate the tab or browser, reconnect, and prove replay uses stable identities and resolves conflicts without duplicate effects. 4. Sign out while private data and queued work exist, then confirm caches, storage, subscriptions, and replay permissions follow the privacy contract. 5. Corrupt or delete one cache generation and simulate a failed worker install; verify the previous working version remains usable and recovery does not require manual storage deletion. ## Exit criteria The change is complete only when the expected behavior, failure behavior, and rollback path have all been exercised with representative data. Preserve the evidence with the change so the next operator can repeat the same checks.