@ultimat3/pwa 1.0.0

package/src/icons.ts

@@ -0,0 +1,187 @@
+/**
+ * Icons and splash screens from ONE source image. Nobody hand-maintains fourteen PNGs;
+ * they maintain three and forget the maskable safe zone, which is why installed Android
+ * icons end up with clipped logos.
+ */
+
+import { transformImageBytes } from '@ultimat3/core';
+import { PwaIconMissingError } from './errors';
+import type { ManifestIcon } from './manifest';
+
+export type IconPurpose = 'any' | 'maskable' | 'monochrome' | 'apple-touch';
+
+export interface IconSpec {
+  readonly size: number;
+  readonly purpose: IconPurpose;
+  readonly filename: string;
+  /** Fraction of the edge reserved as padding so the safe zone survives masking. */
+  readonly padding: number;
+}
+
+/** Maskable icons are cropped to a circle of ~80% of the edge; 10% padding per side. */
+export const MASKABLE_PADDING = 0.1;
+
+export const ICON_MATRIX: readonly IconSpec[] = Object.freeze([
+  { size: 48, purpose: 'any', filename: 'icon-48.png', padding: 0 },
+  { size: 72, purpose: 'any', filename: 'icon-72.png', padding: 0 },
+  { size: 96, purpose: 'any', filename: 'icon-96.png', padding: 0 },
+  { size: 128, purpose: 'any', filename: 'icon-128.png', padding: 0 },
+  { size: 192, purpose: 'any', filename: 'icon-192.png', padding: 0 },
+  { size: 256, purpose: 'any', filename: 'icon-256.png', padding: 0 },
+  { size: 384, purpose: 'any', filename: 'icon-384.png', padding: 0 },
+  { size: 512, purpose: 'any', filename: 'icon-512.png', padding: 0 },
+  { size: 192, purpose: 'maskable', filename: 'icon-maskable-192.png', padding: MASKABLE_PADDING },
+  { size: 512, purpose: 'maskable', filename: 'icon-maskable-512.png', padding: MASKABLE_PADDING },
+  { size: 512, purpose: 'monochrome', filename: 'icon-mono-512.png', padding: MASKABLE_PADDING },
+  { size: 180, purpose: 'apple-touch', filename: 'apple-touch-icon.png', padding: 0 },
+  { size: 167, purpose: 'apple-touch', filename: 'apple-touch-icon-167.png', padding: 0 },
+  { size: 152, purpose: 'apple-touch', filename: 'apple-touch-icon-152.png', padding: 0 },
+]);
+
+export interface SplashSpec {
+  readonly width: number;
+  readonly height: number;
+  readonly ratio: number;
+  readonly orientation: 'portrait' | 'landscape';
+  readonly filename: string;
+}
+
+/** iOS still needs explicit splash images; every other platform derives them. */
+export const SPLASH_MATRIX: readonly SplashSpec[] = Object.freeze([
+  { width: 1290, height: 2796, ratio: 3, orientation: 'portrait', filename: 'splash-1290.png' },
+  { width: 1179, height: 2556, ratio: 3, orientation: 'portrait', filename: 'splash-1179.png' },
+  { width: 1170, height: 2532, ratio: 3, orientation: 'portrait', filename: 'splash-1170.png' },
+  { width: 1125, height: 2436, ratio: 3, orientation: 'portrait', filename: 'splash-1125.png' },
+  { width: 828, height: 1792, ratio: 2, orientation: 'portrait', filename: 'splash-828.png' },
+  { width: 1536, height: 2048, ratio: 2, orientation: 'portrait', filename: 'splash-1536.png' },
+  { width: 2048, height: 2732, ratio: 2, orientation: 'portrait', filename: 'splash-2048.png' },
+]);
+
+export interface SafeZone {
+  /** Pixels of padding on each edge. */
+  readonly padding: number;
+  /** Edge length of the region the artwork may occupy. */
+  readonly inner: number;
+}
+
+export function maskableSafeZone(size: number, padding = MASKABLE_PADDING): SafeZone {
+  const pad = Math.round(size * padding);
+  return { padding: pad, inner: size - pad * 2 };
+}
+
+export interface ImageTransform {
+  readonly size: number;
+  readonly padding: number;
+  /** `'#rgb' | '#rgba' | '#rrggbb' | '#rrggbbaa' | 'transparent'`. There are no named colours. */
+  readonly background?: string;
+}
+
+/** The transform driver: source bytes in, one square PNG of `transform.size` out. */
+export interface ImagePipeline {
+  resize(source: Uint8Array, transform: ImageTransform): Promise<Uint8Array>;
+}
+
+/**
+ * The one driver, backed by core's zero-dependency pipeline — no `sharp`, no image CDN.
+ * Always square PNG: `toManifestIcon` declares `type: 'image/png'`, so any other format
+ * would make the manifest lie about bytes the browser then refuses.
+ *
+ * `async` on purpose. A `Promise`-typed method that throws synchronously skips every
+ * `.catch()` a caller wrote; an undecodable source or a named colour must reject instead.
+ */
+export class BuiltinImagePipeline implements ImagePipeline {
+  async resize(source: Uint8Array, transform: ImageTransform): Promise<Uint8Array> {
+    return transformImageBytes(source, {
+      width: transform.size,
+      height: transform.size,
+      fit: 'contain',
+      padding: transform.padding,
+      background: transform.background,
+      format: 'png',
+    });
+  }
+}
+
+export interface IconSourceConfig {
+  /** Path to the ONE source icon, 1024x1024 or larger, square. */
+  readonly sourceIcon?: string;
+  readonly outDir?: string;
+  readonly background?: string;
+}
+
+export interface IconPlanEntry {
+  readonly spec: IconSpec;
+  readonly outputPath: string;
+  readonly transform: ImageTransform;
+  readonly manifestIcon: ManifestIcon | null;
+}
+
+export interface IconPlan {
+  readonly source: string;
+  readonly entries: readonly IconPlanEntry[];
+  readonly splashes: readonly SplashSpec[];
+  readonly manifestIcons: readonly ManifestIcon[];
+}
+
+/** `x doctor` calls this: a missing source icon must report a fix, not a stack trace. */
+export function requireSourceIcon(config: IconSourceConfig): string {
+  const source = config.sourceIcon;
+  if (source === undefined || source.trim() === '') {
+    throw new PwaIconMissingError(
+      'no source icon: pwa.sourceIcon is unset, so no manifest icon can be generated and ' +
+        'the app is not installable',
+      "add a 1024x1024 square PNG at assets/icon.png and set pwa.sourceIcon: 'assets/icon.png'",
+    );
+  }
+  return source;
+}
+
+export function planIcons(config: IconSourceConfig): IconPlan {
+  const source = requireSourceIcon(config);
+  const outDir = (config.outDir ?? '/icons').replace(/\/$/, '');
+
+  const entries = ICON_MATRIX.map((spec) => {
+    const outputPath = `${outDir}/${spec.filename}`;
+    const transform: ImageTransform = {
+      size: spec.size,
+      padding: spec.padding,
+      ...(config.background === undefined ? {} : { background: config.background }),
+    };
+    return {
+      spec,
+      outputPath,
+      transform,
+      manifestIcon: toManifestIcon(spec, outputPath),
+    };
+  });
+
+  return {
+    source,
+    entries,
+    splashes: SPLASH_MATRIX,
+    manifestIcons: entries
+      .map((entry) => entry.manifestIcon)
+      .filter((icon): icon is ManifestIcon => icon !== null),
+  };
+}
+
+/** Apple touch icons are `<link rel="apple-touch-icon">`, not manifest members. */
+function toManifestIcon(spec: IconSpec, outputPath: string): ManifestIcon | null {
+  if (spec.purpose === 'apple-touch') return null;
+  return {
+    src: outputPath,
+    sizes: `${spec.size}x${spec.size}`,
+    type: 'image/png',
+    purpose: spec.purpose,
+  };
+}
+
+export function appleTouchLinks(plan: IconPlan): string {
+  return plan.entries
+    .filter((entry) => entry.spec.purpose === 'apple-touch')
+    .map(
+      (entry) =>
+        `<link rel="apple-touch-icon" sizes="${entry.spec.size}x${entry.spec.size}" href="${entry.outputPath}">`,
+    )
+    .join('');
+}

