@ultimat3/pwa 10.0.0 → 11.1.0

package/CLAUDE.md

@@ -26,7 +26,7 @@ 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 | queue lives in `@ultimat3/realtime`. This package only registers the sync trigger. |
+| 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. |
 | 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 | token values passed in via `PwaConfig.tokens`. Never a hex literal in this package — a test fixture asserting the parser is the one exception. |

package/README.md

@@ -93,7 +93,7 @@ capability nothing implements.
 | `planIcons`, `requireSourceIcon`, `maskableSafeZone` | icons and splashes from one source |
 | `BuiltinImagePipeline` | renders that plan: one square PNG per entry, deterministic |
 | `requireOfflineFallback` | the mandatory offline route |
-| `backgroundSyncSource`, `retryDelayMs` | the Background Sync trigger |
+| `backgroundSyncSource`, `registerBackgroundSyncSource` | the Background Sync trigger. No retry policy: the handler rejects and the PLATFORM reschedules it |
 | `renderPushPayload`, `pushSource`, `subscribeSource` | Web Push, per-locale bodies |
 | `createInstallController`, `iosInstallGuidance` | install prompt, never on first paint |
 | `PwaStrategyExhaustedError` and the other `errors.ts` classes | the codes this package throws, catchable by an app |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/pwa",
-  "version": "10.0.0",
+  "version": "11.1.0",
   "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": "10.0.0",
-    "@ultimat3/seo": "10.0.0"
+    "@ultimat3/core": "11.1.0",
+    "@ultimat3/seo": "11.1.0"
   }
 }

package/src/background-sync.ts

@@ -20,36 +20,19 @@ import { BUILD_ID_HEADER } from './version-skew';
 
 export const SYNC_TAG = 'x-outbox';
 
-export interface RetryPolicy {
-  readonly maxAttempts: number;
-  readonly baseDelayMs: number;
-  readonly maxDelayMs: number;
-}
-
-export const DEFAULT_RETRY: RetryPolicy = Object.freeze({
-  maxAttempts: 6,
-  baseDelayMs: 1_000,
-  maxDelayMs: 5 * 60 * 1000,
-});
-
 /**
- * Deterministic exponential backoff — no jitter here on purpose: the Background Sync
- * scheduler already spreads wake-ups across clients, and a deterministic delay is
- * testable and reproducible in a bug report.
+ * `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.
  */
-export function retryDelayMs(attempt: number, policy: RetryPolicy = DEFAULT_RETRY): number {
-  const clamped = Math.max(1, Math.min(attempt, policy.maxAttempts));
-  return Math.min(policy.baseDelayMs * 2 ** (clamped - 1), policy.maxDelayMs);
-}
-
-export function shouldRetry(attempt: number, policy: RetryPolicy = DEFAULT_RETRY): boolean {
-  return attempt < policy.maxAttempts;
-}
-
 export interface BackgroundSyncOptions {
   /** Endpoint `@ultimat3/realtime` exposes to flush the outbox. */
   readonly flushEndpoint?: string;
-  readonly retry?: RetryPolicy;
 }
 
 export const DEFAULT_FLUSH_ENDPOINT = '/_x/outbox/flush';
@@ -86,11 +69,9 @@ class PwaSyncError extends Error{
  */
 export function backgroundSyncSource(options: BackgroundSyncOptions = {}): string {
   const endpoint = options.flushEndpoint ?? DEFAULT_FLUSH_ENDPOINT;
-  const retry = options.retry ?? DEFAULT_RETRY;
   return `
 const SYNC_TAG=${JSON.stringify(SYNC_TAG)};
 const FLUSH_ENDPOINT=${JSON.stringify(endpoint)};
-const SYNC_MAX_ATTEMPTS=${retry.maxAttempts};
 ${SYNC_ERROR_CLASS}
 async function flushOutbox(){
   const res=await fetch(FLUSH_ENDPOINT,{method:'POST',headers:{${JSON.stringify(BUILD_ID_HEADER)}:BUILD_ID}});
@@ -98,7 +79,7 @@ async function flushOutbox(){
   // ||{} 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   # drain the outbox, or raise pwa.backgroundSync.retry.maxAttempts in app.config.ts');
+  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');
 }
 self.addEventListener('sync',(event)=>{
   if(event.tag!==SYNC_TAG)return;

package/src/index.ts

@@ -9,15 +9,12 @@ 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, RetryPolicy } from './background-sync';
+export type { BackgroundSyncOptions } from './background-sync';
 export {
   backgroundSyncSource,
   DEFAULT_FLUSH_ENDPOINT,
-  DEFAULT_RETRY,
   registerBackgroundSyncSource,
-  retryDelayMs,
   SYNC_TAG,
-  shouldRetry,
 } from './background-sync';
 export type { Capability, CapabilityFlags, ResolvedCapabilities } from './capabilities';
 export {

package/src/precache.ts

@@ -99,7 +99,12 @@ export function buildPrecacheManifest(input: PrecacheInput): PrecacheManifest {
     add({ url: asset.url, revision: asset.revision, bytes: asset.bytes, reason: 'asset' });
   }
 
-  const sorted = [...entries.values()].sort((a, b) => a.url.localeCompare(b.url));
+  // CODE UNITS, never `localeCompare`: these entries are emitted into `sw.js`, whose header
+  // promises byte-identical output for identical input, and `localeCompare` with no locale
+  // argument answers from the runtime's ICU default and collation version — two machines, two
+  // orders, one no-op deploy that fires the SW update check. Same rule as `service-worker.ts`'s
+  // rule tie-break and `@ultimat3/jobs`' `job.ts`.
+  const sorted = [...entries.values()].sort((a, b) => (a.url < b.url ? -1 : a.url > b.url ? 1 : 0));
   const totalBytes = sorted.reduce((sum, entry) => sum + entry.bytes, 0);
   const warnBytes = input.warnBytes ?? DEFAULT_PRECACHE_WARN_BYTES;
 

package/src/service-worker.ts

@@ -123,8 +123,14 @@ const hasWildcard = (path: string): boolean =>
  * install and then never looked up, and a route the app declared cacheable served `network-only`,
  * which offline is the `/offline` document.
  *
- * The path stays as the tie-break, so the emitted file is still byte-identical for identical input.
+ * The path stays as the tie-break, so the emitted file is still byte-identical for identical input
+ * — compared by CODE UNIT, never `localeCompare`, which answers from the runtime's ICU default and
+ * collation version: `/Posts` sorted before `/posts` on one machine and after it on the next, for
+ * the same route table. The rule `@ultimat3/jobs`' `job.ts` states for `x.manifest.json`, applied
+ * to the artifact this file emits.
  */
+const byCodeUnit = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
 export function routeRules(routes: readonly PwaRoute[]): readonly RouteRule[] {
   return [...routes]
     .filter((route) => route.surface !== 'api')
@@ -132,7 +138,7 @@ export function routeRules(routes: readonly PwaRoute[]): readonly RouteRule[] {
       (a, b) =>
         Number(hasWildcard(a.path)) - Number(hasWildcard(b.path)) ||
         specificityOf(b.path) - specificityOf(a.path) ||
-        a.path.localeCompare(b.path),
+        byCodeUnit(a.path, b.path),
     )
     .map((route) => {
       const strategy = strategyFor(route);