@ultimat3/pwa 26.0.0 → 26.1.0

package/CLAUDE.md

@@ -4,16 +4,23 @@ Owns: `sw.js` generation, caching strategies, precache manifest, version skew, w
 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).
+`entity`, `policy`, `http`, `action`, `query`. **Never** `render`, `mcp`, `ai`, `manifest`,
+`notify` (sideways), never `ui`/`cli` (upward). Tier 4 is its FLOOR since 26.1.0 — `pushSubscribe`
+builds an `action` — so it has no `FLOOR_ABOVE` row; `render` keeps one and holds the pair level.
+
+Three entry points: `.` (server), `./client` (`client.ts` — THE browser entry: install prompt,
+skew, the browser half of push; its graph is `install.ts`, `skew.ts`, `push-client.ts` and
+`@ultimat3/core/page`, held by `client-bundle.test.ts` — never import `@ultimat3/core`'s barrel or
+`errors.ts` from those three) and `./schema` (`push-schema.ts` — the one DDL leaf every
+role's boot loads, `@ultimat3/mcp/schema`'s shape; `serve-graph.test.ts` exempts it by name).
 
 | 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. `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. |
+| 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. **Key material is the one exception, and it is injectable**: RFC 8291 needs a fresh salt and one-message ECDH key per push (reusing either reuses a GCM nonce under one key) — `encryptPushMessage`'s `options.salt` / `options.ephemeral` are the seam the Appendix A test pins — and `generateVapidKeys` rolls a pair. Every clock read in push (`vapidAuthorization`'s `exp`, expiry) takes a `Clock`. |
 | 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. The order is `@ultimat3/core`'s `routeRank` — the ONE route precedence, also `@ultimat3/render`'s `CompiledPattern.specificity`: the request router's order, segment by segment. Never a local copy, never a sum. |
 | 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` / `runtime-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. |
+| 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` / `runtime-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 wired too, `As of 26.1.0`** (#710): the boot (`@ultimat3/cli`'s `runtime-push.ts`) resolves the VAPID pair and calls `installWebPush`, the web role hands `installedVapid()` to `generateServiceWorker` (push handler) and the head (`<meta name="x-push-key">`), and a static export — no runtime behind it — is the one build `serviceWorkerWarnings` still reports |
 | 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. Every row is `network-first` `As of 22.3.2`: every rule is a DOCUMENT, and `static: 'cache-first'` / `isr`,`stream: 'stale-while-revalidate'` answered online navigations with the old deploy's HTML (and so its old hashed assets) until Shift+F5. Precache ≠ cache-first — the precached copy is the offline answer. |
 | Worker update | `self.skipWaiting()` in `install`, `As of 22.3.2` — worker-side, because the browsers that must converge run a 22.3.1 worker and register script that never post `skip-waiting`. Safe for an open tab: the worker routes no chunk. Never a reload — the next navigation is fresh. The `skip-waiting` message stays. |
@@ -44,7 +51,11 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | The installing page | cached on `activate`. It loaded before the worker controlled it, so no strategy saw it and an `offline: 'runtime'` route was unavailable offline until a second online visit. After `clients.claim()` each controlled window's URL runs through its OWN route's strategy (`warm`) — only rules with `c: 'pages'`, same origin, not `NEVER_CACHE` — never a second caching rule. Best effort; a failed warm-up never fails activation. It runs AFTER activation, never inside its `waitUntil`: a fetch event waits for the worker to finish activating, so a warm-up copying a streamed page's whole body there held the claimed tab's every request — the `/feed` e2e hang. The offline page read (`pageOffline`) awaits it instead. `service-worker-runtime.test.ts` runs it. |
 | Outbox drain | the worker SENDS NOTHING, `As of 21.0.0`. The outbox is `@ultimat3/realtime`'s and lives in the page (IndexedDB), so the `sync` event — and the `{type:'flush-outbox'}` fallback message, posted by `registerBackgroundSyncSource` wherever `registration.sync` is absent (Safari, Firefox) — both run `drainOutbox`, which posts `OUTBOX_DRAIN_MESSAGE` (`@ultimat3/core`) to EVERY open window client; realtime's listener drains. No client open = the handler resolves and the next load drains; it never fakes work. `/_x/outbox/flush`, `DEFAULT_FLUSH_ENDPOINT`, and `BackgroundSyncOptions` were deleted, and `X_PWA_SYNC_FLUSH_FAILED` / `X_PWA_SYNC_INCOMPLETE` are still registered but thrown by nothing (shipped codes are stable forever): the worker POSTed to a route nothing in the framework ever mounted. The fallback branch lives in the shared message handler, so `CAPABILITY_SW_MARKERS.backgroundSync` carrying `d.type==='flush-outbox'` is what keeps it gated with the `drainOutbox` it calls. `background-sync.test.ts` and `service-worker-runtime.test.ts` run the emitted code and assert the posted messages. |
 | Outbox | queue, replay, retry and idempotency are all `@ultimat3/realtime`'s. This package only registers the sync trigger and schedules **no retry** — `RetryPolicy`, `DEFAULT_RETRY`, `retryDelayMs`, `shouldRetry` and `BackgroundSyncOptions.retry` were deleted 2026-08-23. |
-| Push strings | i18n keys only, rendered per subscriber locale. Never a literal. |
+| Push strings | i18n keys only, rendered per subscriber locale. Never a literal. The runtime's `translate` defaults to `@ultimat3/i18n`'s `translatorFor(subscription.locale)` — the app's registered catalogs. |
+| Web Push crypto | WebCrypto only, no dependency (`docs/idea/18-build-vs-wrap.md`). `push-encrypt.ts` is RFC 8291 + RFC 8188 (one `aes128gcm` record, delimiter `0x02`, no padding) and is pinned by RFC 8291 Appendix A byte for byte, every intermediate included; it is `scripts/seal-calls.ts`'s `STANDARD_CIPHERS` row, because the key is agreed with the subscriber's browser and is never the app's — `seal()` cannot be what it calls. `vapid.ts` is RFC 8292: `aud` is the endpoint's ORIGIN, `exp` 12 h (≤ 24 h), the signature WebCrypto's raw `r‖s` (= JWS ES256). WebCrypto does not check that `d` belongs to `x`/`y`, so `assertVapidPair` signs and verifies a probe — the boot runs it once. |
+| VAPID keys | env, never config: `ULTIMATE_VAPID_PUBLIC_KEY` + `ULTIMATE_VAPID_PRIVATE_KEY`, printable formats (`web-push`'s). `resolveVapidKeys(env)`: both set → checked pair; neither, locally → `DEV_VAPID_KEYS` (published); neither or the dev key when `devSecretsRefused` (core's rule, fails closed), or half a pair anywhere → `X_PWA_VAPID_KEY_MISSING`. `pwa.vapid` holds the `subject` only. |
+| Push sending | `sendPushMessage` → `delivered` (2xx), `gone` (404/410 — delete, never retry), or a throw: `X_PWA_PUSH_FAILED` (`retry-after`: 429 / 5xx / no connection, `Retry-After` in `meta`), `X_PWA_PUSH_REJECTED` (terminal). `pushToActor` tries EVERY device, deletes the gone, the expired and the 401/403-refused (made with another VAPID key), logs the refused, and rethrows the first retryable failure LAST — so the notifier job retries, and devices that got it get it again; the `tag` is what makes that a replacement. The endpoint must be `https:` on a LISTED push service (`push-hosts.ts`: the built-in four plus `pwa.vapid.pushHosts`, dot-boundary suffix match), checked at subscribe and at send: it came from a request body, and a hostname resolves wherever its owner points it — the list, never the name's shape or its DNS answer, is the screen. `redirect: 'manual'`, a `PUSH_SEND_TIMEOUT_MS` deadline per POST, and a caller's abort rethrown as is — never the retryable class. |
+| Subscriptions | keyed by ENDPOINT (a browser subscribed by a second person is theirs now), stored against `ctx.actor.id` — never an id from the body. `pushSubscribe` / `pushUnsubscribe` are factories over `action` (`PRIMITIVE_FACTORIES` rows); an agent is refused in the policy. `x_push_subscriptions` is DDL applied by the boot (`FRAMEWORK_SCHEMA`), never an `entity()`. |
 | `renotify` | never without a `tag`, at BOTH ends. The Notifications spec makes `showNotification` reject with a `TypeError` for the pair, so the device shows **nothing** — the failure a `renotify: true` with no collapse key produces is the whole notification disappearing. `renderPushPayload` drops the flag and files a `warnings` entry (a knob with no effect is worse than no knob), and the emitted handler recomputes it as `!!d.renotify&&!!d.tag` because a push body is composed by whatever holds the VAPID key. `push.test.ts`'s `showNotification` stub throws the spec's TypeError, so a stub that tolerates the pair cannot go green. |
 | 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. A URL that does not resolve to `self.location.origin` (another host, a scheme, malformed, a non-string) opens the root instead (`tapTarget`). The `push` body is parsed INSIDE `waitUntil` (`pushData`): plain text is the body, JSON that is no object is `{}`. `push-handler.test.ts`. |
 | 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. |

package/README.md

@@ -8,6 +8,32 @@ the second copy is the one nobody updates.
 const { source, precache, warnings } = generateServiceWorker(describePages(), config, buildId);
 ```
 
