@braidlabs/sw 0.1.1

package/README.md

@@ -0,0 +1,160 @@
+# @braidlabs/sw
+
+Skew-aware asset serving for composed pages.
+
+The classic micro-frontend white screen: a user has the page open, a deploy lands, they click
+something that lazy-loads `main.abc123.js` — and it is gone, because the new build wrote
+`main.def456.js`. Nothing on the page can recover. The request comes from the module loader, the
+response is a 404, and the route dies.
+
+A service worker is the **only** layer that can answer that request from a copy it kept.
+
+Braid makes this materially cleaner than it is for a monolith. Every fragment's assets live under
+`/__braid/frag/:id/*`, so each fragment gets **its own cache partition keyed by its own build**.
+Fragment A at build 5 and fragment B at build 12 coexist, with no shared cache generation for one
+deploy to invalidate on the other's behalf. A monolith's worker has one bucket and one answer.
+
+---
+
+## Two shapes
+
+Both ship, because "the app already has a service worker" is not a safe assumption — least of all
+for internal enterprise apps.
+
+**A handler, for a worker you already own.** Braid never takes your `fetch` event:
+
+```js
+// your sw.js
+import { braidFetchHandler } from '@braidlabs/sw';
+const braid = braidFetchHandler({ buildId: BUILD_ID });
+
+self.addEventListener('fetch', (event) => {
+  const handled = braid(event.request); // null for anything not ours
+  if (handled) event.respondWith(handled);
+});
+```
+
+**A complete worker, for shells with none.** Same handler, already wired:
+
+```js
+// sw.js
+import { setupBraidWorker } from '@braidlabs/sw';
+setupBraidWorker({ buildId: BUILD_ID, precache: ['billing', 'notifications'] });
+```
+
+## Let the gateway serve it
+
+```ts
+createGateway({ registry, serviceWorker: true });                  // scope '/'
+createGateway({ registry, serviceWorker: { scope: '/apps/' } });   // path-mounted deployments
+```
+
+```ts
+import { registerBraidServiceWorker } from '@braidlabs/core';
+await registerBraidServiceWorker({ buildId: BUILD_ID });
+```
+
+**A worker's scope is capped by the path it is served from.** A script at `/__braid/sw.js` defaults
+to controlling `/__braid/` — enough for fragment assets, useless for the shell's own, which is the
+chunk-failure case that matters most. Widening it needs `Service-Worker-Allowed` on the script
+response, and the gateway is the one component already in front of the origin that can send it
+without touching infrastructure config.
+
+Claiming `/` sounds broad and costs nothing: scope precedence is longest-match, so a worker
+registered at `/legacy/` still controls `/legacy/` whatever Braid claims. The root is a fallback,
+not an exclusion — and the handler returns `null` outside the namespace anyway.
+
+The generated script is **byte-stable across registry publishes**. Baking the snapshot id into it
+would make every publish a worker update with its own waiting and activation lifecycle;
+configuration churn must not become worker churn.
+
+## What it will and will not do
+
+| | |
+| --- | --- |
+| Serves a cached chunk when the origin 404s it | ✅ the deploy case |
+| Serves from cache when the network is gone | ✅ offline |
+| Answers a 500 from cache | ❌ that is an outage, and hiding it makes it someone else's mystery |
+| Answers a POST | ❌ a cache cannot, and pretending turns a failed write into a stale success |
+| Touches anything outside `/__braid/` | ❌ never |
+| Caches fragment **documents** | ❌ composed markup's freshness is the gateway's business |
+
+## Offline composition
+
+Opt-in, and the piece with the most leverage: the worker runs **the gateway's own piercing**.
+
+```js
+setupBraidWorker({
+  buildId: BUILD_ID,
+  offline: { snapshotUrl: '/__braid/registry/pinned.json' },
+});
+```
+
+The gateway core is runtime-neutral — no `node:` imports in the gateway, the registry, or the
+rewriter — and a service worker is a web-standard runtime. So the worker holds the shell and the
+fragment documents and interleaves them with the same `pierceShellHtml` the server runs. A second
+implementation of piercing would be a second set of piercing bugs, found offline.
+
+**It holds the parts, not the finished page.** Caching composed HTML would be simpler and much less
+useful: the composed page is the cross-product of shell, fragments, and route. Holding the parts
+means a route visited once composes offline afterwards, a fragment updates its own part, and a
+fragment with nothing cached degrades to a placeholder instead of failing the page.
+
+The shell is re-fetched with `sec-fetch-dest: empty`, which is how the gateway already distinguishes
+a soft-navigation fetch from a document request — the same distinction every pierced response
+declares in its `Vary` header, used from the other side.
+
+Two things it will not do: compose while the network is reachable (the gateway is authoritative),
+and cache a composed response (a page pierced against a registry that has since changed is exactly
+the stale artifact this package exists to avoid). Composed pages carry
+`x-braid-composed: offline` so a shell can say so rather than look merely slow.
+
+## The worker is itself a skew vector
+
+It is a long-lived deployment artifact that updates on its own schedule — a version boundary added
+to a system whose purpose is managing version boundaries. So it gets the same discipline: it knows
+its build and the snapshot it serves, and says so when they disagree with the page.
+
+```ts
+await registerBraidServiceWorker({
+  buildId: BUILD_ID,
+  onVersion: (report) => telemetry.record(report),
+});
+```
+
+`claimClients` is off by default for the same reason. Claiming swaps the worker underneath a page
+that is already running, so a page mid-session starts being served by a build it did not load
+against. Waiting for the next navigation is the boring, correct behaviour.
+
+## Reports that survive the tab closing
+
+```js
+setupBraidWorker({
+  buildId: BUILD_ID,
+  reports: { endpoint: '/__telemetry', driver: indexedDbRecordDriver({ database: 'braid-sw' }) },
+});
+```
+
+The worker knows things nobody else can see — that a chunk was served from cache after the origin
+404'd it, that its build disagrees with the page's. Handed to `onReport` those facts are
+fire-and-forget, and the ones that go missing are disproportionately the interesting ones: a user who
+hits a broken deploy is a user who closes the tab, and a `fetch` started during teardown loses that
+race.
+
+Queued reports are flushed on a Background Sync event — the browser wakes the worker when it judges
+the network is back, with no page open and nothing racing teardown. Background Sync is Chromium-only,
+so every activation also flushes opportunistically; a browser without it gets that path and nothing
+else.
+
+The queue is `@braidlabs/data`'s outbox rather than a second implementation: one record per entry, so
+appending never reads the queue first and two contexts cannot lose each other's writes. A refused
+batch stays queued in full — partial credit would need the endpoint to say which records it took,
+and no telemetry endpoint does.
+
+## Not a data cache
+
+The Cache API stores `Request → Response`. The data layer needs per-entity keys, versioned
+envelopes, and migrate-on-read; the Cache API offers none of the three, and storing enveloped
+entities as opaque response bodies would defeat the projection the whole design rests on.
+
+**Cache API for assets and stubs. IndexedDB (`@braidlabs/data`) for entities.**

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@braidlabs/sw",
+  "version": "0.1.1",
+  "description": "Braid service worker — skew-aware asset serving for composed pages: each fragment gets its own build-keyed cache partition, so a page already open keeps getting the chunks it was built against after a deploy lands. Ships as a handler to compose into an existing worker, and as a complete worker.",
+  "keywords": [
+    "micro-frontends",
+    "service-worker",
+    "version-skew",
+    "cache",
+    "offline"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/braidjs/braid.git",
+    "directory": "libs/braid-sw"
+  },
+  "homepage": "https://github.com/braidjs/braid#readme",
+  "bugs": {
+    "url": "https://github.com/braidjs/braid/issues"
+  },
+  "module": "./src/index.js"
+}

