@cogenta/render 0.1.0

package/dist/pwa/client.js

@@ -0,0 +1,76 @@
+/**
+ * The page side of the PWA: registration, and the way out.
+ *
+ * These functions take the browser objects as arguments instead of reaching for
+ * `navigator` and `caches`. That is what lets them be unit-tested at all — the
+ * package compiles without the DOM library — and it keeps the surface the code
+ * depends on down to the six methods declared here. A caller in the admin (L2)
+ * passes `navigator.serviceWorker` and `caches`; the real objects satisfy these
+ * interfaces structurally, with no cast.
+ */
+export const DEFAULT_SERVICE_WORKER_URL = '/sw.js';
+/**
+ * Registers the worker at the root scope.
+ *
+ * Returns `null` rather than throwing when the browser has no service worker
+ * support, or when registration fails: a site that renders on the server does
+ * not stop working because an offline nicety could not be installed (rule R1
+ * applied to the browser).
+ */
+export async function registerServiceWorker(container, options = {}) {
+    if (container === undefined)
+        return null;
+    try {
+        return await container.register(options.scriptUrl ?? DEFAULT_SERVICE_WORKER_URL, {
+            scope: options.scope ?? '/',
+            updateViaCache: 'none',
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Deletes the caches this site owns. Names outside `cachePrefix` are left
+ * alone: another application may share the origin, and deleting a neighbour's
+ * cache is a worse incident than the stale content this is fixing.
+ */
+export async function purgeSiteCaches(cacheStorage, cachePrefix) {
+    if (cacheStorage === undefined)
+        return [];
+    const names = await cacheStorage.keys();
+    const mine = names.filter((name) => name.startsWith(`${cachePrefix}:`));
+    await Promise.all(mine.map((name) => cacheStorage.delete(name)));
+    return mine;
+}
+/**
+ * The "clear client cache" button of the admin, as a function.
+ *
+ * The order is deliberate. The active worker is asked to purge and unregister
+ * itself first, because it is the only party that can empty its caches while it
+ * is still running. Then the registrations are unregistered from the page side,
+ * which also covers a worker that is broken, hung, or from a build that never
+ * understood the message. Only then are the remaining caches deleted directly —
+ * doing that first would simply let the still-running worker refill them.
+ *
+ * Even after all of this the current page is still controlled by the old
+ * worker, which is why the report insists on a reload.
+ */
+export async function resetPwaClient(environment, cachePrefix) {
+    const container = environment.serviceWorker;
+    const cacheStorage = environment.caches;
+    const supported = container !== undefined && cacheStorage !== undefined;
+    const controlled = container?.controller != null;
+    let registrationsRemoved = 0;
+    if (container !== undefined) {
+        const registrations = await container.getRegistrations();
+        for (const registration of registrations) {
+            registration.active?.postMessage({ type: 'cogenta:unregister' });
+        }
+        const results = await Promise.all(registrations.map((registration) => registration.unregister().catch(() => false)));
+        registrationsRemoved = results.filter((removed) => removed).length;
+    }
+    const cachesDeleted = await purgeSiteCaches(cacheStorage, cachePrefix);
+    return { registrationsRemoved, cachesDeleted, reloadRequired: controlled, supported };
+}
+//# sourceMappingURL=client.js.map

package/dist/pwa/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/pwa/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAwCH,MAAM,CAAC,MAAM,0BAA0B,GAAG,QAAQ,CAAA;AAElD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,SAAmD,EACnD,OAAO,GAA6D,EAAE;IAEtE,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,IAAI,CAAA;IACxC,IAAI,CAAC;QACH,OAAO,MAAM,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,IAAI,0BAA0B,EAAE;YAC/E,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG;YAC3B,cAAc,EAAE,MAAM;SACvB,CAAC,CAAA;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC;AAiBD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,YAA4C,EAC5C,WAAmB;IAEnB,IAAI,YAAY,KAAK,SAAS;QAAE,OAAO,EAAE,CAAA;IACzC,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,IAAI,EAAE,CAAA;IACvC,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,WAAW,GAAG,CAAC,CAAC,CAAA;IACvE,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IAChE,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,WAAiC,EACjC,WAAmB;IAEnB,MAAM,SAAS,GAAG,WAAW,CAAC,aAAa,CAAA;IAC3C,MAAM,YAAY,GAAG,WAAW,CAAC,MAAM,CAAA;IACvC,MAAM,SAAS,GAAG,SAAS,KAAK,SAAS,IAAI,YAAY,KAAK,SAAS,CAAA;IACvE,MAAM,UAAU,GAAG,SAAS,EAAE,UAAU,IAAI,IAAI,CAAA;IAEhD,IAAI,oBAAoB,GAAG,CAAC,CAAA;IAC5B,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,aAAa,GAAG,MAAM,SAAS,CAAC,gBAAgB,EAAE,CAAA;QACxD,KAAK,MAAM,YAAY,IAAI,aAAa,EAAE,CAAC;YACzC,YAAY,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC,CAAA;QAClE,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,aAAa,CAAC,GAAG,CAAC,CAAC,YAAY,EAAE,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,CAClF,CAAA;QACD,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,MAAM,CAAA;IACpE,CAAC;IAED,MAAM,aAAa,GAAG,MAAM,eAAe,CAAC,YAAY,EAAE,WAAW,CAAC,CAAA;IAEtE,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAE,CAAA;AACvF,CAAC"}

package/dist/pwa/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * PWA layer: manifest, service worker, per-resource cache strategies, offline
+ * page, and — the part that has to exist before the first deploy, not after the
+ * first incident — a working way to purge the caches and remove the worker.
+ *
+ * Deliberately dependency-free. Workbox would cover most of this, but it is a
+ * large dependency for code we would still have to understand line by line the
+ * day a visitor reports stale content, and rule R9 asks for zero dependencies
+ * before a small one. What is here is a route table, three caching strategies
+ * and a generational purge; the value Workbox adds over that is a build plugin
+ * we do not want and a precache manifest we deliberately keep tiny.
+ */
+export type { PwaArtefacts, PwaBuildInput } from './build.js';
+export { buildPwaAssets, DEFAULT_OFFLINE_URL } from './build.js';
+export type { ClientCacheStorage, ClientRegisterOptions, ClientRegistration, ClientServiceWorkerContainer, ClientWorker, PwaClientEnvironment, PwaResetReport, } from './client.js';
+export { DEFAULT_SERVICE_WORKER_URL, purgeSiteCaches, registerServiceWorker, resetPwaClient, } from './client.js';
+export type { DisplayMode, InstallabilityProblem, ManifestIcon, ManifestInput, WebAppManifest, } from './manifest.js';
+export { assertInstallable, buildManifest, checkInstallability, MANIFEST_CONTENT_TYPE, renderManifest, } from './manifest.js';
+export type { OfflinePageOptions } from './offline.js';
+export { OFFLINE_PAGE_SCRIPT, renderOfflinePage } from './offline.js';
+export { renderServiceWorker, renderTombstoneServiceWorker, SERVICE_WORKER_HEADERS, } from './service-worker.js';
+export { chooseStrategy, DEFAULT_ROUTES, IMMUTABLE_ASSET_PATTERN } from './strategy.js';
+export type { ServiceWorkerScope } from './sw-runtime.js';
+export { SW_MESSAGE_ACTIVATED, SW_MESSAGE_PURGE, SW_MESSAGE_UNREGISTER, SW_MESSAGE_UNREGISTERED, serviceWorkerMain, tombstoneMain, } from './sw-runtime.js';
+export type { CacheBucket, CacheStrategy, PwaConfig, RequestDescriptor, RouteRule, StrategyDecision, } from './types.js';
+export { CACHE_BUCKETS } from './types.js';
+export type { ParsedCacheName } from './version.js';
+export { bucketCacheName, cacheNameFor, cachesToPurge, computeCacheVersion, DEFAULT_CACHE_PREFIX, parseCacheName, } from './version.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/pwa/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pwa/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC7D,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAChE,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,4BAA4B,EAC5B,YAAY,EACZ,oBAAoB,EACpB,cAAc,GACf,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,0BAA0B,EAC1B,eAAe,EACf,qBAAqB,EACrB,cAAc,GACf,MAAM,aAAa,CAAA;AACpB,YAAY,EACV,WAAW,EACX,qBAAqB,EACrB,YAAY,EACZ,aAAa,EACb,cAAc,GACf,MAAM,eAAe,CAAA;AACtB,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,qBAAqB,EACrB,cAAc,GACf,MAAM,eAAe,CAAA;AACtB,YAAY,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AACtD,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AACrE,OAAO,EACL,mBAAmB,EACnB,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAA;AACvF,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,EACrB,uBAAuB,EACvB,iBAAiB,EACjB,aAAa,GACd,MAAM,iBAAiB,CAAA;AACxB,YAAY,EACV,WAAW,EACX,aAAa,EACb,SAAS,EACT,iBAAiB,EACjB,SAAS,EACT,gBAAgB,GACjB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC1C,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EACL,eAAe,EACf,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,GACf,MAAM,cAAc,CAAA"}

package/dist/pwa/index.js

@@ -0,0 +1,22 @@
+/**
+ * PWA layer: manifest, service worker, per-resource cache strategies, offline
+ * page, and — the part that has to exist before the first deploy, not after the
+ * first incident — a working way to purge the caches and remove the worker.
+ *
+ * Deliberately dependency-free. Workbox would cover most of this, but it is a
+ * large dependency for code we would still have to understand line by line the
+ * day a visitor reports stale content, and rule R9 asks for zero dependencies
+ * before a small one. What is here is a route table, three caching strategies
+ * and a generational purge; the value Workbox adds over that is a build plugin
+ * we do not want and a precache manifest we deliberately keep tiny.
+ */
+export { buildPwaAssets, DEFAULT_OFFLINE_URL } from './build.js';
+export { DEFAULT_SERVICE_WORKER_URL, purgeSiteCaches, registerServiceWorker, resetPwaClient, } from './client.js';
+export { assertInstallable, buildManifest, checkInstallability, MANIFEST_CONTENT_TYPE, renderManifest, } from './manifest.js';
+export { OFFLINE_PAGE_SCRIPT, renderOfflinePage } from './offline.js';
+export { renderServiceWorker, renderTombstoneServiceWorker, SERVICE_WORKER_HEADERS, } from './service-worker.js';
+export { chooseStrategy, DEFAULT_ROUTES, IMMUTABLE_ASSET_PATTERN } from './strategy.js';
+export { SW_MESSAGE_ACTIVATED, SW_MESSAGE_PURGE, SW_MESSAGE_UNREGISTER, SW_MESSAGE_UNREGISTERED, serviceWorkerMain, tombstoneMain, } from './sw-runtime.js';
+export { CACHE_BUCKETS } from './types.js';
+export { bucketCacheName, cacheNameFor, cachesToPurge, computeCacheVersion, DEFAULT_CACHE_PREFIX, parseCacheName, } from './version.js';
+//# sourceMappingURL=index.js.map

package/dist/pwa/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/pwa/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAUhE,OAAO,EACL,0BAA0B,EAC1B,eAAe,EACf,qBAAqB,EACrB,cAAc,GACf,MAAM,aAAa,CAAA;AAQpB,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,qBAAqB,EACrB,cAAc,GACf,MAAM,eAAe,CAAA;AAEtB,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AACrE,OAAO,EACL,mBAAmB,EACnB,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAA;AAEvF,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,EACrB,uBAAuB,EACvB,iBAAiB,EACjB,aAAa,GACd,MAAM,iBAAiB,CAAA;AASxB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE1C,OAAO,EACL,eAAe,EACf,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,GACf,MAAM,cAAc,CAAA"}

package/dist/pwa/manifest.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The web application manifest, and the installability check that goes with it.
+ *
+ * Installability is not a property of the manifest alone — the browser also
+ * requires a registered service worker that answers navigations offline, which
+ * is what the document route and the precached offline page provide. What this
+ * module can check is the half that is data, and it checks it *before* the
+ * build ships rather than leaving the author to discover in a Lighthouse report
+ * that the install button never appeared.
+ */
+export type DisplayMode = 'fullscreen' | 'standalone' | 'minimal-ui' | 'browser';
+export interface ManifestIcon {
+    readonly src: string;
+    /** `"192x192"`, or `"any"` for a vector. */
+    readonly sizes: string;
+    readonly type: string;
+    /**
+     * `any` is drawn as-is; `maskable` fills a platform-defined shape. A single
+     * icon may declare both, but then it must survive being cropped to a circle.
+     */
+    readonly purpose?: 'any' | 'maskable' | 'any maskable';
+}
+export interface WebAppManifest {
+    /** Stable identity of the application. Changing it installs a *new* app. */
+    readonly id: string;
+    readonly name: string;
+    readonly short_name: string;
+    readonly description?: string;
+    readonly start_url: string;
+    readonly scope: string;
+    readonly display: DisplayMode;
+    readonly background_color: string;
+    readonly theme_color: string;
+    readonly lang: string;
+    readonly dir: 'ltr' | 'rtl' | 'auto';
+    readonly icons: readonly ManifestIcon[];
+}
+export interface ManifestInput {
+    readonly name: string;
+    readonly shortName?: string;
+    readonly description?: string;
+    /** Absolute path within the origin. Where the installed app opens. */
+    readonly startUrl?: string;
+    readonly scope?: string;
+    readonly display?: DisplayMode;
+    readonly backgroundColor: string;
+    readonly themeColor: string;
+    readonly lang: string;
+    readonly dir?: 'ltr' | 'rtl' | 'auto';
+    readonly icons: readonly ManifestIcon[];
+}
+export declare function buildManifest(input: ManifestInput): WebAppManifest;
+export interface InstallabilityProblem {
+    readonly field: string;
+    readonly problem: string;
+    readonly fix: string;
+}
+/**
+ * Reports everything that would stop a browser offering installation, in one
+ * pass. Reporting one problem per run is the loop that makes an author give up
+ * on the third iteration.
+ */
+export declare function checkInstallability(manifest: WebAppManifest): InstallabilityProblem[];
+/** Throws a message an author can act on, listing every problem at once. */
+export declare function assertInstallable(manifest: WebAppManifest): void;
+/** Serialised manifest, ready to write to `manifest.webmanifest`. */
+export declare function renderManifest(manifest: WebAppManifest): string;
+export declare const MANIFEST_CONTENT_TYPE = "application/manifest+json";
+//# sourceMappingURL=manifest.d.ts.map

package/dist/pwa/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/pwa/manifest.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,YAAY,GAAG,YAAY,GAAG,SAAS,CAAA;AAEhF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,GAAG,UAAU,GAAG,cAAc,CAAA;CACvD;AAED,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,CAAA;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;CACxC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAA;IAC9B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,CAAA;IACrC,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;CACxC;AAQD,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,cAAc,CAsBlE;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAQD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,cAAc,GAAG,qBAAqB,EAAE,CA4DrF;AAED,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAWhE;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAE/D;AAED,eAAO,MAAM,qBAAqB,8BAA8B,CAAA"}

package/dist/pwa/manifest.js

@@ -0,0 +1,108 @@
+import { CogentaError } from '@cogenta/core';
+/**
+ * Android home-screen labels are truncated around twelve characters, so a long
+ * `short_name` is silently mangled rather than rejected.
+ */
+const SHORT_NAME_MAX = 12;
+export function buildManifest(input) {
+    const scope = input.scope ?? '/';
+    const shortName = input.shortName ?? input.name.slice(0, SHORT_NAME_MAX);
+    const manifest = {
+        // `id` defaults to `start_url` in browsers, which means changing the start
+        // URL orphans the installed app. Pinning it to the scope makes the identity
+        // survive a routing change.
+        id: scope,
+        name: input.name,
+        short_name: shortName,
+        start_url: input.startUrl ?? scope,
+        scope,
+        display: input.display ?? 'standalone',
+        background_color: input.backgroundColor,
+        theme_color: input.themeColor,
+        lang: input.lang,
+        dir: input.dir ?? 'ltr',
+        icons: input.icons,
+    };
+    return input.description === undefined
+        ? manifest
+        : { ...manifest, description: input.description };
+}
+function hasSquareIcon(icons, edge) {
+    return icons.some((icon) => icon.sizes.split(/\s+/).some((size) => size.toLowerCase() === `${edge}x${edge}`));
+}
+/**
+ * Reports everything that would stop a browser offering installation, in one
+ * pass. Reporting one problem per run is the loop that makes an author give up
+ * on the third iteration.
+ */
+export function checkInstallability(manifest) {
+    const problems = [];
+    if (manifest.name.trim() === '') {
+        problems.push({
+            field: 'name',
+            problem: 'the manifest has no name',
+            fix: 'Set the site name: it is the label of the install prompt.',
+        });
+    }
+    if (manifest.short_name.length > SHORT_NAME_MAX) {
+        problems.push({
+            field: 'short_name',
+            problem: `short_name is ${manifest.short_name.length} characters`,
+            fix: `Keep it to ${SHORT_NAME_MAX} characters or fewer, or the home screen truncates it.`,
+        });
+    }
+    if (manifest.display === 'browser') {
+        problems.push({
+            field: 'display',
+            problem: 'display is "browser", which no browser treats as installable',
+            fix: 'Use "standalone", "minimal-ui" or "fullscreen".',
+        });
+    }
+    if (!manifest.start_url.startsWith(manifest.scope)) {
+        problems.push({
+            field: 'start_url',
+            problem: `start_url "${manifest.start_url}" is outside scope "${manifest.scope}"`,
+            fix: 'The start URL must be inside the scope, or the installed app opens outside itself.',
+        });
+    }
+    if (!hasSquareIcon(manifest.icons, 192)) {
+        problems.push({
+            field: 'icons',
+            problem: 'no 192x192 icon',
+            fix: 'Add a 192x192 PNG: it is the minimum Android requires for the install prompt.',
+        });
+    }
+    if (!hasSquareIcon(manifest.icons, 512)) {
+        problems.push({
+            field: 'icons',
+            problem: 'no 512x512 icon',
+            fix: 'Add a 512x512 PNG: it is used for the splash screen.',
+        });
+    }
+    if (!manifest.icons.some((icon) => icon.purpose?.includes('maskable') === true)) {
+        problems.push({
+            field: 'icons',
+            problem: 'no maskable icon',
+            fix: 'Add an icon with purpose "maskable" and 20% safe padding, or Android draws your square icon inside a white circle.',
+        });
+    }
+    return problems;
+}
+/** Throws a message an author can act on, listing every problem at once. */
+export function assertInstallable(manifest) {
+    const problems = checkInstallability(manifest);
+    if (problems.length === 0)
+        return;
+    throw new CogentaError({
+        code: 'CONFIG_INVALID',
+        message: `The web app manifest is not installable (${problems.length} problem${problems.length === 1 ? '' : 's'}):\n${problems.map((p) => `  ${p.field}: ${p.problem} — ${p.fix}`).join('\n')}`,
+        hint: 'A browser offers installation only when the manifest is complete, the display mode is not "browser", and a service worker answers navigations offline.',
+        details: { problems },
+    });
+}
+/** Serialised manifest, ready to write to `manifest.webmanifest`. */
+export function renderManifest(manifest) {
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+export const MANIFEST_CONTENT_TYPE = 'application/manifest+json';
+//# sourceMappingURL=manifest.js.map

package/dist/pwa/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/pwa/manifest.ts"],"names":[],"mappings":"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"}

package/dist/pwa/offline.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The offline page.
+ *
+ * It has one job and one honesty requirement: say that the *network* is
+ * missing, not that the site is broken, and never render an empty shell. A
+ * blank page is indistinguishable from a crashed site, so a visitor reloads,
+ * blames the site, and leaves.
+ *
+ * It is fully self-contained — inline styles, no font, no image, no external
+ * stylesheet — because every external reference is one more thing that must
+ * have been cached for the page to render at the exact moment nothing can be
+ * fetched. It styles itself from the skin custom properties when they happen to
+ * be defined, and falls back to literal values when they are not.
+ */
+export interface OfflinePageOptions {
+    readonly siteName: string;
+    /** BCP 47 tag. Drives the `lang` attribute, so screen readers pronounce it. */
+    readonly lang: string;
+    readonly dir?: 'ltr' | 'rtl' | 'auto';
+    /** Heading. Must state that the visitor is offline. */
+    readonly title?: string;
+    readonly message?: string;
+    readonly retryLabel?: string;
+    /** Shown once the browser reports the connection is back. */
+    readonly restoredLabel?: string;
+    /**
+     * Whether to include the retry script. Disable it on a site whose CSP has no
+     * hash or nonce for inline scripts; the page still renders and still tells
+     * the truth, it just cannot retry by itself.
+     */
+    readonly interactive?: boolean;
+}
+/**
+ * The inline script, exported so a strict CSP can hash it
+ * (`script-src 'sha256-…'`) instead of loosening to `unsafe-inline`.
+ *
+ * It does two things and nothing else: reload on demand, and notice when the
+ * connection returns. `navigator.onLine` is famously optimistic — it reports a
+ * live network adapter, not a reachable site — so it is used only to *offer* a
+ * reload, never to claim the site is back.
+ */
+export declare const OFFLINE_PAGE_SCRIPT: string;
+export declare function renderOfflinePage(options: OfflinePageOptions): string;
+//# sourceMappingURL=offline.d.ts.map

package/dist/pwa/offline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offline.d.ts","sourceRoot":"","sources":["../../src/pwa/offline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAcH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,CAAA;IACrC,uDAAuD;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAC/B;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,QAOpB,CAAA;AAkBZ,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAuCrE"}

package/dist/pwa/offline.js

@@ -0,0 +1,94 @@
+/**
+ * The offline page.
+ *
+ * It has one job and one honesty requirement: say that the *network* is
+ * missing, not that the site is broken, and never render an empty shell. A
+ * blank page is indistinguishable from a crashed site, so a visitor reloads,
+ * blames the site, and leaves.
+ *
+ * It is fully self-contained — inline styles, no font, no image, no external
+ * stylesheet — because every external reference is one more thing that must
+ * have been cached for the page to render at the exact moment nothing can be
+ * fetched. It styles itself from the skin custom properties when they happen to
+ * be defined, and falls back to literal values when they are not.
+ */
+const ESCAPES = {
+    '&': '&',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+};
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (char) => ESCAPES[char] ?? char);
+}
+/**
+ * The inline script, exported so a strict CSP can hash it
+ * (`script-src 'sha256-…'`) instead of loosening to `unsafe-inline`.
+ *
+ * It does two things and nothing else: reload on demand, and notice when the
+ * connection returns. `navigator.onLine` is famously optimistic — it reports a
+ * live network adapter, not a reachable site — so it is used only to *offer* a
+ * reload, never to claim the site is back.
+ */
+export const OFFLINE_PAGE_SCRIPT = [
+    '(function () {',
+    '  var button = document.getElementById("cogenta-offline-retry")',
+    '  var status = document.getElementById("cogenta-offline-status")',
+    '  if (button) button.addEventListener("click", function () { location.reload() })',
+    '  addEventListener("online", function () { if (status) status.hidden = false })',
+    '})()',
+].join('\n');
+const STYLE = [
+    ':root{color-scheme:light dark}',
+    'body{margin:0;min-height:100vh;display:grid;place-items:center;',
+    'padding:var(--cogenta-space-unit,1rem);',
+    'background:var(--cogenta-color-bg,#fff);color:var(--cogenta-color-fg,#111);',
+    'font-family:var(--cogenta-font-sans,system-ui,sans-serif);line-height:1.5}',
+    'main{max-width:34rem;text-align:center}',
+    'h1{font-size:var(--cogenta-font-size-xl,1.75rem);margin:0 0 .5rem}',
+    'p{margin:0 0 1.5rem;color:var(--cogenta-color-muted-fg,#555)}',
+    'button{font:inherit;cursor:pointer;padding:.6rem 1.2rem;',
+    'border:1px solid var(--cogenta-color-border,#ccc);',
+    'border-radius:var(--cogenta-radius-md,.375rem);',
+    'background:var(--cogenta-color-accent,#111);color:var(--cogenta-color-accent-fg,#fff)}',
+    '[hidden]{display:none}',
+].join('');
+export function renderOfflinePage(options) {
+    const lang = escapeHtml(options.lang);
+    const dir = options.dir ?? 'ltr';
+    const siteName = escapeHtml(options.siteName);
+    const title = escapeHtml(options.title ?? 'You are offline');
+    const message = escapeHtml(options.message ??
+        'This page has not been downloaded yet, and there is no connection to fetch it. Everything you have already visited is still available.');
+    const retryLabel = escapeHtml(options.retryLabel ?? 'Try again');
+    const restoredLabel = escapeHtml(options.restoredLabel ?? 'The connection is back.');
+    const interactive = options.interactive ?? true;
+    return [
+        '<!doctype html>',
+        `<html lang="${lang}" dir="${dir}">`,
+        '<head>',
+        '<meta charset="utf-8">',
+        '<meta name="viewport" content="width=device-width, initial-scale=1">',
+        // Not indexable, and never a canonical answer for a real URL.
+        '<meta name="robots" content="noindex">',
+        `<title>${title} · ${siteName}</title>`,
+        `<style>${STYLE}</style>`,
+        '</head>',
+        '<body>',
+        '<main>',
+        `<h1>${title}</h1>`,
+        `<p>${message}</p>`,
+        interactive
+            ? `<p id="cogenta-offline-status" hidden>${restoredLabel}</p><button id="cogenta-offline-retry" type="button">${retryLabel}</button>`
+            : '',
+        '</main>',
+        interactive ? `<script>${OFFLINE_PAGE_SCRIPT}</script>` : '',
+        '</body>',
+        '</html>',
+        '',
+    ]
+        .filter((line) => line !== '')
+        .join('\n');
+}
+//# sourceMappingURL=offline.js.map

package/dist/pwa/offline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"offline.js","sourceRoot":"","sources":["../../src/pwa/offline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,OAAO,GAAqC;IAChD,GAAG,EAAE,OAAO;IACZ,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,QAAQ;IACb,GAAG,EAAE,OAAO;CACb,CAAA;AAED,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAA;AACnE,CAAC;AAqBD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,gBAAgB;IAChB,iEAAiE;IACjE,kEAAkE;IAClE,mFAAmF;IACnF,iFAAiF;IACjF,MAAM;CACP,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAEZ,MAAM,KAAK,GAAG;IACZ,gCAAgC;IAChC,iEAAiE;IACjE,yCAAyC;IACzC,6EAA6E;IAC7E,4EAA4E;IAC5E,yCAAyC;IACzC,oEAAoE;IACpE,+DAA+D;IAC/D,0DAA0D;IAC1D,oDAAoD;IACpD,iDAAiD;IACjD,wFAAwF;IACxF,wBAAwB;CACzB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;AAEV,MAAM,UAAU,iBAAiB,CAAC,OAA2B;IAC3D,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,KAAK,CAAA;IAChC,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC7C,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,IAAI,iBAAiB,CAAC,CAAA;IAC5D,MAAM,OAAO,GAAG,UAAU,CACxB,OAAO,CAAC,OAAO;QACb,wIAAwI,CAC3I,CAAA;IACD,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,CAAC,UAAU,IAAI,WAAW,CAAC,CAAA;IAChE,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,CAAC,aAAa,IAAI,yBAAyB,CAAC,CAAA;IACpF,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,IAAI,CAAA;IAE/C,OAAO;QACL,iBAAiB;QACjB,eAAe,IAAI,UAAU,GAAG,IAAI;QACpC,QAAQ;QACR,wBAAwB;QACxB,sEAAsE;QACtE,8DAA8D;QAC9D,wCAAwC;QACxC,UAAU,KAAK,MAAM,QAAQ,UAAU;QACvC,UAAU,KAAK,UAAU;QACzB,SAAS;QACT,QAAQ;QACR,QAAQ;QACR,OAAO,KAAK,OAAO;QACnB,MAAM,OAAO,MAAM;QACnB,WAAW;YACT,CAAC,CAAC,yCAAyC,aAAa,wDAAwD,UAAU,WAAW;YACrI,CAAC,CAAC,EAAE;QACN,SAAS;QACT,WAAW,CAAC,CAAC,CAAC,WAAW,mBAAmB,WAAW,CAAC,CAAC,CAAC,EAAE;QAC5D,SAAS;QACT,SAAS;QACT,EAAE;KACH;SACE,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC;SAC7B,IAAI,CAAC,IAAI,CAAC,CAAA;AACf,CAAC"}

package/dist/pwa/service-worker.d.ts

@@ -0,0 +1,71 @@
+import type { PwaConfig } from './types.js';
+/**
+ * Generation of the service worker script.
+ *
+ * ## The update strategy, stated in full
+ *
+ * `skipWaiting()` and `clients.claim()` are two calls; the strategy is the four
+ * properties that make those two calls safe.
+ *
+ * **1. Every generation owns its caches.** Cache names embed a version derived
+ * from the offline page, the precache list and the route table
+ * (`computeCacheVersion`). A new deploy therefore writes into new caches and
+ * cannot mix generations, which is what makes immediate activation safe: there
+ * is no window in which half the entries are old.
+ *
+ * **2. Activation purges the previous generations.** `cachesToPurge` returns
+ * every cache of ours whose version is not the current one, and activation
+ * deletes them before claiming clients. Storage does not accumulate one
+ * generation per deploy, and — the part that matters — yesterday's HTML is
+ * *gone*, not merely lower priority.
+ *
+ * **3. Documents are never served from cache while the network works.** Even a
+ * worker that somehow survived a bad deploy cannot pin an old page: the
+ * document strategy is network-first, so the cache answers only when the
+ * network has already failed. This is the property that keeps a mistake
+ * recoverable by deploying a fix, rather than requiring every visitor to clear
+ * their site data.
+ *
+ * **4. There is an exit.** The worker answers a message by purging every cache
+ * it owns and calling `registration.unregister()` — that is the admin's "clear
+ * client cache" button. For clients we can no longer run code on,
+ * `renderTombstoneServiceWorker` produces a worker that unregisters itself on
+ * activation; deploying it at the same URL removes the PWA from every browser
+ * that re-fetches the script, which browsers do at least daily.
+ *
+ * ## What is deliberately *not* done
+ *
+ * The worker does not reload open pages when it activates. A forced reload
+ * destroys scroll position, half-typed comments and video playback, and it
+ * turns one bad deploy into a reload loop. It posts `cogenta:activated`
+ * instead, and the page decides — the registration helper in `client.ts` turns
+ * that into an "a new version is available" prompt.
+ *
+ * The worker is a *classic* script, not an ES module: module workers are still
+ * unevenly supported, and there is nothing to import — the script is
+ * self-contained by construction.
+ */
+/**
+ * Headers the server must send for the service worker script.
+ *
+ * This is not decoration. A worker script cached by the HTTP cache for a year
+ * is the canonical unkillable zombie: the browser's daily update check reads
+ * the stale copy from disk, sees no change, and keeps the old worker alive —
+ * including after the tombstone has been deployed. `no-cache` (revalidate, do
+ * not blindly reuse) is the minimum, and the scope header lets the script live
+ * anywhere while controlling the whole origin.
+ */
+export declare const SERVICE_WORKER_HEADERS: Readonly<Record<string, string>>;
+export declare function renderServiceWorker(config: PwaConfig): string;
+/**
+ * The kill switch, as a deployable artefact.
+ *
+ * Deploy this at the URL the real worker was served from. It caches nothing,
+ * intercepts nothing, deletes every cache under `cachePrefix` and unregisters
+ * itself. Keep it deployed for at least one update cycle — twenty-four hours
+ * covers browsers that only check the script once a day — before removing the
+ * route entirely, because a 404 on the worker URL also unregisters the worker
+ * but tells the caches nothing.
+ */
+export declare function renderTombstoneServiceWorker(cachePrefix: string): string;
+//# sourceMappingURL=service-worker.d.ts.map

package/dist/pwa/service-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-worker.d.ts","sourceRoot":"","sources":["../../src/pwa/service-worker.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAG3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAInE,CAAA;AA0BD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAiB7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CASxE"}