@ultimat3/pwa 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# 📲 @ultimat3/pwa
+
+**You never open `sw.js`.** It is emitted from the route table. That is this package's
+whole thesis: a hand-written service worker encodes routing decisions a second time, and
+the second copy is the one nobody updates.
+
+```ts
+const { source, precache, warnings } = generateServiceWorker(describeRoutes(), config, buildId);
+```
+
+## Render mode → runtime strategy
+
+| Render mode | Strategy | Why |
+|---|---|---|
+| `static` | cache-first | built once; the URL's bytes only change on deploy |
+| `isr` | stale-while-revalidate | stale is correct by construction, refresh behind |
+| `stream` | stale-while-revalidate | shell is reusable, holes come from the network |
+| `ssr` | network-first | freshness is the point; cache is the offline safety net |
+| `spa` | cache-first | the shell is identical for every actor |
+
+Overrides: `offline: 'network-only'` forces `network-only`; a per-route `strategy` wins over
+everything. `api/` routes get no cache rule at all.
+
+| `offline` | Meaning |
+|---|---|
+| `precache` | fetched at install, keyed by content hash |
+| `runtime` | cached on first visit under the render-mode strategy |
+| `network-only` | never served from a cache |
+
+## Version skew — the thing that actually breaks PWAs
+
+A client loaded build A hours ago. Build B deletes A's chunks. The next lazy import 404s
+and the app dies with a blank screen and no error anyone can act on.
+
+| Mechanism | Rule |
+|---|---|
+| Build id | immutable per deploy, derived from the commit sha; `X_BUILD_ID_MISSING` if absent |
+| 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) |
+| 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 }
+```
+
+`unknown` means no id was sent — a first load or a crawler — and is never treated as stale.
+
+## The offline fallback is mandatory in the type
+
+```
+X_PWA_NO_OFFLINE_FALLBACK: no offline fallback route
+  cause: app.config.ts has no `offline` block, so an offline navigation would show the browser's error page
+  fix:   create app/offline.tsx and set offline.fallback
+```
+
+`requireOfflineFallback(config)` runs inside `generateServiceWorker`, so the build fails
+before an un-shippable PWA exists.
+
+## Capabilities are opt-in, and gate bytes
+
+| Capability | Manifest member | SW code |
+|---|---|---|
+| `push` | — | `push` + `notificationclick` listeners |
+| `backgroundSync` | — | `sync` listener + outbox flush |
+| `badging` | — | `navigator.setAppBadge` after a push |
+| `shareTarget` | `share_target` | share-target route rule |
+| `fileHandlers` | `file_handlers` | — |
+| `protocolHandlers` | `protocol_handlers` | — |
+
+A disabled capability emits neither the manifest member nor the SW code. An unused
+capability ships zero bytes and asks for zero permissions.
+
+## Public API
+
+| Export | Owns |
+|---|---|
+| `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 |
+| `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 |
+| `requireOfflineFallback` | the mandatory offline route |
+| `backgroundSyncSource`, `retryDelayMs` | the Background Sync trigger |
+| `renderPushPayload`, `pushSource`, `subscribeSource` | Web Push, per-locale bodies |
+| `createInstallController`, `iosInstallGuidance` | install prompt, never on first paint |
+
+## Notes
+
+- **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.
+- **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
+  only the Background Sync trigger that asks realtime to flush.
+- **Push bodies are rendered server-side per subscriber locale**, from the locale stored on
+  the subscription. A notification in the wrong language is a real bug, and the sending
+  server has no request context to infer one from.
+- **Icons come from one source image.** `X_PWA_ICON_MISSING` names the file to add;
+  `BuiltinImagePipeline` renders the whole matrix from it through `@ultimat3/core`'s image
+  pipeline — no `sharp`, no vendor image CDN, no native build step. Every output is a square
+  PNG, because `type: 'image/png'` is what the manifest declares. A maskable icon's artwork
+  lands exactly inside `maskableSafeZone(size)`; the ring around it is `background`, which is
+  hex or `transparent` (there are no named colours). Same bytes in, same bytes out.
+- **Route data arrives as data.** `@ultimat3/render` and `@ultimat3/pwa` are both tier 4, so
+  `PwaRoute` is a structural view of `RouteDescriptor`, never an import.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@ultimat3/pwa",
+  "version": "1.0.0",
+  "description": "Generated service worker, web manifest, icons, push and version-skew handling.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/pwa"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/core": "1.0.0"
+  }
+}

package/src/background-sync.ts

@@ -0,0 +1,117 @@
+/**
+ * Background Sync registration for the offline mutation queue.
+ *
+ * SRP: the queue itself — the outbox, the optimistic local twins, the conflict policy —
+ * belongs to `@ultimat3/realtime`. This file owns only the browser-side trigger: register
+ * a sync tag, and when the platform says connectivity is back, ask realtime to flush.
+ * Nothing here knows what a mutation is, and it must stay that way.
+ *
+ * The two failures below (`X_PWA_SYNC_FLUSH_FAILED`, `X_PWA_SYNC_INCOMPLETE`, documented in
+ * `./errors.ts`) run inside the string emitted into `sw.js` — the browser's service-worker
+ * realm, which has no bundler and cannot import `@ultimat3/core`. What it *can* have is a class
+ * of its own, so `SYNC_ERROR_CLASS` emits one: a bare `Error` carries a message and nothing a
+ * caller can read, while the emitted class exposes the same `code`, `cause`, `fix` and `docs` an
+ * `UltimateError` does everywhere else in the framework.
+ */
+
+import { PwaSyncFlushFailedError, PwaSyncIncompleteError } from './errors';
+import { BUILD_ID_HEADER } from './version-skew';
+
+export const SYNC_TAG = 'x-outbox';
+export const PERIODIC_SYNC_TAG = 'x-refresh';
+
+export interface RetryPolicy {
+  readonly maxAttempts: number;
+  readonly baseDelayMs: number;
+  readonly maxDelayMs: number;
+}
+
+export const DEFAULT_RETRY: RetryPolicy = Object.freeze({
+  maxAttempts: 6,
+  baseDelayMs: 1_000,
+  maxDelayMs: 5 * 60 * 1000,
+});
+
+/**
+ * Deterministic exponential backoff — no jitter here on purpose: the Background Sync
+ * scheduler already spreads wake-ups across clients, and a deterministic delay is
+ * testable and reproducible in a bug report.
+ */
+export function retryDelayMs(attempt: number, policy: RetryPolicy = DEFAULT_RETRY): number {
+  const clamped = Math.max(1, Math.min(attempt, policy.maxAttempts));
+  return Math.min(policy.baseDelayMs * 2 ** (clamped - 1), policy.maxDelayMs);
+}
+
+export function shouldRetry(attempt: number, policy: RetryPolicy = DEFAULT_RETRY): boolean {
+  return attempt < policy.maxAttempts;
+}
+
+export interface BackgroundSyncOptions {
+  /** Endpoint `@ultimat3/realtime` exposes to flush the outbox. */
+  readonly flushEndpoint?: string;
+  readonly retry?: RetryPolicy;
+  /** Minimum interval for periodic sync, when the platform grants it. */
+  readonly periodicMinIntervalMs?: number;
+}
+
+export const DEFAULT_FLUSH_ENDPOINT = '/_x/outbox/flush';
+
+/**
+ * Where the emitted class sends a reader. The same host `./errors.ts` documents these two codes
+ * at — retyped here because the SW builds its URL from the code at throw time, and
+ * `background-sync.test.ts` asserts the two halves still agree.
+ */
+const SYNC_DOCS_BASE = 'https://ultimate.dev/errors/';
+
+/**
+ * The generated realm's own coded error, as source. Small on purpose — this ships in `sw.js` — and
+ * deliberately not a bare `Error`: `code` is what a reporting hook groups on, `fix` is what the
+ * developer in devtools acts on, and neither survives being flattened into a message alone. The
+ * message still renders the contract's own line shape, because an uncaught `waitUntil` rejection
+ * prints nothing else.
+ */
+const SYNC_ERROR_CLASS = `
+class PwaSyncError extends Error{
+  constructor(code,cause,fix){
+    const docs=${JSON.stringify(SYNC_DOCS_BASE)}+code;
+    super(code+': '+cause+'\\n  fix:   '+fix+'\\n  docs:  '+docs);
+    this.name='PwaSyncError';this.code=code;this.cause=cause;this.fix=fix;this.docs=docs;
+  }
+}`.trim();
+
+/**
+ * Emitted into `sw.js` only when the `backgroundSync` capability is on. The handler posts
+ * to realtime's flush endpoint; a non-2xx keeps the sync registration alive so the
+ * platform retries with its own scheduling.
+ */
+export function backgroundSyncSource(options: BackgroundSyncOptions = {}): string {
+  const endpoint = options.flushEndpoint ?? DEFAULT_FLUSH_ENDPOINT;
+  const retry = options.retry ?? DEFAULT_RETRY;
+  return `
+const SYNC_TAG=${JSON.stringify(SYNC_TAG)};
+const FLUSH_ENDPOINT=${JSON.stringify(endpoint)};
+const SYNC_MAX_ATTEMPTS=${retry.maxAttempts};
+${SYNC_ERROR_CLASS}
+async function flushOutbox(){
+  const res=await fetch(FLUSH_ENDPOINT,{method:'POST',headers:{${JSON.stringify(BUILD_ID_HEADER)}:BUILD_ID}});
+  if(!res.ok)throw new PwaSyncError(${JSON.stringify(PwaSyncFlushFailedError.code)},'outbox flush POST '+FLUSH_ENDPOINT+' returned '+res.status,'curl -i -X POST '+FLUSH_ENDPOINT+' — @ultimat3/realtime must mount it and answer 2xx');
+  const body=await res.json().catch(()=>({remaining:0}));
+  if(body.remaining>0)throw new PwaSyncError(${JSON.stringify(PwaSyncIncompleteError.code)},'outbox flush at '+FLUSH_ENDPOINT+' left '+body.remaining+' mutation(s) queued','x dev --role sync   # drain the outbox, or raise pwa.backgroundSync.retry.maxAttempts in app.config.ts');
+}
+self.addEventListener('sync',(event)=>{
+  if(event.tag!==SYNC_TAG)return;
+  // Rejecting keeps the registration so the platform retries on its own schedule.
+  event.waitUntil(flushOutbox());
+});`.trim();
+}
+
+/** Client-side registration. Falls back to an `online` listener where sync is missing. */
+export function registerBackgroundSyncSource(): string {
+  return `
+export async function registerOutboxSync(registration){
+  const sync=registration.sync;
+  if(sync&&typeof sync.register==='function'){await sync.register(${JSON.stringify(SYNC_TAG)});return 'sync'}
+  addEventListener('online',()=>{navigator.serviceWorker.controller?.postMessage({type:'flush-outbox'})});
+  return 'fallback'
+}`.trim();
+}

package/src/capabilities.ts

@@ -0,0 +1,70 @@
+/**
+ * The opt-in capability flags from `app.config.ts`. Each flag gates BOTH the manifest
+ * entry and the service-worker code, so a capability you did not ask for ships zero
+ * bytes and requests zero permissions.
+ */
+
+export const CAPABILITIES = [
+  'push',
+  'backgroundSync',
+  'badging',
+  'shareTarget',
+  'fileHandlers',
+  'protocolHandlers',
+] as const;
+
+export type Capability = (typeof CAPABILITIES)[number];
+
+export type CapabilityFlags = { readonly [K in Capability]?: boolean };
+export type ResolvedCapabilities = Readonly<Record<Capability, boolean>>;
+
+/** Everything is off unless the app turns it on. */
+export function resolveCapabilities(flags: CapabilityFlags = {}): ResolvedCapabilities {
+  const resolved: Record<Capability, boolean> = {
+    push: false,
+    backgroundSync: false,
+    badging: false,
+    shareTarget: false,
+    fileHandlers: false,
+    protocolHandlers: false,
+  };
+  for (const capability of CAPABILITIES) {
+    resolved[capability] = flags[capability] === true;
+  }
+  return resolved;
+}
+
+export function isEnabled(capabilities: ResolvedCapabilities, capability: Capability): boolean {
+  return capabilities[capability];
+}
+
+export function enabledCapabilities(capabilities: ResolvedCapabilities): readonly Capability[] {
+  return CAPABILITIES.filter((capability) => capabilities[capability]);
+}
+
+/** 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'],
+  });
+
+/**
+ * The service-worker code each capability emits — its listener, and anything that listener alone
+ * needs. Used to assert nothing leaks when disabled: `PwaSyncError` is the background-sync
+ * handler's own error class, so it ships with the handler and never without 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: ['/_x/share-target'],
+    fileHandlers: [],
+    protocolHandlers: [],
+  },
+);

package/src/errors.ts

@@ -0,0 +1,176 @@
+/**
+ * PWA error codes. Everything that breaks a PWA in production — a missing offline
+ * fallback, a missing build id, a bad scope — fails here at build time instead.
+ */
+
+import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+
+/** Codes this package declares and owns. */
+export const PWA_OWNED_ERROR_CODES = [
+  'X_PWA_NO_OFFLINE_FALLBACK',
+  'X_PWA_ICON_MISSING',
+  'X_PWA_MANIFEST_INVALID',
+  'X_BUILD_ID_MISSING',
+  'X_SW_SCOPE_INVALID',
+  'X_PWA_STRATEGY_EXHAUSTED',
+  'X_PWA_SYNC_FLUSH_FAILED',
+  'X_PWA_SYNC_INCOMPLETE',
+] as const;
+
+/**
+ * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s. Thrown here, titled only there — the copy this file
+ * used to keep was a second title that could drift from core's with nothing to catch it.
+ */
+export const PWA_BORROWED_ERROR_CODES = ['X_NOT_IMPLEMENTED'] as const;
+
+/** Every code pwa can throw: the ones it owns plus the one it borrows. */
+export const PWA_ERROR_CODES = [...PWA_OWNED_ERROR_CODES, ...PWA_BORROWED_ERROR_CODES] as const;
+
+export type PwaOwnedErrorCode = (typeof PWA_OWNED_ERROR_CODES)[number];
+export type PwaErrorCode = (typeof PWA_ERROR_CODES)[number];
+
+export const PWA_ERROR_TITLES: Readonly<Record<PwaOwnedErrorCode, string>> = {
+  X_PWA_NO_OFFLINE_FALLBACK: 'pwa.offline.fallback is not set',
+  X_PWA_ICON_MISSING: 'no source icon to generate from',
+  X_PWA_MANIFEST_INVALID: 'the generated web manifest failed validation',
+  X_BUILD_ID_MISSING: 'no immutable build ID',
+  X_SW_SCOPE_INVALID: 'the service-worker scope cannot serve the routes it precaches',
+  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',
+};
+
+// One unconditional call, so a second package claiming one of pwa's codes throws
+// X_ERROR_CODE_DUPLICATE instead of losing silently to whichever module imported first.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(PWA_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+);
+
+const docsFor = (code: PwaErrorCode): string => `https://ultimate.dev/errors/${code}`;
+
+/** No `app/offline.tsx`. You cannot ship a PWA that has nothing to show offline. */
+export class PwaNoOfflineFallbackError extends UltimateError {
+  static readonly code = 'X_PWA_NO_OFFLINE_FALLBACK' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: PwaNoOfflineFallbackError.code,
+      cause,
+      fix,
+      docs: docsFor(PwaNoOfflineFallbackError.code),
+    });
+  }
+}
+
+/** The single source icon is missing or too small to derive the size matrix from. */
+export class PwaIconMissingError extends UltimateError {
+  static readonly code = 'X_PWA_ICON_MISSING' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: PwaIconMissingError.code,
+      cause,
+      fix,
+      docs: docsFor(PwaIconMissingError.code),
+    });
+  }
+}
+
+/** The generated web manifest would be rejected by the browser. */
+export class PwaManifestInvalidError extends UltimateError {
+  static readonly code = 'X_PWA_MANIFEST_INVALID' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: PwaManifestInvalidError.code,
+      cause,
+      fix,
+      docs: docsFor(PwaManifestInvalidError.code),
+    });
+  }
+}
+
+/** No immutable build id, so caches cannot be keyed and skew cannot be detected. */
+export class BuildIdMissingError extends UltimateError {
+  static readonly code = 'X_BUILD_ID_MISSING' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: BuildIdMissingError.code,
+      cause,
+      fix,
+      docs: docsFor(BuildIdMissingError.code),
+    });
+  }
+}
+
+/** The service worker's scope cannot cover the URLs it is asked to control. */
+export class SwScopeInvalidError extends UltimateError {
+  static readonly code = 'X_SW_SCOPE_INVALID' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: SwScopeInvalidError.code,
+      cause,
+      fix,
+      docs: docsFor(SwScopeInvalidError.code),
+    });
+  }
+}
+
+/**
+ * A strategy exhausted the cache, the network, and any declared fallback. Runs in-process (the
+ * `STRATEGY_FNS` half of `strategies.ts`, tested for parity with the `STRATEGY_SOURCE` emitted
+ * into `sw.js`), so it can import core the way the generated bundle below cannot.
+ */
+export class PwaStrategyExhaustedError extends UltimateError {
+  static readonly code = 'X_PWA_STRATEGY_EXHAUSTED' as const;
+  constructor(input: { cacheName: string }) {
+    super({
+      code: PwaStrategyExhaustedError.code,
+      cause: `no cached response and the network failed for "${input.cacheName}"`,
+      fix: 'pass options.fallback to staleWhileRevalidate(request, env, options), or set pwa.offline.fallback in app.config.ts',
+      docs: docsFor(PwaStrategyExhaustedError.code),
+    });
+  }
+}
+
+/**
+ * Titles one of the two failures `backgroundSyncSource()` emits into `sw.js`, and owns the `code`
+ * the emitted source throws. The generated code runs in the browser's service-worker realm, which
+ * has no bundler and no `@ultimat3/core` to import — so it defines a local `PwaSyncError` carrying
+ * this same code, cause, fix and docs rather than constructing this class. This class is what gives
+ * the code one title and one wiki row, the same as every other code in this file.
+ */
+export class PwaSyncFlushFailedError extends UltimateError {
+  static readonly code = 'X_PWA_SYNC_FLUSH_FAILED' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: PwaSyncFlushFailedError.code,
+      cause,
+      fix,
+      docs: docsFor(PwaSyncFlushFailedError.code),
+    });
+  }
+}
+
+/** Documented for the same reason as {@link PwaSyncFlushFailedError} — see its comment. */
+export class PwaSyncIncompleteError extends UltimateError {
+  static readonly code = 'X_PWA_SYNC_INCOMPLETE' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: PwaSyncIncompleteError.code,
+      cause,
+      fix,
+      docs: docsFor(PwaSyncIncompleteError.code),
+    });
+  }
+}
+
+/** A driver whose interface exists and whose backing implementation does not, yet. */
+export class NotImplementedError extends UltimateError {
+  static readonly code = 'X_NOT_IMPLEMENTED' as const;
+  constructor(cause: string, fix: string) {
+    super({
+      code: NotImplementedError.code,
+      cause,
+      fix,
+      docs: docsFor(NotImplementedError.code),
+    });
+  }
+}