@ultimat3/pwa 9.0.0 → 10.0.0

package/CLAUDE.md

@@ -10,11 +10,13 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | Rule | Detail |
 |---|---|
 | `sw.js` | generated, never hand-written, never committed. No file in this package is a SW. |
-| Determinism | no `Date.now()`, no randomness, sort every collection. Same input → same bytes. |
+| Determinism | no `Date.now()`, no randomness, sort every collection. Same input → same bytes. `subscriptionState` took `now = Date.now()` and was the one exception; it takes a `Clock` `As of 2026-08-23`, so a frozen clock freezes this package too. |
+| Rule ORDER | most specific first, then the path. `ruleFor` in the emitted worker returns the FIRST pattern that matches and has no notion of specificity, so the sort IS the routing decision. Alphabetical, `:` (0x3A) and `*` (0x2A) sort before every letter: `/posts/:id` shadowed `/posts/new`, and one `/*` catch-all shadowed the whole table — every `PRECACHE_MANIFEST` entry downloaded at install and never looked up, and a cacheable route served `network-only`, which offline is the `/offline` document. Weights are `@ultimat3/render`'s `compilePattern` (literal 100, `:param` 10, `*` 1), **duplicated** because both packages are tier 4; a wildcard sorts last outright, because a sum over segments cannot say that `/` (0 segments) outranks `/*rest` (1). The shared home is `@ultimat3/core`'s `route-vocabulary.ts`. |
+| A generated header | names something that regenerates the file. `sw.js` said `regenerate: x build` and no `x build` target emits a service worker — `generateServiceWorker` has no caller anywhere in the tree — so it names the CALL until a build writes it. |
 | 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. |
-| 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.test.ts` executes the emitted `sw.js` against stub `caches`/`fetch` rather than asserting its text. |
+| 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. |
 | SW scope | `assertScope` refuses a relative `swPath`. `lastIndexOf('/')` on `sw.js` is `-1`, so the directory was `''` and `scope.startsWith('')` passed for every scope — the check waved through exactly the config most likely to be wrong. |
 | HTML sinks | one escaper: `escapeAttribute` from `@ultimat3/seo` (tier 1, and the only one reachable — render's `html.ts` is tier 4, sideways). `appleTouchLinks` and `renderThemeColorMeta` interpolate app config into attributes; both escape. Never a second escaper here. |

package/package.json

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

package/src/background-sync.ts

@@ -14,6 +14,7 @@
  * `UltimateError` does everywhere else in the framework.
  */
 
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import { PwaSyncFlushFailedError, PwaSyncIncompleteError } from './errors';
 import { BUILD_ID_HEADER } from './version-skew';
 
@@ -54,11 +55,13 @@ export interface BackgroundSyncOptions {
 export const DEFAULT_FLUSH_ENDPOINT = '/_x/outbox/flush';
 
 /**
- * Where the emitted class sends a reader. The same host `./errors.ts` documents these two codes
- * at — retyped here because the SW builds its URL from the code at throw time, and
- * `background-sync.test.ts` asserts the two halves still agree.
+ * 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_BASE = 'https://ultimate.dev/errors/';
+const SYNC_DOCS = ERROR_DOCS_URL;
 
 /**
  * The generated realm's own coded error, as source. Small on purpose — this ships in `sw.js` — and
@@ -70,7 +73,7 @@ const SYNC_DOCS_BASE = 'https://ultimate.dev/errors/';
 const SYNC_ERROR_CLASS = `
 class PwaSyncError extends Error{
   constructor(code,cause,fix){
-    const docs=${JSON.stringify(SYNC_DOCS_BASE)}+code;
+    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;
   }
@@ -92,7 +95,9 @@ ${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');
-  const body=await res.json().catch(()=>({remaining:0}));
+  // ||{} 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');
 }
 self.addEventListener('sync',(event)=>{

package/src/errors.ts

@@ -46,7 +46,12 @@ registerErrorCodes(
   Object.fromEntries(Object.entries(PWA_ERROR_TITLES).map(([code, title]) => [code, { title }])),
 );
 
-const docsFor = (code: PwaErrorCode): string => `https://ultimate.dev/errors/${code}`;
+// No `docs:` on the subclasses below. `UltimateError` fills it from `describeErrorCode(code).docs`,
+// which is `@ultimat3/core`'s `ERROR_DOCS_URL` — one page for every code, never one per code, because
+// `wiki/` is the framework's only public documentation surface and a code lives there in a TABLE ROW,
+// which has no anchor. The `https://ultimate.dev/errors/<code>` links this file built until 9.x
+// answered 404, host included, on every error it has ever thrown; restating the replacement here
+// would be the same constant in eight places waiting to drift again.
 
 /** No `app/offline.tsx`. You cannot ship a PWA that has nothing to show offline. */
 export class PwaNoOfflineFallbackError extends UltimateError {
@@ -56,7 +61,6 @@ export class PwaNoOfflineFallbackError extends UltimateError {
       code: PwaNoOfflineFallbackError.code,
       cause,
       fix,
-      docs: docsFor(PwaNoOfflineFallbackError.code),
     });
   }
 }
@@ -69,7 +73,6 @@ export class PwaIconMissingError extends UltimateError {
       code: PwaIconMissingError.code,
       cause,
       fix,
-      docs: docsFor(PwaIconMissingError.code),
     });
   }
 }
