@ultimat3/pwa 19.1.3 → 19.3.1

package/CLAUDE.md

@@ -17,6 +17,8 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | Route input | `PwaRoute` is a **structural** view of render's `RouteDescriptor`. Never import render. |
 | Strategy choice | derived from render mode via `MODE_STRATEGY`. Per-route override only. |
 | Precache revision | content hash. Never the build id — that re-downloads everything per deploy. |
+| A truncation of author text | CODE POINTS, never `slice`. `short_name` falls back to the first 12 of `name`, and a UTF-16 `slice` cuts inside a surrogate pair — the lone half encodes as U+FFFD, so an app named with an emoji got a home-screen label ending in a replacement character. `Array.from(name).slice(0, n).join('')` is the form. |
+| Declared and never wired | `ServiceWorkerConfig.shellUrl` / `shellRevision` / `shellBytes` and `PwaRoute.dataUrl`. No caller in the framework's build path sets any of them, so `precache.ts`'s `reason: 'shell'` and `reason: 'route-data'` branches are reachable only from a hand-built `generateServiceWorker` call. Each doc comment now says so; the shell trio's said "precached for every `spa` route" while `spa` was already deleted from `RENDER_MODES`. **Kept, not deleted** — a public field is a major — and carried as candidates for the next major's declared-and-never-wired half. `revision` and `bytes` are the pair that IS fed, by the CLI's prerender pass. |
 | Every byte count and every threshold | a whole number of 0 or more, screened with `finiteCount` where it is READ — `buildPrecacheManifest`'s `warnBytes` AND each entry's own `bytes` (shell, route, asset), `createInstallController`'s `minEngagementMs`, `retentionPlan`'s `keep`. `totalBytes > warnBytes` is false when EITHER side is `NaN`, so one asset whose byte count did not arrive as a number took down the install-size warning for every other entry, silently, in the function whose output is otherwise byte-identical per commit; `now() - startedAt < NaN` is false at every instant, so the install prompt fired on first paint; and `Math.max(1, NaN)` is `NaN` with `slice(0, NaN)` `[]`, so a retention plan evicted every deploy including the running one. `Math.max` is not a validator — it propagates. `keep: 0` still means 1 (`version-skew.test.ts` pins it), so the floor is 0 everywhere here. `bun run finite-bounds` is the ratchet. |
 | Precache KEY | the bare URL, always. The revision addresses the FETCH (`?v=<hash>`), never the key: every strategy looks an entry up with `caches.match(req)` and `ignoreSearch` defaults to `false`, so an entry left keyed under `?v=` is a permanent miss — offline serves the fallback document instead of the precached page, and online every precached byte is downloaded twice. `addAll` still does the fetching, because its all-or-nothing failure is what stops a half-populated precache from activating; the install block only re-keys what it stored. `service-worker-runtime.test.ts` executes the emitted `sw.js` against stub `caches`/`fetch` rather than asserting its text. |
 | Precache FETCH | the revision is appended with `?` or `&`, picked per entry. `PrecacheAsset.url` is public API and a bundler emits `?v=<hash>` of its own, so a fixed `?` built `...?locale=en?v=<rev>`; `addAll` is all-or-nothing, so one non-200 there means `install` rejects and the worker never activates at all. |
@@ -25,11 +27,15 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | A byte count in a warning | `formatBytes` from `@ultimat3/core`, never a local one. The copy that lived in `precache.ts` stopped at `mb`, so a precache past a gigabyte reported a four-digit `mb` — and `@ultimat3/render`'s copy stopped at `kb`, so the two halves of one build printed different units for the same bytes. Still on this barrel: a size report is what a caller of this package prints. |
 | Cache names | always `cacheNamespace(buildId, kind)`. An unkeyed cache name is a rejected change. |
 | Offline fallback | `requireOfflineFallback` runs inside `generateServiceWorker`. Never optional. |