package/src/index.ts

@@ -0,0 +1,155 @@
+/** Public API of `@ultimat3/pwa`. You never open `sw.js`; you call these. */
+
+export type { BackgroundSyncOptions, RetryPolicy } from './background-sync';
+export {
+  backgroundSyncSource,
+  DEFAULT_FLUSH_ENDPOINT,
+  DEFAULT_RETRY,
+  PERIODIC_SYNC_TAG,
+  registerBackgroundSyncSource,
+  retryDelayMs,
+  SYNC_TAG,
+  shouldRetry,
+} from './background-sync';
+export type { Capability, CapabilityFlags, ResolvedCapabilities } from './capabilities';
+export {
+  CAPABILITIES,
+  CAPABILITY_MANIFEST_KEYS,
+  CAPABILITY_SW_MARKERS,
+  enabledCapabilities,
+  isEnabled,
+  resolveCapabilities,
+} from './capabilities';
+export type { PwaErrorCode } from './errors';
+export {
+  BuildIdMissingError,
+  NotImplementedError,
+  PWA_ERROR_CODES,
+  PWA_ERROR_TITLES,
+  PwaIconMissingError,
+  PwaManifestInvalidError,
+  PwaNoOfflineFallbackError,
+  SwScopeInvalidError,
+} from './errors';
+export type {
+  IconPlan,
+  IconPlanEntry,
+  IconPurpose,
+  IconSourceConfig,
+  IconSpec,
+  ImagePipeline,
+  ImageTransform,
+  SafeZone,
+  SplashSpec,
+} from './icons';
+export {
+  appleTouchLinks,
+  BuiltinImagePipeline,
+  ICON_MATRIX,
+  MASKABLE_PADDING,
+  maskableSafeZone,
+  planIcons,
+  requireSourceIcon,
+  SPLASH_MATRIX,
+} from './icons';
+export type {
+  BeforeInstallPromptEventLike,
+  InstallController,
+  InstallHost,
+  InstallOptions,
+  InstallOutcome,
+  IosGuidance,
+  ReadSignal,
+} from './install';
+export { createInstallController, iosInstallGuidance, MIN_ENGAGEMENT_MS } from './install';
+export type {
+  DisplayMode,
+  FileHandler,
+  ManifestIcon,
+  ManifestScreenshot,
+  ManifestShortcut,
+  Orientation,
+  ProtocolHandler,
+  PwaConfig,
+  SchemeColors,
+  ShareTarget,
+  ThemeColorMeta,
+  ThemeTokens,
+  WebManifest,
+  WebManifestResult,
+} from './manifest';
+export { generateWebManifest, renderThemeColorMeta, serializeWebManifest } from './manifest';
+export type { OfflineConfig, OfflineFallback } from './offline-fallback';
+export { offlineFallbackSource, requireOfflineFallback } from './offline-fallback';
+export type { PrecacheAsset, PrecacheEntry, PrecacheInput, PrecacheManifest } from './precache';
+export {
+  buildPrecacheManifest,
+  DEFAULT_PRECACHE_WARN_BYTES,
+  formatBytes,
+  serializePrecacheManifest,
+} from './precache';
+export type {
+  PushPayload,
+  PushSourceOptions,
+  PushSubscriptionKeys,
+  PushSubscriptionRecord,
+  RenderedNotification,
+  SubscriptionState,
+  Translate,
+  VapidConfig,
+} from './push';
+export {
+  pushSource,
+  renderPushPayload,
+  serializePushMessage,
+  subscribeSource,
+  subscriptionState,
+} from './push';
+export type { RouteRule, ServiceWorkerConfig, ServiceWorkerOutput } from './service-worker';
+export { assertScope, generateServiceWorker, routeRules } from './service-worker';
+export type {
+  PwaOfflineStrategy,
+  PwaRenderMode,
+  PwaRoute,
+  StrategyCache,
+  StrategyEnv,
+  StrategyName,
+  StrategyOptions,
+} from './strategies';
+export {
+  cacheFirst,
+  MODE_STRATEGY,
+  networkFirst,
+  networkOnly,
+  STRATEGY_FN_NAMES,
+  STRATEGY_FNS,
+  STRATEGY_NAMES,
+  STRATEGY_SOURCE,
+  staleWhileRevalidate,
+  strategyFor,
+} from './strategies';
+export type {
+  AppUpdateAvailable,
+  BuildIdInput,
+  Deploy,
+  DeployChannel,
+  ForceReason,
+  RetentionPlan,
+  SkewState,
+  UpdatePolicy,
+  UpdatePolicyInput,
+  UpdateSignalInput,
+} from './version-skew';
+export {
+  APP_UPDATE_AVAILABLE,
+  assertBuildId,
+  BUILD_ID_HEADER,
+  BUILD_ID_META,
+  buildId,
+  cacheNamespace,
+  DEFAULT_GRACE_MS,
+  detectSkew,
+  retentionPlan,
+  updatePolicy,
+  updateSignal,
+} from './version-skew';

