@ultimat3/pwa 20.2.0 → 21.0.0

package/CLAUDE.md

@@ -32,8 +32,11 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | Capabilities | gate the manifest member **and** the SW block, where the capability has one. Disabled → zero bytes. `push`, `backgroundSync` and `badging` emit worker code; `shareTarget`, `fileHandlers` and `protocolHandlers` are **manifest-only** — the OS delivers to a route the app already serves — and their `CAPABILITY_SW_MARKERS` list is empty, which `service-worker.test.ts` checks in both directions: every declared marker is in the worker when its capability is on, none is when they are all off. `shareTarget` named `/_x/share-target` there while no block emitted it. |
 | `AppUpdateAvailable` | declares exactly the fields the emitted `activate` block posts, and no more. `version-skew.test.ts` reads the literal back out of the generated source and compares it to a fixture typed `Required<AppUpdateAvailable>` — a field added to the interface stops compiling, a field added to the worker fails the assertion. It declared five and posted two until 9.0.0; the three extra described a forced reload nothing performed. |
 | Forced reload | **not a capability of this package.** `updateSignal`/`updatePolicy` computed `forced`/`deadlineAt` with no runtime caller and were deleted in 9.0.0. The two runtimes holding both build ids are BELOW this one — `http`'s `ctx.clientBuildId` (tier 2), `sync`'s `update-available` frame (tier 3) — so neither could ever have called into tier 4 to act on one. The app renders its own affordance; the framework never navigates a client. |
-| Outbox drain | TWO doors, and the second was missing for the framework's whole history: the `sync` event, and a `{type:'flush-outbox'}` message. `registerBackgroundSyncSource`'s fallback posts that message wherever `registration.sync` is absent — **Safari and Firefox** — and `messageBlock` answered only `skip-waiting` and `build-id`, so on exactly the browsers the fallback exists for an offline mutation queue was never drained: no rejection, no request, no log. The branch lives in the shared message handler rather than in `backgroundSyncSource`, so `CAPABILITY_SW_MARKERS.backgroundSync` carrying `d.type==='flush-outbox'` is what keeps it gated with the `flushOutbox` it calls — an ungated branch is a `ReferenceError` inside `waitUntil` in every app with the capability off. `service-worker-runtime.test.ts` posts the message and asserts the POST. |
-| Outbox | queue lives in `@ultimat3/realtime`. This package only registers the sync trigger — and schedules **no retry**: the handler rejects and the PLATFORM decides when to wake it again. `RetryPolicy`, `DEFAULT_RETRY`, `retryDelayMs`, `shouldRetry` and `BackgroundSyncOptions.retry` were deleted 2026-08-23; of the policy only `maxAttempts` ever reached the worker, as a `SYNC_MAX_ATTEMPTS` constant nothing read, and the emitted `X_PWA_SYNC_INCOMPLETE` fix told the reader to raise `pwa.backgroundSync.retry.maxAttempts`, a key `PwaConfig` has never had. `background-sync.test.ts` asserts that every constant the worker declares is one the worker reads. |
+| A cache copy is never awaited before answering | `Cache.put` reads the whole body, so a strategy that awaited it held a streamed (or slow) document away from the tab until it had ENDED. The emitted strategies hand the copy to `later(wait, …)` — the fetch event's `waitUntil` — and return the response at once. `service-worker-runtime.test.ts` streams a gated body and asserts the page reads the first chunk before it ends; its `StubCache.put` reads the whole body, as the real one does, or the test could not fail. |
+| A per-member document | NEVER served from cache while online, and partitioned by principal offline (21.0.0, security). The pages cache was keyed by URL alone, so `/feed` (`stream`, SWR) rendered for kenji answered bruno on a shared browser. The emitted strategies open caches through `openCache`; for `PAGES` that is a facade: a shareable response is stored and read as before, a PRIVATE one (`private`/`no-store`, or carrying `x-ultimate-scope` — `CLIENT_SCOPE_HEADER`, set by `@ultimat3/cli`'s `dev-render.ts` exactly where the scope meta is) is never read from `PAGES` and is kept only in `PAGES~<scope>`, written in the BACKGROUND (a stream's put would otherwise hold the navigation) and read only by `pageOffline`. Storing one principal's page deletes every other partition, so offline answers the most recent member only; private with no scope is not kept at all. `service-worker-runtime.test.ts` runs two members on one URL. |
+| The installing page | cached on `activate`. It loaded before the worker controlled it, so no strategy saw it and an `offline: 'runtime'` route was unavailable offline until a second online visit. After `clients.claim()` each controlled window's URL runs through its OWN route's strategy (`warm`) — only rules with `c: 'pages'`, same origin, not `NEVER_CACHE` — never a second caching rule. Best effort; a failed warm-up never fails activation. It runs AFTER activation, never inside its `waitUntil`: a fetch event waits for the worker to finish activating, so a warm-up copying a streamed page's whole body there held the claimed tab's every request — the `/feed` e2e hang. The offline page read (`pageOffline`) awaits it instead. `service-worker-runtime.test.ts` runs it. |
+| Outbox drain | the worker SENDS NOTHING, `As of 21.0.0`. The outbox is `@ultimat3/realtime`'s and lives in the page (IndexedDB), so the `sync` event — and the `{type:'flush-outbox'}` fallback message, posted by `registerBackgroundSyncSource` wherever `registration.sync` is absent (Safari, Firefox) — both run `drainOutbox`, which posts `OUTBOX_DRAIN_MESSAGE` (`@ultimat3/core`) to EVERY open window client; realtime's listener drains. No client open = the handler resolves and the next load drains; it never fakes work. `/_x/outbox/flush`, `DEFAULT_FLUSH_ENDPOINT`, and `BackgroundSyncOptions` were deleted, and `X_PWA_SYNC_FLUSH_FAILED` / `X_PWA_SYNC_INCOMPLETE` are still registered but thrown by nothing (shipped codes are stable forever): the worker POSTed to a route nothing in the framework ever mounted. The fallback branch lives in the shared message handler, so `CAPABILITY_SW_MARKERS.backgroundSync` carrying `d.type==='flush-outbox'` is what keeps it gated with the `drainOutbox` it calls. `background-sync.test.ts` and `service-worker-runtime.test.ts` run the emitted code and assert the posted messages. |
+| Outbox | queue, replay, retry and idempotency are all `@ultimat3/realtime`'s. This package only registers the sync trigger and schedules **no retry** — `RetryPolicy`, `DEFAULT_RETRY`, `retryDelayMs`, `shouldRetry` and `BackgroundSyncOptions.retry` were deleted 2026-08-23. |
 | Push strings | i18n keys only, rendered per subscriber locale. Never a literal. |
 | `renotify` | never without a `tag`, at BOTH ends. The Notifications spec makes `showNotification` reject with a `TypeError` for the pair, so the device shows **nothing** — the failure a `renotify: true` with no collapse key produces is the whole notification disappearing. `renderPushPayload` drops the flag and files a `warnings` entry (a knob with no effect is worse than no knob), and the emitted handler recomputes it as `!!d.renotify&&!!d.tag` because a push body is composed by whatever holds the VAPID key. `push.test.ts`'s `showNotification` stub throws the spec's TypeError, so a stub that tolerates the pair cannot go green. |
 | Push URLs | `PushPayload.url` is a PATH and `WindowClient.url` is absolute, so `notificationclick` resolves against `self.location.origin` before comparing. Unresolved, the focus-existing-tab loop matched nothing and every tap opened a second window. |