+## Browser entry: `@ultimat3/pwa/client`
+
+`As of 26.1.0`. Everything a page or an island calls comes from **`@ultimat3/pwa/client`**, never
+from `@ultimat3/pwa`: the barrel reaches the icon pipeline (core's image transform, Node-only), the
+service-worker generator and the push sender, and an island importing it does not build.
+
+```ts
+import {
+  detectSkew,
+  installController,
+  MIN_ENGAGEMENT_MS,
+  subscribeToPush,
+} from '@ultimat3/pwa/client';
+import { APP_UPDATE_MESSAGE, CLIENT_BUILD_META } from '@ultimat3/core/page';
+```
+
+| Need | From `@ultimat3/pwa/client` |
+|---|---|
+| the install prompt, never on first paint | `installController` (+ `InstallOptions`, `InstallHost`, `InstallController`, `InstallOutcome`, `BeforeInstallPromptEventLike`, `ReadSignal`), `iosInstallGuidance` (+ `IosGuidance`), `MIN_ENGAGEMENT_MS` (30 000 — the default `minEngagementMs`) |
+| "a new version is live" | `AppUpdateAvailable` (the worker's message), `detectSkew` (+ `SkewState`). The message's `type` value is core's `APP_UPDATE_MESSAGE`, from `@ultimat3/core/page` — one name, one home |
+| Web Push | `subscribeToPush`, `unsubscribeFromPush`, `pushPermission`, `browserPushHost`, `PUSH_KEY_META` (+ their types) |
+
+Its graph is three modules of this package plus `@ultimat3/core/page`; `client-bundle.test.ts`
+bundles it for the browser and refuses a fourth, an image module or a `node:` import. The server
+barrel keeps exporting the same names for server code and tests.
+
 ## Render mode → runtime strategy
 
 | Render mode | Strategy | Why |
@@ -72,7 +98,7 @@ placeholders a failed image or font request gets — each served only from the p
 
 | Capability | Manifest member | SW code |
 |---|---|---|
-| `push` | — | `push` + `notificationclick` listeners; a tap opens a same-origin URL only |
+| `push` | — | `push` + `notificationclick` listeners; a tap opens a same-origin URL only. Emitted only when a `vapid` key comes with it — the web role passes `installedVapid()` |
 | `backgroundSync` | — | `sync` listener that tells every open tab to drain realtime's outbox (`OUTBOX_DRAIN_MESSAGE`) |
 | `badging` | — | `navigator.setAppBadge` after a push |
 | `shareTarget` | `share_target` | — |
@@ -88,6 +114,59 @@ gate. `CAPABILITY_SW_MARKERS` is checked against the emitted `sw.js` in both dir
 here that the generator does not honour is a failing test rather than an installed app announcing a
 capability nothing implements.
 
+## Web Push
+
+`pwa: { push: true, vapid: { subject: 'mailto:ops@example.com' } }` in `app.config.ts`, and the rest
+is wiring the framework does: the boot resolves the VAPID pair from the environment and installs the
+runtime, the worker carries the handlers, every page carries `<meta name="x-push-key">`. RFC 8291
+encryption and RFC 8292 (ES256) signing, on WebCrypto — no dependency.
+
+```ts
+// apps/web/app/push/actions.ts — two real actions: route, OpenAPI, typed client, contract tests.
+import { pushSubscribe, pushUnsubscribe } from '@ultimat3/pwa';
+
+export const subscribePush = pushSubscribe({ permission: 'push:subscribe' });
+export const unsubscribePush = pushUnsubscribe({ permission: 'push:subscribe' });
+```
+
+```ts
+// an island, on a click — the browser entry, `@ultimat3/pwa/client`.
+import { subscribeToPush } from '@ultimat3/pwa/client';
+
+declare const client: { subscribePush(input: unknown): Promise<unknown> };
+
+const outcome = await subscribeToPush({ save: client.subscribePush });
+// { status: 'subscribed', endpoint } | { status: 'denied' } | { status: 'unsupported' } | { status: 'unconfigured' }
+```
+
+```ts
+// a notifier — every device of the recipient, each in the locale it subscribed with.
+import { pushChannel } from '@ultimat3/notify';
+import { webPush } from '@ultimat3/pwa';
+
+export const channel = pushChannel<{ postId: string }>({
+  pusher: webPush(),
+  message: ({ event }) => ({
+    titleKey: 'push.comment.title',
+    bodyKey: 'push.comment.body',
+    url: `/posts/${event.params.postId}`,
+    tag: `post:${event.params.postId}`,
+  }),
+});
+```
+
+| Piece | Rule |
+|---|---|
+| Keys | `ULTIMATE_VAPID_PUBLIC_KEY` + `ULTIMATE_VAPID_PRIVATE_KEY`, env only. `x vapid create` seals both in one write; locally, neither set signs with `DEV_VAPID_KEYS`, which a deployed boot refuses (`X_PWA_VAPID_KEY_MISSING`). Two halves that do not sign for each other: `X_PWA_VAPID_KEY_INVALID`, at boot |
+| Subscriptions | `x_push_subscriptions`, applied by the boot; keyed by endpoint, stored against `ctx.actor.id`, with the locale and zone they subscribed in. An agent never subscribes |
+| Strings | catalog keys (`titleKey`, `bodyKey`, `actions[].titleKey`), rendered per subscription locale through `@ultimat3/i18n`'s `translatorFor` |
+| Size | one 4096-byte record: 3993 bytes of notification (`X_PWA_PUSH_PAYLOAD_TOO_LARGE`). Send a path, never the content |
+| Travel | `ttlSeconds` (default 86 400), `urgency`, `topic` — RFC 8030 headers; the topic is any string, sent as 32 URL-safe characters of its SHA-256 |
+| 201 / 404, 410 / 429, 5xx / 400, 401, 403, 413 | delivered / subscription deleted / `X_PWA_PUSH_FAILED`, retried by the job after every other device was tried / `X_PWA_PUSH_REJECTED`, logged, never retried — and on 401/403 the subscription is deleted: it was made with a key this server no longer signs with |
+| Key rotation | `subscribeToPush` compares a browser's existing subscription with the page's `x-push-key`; one made with another key is unsubscribed and replaced, never re-saved |
+| Endpoints | dialled only on a push service: `https:`, and a host that is one of `PUSH_SERVICE_HOSTS` (FCM, Mozilla, Apple, WNS) or `pwa.vapid.pushHosts`, or a subdomain of one on a dot boundary — checked when stored and before every send (`assertPushEndpoint`), never by where the name resolves, since the endpoint came from a request body (`X_PWA_PUSH_HOST_UNLISTED`; a stored one is deleted unsent). One POST waits at most `PUSH_SEND_TIMEOUT_MS` (30 s); a caller's abort is rethrown as is, never the retryable class |
+| `renotify` | dropped, with a warning, without a `tag` — at both ends |
+
 ## Error classes
 
 Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
@@ -99,7 +178,14 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `PwaIconMissingError` | `X_PWA_ICON_MISSING` | `src/errors.ts` |
 | `PwaManifestInvalidError` | `X_PWA_MANIFEST_INVALID` | `src/errors.ts` |
 | `PwaNoOfflineFallbackError` | `X_PWA_NO_OFFLINE_FALLBACK` | `src/errors.ts` |
+| `PwaPushFailedError` | `X_PWA_PUSH_FAILED` | `src/errors.ts` |
+| `PwaPushPayloadTooLargeError` | `X_PWA_PUSH_PAYLOAD_TOO_LARGE` | `src/errors.ts` |
+| `PwaPushRejectedError` | `X_PWA_PUSH_REJECTED` | `src/errors.ts` |
+| `PwaPushSubscriptionInvalidError` | `X_PWA_PUSH_SUBSCRIPTION_INVALID` | `src/errors.ts` |
+| `PwaPushUnconfiguredError` | `X_PWA_PUSH_UNCONFIGURED` | `src/errors.ts` |
 | `PwaStrategyExhaustedError` | `X_PWA_STRATEGY_EXHAUSTED` | `src/errors.ts` |
+| `PwaVapidKeyInvalidError` | `X_PWA_VAPID_KEY_INVALID` | `src/errors.ts` |
+| `PwaVapidKeyMissingError` | `X_PWA_VAPID_KEY_MISSING` | `src/errors.ts` |
 | `SwScopeInvalidError` | `X_SW_SCOPE_INVALID` | `src/errors.ts` |
 
 ## Public API
@@ -111,14 +197,21 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `routeRules`, `assetRules` | the worker's rule list: routes most specific first, runtime asset prefixes (`/islands/`) ahead of them. `routeRules(routes, personalPages)` — `'last-member'` gives a personal page a `pages` rule; a pattern matches the browser's percent-encoded pathname, and a catch-all its bare prefix |
 | `CLEAR_PAGES_MESSAGE`, `PAGES_CLEARED_MESSAGE` | `{ type: 'clear-pages' }` — post it to the worker on sign-out; it empties every pages cache and answers `{ type: 'pages-cleared' }` |
 | `buildPrecacheManifest` | precache entries (url + content-hash revision), size warnings |
-| `buildId`, `detectSkew`, `retentionPlan` | version skew |
+| `buildId`, `detectSkew`, `retentionPlan` | version skew (`detectSkew` also on `./client`) |
 | `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 |
 | `backgroundSyncSource`, `registerBackgroundSyncSource` | the Background Sync trigger. No retry policy: the handler rejects and the PLATFORM reschedules it |
 | `renderPushPayload`, `pushSource`, `subscribeSource` | Web Push, per-locale bodies |
-| `installController`, `iosInstallGuidance` | install prompt, never on first paint |
+| `pushSubscribe`, `pushUnsubscribe` | factories over `action`: store / forget this browser's subscription for `ctx.actor` |
+| `webPush`, `pushToActor` | one notification to every device of one person — `webPush()` is notify's `Pusher` |
+| `sendPushMessage`, `encryptPushMessage`, `vapidAuthorization` | one message to one subscription; RFC 8291; RFC 8292 |
+| `installWebPush`, `installedVapid`, `webPushRuntime`, `resetWebPush` | the runtime the boot installs (store, signer, transport, translator) |
+| `memoryPushSubscriptionStore`, `postgresPushSubscriptionStore` | where subscriptions live; `x_push_subscriptions` DDL is `@ultimat3/pwa/schema` |
+| `resolveVapidKeys`, `generateVapidKeys`, `assertVapidPair`, `DEV_VAPID_KEYS` | the key pair: from env, minted, checked, and the published development one |
+| `@ultimat3/pwa/client` | THE browser entry — [Browser entry](#browser-entry-ultimat3pwaclient) |
+| `installController`, `iosInstallGuidance`, `MIN_ENGAGEMENT_MS` | install prompt, never on first paint (also on `./client`) |
 | `PwaStrategyExhaustedError` and the other `errors.ts` classes | the codes this package throws, catchable by an app |
 
 ## Notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/pwa",
-  "version": "26.0.0",
+  "version": "26.1.0",
   "description": "Generated service worker, web manifest, icons, push and version-skew handling.",
   "license": "MIT",
   "type": "module",
@@ -14,7 +14,9 @@
     "provenance": true
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./client": "./src/client.ts",
+    "./schema": "./src/push-schema.ts"
   },
   "files": [
     "src",
@@ -32,6 +34,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "26.0.0"
+    "@ultimat3/action": "26.1.0",
+    "@ultimat3/core": "26.1.0",
+    "@ultimat3/i18n": "26.1.0",
+    "@ultimat3/policy": "26.1.0",
+    "@ultimat3/schema": "26.1.0"
   }
 }

package/src/client.ts

@@ -0,0 +1,37 @@
+// `@ultimat3/pwa/client` — THE browser entry of this package: everything an island or a page script
+// may call, and nothing that drags the server half along. The `.` barrel reaches the icon pipeline
+// (core's image transform, Node-only), the service-worker generator and the push sender; this
+// entry's graph is these four files and `@ultimat3/core/page`, held there by `client-bundle.test.ts`.
+//
+//   import { detectSkew, installController, subscribeToPush } from '@ultimat3/pwa/client';
+//
+// The worker's message TYPE (`'AppUpdateAvailable'`) is core's `APP_UPDATE_MESSAGE`, imported from
+// `@ultimat3/core/page` — one name, one home (`X_HELPER_COPY`); `AppUpdateAvailable` types it here.
+
+export type {
+  BeforeInstallPromptEventLike,
+  InstallController,
+  InstallHost,
+  InstallOptions,
+  InstallOutcome,
+  IosGuidance,
+  ReadSignal,
+} from './install';
+export { installController, iosInstallGuidance, MIN_ENGAGEMENT_MS } from './install';
+export type {
+  PushClientHost,
+  PushPermission,
+  PushRegistrationLike,
+  PushSubscribeOutcome,
+  PushSubscriptionInput,
+  PushSubscriptionLike,
+} from './push-client';
+export {
+  browserPushHost,
+  PUSH_KEY_META,
+  pushPermission,
+  subscribeToPush,
+  unsubscribeFromPush,
+} from './push-client';
+export type { AppUpdateAvailable, SkewState } from './skew';
+export { detectSkew } from './skew';

package/src/errors.ts

@@ -3,7 +3,7 @@
  * fallback, a missing build id, a bad scope — fails here at build time instead.
  */
 
-import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+import { registerErrorCodes, registerErrorRetry, UltimateError } from '@ultimat3/core';
 
 /** Codes this package declares and owns. */
 export const PWA_OWNED_ERROR_CODES = [
@@ -17,6 +17,14 @@ export const PWA_OWNED_ERROR_CODES = [
   // POSTing to `/_x/outbox/flush` (`background-sync.ts`). Registered so an old log still explains.
   'X_PWA_SYNC_FLUSH_FAILED',
   'X_PWA_SYNC_INCOMPLETE',
+  'X_PWA_VAPID_KEY_MISSING',
+  'X_PWA_VAPID_KEY_INVALID',
+  'X_PWA_PUSH_UNCONFIGURED',
+  'X_PWA_PUSH_FAILED',
+  'X_PWA_PUSH_REJECTED',
+  'X_PWA_PUSH_PAYLOAD_TOO_LARGE',
+  'X_PWA_PUSH_SUBSCRIPTION_INVALID',
+  'X_PWA_PUSH_HOST_UNLISTED',
 ] as const;
 
 /**
@@ -41,6 +49,14 @@ export const PWA_ERROR_TITLES: Readonly<Record<PwaOwnedErrorCode, string>> = {
   X_PWA_STRATEGY_EXHAUSTED: 'a caching strategy had no cache, no network and no fallback',
   X_PWA_SYNC_FLUSH_FAILED: 'the background-sync outbox flush was rejected',
   X_PWA_SYNC_INCOMPLETE: 'the background-sync outbox flush left mutations queued',
+  X_PWA_VAPID_KEY_MISSING: 'no VAPID key pair for push',
+  X_PWA_VAPID_KEY_INVALID: 'the VAPID key pair is malformed or not a pair',
+  X_PWA_PUSH_UNCONFIGURED: 'push is not configured in this process',
+  X_PWA_PUSH_FAILED: 'the push service did not accept the message, and may later',
+  X_PWA_PUSH_REJECTED: 'the push service refused the message and will refuse it again',
+  X_PWA_PUSH_PAYLOAD_TOO_LARGE: 'the push message does not fit one 4096-byte record',
+  X_PWA_PUSH_SUBSCRIPTION_INVALID: 'the push subscription is not one a browser produced',
+  X_PWA_PUSH_HOST_UNLISTED: 'the push endpoint is not on a push service this app sends to',
 };
 
 // One unconditional call, so a second package claiming one of pwa's codes throws
@@ -131,3 +147,142 @@ export class PwaStrategyExhaustedError extends UltimateError {
     });
   }
 }
+
+// Web Push. `X_PWA_PUSH_FAILED` is the one a retry can cure — the same message landing later —
+// so it is `retry-after` (a 429's `Retry-After` is honoured through `meta.retryAfterSeconds`); the
+// rest describe the key, the subscription or the body, and every attempt meets them unchanged.
+registerErrorRetry({
+  X_PWA_PUSH_FAILED: 'retry-after',
+  X_PWA_PUSH_REJECTED: 'terminal',
+  X_PWA_PUSH_PAYLOAD_TOO_LARGE: 'terminal',
+  X_PWA_PUSH_SUBSCRIPTION_INVALID: 'terminal',
+  X_PWA_PUSH_HOST_UNLISTED: 'terminal',
+  X_PWA_VAPID_KEY_MISSING: 'terminal',
+  X_PWA_VAPID_KEY_INVALID: 'terminal',
+  X_PWA_PUSH_UNCONFIGURED: 'terminal',
+});
+
+/** The boot refuses push with no key pair in a deployed environment. */
+export class PwaVapidKeyMissingError extends UltimateError {
+  static readonly code = 'X_PWA_VAPID_KEY_MISSING' as const;
+  constructor(input: { missing: readonly string[]; deployed: boolean }) {
+    const unset = `${input.missing.join(' and ')} ${input.missing.length === 1 ? 'is' : 'are'} unset`;
+    super({
+      code: PwaVapidKeyMissingError.code,
+      cause: input.deployed
+        ? `pwa.push is true and ${unset} (or holds the published development key), and a deployed environment never signs with the development pair`
+        : `pwa.push is true and ${unset} while its other half is set — half a pair is never completed with the development one`,
+      fix: "x vapid create   # seals a fresh pair into secrets.enc.json; or set ULTIMATE_VAPID_PUBLIC_KEY and ULTIMATE_VAPID_PRIVATE_KEY in the deployment's environment",
+      meta: { missing: [...input.missing] },
+    });
+  }
+}
+
+/** A key that is not a P-256 key, or a private key that does not sign for its public half. */
+export class PwaVapidKeyInvalidError extends UltimateError {
+  static readonly code = 'X_PWA_VAPID_KEY_INVALID' as const;
+  constructor(input: { key: string; reason: string }) {
+    super({
+      code: PwaVapidKeyInvalidError.code,
+      cause: `${input.key} ${input.reason}`,
+      fix: 'x vapid create   # one command writes both halves, so they cannot disagree',
+      meta: { key: input.key },
+    });
+  }
+}
+
+/** Push used in a process whose boot installed no Web Push runtime. */
+export class PwaPushUnconfiguredError extends UltimateError {
+  static readonly code = 'X_PWA_PUSH_UNCONFIGURED' as const;
+  constructor(input: { operation: string }) {
+    super({
+      code: PwaPushUnconfiguredError.code,
+      cause: `${input.operation} ran in a process whose boot installed no Web Push runtime: pwa.push is false, or pwa.enabled is`,
+      fix: "pwa: { enabled: true, push: true, vapid: { subject: 'mailto:ops@example.com' } }   # in app.config.ts; a test calls installWebPush({ store, keys, subject }) first",
+    });
+  }
+}
+
+/** The push service may accept the same message later: a 429, a 5xx, or no connection at all. */
+export class PwaPushFailedError extends UltimateError {
+  static readonly code = 'X_PWA_PUSH_FAILED' as const;
+  constructor(input: {
+    origin: string;
+    status: number | null;
+    detail: string;
+    retryAfterSeconds?: number | undefined;
+  }) {
+    super({
+      code: PwaPushFailedError.code,
+      cause: `the push service at ${input.origin} answered ${input.status === null ? input.detail : `status ${input.status}`}`,
+      fix: 'x jobs list --json   # the job retries on its policy; a stated Retry-After rides in meta.retryAfterSeconds',
+      meta: {
+        origin: input.origin,
+        status: input.status,
+        ...(input.retryAfterSeconds === undefined
+          ? {}
+          : { retryAfterSeconds: input.retryAfterSeconds }),
+      },
+    });
+  }
+}
+
+/** The push service refused the message, and will refuse it again. */
+export class PwaPushRejectedError extends UltimateError {
+  static readonly code = 'X_PWA_PUSH_REJECTED' as const;
+  constructor(input: { origin: string; status: number; body: string }) {
+    super({
+      code: PwaPushRejectedError.code,
+      cause: `the push service at ${input.origin} refused the message with status ${input.status}${input.body === '' ? '' : `: ${input.body}`}`,
+      fix:
+        input.status === 403 || input.status === 401
+          ? 'x vapid show   # the subscription was made with another public key: a key change means every subscriber subscribes again'
+          : "vapid: { subject: 'mailto:ops@example.com' }   # pwa.vapid in app.config.ts — the push service's answer in the cause names the field it refused",
+      meta: { origin: input.origin, status: input.status },
+    });
+  }
+}
+
+/** One record is 4096 bytes; RFC 8291 leaves 3993 of them for the notification. */
+export class PwaPushPayloadTooLargeError extends UltimateError {
+  static readonly code = 'X_PWA_PUSH_PAYLOAD_TOO_LARGE' as const;
+  constructor(input: { bytes: number; limit: number }) {
+    super({
+      code: PwaPushPayloadTooLargeError.code,
+      cause: `the rendered notification is ${input.bytes} bytes and one Web Push record carries ${input.limit}`,
+      fix: "url: '/posts/1'   # send a path to the content and shorten the catalog strings — never the content itself",
+      meta: { bytes: input.bytes, limit: input.limit },
+    });
+  }
+}
+
+/** A subscription no browser produced: a non-https endpoint, or keys of the wrong size. */
+export class PwaPushSubscriptionInvalidError extends UltimateError {
+  static readonly code = 'X_PWA_PUSH_SUBSCRIPTION_INVALID' as const;
+  constructor(input: { field: string; reason: string }) {
+    super({
+      code: PwaPushSubscriptionInvalidError.code,
+      cause: `${input.field} ${input.reason}`,
+      fix: "import { subscribeToPush } from '@ultimat3/pwa/client';   // it sends PushSubscription.toJSON() unchanged",
+      meta: { field: input.field },
+    });
+  }
+}
+
+/**
+ * An endpoint whose host is not a push service this app sends to. The endpoint arrives in a request
+ * body, and a hostname can resolve anywhere — a private address, the metadata service — so the one
+ * screen that holds is a list of the services themselves (`push-hosts.ts`), not a check of where a
+ * name points today.
+ */
+export class PwaPushHostUnlistedError extends UltimateError {
+  static readonly code = 'X_PWA_PUSH_HOST_UNLISTED' as const;
+  constructor(input: { host: string }) {
+    super({
+      code: PwaPushHostUnlistedError.code,
+      cause: `the endpoint's host ${input.host} is neither a built-in push service (PUSH_SERVICE_HOSTS: FCM, Mozilla, Apple, WNS, or a subdomain of one) nor listed in pwa.vapid.pushHosts`,
+      fix: "vapid: { subject: 'mailto:ops@example.com', pushHosts: ['push.example.com'] }   # pwa.vapid.pushHosts in app.config.ts, for a push service the built-in list does not name",
+      meta: { host: input.host },
+    });
+  }
+}