@@ -82,7 +85,6 @@ export class PwaManifestInvalidError extends UltimateError {
       code: PwaManifestInvalidError.code,
       cause,
       fix,
-      docs: docsFor(PwaManifestInvalidError.code),
     });
   }
 }
@@ -95,7 +97,6 @@ export class BuildIdMissingError extends UltimateError {
       code: BuildIdMissingError.code,
       cause,
       fix,
-      docs: docsFor(BuildIdMissingError.code),
     });
   }
 }
@@ -108,7 +109,6 @@ export class SwScopeInvalidError extends UltimateError {
       code: SwScopeInvalidError.code,
       cause,
       fix,
-      docs: docsFor(SwScopeInvalidError.code),
     });
   }
 }
@@ -125,7 +125,6 @@ export class PwaStrategyExhaustedError extends UltimateError {
       code: PwaStrategyExhaustedError.code,
       cause: `no cached response and the network failed for "${input.cacheName}"`,
       fix: 'pass options.fallback to staleWhileRevalidate(request, env, options), or set pwa.offline.fallback in app.config.ts',
-      docs: docsFor(PwaStrategyExhaustedError.code),
     });
   }
 }
@@ -144,7 +143,6 @@ export class PwaSyncFlushFailedError extends UltimateError {
       code: PwaSyncFlushFailedError.code,
       cause,
       fix,
-      docs: docsFor(PwaSyncFlushFailedError.code),
     });
   }
 }
@@ -157,7 +155,6 @@ export class PwaSyncIncompleteError extends UltimateError {
       code: PwaSyncIncompleteError.code,
       cause,
       fix,
-      docs: docsFor(PwaSyncIncompleteError.code),
     });
   }
 }
@@ -170,7 +167,6 @@ export class NotImplementedError extends UltimateError {
       code: NotImplementedError.code,
       cause,
       fix,
-      docs: docsFor(NotImplementedError.code),
     });
   }
 }

package/src/push.ts

@@ -6,6 +6,9 @@
  * is a real bug that users report as "the app is broken".
  */
 