package/src/install.ts

@@ -0,0 +1,137 @@
+/**
+ * Install prompt handling. Two rules: capture `beforeinstallprompt` so the browser's own
+ * bar is suppressed and the app owns the moment, and NEVER prompt on first paint — an
+ * install prompt before the user knows what the app is converts worse and is dismissed
+ * permanently on some platforms.
+ */
+
+/** A minimal signal so this file needs no framework runtime. */
+export interface ReadSignal<T> {
+  (): T;
+  subscribe(listener: (value: T) => void): () => void;
+}
+
+interface WritableSignal<T> extends ReadSignal<T> {
+  set(value: T): void;
+}
+
+function createSignal<T>(initial: T): WritableSignal<T> {
+  let value = initial;
+  const listeners = new Set<(value: T) => void>();
+  const read = (() => value) as WritableSignal<T>;
+  read.set = (next: T): void => {
+    if (Object.is(next, value)) return;
+    value = next;
+    for (const listener of listeners) listener(next);
+  };
+  read.subscribe = (listener) => {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  };
+  return read;
+}
+
+export type InstallOutcome = 'accepted' | 'dismissed' | 'unavailable' | 'too-early';
+
+export interface BeforeInstallPromptEventLike {
+  preventDefault(): void;
+  prompt(): Promise<void>;
+  readonly userChoice: Promise<{ readonly outcome: 'accepted' | 'dismissed' }>;
+}
+
+/** Structural view of the host, so this runs under `bun test` with no DOM. */
+export interface InstallHost {
+  addEventListener(type: string, handler: (event: unknown) => void): void;
+  removeEventListener(type: string, handler: (event: unknown) => void): void;
+  /** `navigator.userAgent`. */
+  readonly userAgent: string;
+  /** True when already running as an installed app. */
+  readonly standalone: boolean;
+  readonly now: () => number;
+}
+
+export interface InstallOptions {
+  readonly host: InstallHost;
+  /** How long the user must have been on the page before a prompt is allowed. */
+  readonly minEngagementMs?: number;
+}
+
+/** Long enough that the prompt follows intent, short enough to still be useful. */
+export const MIN_ENGAGEMENT_MS = 30_000;
+
+export interface IosGuidance {
+  readonly platform: 'ios';
+  /** i18n key — never a literal string. */
+  readonly instructionKey: string;
+  readonly stepKeys: readonly string[];
+}
+
+export interface InstallController {
+  readonly canInstall: ReadSignal<boolean>;
+  readonly installed: ReadSignal<boolean>;
+  /** iOS has no `beforeinstallprompt`; it needs a guided flow instead. */
+  readonly iosGuidance: IosGuidance | null;
+  prompt(): Promise<InstallOutcome>;
+  dispose(): void;
+}
+
+export function createInstallController(options: InstallOptions): InstallController {
+  const host = options.host;
+  const minEngagementMs = options.minEngagementMs ?? MIN_ENGAGEMENT_MS;
+  const startedAt = host.now();
+
+  const canInstall = createSignal(false);
+  const installed = createSignal(host.standalone);
+  let deferred: BeforeInstallPromptEventLike | null = null;
+
+  const onBeforeInstallPrompt = (event: unknown): void => {
+    const candidate = event as BeforeInstallPromptEventLike;
+    if (typeof candidate?.prompt !== 'function') return;
+    // Suppress the browser bar; the app decides when to ask.
+    candidate.preventDefault();
+    deferred = candidate;
+    canInstall.set(true);
+  };
+
+  const onInstalled = (): void => {
+    deferred = null;
+    canInstall.set(false);
+    installed.set(true);
+  };
+
+  host.addEventListener('beforeinstallprompt', onBeforeInstallPrompt);
+  host.addEventListener('appinstalled', onInstalled);
+
+  return {
+    canInstall,
+    installed,
+    iosGuidance: iosInstallGuidance(host.userAgent, host.standalone),
+
+    async prompt(): Promise<InstallOutcome> {
+      if (deferred === null) return 'unavailable';
+      if (host.now() - startedAt < minEngagementMs) return 'too-early';
+      await deferred.prompt();
+      const choice = await deferred.userChoice;
+      deferred = null;
+      canInstall.set(false);
+      return choice.outcome;
+    },
+
+    dispose(): void {
+      host.removeEventListener('beforeinstallprompt', onBeforeInstallPrompt);
+      host.removeEventListener('appinstalled', onInstalled);
+    },
+  };
+}
+
+const IOS_UA = /iphone|ipad|ipod/i;
+
+/** Safari never fires `beforeinstallprompt`; the only install path is Share → Add. */
+export function iosInstallGuidance(userAgent: string, standalone: boolean): IosGuidance | null {
+  if (standalone || !IOS_UA.test(userAgent)) return null;
+  return {
+    platform: 'ios',
+    instructionKey: 'pwa.install.ios.instruction',
+    stepKeys: ['pwa.install.ios.step.share', 'pwa.install.ios.step.addToHome'],
+  };
+}