+| Its `fix:` names a route the framework accepts | `x g route offline --surface site   # then set pwa.offline.fallback to '/offline' in app.config.ts`. It said `create app/offline.tsx and set offline.fallback`, and BOTH halves were wrong: `<name>.tsx` is not a route file — `registerRoute` refuses it with `X_ROUTE_FILE_INVALID`, because the directory is the URL — and `offline.fallback` names no key `app.config.ts` has. A reader who followed it built a component nothing imports, left `/offline` a URL that does not exist, and met the same refusal on the next build; `wiki/Upgrading.md` had already recorded that path as the wrong one. `--surface site`, not `app`: the document answering a lost network must render with no network, no session and no database, which `app/` (`ssr \| stream`) cannot promise. `@ultimat3/cli`'s `doctor-offline.ts` writes the same line for the same code. |
+| The offline document's revision | `ServiceWorkerConfig.offlineFallbackRevision` / `offlineFallbackBytes`, forwarded to `buildPrecacheManifest`. `ServiceWorkerConfig` had no field for either, so the one page an offline navigation depends on was the single precache entry stamped with the **build id** — re-downloaded on every deploy, which the `Precache revision` row above forbids for everything else — and counted as **0 bytes** against `warnBytes`, under-counting the install by exactly the size of the page that has to survive a lost network. Unlike the shell trio, this pair is meant to be fed: the CLI's prerender pass holds both values. |
 | 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. |
 | 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. |
 | Colours | `@ultimat3/core`'s `PwaColors`, passed in as `WebManifestInput.tokens`. Never a hex literal in this package — a test fixture asserting the parser is the one exception. This package declared `ThemeTokens`/`SchemeColors` itself until 2026-08-27: structurally identical to what `app.config.ts` already carried, with no map between them and nothing asserting they agreed, which is the axiom-1 defect the two `PwaConfig`s were. Deleted; tier 0 owns the shape. |
 | `WebManifestInput` | what `generateWebManifest` takes, and **not** the `pwa` block of `app.config.ts` — it was called `PwaConfig` and said it was, while `@ultimat3/core` exported a different type of the same name that really is the block. An app declares `name` and `colors`; every other member is a caller's (`icons` from `planIcons`, `capabilities` from the build). `packages/cli/src/pwa-artifacts.ts` is the one composer of the two, and the only caller of `generateWebManifest` in the tree. |

package/README.md

@@ -55,7 +55,7 @@ detectSkew(clientBuildId, message.to); // 'current' | 'stale' | 'unknown'
 ```
 X_PWA_NO_OFFLINE_FALLBACK: no offline fallback route
   cause: app.config.ts has no `offline` block, so an offline navigation would show the browser's error page
-  fix:   create app/offline.tsx and set offline.fallback
+  fix:   x g route offline --surface site   # then set pwa.offline.fallback to '/offline' in app.config.ts
 ```
 
 `requireOfflineFallback(config)` runs inside `generateServiceWorker`, so the build fails

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/pwa",
-  "version": "19.1.3",
+  "version": "19.3.1",
   "description": "Generated service worker, web manifest, icons, push and version-skew handling.",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "19.1.3",
-    "@ultimat3/seo": "19.1.3"
+    "@ultimat3/core": "19.3.1",
+    "@ultimat3/seo": "19.3.1"
   }
 }

package/src/capabilities.ts

@@ -58,6 +58,10 @@ export const CAPABILITY_MANIFEST_KEYS = Object.freeze<Record<Capability, readonl
  * 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.
  *
