@broberg/pwa 0.1.1 → 0.2.1

package/README.md

@@ -118,6 +118,39 @@ With **Serwist**/**Workbox**, keep activation user-gated:
 new Serwist({ /* … */, skipWaiting: false, clientsClaim: true });
 ```
 
+## Install setup — manifest, icons, meta (`@broberg/pwa/manifest`, v0.2.0)
+
+The *other* half of a PWA: the `manifest.webmanifest`, the icon set, and the
+apple-touch `<meta>` tags — all as **pure, zero-dep** factories so you stop
+hand-rolling `app/manifest.ts`, a `gen-pwa-icons.cjs` script, and a wall of
+`<meta>` tags. Icons are emitted as self-contained **SVG** (modern manifests +
+apple-touch accept SVG); no rasteriser is bundled.
+
+```ts
+import { defineManifest, serializeManifest, buildIconSet, pwaMetaTags } from "@broberg/pwa/manifest";
+
+// 1. Icons from a monogram (or pass `svg: "<svg…>"` for real artwork).
+const { files, icons } = buildIconSet({ monogram: "AK", background: "#141969", color: "#fff" });
+//    files → [{ path:"/icons/icon-180.svg", content:"<svg…>", … }, …]  (write to public/)
+//    icons → manifest icons[] incl. a padded maskable-512
+
+// 2. Manifest — required members defaulted; `extra` merges last.
+const manifest = defineManifest({ name: "Aalborg Klinik", shortName: "AK", themeColor: "#141969", icons });
+writeFile("public/manifest.webmanifest", serializeManifest(manifest));
+
+// 3. Head tags — typed descriptors you render in Next metadata / a Hono head / plain HTML.
+pwaMetaTags({ themeColor: "#141969", title: "AK" });
+// → [{tag:"link",attrs:{rel:"manifest",href:"/manifest.webmanifest"}}, {tag:"meta",attrs:{name:"theme-color",…}}, …]
+```
+
+- **`buildIconSet`** emits apple-touch (180), 192, 512 + a maskable-512 (10 % safe-zone
+  inset) by default; override `sizes`, `basePath`, `maskable`. `180` goes in the
+  apple-touch `<link>`, not the manifest `icons[]`.
+- **Everything is a pure return value** — you own the filesystem write and the head
+  render. Runs in a build script, a Route Handler, or the browser.
+- Need PNG? Rasterise the returned SVGs with `sharp` on your side — the package
+  stays dependency-free.
+
 ## Gotchas (baked into this package so you don't rediscover them)
 
 - **First install is suppressed.** A worker reaching `installed` with no existing

package/dist/index.cjs

@@ -51,8 +51,13 @@ function createPwaUpdater(options = {}) {
       emit();
     }
   };
+  let hadController = !!container.controller;
   const onControllerChange = () => {
     if (!reloadOnControllerChange || reloading) return;
+    if (!hadController) {
+      hadController = true;
+      return;
+    }
     reloading = true;
     if (typeof location !== "undefined") location.reload();
   };

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/message.ts","../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * The single source of the client↔service-worker \"activate the waiting worker\"\n * message. Both the client controller (`applyUpdate`) and the SW helper\n * (`listenForSkipWaiting`) import it so the contract can never drift.\n */\nexport const SKIP_WAITING = \"SKIP_WAITING\" as const;\n\nexport const SKIP_WAITING_MESSAGE = { type: SKIP_WAITING } as const;\n\nexport type SkipWaitingMessage = typeof SKIP_WAITING_MESSAGE;\n","import { SKIP_WAITING_MESSAGE } from \"./message.js\";\n\nexport { SKIP_WAITING, SKIP_WAITING_MESSAGE } from \"./message.js\";\nexport type { SkipWaitingMessage } from \"./message.js\";\n\nexport interface PwaUpdaterOptions {\n  /** Service-worker script URL to register. Default `/sw.js`. */\n  swUrl?: string;\n  /**\n   * Register `swUrl` ourselves (manual `sw.js` style). Set `false` when the\n   * app already registers the SW (e.g. Serwist's `registerSW` / `@serwist/next`)\n   * — the updater then attaches to the existing registration via\n   * `navigator.serviceWorker.ready` instead of registering again. Default `true`.\n   */\n  register?: boolean;\n  /** How often to poll `registration.update()` (ms). `0` disables. Default 60 min. */\n  pollIntervalMs?: number;\n  /**\n   * Also check for an update when the tab regains focus / becomes visible.\n   * A constantly-focused tab never fires `visibilitychange`, so `focus` is the\n   * one that catches \"user came back to the app\". Default `true`.\n   */\n  updateOnFocus?: boolean;\n  /** Reload the page once the new worker takes control. Default `true`. */\n  reloadOnControllerChange?: boolean;\n  /**\n   * Consumer guard. When `true` the updater is an inert no-op (registers\n   * nothing). Pass your own policy, e.g. `disabled: isNativeCapacitor || isDev`\n   * — the package never hardcodes an environment or a `.native` check.\n   */\n  disabled?: boolean;\n}\n\nexport interface PwaUpdaterState {\n  /** A new service worker is installed and waiting to activate. */\n  updateReady: boolean;\n}\n\nexport interface PwaUpdater {\n  /** Subscribe to state changes. Returns an unsubscribe fn. */\n  subscribe(listener: (state: PwaUpdaterState) => void): () => void;\n  getState(): PwaUpdaterState;\n  /** Tell the waiting worker to activate (posts SKIP_WAITING). No-op if none waits. */\n  applyUpdate(): void;\n  /** Stop polling + remove all listeners. */\n  destroy(): void;\n}\n\nconst DEFAULT_POLL_MS = 60 * 60 * 1000;\n\n/**\n * Framework- and bundler-agnostic controller for the PWA \"new version\n * available\" lifecycle: register (or attach) → detect a waiting worker\n * (suppressing the first install) → let the consumer activate it → reload on\n * takeover, re-checking on interval + focus/visibility.\n *\n * Distilled from the pattern hand-rolled across the fleet (fds, cardmem,\n * pitch-vault). Works with any service worker (Serwist, Workbox, hand-rolled)\n * as long as the SW answers a `SKIP_WAITING` message — see `@broberg/pwa/sw`.\n */\nexport function createPwaUpdater(options: PwaUpdaterOptions = {}): PwaUpdater {\n  const {\n    swUrl = \"/sw.js\",\n    register = true,\n    pollIntervalMs = DEFAULT_POLL_MS,\n    updateOnFocus = true,\n    reloadOnControllerChange = true,\n    disabled = false,\n  } = options;\n\n  const listeners = new Set<(state: PwaUpdaterState) => void>();\n  let updateReady = false;\n  let waitingWorker: ServiceWorker | null = null;\n\n  const getState = (): PwaUpdaterState => ({ updateReady });\n  const emit = (): void => {\n    const state = getState();\n    for (const listener of listeners) listener(state);\n  };\n  const subscribe = (listener: (state: PwaUpdaterState) => void): (() => void) => {\n    listeners.add(listener);\n    return () => listeners.delete(listener);\n  };\n\n  const supported =\n    typeof navigator !== \"undefined\" && \"serviceWorker\" in navigator;\n\n  // Inert no-op: disabled by the consumer, or no service-worker support at all.\n  if (disabled || !supported) {\n    return {\n      subscribe,\n      getState,\n      applyUpdate() {},\n      destroy() {\n        listeners.clear();\n      },\n    };\n  }\n\n  const container = navigator.serviceWorker;\n  let pollId: ReturnType<typeof setInterval> | null = null;\n  let removeFocusListeners: (() => void) | null = null;\n  let reloading = false;\n  let destroyed = false;\n\n  const markReady = (worker: ServiceWorker): void => {\n    waitingWorker = worker;\n    if (!updateReady) {\n      updateReady = true;\n      emit();\n    }\n  };\n\n  const onControllerChange = (): void => {\n    if (!reloadOnControllerChange || reloading) return;\n    reloading = true; // guard against a reload-loop\n    if (typeof location !== \"undefined\") location.reload();\n  };\n  container.addEventListener(\"controllerchange\", onControllerChange);\n\n  const watchInstalling = (registration: ServiceWorkerRegistration): void => {\n    const installing = registration.installing;\n    if (!installing) return;\n    installing.addEventListener(\"statechange\", () => {\n      // A new worker reaching `installed` WHILE a controller already exists is\n      // an update. Reaching `installed` with no controller is the FIRST install\n      // — nothing to update, so we stay quiet.\n      if (installing.state === \"installed\" && container.controller) {\n        markReady(installing);\n      }\n    });\n  };\n\n  const wireFocusChecks = (registration: ServiceWorkerRegistration): void => {\n    if (!updateOnFocus) return;\n    const check = (): void => {\n      registration.update().catch(() => {});\n    };\n    const onFocus = (): void => check();\n    const onVisibility = (): void => {\n      if (typeof document !== \"undefined\" && document.visibilityState === \"visible\") {\n        check();\n      }\n    };\n    if (typeof window !== \"undefined\") window.addEventListener(\"focus\", onFocus);\n    if (typeof document !== \"undefined\") {\n      document.addEventListener(\"visibilitychange\", onVisibility);\n    }\n    removeFocusListeners = () => {\n      if (typeof window !== \"undefined\") window.removeEventListener(\"focus\", onFocus);\n      if (typeof document !== \"undefined\") {\n        document.removeEventListener(\"visibilitychange\", onVisibility);\n      }\n    };\n  };\n\n  // Manual style registers swUrl; serwist/registerSW style attaches to the\n  // registration the app already made via `.ready`.\n  const registrationPromise = register ? container.register(swUrl) : container.ready;\n\n  registrationPromise\n    .then((registration) => {\n      if (destroyed) return;\n      if (registration.waiting) markReady(registration.waiting);\n      registration.addEventListener(\"updatefound\", () => watchInstalling(registration));\n      if (pollIntervalMs > 0) {\n        pollId = setInterval(() => {\n          registration.update().catch(() => {\n            // ignore transient update-check network errors\n          });\n        }, pollIntervalMs);\n      }\n      wireFocusChecks(registration);\n    })\n    .catch(() => {\n      // registration failed — stay inert rather than throw into the app\n    });\n\n  return {\n    subscribe,\n    getState,\n    applyUpdate() {\n      if (waitingWorker) waitingWorker.postMessage(SKIP_WAITING_MESSAGE);\n    },\n    destroy() {\n      destroyed = true;\n      if (pollId !== null) clearInterval(pollId);\n      removeFocusListeners?.();\n      container.removeEventListener(\"controllerchange\", onControllerChange);\n      listeners.clear();\n    },\n  };\n}\n"]}
+{"version":3,"sources":["../src/message.ts","../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * The single source of the client↔service-worker \"activate the waiting worker\"\n * message. Both the client controller (`applyUpdate`) and the SW helper\n * (`listenForSkipWaiting`) import it so the contract can never drift.\n */\nexport const SKIP_WAITING = \"SKIP_WAITING\" as const;\n\nexport const SKIP_WAITING_MESSAGE = { type: SKIP_WAITING } as const;\n\nexport type SkipWaitingMessage = typeof SKIP_WAITING_MESSAGE;\n","import { SKIP_WAITING_MESSAGE } from \"./message.js\";\n\nexport { SKIP_WAITING, SKIP_WAITING_MESSAGE } from \"./message.js\";\nexport type { SkipWaitingMessage } from \"./message.js\";\n\nexport interface PwaUpdaterOptions {\n  /** Service-worker script URL to register. Default `/sw.js`. */\n  swUrl?: string;\n  /**\n   * Register `swUrl` ourselves (manual `sw.js` style). Set `false` when the\n   * app already registers the SW (e.g. Serwist's `registerSW` / `@serwist/next`)\n   * — the updater then attaches to the existing registration via\n   * `navigator.serviceWorker.ready` instead of registering again. Default `true`.\n   */\n  register?: boolean;\n  /** How often to poll `registration.update()` (ms). `0` disables. Default 60 min. */\n  pollIntervalMs?: number;\n  /**\n   * Also check for an update when the tab regains focus / becomes visible.\n   * A constantly-focused tab never fires `visibilitychange`, so `focus` is the\n   * one that catches \"user came back to the app\". Default `true`.\n   */\n  updateOnFocus?: boolean;\n  /** Reload the page once the new worker takes control. Default `true`. */\n  reloadOnControllerChange?: boolean;\n  /**\n   * Consumer guard. When `true` the updater is an inert no-op (registers\n   * nothing). Pass your own policy, e.g. `disabled: isNativeCapacitor || isDev`\n   * — the package never hardcodes an environment or a `.native` check.\n   */\n  disabled?: boolean;\n}\n\nexport interface PwaUpdaterState {\n  /** A new service worker is installed and waiting to activate. */\n  updateReady: boolean;\n}\n\nexport interface PwaUpdater {\n  /** Subscribe to state changes. Returns an unsubscribe fn. */\n  subscribe(listener: (state: PwaUpdaterState) => void): () => void;\n  getState(): PwaUpdaterState;\n  /** Tell the waiting worker to activate (posts SKIP_WAITING). No-op if none waits. */\n  applyUpdate(): void;\n  /** Stop polling + remove all listeners. */\n  destroy(): void;\n}\n\nconst DEFAULT_POLL_MS = 60 * 60 * 1000;\n\n/**\n * Framework- and bundler-agnostic controller for the PWA \"new version\n * available\" lifecycle: register (or attach) → detect a waiting worker\n * (suppressing the first install) → let the consumer activate it → reload on\n * takeover, re-checking on interval + focus/visibility.\n *\n * Distilled from the pattern hand-rolled across the fleet (fds, cardmem,\n * pitch-vault). Works with any service worker (Serwist, Workbox, hand-rolled)\n * as long as the SW answers a `SKIP_WAITING` message — see `@broberg/pwa/sw`.\n */\nexport function createPwaUpdater(options: PwaUpdaterOptions = {}): PwaUpdater {\n  const {\n    swUrl = \"/sw.js\",\n    register = true,\n    pollIntervalMs = DEFAULT_POLL_MS,\n    updateOnFocus = true,\n    reloadOnControllerChange = true,\n    disabled = false,\n  } = options;\n\n  const listeners = new Set<(state: PwaUpdaterState) => void>();\n  let updateReady = false;\n  let waitingWorker: ServiceWorker | null = null;\n\n  const getState = (): PwaUpdaterState => ({ updateReady });\n  const emit = (): void => {\n    const state = getState();\n    for (const listener of listeners) listener(state);\n  };\n  const subscribe = (listener: (state: PwaUpdaterState) => void): (() => void) => {\n    listeners.add(listener);\n    return () => listeners.delete(listener);\n  };\n\n  const supported =\n    typeof navigator !== \"undefined\" && \"serviceWorker\" in navigator;\n\n  // Inert no-op: disabled by the consumer, or no service-worker support at all.\n  if (disabled || !supported) {\n    return {\n      subscribe,\n      getState,\n      applyUpdate() {},\n      destroy() {\n        listeners.clear();\n      },\n    };\n  }\n\n  const container = navigator.serviceWorker;\n  let pollId: ReturnType<typeof setInterval> | null = null;\n  let removeFocusListeners: (() => void) | null = null;\n  let reloading = false;\n  let destroyed = false;\n\n  const markReady = (worker: ServiceWorker): void => {\n    waitingWorker = worker;\n    if (!updateReady) {\n      updateReady = true;\n      emit();\n    }\n  };\n\n  // With `clientsClaim: true` a brand-new worker claims a previously\n  // uncontrolled page and fires `controllerchange` on the FIRST install — that\n  // is not an update, so reloading there would yank a first-time visitor out of\n  // whatever they are doing. Only a `controllerchange` that REPLACES an existing\n  // controller is a real takeover worth reloading for.\n  let hadController = !!container.controller;\n  const onControllerChange = (): void => {\n    if (!reloadOnControllerChange || reloading) return;\n    if (!hadController) {\n      hadController = true; // first claim of an uncontrolled page — not an update\n      return;\n    }\n    reloading = true; // guard against a reload-loop\n    if (typeof location !== \"undefined\") location.reload();\n  };\n  container.addEventListener(\"controllerchange\", onControllerChange);\n\n  const watchInstalling = (registration: ServiceWorkerRegistration): void => {\n    const installing = registration.installing;\n    if (!installing) return;\n    installing.addEventListener(\"statechange\", () => {\n      // A new worker reaching `installed` WHILE a controller already exists is\n      // an update. Reaching `installed` with no controller is the FIRST install\n      // — nothing to update, so we stay quiet.\n      if (installing.state === \"installed\" && container.controller) {\n        markReady(installing);\n      }\n    });\n  };\n\n  const wireFocusChecks = (registration: ServiceWorkerRegistration): void => {\n    if (!updateOnFocus) return;\n    const check = (): void => {\n      registration.update().catch(() => {});\n    };\n    const onFocus = (): void => check();\n    const onVisibility = (): void => {\n      if (typeof document !== \"undefined\" && document.visibilityState === \"visible\") {\n        check();\n      }\n    };\n    if (typeof window !== \"undefined\") window.addEventListener(\"focus\", onFocus);\n    if (typeof document !== \"undefined\") {\n      document.addEventListener(\"visibilitychange\", onVisibility);\n    }\n    removeFocusListeners = () => {\n      if (typeof window !== \"undefined\") window.removeEventListener(\"focus\", onFocus);\n      if (typeof document !== \"undefined\") {\n        document.removeEventListener(\"visibilitychange\", onVisibility);\n      }\n    };\n  };\n\n  // Manual style registers swUrl; serwist/registerSW style attaches to the\n  // registration the app already made via `.ready`.\n  const registrationPromise = register ? container.register(swUrl) : container.ready;\n\n  registrationPromise\n    .then((registration) => {\n      if (destroyed) return;\n      if (registration.waiting) markReady(registration.waiting);\n      registration.addEventListener(\"updatefound\", () => watchInstalling(registration));\n      if (pollIntervalMs > 0) {\n        pollId = setInterval(() => {\n          registration.update().catch(() => {\n            // ignore transient update-check network errors\n          });\n        }, pollIntervalMs);\n      }\n      wireFocusChecks(registration);\n    })\n    .catch(() => {\n      // registration failed — stay inert rather than throw into the app\n    });\n\n  return {\n    subscribe,\n    getState,\n    applyUpdate() {\n      if (waitingWorker) waitingWorker.postMessage(SKIP_WAITING_MESSAGE);\n    },\n    destroy() {\n      destroyed = true;\n      if (pollId !== null) clearInterval(pollId);\n      removeFocusListeners?.();\n      container.removeEventListener(\"controllerchange\", onControllerChange);\n      listeners.clear();\n    },\n  };\n}\n"]}

package/dist/index.js

@@ -48,8 +48,13 @@ function createPwaUpdater(options = {}) {
       emit();
     }
   };
+  let hadController = !!container.controller;
   const onControllerChange = () => {
     if (!reloadOnControllerChange || reloading) return;
+    if (!hadController) {
+      hadController = true;
+      return;
+    }
     reloading = true;
     if (typeof location !== "undefined") location.reload();
   };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { SKIP_WAITING_MESSAGE } from \"./message.js\";\n\nexport { SKIP_WAITING, SKIP_WAITING_MESSAGE } from \"./message.js\";\nexport type { SkipWaitingMessage } from \"./message.js\";\n\nexport interface PwaUpdaterOptions {\n  /** Service-worker script URL to register. Default `/sw.js`. */\n  swUrl?: string;\n  /**\n   * Register `swUrl` ourselves (manual `sw.js` style). Set `false` when the\n   * app already registers the SW (e.g. Serwist's `registerSW` / `@serwist/next`)\n   * — the updater then attaches to the existing registration via\n   * `navigator.serviceWorker.ready` instead of registering again. Default `true`.\n   */\n  register?: boolean;\n  /** How often to poll `registration.update()` (ms). `0` disables. Default 60 min. */\n  pollIntervalMs?: number;\n  /**\n   * Also check for an update when the tab regains focus / becomes visible.\n   * A constantly-focused tab never fires `visibilitychange`, so `focus` is the\n   * one that catches \"user came back to the app\". Default `true`.\n   */\n  updateOnFocus?: boolean;\n  /** Reload the page once the new worker takes control. Default `true`. */\n  reloadOnControllerChange?: boolean;\n  /**\n   * Consumer guard. When `true` the updater is an inert no-op (registers\n   * nothing). Pass your own policy, e.g. `disabled: isNativeCapacitor || isDev`\n   * — the package never hardcodes an environment or a `.native` check.\n   */\n  disabled?: boolean;\n}\n\nexport interface PwaUpdaterState {\n  /** A new service worker is installed and waiting to activate. */\n  updateReady: boolean;\n}\n\nexport interface PwaUpdater {\n  /** Subscribe to state changes. Returns an unsubscribe fn. */\n  subscribe(listener: (state: PwaUpdaterState) => void): () => void;\n  getState(): PwaUpdaterState;\n  /** Tell the waiting worker to activate (posts SKIP_WAITING). No-op if none waits. */\n  applyUpdate(): void;\n  /** Stop polling + remove all listeners. */\n  destroy(): void;\n}\n\nconst DEFAULT_POLL_MS = 60 * 60 * 1000;\n\n/**\n * Framework- and bundler-agnostic controller for the PWA \"new version\n * available\" lifecycle: register (or attach) → detect a waiting worker\n * (suppressing the first install) → let the consumer activate it → reload on\n * takeover, re-checking on interval + focus/visibility.\n *\n * Distilled from the pattern hand-rolled across the fleet (fds, cardmem,\n * pitch-vault). Works with any service worker (Serwist, Workbox, hand-rolled)\n * as long as the SW answers a `SKIP_WAITING` message — see `@broberg/pwa/sw`.\n */\nexport function createPwaUpdater(options: PwaUpdaterOptions = {}): PwaUpdater {\n  const {\n    swUrl = \"/sw.js\",\n    register = true,\n    pollIntervalMs = DEFAULT_POLL_MS,\n    updateOnFocus = true,\n    reloadOnControllerChange = true,\n    disabled = false,\n  } = options;\n\n  const listeners = new Set<(state: PwaUpdaterState) => void>();\n  let updateReady = false;\n  let waitingWorker: ServiceWorker | null = null;\n\n  const getState = (): PwaUpdaterState => ({ updateReady });\n  const emit = (): void => {\n    const state = getState();\n    for (const listener of listeners) listener(state);\n  };\n  const subscribe = (listener: (state: PwaUpdaterState) => void): (() => void) => {\n    listeners.add(listener);\n    return () => listeners.delete(listener);\n  };\n\n  const supported =\n    typeof navigator !== \"undefined\" && \"serviceWorker\" in navigator;\n\n  // Inert no-op: disabled by the consumer, or no service-worker support at all.\n  if (disabled || !supported) {\n    return {\n      subscribe,\n      getState,\n      applyUpdate() {},\n      destroy() {\n        listeners.clear();\n      },\n    };\n  }\n\n  const container = navigator.serviceWorker;\n  let pollId: ReturnType<typeof setInterval> | null = null;\n  let removeFocusListeners: (() => void) | null = null;\n  let reloading = false;\n  let destroyed = false;\n\n  const markReady = (worker: ServiceWorker): void => {\n    waitingWorker = worker;\n    if (!updateReady) {\n      updateReady = true;\n      emit();\n    }\n  };\n\n  const onControllerChange = (): void => {\n    if (!reloadOnControllerChange || reloading) return;\n    reloading = true; // guard against a reload-loop\n    if (typeof location !== \"undefined\") location.reload();\n  };\n  container.addEventListener(\"controllerchange\", onControllerChange);\n\n  const watchInstalling = (registration: ServiceWorkerRegistration): void => {\n    const installing = registration.installing;\n    if (!installing) return;\n    installing.addEventListener(\"statechange\", () => {\n      // A new worker reaching `installed` WHILE a controller already exists is\n      // an update. Reaching `installed` with no controller is the FIRST install\n      // — nothing to update, so we stay quiet.\n      if (installing.state === \"installed\" && container.controller) {\n        markReady(installing);\n      }\n    });\n  };\n\n  const wireFocusChecks = (registration: ServiceWorkerRegistration): void => {\n    if (!updateOnFocus) return;\n    const check = (): void => {\n      registration.update().catch(() => {});\n    };\n    const onFocus = (): void => check();\n    const onVisibility = (): void => {\n      if (typeof document !== \"undefined\" && document.visibilityState === \"visible\") {\n        check();\n      }\n    };\n    if (typeof window !== \"undefined\") window.addEventListener(\"focus\", onFocus);\n    if (typeof document !== \"undefined\") {\n      document.addEventListener(\"visibilitychange\", onVisibility);\n    }\n    removeFocusListeners = () => {\n      if (typeof window !== \"undefined\") window.removeEventListener(\"focus\", onFocus);\n      if (typeof document !== \"undefined\") {\n        document.removeEventListener(\"visibilitychange\", onVisibility);\n      }\n    };\n  };\n\n  // Manual style registers swUrl; serwist/registerSW style attaches to the\n  // registration the app already made via `.ready`.\n  const registrationPromise = register ? container.register(swUrl) : container.ready;\n\n  registrationPromise\n    .then((registration) => {\n      if (destroyed) return;\n      if (registration.waiting) markReady(registration.waiting);\n      registration.addEventListener(\"updatefound\", () => watchInstalling(registration));\n      if (pollIntervalMs > 0) {\n        pollId = setInterval(() => {\n          registration.update().catch(() => {\n            // ignore transient update-check network errors\n          });\n        }, pollIntervalMs);\n      }\n      wireFocusChecks(registration);\n    })\n    .catch(() => {\n      // registration failed — stay inert rather than throw into the app\n    });\n\n  return {\n    subscribe,\n    getState,\n    applyUpdate() {\n      if (waitingWorker) waitingWorker.postMessage(SKIP_WAITING_MESSAGE);\n    },\n    destroy() {\n      destroyed = true;\n      if (pollId !== null) clearInterval(pollId);\n      removeFocusListeners?.();\n      container.removeEventListener(\"controllerchange\", onControllerChange);\n      listeners.clear();\n    },\n  };\n}\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { SKIP_WAITING_MESSAGE } from \"./message.js\";\n\nexport { SKIP_WAITING, SKIP_WAITING_MESSAGE } from \"./message.js\";\nexport type { SkipWaitingMessage } from \"./message.js\";\n\nexport interface PwaUpdaterOptions {\n  /** Service-worker script URL to register. Default `/sw.js`. */\n  swUrl?: string;\n  /**\n   * Register `swUrl` ourselves (manual `sw.js` style). Set `false` when the\n   * app already registers the SW (e.g. Serwist's `registerSW` / `@serwist/next`)\n   * — the updater then attaches to the existing registration via\n   * `navigator.serviceWorker.ready` instead of registering again. Default `true`.\n   */\n  register?: boolean;\n  /** How often to poll `registration.update()` (ms). `0` disables. Default 60 min. */\n  pollIntervalMs?: number;\n  /**\n   * Also check for an update when the tab regains focus / becomes visible.\n   * A constantly-focused tab never fires `visibilitychange`, so `focus` is the\n   * one that catches \"user came back to the app\". Default `true`.\n   */\n  updateOnFocus?: boolean;\n  /** Reload the page once the new worker takes control. Default `true`. */\n  reloadOnControllerChange?: boolean;\n  /**\n   * Consumer guard. When `true` the updater is an inert no-op (registers\n   * nothing). Pass your own policy, e.g. `disabled: isNativeCapacitor || isDev`\n   * — the package never hardcodes an environment or a `.native` check.\n   */\n  disabled?: boolean;\n}\n\nexport interface PwaUpdaterState {\n  /** A new service worker is installed and waiting to activate. */\n  updateReady: boolean;\n}\n\nexport interface PwaUpdater {\n  /** Subscribe to state changes. Returns an unsubscribe fn. */\n  subscribe(listener: (state: PwaUpdaterState) => void): () => void;\n  getState(): PwaUpdaterState;\n  /** Tell the waiting worker to activate (posts SKIP_WAITING). No-op if none waits. */\n  applyUpdate(): void;\n  /** Stop polling + remove all listeners. */\n  destroy(): void;\n}\n\nconst DEFAULT_POLL_MS = 60 * 60 * 1000;\n\n/**\n * Framework- and bundler-agnostic controller for the PWA \"new version\n * available\" lifecycle: register (or attach) → detect a waiting worker\n * (suppressing the first install) → let the consumer activate it → reload on\n * takeover, re-checking on interval + focus/visibility.\n *\n * Distilled from the pattern hand-rolled across the fleet (fds, cardmem,\n * pitch-vault). Works with any service worker (Serwist, Workbox, hand-rolled)\n * as long as the SW answers a `SKIP_WAITING` message — see `@broberg/pwa/sw`.\n */\nexport function createPwaUpdater(options: PwaUpdaterOptions = {}): PwaUpdater {\n  const {\n    swUrl = \"/sw.js\",\n    register = true,\n    pollIntervalMs = DEFAULT_POLL_MS,\n    updateOnFocus = true,\n    reloadOnControllerChange = true,\n    disabled = false,\n  } = options;\n\n  const listeners = new Set<(state: PwaUpdaterState) => void>();\n  let updateReady = false;\n  let waitingWorker: ServiceWorker | null = null;\n\n  const getState = (): PwaUpdaterState => ({ updateReady });\n  const emit = (): void => {\n    const state = getState();\n    for (const listener of listeners) listener(state);\n  };\n  const subscribe = (listener: (state: PwaUpdaterState) => void): (() => void) => {\n    listeners.add(listener);\n    return () => listeners.delete(listener);\n  };\n\n  const supported =\n    typeof navigator !== \"undefined\" && \"serviceWorker\" in navigator;\n\n  // Inert no-op: disabled by the consumer, or no service-worker support at all.\n  if (disabled || !supported) {\n    return {\n      subscribe,\n      getState,\n      applyUpdate() {},\n      destroy() {\n        listeners.clear();\n      },\n    };\n  }\n\n  const container = navigator.serviceWorker;\n  let pollId: ReturnType<typeof setInterval> | null = null;\n  let removeFocusListeners: (() => void) | null = null;\n  let reloading = false;\n  let destroyed = false;\n\n  const markReady = (worker: ServiceWorker): void => {\n    waitingWorker = worker;\n    if (!updateReady) {\n      updateReady = true;\n      emit();\n    }\n  };\n\n  // With `clientsClaim: true` a brand-new worker claims a previously\n  // uncontrolled page and fires `controllerchange` on the FIRST install — that\n  // is not an update, so reloading there would yank a first-time visitor out of\n  // whatever they are doing. Only a `controllerchange` that REPLACES an existing\n  // controller is a real takeover worth reloading for.\n  let hadController = !!container.controller;\n  const onControllerChange = (): void => {\n    if (!reloadOnControllerChange || reloading) return;\n    if (!hadController) {\n      hadController = true; // first claim of an uncontrolled page — not an update\n      return;\n    }\n    reloading = true; // guard against a reload-loop\n    if (typeof location !== \"undefined\") location.reload();\n  };\n  container.addEventListener(\"controllerchange\", onControllerChange);\n\n  const watchInstalling = (registration: ServiceWorkerRegistration): void => {\n    const installing = registration.installing;\n    if (!installing) return;\n    installing.addEventListener(\"statechange\", () => {\n      // A new worker reaching `installed` WHILE a controller already exists is\n      // an update. Reaching `installed` with no controller is the FIRST install\n      // — nothing to update, so we stay quiet.\n      if (installing.state === \"installed\" && container.controller) {\n        markReady(installing);\n      }\n    });\n  };\n\n  const wireFocusChecks = (registration: ServiceWorkerRegistration): void => {\n    if (!updateOnFocus) return;\n    const check = (): void => {\n      registration.update().catch(() => {});\n    };\n    const onFocus = (): void => check();\n    const onVisibility = (): void => {\n      if (typeof document !== \"undefined\" && document.visibilityState === \"visible\") {\n        check();\n      }\n    };\n    if (typeof window !== \"undefined\") window.addEventListener(\"focus\", onFocus);\n    if (typeof document !== \"undefined\") {\n      document.addEventListener(\"visibilitychange\", onVisibility);\n    }\n    removeFocusListeners = () => {\n      if (typeof window !== \"undefined\") window.removeEventListener(\"focus\", onFocus);\n      if (typeof document !== \"undefined\") {\n        document.removeEventListener(\"visibilitychange\", onVisibility);\n      }\n    };\n  };\n\n  // Manual style registers swUrl; serwist/registerSW style attaches to the\n  // registration the app already made via `.ready`.\n  const registrationPromise = register ? container.register(swUrl) : container.ready;\n\n  registrationPromise\n    .then((registration) => {\n      if (destroyed) return;\n      if (registration.waiting) markReady(registration.waiting);\n      registration.addEventListener(\"updatefound\", () => watchInstalling(registration));\n      if (pollIntervalMs > 0) {\n        pollId = setInterval(() => {\n          registration.update().catch(() => {\n            // ignore transient update-check network errors\n          });\n        }, pollIntervalMs);\n      }\n      wireFocusChecks(registration);\n    })\n    .catch(() => {\n      // registration failed — stay inert rather than throw into the app\n    });\n\n  return {\n    subscribe,\n    getState,\n    applyUpdate() {\n      if (waitingWorker) waitingWorker.postMessage(SKIP_WAITING_MESSAGE);\n    },\n    destroy() {\n      destroyed = true;\n      if (pollId !== null) clearInterval(pollId);\n      removeFocusListeners?.();\n      container.removeEventListener(\"controllerchange\", onControllerChange);\n      listeners.clear();\n    },\n  };\n}\n"]}

package/dist/manifest.cjs

@@ -0,0 +1,103 @@
+'use strict';
+
+// src/manifest.ts
+function defineManifest(opts) {
+  if (!opts?.name) throw new Error("defineManifest: `name` is required");
+  const manifest = {
+    name: opts.name,
+    short_name: opts.shortName ?? opts.name,
+    start_url: opts.startUrl ?? "/",
+    scope: opts.scope ?? "/",
+    display: opts.display ?? "standalone",
+    theme_color: opts.themeColor ?? "#ffffff",
+    background_color: opts.backgroundColor ?? "#ffffff",
+    icons: opts.icons ?? []
+  };
+  if (opts.description) manifest.description = opts.description;
+  if (opts.lang) manifest.lang = opts.lang;
+  if (opts.orientation) manifest.orientation = opts.orientation;
+  if (opts.categories) manifest.categories = opts.categories;
+  if (opts.id) manifest.id = opts.id;
+  return { ...manifest, ...opts.extra ?? {} };
+}
+function serializeManifest(manifest, opts = {}) {
+  return JSON.stringify(manifest, null, opts.pretty === false ? void 0 : 2);
+}
+var DEFAULT_SIZES = [180, 192, 512];
+function escapeXml(s) {
+  return s.replace(
+    /[<>&"']/g,
+    (c) => c === "<" ? "&lt;" : c === ">" ? "&gt;" : c === "&" ? "&amp;" : c === '"' ? "&quot;" : "&apos;"
+  );
+}
+function toBase64(s) {
+  const g = globalThis;
+  if (typeof g.Buffer !== "undefined") return g.Buffer.from(s, "utf-8").toString("base64");
+  const bytes = new TextEncoder().encode(s);
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return g.btoa(bin);
+}
+function renderIcon(size, inset, opts) {
+  const bg = opts.background ?? "#111827";
+  const fg = opts.color ?? "#ffffff";
+  const pad = Math.round(size * inset);
+  const inner = size - pad * 2;
+  let art;
+  if (opts.svg) {
+    const href = `data:image/svg+xml;base64,${toBase64(opts.svg)}`;
+    art = `<image x="${pad}" y="${pad}" width="${inner}" height="${inner}" href="${href}" preserveAspectRatio="xMidYMid meet"/>`;
+  } else {
+    const text = escapeXml((opts.monogram ?? "").slice(0, 3).toUpperCase());
+    const fontSize = Math.round(inner * (text.length >= 3 ? 0.42 : 0.52));
+    art = `<text x="50%" y="50%" fill="${fg}" font-family="system-ui, -apple-system, Segoe UI, Roboto, sans-serif" font-weight="700" font-size="${fontSize}" text-anchor="middle" dominant-baseline="central">${text}</text>`;
+  }
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="0 0 ${size} ${size}"><rect width="${size}" height="${size}" fill="${bg}"/>` + art + `</svg>`;
+}
+function buildIconSet(opts) {
+  if (!opts?.svg && !opts?.monogram) {
+    throw new Error("buildIconSet: provide either `svg` or `monogram`");
+  }
+  const base = (opts.basePath ?? "/icons").replace(/\/$/, "");
+  const sizes = opts.sizes ?? DEFAULT_SIZES;
+  const files = [];
+  const icons = [];
+  for (const size of sizes) {
+    const path = `${base}/icon-${size}.svg`;
+    files.push({ path, content: renderIcon(size, 0, opts), type: "image/svg+xml", size, purpose: "any" });
+    if (size !== 180) {
+      icons.push({ src: path, sizes: `${size}x${size}`, type: "image/svg+xml", purpose: "any" });
+    }
+  }
+  if (opts.maskable !== false) {
+    const path = `${base}/icon-maskable-512.svg`;
+    files.push({ path, content: renderIcon(512, 0.1, opts), type: "image/svg+xml", size: 512, purpose: "maskable" });
+    icons.push({ src: path, sizes: "512x512", type: "image/svg+xml", purpose: "maskable" });
+  }
+  return { files, icons };
+}
+function pwaMetaTags(opts = {}) {
+  const tags = [];
+  tags.push({ tag: "link", attrs: { rel: "manifest", href: opts.manifest ?? "/manifest.webmanifest" } });
+  tags.push({ tag: "meta", attrs: { name: "theme-color", content: opts.themeColor ?? "#ffffff" } });
+  tags.push({ tag: "link", attrs: { rel: "apple-touch-icon", href: opts.appleTouchIcon ?? "/icons/icon-180.svg" } });
+  if (opts.capable !== false) {
+    tags.push({ tag: "meta", attrs: { name: "mobile-web-app-capable", content: "yes" } });
+    tags.push({ tag: "meta", attrs: { name: "apple-mobile-web-app-capable", content: "yes" } });
+    tags.push({
+      tag: "meta",
+      attrs: { name: "apple-mobile-web-app-status-bar-style", content: opts.statusBarStyle ?? "default" }
+    });
+  }
+  if (opts.title) {
+    tags.push({ tag: "meta", attrs: { name: "apple-mobile-web-app-title", content: opts.title } });
+  }
+  return tags;
+}
+
+exports.buildIconSet = buildIconSet;
+exports.defineManifest = defineManifest;
+exports.pwaMetaTags = pwaMetaTags;
+exports.serializeManifest = serializeManifest;
+//# sourceMappingURL=manifest.cjs.map
+//# sourceMappingURL=manifest.cjs.map

