@ultimat3/pwa 23.0.0 → 24.0.0

package/CLAUDE.md

@@ -11,14 +11,15 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 |---|---|
 | `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. `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`. |
+| 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. The order is `@ultimat3/core`'s `routeRank` — the ONE route precedence, also `@ultimat3/render`'s `CompiledPattern.specificity`: the request router's order, segment by segment. Never a local copy, never a sum. |
 | A generated header | names something that regenerates the file. `sw.js` says `regenerate: x build`, and `As of 2026-08` a build really writes it (#390); it named the CALL for as long as none did. |
 | What is WIRED, and what is not | **every generator here has a caller, `As of 2026-08`.** `generateWebManifest`, `renderThemeColorMeta`, `planIcons`, `appleTouchLinks` and `BuiltinImagePipeline` through `pwa-artifacts.ts` / `dev-assets.ts` (#362); `generateServiceWorker` — and with it `buildPrecacheManifest`, `offlineFallbackSource`, `backgroundSyncSource` and `pushSource` — through `sw-artifacts.ts` (#390). So `x dev`, the container and the static export emit `manifest.webmanifest`, `sw.js` and `x-sw-register.js` alike. The worker half landed a release later because a bad `sw.js` is sticky: it waited on a real browser check (`packages/cli/e2e/service-worker.e2e.test.ts`), which nothing in the gate could run until #400. **`pwa.push` is the one capability still unwired** — the generator emits a push handler only when a VAPID key comes with it and there is no `pwa.vapid` config key, so `x build` reports it as a `serviceWorkerWarnings` entry rather than dropping it in silence. |
 | 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. Every row is `network-first` `As of 22.3.2`: every rule is a DOCUMENT, and `static: 'cache-first'` / `isr`,`stream: 'stale-while-revalidate'` answered online navigations with the old deploy's HTML (and so its old hashed assets) until Shift+F5. Precache ≠ cache-first — the precached copy is the offline answer. |
 | Worker update | `self.skipWaiting()` in `install`, `As of 22.3.2` — worker-side, because the browsers that must converge run a 22.3.1 worker and register script that never post `skip-waiting`. Safe for an open tab: the worker routes no chunk. Never a reload — the next navigation is fresh. The `skip-waiting` message stays. |
 | Navigation preload | enabled on `activate`; every emitted strategy reaches the network through `net(req,pre)` (`NETWORK_SOURCE`), never a bare `fetch`, so a navigation is answered by `event.preloadResponse`. The preload carries no build id: `seenBuild` reads skew off the ANSWER. `fromNetwork` is the exported mirror. `service-worker-preload.test.ts` executes it. |
-| Install fill | `PRECACHE_CONCURRENCY` (4) in flight, never `Promise.all` over the manifest: it runs on the first visit against the connection the first click needs. Still one entry per failure. |
+| Install fill | `PRECACHE_CONCURRENCY` (4) in flight, never `Promise.all` over the manifest: it runs on the first visit against the connection the first click needs. Still one entry per failure. An answer stamped with another build's `BUILD_ID_HEADER` is not stored (an old pod mid-rollout); an unstamped one is. |
+| Rule patterns | built from the DECODED route path, matched against the PERCENT-ENCODED `url.pathname`: a literal segment goes through the WHATWG serializer (`URL.pathname`, never `encodeURI` — it escapes `\|`, `[`, `^`, `%` a browser leaves literal), either hex case. A catch-all is `(?:/.*)?`, so `/docs/*path` owns `/docs`. `route-rules.test.ts`; the e2e drives both in Chrome. |
 | Runtime assets | `ServiceWorkerConfig.runtimeAssets` prefixes (`/islands/`) are `cache-first` runtime rules AHEAD of every page rule (`assetRules`, `route-rules.ts`), and go to the network as the browser asked — no build-id header, because a classic script is a `no-cors` request whose headers a worker may not extend. The precache names only what a precached page boots (the CLI chooses: `sw-precache-plan.ts`); all 43 islands (~1 MB) were precached on a first anonymous visit until 22.3.3. |
 | Locales | the worker matches pathnames and the server strips `/en/` before it matches, so the CALLER spells every route once per routed locale (`@ultimat3/cli`'s `sw-precache-plan.ts`). `localePrefixes` is only for the offline document: a navigation under `/en/` tries `/en` + `OFFLINE_DOC` first. |
 | Precache revision | content hash. Never the build id — that re-downloads everything per deploy. |
@@ -28,7 +29,7 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | 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. Each entry is fetched and `put` on its own, `As of 22.3.4`: `addAll`'s all-or-nothing let one 404 (a stylesheet another pod minted) fail the install of every deploy, so every visitor stayed on the first worker that ever installed (notificado.co). A failed entry costs its offline copy only. `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. |
+| HTML sinks | one escaper: `escapeHtml` from `@ultimat3/core`, the framework's one character table (`bun run flight-copies`, `X_HELPER_COPY`). `appleTouchLinks` and `renderThemeColorMeta` interpolate app config into attributes; both escape. Never a second escaper here. |
 | 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. |
@@ -38,13 +39,13 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | `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. |
 | 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 stored, in any cache, under any rule (22.3.3, security). `openCache` guards every cache a strategy opens: a response that is `private`/`no-store` or carries `x-ultimate-scope` (`CLIENT_SCOPE_HEADER`) is answered and dropped. 21.0.0 kept one in a per-principal partition (`PAGES~<scope>`) for offline, and after sign-out an offline navigation on a shared device showed the previous member's cases (notificado.co). A PERSONAL route (`PwaRoute.personal`: a policy, a `stream`, a `no-store`/`private` cache) is also `network-only` in `strategyFor` and skipped by `buildPrecacheManifest`. `{type:'clear-pages'}` (`CLEAR_PAGES_MESSAGE`) deletes every `x-pages-*` cache — old partitions included — and answers `pages-cleared`. `offline.personalPages: 'last-member'` (an app's explicit opt-in) restores 21.0.0's partition — `pagesCacheSource(mode)` emits one of the two. `service-worker-pages.test.ts` runs both modes. |
+| A per-member document | NEVER stored, in any cache, under any rule (22.3.3, security). `openCache` guards every cache a strategy opens: a response that is `private`/`no-store` or carries `x-ultimate-scope` (`CLIENT_SCOPE_HEADER`) is answered and dropped. 21.0.0 kept one in a per-principal partition (`PAGES~<scope>`) for offline, and after sign-out an offline navigation on a shared device showed the previous member's cases (notificado.co). A PERSONAL route (`PwaRoute.personal`: a policy, a `stream`, a `no-store`/`private` cache) is also `network-only` in `strategyFor` and skipped by `buildPrecacheManifest`. `{type:'clear-pages'}` (`CLEAR_PAGES_MESSAGE`) deletes every `x-pages-*` cache — old partitions included — and answers `pages-cleared`. `offline.personalPages: 'last-member'` (an app's explicit opt-in) restores 21.0.0's partition — `pagesCacheSource(mode)` emits one of the two, and `routeRules(routes, mode)` gives a personal page a `pages` rule whatever its `offline` (a `precache` rule was never filled, so it was never kept). `service-worker-pages.test.ts` runs both modes. |
 | 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. |
+| 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. A URL that does not resolve to `self.location.origin` (another host, a scheme, malformed, a non-string) opens the root instead (`tapTarget`). The `push` body is parsed INSIDE `waitUntil` (`pushData`): plain text is the body, JSON that is no object is `{}`. `push-handler.test.ts`. |
 | 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. |
 | Icons | one source image → `BuiltinImagePipeline` → a square PNG per `ICON_MATRIX` entry, rendered by `@ultimat3/core`'s image pipeline. Never a second scaler, never `sharp`, never a vendor CDN. |

package/README.md

@@ -71,7 +71,7 @@ before an un-shippable PWA exists.
 
 | Capability | Manifest member | SW code |
 |---|---|---|
-| `push` | — | `push` + `notificationclick` listeners |
+| `push` | — | `push` + `notificationclick` listeners; a tap opens a same-origin URL only |
 | `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` | — |
@@ -95,7 +95,6 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | Class | Code | Declared in |
 |---|---|---|
 | `BuildIdMissingError` | `X_BUILD_ID_MISSING` | `src/errors.ts` |
-| `NotImplementedError` | `X_NOT_IMPLEMENTED` | `src/errors.ts` |
 | `PwaIconMissingError` | `X_PWA_ICON_MISSING` | `src/errors.ts` |
 | `PwaManifestInvalidError` | `X_PWA_MANIFEST_INVALID` | `src/errors.ts` |
 | `PwaNoOfflineFallbackError` | `X_PWA_NO_OFFLINE_FALLBACK` | `src/errors.ts` |
@@ -108,7 +107,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 |---|---|
 | `generateServiceWorker` | `sw.js` from the route table; deterministic for identical input |
 | `strategyFor`, `MODE_STRATEGY`, `cacheFirst`, … | the four strategies + the mapping table; a `personal` route is `network-only` |
-| `routeRules`, `assetRules` | the worker's rule list: routes most specific first, runtime asset prefixes (`/islands/`) ahead of them |
+| `routeRules`, `assetRules` | the worker's rule list: routes most specific first, runtime asset prefixes (`/islands/`) ahead of them. `routeRules(routes, personalPages)` — `'last-member'` gives a personal page a `pages` rule; a pattern matches the browser's percent-encoded pathname, and a catch-all its bare prefix |
 | `CLEAR_PAGES_MESSAGE`, `PAGES_CLEARED_MESSAGE` | `{ type: 'clear-pages' }` — post it to the worker on sign-out; it empties every pages cache and answers `{ type: 'pages-cleared' }` |
 | `buildPrecacheManifest` | precache entries (url + content-hash revision), size warnings |
 | `buildId`, `detectSkew`, `retentionPlan` | version skew |
@@ -153,9 +152,9 @@ a job boundary the class is gone and the `code` is what survives — match on th
   lands exactly inside `maskableSafeZone(size)`; the ring around it is `background`, which is
   hex or `transparent` (there are no named colours). Same bytes in, same bytes out.
 - **Every HTML sink goes through one escaper.** `appleTouchLinks` and `renderThemeColorMeta`
-  interpolate app configuration into attributes, so both run it through `escapeAttribute` from
-  `@ultimat3/seo` (tier 1, and the one this package can reach — `@ultimat3/render`'s `html.ts` is
-  tier 4, sideways). Never a second escaper here.
+  interpolate app configuration into attributes, so both run it through `escapeHtml` from
+  `@ultimat3/core` — the framework's one HTML character table (`@ultimat3/render`'s `html.ts` is
+  tier 4, sideways, and re-exports the same function). Never a second escaper here.
 - **A precache URL may already carry a query.** `PrecacheAsset.url` is public API and bundlers emit
   `?v=<hash>` of their own, so the install block picks `?` or `&` per entry. A fixed `?` produced
   `...?locale=en?v=<rev>`, and because `cache.addAll` is all-or-nothing a single non-200 there means

package/package.json

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

package/src/errors.ts

@@ -20,8 +20,9 @@ export const PWA_OWNED_ERROR_CODES = [
 ] as const;
 
 /**
- * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s. Thrown here, titled only there — the copy this file
- * used to keep was a second title that could drift from core's with nothing to catch it.
+ * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s — constructed only there, by core's own
+ * `NotImplementedError`, and titled only there: the copy this file used to keep was a second title
+ * that could drift from core's with nothing to catch it.
  */
 export const PWA_BORROWED_ERROR_CODES = ['X_NOT_IMPLEMENTED'] as const;
 
@@ -130,15 +131,3 @@ export class PwaStrategyExhaustedError extends UltimateError {
     });
   }
 }
