@ultimat3/pwa 3.0.0 → 4.0.0

package/CLAUDE.md

@@ -15,11 +15,15 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | 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 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. |
 | Cache names | always `cacheNamespace(buildId, kind)`. An unkeyed cache name is a rejected change. |
 | Offline fallback | `requireOfflineFallback` runs inside `generateServiceWorker`. Never optional. |
-| Capabilities | gate the manifest member **and** the SW block. Disabled → zero bytes. |
+| 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. |
 | Outbox | queue lives in `@ultimat3/realtime`. This package only registers the sync trigger. |
 | 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. |
 | 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. |
 | Icon source | a **PNG** (core decodes PNG and JPEG only). `x new` scaffolds one; `@ultimat3/cli`'s `dev-assets.ts` reads it at `ICON_SOURCE` and serves every entry at its `outputPath`. This package renders bytes and mounts nothing. |

package/README.md

@@ -67,13 +67,19 @@ before an un-shippable PWA exists.
 | `push` | — | `push` + `notificationclick` listeners |
 | `backgroundSync` | — | `sync` listener + outbox flush |
 | `badging` | — | `navigator.setAppBadge` after a push |
-| `shareTarget` | `share_target` | share-target route rule |
+| `shareTarget` | `share_target` | — |
 | `fileHandlers` | `file_handlers` | — |
 | `protocolHandlers` | `protocol_handlers` | — |
 
 A disabled capability emits neither the manifest member nor the SW code. An unused
 capability ships zero bytes and asks for zero permissions.
 
+Three of the six are manifest-only, and the `—` in their SW column is load-bearing: the OS hands a
+share, a file or a protocol URL to a route the app already serves, so there is no worker branch to
+gate. `CAPABILITY_SW_MARKERS` is checked against the emitted `sw.js` in both directions, so a claim
+here that the generator does not honour is a failing test rather than an installed app announcing a
+capability nothing implements.
+
 ## Public API
 
 | Export | Owns |
@@ -89,6 +95,7 @@ capability ships zero bytes and asks for zero permissions.
 | `backgroundSyncSource`, `retryDelayMs` | the Background Sync trigger |
 | `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 |
 
 ## Notes
 
@@ -109,5 +116,13 @@ capability ships zero bytes and asks for zero permissions.
   PNG, because `type: 'image/png'` is what the manifest declares. A maskable icon's artwork
   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.
+- **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
+  the worker never installs at all.
 - **Route data arrives as data.** `@ultimat3/render` and `@ultimat3/pwa` are both tier 4, so
   `PwaRoute` is a structural view of `RouteDescriptor`, never an import.

package/package.json

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

package/src/background-sync.ts

@@ -18,7 +18,6 @@ import { PwaSyncFlushFailedError, PwaSyncIncompleteError } from './errors';
 import { BUILD_ID_HEADER } from './version-skew';
 
 export const SYNC_TAG = 'x-outbox';
-export const PERIODIC_SYNC_TAG = 'x-refresh';
 
 export interface RetryPolicy {
   readonly maxAttempts: number;
@@ -50,8 +49,6 @@ export interface BackgroundSyncOptions {
   /** Endpoint `@ultimat3/realtime` exposes to flush the outbox. */
   readonly flushEndpoint?: string;
   readonly retry?: RetryPolicy;
-  /** Minimum interval for periodic sync, when the platform grants it. */
-  readonly periodicMinIntervalMs?: number;
 }
 
 export const DEFAULT_FLUSH_ENDPOINT = '/_x/outbox/flush';

package/src/capabilities.ts

@@ -55,15 +55,21 @@ export const CAPABILITY_MANIFEST_KEYS: Readonly<Record<Capability, readonly stri
 
 /**
  * The service-worker code each capability emits — its listener, and anything that listener alone
- * needs. Used to assert nothing leaks when disabled: `PwaSyncError` is the background-sync
- * handler's own error class, so it ships with the handler and never without it.
+ * needs. Checked in BOTH directions (`service-worker.test.ts`): every marker is in the emitted
+ * worker when its capability is on, and none of them is when they are all off. `PwaSyncError` is
+ * the background-sync handler's own error class, so it ships with the handler and never without it.
+ *
+ * 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.
+ * `shareTarget` named `/_x/share-target` here for two releases and no block ever emitted it.
  */
 export const CAPABILITY_SW_MARKERS: Readonly<Record<Capability, readonly string[]>> = Object.freeze(
   {
     push: ["addEventListener('push'", "addEventListener('notificationclick'"],
     backgroundSync: ["addEventListener('sync'", 'class PwaSyncError'],
     badging: ['navigator.setAppBadge'],
-    shareTarget: ['/_x/share-target'],
+    shareTarget: [],
     fileHandlers: [],
     protocolHandlers: [],
   },

package/src/icons.ts

@@ -5,6 +5,7 @@
  */
 
 import { transformImageBytes } from '@ultimat3/core';
+import { escapeAttribute } from '@ultimat3/seo';
 import { PwaIconMissingError } from './errors';
 import type { ManifestIcon } from './manifest';
 
@@ -180,8 +181,11 @@ export function appleTouchLinks(plan: IconPlan): string {
   return plan.entries
     .filter((entry) => entry.spec.purpose === 'apple-touch')
     .map(
+      // `outputPath` carries `IconSourceConfig.outDir`, which is app config on its way into an
+      // `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="${entry.outputPath}">`,
+        `<link rel="apple-touch-icon" sizes="${entry.spec.size}x${entry.spec.size}" href="${escapeAttribute(entry.outputPath)}">`,
     )
     .join('');
 }

package/src/index.ts

@@ -5,7 +5,6 @@ export {
   backgroundSyncSource,
   DEFAULT_FLUSH_ENDPOINT,
   DEFAULT_RETRY,
-  PERIODIC_SYNC_TAG,
   registerBackgroundSyncSource,
   retryDelayMs,
   SYNC_TAG,
@@ -29,6 +28,10 @@ export {
   PwaIconMissingError,
   PwaManifestInvalidError,
   PwaNoOfflineFallbackError,
+  // `staleWhileRevalidate` is public and throws this, so an app that catches it can name it. The
+  // two X_PWA_SYNC_* classes are not here on purpose: the emitted `sw.js` builds its own local
+  // class in a realm with no bundler, so no instance of theirs can ever reach an app.
+  PwaStrategyExhaustedError,
   SwScopeInvalidError,
 } from './errors';
 export type {

package/src/manifest.ts

@@ -5,6 +5,7 @@
  * app gets a light status bar on every launch.
  */
 
+import { escapeAttribute } from '@ultimat3/seo';
 import type { CapabilityFlags, ResolvedCapabilities } from './capabilities';
 import { isEnabled, resolveCapabilities } from './capabilities';
 import { PwaManifestInvalidError } from './errors';
@@ -211,6 +212,12 @@ export function serializeWebManifest(manifest: WebManifest): string {
 
 export function renderThemeColorMeta(metas: readonly ThemeColorMeta[]): string {
   return metas
-    .map((meta) => `<meta name="theme-color" content="${meta.content}" media="${meta.media}">`)
+    .map(
+      // Both values are attribute sinks. `assertValid` only asks that a token is non-empty, so a
+      // 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)}">`,
+    )
     .join('');
 }

