@ultimat3/pwa 7.0.0 → 9.0.0

package/CLAUDE.md

@@ -18,9 +18,12 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | 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. |
+| 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. |
 | 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. |
 | 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. |

package/README.md

@@ -38,13 +38,14 @@ and the app dies with a blank screen and no error anyone can act on.
 | Client → server | every SW-proxied request carries `x-ultimate-build` |
 | Retention | `retentionPlan(deploys, keep)` keeps the last N deploys' assets alive (default 3) |
 | Stale client | gets `AppUpdateAvailable`, never a 404 |
-| Forced reload | only for `forceOn` reasons, only after `graceMs` (default 6h) |
+| Forced reload | none. This package never navigates a client — the app decides what to do with the message |
 | Preview deploys | cache names are `x-<kind>-<buildId>`, so a branch build cannot poison production |
 
 ```ts
-detectSkew(clientBuildId, serverBuildId);   // 'current' | 'stale' | 'unknown'
-updateSignal({ clientBuildId, serverBuildId, policy: updatePolicy() });
-// → { type: 'AppUpdateAvailable', from, to, forced, deadlineAt }
+// The generated worker posts this to every page it controls, on activation — and this is the
+// whole message, which `version-skew.test.ts` holds the interface to.
+// { type: 'AppUpdateAvailable', to: BUILD_ID }
+detectSkew(clientBuildId, message.to); // 'current' | 'stale' | 'unknown'
 ```
 
 `unknown` means no id was sent — a first load or a crawler — and is never treated as stale.
@@ -87,7 +88,7 @@ capability nothing implements.
 | `generateServiceWorker` | `sw.js` from the route table; deterministic for identical input |
 | `strategyFor`, `MODE_STRATEGY`, `cacheFirst`, … | the four strategies + the mapping table |
 | `buildPrecacheManifest` | precache entries (url + content-hash revision), size warnings |
-| `buildId`, `detectSkew`, `retentionPlan`, `updatePolicy`, `updateSignal` | version skew |
+| `buildId`, `detectSkew`, `retentionPlan` | version skew |
 | `generateWebManifest` | the manifest + `theme-color` metas for both schemes |
 | `planIcons`, `requireSourceIcon`, `maskableSafeZone` | icons and splashes from one source |
 | `BuiltinImagePipeline` | renders that plan: one square PNG per entry, deterministic |

package/package.json

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

package/src/index.ts