-
-/** 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;
-  constructor(cause: string, fix: string) {
-    super({
-      code: NotImplementedError.code,
-      cause,
-      fix,
-    });
-  }
-}

package/src/icons.ts

@@ -4,8 +4,7 @@
  * icons end up with clipped logos.
  */
 
-import { transformImageBytes } from '@ultimat3/core';
-import { escapeAttribute } from '@ultimat3/seo';
+import { escapeHtml, transformImageBytes } from '@ultimat3/core';
 import { PwaIconMissingError } from './errors';
 import type { ManifestIcon } from './manifest';
 
@@ -186,7 +185,7 @@ export function appleTouchLinks(plan: IconPlan): string {
       // `href` — a quote in it closed the attribute AND the tag, so `<head>` got a live element.
       // seo's escaper is tier 1 and the one this package can reach; render's html.ts is tier 4.
       (entry) =>
-        `<link rel="apple-touch-icon" sizes="${entry.spec.size}x${entry.spec.size}" href="${escapeAttribute(entry.outputPath)}">`,
+        `<link rel="apple-touch-icon" sizes="${entry.spec.size}x${entry.spec.size}" href="${escapeHtml(entry.outputPath)}">`,
     )
     .join('');
 }

package/src/index.ts

@@ -25,7 +25,6 @@ export {
 export type { PwaErrorCode } from './errors';
 export {
   BuildIdMissingError,
-  NotImplementedError,
   PWA_ERROR_CODES,
   PWA_ERROR_TITLES,
   PwaIconMissingError,

package/src/manifest.ts

@@ -10,7 +10,7 @@
 // with no map between them and nothing asserting they agreed, which is the same axiom-1 defect the
 // two `PwaConfig`s were. An app writes them once, in the one config file.
 import type { PwaColors } from '@ultimat3/core';
-import { escapeAttribute } from '@ultimat3/seo';
+import { escapeHtml } from '@ultimat3/core';
 import type { CapabilityFlags, ResolvedCapabilities } from './capabilities';
 import { isEnabled, resolveCapabilities } from './capabilities';
 import { PwaManifestInvalidError } from './errors';
@@ -132,6 +132,8 @@ export function generateWebManifest(config: WebManifestInput): WebManifestResult
   assertValid(config);
   const capabilities = resolveCapabilities(config.capabilities);
   const scope = config.scope ?? '/';
+  const display = config.display ?? 'standalone';
+  const override = displayOverrideFor(display);
 
   const optional: MutableManifest = {};
   if (config.description !== undefined) optional.description = config.description;
@@ -156,8 +158,9 @@ export function generateWebManifest(config: WebManifestInput): WebManifestResult
     short_name: config.shortName ?? shortNameFrom(config.name),
     start_url: config.startUrl ?? scope,
     scope,
-    display: config.display ?? 'standalone',
-    display_override: ['standalone', 'minimal-ui'],
+    display,
+    // Right after `display`, where it always was: an unchanged config emits unchanged bytes.
+    ...(override.length > 0 ? { display_override: override } : {}),
     orientation: config.orientation ?? 'any',
     lang: config.lang ?? 'en',
     dir: config.dir ?? 'ltr',
@@ -177,6 +180,19 @@ export function generateWebManifest(config: WebManifestInput): WebManifestResult
   };
 }
 