+ * `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.
+ *
  * 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
  * already serves, so the member is the whole feature and the worker has no branch to add.
@@ -65,7 +69,7 @@ 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'],
+  backgroundSync: ["addEventListener('sync'", 'class PwaSyncError', "d.type==='flush-outbox'"],
   badging: ['navigator.setAppBadge'],
   shareTarget: [],
   fileHandlers: [],

package/src/manifest.ts

@@ -153,7 +153,7 @@ export function generateWebManifest(config: WebManifestInput): WebManifestResult
 
   const manifest: WebManifest = {
     name: config.name,
-    short_name: config.shortName ?? config.name.slice(0, 12),
+    short_name: config.shortName ?? shortNameFrom(config.name),
     start_url: config.startUrl ?? scope,
     scope,
     display: config.display ?? 'standalone',
@@ -179,6 +179,19 @@ export function generateWebManifest(config: WebManifestInput): WebManifestResult
 
 type MutableManifest = { -readonly [K in keyof WebManifest]?: WebManifest[K] };
 
+/** Home-screen labels are truncated by the OS well before this; the cap only bounds the string. */
+const SHORT_NAME_MAX_CODE_POINTS = 12;
+
+/**
+ * CODE POINTS, never `slice` — `String.prototype.slice` counts UTF-16 code units, so a name whose
+ * 12th unit is the high half of a surrogate pair (any emoji, any astral script) is cut mid
+ * character, and the lone surrogate that survives is what every UTF-8 encoder replaces with U+FFFD.
+ * The install prompt then offers a label ending in `` on the one surface a `short_name` exists for.
+ */
+function shortNameFrom(name: string): string {
+  return Array.from(name).slice(0, SHORT_NAME_MAX_CODE_POINTS).join('');
+}
+
 function assertValid(config: WebManifestInput): void {
   if (config.name.trim() === '') {
     throw new PwaManifestInvalidError(

package/src/offline-fallback.ts

@@ -23,11 +23,33 @@ export interface OfflineFallback {
   readonly neverCache: readonly string[];
 }
 
-const FIX = 'create app/offline.tsx and set offline.fallback';
+/**
+ * The edit, then the command — TWO actions, and neither is optional. It was `create
+ * app/offline.tsx and set offline.fallback`, and both halves were wrong: `<name>.tsx` is not a
+ * route file at all — `registerRoute` refuses it with `X_ROUTE_FILE_INVALID` because the
+ * directory is the URL — and `offline.fallback` names no key `app.config.ts` has. So a reader who
+ * followed this line literally created a component nothing imports, left `/offline` a URL that
+ * does not exist, and met the same refusal on the next build. `wiki/Upgrading.md` already recorded
+ * `apps/web/app/offline.tsx` as the wrong path.
+ *
+ * The edit comes FIRST, and the command is not the head of the line: with `x g route …   # then
+ * set …` the second half was a shell COMMENT, so the line read as one paste that does the whole
+ * job and did half of it — the route appeared, `pwa.offline.fallback` stayed unset, and the very
+ * next build raised this same error. A `fix:` that half-runs is worse than one that names two
+ * steps, because the reader has no signal that anything is left. The contract's own accepted
+ * shape is an edit naming its file (`set auth.signInPath = '/signin' in app.config.ts`).
+ *
+ * `--surface site`, and not `app`: the document that answers a lost network must render with no
+ * network, no session and no database, which `app/` (`ssr | stream`) cannot promise — and only a
+ * `static` route is prerendered, so an `app/` fallback has no document to precache at all. The
+ * command writes `apps/web/site/offline/page.tsx`, which is what `x new` scaffolds.
+ */
+const FIX =
+  "set pwa: { offline: { fallback: '/offline' } } in app.config.ts, then create the route it names: x g route offline --surface site";
 
 /**
  * Build-time gate, called by `generateServiceWorker` and by `x doctor`. The fix line is
- * the literal two-step edit, not a doc link.
+ * the config edit plus the command that creates the route it names, not a doc link.
  */
 export function requireOfflineFallback(
   config: Partial<OfflineConfig> | undefined | null,
@@ -49,7 +71,7 @@ export function requireOfflineFallback(
   if (!fallback.startsWith('/')) {
     throw new PwaNoOfflineFallbackError(
       `offline.fallback is ${JSON.stringify(fallback)}, which is not an absolute route path`,
-      `set offline.fallback to '/${fallback.replace(/^\/+/, '')}'`,
+      `set pwa.offline.fallback to '/${fallback.replace(/^\/+/, '')}' in app.config.ts`,
     );
   }
 

package/src/precache.ts

@@ -34,13 +34,31 @@ export interface PrecacheInput {
   readonly buildId: string;
   readonly routes: readonly PwaRoute[];
   readonly assets?: readonly PrecacheAsset[];
-  /** The app shell URL, precached for every `spa` route. */
+  /**
+   * A single document precached for every route, whatever its render mode — an app shell.
+   *
+   * **Nothing in the framework's build path sets this trio.** It said "precached for every `spa`
+   * route" until `As of 2026-09`, and `spa` was deleted from `RENDER_MODES` — so the sentence
+   * named a mode that cannot be declared, over a branch no caller reaches. Today the only way to
+   * a `reason: 'shell'` entry is a hand-built `generateServiceWorker` call: `x build`'s composer
+   * (`packages/cli/src/sw-artifacts.ts`) passes routes and assets and never a shell. Kept because
+   * deleting a public field is a major; a candidate for the next one's declared-and-never-wired
+   * sweep, with `PwaRoute.dataUrl`.
+   */
   readonly shellUrl?: string;
+  /** Defaults to `buildId`, which re-downloads the shell on every deploy. */
   readonly shellRevision?: string;
   readonly shellBytes?: number;
   /** The mandatory offline document. */
   readonly offlineFallbackUrl?: string;
+  /**
+   * Content hash of the built offline document. Absent, the entry is stamped with `buildId` and
+   * every deploy re-downloads the one page an offline navigation depends on — the rule this file's
+   * header states for every other entry, which this one had no field to obey.
+   */
   readonly offlineFallbackRevision?: string;
+  /** Byte size of the same document. Absent, it counts as 0 against `warnBytes`. */
+  readonly offlineFallbackBytes?: number;
   /** Warn past this total. Default 5 MB: past that, install stalls on a bad connection. */
   readonly warnBytes?: number;
 }
@@ -75,7 +93,7 @@ export function buildPrecacheManifest(input: PrecacheInput): PrecacheManifest {
     add({
       url: input.offlineFallbackUrl,
       revision: input.offlineFallbackRevision ?? input.buildId,
-      bytes: 0,
+      bytes: input.offlineFallbackBytes ?? 0,
       reason: 'fallback',
     });
   }

package/src/push.ts

@@ -66,6 +66,7 @@ export interface PushPayload {
   readonly tag?: string;
   readonly icon?: string;
   readonly badge?: string;
+  /** Alert again when the `tag` above is replaced. Ignored, with a warning, without one. */
   readonly renotify?: boolean;
   readonly requireInteraction?: boolean;
   readonly actions?: readonly { readonly action: string; readonly titleKey: string }[];
@@ -82,7 +83,11 @@ export interface RenderedNotification {
   readonly requireInteraction: boolean;
   readonly actions: readonly { readonly action: string; readonly title: string }[];
   readonly locale: string;
-  /** Missing-key markers (`⟦key⟧`) surfaced instead of being shipped to a user. */
+  /**
+   * What the composing server must see and the device must not: a missing-key marker (`⟦key⟧`),
+   * and a `renotify` dropped for want of a `tag`. Never serialized — `serializePushMessage` picks
+   * the wire fields by name.
+   */
   readonly warnings: readonly string[];
 }
 
@@ -102,14 +107,30 @@ export function renderPushPayload(
     return value;
   };
 
+  // `renotify` means "replace the notification carrying this tag and alert again", so the spec
+  // gives it no meaning without one: `showNotification` REJECTS with a `TypeError` and the device
+  // shows nothing at all. Dropped here rather than passed on, and reported rather than dropped in
+  // silence — a flag whose only effect is that the notification disappears is the shape this
+  // repository keeps re-shipping (`jobs.driver`, `PwaConfig.installPrompt`).
+  //
+  // The test is EMPTINESS, not presence: `tag` defaults to the empty DOMString in
+  // `NotificationOptions`, so `tag: ''` is the very pair the spec rejects and `!== undefined`
+  // waved it through — the guard reintroducing the `TypeError` it exists to prevent. `''` is also
+  // what a composing server produces from an unset collapse key, which is the common case.
+  const tag = payload.tag === undefined || payload.tag === '' ? undefined : payload.tag;
+  const renotify = (payload.renotify ?? false) && tag !== undefined;
+  if (payload.renotify === true && tag === undefined) {
+    warnings.push(`renotify needs a tag to replace — dropped for ${payload.titleKey}`);
+  }
+
   return {
     title: render(payload.titleKey),
     body: render(payload.bodyKey),
     url: payload.url,
-    tag: payload.tag ?? null,
+    tag: tag ?? null,
     icon: payload.icon ?? null,
     badge: payload.badge ?? null,
-    renotify: payload.renotify ?? false,
+    renotify,
     requireInteraction: payload.requireInteraction ?? false,
     actions: (payload.actions ?? []).map((action) => ({
       action: action.action,
@@ -152,8 +173,15 @@ export function pushSource(options: PushSourceOptions = {}): string {
   return `
 self.addEventListener('push',(event)=>{
   const d=event.data?event.data.json():{};
+  // renotify needs the tag: showNotification rejects with a TypeError when the flag is set and
+  // the tag is empty, and the device shows nothing. renderPushPayload refuses the pair too, but a
+  // push body is composed by whatever holds the VAPID key, so this is the last guard there is.
+  // A NON-EMPTY STRING, never truthiness: WebIDL converts every tag to a DOMString, and [] and {}
+  // are truthy in JS while converting to '' and '[object Object]'. !!d.tag therefore enabled
+  // renotify for a JSON [] whose converted tag is empty — the rejection this line exists to avoid.
+  const tg=typeof d.tag==='string'&&d.tag!==''?d.tag:undefined;
   const opts={body:d.body||'',icon:d.icon||${icon},badge:d.badge||${badge},
-    tag:d.tag||undefined,renotify:!!d.renotify,requireInteraction:!!d.requireInteraction,
+    tag:tg,renotify:!!d.renotify&&tg!==undefined,requireInteraction:!!d.requireInteraction,
     lang:d.lang||undefined,actions:d.actions||[],data:{url:d.url||'/'}};
   event.waitUntil(self.registration.showNotification(d.title||'',opts)${
     badging ? '.then(()=>navigator.setAppBadge&&navigator.setAppBadge())' : ''

package/src/service-worker.ts

@@ -35,9 +35,23 @@ export interface ServiceWorkerConfig {
   readonly offline: Partial<OfflineConfig>;
   readonly capabilities?: CapabilityFlags;
   readonly assets?: readonly PrecacheAsset[];
+  /**
+   * Forwarded verbatim to `buildPrecacheManifest`, which documents the whole trio: no caller in
+   * the framework's build path sets it, so `reason: 'shell'` is reachable only from a hand-built
+   * call to this function.
+   */
   readonly shellUrl?: string;
   readonly shellRevision?: string;
   readonly shellBytes?: number;
+  /**
+   * Content hash and byte size of the built offline document, forwarded to
+   * `buildPrecacheManifest`. Absent, the entry is stamped with the build id and counted as 0
+   * bytes — so the one page an offline navigation depends on is re-downloaded on every deploy,
+   * which is what `Precache revision` forbids for every other entry. Unlike the shell trio above,
+   * this pair is meant to be fed: the CLI's prerender pass already holds both values.
+   */
+  readonly offlineFallbackRevision?: string;
+  readonly offlineFallbackBytes?: number;
   readonly vapid?: VapidConfig;
   readonly backgroundSync?: BackgroundSyncOptions;
   /** Build ids whose caches must survive this activation (see `retentionPlan`). */
@@ -191,6 +205,14 @@ export function generateServiceWorker(
     ...(config.shellUrl === undefined ? {} : { shellUrl: config.shellUrl }),
     ...(config.shellRevision === undefined ? {} : { shellRevision: config.shellRevision }),
     ...(config.shellBytes === undefined ? {} : { shellBytes: config.shellBytes }),
+    // Spread, never assigned: `exactOptionalPropertyTypes` makes an explicit `undefined` a
+    // different answer from an absent key, and `?? input.buildId` is what reads it.
+    ...(config.offlineFallbackRevision === undefined
+      ? {}
+      : { offlineFallbackRevision: config.offlineFallbackRevision }),
+    ...(config.offlineFallbackBytes === undefined
+      ? {}
+      : { offlineFallbackBytes: config.offlineFallbackBytes }),
     ...(config.precacheWarnBytes === undefined ? {} : { warnBytes: config.precacheWarnBytes }),
   });
 
@@ -207,7 +229,7 @@ export function generateServiceWorker(
     INSTALL_BLOCK,
     activateBlock(),
     fetchBlock(),
-    messageBlock(),
+    messageBlock(isEnabled(capabilities, 'backgroundSync')),
   ];
 
   if (isEnabled(capabilities, 'push') && config.vapid !== undefined) {
@@ -388,11 +410,25 @@ async function healSkew(req,res){
 }`.trim();
 }
 
-function messageBlock(): string {
+/**
+ * The window → worker channel. `flush-outbox` is here and not in `backgroundSyncSource` because
+ * 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.
+ *
+ * Gated on the capability, because `flushOutbox` 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());"
+    : '';
   return `
 self.addEventListener('message',(event)=>{
   const d=event.data||{};
   if(d.type==='skip-waiting')self.skipWaiting();
-  if(d.type==='build-id')event.source&&event.source.postMessage({type:'build-id',buildId:BUILD_ID});
+  if(d.type==='build-id')event.source&&event.source.postMessage({type:'build-id',buildId:BUILD_ID});${flush}
 });`.trim();
 }

package/src/strategies.ts

@@ -32,10 +32,20 @@ export interface PwaRoute {
   readonly dynamic?: boolean;
   /** Explicit per-route override; wins over the derived strategy. */
   readonly strategy?: StrategyName;
-  /** Content hash of the built HTML — the precache revision. */
+  /**
+   * Content hash of the built HTML — the precache revision. Fed by the CLI's prerender pass; the
+   * `buildId` is the fallback, and it re-downloads every precached page on every deploy.
+   */
   readonly revision?: string;
+  /** Byte size of the built HTML, from the same prerender pass. Counted against `warnBytes`. */
   readonly bytes?: number;
-  /** Companion data endpoint precached alongside the HTML. */
+  /**
+   * Companion data endpoint precached alongside the HTML. **Nothing in the framework's build path
+   * sets it** — a hand-built `generateServiceWorker` call is the only route to a
+   * `reason: 'route-data'` entry, so the branch in `precache.ts` is unreachable in production.
+   * Kept because deleting a public field is a major; a candidate for the next one's
+   * declared-and-never-wired sweep, with `ServiceWorkerConfig`'s shell trio.
+   */
   readonly dataUrl?: string;
 }