@@ -43,7 +46,7 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | Icon source | a **PNG** (core decodes PNG and JPEG only). `x new` scaffolds one; `@ultimat3/cli`'s `dev-assets.ts` reads it at `ICON_SOURCE` and serves every entry at its `outputPath`. This package renders bytes and mounts nothing. |
 | Icon background | `IconSourceConfig.background`, hex or `transparent` — core's grammar has no named colours. Default transparent. |
 | Errors | `errors.ts` subclasses only. `X_NOT_IMPLEMENTED` must carry a real `fix:`. |
-| Errors in `sw.js` | no bundler there, so no `UltimateError` import — the generated source defines its own class (`SYNC_ERROR_CLASS`) carrying `code`, `cause`, `fix`, `docs`. Never emit a bare `throw new Error`; the code stays owned by `errors.ts`. |
+| Errors in `sw.js` | no bundler there, so no `UltimateError` import. Never emit a bare `throw new Error`: a coded failure in the worker gets a code in `errors.ts` and a local class carrying `code`, `cause`, `fix`, `docs`. `As of 21.0.0` the emitted worker throws nothing of its own. |
 
 ```
 bun test                          # from packages/pwa

package/README.md

@@ -66,7 +66,7 @@ before an un-shippable PWA exists.
 | Capability | Manifest member | SW code |
 |---|---|---|
 | `push` | — | `push` + `notificationclick` listeners |
-| `backgroundSync` | — | `sync` listener + outbox flush |
+| `backgroundSync` | — | `sync` listener that tells every open tab to drain realtime's outbox (`OUTBOX_DRAIN_MESSAGE`) |
 | `badging` | — | `navigator.setAppBadge` after a push |
 | `shareTarget` | `share_target` | — |
 | `fileHandlers` | `file_handlers` | — |
@@ -119,7 +119,7 @@ capability nothing implements.
 - **Precache revisions are content hashes, never the build id.** Keying on the build id
   re-downloads every asset on every deploy.
 - **The mutation queue lives in `@ultimat3/realtime`, not here** (SRP). This package owns
-  only the Background Sync trigger that asks realtime to flush.
+  only the Background Sync trigger that tells the open tabs to drain it.
 - **Push bodies are rendered server-side per subscriber locale**, from the locale stored on
   the subscription. A notification in the wrong language is a real bug, and the sending
   server has no request context to infer one from.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/pwa",
-  "version": "20.2.0",
+  "version": "21.0.0",
   "description": "Generated service worker, web manifest, icons, push and version-skew handling.",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -31,7 +32,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "20.2.0",
-    "@ultimat3/seo": "20.2.0"
+    "@ultimat3/core": "21.0.0",
+    "@ultimat3/seo": "21.0.0"
   }
 }

package/src/background-sync.ts

@@ -1,94 +1,43 @@
 /**
- * Background Sync registration for the offline mutation queue.
+ * Background Sync: the browser-side TRIGGER for draining the offline outbox, and nothing else.
  *
- * SRP: the queue itself — the outbox, the optimistic local twins, the conflict policy —
- * belongs to `@ultimat3/realtime`. This file owns only the browser-side trigger: register
- * a sync tag, and when the platform says connectivity is back, ask realtime to flush.
- * Nothing here knows what a mutation is, and it must stay that way.
+ * The outbox itself — queued mutations, their idempotency keys, the replay over HTTP — is
+ * `@ultimat3/realtime`'s, and it lives in the PAGE (IndexedDB), because only the page holds the
+ * store, the principal and `clientTransport`. So when the platform says connectivity is back, the
+ * worker does not send anything itself: it posts `OUTBOX_DRAIN_MESSAGE` to every open window client
+ * and realtime's listener drains. One outbox, not two — until 21.0.0 the worker POSTed to
+ * `/_x/outbox/flush`, a route nothing in the framework ever mounted.
  *
- * The two failures below (`X_PWA_SYNC_FLUSH_FAILED`, `X_PWA_SYNC_INCOMPLETE`, documented in
- * `./errors.ts`) run inside the string emitted into `sw.js` — the browser's service-worker
- * realm, which has no bundler and cannot import `@ultimat3/core`. What it *can* have is a class
- * of its own, so `SYNC_ERROR_CLASS` emits one: a bare `Error` carries a message and nothing a
- * caller can read, while the emitted class exposes the same `code`, `cause`, `fix` and `docs` an
- * `UltimateError` does everywhere else in the framework.
+ * With NO client open there is nobody to drain, and the handler resolves rather than faking work:
+ * the queue is still in IndexedDB and the next page load replays it. Rejecting instead would only
+ * make the platform re-wake a worker that still has nobody to tell.
  */
 
-import { ERROR_DOCS_URL } from '@ultimat3/core';
-import { PwaSyncFlushFailedError, PwaSyncIncompleteError } from './errors';
-import { BUILD_ID_HEADER } from './version-skew';
+import { OUTBOX_DRAIN_MESSAGE } from '@ultimat3/core';
 
 export const SYNC_TAG = 'x-outbox';
 
 /**
- * `retry` was removed 2026-08-23, with `RetryPolicy`, `DEFAULT_RETRY`, `retryDelayMs` and
- * `shouldRetry`: **this package schedules no retry and never did.** The one-shot `sync` handler
- * rejects, and the PLATFORM decides when to wake it again — `flushOutbox` counts no attempts and
- * has nowhere to apply a delay. Of the policy only `maxAttempts` ever reached the worker, as a
- * `SYNC_MAX_ATTEMPTS` constant nothing read; the two exported functions were called by their own
- * test and by nothing else. Same rule as `PwaConfig.installPrompt` and `JobsConfig.driver`
- * (`packages/core/src/config.ts`): a knob that produces neither a build error nor a runtime effect
- * is worse than no knob, because an author sets it, ships, and nothing changes.
+ * Emitted into `sw.js` only when the `backgroundSync` capability is on. `drainOutbox` is also what
+ * the shared message handler calls for the page's `flush-outbox` fallback (`service-worker.ts`).
  */
-export interface BackgroundSyncOptions {
-  /** Endpoint `@ultimat3/realtime` exposes to flush the outbox. */
-  readonly flushEndpoint?: string;
-}
-
-export const DEFAULT_FLUSH_ENDPOINT = '/_x/outbox/flush';
-
-/**
- * Where the emitted class sends a reader — `@ultimat3/core`'s `ERROR_DOCS_URL`, interpolated into
- * the worker source rather than restated, because a URL retyped in a generated string is a second
- * constant that drifts silently. One page for every code, not one per code: `wiki/` is the
- * framework's only public documentation surface and a code lives there in a table row, which has no
- * anchor. `background-sync.test.ts` asserts the emitted value still equals what the registry says.
- */
-const SYNC_DOCS = ERROR_DOCS_URL;
-
-/**
- * The generated realm's own coded error, as source. Small on purpose — this ships in `sw.js` — and
- * deliberately not a bare `Error`: `code` is what a reporting hook groups on, `fix` is what the
- * developer in devtools acts on, and neither survives being flattened into a message alone. The
- * message still renders the contract's own line shape, because an uncaught `waitUntil` rejection
- * prints nothing else.
- */
-const SYNC_ERROR_CLASS = `
-class PwaSyncError extends Error{
-  constructor(code,cause,fix){
-    const docs=${JSON.stringify(SYNC_DOCS)};
-    super(code+': '+cause+'\\n  fix:   '+fix+'\\n  docs:  '+docs);
-    this.name='PwaSyncError';this.code=code;this.cause=cause;this.fix=fix;this.docs=docs;
-  }
-}`.trim();
-
-/**
- * Emitted into `sw.js` only when the `backgroundSync` capability is on. The handler posts
- * to realtime's flush endpoint; a non-2xx keeps the sync registration alive so the
- * platform retries with its own scheduling.
- */
-export function backgroundSyncSource(options: BackgroundSyncOptions = {}): string {
-  const endpoint = options.flushEndpoint ?? DEFAULT_FLUSH_ENDPOINT;
+export function backgroundSyncSource(): string {
   return `
 const SYNC_TAG=${JSON.stringify(SYNC_TAG)};