package/src/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `@braidlabs/sw` — skew-aware asset serving for composed pages.
+ *
+ * The classic micro-frontend white screen is a deploy landing under an open page: a lazy chunk is
+ * requested, the build that wrote it is gone, and nothing on the page can recover. A service worker
+ * is the only layer that can answer that request from a copy it kept — and because every fragment's
+ * assets live under `/__braid/frag/:id/*`, each fragment gets its own build-keyed cache partition
+ * rather than a monolith's single bucket with a single answer.
+ *
+ * Ships in both shapes on purpose: a handler to compose into a worker you already own, and a
+ * complete worker for the (common) case where you have none.
+ */
+export { braidFetchHandler, pruneFragmentCaches } from './lib/asset-handler.js';
+export type { BraidFetchHandlerOptions, AssetOutcome, AssetReport } from './lib/asset-handler.js';
+export { setupBraidWorker } from './lib/worker.js';
+export type { BraidWorkerOptions } from './lib/worker.js';
+export { braidNavigationHandler } from './lib/compose.js';
+export type { OfflineCompositionOptions } from './lib/compose.js';
+export { precacheRealmStubs } from './lib/precache.js';
+export type { PrecacheOptions, PrecacheResult } from './lib/precache.js';
+export { createReportQueue, BRAID_REPORT_SYNC_TAG } from './lib/reports.js';
+export type { ReportQueue, ReportQueueOptions, BraidReport, FlushOutcome } from './lib/reports.js';
+export { diagnoseSkew, BRAID_BUILD_HEADER, BRAID_SNAPSHOT_HEADER } from './lib/skew-report.js';
+export type { SkewDiagnosis, SkewSeverity, WorkerVersion, PageVersion } from './lib/skew-report.js';

package/src/index.js

@@ -0,0 +1,19 @@
+/**
+ * `@braidlabs/sw` — skew-aware asset serving for composed pages.
+ *
+ * The classic micro-frontend white screen is a deploy landing under an open page: a lazy chunk is
+ * requested, the build that wrote it is gone, and nothing on the page can recover. A service worker
+ * is the only layer that can answer that request from a copy it kept — and because every fragment's
+ * assets live under `/__braid/frag/:id/*`, each fragment gets its own build-keyed cache partition
+ * rather than a monolith's single bucket with a single answer.
+ *
+ * Ships in both shapes on purpose: a handler to compose into a worker you already own, and a
+ * complete worker for the (common) case where you have none.
+ */
+export { braidFetchHandler, pruneFragmentCaches } from './lib/asset-handler.js';
+export { setupBraidWorker } from './lib/worker.js';
+export { braidNavigationHandler } from './lib/compose.js';
+export { precacheRealmStubs } from './lib/precache.js';
+export { createReportQueue, BRAID_REPORT_SYNC_TAG } from './lib/reports.js';
+export { diagnoseSkew, BRAID_BUILD_HEADER, BRAID_SNAPSHOT_HEADER } from './lib/skew-report.js';
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/braid-sw/src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAGhF,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAG1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAGvD,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAG5E,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC"}