package/src/manifest.ts

@@ -0,0 +1,216 @@
+/**
+ * The web app manifest, generated from `app.config.ts`. 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 gets a light status bar on every launch.
+ */
+
+import type { CapabilityFlags, ResolvedCapabilities } from './capabilities';
+import { isEnabled, resolveCapabilities } from './capabilities';
+import { PwaManifestInvalidError } from './errors';
+
+export type DisplayMode = 'standalone' | 'fullscreen' | 'minimal-ui' | 'browser';
+export type Orientation = 'any' | 'natural' | 'portrait' | 'landscape';
+
+export interface ManifestIcon {
+  readonly src: string;
+  readonly sizes: string;
+  readonly type: string;
+  readonly purpose?: 'any' | 'maskable' | 'monochrome';
+}
+
+export interface ManifestShortcut {
+  readonly name: string;
+  readonly short_name?: string;
+  readonly description?: string;
+  readonly url: string;
+  readonly icons?: readonly ManifestIcon[];
+}
+
+export interface ManifestScreenshot {
+  readonly src: string;
+  readonly sizes: string;
+  readonly type: string;
+  readonly form_factor?: 'narrow' | 'wide';
+  readonly label?: string;
+}
+
+export interface ShareTarget {
+  readonly action: string;
+  readonly method: 'GET' | 'POST';
+  readonly enctype?: string;
+  readonly params: {
+    readonly title?: string;
+    readonly text?: string;
+    readonly url?: string;
+    readonly files?: readonly { readonly name: string; readonly accept: readonly string[] }[];
+  };
+}
+
+export interface FileHandler {
+  readonly action: string;
+  readonly accept: Readonly<Record<string, readonly string[]>>;
+}
+
+export interface ProtocolHandler {
+  readonly protocol: string;
+  readonly url: string;
+}
+
+export interface WebManifest {
+  readonly name: string;
+  readonly short_name: string;
+  readonly description?: string;
+  readonly start_url: string;
+  readonly scope: string;
+  readonly id?: string;
+  readonly display: DisplayMode;
+  readonly display_override?: readonly DisplayMode[];
+  readonly orientation: Orientation;
+  readonly lang: string;
+  readonly dir: 'ltr' | 'rtl' | 'auto';
+  readonly theme_color: string;
+  readonly background_color: string;
+  readonly categories?: readonly string[];
+  readonly icons: readonly ManifestIcon[];
+  readonly shortcuts?: readonly ManifestShortcut[];
+  readonly screenshots?: readonly ManifestScreenshot[];
+  readonly share_target?: ShareTarget;
+  readonly file_handlers?: readonly FileHandler[];
+  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 {
+  readonly name: string;
+  readonly shortName?: string;
+  readonly description?: string;
+  readonly startUrl?: string;
+  readonly scope?: string;
+  readonly id?: string;
+  readonly display?: DisplayMode;
+  readonly orientation?: Orientation;
+  readonly lang?: string;
+  readonly dir?: 'ltr' | 'rtl' | 'auto';
+  readonly tokens: ThemeTokens;
+  readonly categories?: readonly string[];
+  readonly icons?: readonly ManifestIcon[];
+  readonly shortcuts?: readonly ManifestShortcut[];
+  readonly screenshots?: readonly ManifestScreenshot[];
+  readonly shareTarget?: ShareTarget;
+  readonly fileHandlers?: readonly FileHandler[];
+  readonly protocolHandlers?: readonly ProtocolHandler[];
+  readonly capabilities?: CapabilityFlags;
+}
+
+export interface ThemeColorMeta {
+  readonly content: string;
+  readonly media: string;
+}
+
+export interface WebManifestResult {
+  readonly manifest: WebManifest;
+  /** Emit both into `<head>`; the manifest can only carry one. */
+  readonly themeColorMeta: readonly ThemeColorMeta[];
+  readonly capabilities: ResolvedCapabilities;
+}
+
+export function generateWebManifest(config: PwaConfig): WebManifestResult {
+  assertValid(config);
+  const capabilities = resolveCapabilities(config.capabilities);
+  const scope = config.scope ?? '/';
+
+  const optional: MutableManifest = {};
+  if (config.description !== undefined) optional.description = config.description;
+  if (config.id !== undefined) optional.id = config.id;
+  if (config.categories !== undefined) optional.categories = config.categories;
+  if (config.shortcuts !== undefined) optional.shortcuts = config.shortcuts;
+  if (config.screenshots !== undefined) optional.screenshots = config.screenshots;
+
+  // A disabled capability contributes no manifest member at all — not an empty one.
+  if (isEnabled(capabilities, 'shareTarget') && config.shareTarget !== undefined) {
+    optional.share_target = config.shareTarget;
+  }
+  if (isEnabled(capabilities, 'fileHandlers') && config.fileHandlers !== undefined) {
+    optional.file_handlers = config.fileHandlers;
+  }
+  if (isEnabled(capabilities, 'protocolHandlers') && config.protocolHandlers !== undefined) {
+    optional.protocol_handlers = config.protocolHandlers;
+  }
+
+  const manifest: WebManifest = {
+    name: config.name,
+    short_name: config.shortName ?? config.name.slice(0, 12),
+    start_url: config.startUrl ?? scope,
+    scope,
+    display: config.display ?? 'standalone',
+    display_override: ['standalone', 'minimal-ui'],
+    orientation: config.orientation ?? 'any',
+    lang: config.lang ?? 'en',
+    dir: config.dir ?? 'ltr',
+    theme_color: config.tokens.light.themeColor,
+    background_color: config.tokens.light.backgroundColor,
+    icons: config.icons ?? [],
+    ...optional,
+  };
+
+  return {
+    manifest,
+    themeColorMeta: [
+      { content: config.tokens.light.themeColor, media: '(prefers-color-scheme: light)' },
+      { content: config.tokens.dark.themeColor, media: '(prefers-color-scheme: dark)' },
+    ],
+    capabilities,
+  };
+}
+
+type MutableManifest = { -readonly [K in keyof WebManifest]?: WebManifest[K] };
+
+function assertValid(config: PwaConfig): void {
+  if (config.name.trim() === '') {
+    throw new PwaManifestInvalidError(
+      'pwa.name is empty, so the install prompt would have no title',
+      'set pwa.name in app.config.ts',
+    );
+  }
+  const scope = config.scope ?? '/';
+  const startUrl = config.startUrl ?? scope;
+  if (!startUrl.startsWith(scope)) {
+    throw new PwaManifestInvalidError(
+      `pwa.startUrl ${JSON.stringify(startUrl)} is outside pwa.scope ${JSON.stringify(scope)}, ` +
+        'so the installed app would open out of scope',
+      `set pwa.startUrl to a path under ${scope} in app.config.ts`,
+    );
+  }
+  for (const scheme of ['light', 'dark'] as const) {
+    const colors = config.tokens[scheme];
+    if (colors.themeColor.trim() === '' || colors.backgroundColor.trim() === '') {
+      throw new PwaManifestInvalidError(
+        `pwa.tokens.${scheme} is missing themeColor or backgroundColor`,
+        `resolve the ${scheme} theme tokens in app.config.ts — both schemes are required`,
+      );
+    }
+  }
+}
+
+/** Deterministic serialization for the emitted `manifest.webmanifest`. */
+export function serializeWebManifest(manifest: WebManifest): string {
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
+export function renderThemeColorMeta(metas: readonly ThemeColorMeta[]): string {
+  return metas
+    .map((meta) => `<meta name="theme-color" content="${meta.content}" media="${meta.media}">`)
+    .join('');
+}