+/** The spec's own fallback chain for `display`, app windows only — `browser` is no window. */
+const DISPLAY_CHAIN: readonly DisplayMode[] = ['fullscreen', 'standalone', 'minimal-ui'];
+
+/**
+ * `display_override` is read BEFORE `display`, so it must start where `display` does: a fixed
+ * `['standalone','minimal-ui']` opened a `browser` app in its own window and gave a `fullscreen`
+ * one browser UI. `browser` gets none — any override would be a window it did not ask for.
+ */
+function displayOverrideFor(display: DisplayMode): readonly DisplayMode[] {
+  const from = DISPLAY_CHAIN.indexOf(display);
+  return from < 0 ? [] : DISPLAY_CHAIN.slice(from);
+}
+
 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. */
@@ -231,7 +247,7 @@ export function renderThemeColorMeta(metas: readonly ThemeColorMeta[]): string {
       // quote in one emitted a second, live attribute — same class as `appleTouchLinks`, same
       // escaper, one per package rather than one per call site.
       (meta) =>
-        `<meta name="theme-color" content="${escapeAttribute(meta.content)}" media="${escapeAttribute(meta.media)}">`,
+        `<meta name="theme-color" content="${escapeHtml(meta.content)}" media="${escapeHtml(meta.media)}">`,
     )
     .join('');
 }