package/src/lib/asset-handler.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Skew-aware asset serving: the one layer that can keep an open page working after a deploy.
+ *
+ * The failure this exists for is the classic micro-frontend white screen. A user has the page open,
+ * a deploy lands, they click something that lazy-loads `main.abc123.js` — and it is gone from the
+ * origin, because the new build wrote `main.def456.js` instead. Nothing on the page can recover:
+ * the request is made by the module loader, the response is a 404, and the route dies.
+ *
+ * A service worker can, because it saw that chunk go past on the way in and kept a copy.
+ *
+ * **Braid makes this materially cleaner than it is for a monolith.** Every fragment's assets live
+ * under `/__braid/frag/:id/*`, so each fragment gets its own cache partition keyed by its own build.
+ * Fragment A at build 5 and fragment B at build 12 coexist with no shared cache generation to
+ * invalidate — a monolith's worker has one bucket and one answer for the whole page.
+ *
+ * Scope discipline: this handler answers for the Braid namespace and returns `null` for everything
+ * else. A shell composing it into its own worker keeps ownership of its own routes, and a shell
+ * using the prebuilt worker gets a worker that does nothing surprising to the rest of its origin.
+ */
+/** How a request was answered — the input to the diagnostics a silent worker would deny you. */
+export type AssetOutcome = 'network' | 'cache'
+/** Served from cache *after* the network said the asset is gone — the deploy-skew save. */
+ | 'cache-after-404' | 'offline';
+export interface AssetReport {
+    fragmentId: string;
+    url: string;
+    outcome: AssetOutcome;
+    /** The cache partition that answered, or would have. */
+    partition: string;
+}
+export interface BraidFetchHandlerOptions {
+    /**
+     * The build this worker was shipped as.
+     *
+     * A worker is itself a long-lived deployment artifact that updates on its own schedule, so it is
+     * a skew vector in a system whose purpose is managing them. Naming its build is what lets a
+     * disagreement be reported instead of silently serving yesterday's assets to today's document.
+     */
+    buildId?: string;
+    /** Cache name prefix. One cache per fragment, so eviction is per fragment too. */
+    cachePrefix?: string;
+    /** Called for every namespace request this handler answers. Wire it to your telemetry. */
+    onReport?: (report: AssetReport) => void;
+    /** Injectable for tests. Defaults to the worker's own `caches`. */
+    caches?: CacheStorage;
+    /** Injectable for tests. Defaults to the worker's own `fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * Builds a fetch handler for the Braid namespace.
+ *
+ * ```js
+ * const braid = braidFetchHandler();
+ * self.addEventListener('fetch', (event) => {
+ *   const handled = braid(event.request);   // null for anything not ours
+ *   if (handled) event.respondWith(handled);
+ * });
+ * ```
+ */
+export declare function braidFetchHandler(options?: BraidFetchHandlerOptions): (request: Request) => Promise<Response> | null;
+/**
+ * Removes cache partitions for fragments that are no longer registered.
+ *
+ * Per fragment rather than per build: a fragment's own chunks are content-hashed, so its partition
+ * grows by a bounded amount per deploy and shrinking it on activate would throw away exactly the
+ * old chunks this handler exists to keep. A fragment that has left the registry, on the other hand,
+ * is never coming back for them.
+ */
+export declare function pruneFragmentCaches(keep: readonly string[], options?: {
+    cachePrefix?: string;
+    caches?: CacheStorage;
+}): Promise<string[]>;

package/src/lib/asset-handler.js

@@ -0,0 +1,92 @@
+import { parseBraidPathname } from '@braidlabs/gateway';
+const DEFAULT_CACHE_PREFIX = 'braid-frag';
+/**
+ * Builds a fetch handler for the Braid namespace.
+ *
+ * ```js
+ * const braid = braidFetchHandler();
+ * self.addEventListener('fetch', (event) => {
+ *   const handled = braid(event.request);   // null for anything not ours
+ *   if (handled) event.respondWith(handled);
+ * });
+ * ```
+ */
+export function braidFetchHandler(options = {}) {
+    const cachePrefix = options.cachePrefix ?? DEFAULT_CACHE_PREFIX;
+    const cacheStorage = options.caches ?? globalThis.caches;
+    const networkFetch = options.fetch ?? globalThis.fetch;
+    return (request) => {
+        // GET only. A cache cannot answer a POST, and pretending otherwise is how a worker turns a
+        // failed write into a stale success.
+        if (request.method !== 'GET')
+            return null;
+        const url = new URL(request.url);
+        const route = parseBraidPathname(url.pathname);
+        // Assets and realm stubs only. A fragment *document* is composed markup whose freshness is the
+        // gateway's business — caching one here would serve a page built against a registry that has
+        // since changed, which is the failure this package exists to prevent rather than cause.
+        if (!route || (route.kind !== 'fragment' && route.kind !== 'realm'))
+            return null;
+        return serve(request, url, route.fragmentId);
+    };
+    async function serve(request, url, fragmentId) {
+        const partition = `${cachePrefix}:${fragmentId}`;
+        const report = (outcome) => options.onReport?.({ fragmentId, url: url.href, outcome, partition });
+        const cache = await cacheStorage?.open(partition);
+        try {
+            const response = await networkFetch(request);
+            // 404 is the deploy case, and the only status worth reaching into the cache for. A 500 is the
+            // server having a bad moment about an asset that still exists; answering it from cache would
+            // paper over an outage and make it someone else's mystery.
+            if (response.status === 404) {
+                const cached = await cache?.match(request);
+                if (cached) {
+                    report('cache-after-404');
+                    return cached;
+                }
+            }
+            // Only successful, non-partial responses are worth keeping. A cached 206 answers a range
+            // request that was never asked for.
+            if (response.ok && response.status === 200 && cache) {
+                // Cached without awaiting: the page is waiting on this response, and the copy is an
+                // optimization for a future load rather than a precondition for this one.
+                void cache.put(request, response.clone()).catch(() => undefined);
+            }
+            report('network');
+            return response;
+        }
+        catch (error) {
+            // The network is gone, not merely unhappy. This is the offline path.
+            const cached = await cache?.match(request);
+            if (cached) {
+                report('offline');
+                return cached;
+            }
+            throw error;
+        }
+    }
+}
+/**
+ * Removes cache partitions for fragments that are no longer registered.
+ *
+ * Per fragment rather than per build: a fragment's own chunks are content-hashed, so its partition
+ * grows by a bounded amount per deploy and shrinking it on activate would throw away exactly the
+ * old chunks this handler exists to keep. A fragment that has left the registry, on the other hand,
+ * is never coming back for them.
+ */
+export async function pruneFragmentCaches(keep, options = {}) {
+    const cachePrefix = options.cachePrefix ?? DEFAULT_CACHE_PREFIX;
+    const cacheStorage = options.caches ?? globalThis.caches;
+    if (!cacheStorage)
+        return [];
+    const kept = new Set(keep.map((id) => `${cachePrefix}:${id}`));
+    const removed = [];
+    for (const name of await cacheStorage.keys()) {
+        if (!name.startsWith(`${cachePrefix}:`) || kept.has(name))
+            continue;
+        await cacheStorage.delete(name);
+        removed.push(name);
+    }
+    return removed;
+}
+//# sourceMappingURL=asset-handler.js.map

package/src/lib/asset-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-handler.js","sourceRoot":"","sources":["../../../../../libs/braid-sw/src/lib/asset-handler.ts"],"names":[],"mappings":"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"}

package/src/lib/compose.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Offline composition: the gateway's own piercing, run inside the worker.
+ *
+ * This falls out of decisions already made rather than needing new machinery. The gateway core is
+ * runtime-neutral — no `node:` imports in the gateway, the registry, or the rewriter — and a service
+ * worker is a web-standard runtime. So the worker can hold the shell and the fragment documents and
+ * interleave them with the **same `pierceShellHtml` the server runs**, which matters more than the
+ * code reuse: a second implementation would be a second set of piercing bugs, discovered offline.
+ *
+ * **Why hold the pieces rather than the composed page.** Caching the finished HTML would be simpler
+ * and much less useful: the composed page is the cross-product of shell, fragments, and route, so a
+ * cache of finished pages only ever answers for routes the user already visited with the fragment
+ * versions they had. Holding the parts means a route visited once composes offline afterwards, and
+ * a fragment that updated on its own schedule updates its part alone.
+ *
+ * Two things this deliberately does not do. It never composes when the network is reachable — the
+ * gateway is authoritative and its answer is always preferred — and it never caches a *composed*
+ * response, because a page pierced against a registry that has since changed is precisely the stale
+ * artifact the rest of this package exists to avoid.
+ */
+export interface OfflineCompositionOptions {
+    /**
+     * Where the pinned registry snapshot is served from.
+     *
+     * Content-addressed and immutable, so it is cacheable under its id forever with no revalidation —
+     * which is what makes an offline compose possible at all: piercing needs to know which fragments
+     * claim this URL, and that answer must survive with no server to ask.
+     */
+    snapshotUrl: string;
+    cachePrefix?: string;
+    caches?: CacheStorage;
+    fetch?: typeof fetch;
+    /** Called when a page is composed offline, so a shell can say so rather than look merely slow. */
+    onCompose?: (event: {
+        pathname: string;
+        fragmentIds: string[];
+    }) => void;
+}
+/**
+ * A navigation handler that composes from cache when the network is gone.
+ *
+ * ```js
+ * const compose = braidNavigationHandler({ snapshotUrl: '/__braid/registry/pinned.json' });
+ * self.addEventListener('fetch', (event) => {
+ *   const handled = compose(event.request);
+ *   if (handled) event.respondWith(handled);
+ * });
+ * ```
+ */
+export declare function braidNavigationHandler(options: OfflineCompositionOptions): (request: Request) => Promise<Response> | null;

package/src/lib/compose.js

@@ -0,0 +1,153 @@
+import { BRAID_DOCUMENT_PREFIX, Registry, pierceShellHtml, } from '@braidlabs/gateway';
+const DEFAULT_CACHE_PREFIX = 'braid-frag';
+const SHELL_CACHE = 'braid-shell';
+const SNAPSHOT_CACHE = 'braid-snapshot';
+/**
+ * A navigation handler that composes from cache when the network is gone.
+ *
+ * ```js
+ * const compose = braidNavigationHandler({ snapshotUrl: '/__braid/registry/pinned.json' });
+ * self.addEventListener('fetch', (event) => {
+ *   const handled = compose(event.request);
+ *   if (handled) event.respondWith(handled);
+ * });
+ * ```
+ */
+export function braidNavigationHandler(options) {
+    const cachePrefix = options.cachePrefix ?? DEFAULT_CACHE_PREFIX;
+    const cacheStorage = options.caches ?? globalThis.caches;
+    const networkFetch = options.fetch ?? globalThis.fetch;
+    return (request) => {
+        if (request.method !== 'GET' || !isNavigation(request))
+            return null;
+        return handle(request);
+    };
+    async function handle(request) {
+        try {
+            const response = await networkFetch(request);
+            // Kept for the next outage rather than awaited: the user is waiting on this navigation, and
+            // refreshing the parts is work for a future load.
+            void refresh(request).catch(() => undefined);
+            return response;
+        }
+        catch (error) {
+            const composed = await composeFromCache(request);
+            if (composed)
+                return composed;
+            throw error;
+        }
+    }
+    /**
+     * Re-fetches the parts a compose would need: the unpierced shell, and each matching fragment's
+     * prepared document.
+     *
+     * The shell is requested with `sec-fetch-dest: empty`, which is how the gateway distinguishes a
+     * soft-navigation fetch from a document request — so it answers with the shell alone. That is not
+     * a trick; it is the same distinction the `Vary` header on every pierced response already
+     * declares, used from the other side.
+     */
+    async function refresh(request) {
+        if (!cacheStorage)
+            return;
+        const url = new URL(request.url);
+        const manifests = await loadSnapshot(url.origin);
+        if (!manifests)
+            return;
+        const registry = new Registry([...manifests]);
+        const matches = await registry.matchPierceRoutes(url.pathname);
+        const shell = await networkFetch(new Request(request.url, { headers: { 'sec-fetch-dest': 'empty' } }));
+        if (shell.ok) {
+            const shellCache = await cacheStorage.open(SHELL_CACHE);
+            await shellCache.put(shellKey(url), shell.clone());
+        }
+        for (const manifest of matches) {
+            const documentUrl = `${url.origin}${BRAID_DOCUMENT_PREFIX}${encodeURIComponent(manifest.id)}${documentPath(manifest, url)}`;
+            const response = await networkFetch(documentUrl);
+            if (!response.ok)
+                continue;
+            // In the fragment's own partition, so pruning a retired fragment takes its documents too.
+            const cache = await cacheStorage.open(`${cachePrefix}:${manifest.id}`);
+            await cache.put(documentUrl, response.clone());
+        }
+    }
+    async function composeFromCache(request) {
+        if (!cacheStorage)
+            return null;
+        const url = new URL(request.url);
+        const shellCache = await cacheStorage.open(SHELL_CACHE);
+        const shell = await shellCache.match(shellKey(url));
+        if (!shell?.body)
+            return null;
+        const manifests = await loadSnapshot(url.origin);
+        if (!manifests)
+            return null;
+        const registry = new Registry([...manifests]);
+        const matches = await registry.matchPierceRoutes(url.pathname);
+        const fragments = [];
+        for (const manifest of matches) {
+            const cache = await cacheStorage.open(`${cachePrefix}:${manifest.id}`);
+            const documentUrl = `${url.origin}${BRAID_DOCUMENT_PREFIX}${encodeURIComponent(manifest.id)}${documentPath(manifest, url)}`;
+            const cached = await cache.match(documentUrl);
+            // A fragment with nothing cached pierces nothing and is marked, exactly as a failed fetch is
+            // server-side: the slot degrades to a placeholder rather than the page failing.
+            fragments.push({
+                fragmentId: manifest.id,
+                content: cached?.body ?? null,
+                ...(cached?.body ? {} : { fallbackReason: 'placeholder' }),
+                ...(manifest.src === undefined ? {} : { src: manifest.src }),
+            });
+        }
+        options.onCompose?.({ pathname: url.pathname, fragmentIds: matches.map((manifest) => manifest.id) });
+        return new Response(pierceShellHtml({ shell: shell.body, fragments }), {
+            headers: {
+                'content-type': 'text/html; charset=utf-8',
+                // Says plainly where this page came from. A composed-offline page that looks identical to a
+                // served one is a page nobody can debug.
+                'x-braid-composed': 'offline',
+            },
+        });
+    }
+    /** The snapshot, from cache first — offline is the case that needs it. */
+    async function loadSnapshot(origin) {
+        if (!cacheStorage)
+            return null;
+        const url = new URL(options.snapshotUrl, origin).href;
+        const cache = await cacheStorage.open(SNAPSHOT_CACHE);
+        let response = await cache.match(url);
+        if (!response) {
+            try {
+                const fresh = await networkFetch(url);
+                if (!fresh.ok)
+                    return null;
+                await cache.put(url, fresh.clone());
+                response = fresh;
+            }
+            catch {
+                return null;
+            }
+        }
+        try {
+            const snapshot = (await response.json());
+            return Array.isArray(snapshot) ? snapshot : (snapshot.manifests ?? null);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/** Unbound fragments are fetched at their own path, bound ones at the page's — as on the server. */
+function documentPath(manifest, url) {
+    return manifest.bound === false && manifest.src ? manifest.src : `${url.pathname}${url.search}`;
+}
+/** Keyed by path alone: a shell does not vary by query, and keying on one would cache N copies. */
+function shellKey(url) {
+    return `${url.origin}${url.pathname}`;
+}
+function isNavigation(request) {
+    if (request.mode === 'navigate')
+        return true;
+    // `mode` is not always populated outside a browser; the accept header is the same signal the
+    // gateway itself falls back to.
+    return request.headers.get('accept')?.includes('text/html') ?? false;
+}
+//# sourceMappingURL=compose.js.map

package/src/lib/compose.js.map

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

package/src/lib/precache.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Realm stub precaching: a fragment boot with no round trip in it.
+ *
+ * A realm stub is the tiny document a fragment's realm is created from. They are identical per URL
+ * and vary on nothing — which is what the protocol's path split bought — so they are the one thing
+ * in this system that can be fetched before anybody asks for it without guessing.
+ *
+ * Kept deliberately small in scope: stubs only. Precaching a fragment's *application* bundles would
+ * mean downloading every fragment on the origin whether or not the user ever visits a page that
+ * composes them, which trades a round trip the user might make for bandwidth they certainly spend.
+ */
+export interface PrecacheOptions {
+    cachePrefix?: string;
+    caches?: CacheStorage;
+    fetch?: typeof fetch;
+    /** Where the stubs live. Defaults to the current origin. */
+    origin?: string;
+}
+export interface PrecacheResult {
+    cached: string[];
+    /** Stubs that could not be fetched, with why. A precache failure must not fail the install. */
+    failed: {
+        url: string;
+        reason: string;
+    }[];
+}
+/**
+ * Fetches and caches each fragment's realm stub.
+ *
+ * Call it from `install`, wrapped in `waitUntil`. Failures are collected rather than thrown: a
+ * worker that refuses to install because one fragment's origin was briefly unreachable is worse
+ * than a worker that installs and fetches that stub on demand like it used to.
+ */
+export declare function precacheRealmStubs(fragmentIds: readonly string[], options?: PrecacheOptions): Promise<PrecacheResult>;

package/src/lib/precache.js

@@ -0,0 +1,36 @@
+import { BRAID_REALM_PREFIX } from '@braidlabs/gateway';
+const DEFAULT_CACHE_PREFIX = 'braid-frag';
+/**
+ * Fetches and caches each fragment's realm stub.
+ *
+ * Call it from `install`, wrapped in `waitUntil`. Failures are collected rather than thrown: a
+ * worker that refuses to install because one fragment's origin was briefly unreachable is worse
+ * than a worker that installs and fetches that stub on demand like it used to.
+ */
+export async function precacheRealmStubs(fragmentIds, options = {}) {
+    const cachePrefix = options.cachePrefix ?? DEFAULT_CACHE_PREFIX;
+    const cacheStorage = options.caches ?? globalThis.caches;
+    const networkFetch = options.fetch ?? globalThis.fetch;
+    const origin = options.origin ?? globalThis.location?.origin ?? '';
+    const result = { cached: [], failed: [] };
+    if (!cacheStorage)
+        return result;
+    for (const fragmentId of fragmentIds) {
+        const url = `${origin}${BRAID_REALM_PREFIX}${fragmentId}/`;
+        try {
+            const response = await networkFetch(url);
+            if (!response.ok) {
+                result.failed.push({ url, reason: `HTTP ${response.status}` });
+                continue;
+            }
+            const cache = await cacheStorage.open(`${cachePrefix}:${fragmentId}`);
+            await cache.put(url, response);
+            result.cached.push(url);
+        }
+        catch (error) {
+            result.failed.push({ url, reason: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=precache.js.map

package/src/lib/precache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"precache.js","sourceRoot":"","sources":["../../../../../libs/braid-sw/src/lib/precache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AA4BxD,MAAM,oBAAoB,GAAG,YAAY,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,WAA8B,EAC9B,UAA2B,EAAE;IAE7B,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,oBAAoB,CAAC;IAChE,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,IAAK,UAAwC,CAAC,MAAM,CAAC;IACxF,MAAM,YAAY,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;IACvD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAK,UAAgD,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,CAAC;IAE1G,MAAM,MAAM,GAAmB,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAC1D,IAAI,CAAC,YAAY;QAAE,OAAO,MAAM,CAAC;IAEjC,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,GAAG,MAAM,GAAG,kBAAkB,GAAG,UAAU,GAAG,CAAC;QAC3D,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,CAAC;YACzC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;gBAC/D,SAAS;YACX,CAAC;YACD,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,GAAG,WAAW,IAAI,UAAU,EAAE,CAAC,CAAC;YACtE,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;YAC/B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC9F,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/src/lib/reports.d.ts

@@ -0,0 +1,54 @@
+import { type RecordDriver } from '@braidlabs/data';
+import type { AssetReport } from './asset-handler.js';
+import type { SkewDiagnosis } from './skew-report.js';
+/**
+ * Durable reports: telemetry that survives the tab being closed.
+ *
+ * The worker already knows things nobody else can see — that a chunk was served from cache after the
+ * origin 404'd it, that its build disagrees with the page's. Handed to an `onReport` callback those
+ * facts are fire-and-forget: a `fetch` started as the tab is closing races page teardown and usually
+ * loses, and the reports that go missing are disproportionately the interesting ones. A user hitting
+ * a broken deploy is a user who closes the tab.
+ *
+ * Background Sync fixes exactly that: records are queued durably and flushed when the browser next
+ * says it can, whether or not any page is open. It is **Chromium-only**, so this is an enhancement
+ * to sending reports rather than a replacement for it — the queue flushes opportunistically too, and
+ * a browser without `sync` simply gets the opportunistic path.
+ *
+ * The queue itself is `@braidlabs/data`'s outbox rather than a second implementation: one record per
+ * entry, so appending never reads the queue first and two contexts cannot lose each other's writes.
+ * That problem was solved once already, and solving it again here would mean debugging it again too.
+ */
+export type BraidReport = {
+    kind: 'asset';
+    at: string;
+    report: AssetReport;
+} | {
+    kind: 'skew';
+    at: string;
+    diagnosis: SkewDiagnosis;
+};
+export interface ReportQueueOptions {
+    /** Where reports are POSTed, as JSON. */
+    endpoint: string;
+    /** Storage for the queue. In a worker, `indexedDbRecordDriver()`. */
+    driver: RecordDriver;
+    /** Distinguishes this worker's reports from anything else sharing the origin's storage. */
+    owner?: string;
+    /** Batch size per flush. Bounded so one flush cannot become an unbounded upload. */
+    batchSize?: number;
+    fetch?: typeof fetch;
+}
+export interface FlushOutcome {
+    sent: number;
+    /** Entries left queued — the endpoint refused them, and they are still owed. */
+    remaining: number;
+}
+export interface ReportQueue {
+    record(report: BraidReport): Promise<void>;
+    flush(): Promise<FlushOutcome>;
+    pending(): Promise<number>;
+}
+export declare function createReportQueue(options: ReportQueueOptions): ReportQueue;
+/** The Background Sync tag this queue registers and answers to. */
+export declare const BRAID_REPORT_SYNC_TAG = "braid-sw:reports";

package/src/lib/reports.js

@@ -0,0 +1,59 @@
+import { createOutbox } from '@braidlabs/data';
+const REPORT_MUTATION = 'braid-sw.report';
+export function createReportQueue(options) {
+    const networkFetch = options.fetch ?? globalThis.fetch;
+    const batchSize = options.batchSize ?? 50;
+    const outbox = createOutbox({
+        driver: options.driver,
+        owner: options.owner ?? 'braid-sw',
+        collection: 'braid-sw-reports',
+    });
+    return {
+        async record(report) {
+            await outbox.enqueue({ mutationId: REPORT_MUTATION, input: report });
+        },
+        async pending() {
+            return (await outbox.mine()).length;
+        },
+        /**
+         * Sends what is queued, oldest first, and removes only what the endpoint accepted.
+         *
+         * One request per batch rather than per record: a worker waking to flush forty reports should
+         * not make forty requests, and the endpoint learns more from a batch than from its parts. A
+         * refused batch stays queued in full — partial credit would need the endpoint to say which
+         * records it took, and no telemetry endpoint does.
+         */
+        async flush() {
+            const entries = (await outbox.mine()).slice(0, batchSize);
+            if (entries.length === 0)
+                return { sent: 0, remaining: 0 };
+            try {
+                const response = await networkFetch(options.endpoint, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body: JSON.stringify({ reports: entries.map((entry) => entry.input) }),
+                    // Reports are diagnostics, not a session: sending credentials with them would attach
+                    // identity to data nobody asked to have attached.
+                    credentials: 'omit',
+                    keepalive: true,
+                });
+                if (!response.ok) {
+                    await Promise.all(entries.map((entry) => outbox.recordFailure(entry.id, `HTTP ${response.status}`)));
+                    return { sent: 0, remaining: (await outbox.mine()).length };
+                }
+                await Promise.all(entries.map((entry) => outbox.remove(entry.id)));
+                return { sent: entries.length, remaining: (await outbox.mine()).length };
+            }
+            catch (error) {
+                // Still offline. The whole point of the queue is that this is survivable, so the entries
+                // stay exactly where they are.
+                const message = error instanceof Error ? error.message : String(error);
+                await Promise.all(entries.map((entry) => outbox.recordFailure(entry.id, message)));
+                return { sent: 0, remaining: (await outbox.mine()).length };
+            }
+        },
+    };
+}
+/** The Background Sync tag this queue registers and answers to. */
+export const BRAID_REPORT_SYNC_TAG = 'braid-sw:reports';
+//# sourceMappingURL=reports.js.map

package/src/lib/reports.js.map

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

package/src/lib/skew-report.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The worker's own version boundary.
+ *
+ * A service worker is a long-lived deployment artifact that updates on its own schedule, which
+ * makes it a skew vector inside a system whose entire purpose is managing skew. It gets the same
+ * discipline as everything else here: it knows its build and the registry snapshot it is serving,
+ * and when those disagree with the page it is answering for, it says so.
+ *
+ * The alternative is the failure worth designing against — a worker that quietly serves yesterday's
+ * assets to today's document. That does not look like a worker problem to anyone debugging it. It
+ * looks like an application bug, in an application that is fine.
+ */
+export type SkewSeverity = 'ok' | 'worker-behind' | 'worker-ahead' | 'snapshot-mismatch';
+export interface WorkerVersion {
+    /** The build this worker script was shipped as. */
+    buildId?: string;
+    /** The registry snapshot id this worker is composing against. */
+    snapshotId?: string;
+}
+export interface PageVersion {
+    buildId?: string;
+    snapshotId?: string;
+}
+export interface SkewDiagnosis {
+    severity: SkewSeverity;
+    message: string;
+    worker: WorkerVersion;
+    page: PageVersion;
+    /** What to do about it, phrased as an instruction. */
+    fixHint?: string;
+}
+/**
+ * Compares the worker's version with the page's.
+ *
+ * Deliberately not an error: a mismatch is usually transient and self-healing — a deploy landed
+ * while a tab was open, and the worker updates on the next navigation. What it must never be is
+ * invisible, so this returns something a host can log, report, or show, and the prebuilt worker
+ * always logs it.
+ */
+export declare function diagnoseSkew(worker: WorkerVersion, page: PageVersion): SkewDiagnosis;
+/**
+ * The header a gateway-served worker can read its page's build from.
+ *
+ * A header rather than a query parameter on the script URL, on purpose: baking the build into the
+ * worker's URL would change the URL on every deploy, and a changed worker URL is a new worker with
+ * its own install-and-wait lifecycle. Configuration churn should not become worker churn.
+ */
+export declare const BRAID_BUILD_HEADER = "x-braid-build";
+export declare const BRAID_SNAPSHOT_HEADER = "x-braid-snapshot";

package/src/lib/skew-report.js

@@ -0,0 +1,55 @@
+/**
+ * The worker's own version boundary.
+ *
+ * A service worker is a long-lived deployment artifact that updates on its own schedule, which
+ * makes it a skew vector inside a system whose entire purpose is managing skew. It gets the same
+ * discipline as everything else here: it knows its build and the registry snapshot it is serving,
+ * and when those disagree with the page it is answering for, it says so.
+ *
+ * The alternative is the failure worth designing against — a worker that quietly serves yesterday's
+ * assets to today's document. That does not look like a worker problem to anyone debugging it. It
+ * looks like an application bug, in an application that is fine.
+ */
+/**
+ * Compares the worker's version with the page's.
+ *
+ * Deliberately not an error: a mismatch is usually transient and self-healing — a deploy landed
+ * while a tab was open, and the worker updates on the next navigation. What it must never be is
+ * invisible, so this returns something a host can log, report, or show, and the prebuilt worker
+ * always logs it.
+ */
+export function diagnoseSkew(worker, page) {
+    const base = { worker, page };
+    if (worker.snapshotId && page.snapshotId && worker.snapshotId !== page.snapshotId) {
+        return {
+            ...base,
+            severity: 'snapshot-mismatch',
+            message: `braid-sw: this worker is composing against registry snapshot "${worker.snapshotId}" and the ` +
+                `page was rendered against "${page.snapshotId}" — the two disagree about which fragments exist`,
+            fixHint: 'the worker updates on the next navigation; if it persists, the gateway is serving a worker ' +
+                'pinned to a snapshot the shell no longer deploys',
+        };
+    }
+    if (worker.buildId && page.buildId && worker.buildId !== page.buildId) {
+        // Which side is stale is not decidable from two opaque ids, and guessing would produce a
+        // confident, wrong instruction. Both directions are named; the fix is the same either way.
+        return {
+            ...base,
+            severity: 'worker-behind',
+            message: `braid-sw: worker build "${worker.buildId}" is serving a page built as "${page.buildId}" — ` +
+                'assets may be answered from the older build',
+            fixHint: 'reload once the worker has activated, or call skipWaiting in your own install handler',
+        };
+    }
+    return { ...base, severity: 'ok', message: 'braid-sw: worker and page agree' };
+}
+/**
+ * The header a gateway-served worker can read its page's build from.
+ *
+ * A header rather than a query parameter on the script URL, on purpose: baking the build into the
+ * worker's URL would change the URL on every deploy, and a changed worker URL is a new worker with
+ * its own install-and-wait lifecycle. Configuration churn should not become worker churn.
+ */
+export const BRAID_BUILD_HEADER = 'x-braid-build';
+export const BRAID_SNAPSHOT_HEADER = 'x-braid-snapshot';
+//# sourceMappingURL=skew-report.js.map

package/src/lib/skew-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skew-report.js","sourceRoot":"","sources":["../../../../../libs/braid-sw/src/lib/skew-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAyBH;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,MAAqB,EAAE,IAAiB;IACnE,MAAM,IAAI,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAE9B,IAAI,MAAM,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,IAAI,MAAM,CAAC,UAAU,KAAK,IAAI,CAAC,UAAU,EAAE,CAAC;QAClF,OAAO;YACL,GAAG,IAAI;YACP,QAAQ,EAAE,mBAAmB;YAC7B,OAAO,EACL,iEAAiE,MAAM,CAAC,UAAU,YAAY;gBAC9F,8BAA8B,IAAI,CAAC,UAAU,kDAAkD;YACjG,OAAO,EACL,6FAA6F;gBAC7F,kDAAkD;SACrD,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC;QACtE,yFAAyF;QACzF,2FAA2F;QAC3F,OAAO;YACL,GAAG,IAAI;YACP,QAAQ,EAAE,eAAe;YACzB,OAAO,EACL,2BAA2B,MAAM,CAAC,OAAO,iCAAiC,IAAI,CAAC,OAAO,MAAM;gBAC5F,6CAA6C;YAC/C,OAAO,EAAE,uFAAuF;SACjG,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,iCAAiC,EAAE,CAAC;AACjF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAClD,MAAM,CAAC,MAAM,qBAAqB,GAAG,kBAAkB,CAAC"}

package/src/lib/worker.d.ts

@@ -0,0 +1,61 @@
+import { type BraidFetchHandlerOptions } from './asset-handler.js';
+import { type OfflineCompositionOptions } from './compose.js';
+import { type ReportQueueOptions } from './reports.js';
+/**
+ * The complete worker, for shells that do not already have one.
+ *
+ * Both shapes ship because the assumption that an application already has a service worker does not
+ * hold — least of all for internal enterprise apps, which is much of the audience. A shell that has
+ * a worker composes {@link braidFetchHandler} into it and keeps ownership of its own `fetch` event;
+ * a shell that has none calls this and authors nothing.
+ */
+export interface BraidWorkerOptions extends BraidFetchHandlerOptions {
+    /** Fragment ids whose realm stubs are precached at install. */
+    precache?: readonly string[];
+    /** The registry snapshot this worker composes against, for the skew diagnostic. */
+    snapshotId?: string;
+    /**
+     * Take over open pages as soon as this worker activates.
+     *
+     * Off by default, and that default is the conservative one for a reason: claiming clients swaps
+     * the worker underneath a page that is already running, so a page mid-session starts being served
+     * by a build it did not load against. Waiting for the next navigation is the boring, correct
+     * behaviour; turn this on when you would rather have the update than the continuity.
+     */
+    claimClients?: boolean;
+    /**
+     * Compose pages from cache when the network is gone.
+     *
+     * Opt-in, because it changes what a failed navigation *is*: without it an offline navigation is
+     * the browser's offline page, which is at least unambiguous. With it, a route the user has
+     * visited before comes back composed — so a shell turning this on should say so on the page, and
+     * the `x-braid-composed: offline` header is there to make that possible.
+     */
+    offline?: OfflineCompositionOptions;
+    /**
+     * Send the worker's own reports durably, surviving a closed tab.
+     *
+     * Without this, `onReport` is fire-and-forget and the reports most likely to be lost are the ones
+     * worth having: a user who hits a broken deploy is a user who closes the tab.
+     */
+    reports?: Omit<ReportQueueOptions, 'fetch'>;
+}
+/** The subset of the worker global this uses, so a test can supply one without a worker. */
+export interface WorkerScopeLike {
+    addEventListener(type: string, listener: (event: never) => void): void;
+    skipWaiting?(): Promise<void>;
+    clients?: {
+        claim(): Promise<void>;
+    };
+    registration?: unknown;
+}
+/**
+ * Installs Braid's handlers on a worker scope.
+ *
+ * ```js
+ * // sw.js
+ * import { setupBraidWorker } from '@braidlabs/sw';
+ * setupBraidWorker({ buildId: BUILD_ID, precache: ['billing', 'notifications'] });
+ * ```
+ */
+export declare function setupBraidWorker(options?: BraidWorkerOptions): void;

package/src/lib/worker.js

@@ -0,0 +1,96 @@
+import { braidFetchHandler, pruneFragmentCaches } from './asset-handler.js';
+import { braidNavigationHandler } from './compose.js';
+import { precacheRealmStubs } from './precache.js';
+import { diagnoseSkew } from './skew-report.js';
+import { BRAID_REPORT_SYNC_TAG, createReportQueue } from './reports.js';
+/**
+ * Installs Braid's handlers on a worker scope.
+ *
+ * ```js
+ * // sw.js
+ * import { setupBraidWorker } from '@braidlabs/sw';
+ * setupBraidWorker({ buildId: BUILD_ID, precache: ['billing', 'notifications'] });
+ * ```
+ */
+export function setupBraidWorker(options = {}) {
+    const scope = globalThis;
+    const reports = options.reports
+        ? createReportQueue({ ...options.reports, ...(options.fetch ? { fetch: options.fetch } : {}) })
+        : null;
+    const handler = braidFetchHandler({
+        ...options,
+        ...(reports
+            ? {
+                onReport: (report) => {
+                    options.onReport?.(report);
+                    // Queued, not sent: the send is the part that loses races with page teardown.
+                    void reports.record({ kind: 'asset', at: new Date().toISOString(), report });
+                },
+            }
+            : {}),
+    });
+    const version = {
+        ...(options.buildId === undefined ? {} : { buildId: options.buildId }),
+        ...(options.snapshotId === undefined ? {} : { snapshotId: options.snapshotId }),
+    };
+    scope.addEventListener('install', (event) => {
+        if (!options.precache?.length)
+            return;
+        // The precache is best-effort by construction: a worker that refuses to install because one
+        // fragment's origin blinked is worse than one that installs and fetches that stub on demand.
+        event.waitUntil?.(precacheRealmStubs(options.precache, options).then((result) => {
+            for (const failure of result.failed) {
+                console.warn(`braid-sw: could not precache ${failure.url} — ${failure.reason}`);
+            }
+        }));
+    });
+    scope.addEventListener('activate', (event) => {
+        const work = [];
+        if (options.precache?.length)
+            work.push(pruneFragmentCaches(options.precache, options));
+        if (options.claimClients && scope.clients)
+            work.push(scope.clients.claim());
+        // Background Sync is Chromium-only, so every activation also flushes opportunistically. A
+        // browser without `sync` gets this path and nothing else; one with it gets both.
+        if (reports)
+            work.push(reports.flush());
+        if (work.length)
+            event.waitUntil?.(Promise.all(work));
+    });
+    /**
+     * The durable path: the browser wakes the worker when it judges the network is back, with no page
+     * open and nothing racing teardown.
+     */
+    if (reports) {
+        scope.addEventListener('sync', (event) => {
+            if (event.tag !== BRAID_REPORT_SYNC_TAG)
+                return;
+            event.waitUntil?.(reports.flush());
+        });
+    }
+    const navigate = options.offline ? braidNavigationHandler({ ...options, ...options.offline }) : null;
+    scope.addEventListener('fetch', (event) => {
+        // Assets first: they are the overwhelming majority, and a navigation is never one.
+        const handled = handler(event.request) ?? navigate?.(event.request);
+        if (handled)
+            event.respondWith?.(handled);
+    });
+    /**
+     * The page introduces itself, and the worker answers with what it is.
+     *
+     * A page cannot read a worker's build any other way, and the mismatch this surfaces is precisely
+     * the one that otherwise presents as an application bug in an application that is fine.
+     */
+    scope.addEventListener('message', (event) => {
+        const data = event.data;
+        if (data?.type !== 'braid-sw:hello')
+            return;
+        const diagnosis = diagnoseSkew(version, data.page ?? {});
+        if (diagnosis.severity !== 'ok') {
+            console.warn(diagnosis.message);
+            void reports?.record({ kind: 'skew', at: new Date().toISOString(), diagnosis });
+        }
+        event.source?.postMessage?.({ type: 'braid-sw:version', diagnosis });
+    });
+}
+//# sourceMappingURL=worker.js.map

package/src/lib/worker.js.map

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