@ultimat3/pwa 1.1.0 → 2.0.0

package/CLAUDE.md

@@ -0,0 +1,34 @@
+# @ultimat3/pwa — boundary
+
+Owns: `sw.js` generation, caching strategies, precache manifest, version skew, web
+manifest, icons, offline fallback, background-sync trigger, push, install prompt.
+
+Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cache`, `seo`,
+`entity`, `policy`, `http`, `action`, `query`. **Never** `render`, `mcp`, `ai`, `manifest`
+(sideways), never `ui`/`cli` (upward).
+
+| 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. |
+| 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. |
+| 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. |
+| 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. |
+| 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. |
+| Icon background | `IconSourceConfig.background`, hex or `transparent` — core's grammar has no named colours. Default transparent. |
+| Errors | `errors.ts` subclasses only. `X_NOT_IMPLEMENTED` must carry a real `fix:`. |
+| Errors in `sw.js` | no bundler there, so no `UltimateError` import — the generated source defines its own class (`SYNC_ERROR_CLASS`) carrying `code`, `cause`, `fix`, `docs`. Never emit a bare `throw new Error`; the code stays owned by `errors.ts`. |
+
+```
+bun test                          # from packages/pwa
+bun run typecheck
+bun run --cwd ../.. verify
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/pwa",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "Generated service worker, web manifest, icons, push and version-skew handling.",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -30,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "1.1.0"
+    "@ultimat3/core": "2.0.0"
   }
 }

package/src/service-worker.ts

@@ -203,12 +203,26 @@ function serializeRules(rules: readonly RouteRule[]): string {
   return `[${rows.join(',')}]`;
 }
 
+/**
+ * The revision addresses the **fetch**, never the **key**. Every strategy looks an entry up with
+ * `caches.match(req)` on the bare URL — `ignoreSearch` defaults to `false` — so an entry left
+ * keyed under `?v=<revision>` is a permanent miss: offline serves the fallback document instead
+ * 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.
+ */
 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.
-    await cache.addAll(PRECACHE_MANIFEST.map((e)=>new Request(e.url+'?v='+e.revision,{cache:'reload'})));
+    const fetched=PRECACHE_MANIFEST.map((e)=>new Request(e.url+'?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]);
+      if(stored)await cache.put(new Request(PRECACHE_MANIFEST[i].url),stored);
+      await cache.delete(fetched[i]);
+    }
   })());
 });`.trim();