@ultimat3/pwa 6.0.0 → 8.0.0

package/CLAUDE.md

@@ -18,6 +18,7 @@ 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. |

package/package.json

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

package/src/capabilities.ts

@@ -43,15 +43,14 @@ export function enabledCapabilities(capabilities: ResolvedCapabilities): readonl
 }
 
 /** Manifest members a capability owns. Absent capability → absent member. */
-export const CAPABILITY_MANIFEST_KEYS: Readonly<Record<Capability, readonly string[]>> =
-  Object.freeze({
-    push: [],
-    backgroundSync: [],
-    badging: [],
-    shareTarget: ['share_target'],
-    fileHandlers: ['file_handlers'],
-    protocolHandlers: ['protocol_handlers'],
-  });
+export const CAPABILITY_MANIFEST_KEYS = Object.freeze<Record<Capability, readonly string[]>>({
+  push: [],
+  backgroundSync: [],
+  badging: [],
+  shareTarget: ['share_target'],
+  fileHandlers: ['file_handlers'],
+  protocolHandlers: ['protocol_handlers'],
+});
 
 /**
  * The service-worker code each capability emits — its listener, and anything that listener alone
@@ -64,13 +63,11 @@ export const CAPABILITY_MANIFEST_KEYS: Readonly<Record<Capability, readonly stri
  * 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: [],
-    fileHandlers: [],
-    protocolHandlers: [],
-  },
-);
+export const CAPABILITY_SW_MARKERS = Object.freeze<Record<Capability, readonly string[]>>({
+  push: ["addEventListener('push'", "addEventListener('notificationclick'"],
+  backgroundSync: ["addEventListener('sync'", 'class PwaSyncError'],
+  badging: ['navigator.setAppBadge'],
+  shareTarget: [],
+  fileHandlers: [],
+  protocolHandlers: [],
+});

package/src/index.ts

@@ -1,5 +1,14 @@
 /** Public API of `@ultimat3/pwa`. You never open `sw.js`; you call these. */
 
+/**
+ * `PwaRenderMode` and `PwaOfflineStrategy` were this package's own NAMES for tier 0's vocabulary —
+ * the alias was the copy. `PwaRoute` takes both in its signature, so the canonical names are
+ * 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,
@@ -88,7 +97,6 @@ export type { PrecacheAsset, PrecacheEntry, PrecacheInput, PrecacheManifest } fr
 export {
   buildPrecacheManifest,
   DEFAULT_PRECACHE_WARN_BYTES,
-  formatBytes,
   serializePrecacheManifest,
 } from './precache';
 export type {
@@ -111,8 +119,6 @@ export {
 export type { RouteRule, ServiceWorkerConfig, ServiceWorkerOutput } from './service-worker';
 export { assertScope, generateServiceWorker, routeRules } from './service-worker';
 export type {
-  PwaOfflineStrategy,
-  PwaRenderMode,
   PwaRoute,
   StrategyCache,
   StrategyEnv,

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/strategies.ts

@@ -4,6 +4,7 @@
  * its bytes have to be, so the mapping is derived and the override is the exception.
  */
 
+import type { OfflineStrategy, RenderMode } from '@ultimat3/core';
 import { PwaStrategyExhaustedError } from './errors';
 
 export type StrategyName =
@@ -19,9 +20,6 @@ export const STRATEGY_NAMES: readonly StrategyName[] = [
   'network-only',
 ];
 
-export type PwaRenderMode = 'static' | 'isr' | 'ssr' | 'stream';
-export type PwaOfflineStrategy = 'precache' | 'runtime' | 'network-only';
-
 /**
  * Structural view of `@ultimat3/render`'s `RouteDescriptor`. Tier-4 packages must not
  * import each other, so route data arrives as data and this is the shape it must have.
@@ -29,8 +27,8 @@ export type PwaOfflineStrategy = 'precache' | 'runtime' | 'network-only';
 export interface PwaRoute {
   readonly path: string;
   readonly surface: 'site' | 'app' | 'api';
-  readonly mode: PwaRenderMode;
-  readonly offline: PwaOfflineStrategy;
+  readonly mode: RenderMode;
+  readonly offline: OfflineStrategy;
   readonly dynamic?: boolean;
   /** Explicit per-route override; wins over the derived strategy. */
   readonly strategy?: StrategyName;
@@ -41,8 +39,20 @@ export interface PwaRoute {
   readonly dataUrl?: string;
 }
 
-/** Render mode → runtime strategy. The whole reason `sw.js` is generated, not written. */
-export const MODE_STRATEGY: Readonly<Record<PwaRenderMode, StrategyName>> = Object.freeze({
+/**
+ * Render mode → runtime strategy. The whole reason `sw.js` is generated, not written.
+ *
+ * Two separate things make the closed set hold, and the table needed both. `Record<RenderMode, …>`
+ * over the TIER-0 union is the exhaustiveness check — this was keyed on a hand-copy, which is how
+ * `spa` went on mapping to `cache-first` after `spa` was deleted from the vocabulary: the one
+ * strategy that gives an `app/` route a SHARED cache entry, i.e. one member's authed HTML served
+ * to the next. And `Object.freeze<T>({…})` with an EXPLICIT type argument, never
+ * `const X: T = Object.freeze({…})` — the second form infers `T` from the literal and the
+ * annotation only checks assignability afterwards, so the literal's freshness is already gone and
+ * an EXTRA key compiles in silence. Named, the literal is contextually typed and a missing key
+ * AND an extra key are both build errors.
+ */
+export const MODE_STRATEGY = Object.freeze<Record<RenderMode, StrategyName>>({
   static: 'cache-first',
   isr: 'stale-while-revalidate',
   ssr: 'network-first',
@@ -138,12 +148,12 @@ export async function networkOnly(
   }
 }
 
-export const STRATEGY_FNS: Readonly<
+export const STRATEGY_FNS = Object.freeze<
   Record<
     StrategyName,
     (request: Request, env: StrategyEnv, options: StrategyOptions) => Promise<Response>
   >
-> = Object.freeze({
+>({
   'cache-first': cacheFirst,
   'network-first': networkFirst,
   'stale-while-revalidate': staleWhileRevalidate,
@@ -176,7 +186,7 @@ async function fallbackOrThrow(options: StrategyOptions): Promise<Response> {
  * service worker is a generated artifact with no bundler in the loop — the shapes are
  * identical on purpose and `strategies.test.ts` asserts both halves stay in step.
  */
-export const STRATEGY_SOURCE: Readonly<Record<StrategyName, string>> = Object.freeze({
+export const STRATEGY_SOURCE = Object.freeze<Record<StrategyName, string>>({
   'cache-first': `async function cacheFirst(req,cn,fb){
   const c=await caches.open(cn);const hit=await c.match(req);if(hit)return hit;
   try{const r=await fetch(req);if(r.ok)await c.put(req,r.clone());return r}catch(e){if(fb)return fb();throw e}
@@ -198,7 +208,7 @@ export const STRATEGY_SOURCE: Readonly<Record<StrategyName, string>> = Object.fr
 }`,
 });
 
-export const STRATEGY_FN_NAMES: Readonly<Record<StrategyName, string>> = Object.freeze({
+export const STRATEGY_FN_NAMES = Object.freeze<Record<StrategyName, string>>({
   'cache-first': 'cacheFirst',
   'network-first': 'networkFirst',
   'stale-while-revalidate': 'staleWhileRevalidate',