package/dist/manifest.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/manifest.ts"],"names":[],"mappings":"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","file":"manifest.cjs","sourcesContent":["/**\n * @broberg/pwa/manifest — the PWA *install* half (the update half lives in the\n * root export). A dependency-free manifest/meta factory + an SVG-based icon\n * generator, so a repo stops hand-rolling `app/manifest.ts`, a\n * `gen-pwa-icons.cjs` script, and a pile of apple-touch `<meta>` tags.\n *\n * Everything here is PURE string/object generation — no filesystem, no\n * rasteriser, no runtime deps — so it runs in Node, Bun, edge, a build script,\n * or the browser, and every piece is offline-unit-testable. Icons are emitted\n * as self-contained SVG documents (modern manifests + apple-touch accept SVG);\n * a consumer that specifically needs PNG can rasterise the SVGs with `sharp`\n * on their side — the package stays dep-free.\n */\n\n// ---------------------------------------------------------------------------\n// Manifest\n// ---------------------------------------------------------------------------\n\nexport type Display = \"standalone\" | \"fullscreen\" | \"minimal-ui\" | \"browser\";\n\nexport interface ManifestIcon {\n  src: string;\n  sizes: string;\n  type: string;\n  /** \"any\" | \"maskable\" | \"monochrome\" (space-separated allowed). */\n  purpose?: string;\n}\n\nexport interface WebAppManifest {\n  name: string;\n  short_name: string;\n  start_url: string;\n  scope: string;\n  display: Display;\n  theme_color: string;\n  background_color: string;\n  icons: ManifestIcon[];\n  description?: string;\n  lang?: string;\n  orientation?: string;\n  categories?: string[];\n  id?: string;\n  [key: string]: unknown;\n}\n\nexport interface DefineManifestOptions {\n  /** App name (required). */\n  name: string;\n  /** Home-screen label. Default: `name`. */\n  shortName?: string;\n  /** Default `/`. */\n  startUrl?: string;\n  /** Default `/`. */\n  scope?: string;\n  /** Default `standalone`. */\n  display?: Display;\n  /** Address-bar / task-switcher colour. Default `#ffffff`. */\n  themeColor?: string;\n  /** Splash background. Default `#ffffff`. */\n  backgroundColor?: string;\n  description?: string;\n  lang?: string;\n  orientation?: string;\n  categories?: string[];\n  id?: string;\n  /** Manifest `icons[]` — typically `buildIconSet(...).icons`. */\n  icons?: ManifestIcon[];\n  /** Escape hatch: extra top-level manifest members, merged last. */\n  extra?: Record<string, unknown>;\n}\n\n/**\n * Build a spec-valid Web App Manifest object. Required members are defaulted so\n * a one-liner produces an installable manifest; every default is overridable\n * and `extra` merges last for anything not modelled (shortcuts, screenshots…).\n */\nexport function defineManifest(opts: DefineManifestOptions): WebAppManifest {\n  if (!opts?.name) throw new Error(\"defineManifest: `name` is required\");\n  const manifest: WebAppManifest = {\n    name: opts.name,\n    short_name: opts.shortName ?? opts.name,\n    start_url: opts.startUrl ?? \"/\",\n    scope: opts.scope ?? \"/\",\n    display: opts.display ?? \"standalone\",\n    theme_color: opts.themeColor ?? \"#ffffff\",\n    background_color: opts.backgroundColor ?? \"#ffffff\",\n    icons: opts.icons ?? [],\n  };\n  if (opts.description) manifest.description = opts.description;\n  if (opts.lang) manifest.lang = opts.lang;\n  if (opts.orientation) manifest.orientation = opts.orientation;\n  if (opts.categories) manifest.categories = opts.categories;\n  if (opts.id) manifest.id = opts.id;\n  return { ...manifest, ...(opts.extra ?? {}) };\n}\n\n/** JSON-stringify a manifest for a `manifest.webmanifest` file. */\nexport function serializeManifest(\n  manifest: WebAppManifest,\n  opts: { pretty?: boolean } = {},\n): string {\n  return JSON.stringify(manifest, null, opts.pretty === false ? undefined : 2);\n}\n\n// ---------------------------------------------------------------------------\n// Icon generation (SVG, zero-dep)\n// ---------------------------------------------------------------------------\n\nexport interface GeneratedIcon {\n  /** URL path, e.g. `/icons/icon-192.svg`. */\n  path: string;\n  /** The SVG document. */\n  content: string;\n  type: \"image/svg+xml\";\n  size: number;\n  purpose: \"any\" | \"maskable\";\n}\n\nexport interface IconSet {\n  files: GeneratedIcon[];\n  /** Ready to drop into `defineManifest({ icons })`. */\n  icons: ManifestIcon[];\n}\n\nexport interface IconSetOptions {\n  /**\n   * Source artwork as a full SVG document (`<svg …>…</svg>`). Embedded via a\n   * data-URI `<image>` so it scales cleanly at any size regardless of its\n   * internal coordinate system. Mutually exclusive with `monogram`.\n   */\n  svg?: string;\n  /** Fallback artwork: 1–3 letters rendered centred (e.g. \"AK\"). */\n  monogram?: string;\n  /** Foreground (monogram text) colour. Default `#ffffff`. */\n  color?: string;\n  /** Background fill. Default `#111827`. */\n  background?: string;\n  /** Icon sizes to emit. Default `[180, 192, 512]` (180 = apple-touch). */\n  sizes?: number[];\n  /** Also emit a maskable 512 with a padded safe-zone. Default `true`. */\n  maskable?: boolean;\n  /** URL prefix for every icon `src`. Default `/icons`. */\n  basePath?: string;\n}\n\nconst DEFAULT_SIZES = [180, 192, 512];\n\nfunction escapeXml(s: string): string {\n  return s.replace(/[<>&\"']/g, (c) =>\n    c === \"<\" ? \"&lt;\" : c === \">\" ? \"&gt;\" : c === \"&\" ? \"&amp;\" : c === '\"' ? \"&quot;\" : \"&apos;\",\n  );\n}\n\n/** UTF-8-safe base64 for the data-URI embed (works in Node/Bun/browser). */\nfunction toBase64(s: string): string {\n  // Reached via globalThis so the package needs no @types/node (browser-safe).\n  const g = globalThis as unknown as {\n    Buffer?: { from(input: string, enc: string): { toString(enc: string): string } };\n    btoa?: (data: string) => string;\n  };\n  if (typeof g.Buffer !== \"undefined\") return g.Buffer.from(s, \"utf-8\").toString(\"base64\");\n  const bytes = new TextEncoder().encode(s);\n  let bin = \"\";\n  for (const b of bytes) bin += String.fromCharCode(b);\n  return g.btoa!(bin);\n}\n\n/** Render one square SVG icon document at `size`. `inset` = safe-zone fraction (maskable). */\nfunction renderIcon(size: number, inset: number, opts: IconSetOptions): string {\n  const bg = opts.background ?? \"#111827\";\n  const fg = opts.color ?? \"#ffffff\";\n  const pad = Math.round(size * inset);\n  const inner = size - pad * 2;\n  let art: string;\n  if (opts.svg) {\n    const href = `data:image/svg+xml;base64,${toBase64(opts.svg)}`;\n    art = `<image x=\"${pad}\" y=\"${pad}\" width=\"${inner}\" height=\"${inner}\" href=\"${href}\" preserveAspectRatio=\"xMidYMid meet\"/>`;\n  } else {\n    const text = escapeXml((opts.monogram ?? \"\").slice(0, 3).toUpperCase());\n    // Font sized to the safe inner box; a touch smaller for breathing room.\n    const fontSize = Math.round(inner * (text.length >= 3 ? 0.42 : 0.52));\n    art =\n      `<text x=\"50%\" y=\"50%\" fill=\"${fg}\" font-family=\"system-ui, -apple-system, Segoe UI, Roboto, sans-serif\" ` +\n      `font-weight=\"700\" font-size=\"${fontSize}\" text-anchor=\"middle\" dominant-baseline=\"central\">${text}</text>`;\n  }\n  return (\n    `<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"${size}\" height=\"${size}\" viewBox=\"0 0 ${size} ${size}\">` +\n    `<rect width=\"${size}\" height=\"${size}\" fill=\"${bg}\"/>` +\n    art +\n    `</svg>`\n  );\n}\n\n/**\n * Generate a full icon set (SVG) + the matching manifest `icons[]`. Deterministic,\n * zero-dep. Give it either a source `svg` or a `monogram`; it emits apple-touch\n * (180), 192, 512 by default plus a padded maskable-512.\n */\nexport function buildIconSet(opts: IconSetOptions): IconSet {\n  if (!opts?.svg && !opts?.monogram) {\n    throw new Error(\"buildIconSet: provide either `svg` or `monogram`\");\n  }\n  const base = (opts.basePath ?? \"/icons\").replace(/\\/$/, \"\");\n  const sizes = opts.sizes ?? DEFAULT_SIZES;\n  const files: GeneratedIcon[] = [];\n  const icons: ManifestIcon[] = [];\n\n  for (const size of sizes) {\n    const path = `${base}/icon-${size}.svg`;\n    files.push({ path, content: renderIcon(size, 0, opts), type: \"image/svg+xml\", size, purpose: \"any\" });\n    // apple-touch-icon is referenced via a <link> (see pwaMetaTags), not the\n    // manifest, so only real manifest sizes go into icons[].\n    if (size !== 180) {\n      icons.push({ src: path, sizes: `${size}x${size}`, type: \"image/svg+xml\", purpose: \"any\" });\n    }\n  }\n\n  if (opts.maskable !== false) {\n    // Maskable safe-zone: keep content within the central 80% (10% inset).\n    const path = `${base}/icon-maskable-512.svg`;\n    files.push({ path, content: renderIcon(512, 0.1, opts), type: \"image/svg+xml\", size: 512, purpose: \"maskable\" });\n    icons.push({ src: path, sizes: \"512x512\", type: \"image/svg+xml\", purpose: \"maskable\" });\n  }\n\n  return { files, icons };\n}\n\n// ---------------------------------------------------------------------------\n// Head meta tags\n// ---------------------------------------------------------------------------\n\nexport interface MetaTag {\n  tag: \"meta\" | \"link\";\n  attrs: Record<string, string>;\n}\n\nexport interface MetaTagsOptions {\n  /** `<meta name=\"theme-color\">`. Default `#ffffff`. */\n  themeColor?: string;\n  /** apple-touch-icon href. Default `/icons/icon-180.svg`. */\n  appleTouchIcon?: string;\n  /** Manifest href for the `<link rel=\"manifest\">`. Default `/manifest.webmanifest`. */\n  manifest?: string;\n  /** apple-mobile-web-app-title. Default: omitted. */\n  title?: string;\n  /** apple-mobile-web-app-status-bar-style. Default `default`. */\n  statusBarStyle?: \"default\" | \"black\" | \"black-translucent\";\n  /** Emit the `*-web-app-capable` tags. Default `true`. */\n  capable?: boolean;\n}\n\n/**\n * The head tags a PWA needs beyond the manifest link — returned as typed\n * descriptors so a consumer renders them in Next.js `metadata`, a Hono/JSX\n * head, or plain HTML. No framework assumption.\n */\nexport function pwaMetaTags(opts: MetaTagsOptions = {}): MetaTag[] {\n  const tags: MetaTag[] = [];\n  tags.push({ tag: \"link\", attrs: { rel: \"manifest\", href: opts.manifest ?? \"/manifest.webmanifest\" } });\n  tags.push({ tag: \"meta\", attrs: { name: \"theme-color\", content: opts.themeColor ?? \"#ffffff\" } });\n  tags.push({ tag: \"link\", attrs: { rel: \"apple-touch-icon\", href: opts.appleTouchIcon ?? \"/icons/icon-180.svg\" } });\n  if (opts.capable !== false) {\n    tags.push({ tag: \"meta\", attrs: { name: \"mobile-web-app-capable\", content: \"yes\" } });\n    tags.push({ tag: \"meta\", attrs: { name: \"apple-mobile-web-app-capable\", content: \"yes\" } });\n    tags.push({\n      tag: \"meta\",\n      attrs: { name: \"apple-mobile-web-app-status-bar-style\", content: opts.statusBarStyle ?? \"default\" },\n    });\n  }\n  if (opts.title) {\n    tags.push({ tag: \"meta\", attrs: { name: \"apple-mobile-web-app-title\", content: opts.title } });\n  }\n  return tags;\n}\n"]}