-const FLUSH_ENDPOINT=${JSON.stringify(endpoint)};
-${SYNC_ERROR_CLASS}
-async function flushOutbox(){
-  const res=await fetch(FLUSH_ENDPOINT,{method:'POST',headers:{${JSON.stringify(BUILD_ID_HEADER)}:BUILD_ID}});
-  if(!res.ok)throw new PwaSyncError(${JSON.stringify(PwaSyncFlushFailedError.code)},'outbox flush POST '+FLUSH_ENDPOINT+' returned '+res.status,'curl -i -X POST '+FLUSH_ENDPOINT+' — @ultimat3/realtime must mount it and answer 2xx');
-  // ||{} rather than a default inside the catch: json() on a 200 body of null RESOLVES with null,
-  // so the catch never fires and body.remaining raised inside waitUntil instead of refusing coded.
-  const body=(await res.json().catch(()=>null))||{};
-  if(body.remaining>0)throw new PwaSyncError(${JSON.stringify(PwaSyncIncompleteError.code)},'outbox flush at '+FLUSH_ENDPOINT+' left '+body.remaining+' mutation(s) queued','x dev --role sync   # run the role that drains the outbox; the browser reschedules this sync on its own');
+async function drainOutbox(){
+  const open=await self.clients.matchAll({type:'window',includeUncontrolled:true});
+  for(const c of open)c.postMessage({type:${JSON.stringify(OUTBOX_DRAIN_MESSAGE)}});
 }
 self.addEventListener('sync',(event)=>{
   if(event.tag!==SYNC_TAG)return;
-  // Rejecting keeps the registration so the platform retries on its own schedule.
-  event.waitUntil(flushOutbox());
+  event.waitUntil(drainOutbox());
 });`.trim();
 }
 
-/** Client-side registration. Falls back to an `online` listener where sync is missing. */
+/**
+ * Client-side registration. Where Background Sync is missing (Safari, Firefox) an `online`
+ * listener asks the worker instead, which answers every open tab — not only the one that noticed.
+ */
 export function registerBackgroundSyncSource(): string {
   return `
 export async function registerOutboxSync(registration){

package/src/capabilities.ts

@@ -55,12 +55,12 @@ export const CAPABILITY_MANIFEST_KEYS = Object.freeze<Record<Capability, readonl
 /**
  * The service-worker code each capability emits — its listener, and anything that listener alone
  * needs. Checked in BOTH directions (`service-worker.test.ts`): every marker is in the emitted
- * worker when its capability is on, and none of them is when they are all off. `PwaSyncError` is
- * the background-sync handler's own error class, so it ships with the handler and never without it.
+ * worker when its capability is on, and none of them is when they are all off. `drainOutbox` is
+ * the background-sync handler's broadcast, so it ships with the handler and never without it.
  *
  * `flush-outbox` is the same kind of pair the other way round: the branch lives in the shared
  * message handler, not in the capability's own block, so only its presence in this table keeps it
- * gated with the `flushOutbox` it calls.
+ * gated with the `drainOutbox` it calls.
  *
  * An EMPTY list is a claim too, and the true one for the three manifest-only capabilities: a share
  * target, a file handler and a protocol handler are all delivered by the OS to a URL the app
@@ -69,7 +69,11 @@ export const CAPABILITY_MANIFEST_KEYS = Object.freeze<Record<Capability, readonl
  */
 export const CAPABILITY_SW_MARKERS = Object.freeze<Record<Capability, readonly string[]>>({
   push: ["addEventListener('push'", "addEventListener('notificationclick'"],
-  backgroundSync: ["addEventListener('sync'", 'class PwaSyncError', "d.type==='flush-outbox'"],
+  backgroundSync: [
+    "addEventListener('sync'",
+    'async function drainOutbox',
+    "d.type==='flush-outbox'",
+  ],
   badging: ['navigator.setAppBadge'],
   shareTarget: [],
   fileHandlers: [],

package/src/errors.ts

@@ -13,6 +13,8 @@ export const PWA_OWNED_ERROR_CODES = [
   'X_BUILD_ID_MISSING',
   'X_SW_SCOPE_INVALID',
   'X_PWA_STRATEGY_EXHAUSTED',
+  // Shipped, so stable forever — and thrown by nothing since 21.0.0, when the worker stopped
+  // POSTing to `/_x/outbox/flush` (`background-sync.ts`). Registered so an old log still explains.
   'X_PWA_SYNC_FLUSH_FAILED',
   'X_PWA_SYNC_INCOMPLETE',
 ] as const;
@@ -129,36 +131,6 @@ export class PwaStrategyExhaustedError extends UltimateError {
   }
 }
 
-/**
- * Titles one of the two failures `backgroundSyncSource()` emits into `sw.js`, and owns the `code`
- * the emitted source throws. The generated code runs in the browser's service-worker realm, which
- * has no bundler and no `@ultimat3/core` to import — so it defines a local `PwaSyncError` carrying
- * this same code, cause, fix and docs rather than constructing this class. This class is what gives
- * the code one title and one wiki row, the same as every other code in this file.
- */
-export class PwaSyncFlushFailedError extends UltimateError {
-  static readonly code = 'X_PWA_SYNC_FLUSH_FAILED' as const;
-  constructor(cause: string, fix: string) {
-    super({
-      code: PwaSyncFlushFailedError.code,
-      cause,
-      fix,
-    });
-  }
-}
-
-/** Documented for the same reason as {@link PwaSyncFlushFailedError} — see its comment. */
-export class PwaSyncIncompleteError extends UltimateError {
-  static readonly code = 'X_PWA_SYNC_INCOMPLETE' as const;
-  constructor(cause: string, fix: string) {
-    super({
-      code: PwaSyncIncompleteError.code,
-      cause,
-      fix,
-    });
-  }
-}
-
 /** A driver whose interface exists and whose backing implementation does not, yet. */
 export class NotImplementedError extends UltimateError {
   static readonly code = 'X_NOT_IMPLEMENTED' as const;

package/src/index.ts

@@ -9,10 +9,8 @@ export type { OfflineStrategy, RenderMode } from '@ultimat3/core';
 // Moved to `@ultimat3/core` (one formatter, `b`/`kb`/`mb`/`gb`); still named here because a service
 // worker's size report is what a caller of this package prints.
 export { formatBytes } from '@ultimat3/core';
-export type { BackgroundSyncOptions } from './background-sync';
 export {
   backgroundSyncSource,
-  DEFAULT_FLUSH_ENDPOINT,
   registerBackgroundSyncSource,
   SYNC_TAG,
 } from './background-sync';

package/src/pages-cache-source.ts

@@ -0,0 +1,56 @@
+/**
+ * The emitted worker's page storage, as source: the facade every strategy opens the pages cache
+ * through, the per-principal partitions a private document is kept in, the background copy, and
+ * the offline read. Its own module because `service-worker.ts` is the rest of `sw.js`; it is
+ * spliced into the fetch block and reads that block's constants (`PAGES`, `SCOPE_HEADER`) and
+ * `warming` from the activate block. `service-worker-pages.test.ts` runs it.
+ */
+
+export const PAGES_CACHE_SOURCE = `// The pages cache is a FACADE, because a document rendered for one member is not a page: keyed by
+// URL alone, /feed rendered for kenji answered bruno on the same browser. A shareable document is
+// stored and read as before. A private one (\`private\`/\`no-store\`, or carrying the scope header)
+// is never read from here — so no strategy can answer it from cache while online — and is kept
+// only in its principal's own partition, PAGES~<scope>, which offline alone reads. Storing one
+// principal's page wipes every other partition: offline answers the most recent member only.
+function openCache(cn){return cn===PAGES?pagesCache():caches.open(cn)}
+// A cache copy the strategy does NOT await: handed to the event's waitUntil when there is one, and
+// never allowed to reject into nobody — a failed copy costs the copy, not the response.
+function later(wait,p){const settled=p.catch(()=>{});if(wait)wait(settled);return settled}
+function isPrivate(r){
+  if(r.headers.has(SCOPE_HEADER))return true;
+  return /(^|,)\\s*(private|no-store)\\s*(,|$)/i.test(r.headers.get('cache-control')||'')
+}
+function pagesCache(){return{
+  match:async(req)=>(await caches.open(PAGES)).match(req),
+  put:async(req,r)=>{
+    if(!isPrivate(r))return (await caches.open(PAGES)).put(req,r);
+    const scope=r.headers.get(SCOPE_HEADER);
+    // Private with no scope: no principal to file it under, so it is not kept at all.
+    if(scope===null)return;
+    // NOT awaited by the strategy: a private document is usually a stream, and a strategy awaits
+    // its put before answering — the navigation would wait for the whole body to be copied into
+    // the cache. The offline read waits for it instead (pageOffline), which is the only reader.
+    keeping=keeping.then(()=>keepScoped(req,r,PAGES+'~'+scope)).catch(()=>{});
+  }
+}}
+let keeping=Promise.resolve();
+async function keepScoped(req,r,name){
+  await (await caches.open(name)).put(req,r);
+  const names=await caches.keys();
+  await Promise.all(names.filter((n)=>n.startsWith(PAGES+'~')&&n!==name).map((n)=>caches.delete(n)));
+}
+/** Offline only: the most recent member's own copy, then the offline document. */
+async function pageOffline(req){
+  await warming;
+  await keeping;
+  // The shared copy first — a warm-up may have landed it after the strategy's own read missed.
+  const shared=await (await caches.open(PAGES)).match(req);
+  if(shared)return shared;
+  for(const n of await caches.keys()){
+    if(!n.startsWith(PAGES+'~'))continue;
+    const hit=await (await caches.open(n)).match(req);
+    if(hit)return hit;
+  }
+  return offlineFallback(req)
+}
+function fallbackFor(rule,req){return rule.c==='pages'?()=>pageOffline(req):()=>offlineFallback(req)}`;

package/src/service-worker.ts

@@ -8,13 +8,14 @@
  * update check does not fire on a no-op deploy.
  */
 
-import type { BackgroundSyncOptions } from './background-sync';
+import { CLIENT_SCOPE_HEADER } from '@ultimat3/core';
 import { backgroundSyncSource } from './background-sync';
 import type { CapabilityFlags, ResolvedCapabilities } from './capabilities';
 import { isEnabled, resolveCapabilities } from './capabilities';
 import { SwScopeInvalidError } from './errors';
 import type { OfflineConfig } from './offline-fallback';
 import { offlineFallbackSource, requireOfflineFallback } from './offline-fallback';
+import { PAGES_CACHE_SOURCE } from './pages-cache-source';
 import type { PrecacheAsset, PrecacheManifest } from './precache';
 import { buildPrecacheManifest, serializePrecacheManifest } from './precache';
 import type { VapidConfig } from './push';
@@ -53,7 +54,6 @@ export interface ServiceWorkerConfig {
   readonly offlineFallbackRevision?: string;
   readonly offlineFallbackBytes?: number;
   readonly vapid?: VapidConfig;
-  readonly backgroundSync?: BackgroundSyncOptions;
   /** Build ids whose caches must survive this activation (see `retentionPlan`). */
   readonly retainBuildIds?: readonly string[];
   readonly precacheWarnBytes?: number;
@@ -236,7 +236,7 @@ export function generateServiceWorker(
     blocks.push(pushSource({ badging: isEnabled(capabilities, 'badging') }));
   }
   if (isEnabled(capabilities, 'backgroundSync')) {
-    blocks.push(backgroundSyncSource(config.backgroundSync ?? {}));
+    blocks.push(backgroundSyncSource());
   }
 
   return {
@@ -275,6 +275,7 @@ const PAGES=${JSON.stringify(cacheNamespace(buildId, 'pages'))};
 const RETAINED=${JSON.stringify(retainedCaches(retained))};
 const NEVER_CACHE=${JSON.stringify(neverCache)};
 const BUILD_HEADER=${JSON.stringify(BUILD_ID_HEADER)};
+const SCOPE_HEADER=${JSON.stringify(CLIENT_SCOPE_HEADER)};
 let SKEWED=false;`.trim();
 }
 
@@ -335,8 +336,32 @@ self.addEventListener('activate',(event)=>{
     await self.clients.claim();
     const cs=await self.clients.matchAll({type:'window'});
     for(const c of cs)c.postMessage({type:${JSON.stringify(APP_UPDATE_AVAILABLE)},to:BUILD_ID});
+    // NOT part of this waitUntil: a fetch event waits for the worker to finish ACTIVATING, so a
+    // warm-up that copies a streamed page's whole body in here held every request of the tab it
+    // just claimed — /feed's own reads included — until that body had ended. Kicked off, never
+    // awaited; the one reader that needs it done, the offline page read, waits for it.
+    warming=Promise.all(cs.map((c)=>warm(c.url))).catch(()=>{});
   })());
-});`.trim();
+});
+let warming=Promise.resolve();
+// The page that installed this worker loaded BEFORE the worker controlled it, so no strategy ever
+// saw it and a runtime-cached route was unavailable offline until a second online visit. Now that
+// the worker controls the window, its URL is run through its own route's strategy — the same rule
+// that caches every later visit, never a second one. Best effort: a failure costs the warm-up only.
+async function warm(href){
+  if(typeof href!=='string')return;
+  const url=new URL(href);
+  if(url.origin!==self.location.origin||NEVER_CACHE.some((p)=>url.pathname.startsWith(p)))return;
+  const rule=ruleFor(url);
+  if(!rule||rule.c!=='pages')return;
+  const fn=STRATEGIES[rule.s];
+  if(!fn)return;
+  const req=new Request(url.href,{headers:withBuild(new Headers())});
+  const copies=[];
+  // The plain offline document, never pageOffline: that one waits for THIS warm-up to finish.
+  try{await fn(req,cacheName(rule.c),()=>offlineFallback(req),(p)=>copies.push(p))}catch(e){}
+  await Promise.all(copies);
+}`.trim();
 }
 
 /**
@@ -370,6 +395,7 @@ function ruleFor(url){
   return null
 }
 function cacheName(kind){return kind==='precache'?PRECACHE:kind==='pages'?PAGES:RUNTIME}
+${PAGES_CACHE_SOURCE}
 const STRATEGIES={cacheFirst:typeof cacheFirst==='function'?cacheFirst:null,
   networkFirst:typeof networkFirst==='function'?networkFirst:null,
   staleWhileRevalidate:typeof staleWhileRevalidate==='function'?staleWhileRevalidate:null,
@@ -386,7 +412,7 @@ self.addEventListener('fetch',(event)=>{
   if(!fn)return;
   // Every proxied request carries the client's build id so the server can detect skew.
   const tagged=new Request(req,{headers:withBuild(req.headers)});
-  event.respondWith(fn(tagged,cacheName(rule.c),()=>offlineFallback(req)).then((res)=>healSkew(req,res)));
+  event.respondWith(fn(tagged,cacheName(rule.c),fallbackFor(rule,req),(p)=>event.waitUntil(p)).then((res)=>healSkew(req,res)));
 });
 function withBuild(headers){
   const h=new Headers(headers);
@@ -415,15 +441,16 @@ async function healSkew(req,res){
  * the page is what sends it: `registerOutboxSync` falls back to an `online` listener posting this
  * message wherever `registration.sync` is absent — Safari and Firefox — and with no branch for it
  * the offline mutation queue was never drained on exactly the browsers the fallback exists for.
- * Silent, too: no rejection, no request, no log.
+ * Silent, too: no rejection, no request, no log. The worker answers it by telling EVERY open tab
+ * to drain (`drainOutbox`), because the outbox lives in the pages, not here.
  *
- * Gated on the capability, because `flushOutbox` is only emitted with `backgroundSyncSource`. An
+ * Gated on the capability, because `drainOutbox` is only emitted with `backgroundSyncSource`. An
  * unconditional branch would answer the message with a `ReferenceError` inside `waitUntil`, which
  * the page that sent it cannot catch, in every app that leaves `backgroundSync` off.
  */
 function messageBlock(backgroundSync: boolean): string {
   const flush = backgroundSync
-    ? "\n  if(d.type==='flush-outbox')event.waitUntil(flushOutbox());"
+    ? "\n  if(d.type==='flush-outbox')event.waitUntil(drainOutbox());"
     : '';
   return `
 self.addEventListener('message',(event)=>{

package/src/strategies.ts

@@ -194,26 +194,31 @@ async function fallbackOrThrow(options: StrategyOptions): Promise<Response> {
 /**
  * The emitted counterpart of the functions above. Kept as source strings because the
  * service worker is a generated artifact with no bundler in the loop — the shapes are
- * identical on purpose and `strategies.test.ts` asserts both halves stay in step.
+ * identical on purpose and `strategies.test.ts` asserts both halves stay in step. They open a
+ * cache through the worker's `openCache`, never `caches.open`: the pages cache is a facade that
+ * partitions a per-member document by principal (`service-worker.ts`, `pagesCache`). And the cache
+ * copy is NEVER awaited before answering: `Cache.put` reads the whole body, so awaiting it held a
+ * streamed document away from the tab until it had ended. It goes to `later(wait, …)` instead —
+ * the fetch event's `waitUntil`, which keeps the worker alive for the copy.
  */
 export const STRATEGY_SOURCE = Object.freeze<Record<StrategyName, string>>({
-  'cache-first': `async function cacheFirst(req,cn,fb){
-  const c=await caches.open(cn);const hit=await c.match(req);if(hit)return hit;
-  try{const r=await fetch(req);if(r.ok)await c.put(req,r.clone());return r}catch(e){if(fb)return fb();throw e}
+  'cache-first': `async function cacheFirst(req,cn,fb,wait){
+  const c=await openCache(cn);const hit=await c.match(req);if(hit)return hit;
+  try{const r=await fetch(req);if(r.ok)later(wait,c.put(req,r.clone()));return r}catch(e){if(fb)return fb();throw e}
 }`,
-  'network-first': `async function networkFirst(req,cn,fb){
-  const c=await caches.open(cn);
-  try{const r=await fetch(req);if(r.ok)await c.put(req,r.clone());return r}
+  'network-first': `async function networkFirst(req,cn,fb,wait){
+  const c=await openCache(cn);
+  try{const r=await fetch(req);if(r.ok)later(wait,c.put(req,r.clone()));return r}
   catch(e){const hit=await c.match(req);if(hit)return hit;if(fb)return fb();throw e}
 }`,
-  'stale-while-revalidate': `async function staleWhileRevalidate(req,cn,fb){
-  const c=await caches.open(cn);const hit=await c.match(req);
-  const refresh=fetch(req).then(async(r)=>{if(r.ok)await c.put(req,r.clone());return r})
+  'stale-while-revalidate': `async function staleWhileRevalidate(req,cn,fb,wait){
+  const c=await openCache(cn);const hit=await c.match(req);
+  const refresh=fetch(req).then((r)=>{if(r.ok)later(wait,c.put(req,r.clone()));return r})
     .catch(()=>hit||(fb?fb():Response.error()));
   if(hit){refresh.catch(()=>{});return hit}
   return refresh
 }`,
-  'network-only': `async function networkOnly(req,cn,fb){
+  'network-only': `async function networkOnly(req,cn,fb,wait){
   try{return await fetch(req)}catch(e){if(fb)return fb();throw e}
 }`,
 });

package/src/version-skew.ts

@@ -10,11 +10,12 @@
  * The app decides what to do with that message. This package never navigates a client.
  */
 
-import { finiteCount } from '@ultimat3/core';
+import { APP_UPDATE_MESSAGE, CLIENT_BUILD_META, finiteCount } from '@ultimat3/core';
 import { BuildIdMissingError } from './errors';
 
 export const BUILD_ID_HEADER = 'x-ultimate-build';
-export const BUILD_ID_META = 'x-ultimate-build';
+/** Shipped name for core's `CLIENT_BUILD_META` — the meta render writes, one literal for both. */
+export const BUILD_ID_META = CLIENT_BUILD_META;
 
 export type DeployChannel = 'production' | 'preview' | 'branch';
 
@@ -136,9 +137,10 @@ export function detectSkew(
  * the literal the worker emits, so the two can no longer differ.
  */
 export interface AppUpdateAvailable {
-  readonly type: 'AppUpdateAvailable';
+  readonly type: typeof APP_UPDATE_MESSAGE;
   /** The build the worker that posted this was generated for. */
   readonly to: string;
 }
 
-export const APP_UPDATE_AVAILABLE = 'AppUpdateAvailable' as const;
+/** Shipped name for core's `APP_UPDATE_MESSAGE` — one literal for the worker and the page. */
+export const APP_UPDATE_AVAILABLE = APP_UPDATE_MESSAGE;