package/src/index.ts

@@ -30,7 +30,15 @@ export {
   // `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.
+  PwaPushFailedError,
+  PwaPushHostUnlistedError,
+  PwaPushPayloadTooLargeError,
+  PwaPushRejectedError,
+  PwaPushSubscriptionInvalidError,
+  PwaPushUnconfiguredError,
   PwaStrategyExhaustedError,
+  PwaVapidKeyInvalidError,
+  PwaVapidKeyMissingError,
   SwScopeInvalidError,
 } from './errors';
 export type {
@@ -62,7 +70,7 @@ export type {
   IosGuidance,
   ReadSignal,
 } from './install';
-export { installController, iosInstallGuidance } from './install';
+export { installController, iosInstallGuidance, MIN_ENGAGEMENT_MS } from './install';
 export type {
   DisplayMode,
   FileHandler,
@@ -103,10 +111,50 @@ export {
   subscribeSource,
   subscriptionState,
 } from './push';
+export type { PushSubscriptionActionOptions } from './push-actions';
+export { pushSubscribe, pushUnsubscribe } from './push-actions';
+// The browser entry is `@ultimat3/pwa/client` (`client.ts`), never this barrel: an island
+// importing it would pull the service-worker generator into a page bundle. Its meta name is
+// re-exported here because the SERVER writes the tag the client reads.
+export { PUSH_KEY_META } from './push-client';
+export type { PushReceiverKeys } from './push-decrypt';
+export { decryptPushMessage } from './push-decrypt';
+export type { PushEncryptionKeys, PushEncryptOptions } from './push-encrypt';
+export { encryptPushMessage, PUSH_RECORD_SIZE, pushMessageCapacity } from './push-encrypt';
+export { PUSH_SERVICE_HOSTS, pushHostAllowed } from './push-hosts';
+export type { WebPushOptions, WebPushRuntime } from './push-runtime';
+export { installedVapid, installWebPush, resetWebPush, webPushRuntime } from './push-runtime';
+export type {
+  PushDelivery,
+  PushSendInput,
+  PushSendOutcome,
+  PushTarget,
+  PushUrgency,
+  VapidSigner,
+} from './push-send';
+export {
+  assertPushEndpoint,
+  DEFAULT_PUSH_TTL_SECONDS,
+  PUSH_SEND_TIMEOUT_MS,
+  PUSH_URGENCIES,
+  pushEndpointProblem,
+  sendPushMessage,
+} from './push-send';
+export type { PushSubscriptionStore } from './push-store';
+export { memoryPushSubscriptionStore } from './push-store';
+export type { PostgresPushSubscriptionStoreOptions } from './push-store-pg';
+export { postgresPushSubscriptionStore } from './push-store-pg';
 export type { RouteRule } from './route-rules';
 export { assetRules, routeRules } from './route-rules';
 export type { ServiceWorkerConfig, ServiceWorkerOutput } from './service-worker';
 export { assertScope, generateServiceWorker, PRECACHE_CONCURRENCY } from './service-worker';
+// 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, SkewState } from './skew';
+export { detectSkew } from './skew';
 export type {
   PwaRoute,
   StrategyCache,
@@ -124,23 +172,19 @@ 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,
-  RetentionPlan,
-  SkewState,
-} from './version-skew';
+export type { VapidKeyPair, VapidTokenInput } from './vapid';
 export {
-  assertBuildId,
-  buildId,
-  cacheNamespace,
-  detectSkew,
-  retentionPlan,
-} from './version-skew';
+  assertVapidPair,
+  generateVapidKeys,
+  importVapidKeys,
+  VAPID_PRIVATE_KEY_ENV,
+  VAPID_PUBLIC_KEY_ENV,
+  VAPID_TOKEN_TTL_SECONDS,
+  vapidAuthorization,
+} from './vapid';
+export type { ResolvedVapidKeys } from './vapid-keys';
+export { DEV_VAPID_KEYS, resolveVapidKeys, usesDevVapidKeys } from './vapid-keys';
+export type { BuildIdInput, Deploy, DeployChannel, RetentionPlan } from './version-skew';
+export { assertBuildId, buildId, cacheNamespace, retentionPlan } from './version-skew';
+export type { PushNotification, PushReport, WebPusher } from './web-push';
+export { pushToActor, webPush } from './web-push';

package/src/install.ts

@@ -5,7 +5,8 @@
  * permanently on some platforms.
  */
 
-import { finiteCount } from '@ultimat3/core';
+// `/page`: the browser-safe subpath — this file is in `@ultimat3/pwa/client`'s graph.
+import { finiteCount } from '@ultimat3/core/page';
 
 /** A minimal signal so this file needs no framework runtime. */
 export interface ReadSignal<T> {