package/src/push.ts

@@ -171,28 +171,46 @@ export function pushSource(options: PushSourceOptions = {}): string {
   const badging = options.badging === true;
 
   return `
+// Parsed INSIDE waitUntil: json() on a body that is not JSON threw out of the listener before it
+// was extended, and nothing was shown. Plain text is the body; JSON that is no object reads as {}.
+function pushData(event){
+  if(!event.data)return {};
+  let v;
+  try{v=event.data.json()}catch(e){return {body:event.data.text()}}
+  return v!==null&&typeof v==='object'&&!Array.isArray(v)?v:{}
+}
 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: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())' : ''
-  });
+  event.waitUntil((async()=>{
+    const d=pushData(event);
+    // 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:tg,renotify:!!d.renotify&&tg!==undefined,requireInteraction:!!d.requireInteraction,
+      lang:d.lang||undefined,actions:Array.isArray(d.actions)?d.actions:[],data:{url:d.url||'/'}};
+    await self.registration.showNotification(d.title||'',opts);${
+      badging ? '\n    if(navigator.setAppBadge)await navigator.setAppBadge();' : ''
+    }
+  })());
 });
+// A tap opens THIS app only: the URL comes from the push body, whoever composed it. Another host, a
+// non-http scheme, a malformed URL or a non-string opens the app's root instead.
+function tapTarget(raw){
+  const root=new URL('/',self.location.origin).href;
+  if(typeof raw!=='string')return root;
+  try{const u=new URL(raw,self.location.origin);return u.origin===self.location.origin?u.href:root}
+  catch(e){return root}
+}
 self.addEventListener('notificationclick',(event)=>{
   event.notification.close();
   // PushPayload.url is a PATH and WindowClient.url is absolute, so the comparison below is only
   // ever true after resolving — unresolved it matched no client at all and every tap opened a
   // second window on an app the user already had open. Same resolve as the fetch block's.
-  const url=new URL((event.notification.data&&event.notification.data.url)||'/',self.location.origin).href;
+  const url=tapTarget(event.notification.data&&event.notification.data.url);
   event.waitUntil(clients.matchAll({type:'window',includeUncontrolled:true}).then((ws)=>{
     for(const w of ws){if(w.url===url&&'focus'in w)return w.focus()}
     return clients.openWindow(url)

package/src/route-rules.ts

@@ -4,7 +4,9 @@
  * that are no route: content-addressed chunks, cached the first time a page asks for one.
  */
 
+import { routeRank } from '@ultimat3/core';
 import { SwScopeInvalidError } from './errors';
+import type { PersonalPages } from './pages-cache-source';
 import type { PwaRoute, StrategyName } from './strategies';
 import { strategyFor } from './strategies';
 
@@ -23,35 +25,8 @@ 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
+ * Ordered MOST SPECIFIC FIRST — `@ultimat3/core`'s `routeRank`, the one rule `@ultimat3/render` and
+ * the request router share — 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
@@ -66,17 +41,21 @@ const hasWildcard = (path: string): boolean =>
  */
 const byCodeUnit = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
 
-export function routeRules(routes: readonly PwaRoute[]): readonly RouteRule[] {
+/**
+ * `personalPages: 'last-member'` routes a personal page by its render mode again — the pages facade
+ * partitions it per member. `'never'` (the default) leaves it `network-only`.
+ */
+export function routeRules(
+  routes: readonly PwaRoute[],
+  personalPages: PersonalPages = 'never',
+): readonly RouteRule[] {
   return [...routes]
     .filter((route) => route.surface !== 'api')
-    .sort(
-      (a, b) =>
-        Number(hasWildcard(a.path)) - Number(hasWildcard(b.path)) ||
-        specificityOf(b.path) - specificityOf(a.path) ||
-        byCodeUnit(a.path, b.path),
-    )
+    .sort((a, b) => routeRank(b.path) - routeRank(a.path) || byCodeUnit(a.path, b.path))
     .map((route) => {
-      const strategy = strategyFor(route);
+      const strategy = strategyFor(
+        personalPages === 'last-member' ? { ...route, personal: false } : route,
+      );
       return {
         pattern: toPattern(route.path),
         strategy,
@@ -85,27 +64,53 @@ export function routeRules(routes: readonly PwaRoute[]): readonly RouteRule[] {
     });
 }
 
+/**
+ * A personal page that reaches a cache at all goes to `pages`, never `precache`: it is never in the
+ * precache manifest (fetched anonymously at install it is a sign-in redirect), so a `precache` rule
+ * was a cache that always missed — and only the pages facade files a member's page by member.
+ */
 function cacheFor(route: PwaRoute, strategy: StrategyName): 'precache' | 'runtime' | 'pages' {
   if (strategy === 'network-only') return 'runtime';
+  if (route.personal === true) return 'pages';
   if (route.offline === 'precache' && route.dynamic !== true) return 'precache';
   return 'pages';
 }
 
+const escapeRegex = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * A literal segment as the browser's `url.pathname` spells it — the WHATWG serializer itself, so a
+ * route path (the DECODED directory name) matches the PERCENT-ENCODED pathname `ruleFor` tests:
+ * `/precios-españa` and `/a b` were never handled. Not `encodeURI`, which also escapes `|`, `[`,
+ * `^` and `%` where a browser leaves them literal. A `%XX` escape matches either hex case, as a
+ * hand-typed link may carry one.
+ */
+function literal(segment: string): string {
+  const url = new URL('https://x.invalid/');
+  url.pathname = `/${segment}`;
+  return escapeRegex(url.pathname.slice(1)).replace(
+    /%([0-9A-Fa-f]{2})/g,
+    (_, hex: string) =>
+      `%${[...hex].map((c) => (/[A-Fa-f]/.test(c) ? `[${c.toUpperCase()}${c.toLowerCase()}]` : c)).join('')}`,
+  );
+}
+
 /**
  * A trailing slash is dropped before the pattern is built, because the pattern allows one anyway:
- * a locale's home is spelled `/en/`, and `^/en//?$` matched `/en/` and missed `/en`.
+ * a locale's home is spelled `/en/`, and `^/en//?$` matched `/en/` and missed `/en`. A catch-all
+ * takes its leading slash with it, `(?:/.*)?`, so `/docs/*path` matches the bare `/docs` that
+ * `@ultimat3/render`'s static export writes for an empty `path`.
  */
 function toPattern(path: string): string {
-  const bare = path.replace(/\/+$/, '');
-  if (bare === '') return '^/$';
-  const body = bare
-    .split('/')
+  const segments = segmentsOf(path);
+  if (segments.length === 0) return '^/$';
+  const body = segments
     .map((segment) => {
-      if (segment.startsWith(':')) return '[^/]+';
-      if (segment.startsWith('*')) return '.*';
-      return segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      if (segment.startsWith(':')) return '/[^/]+';
+      if (segment.startsWith('*')) return '(?:/.*)?';
+      return `/${literal(segment)}`;
     })
-    .join('/');
+    .join('');
   return `^${body}/?$`;
 }
 
@@ -125,7 +130,7 @@ export function assetRules(prefixes: readonly string[], scope: string): readonly
       );
     }
     return {
-      pattern: `^${prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`,
+      pattern: `^${escapeRegex(prefix)}`,
       strategy: 'cache-first',
       cache: 'runtime',
       asset: true,

package/src/service-worker.ts

@@ -123,13 +123,12 @@ export function generateServiceWorker(
 
   const fallback = requireOfflineFallback(config.offline);
   const capabilities = resolveCapabilities(config.capabilities);
-  // `last-member` routes a personal page by its render mode again — the pages facade partitions it.
-  // The precache below still skips it: fetched anonymously at install, it is a sign-in redirect.
-  const routed =
-    fallback.personalPages === 'last-member'
-      ? routes.map((route) => ({ ...route, personal: false }))
-      : routes;
-  const rules = [...assetRules(config.runtimeAssets ?? [], scope), ...routeRules(routed)];
+  // The precache below skips a personal page in both modes: fetched anonymously at install, it is a
+  // sign-in redirect. `routeRules` decides where `last-member` keeps it instead — the pages facade.
+  const rules = [
+    ...assetRules(config.runtimeAssets ?? [], scope),
+    ...routeRules(routes, fallback.personalPages),
+  ];
 
   const precache = buildPrecacheManifest({
     buildId,
@@ -278,7 +277,9 @@ self.addEventListener('install',(event)=>{
         const e=PRECACHE_MANIFEST[i++];
         try{
           const r=await fetch(new Request(e.url+(e.url.indexOf('?')<0?'?':'&')+'v='+e.revision,{cache:'reload'}));
-          if(r.ok)await cache.put(new Request(e.url),r);
+          // Mid-rollout an OLD pod may answer: its document is not this build's offline copy.
+          const b=r.headers.get(BUILD_HEADER);
+          if(r.ok&&(b===null||b===BUILD_ID))await cache.put(new Request(e.url),r);
         }catch(err){}
       }
     };