@ultimat3/pwa 17.0.0 → 19.0.0

package/CLAUDE.md

@@ -12,7 +12,8 @@ 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`. |
-| A generated header | names something that regenerates the file. `sw.js` said `regenerate: x build` and no `x build` target emits a service worker — `generateServiceWorker` has no caller anywhere in the tree — so it names the CALL until a build writes it. |
+| 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. |
 | Precache revision | content hash. Never the build id — that re-downloads everything per deploy. |
@@ -30,7 +31,8 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | Outbox | queue lives in `@ultimat3/realtime`. This package only registers the sync trigger — and schedules **no retry**: the handler rejects and the PLATFORM decides when to wake it again. `RetryPolicy`, `DEFAULT_RETRY`, `retryDelayMs`, `shouldRetry` and `BackgroundSyncOptions.retry` were deleted 2026-08-23; of the policy only `maxAttempts` ever reached the worker, as a `SYNC_MAX_ATTEMPTS` constant nothing read, and the emitted `X_PWA_SYNC_INCOMPLETE` fix told the reader to raise `pwa.backgroundSync.retry.maxAttempts`, a key `PwaConfig` has never had. `background-sync.test.ts` asserts that every constant the worker declares is one the worker reads. |
 | 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. |
+| 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. |
 | 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. |

package/README.md

@@ -89,7 +89,7 @@ capability nothing implements.
 | `strategyFor`, `MODE_STRATEGY`, `cacheFirst`, … | the four strategies + the mapping table |
 | `buildPrecacheManifest` | precache entries (url + content-hash revision), size warnings |
 | `buildId`, `detectSkew`, `retentionPlan` | version skew |
-| `generateWebManifest` | the manifest + `theme-color` metas for both schemes |
+| `generateWebManifest` | the manifest + `theme-color` metas for both schemes, from a `WebManifestInput`. Called by `@ultimat3/cli` (`pwa-artifacts.ts`) `As of 2026-08-27`, so `x dev`, the container and the static export all emit `manifest.webmanifest` |
 | `planIcons`, `requireSourceIcon`, `maskableSafeZone` | icons and splashes from one source |
 | `BuiltinImagePipeline` | renders that plan: one square PNG per entry, deterministic |
 | `requireOfflineFallback` | the mandatory offline route |
@@ -103,7 +103,19 @@ capability nothing implements.
 - **Theme colours come from the design tokens for both schemes.** The manifest spec carries
   one `theme_color`, so the dark value is emitted as a media-scoped
   `<meta name="theme-color">` — otherwise an installed dark app launches with a light status
-  bar every time.
+  bar every time. The shape is `@ultimat3/core`'s `PwaColors`, which is what an app writes in
+  `app.config.ts` as `pwa.colors`; this package declared its own identical `ThemeTokens` until
+  2026-08-27, with nothing asserting the two agreed.
+- **`WebManifestInput` is not the `pwa` block of `app.config.ts`.** It was called `PwaConfig` and
+  said it was, while `@ultimat3/core` exported a different type of that name that really is the
+  block. An app writes `name` and `colors`; every other member is a caller's.
+- **The service worker has a build behind it, `As of 2026-08`.** `generateServiceWorker` — and
+  through it `buildPrecacheManifest`, `offlineFallbackSource`, `backgroundSyncSource` and
+  `pushSource` — is called by `packages/cli/src/sw-artifacts.ts`, so `x dev`, the container and the
+  static export all emit `sw.js` and `x-sw-register.js`
+  ([#390](https://github.com/developerz-ai/ultimate/issues/390)). It landed a release after the
+  manifest half because a bad `sw.js` is sticky: it waited on a real browser check
+  (`packages/cli/e2e/service-worker.e2e.test.ts`), which the tree could not run until #400.
 - **Precache revisions are content hashes, never the build id.** Keying on the build id
   re-downloads every asset on every deploy.
 - **The mutation queue lives in `@ultimat3/realtime`, not here** (SRP). This package owns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/pwa",
-  "version": "17.0.0",
+  "version": "19.0.0",
   "description": "Generated service worker, web manifest, icons, push and version-skew handling.",
   "license": "MIT",
   "type": "module",
@@ -24,14 +24,14 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=1.4.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "17.0.0",
-    "@ultimat3/seo": "17.0.0"
+    "@ultimat3/core": "19.0.0",
+    "@ultimat3/seo": "19.0.0"
   }
 }

package/src/index.ts

@@ -79,12 +79,10 @@ export type {
   ManifestShortcut,
   Orientation,
   ProtocolHandler,
-  PwaConfig,
-  SchemeColors,
   ShareTarget,
   ThemeColorMeta,
-  ThemeTokens,
   WebManifest,
+  WebManifestInput,
   WebManifestResult,
 } from './manifest';
 export { generateWebManifest, renderThemeColorMeta, serializeWebManifest } from './manifest';

package/src/manifest.ts

@@ -5,6 +5,11 @@
  * app gets a light status bar on every launch.
  */
 
+// `PwaColors`/`PwaSchemeColors` are tier 0's, not this package's. They were declared here as
+// `ThemeTokens`/`SchemeColors` — structurally identical to what `app.config.ts` already carried,
+// 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 type { CapabilityFlags, ResolvedCapabilities } from './capabilities';
 import { isEnabled, resolveCapabilities } from './capabilities';
@@ -81,19 +86,15 @@ export interface WebManifest {
   readonly protocol_handlers?: readonly ProtocolHandler[];
 }
 
-/** Resolved token values for one colour scheme. Never a hex literal in framework code. */
-export interface SchemeColors {
-  readonly themeColor: string;
-  readonly backgroundColor: string;
-}
-
-export interface ThemeTokens {
-  readonly light: SchemeColors;
-  readonly dark: SchemeColors;
-}
-
-/** The `pwa` block of `app.config.ts`. */
-export interface PwaConfig {
+/**
+ * Everything `generateWebManifest` needs, which is NOT the `pwa` block of `app.config.ts` — this
+ * type was called `PwaConfig` and said it was, while `@ultimat3/core` exported a different type of
+ * the same name that really is the block. Two exported `PwaConfig`s with no map between them is
+ * axiom 1, and the one that lied is this one: an app declares `name` and `colors`, and every other
+ * member here is a caller's — `icons` comes from `planIcons`, `capabilities` from the build.
+ * `packages/cli/src/pwa-artifacts.ts` is what composes the two into this.
+ */
+export interface WebManifestInput {
   readonly name: string;
   readonly shortName?: string;
   readonly description?: string;
@@ -104,7 +105,7 @@ export interface PwaConfig {
   readonly orientation?: Orientation;
   readonly lang?: string;
   readonly dir?: 'ltr' | 'rtl' | 'auto';
-  readonly tokens: ThemeTokens;
+  readonly tokens: PwaColors;
   readonly categories?: readonly string[];
   readonly icons?: readonly ManifestIcon[];
   readonly shortcuts?: readonly ManifestShortcut[];
@@ -127,7 +128,7 @@ export interface WebManifestResult {
   readonly capabilities: ResolvedCapabilities;
 }
 
-export function generateWebManifest(config: PwaConfig): WebManifestResult {
+export function generateWebManifest(config: WebManifestInput): WebManifestResult {
   assertValid(config);
   const capabilities = resolveCapabilities(config.capabilities);
   const scope = config.scope ?? '/';
@@ -178,7 +179,7 @@ export function generateWebManifest(config: PwaConfig): WebManifestResult {
 
 type MutableManifest = { -readonly [K in keyof WebManifest]?: WebManifest[K] };
 
-function assertValid(config: PwaConfig): void {
+function assertValid(config: WebManifestInput): void {
   if (config.name.trim() === '') {
     throw new PwaManifestInvalidError(
       'pwa.name is empty, so the install prompt would have no title',

package/src/service-worker.ts

@@ -227,13 +227,15 @@ export function generateServiceWorker(
 }
 
 function header(buildId: string): string {
-  // `regenerate:` names the CALL, not a command: `x build` emits no service worker — nothing in
-  // the tree calls `generateServiceWorker` at all — so the line sent whoever found this file in a
-  // diff to a command that would leave it exactly as they found it. It becomes `x build` on the day
-  // the build actually writes this file, and not before.
+  // `x build`, `As of 2026-08-27`, and it took until then to become true. This said
+  // `generateServiceWorker(routes, config, buildId) from @ultimat3/pwa` — the CALL rather than a
+  // command — because nothing in the tree called it: `x build` emitted no service worker, so the
+  // line would have sent whoever found this file in a diff to a command that left it exactly as
+  // they found it. `packages/cli/src/sw-artifacts.ts` is the caller now (#390), and `x build`
+  // regenerates this file the way the comment always meant to say.
   return `// GENERATED by @ultimat3/pwa from the route table — do not edit.
 // build: ${buildId}
-// regenerate: generateServiceWorker(routes, config, buildId) from @ultimat3/pwa`;
+// regenerate: x build`;
 }
 
 function constants(