package/src/precache.ts

@@ -11,8 +11,6 @@ export interface PrecacheAsset {
   /** Content hash. Same bytes → same revision → no re-download. */
   readonly revision: string;
   readonly bytes: number;
-  /** Critical assets (the shell CSS, the LCP font) are precached even if large. */
-  readonly critical?: boolean;
 }
 
 export interface PrecacheEntry {

package/src/push.ts

@@ -150,7 +150,10 @@ self.addEventListener('push',(event)=>{
 });
 self.addEventListener('notificationclick',(event)=>{
   event.notification.close();
-  const url=(event.notification.data&&event.notification.data.url)||'/';
+  // 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;
   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/service-worker.ts

@@ -64,6 +64,16 @@ export interface ServiceWorkerOutput {
  * "why is my PWA not working" and it is checkable at build time.
  */
 export function assertScope(swPath: string, scope: string): void {
+  // A relative path has no directory to compare, and `''` is a prefix of every scope — so the
+  // check passed for exactly the config most likely to be wrong. Refused, not normalised: where
+  // the browser would resolve `sw.js` from is the registration call, which this cannot see.
+  if (!swPath.startsWith('/')) {
+    throw new SwScopeInvalidError(
+      `sw.js is served from ${swPath}, which is relative, so the directory it can control is ` +
+        `unknown at build time; the configured scope is ${scope}`,
+      `set pwa.swPath to an absolute path — '${scope}sw.js' serves scope ${scope}`,
+    );
+  }
   const directory = swPath.slice(0, swPath.lastIndexOf('/') + 1);
   if (!scope.startsWith(directory)) {
     throw new SwScopeInvalidError(
@@ -210,13 +220,19 @@ function serializeRules(rules: readonly RouteRule[]): string {
  * of the page that was precached, and online every precached byte is downloaded a second time.
  * `addAll` still does the fetching, because its all-or-nothing failure is what stops a
  * half-populated precache from activating; the second pass only re-keys what it stored.
+ *
+ * The separator in front of `v=` is chosen per entry, because `PrecacheAsset.url` is public API
+ * and a bundler emits a query of its own: a fixed `?` built `...?locale=en?v=<rev>`, and a single
+ * non-200 for it rejects `addAll`, which rejects the install — no precache, no offline document,
+ * no version-skew header, and a worker that never activates at all.
  */
 const INSTALL_BLOCK = `
 self.addEventListener('install',(event)=>{
   event.waitUntil((async()=>{
     const cache=await caches.open(PRECACHE);
     // Revision is a content hash: unchanged assets are not re-downloaded across deploys.
-    const fetched=PRECACHE_MANIFEST.map((e)=>new Request(e.url+'?v='+e.revision,{cache:'reload'}));
+    // The separator is picked per entry: a precache URL may already carry a query.
+    const fetched=PRECACHE_MANIFEST.map((e)=>new Request(e.url+(e.url.indexOf('?')<0?'?':'&')+'v='+e.revision,{cache:'reload'}));
     await cache.addAll(fetched);
     for(let i=0;i<PRECACHE_MANIFEST.length;i++){
       const stored=await cache.match(fetched[i]);