package/dist/manifest.d.cts

@@ -0,0 +1,138 @@
+/**
+ * @broberg/pwa/manifest — the PWA *install* half (the update half lives in the
+ * root export). A dependency-free manifest/meta factory + an SVG-based icon
+ * generator, so a repo stops hand-rolling `app/manifest.ts`, a
+ * `gen-pwa-icons.cjs` script, and a pile of apple-touch `<meta>` tags.
+ *
+ * Everything here is PURE string/object generation — no filesystem, no
+ * rasteriser, no runtime deps — so it runs in Node, Bun, edge, a build script,
+ * or the browser, and every piece is offline-unit-testable. Icons are emitted
+ * as self-contained SVG documents (modern manifests + apple-touch accept SVG);
+ * a consumer that specifically needs PNG can rasterise the SVGs with `sharp`
+ * on their side — the package stays dep-free.
+ */
+type Display = "standalone" | "fullscreen" | "minimal-ui" | "browser";
+interface ManifestIcon {
+    src: string;
+    sizes: string;
+    type: string;
+    /** "any" | "maskable" | "monochrome" (space-separated allowed). */
+    purpose?: string;
+}
+interface WebAppManifest {
+    name: string;
+    short_name: string;
+    start_url: string;
+    scope: string;
+    display: Display;
+    theme_color: string;
+    background_color: string;
+    icons: ManifestIcon[];
+    description?: string;
+    lang?: string;
+    orientation?: string;
+    categories?: string[];
+    id?: string;
+    [key: string]: unknown;
+}
+interface DefineManifestOptions {
+    /** App name (required). */
+    name: string;
+    /** Home-screen label. Default: `name`. */
+    shortName?: string;
+    /** Default `/`. */
+    startUrl?: string;
+    /** Default `/`. */
+    scope?: string;
+    /** Default `standalone`. */
+    display?: Display;
+    /** Address-bar / task-switcher colour. Default `#ffffff`. */
+    themeColor?: string;
+    /** Splash background. Default `#ffffff`. */
+    backgroundColor?: string;
+    description?: string;
+    lang?: string;
+    orientation?: string;
+    categories?: string[];
+    id?: string;
+    /** Manifest `icons[]` — typically `buildIconSet(...).icons`. */
+    icons?: ManifestIcon[];
+    /** Escape hatch: extra top-level manifest members, merged last. */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Build a spec-valid Web App Manifest object. Required members are defaulted so
+ * a one-liner produces an installable manifest; every default is overridable
+ * and `extra` merges last for anything not modelled (shortcuts, screenshots…).
+ */
+declare function defineManifest(opts: DefineManifestOptions): WebAppManifest;
+/** JSON-stringify a manifest for a `manifest.webmanifest` file. */
+declare function serializeManifest(manifest: WebAppManifest, opts?: {
+    pretty?: boolean;
+}): string;
+interface GeneratedIcon {
+    /** URL path, e.g. `/icons/icon-192.svg`. */
+    path: string;
+    /** The SVG document. */
+    content: string;
+    type: "image/svg+xml";
+    size: number;
+    purpose: "any" | "maskable";
+}
+interface IconSet {
+    files: GeneratedIcon[];
+    /** Ready to drop into `defineManifest({ icons })`. */
+    icons: ManifestIcon[];
+}
+interface IconSetOptions {
+    /**
+     * Source artwork as a full SVG document (`<svg …>…</svg>`). Embedded via a
+     * data-URI `<image>` so it scales cleanly at any size regardless of its
+     * internal coordinate system. Mutually exclusive with `monogram`.
+     */
+    svg?: string;
+    /** Fallback artwork: 1–3 letters rendered centred (e.g. "AK"). */
+    monogram?: string;
+    /** Foreground (monogram text) colour. Default `#ffffff`. */
+    color?: string;
+    /** Background fill. Default `#111827`. */
+    background?: string;
+    /** Icon sizes to emit. Default `[180, 192, 512]` (180 = apple-touch). */
+    sizes?: number[];
+    /** Also emit a maskable 512 with a padded safe-zone. Default `true`. */
+    maskable?: boolean;
+    /** URL prefix for every icon `src`. Default `/icons`. */
+    basePath?: string;
+}
+/**
+ * Generate a full icon set (SVG) + the matching manifest `icons[]`. Deterministic,
+ * zero-dep. Give it either a source `svg` or a `monogram`; it emits apple-touch
+ * (180), 192, 512 by default plus a padded maskable-512.
+ */
+declare function buildIconSet(opts: IconSetOptions): IconSet;
+interface MetaTag {
+    tag: "meta" | "link";
+    attrs: Record<string, string>;
+}
+interface MetaTagsOptions {
+    /** `<meta name="theme-color">`. Default `#ffffff`. */
+    themeColor?: string;
+    /** apple-touch-icon href. Default `/icons/icon-180.svg`. */
+    appleTouchIcon?: string;
+    /** Manifest href for the `<link rel="manifest">`. Default `/manifest.webmanifest`. */
+    manifest?: string;
+    /** apple-mobile-web-app-title. Default: omitted. */
+    title?: string;
+    /** apple-mobile-web-app-status-bar-style. Default `default`. */
+    statusBarStyle?: "default" | "black" | "black-translucent";
+    /** Emit the `*-web-app-capable` tags. Default `true`. */
+    capable?: boolean;
+}
+/**
+ * The head tags a PWA needs beyond the manifest link — returned as typed
+ * descriptors so a consumer renders them in Next.js `metadata`, a Hono/JSX
+ * head, or plain HTML. No framework assumption.
+ */
+declare function pwaMetaTags(opts?: MetaTagsOptions): MetaTag[];
+
+export { type DefineManifestOptions, type Display, type GeneratedIcon, type IconSet, type IconSetOptions, type ManifestIcon, type MetaTag, type MetaTagsOptions, type WebAppManifest, buildIconSet, defineManifest, pwaMetaTags, serializeManifest };

package/dist/manifest.d.ts

@@ -0,0 +1,138 @@
+/**
+ * @broberg/pwa/manifest — the PWA *install* half (the update half lives in the
+ * root export). A dependency-free manifest/meta factory + an SVG-based icon
+ * generator, so a repo stops hand-rolling `app/manifest.ts`, a
+ * `gen-pwa-icons.cjs` script, and a pile of apple-touch `<meta>` tags.
+ *
+ * Everything here is PURE string/object generation — no filesystem, no
+ * rasteriser, no runtime deps — so it runs in Node, Bun, edge, a build script,
+ * or the browser, and every piece is offline-unit-testable. Icons are emitted
+ * as self-contained SVG documents (modern manifests + apple-touch accept SVG);
+ * a consumer that specifically needs PNG can rasterise the SVGs with `sharp`
+ * on their side — the package stays dep-free.
+ */
+type Display = "standalone" | "fullscreen" | "minimal-ui" | "browser";
+interface ManifestIcon {
+    src: string;
+    sizes: string;
+    type: string;
+    /** "any" | "maskable" | "monochrome" (space-separated allowed). */
+    purpose?: string;
+}
+interface WebAppManifest {
+    name: string;
+    short_name: string;
+    start_url: string;
+    scope: string;
+    display: Display;
+    theme_color: string;
+    background_color: string;
+    icons: ManifestIcon[];
+    description?: string;
+    lang?: string;
+    orientation?: string;
+    categories?: string[];
+    id?: string;
+    [key: string]: unknown;
+}
+interface DefineManifestOptions {
+    /** App name (required). */
+    name: string;
+    /** Home-screen label. Default: `name`. */
+    shortName?: string;
+    /** Default `/`. */
+    startUrl?: string;
+    /** Default `/`. */
+    scope?: string;
+    /** Default `standalone`. */
+    display?: Display;
+    /** Address-bar / task-switcher colour. Default `#ffffff`. */
+    themeColor?: string;
+    /** Splash background. Default `#ffffff`. */
+    backgroundColor?: string;
+    description?: string;
+    lang?: string;
+    orientation?: string;
+    categories?: string[];
+    id?: string;
+    /** Manifest `icons[]` — typically `buildIconSet(...).icons`. */
+    icons?: ManifestIcon[];
+    /** Escape hatch: extra top-level manifest members, merged last. */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Build a spec-valid Web App Manifest object. Required members are defaulted so
+ * a one-liner produces an installable manifest; every default is overridable
+ * and `extra` merges last for anything not modelled (shortcuts, screenshots…).
+ */
+declare function defineManifest(opts: DefineManifestOptions): WebAppManifest;
+/** JSON-stringify a manifest for a `manifest.webmanifest` file. */
+declare function serializeManifest(manifest: WebAppManifest, opts?: {
+    pretty?: boolean;
+}): string;
+interface GeneratedIcon {
+    /** URL path, e.g. `/icons/icon-192.svg`. */
+    path: string;
+    /** The SVG document. */
+    content: string;
+    type: "image/svg+xml";
+    size: number;
+    purpose: "any" | "maskable";
+}
+interface IconSet {
+    files: GeneratedIcon[];
+    /** Ready to drop into `defineManifest({ icons })`. */
+    icons: ManifestIcon[];
+}
+interface IconSetOptions {
+    /**
+     * Source artwork as a full SVG document (`<svg …>…</svg>`). Embedded via a
+     * data-URI `<image>` so it scales cleanly at any size regardless of its
+     * internal coordinate system. Mutually exclusive with `monogram`.
+     */
+    svg?: string;
+    /** Fallback artwork: 1–3 letters rendered centred (e.g. "AK"). */
+    monogram?: string;
+    /** Foreground (monogram text) colour. Default `#ffffff`. */
+    color?: string;
+    /** Background fill. Default `#111827`. */
+    background?: string;
+    /** Icon sizes to emit. Default `[180, 192, 512]` (180 = apple-touch). */
+    sizes?: number[];
+    /** Also emit a maskable 512 with a padded safe-zone. Default `true`. */
+    maskable?: boolean;
+    /** URL prefix for every icon `src`. Default `/icons`. */
+    basePath?: string;
+}
+/**
+ * Generate a full icon set (SVG) + the matching manifest `icons[]`. Deterministic,
+ * zero-dep. Give it either a source `svg` or a `monogram`; it emits apple-touch
+ * (180), 192, 512 by default plus a padded maskable-512.
+ */
+declare function buildIconSet(opts: IconSetOptions): IconSet;
+interface MetaTag {
+    tag: "meta" | "link";
+    attrs: Record<string, string>;
+}
+interface MetaTagsOptions {
+    /** `<meta name="theme-color">`. Default `#ffffff`. */
+    themeColor?: string;
+    /** apple-touch-icon href. Default `/icons/icon-180.svg`. */
+    appleTouchIcon?: string;
+    /** Manifest href for the `<link rel="manifest">`. Default `/manifest.webmanifest`. */
+    manifest?: string;
+    /** apple-mobile-web-app-title. Default: omitted. */
+    title?: string;
+    /** apple-mobile-web-app-status-bar-style. Default `default`. */
+    statusBarStyle?: "default" | "black" | "black-translucent";
+    /** Emit the `*-web-app-capable` tags. Default `true`. */
+    capable?: boolean;
+}
+/**
+ * The head tags a PWA needs beyond the manifest link — returned as typed
+ * descriptors so a consumer renders them in Next.js `metadata`, a Hono/JSX
+ * head, or plain HTML. No framework assumption.
+ */
+declare function pwaMetaTags(opts?: MetaTagsOptions): MetaTag[];
+
+export { type DefineManifestOptions, type Display, type GeneratedIcon, type IconSet, type IconSetOptions, type ManifestIcon, type MetaTag, type MetaTagsOptions, type WebAppManifest, buildIconSet, defineManifest, pwaMetaTags, serializeManifest };