@@ -6,6 +6,9 @@
  * re-exported here; a consumer still needs one import, and now it names the real type.
  */
 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 {
   backgroundSyncSource,
@@ -94,7 +97,6 @@ export type { PrecacheAsset, PrecacheEntry, PrecacheInput, PrecacheManifest } fr
 export {
   buildPrecacheManifest,
   DEFAULT_PRECACHE_WARN_BYTES,
-  formatBytes,
   serializePrecacheManifest,
 } from './precache';
 export type {
@@ -135,17 +137,18 @@ export {
   staleWhileRevalidate,
   strategyFor,
 } from './strategies';
+// The forced-reload half of this module is gone as of 9.0.0 — `updateSignal`, `updatePolicy`,
+// `DEFAULT_GRACE_MS`, `ForceReason`, `UpdatePolicy`, `UpdatePolicyInput`, `UpdateSignalInput`.
+// It computed `forced`/`deadlineAt` for a client-side reload no code in the framework performed,
+// from a caller that never existed. What remains is what runs: an id, a comparison, a retention
+// plan, and the message the generated worker really posts.
 export type {
   AppUpdateAvailable,
   BuildIdInput,
   Deploy,
   DeployChannel,
-  ForceReason,
   RetentionPlan,
   SkewState,
-  UpdatePolicy,
-  UpdatePolicyInput,
-  UpdateSignalInput,
 } from './version-skew';
 export {
   APP_UPDATE_AVAILABLE,
@@ -154,9 +157,6 @@ export {
   BUILD_ID_META,
   buildId,
   cacheNamespace,
-  DEFAULT_GRACE_MS,
   detectSkew,
   retentionPlan,
-  updatePolicy,
-  updateSignal,
 } from './version-skew';

package/src/precache.ts

@@ -4,6 +4,9 @@
  * hash, never the build id, or every deploy would re-fetch everything.
  */
 
+// One formatter, in `@ultimat3/core`: the copy that lived here stopped at `mb`, and the route
+// budget message on the other side of the build stopped at `kb`, for the same byte count.
+import { formatBytes } from '@ultimat3/core';
 import type { PwaRoute } from './strategies';
 
 export interface PrecacheAsset {
@@ -120,12 +123,6 @@ export function buildPrecacheManifest(input: PrecacheInput): PrecacheManifest {
   return { buildId: input.buildId, entries: sorted, totalBytes, warnings };
 }
 
-export function formatBytes(bytes: number): string {
-  if (bytes < 1024) return `${bytes}b`;
-  if (bytes < 1024 * 1024) return `${Math.round((bytes / 1024) * 10) / 10}kb`;
-  return `${Math.round((bytes / (1024 * 1024)) * 10) / 10}mb`;
-}
-
 /** The manifest as it is embedded in `sw.js`; stable key order for determinism. */
 export function serializePrecacheManifest(manifest: PrecacheManifest): string {
   const rows = manifest.entries.map(

package/src/version-skew.ts

@@ -5,7 +5,9 @@
  *
  *   immutable build id per deploy → the client sends it on every request →
  *   old builds' assets are retained for N deploys → a stale client gets
- *   `AppUpdateAvailable`, never a 404 → forced reload only after a grace period.
+ *   `AppUpdateAvailable`, never a 404.
+ *
+ * The app decides what to do with that message. This package never navigates a client.
  */
 
 import { BuildIdMissingError } from './errors';
@@ -115,73 +117,23 @@ export function detectSkew(
   return clientBuildId === serverBuildId ? 'current' : 'stale';
 }
 
-export type ForceReason = 'security' | 'breaking-protocol' | 'never';
-
-export interface UpdatePolicyInput {
-  /** How long a stale client may keep running before the reload is forced. */
-  readonly graceMs?: number;
-  readonly forceOn?: readonly ForceReason[];
-}
-
-export interface UpdatePolicy {
-  readonly graceMs: number;
-  readonly forceOn: readonly ForceReason[];
-  shouldForce(reason: ForceReason, staleForMs: number): boolean;
-}
-
-export const DEFAULT_GRACE_MS = 6 * 60 * 60 * 1000;
-
-export function updatePolicy(input: UpdatePolicyInput = {}): UpdatePolicy {
-  const graceMs = input.graceMs ?? DEFAULT_GRACE_MS;
-  const forceOn = input.forceOn ?? ['security'];
-  return {
-    graceMs,
-    forceOn,
-    // A security patch still respects the grace window; it just does not wait forever.
-    shouldForce: (reason, staleForMs) => forceOn.includes(reason) && staleForMs >= graceMs,
-  };
-}
-
 /**
- * The client-side contract. The SW posts this to every controlled page; the app shows an
- * unobtrusive "refresh to update" affordance and reloads on the user's terms — unless
- * `forced`, in which case it reloads at `deadlineAt`.
+ * The client-side contract, and the whole of it: what the generated worker posts to every page it
+ * controls on activation. The page compares `to` against its own `BUILD_ID_META` — `detectSkew`
+ * is that comparison — and renders its own "refresh to update" affordance.
+ *
+ * It declared `from`, `forced` and `deadlineAt` too, for a forced reload after a grace period that
+ * NOTHING performed: `updateSignal`/`updatePolicy` computed the three and had no runtime caller,
+ * and `x deploy --critical`, the flag that was to have set the reason, was removed in 4.0.0 for
+ * being read by nobody. The two runtimes that hold both build ids cannot call into this package
+ * anyway — `http`'s `ctx.clientBuildId` (tier 2) and `sync`'s `update-available` frame (tier 3)
+ * are both BELOW `pwa`, and imports only go down. `version-skew.test.ts` holds this interface to
+ * the literal the worker emits, so the two can no longer differ.
  */
 export interface AppUpdateAvailable {
   readonly type: 'AppUpdateAvailable';
-  readonly from: string;
+  /** The build the worker that posted this was generated for. */
   readonly to: string;
-  readonly forced: boolean;
-  /** Epoch milliseconds after which the client reloads itself. Null when not forced. */
-  readonly deadlineAt: number | null;
 }
 
 export const APP_UPDATE_AVAILABLE = 'AppUpdateAvailable' as const;
-
-export interface UpdateSignalInput {
-  readonly clientBuildId: string | null | undefined;
-  readonly serverBuildId: string;
-  readonly policy: UpdatePolicy;
-  readonly reason?: ForceReason;
-  readonly staleForMs?: number;
-  readonly now?: number;
-}
-
-/** Null when the client is current or unknown — no signal, no nag. */
-export function updateSignal(input: UpdateSignalInput): AppUpdateAvailable | null {
-  const state = detectSkew(input.clientBuildId, input.serverBuildId);
-  if (state !== 'stale') return null;
-
-  const reason = input.reason ?? 'never';
-  const staleForMs = input.staleForMs ?? 0;
-  const forced = input.policy.shouldForce(reason, staleForMs);
-  const now = input.now ?? Date.now();
-
-  return {
-    type: APP_UPDATE_AVAILABLE,
-    from: String(input.clientBuildId),
-    to: input.serverBuildId,
-    forced,
-    deadlineAt: forced ? now : null,
-  };
-}