+import type { Clock } from '@ultimat3/core';
+import { systemClock } from '@ultimat3/core';
+
 export interface VapidConfig {
   readonly publicKey: string;
   /** `mailto:` or an https URL — required by the spec, checked by every push service. */
@@ -30,13 +33,21 @@ export interface PushSubscriptionRecord {
 
 export type SubscriptionState = 'active' | 'expired' | 'gone';
 
-/** A 404/410 from the push service means the subscription is dead — delete it, don't retry. */
+/**
+ * A 404/410 from the push service means the subscription is dead — delete it, don't retry.
+ *
+ * `clock`, never `Date.now()`: this package's boundary says `Determinism | no Date.now()` without
+ * qualification, and an injectable default is still a wall-clock read living in the module. Every
+ * other "now" in the framework goes through a `Clock`, so a caller freezing time freezes this too
+ * rather than having to know that one function takes epoch milliseconds instead.
+ */
 export function subscriptionState(
   record: PushSubscriptionRecord,
   lastStatus: number | null,
-  now = Date.now(),
+  clock: Clock = systemClock,
 ): SubscriptionState {
   if (lastStatus === 404 || lastStatus === 410) return 'gone';
+  const now = clock.now().getTime();
   if (record.expirationTime !== null && record.expirationTime <= now) return 'expired';
   return 'active';
 }

package/src/service-worker.ts

@@ -84,10 +84,56 @@ export function assertScope(swPath: string, scope: string): void {
   }
 }
 
+const segmentsOf = (path: string): readonly string[] =>
+  path.split('/').filter((segment) => segment.length > 0);
+
+/**
+ * How specifically a path claims a URL: a literal segment beats a `:param`, which beats a `*`.
+ * The weights are `@ultimat3/render`'s `compilePattern`, verbatim (100 / 10 / 1), so the service
+ * worker and the server rank the same pathname the same way.
+ *
+ * DUPLICATED, not imported: `render` and `pwa` are both tier 4 and a sideways import is a build
+ * error. The shared home is `@ultimat3/core`'s `route-vocabulary.ts` — tier 0, already the owner of
+ * `RENDER_MODES` / `OFFLINE_STRATEGIES` / `HYDRATE_STRATEGIES` for exactly this reason — and moving
+ * it there is the follow-up this comment exists to name.
+ */
+function specificityOf(path: string): number {
+  return segmentsOf(path).reduce((total, segment) => {
+    if (segment.startsWith('*')) return total + 1;
+    if (segment.startsWith(':')) return total + 10;
+    return total + 100;
+  }, 0);
+}
+
+/**
+ * A catch-all is a FALLBACK, and it sorts behind every rule that is not one — a second key, because
+ * a sum over segments cannot say it. `/` has no segments and so scores 0, while `/*rest` scores 1:
+ * on specificity alone a single root catch-all outranks the home page, and with it every precached
+ * entry in the table. The rule this expresses is the one a reader already assumes — a pattern that
+ * matches everything answers only what nothing else claimed.
+ */
+const hasWildcard = (path: string): boolean =>
+  segmentsOf(path).some((segment) => segment.startsWith('*'));
+
+/**
+ * Ordered MOST SPECIFIC FIRST, because the emitted `ruleFor` returns the first pattern that
+ * matches and has no notion of specificity of its own. Sorted alphabetically it did not: `:` (0x3A)
+ * and `*` (0x2A) both sort before every letter, so `/posts/:id` shadowed `/posts/new` and a single
+ * `/*` catch-all shadowed the entire table — every entry in `PRECACHE_MANIFEST` downloaded at
+ * 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.
+ */
 export function routeRules(routes: readonly PwaRoute[]): readonly RouteRule[] {
   return [...routes]
     .filter((route) => route.surface !== 'api')
-    .sort((a, b) => a.path.localeCompare(b.path))
+    .sort(
+      (a, b) =>
+        Number(hasWildcard(a.path)) - Number(hasWildcard(b.path)) ||
+        specificityOf(b.path) - specificityOf(a.path) ||
+        a.path.localeCompare(b.path),
+    )
     .map((route) => {
       const strategy = strategyFor(route);
       return {
@@ -175,8 +221,13 @@ export function generateServiceWorker(
 }
 
 function header(buildId: string): string {
+  // `regenerate:` names the CALL, not a command: `x build` emits no service worker — nothing in
+  // the tree calls `generateServiceWorker` at all — so the line sent whoever found this file in a
+  // diff to a command that would leave it exactly as they found it. It becomes `x build` on the day
+  // the build actually writes this file, and not before.
   return `// GENERATED by @ultimat3/pwa from the route table — do not edit.
-// build: ${buildId}   regenerate: x build`;
+// build: ${buildId}
+// regenerate: generateServiceWorker(routes, config, buildId) from @ultimat3/pwa`;
 }
 
 function constants(