cursedbelt-core 2.1.1 → 2.2.0

package/dist/core/offline/shellWorker.d.ts

@@ -0,0 +1,185 @@
+/**
+ * The app-shell service worker, once, for every app that serves its shell offline
+ * (task 2073, 2026-09-22).
+ *
+ * `apps/roms` wrote this by hand as plain JS in `public/sw.js`, with a TypeScript
+ * twin in `src/offline/swRouting.ts` held in step by a comment saying "keep the two
+ * in step". `apps/music` needed the same worker, and a third hand copy is how a fix
+ * lands in one app and not the others. This module is the one body; an app's
+ * `src/sw.ts` passes a config and adds whatever is genuinely its own (background
+ * sync, an outbox, a digest-keyed media cache) as further listeners beside it.
+ *
+ * What it does, and it is deliberately all it does:
+ *  - `install`  — precache the shell and the config's `precache` list, then `skipWaiting`.
+ *  - `activate` — delete every cache named `<cachePrefix>*` that is not this version's,
+ *                 then `clients.claim()`.
+ *  - `fetch`    — same-origin static ASSETS cache-first; document NAVIGATIONS
+ *                 network-first, falling back offline to the exact URL, then the same
+ *                 path ignoring the query, then the shell. Everything else is left on
+ *                 the network: `respondWith` is never called for it.
+ *
+ * 🔴 `/api/` is NEVER cached and NEVER served from a cache. It is auth-gated, and a
+ * browser whose session has since been revoked must not read yesterday's copy of a
+ * private response out of its own cache. That is not a default a config can switch
+ * off: `apiPrefixes` ADDS prefixes to `/api/`, it cannot remove it, a precache entry
+ * under an API prefix is refused when the worker is installed, and `shouldCache`
+ * refuses to store an `api` route even if a caller asks.
+ *
+ * 🔴 `noShellFallback` exists because of the 2026-08-12 frame incident in roms. A game
+ * boots by loading `/emulator-frame.html` into a sandboxed iframe — a NAVIGATION, so it
+ * went network-first, and offline with nothing cached under that path the fallback
+ * handed it the APP SHELL. The iframe rendered a second copy of the library where the
+ * game should be: no canvas, no error, no clue. Any document that is not the shell (an
+ * iframe, a popup, a print view) must be listed there, and must be in `precache` if it
+ * is meant to work offline at all — an offline miss on it then REJECTS, which is the
+ * honest answer, rather than resolving the wrong document.
+ *
+ * Imports nothing at runtime (`leafSubpathsImportNothing.spec.ts` holds it to that):
+ * it is bundled into a service worker, where every byte ships on every install.
+ * `scope` is typed structurally so this compiles without the WebWorker lib, is testable
+ * with a fake, and still accepts the real `self` — `shellWorker.webworker.spec.ts`
+ * typechecks exactly that against `lib.webworker.d.ts`.
+ */
+/** Where a request goes. */
+export type ShellRoute = 
+/** A document navigation — network-first, cached-document fallback offline. */
+'navigate'
+/** A same-origin static asset (JS/CSS/WASM/font/image/JSON) — cache-first. */
+ | 'asset'
+/** An auth-gated API call — never cached, never answered from a cache. */
+ | 'api'
+/** Everything else (non-GET, cross-origin, `passthroughPrefixes`) — untouched. */
+ | 'passthrough';
+/** The facts about a request that classification reads — nothing else. */
+export interface RequestFacts {
+    method: string;
+    /** Same origin as the worker (`new URL(request.url).origin === location.origin`). */
+    sameOrigin: boolean;
+    /** URL pathname, no query. */
+    pathname: string;
+    /** `request.mode === 'navigate'`. */
+    isNavigate: boolean;
+}
+export interface ShellWorkerConfig {
+    /**
+     * Every cache this worker owns is named `<cachePrefix><version>`, and `activate`
+     * deletes every OTHER cache starting with `cachePrefix`. So the prefix must be one
+     * nothing else in the app shares — `roms-shell-`, not `roms-`, or the app's own
+     * digest-keyed caches go with it.
+     */
+    cachePrefix: string;
+    /** Bump to evict the previous shell on the next activate. */
+    version: string;
+    /**
+     * Same-origin paths fetched into the cache at install. `shellPath` is always
+     * precached whether listed or not — a shell fallback with no shell is no fallback.
+     */
+    precache: readonly string[];
+    /**
+     * Extra API prefixes. `/api/` is ALWAYS one of them and cannot be removed — see the
+     * header. Default: `['/api/']`.
+     */
+    apiPrefixes?: readonly string[];
+    /**
+     * Same-origin prefixes the worker must leave alone even for GET assets — e.g. roms'
+     * `/_nes-roms/`, whose bytes the app caches itself under a content digest.
+     */
+    passthroughPrefixes?: readonly string[];
+    /**
+     * Exact pathnames that must NEVER be answered with the shell offline (roms'
+     * `/emulator-frame.html`). An offline miss on one rejects instead. See the header.
+     */
+    noShellFallback?: readonly string[];
+    /** Which same-origin pathnames count as static assets. Default: `DEFAULT_ASSET_EXT`. */
+    assetExtensions?: RegExp;
+    /** The app shell's path, the navigation fallback. Default: `'/'`. */
+    shellPath?: string;
+}
+/** A config with every default applied and every refusal already checked. */
+export interface ResolvedShellWorkerConfig {
+    cachePrefix: string;
+    version: string;
+    cacheName: string;
+    precache: readonly string[];
+    apiPrefixes: readonly string[];
+    passthroughPrefixes: readonly string[];
+    noShellFallback: readonly string[];
+    assetExtensions: RegExp;
+    shellPath: string;
+}
+/** roms' `ASSET_EXT`, verbatim. */
+export declare const DEFAULT_ASSET_EXT: RegExp;
+/** Always an API prefix, whatever the config says. */
+export declare const ALWAYS_API_PREFIX = "/api/";
+/**
+ * Classify a request. Order matters and is roms' order: non-GET and cross-origin
+ * first, then the API (so an API path that happens to end in `.json` is still `api`),
+ * then the app's own passthrough prefixes, then navigation, then assets.
+ */
+export declare function classifyRequest(facts: RequestFacts, config?: Pick<ShellWorkerConfig, 'apiPrefixes' | 'passthroughPrefixes' | 'assetExtensions'>): ShellRoute;
+/** Whether a response on this route may be written to the cache. Never `api`. */
+export declare function shouldCache(route: ShellRoute): boolean;
+/** May an offline miss on this navigation be answered with the shell? */
+export declare function mayFallBackToShell(pathname: string, config?: Pick<ShellWorkerConfig, 'noShellFallback'>): boolean;
+/**
+ * Apply defaults and refuse the configs that would break a promise in the header.
+ * `installShellWorker` calls this; it is exported so an app's own test can prove its
+ * config is accepted without standing up a worker.
+ */
+export declare function resolveShellWorkerConfig(config: ShellWorkerConfig): ResolvedShellWorkerConfig;
+export interface ShellWorkerRequest {
+    readonly url: string;
+    readonly method: string;
+    readonly mode: string;
+}
+/**
+ * The structural mirror of `RequestInfo | URL` — a request, a string, or a URL-like —
+ * which is what the real `fetch`, `Cache` and `CacheStorage` accept. It has to be the
+ * whole union: with `ShellWorkerRequest` alone the real `self` is refused, because a
+ * `URL` is not a request in either direction (measured by the webworker spec).
+ */
+export type ShellWorkerRequestInfo = ShellWorkerRequest | string | {
+    readonly href: string;
+};
+export interface ShellWorkerResponse {
+    readonly ok: boolean;
+    clone(): ShellWorkerResponse;
+}
+export interface ShellWorkerCache {
+    addAll(requests: string[]): Promise<void>;
+    put(request: ShellWorkerRequestInfo, response: ShellWorkerResponse): Promise<void>;
+}
+export interface ShellWorkerCacheStorage {
+    open(cacheName: string): Promise<ShellWorkerCache>;
+    keys(): Promise<string[]>;
+    delete(cacheName: string): Promise<boolean>;
+    match(request: ShellWorkerRequestInfo, options?: {
+        ignoreSearch?: boolean;
+    }): Promise<ShellWorkerResponse | undefined>;
+}
+export interface ShellExtendableEvent {
+    waitUntil(promise: Promise<unknown>): void;
+}
+export interface ShellFetchEvent extends ShellExtendableEvent {
+    readonly request: ShellWorkerRequest;
+    respondWith(response: Promise<ShellWorkerResponse>): void;
+}
+export interface ShellWorkerScope {
+    addEventListener(type: 'install', listener: (event: ShellExtendableEvent) => void): void;
+    addEventListener(type: 'activate', listener: (event: ShellExtendableEvent) => void): void;
+    addEventListener(type: 'fetch', listener: (event: ShellFetchEvent) => void): void;
+    readonly caches: ShellWorkerCacheStorage;
+    readonly clients: {
+        claim(): Promise<void>;
+    };
+    readonly location: {
+        readonly origin: string;
+    };
+    fetch(request: ShellWorkerRequestInfo): Promise<ShellWorkerResponse>;
+    skipWaiting(): Promise<void>;
+}
+/**
+ * Wire `install`, `activate` and `fetch` onto `scope` (the worker's `self`).
+ * Returns the resolved config, so an app can read `cacheName` for its own use.
+ */
+export declare function installShellWorker(scope: ShellWorkerScope, config: ShellWorkerConfig): ResolvedShellWorkerConfig;

package/dist/core/offline/shellWorker.js

@@ -0,0 +1,200 @@
+/**
+ * The app-shell service worker, once, for every app that serves its shell offline
+ * (task 2073, 2026-09-22).
+ *
+ * `apps/roms` wrote this by hand as plain JS in `public/sw.js`, with a TypeScript
+ * twin in `src/offline/swRouting.ts` held in step by a comment saying "keep the two
+ * in step". `apps/music` needed the same worker, and a third hand copy is how a fix
+ * lands in one app and not the others. This module is the one body; an app's
+ * `src/sw.ts` passes a config and adds whatever is genuinely its own (background
+ * sync, an outbox, a digest-keyed media cache) as further listeners beside it.
+ *
+ * What it does, and it is deliberately all it does:
+ *  - `install`  — precache the shell and the config's `precache` list, then `skipWaiting`.
+ *  - `activate` — delete every cache named `<cachePrefix>*` that is not this version's,
+ *                 then `clients.claim()`.
+ *  - `fetch`    — same-origin static ASSETS cache-first; document NAVIGATIONS
+ *                 network-first, falling back offline to the exact URL, then the same
+ *                 path ignoring the query, then the shell. Everything else is left on
+ *                 the network: `respondWith` is never called for it.
+ *
+ * 🔴 `/api/` is NEVER cached and NEVER served from a cache. It is auth-gated, and a
+ * browser whose session has since been revoked must not read yesterday's copy of a
+ * private response out of its own cache. That is not a default a config can switch
+ * off: `apiPrefixes` ADDS prefixes to `/api/`, it cannot remove it, a precache entry
+ * under an API prefix is refused when the worker is installed, and `shouldCache`
+ * refuses to store an `api` route even if a caller asks.
+ *
+ * 🔴 `noShellFallback` exists because of the 2026-08-12 frame incident in roms. A game
+ * boots by loading `/emulator-frame.html` into a sandboxed iframe — a NAVIGATION, so it
+ * went network-first, and offline with nothing cached under that path the fallback
+ * handed it the APP SHELL. The iframe rendered a second copy of the library where the
+ * game should be: no canvas, no error, no clue. Any document that is not the shell (an
+ * iframe, a popup, a print view) must be listed there, and must be in `precache` if it
+ * is meant to work offline at all — an offline miss on it then REJECTS, which is the
+ * honest answer, rather than resolving the wrong document.
+ *
+ * Imports nothing at runtime (`leafSubpathsImportNothing.spec.ts` holds it to that):
+ * it is bundled into a service worker, where every byte ships on every install.
+ * `scope` is typed structurally so this compiles without the WebWorker lib, is testable
+ * with a fake, and still accepts the real `self` — `shellWorker.webworker.spec.ts`
+ * typechecks exactly that against `lib.webworker.d.ts`.
+ */
+/** roms' `ASSET_EXT`, verbatim. */
+export const DEFAULT_ASSET_EXT = /\.(?:js|mjs|css|wasm|woff2?|ttf|png|jpe?g|webp|svg|ico|json)$/i;
+/** Always an API prefix, whatever the config says. */
+export const ALWAYS_API_PREFIX = '/api/';
+const apiPrefixesOf = (config) => {
+    const extra = config.apiPrefixes ?? [];
+    return extra.includes(ALWAYS_API_PREFIX) ? extra : [ALWAYS_API_PREFIX, ...extra];
+};
+const startsWithAny = (pathname, prefixes) => prefixes.some((prefix) => pathname.startsWith(prefix));
+/**
+ * Classify a request. Order matters and is roms' order: non-GET and cross-origin
+ * first, then the API (so an API path that happens to end in `.json` is still `api`),
+ * then the app's own passthrough prefixes, then navigation, then assets.
+ */
+export function classifyRequest(facts, config = {}) {
+    if (facts.method !== 'GET')
+        return 'passthrough';
+    if (!facts.sameOrigin)
+        return 'passthrough';
+    if (startsWithAny(facts.pathname, apiPrefixesOf(config)))
+        return 'api';
+    if (startsWithAny(facts.pathname, config.passthroughPrefixes ?? []))
+        return 'passthrough';
+    if (facts.isNavigate)
+        return 'navigate';
+    if ((config.assetExtensions ?? DEFAULT_ASSET_EXT).test(facts.pathname))
+        return 'asset';
+    return 'passthrough';
+}
+/** Whether a response on this route may be written to the cache. Never `api`. */
+export function shouldCache(route) {
+    return route === 'asset' || route === 'navigate';
+}
+/** May an offline miss on this navigation be answered with the shell? */
+export function mayFallBackToShell(pathname, config = {}) {
+    return !(config.noShellFallback ?? []).includes(pathname);
+}
+/**
+ * Apply defaults and refuse the configs that would break a promise in the header.
+ * `installShellWorker` calls this; it is exported so an app's own test can prove its
+ * config is accepted without standing up a worker.
+ */
+export function resolveShellWorkerConfig(config) {
+    if (config.cachePrefix.trim() === '') {
+        // An empty prefix makes EVERY cache on the origin "an old version of ours", and
+        // activate would delete the app's other caches with it.
+        throw new Error('shell worker: cachePrefix must not be empty — activate deletes every cache it prefixes');
+    }
+    if (config.version.trim() === '')
+        throw new Error('shell worker: version must not be empty');
+    const shellPath = config.shellPath ?? '/';
+    const apiPrefixes = apiPrefixesOf(config);
+    const precache = config.precache.includes(shellPath) ? [...config.precache] : [shellPath, ...config.precache];
+    for (const path of precache) {
+        if (!path.startsWith('/')) {
+            throw new Error(`shell worker: precache entry "${path}" must be a same-origin path starting with "/"`);
+        }
+        if (startsWithAny(path, apiPrefixes)) {
+            throw new Error(`shell worker: precache entry "${path}" is under an API prefix — the API is never cached`);
+        }
+    }
+    if (config.noShellFallback?.includes(shellPath)) {
+        throw new Error(`shell worker: the shell path "${shellPath}" cannot also be in noShellFallback`);
+    }
+    return {
+        cachePrefix: config.cachePrefix,
+        version: config.version,
+        cacheName: `${config.cachePrefix}${config.version}`,
+        precache,
+        apiPrefixes,
+        passthroughPrefixes: config.passthroughPrefixes ?? [],
+        noShellFallback: config.noShellFallback ?? [],
+        assetExtensions: config.assetExtensions ?? DEFAULT_ASSET_EXT,
+        shellPath,
+    };
+}
+/**
+ * Wire `install`, `activate` and `fetch` onto `scope` (the worker's `self`).
+ * Returns the resolved config, so an app can read `cacheName` for its own use.
+ */
+export function installShellWorker(scope, config) {
+    const resolved = resolveShellWorkerConfig(config);
+    const { caches } = scope;
+    // Written after the response is handed back, like roms' `cache.put` — but kept
+    // alive with `waitUntil` so the worker is not stopped mid-write, and swallowed on
+    // failure: a full quota must not turn a good network response into an error.
+    const store = (event, route, response) => {
+        if (!shouldCache(route) || !response.ok)
+            return;
+        const copy = response.clone();
+        event.waitUntil(caches
+            .open(resolved.cacheName)
+            .then((cache) => cache.put(event.request, copy))
+            .catch(() => undefined));
+    };
+    const cacheFirst = async (event) => {
+        const cached = await caches.match(event.request);
+        if (cached)
+            return cached;
+        const response = await scope.fetch(event.request);
+        store(event, 'asset', response);
+        return response;
+    };
+    const networkFirst = async (event) => {
+        const { request } = event;
+        try {
+            const response = await scope.fetch(request);
+            store(event, 'navigate', response);
+            return response;
+        }
+        catch (error) {
+            // Offline. The exact URL first, then the same path ignoring the query — roms'
+            // frame is `/emulator-frame.html?system=nes`, and one cached copy answers for
+            // every console.
+            const cached = (await caches.match(request)) ?? (await caches.match(request, { ignoreSearch: true }));
+            if (cached)
+                return cached;
+            if (mayFallBackToShell(new URL(request.url).pathname, resolved)) {
+                const shell = await caches.match(resolved.shellPath);
+                if (shell)
+                    return shell;
+            }
+            // Nothing honest to serve: reject, and the browser shows its own offline page
+            // rather than a document that is not the one asked for.
+            throw error;
+        }
+    };
+    scope.addEventListener('install', (event) => {
+        event.waitUntil(caches
+            .open(resolved.cacheName)
+            .then((cache) => cache.addAll([...resolved.precache]))
+            .then(() => scope.skipWaiting()));
+    });
+    scope.addEventListener('activate', (event) => {
+        event.waitUntil(caches
+            .keys()
+            .then((keys) => Promise.all(keys
+            .filter((key) => key.startsWith(resolved.cachePrefix) && key !== resolved.cacheName)
+            .map((key) => caches.delete(key))))
+            .then(() => scope.clients.claim()));
+    });
+    scope.addEventListener('fetch', (event) => {
+        const url = new URL(event.request.url);
+        const route = classifyRequest({
+            method: event.request.method,
+            sameOrigin: url.origin === scope.location.origin,
+            pathname: url.pathname,
+            isNavigate: event.request.mode === 'navigate',
+        }, resolved);
+        if (route === 'asset')
+            event.respondWith(cacheFirst(event));
+        else if (route === 'navigate')
+            event.respondWith(networkFirst(event));
+        // `api` and `passthrough`: no respondWith, so the browser goes to the network as
+        // if this worker did not exist. Never a cache read, never a cache write.
+    });
+    return resolved;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-core",
-	"version": "2.1.1",
+	"version": "2.2.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "Framework-agnostic core of the cursedbelt split — isomorphic domain logic. cwip below it, cursedbelt-server and cursedbelt (react) above it.",
@@ -251,6 +251,12 @@
 			"source": "./src/core/net/reconnectSchedule.ts",
 			"import": "./dist/core/net/reconnectSchedule.js"
 		},
+		"./offline/shell-worker": {
+			"types": "./dist/core/offline/shellWorker.d.ts",
+			"bun": "./src/core/offline/shellWorker.ts",
+			"source": "./src/core/offline/shellWorker.ts",
+			"import": "./dist/core/offline/shellWorker.js"
+		},
 		"./palette": {
 			"types": "./dist/core/palette/index.d.ts",
 			"bun": "./src/core/palette/index.ts",

package/src/core/offline/shellWorker.spec.ts

@@ -0,0 +1,392 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  classifyRequest,
+  installShellWorker,
+  mayFallBackToShell,
+  type RequestFacts,
+  resolveShellWorkerConfig,
+  type ShellExtendableEvent,
+  type ShellFetchEvent,
+  type ShellWorkerCache,
+  type ShellWorkerConfig,
+  type ShellWorkerRequest,
+  type ShellWorkerRequestInfo,
+  type ShellWorkerResponse,
+  type ShellWorkerScope,
+  shouldCache,
+} from './shellWorker.js';
+
+/** roms' worker, expressed as a config — the two special cases are the point. */
+const ROMS: ShellWorkerConfig = {
+  cachePrefix: 'roms-shell-',
+  version: 'v3',
+  precache: ['/', '/emulator-frame.html', '/emulator-runtime.js'],
+  passthroughPrefixes: ['/_nes-roms/'],
+  noShellFallback: ['/emulator-frame.html'],
+};
+
+const facts = (pathname: string, over: Partial<RequestFacts> = {}): RequestFacts => ({
+  method: 'GET',
+  sameOrigin: true,
+  pathname,
+  isNavigate: false,
+  ...over,
+});
+
+describe('classifyRequest — roms parity', () => {
+  const table: Array<[string, RequestFacts, string]> = [
+    ['non-GET is passthrough', facts('/app.js', { method: 'POST' }), 'passthrough'],
+    ['cross-origin is passthrough', facts('/app.js', { sameOrigin: false }), 'passthrough'],
+    ['/api/ is api', facts('/api/saves'), 'api'],
+    ['/api/ wins over the .json asset extension', facts('/api/library.json'), 'api'],
+    ['/api/ wins over a navigation', facts('/api/me', { isNavigate: true }), 'api'],
+    ['roms ROM bytes are passthrough (config)', facts('/_nes-roms/mario.nes'), 'passthrough'],
+    ['roms ROM path as a .json is still passthrough', facts('/_nes-roms/index.json'), 'passthrough'],
+    ['a navigation is navigate', facts('/library/nes', { isNavigate: true }), 'navigate'],
+    ['the frame document is a navigation', facts('/emulator-frame.html', { isNavigate: true }), 'navigate'],
+    ['hashed JS is an asset', facts('/assets/index-abc123.js'), 'asset'],
+    ['WASM is an asset', facts('/cores/snes9x.wasm'), 'asset'],
+    ['a font is an asset', facts('/fonts/inter.woff2'), 'asset'],
+    ['upper-case extension is an asset', facts('/icons/LOGO.PNG'), 'asset'],
+    ['an extensionless non-navigation is passthrough', facts('/healthz'), 'passthrough'],
+    ['a .nes file outside the ROM path is passthrough', facts('/other/mario.nes'), 'passthrough'],
+  ];
+  for (const [name, input, route] of table) {
+    it(name, () => expect(classifyRequest(input, ROMS)).toBe(route));
+  }
+
+  it('without the passthrough config the ROM path would be an asset — the config is what decides', () => {
+    expect(classifyRequest(facts('/_nes-roms/index.json'), {})).toBe('asset');
+  });
+
+  it('/api/ stays api even when a config lists only other API prefixes', () => {
+    expect(classifyRequest(facts('/api/me'), { apiPrefixes: ['/rpc/'] })).toBe('api');
+    expect(classifyRequest(facts('/rpc/call.json'), { apiPrefixes: ['/rpc/'] })).toBe('api');
+  });
+
+  it('a custom asset regex replaces the default', () => {
+    expect(classifyRequest(facts('/a.js'), { assetExtensions: /\.css$/ })).toBe('passthrough');
+    expect(classifyRequest(facts('/a.css'), { assetExtensions: /\.css$/ })).toBe('asset');
+  });
+});
+
+describe('shouldCache / mayFallBackToShell', () => {
+  it('caches assets and navigations, never the API or passthrough', () => {
+    expect(shouldCache('asset')).toBe(true);
+    expect(shouldCache('navigate')).toBe(true);
+    expect(shouldCache('api')).toBe(false);
+    expect(shouldCache('passthrough')).toBe(false);
+  });
+
+  it('refuses the shell to roms’ frame and allows it everywhere else', () => {
+    expect(mayFallBackToShell('/emulator-frame.html', ROMS)).toBe(false);
+    expect(mayFallBackToShell('/library/nes', ROMS)).toBe(true);
+    expect(mayFallBackToShell('/emulator-frame.html', {})).toBe(true);
+  });
+});
+
+describe('resolveShellWorkerConfig — the refusals', () => {
+  it('names the cache prefix+version and always precaches the shell', () => {
+    const resolved = resolveShellWorkerConfig({ cachePrefix: 'music-shell-', version: 'v1', precache: ['/player.js'] });
+    expect(resolved.cacheName).toBe('music-shell-v1');
+    expect(resolved.precache).toEqual(['/', '/player.js']);
+    expect(resolved.apiPrefixes).toEqual(['/api/']);
+  });
+
+  it('keeps roms’ precache as written when the shell is already listed', () => {
+    expect(resolveShellWorkerConfig(ROMS).precache).toEqual(ROMS.precache);
+  });
+
+  it('refuses an empty prefix — activate would delete every cache on the origin', () => {
+    expect(() => resolveShellWorkerConfig({ ...ROMS, cachePrefix: '' })).toThrow(/cachePrefix/);
+  });
+
+  it('refuses to precache anything under an API prefix', () => {
+    expect(() => resolveShellWorkerConfig({ ...ROMS, precache: ['/', '/api/me'] })).toThrow(/API is never cached/);
+    expect(() => resolveShellWorkerConfig({ ...ROMS, apiPrefixes: ['/rpc/'], precache: ['/rpc/x'] })).toThrow(
+      /API is never cached/,
+    );
+  });
+
+  it('refuses a relative precache entry and a shell that may not be its own fallback', () => {
+    expect(() => resolveShellWorkerConfig({ ...ROMS, precache: ['app.js'] })).toThrow(/starting with "\/"/);
+    expect(() => resolveShellWorkerConfig({ ...ROMS, noShellFallback: ['/'] })).toThrow(/noShellFallback/);
+  });
+});
+
+// ── A fake worker scope ─────────────────────────────────────────────────────────
+
+const ORIGIN = 'https://app.test';
+
+class FakeResponse implements ShellWorkerResponse {
+  constructor(
+    readonly body: string,
+    readonly ok = true,
+  ) {}
+  clone(): FakeResponse {
+    return new FakeResponse(this.body, this.ok);
+  }
+}
+
+const req = (path: string, over: Partial<ShellWorkerRequest> = {}): ShellWorkerRequest => ({
+  url: path.startsWith('http') ? path : `${ORIGIN}${path}`,
+  method: 'GET',
+  mode: 'cors',
+  ...over,
+});
+const nav = (path: string): ShellWorkerRequest => req(path, { mode: 'navigate' });
+
+const urlOf = (info: ShellWorkerRequestInfo): string =>
+  typeof info === 'string' ? new URL(info, ORIGIN).href : 'href' in info ? info.href : info.url;
+
+const stripSearch = (url: string): string => {
+  const u = new URL(url);
+  return `${u.origin}${u.pathname}`;
+};
+
+/**
+ * A worker scope backed by Maps: `server` is what the network answers when `online`,
+ * `cacheStore` is CacheStorage. Every network call and every cache write is recorded,
+ * so a test can prove a request was NEVER touched, not merely answered correctly.
+ */
+const makeWorld = () => {
+  const server = new Map<string, FakeResponse>();
+  const cacheStore = new Map<string, Map<string, FakeResponse>>();
+  const networkCalls: string[] = [];
+  const cacheWrites: string[] = [];
+  const listeners: Record<string, (event: never) => void> = {};
+  let online = true;
+  let skipped = false;
+  let claimed = false;
+
+  const network = async (url: string): Promise<FakeResponse> => {
+    networkCalls.push(url);
+    if (!online) throw new TypeError('Failed to fetch');
+    return server.get(url) ?? new FakeResponse('not found', false);
+  };
+
+  const openCache = (name: string): ShellWorkerCache => {
+    let entries = cacheStore.get(name);
+    if (!entries) {
+      entries = new Map();
+      cacheStore.set(name, entries);
+    }
+    const bucket = entries;
+    return {
+      async addAll(paths) {
+        for (const path of paths) {
+          const res = await network(`${ORIGIN}${path}`);
+          if (!res.ok) throw new TypeError(`addAll: ${path} answered not-ok`);
+          bucket.set(`${ORIGIN}${path}`, res);
+        }
+      },
+      async put(request, response) {
+        cacheWrites.push(urlOf(request));
+        bucket.set(urlOf(request), response as FakeResponse);
+      },
+    };
+  };
+
+  const scope: ShellWorkerScope = {
+    addEventListener(type: string, listener: (event: never) => void) {
+      listeners[type] = listener;
+    },
+    caches: {
+      open: async (name) => openCache(name),
+      keys: async () => [...cacheStore.keys()],
+      delete: async (name) => cacheStore.delete(name),
+      async match(request, options) {
+        const raw = urlOf(request);
+        for (const entries of cacheStore.values()) {
+          const exact = entries.get(raw);
+          if (exact) return exact;
+          if (options?.ignoreSearch) {
+            for (const [key, value] of entries) if (stripSearch(key) === stripSearch(raw)) return value;
+          }
+        }
+        return undefined;
+      },
+    },
+    clients: {
+      async claim() {
+        claimed = true;
+      },
+    },
+    location: { origin: ORIGIN },
+    fetch: (request) => network(urlOf(request)),
+    async skipWaiting() {
+      skipped = true;
+    },
+  };
+
+  const extendable = async (type: 'install' | 'activate'): Promise<void> => {
+    const waits: Promise<unknown>[] = [];
+    const event: ShellExtendableEvent = { waitUntil: (p) => void waits.push(p) };
+    (listeners[type] as (e: ShellExtendableEvent) => void)(event);
+    await Promise.all(waits);
+  };
+
+  /** Dispatch a fetch. `response` is undefined when the worker did not call respondWith. */
+  const dispatch = (request: ShellWorkerRequest) => {
+    const waits: Promise<unknown>[] = [];
+    let response: Promise<ShellWorkerResponse> | undefined;
+    const event: ShellFetchEvent = {
+      request,
+      waitUntil: (p) => void waits.push(p),
+      respondWith: (r) => {
+        response = r;
+      },
+    };
+    (listeners.fetch as (e: ShellFetchEvent) => void)(event);
+    return {
+      response,
+      /** Resolve the response, then let every deferred cache write land. */
+      settled: async () => {
+        const body = response ? await response : undefined;
+        await Promise.all(waits);
+        return body as FakeResponse | undefined;
+      },
+    };
+  };
+
+  return {
+    scope,
+    server,
+    cacheStore,
+    networkCalls,
+    cacheWrites,
+    extendable,
+    dispatch,
+    goOffline: () => {
+      online = false;
+    },
+    get skipped() {
+      return skipped;
+    },
+    get claimed() {
+      return claimed;
+    },
+  };
+};
+
+/** A roms-shaped world, installed while online. */
+const installedRoms = async () => {
+  const world = makeWorld();
+  world.server.set(`${ORIGIN}/`, new FakeResponse('<shell>'));
+  world.server.set(`${ORIGIN}/emulator-frame.html`, new FakeResponse('<frame>'));
+  world.server.set(`${ORIGIN}/emulator-runtime.js`, new FakeResponse('runtime'));
+  installShellWorker(world.scope, ROMS);
+  await world.extendable('install');
+  return world;
+};
+
+describe('installShellWorker — install and activate', () => {
+  it('precaches the configured paths into prefix+version and skips waiting', async () => {
+    const world = await installedRoms();
+    expect([...(world.cacheStore.get('roms-shell-v3')?.keys() ?? [])]).toEqual([
+      `${ORIGIN}/`,
+      `${ORIGIN}/emulator-frame.html`,
+      `${ORIGIN}/emulator-runtime.js`,
+    ]);
+    expect(world.skipped).toBe(true);
+  });
+
+  it('does not skip waiting when the precache fails — the old worker keeps serving', async () => {
+    const world = makeWorld(); // nothing on the server: addAll rejects
+    installShellWorker(world.scope, ROMS);
+    await expect(world.extendable('install')).rejects.toThrow(/answered not-ok/);
+    expect(world.skipped).toBe(false);
+  });
+
+  it('deletes old versions of its own prefix on activate, keeps everything else, and claims', async () => {
+    const world = await installedRoms();
+    world.cacheStore.set('roms-shell-v2', new Map());
+    world.cacheStore.set('roms-shell-v1', new Map());
+    world.cacheStore.set('roms-rom-digests', new Map()); // the app's own cache
+    await world.extendable('activate');
+    expect([...world.cacheStore.keys()].sort()).toEqual(['roms-rom-digests', 'roms-shell-v3']);
+    expect(world.claimed).toBe(true);
+  });
+});
+
+describe('installShellWorker — fetch', () => {
+  it('serves an online navigation from the network and caches it', async () => {
+    const world = await installedRoms();
+    world.server.set(`${ORIGIN}/library/nes`, new FakeResponse('<library>'));
+    const body = await world.dispatch(nav('/library/nes')).settled();
+    expect(body?.body).toBe('<library>');
+    expect(world.cacheWrites).toContain(`${ORIGIN}/library/nes`);
+  });
+
+  it('falls back to the SHELL for an offline navigation nothing cached', async () => {
+    const world = await installedRoms();
+    world.goOffline();
+    const body = await world.dispatch(nav('/library/snes?sort=recent')).settled();
+    expect(body?.body).toBe('<shell>');
+  });
+
+  it('answers the frame offline from its own cached copy, ignoring the query', async () => {
+    const world = await installedRoms();
+    world.goOffline();
+    const body = await world.dispatch(nav('/emulator-frame.html?system=nes')).settled();
+    expect(body?.body).toBe('<frame>');
+  });
+
+  it('🔴 never hands the SHELL to a noShellFallback path — it rejects instead (the 2026-08-12 incident)', async () => {
+    const world = makeWorld();
+    world.server.set(`${ORIGIN}/`, new FakeResponse('<shell>'));
+    // The 2026-08-12 shape: the frame is NOT precached, the shell is.
+    installShellWorker(world.scope, { ...ROMS, precache: ['/'] });
+    await world.extendable('install');
+    world.goOffline();
+    const { response } = world.dispatch(nav('/emulator-frame.html?system=nes'));
+    expect(response).toBeDefined();
+    await expect(response as Promise<ShellWorkerResponse>).rejects.toThrow('Failed to fetch');
+  });
+
+  it('rethrows the network error when offline with nothing cached at all, rather than resolving anything', async () => {
+    const world = makeWorld();
+    installShellWorker(world.scope, ROMS); // never installed: no shell in any cache
+    world.goOffline();
+    await expect(world.dispatch(nav('/library/nes')).response as Promise<ShellWorkerResponse>).rejects.toThrow(
+      'Failed to fetch',
+    );
+  });
+
+  it('serves assets cache-first and caches only an ok response', async () => {
+    const world = await installedRoms();
+    world.server.set(`${ORIGIN}/assets/app-1.js`, new FakeResponse('app'));
+    expect((await world.dispatch(req('/assets/app-1.js')).settled())?.body).toBe('app');
+    expect((await world.dispatch(req('/assets/missing.js')).settled())?.ok).toBe(false);
+    expect(world.cacheWrites).toEqual([`${ORIGIN}/assets/app-1.js`]);
+    world.goOffline();
+    const calls = world.networkCalls.length;
+    expect((await world.dispatch(req('/assets/app-1.js')).settled())?.body).toBe('app');
+    expect(world.networkCalls.length).toBe(calls); // from the cache, not the network
+  });
+
+  it('🔴 never intercepts, reads or caches /api/ — even with a stale copy planted in the cache', async () => {
+    const world = await installedRoms();
+    world.cacheStore.get('roms-shell-v3')?.set(`${ORIGIN}/api/me`, new FakeResponse('{"user":"revoked"}'));
+    for (const request of [req('/api/me'), nav('/api/me'), req('/api/library.json')]) {
+      const { response } = world.dispatch(request);
+      expect(response, `${request.url} (${request.mode}) must not be answered by the worker`).toBeUndefined();
+    }
+    world.goOffline();
+    expect(world.dispatch(req('/api/me')).response).toBeUndefined();
+    expect(world.networkCalls.filter((u) => u.includes('/api/'))).toEqual([]);
+    expect(world.cacheWrites.filter((u) => u.includes('/api/'))).toEqual([]);
+  });
+
+  it('leaves non-GET, cross-origin and passthrough-prefixed requests to the browser', async () => {
+    const world = await installedRoms();
+    for (const request of [
+      req('/assets/app.js', { method: 'POST' }),
+      req('https://cdn.other.test/lib.js'),
+      req('/_nes-roms/mario.nes'),
+      req('/healthz'),
+    ]) {
+      expect(world.dispatch(request).response, request.url).toBeUndefined();
+    }
+  });
+});

package/src/core/offline/shellWorker.ts

@@ -0,0 +1,346 @@
+/**
+ * The app-shell service worker, once, for every app that serves its shell offline
+ * (task 2073, 2026-09-22).
+ *
+ * `apps/roms` wrote this by hand as plain JS in `public/sw.js`, with a TypeScript
+ * twin in `src/offline/swRouting.ts` held in step by a comment saying "keep the two
+ * in step". `apps/music` needed the same worker, and a third hand copy is how a fix
+ * lands in one app and not the others. This module is the one body; an app's
+ * `src/sw.ts` passes a config and adds whatever is genuinely its own (background
+ * sync, an outbox, a digest-keyed media cache) as further listeners beside it.
+ *
+ * What it does, and it is deliberately all it does:
+ *  - `install`  — precache the shell and the config's `precache` list, then `skipWaiting`.
+ *  - `activate` — delete every cache named `<cachePrefix>*` that is not this version's,
+ *                 then `clients.claim()`.
+ *  - `fetch`    — same-origin static ASSETS cache-first; document NAVIGATIONS
+ *                 network-first, falling back offline to the exact URL, then the same
+ *                 path ignoring the query, then the shell. Everything else is left on
+ *                 the network: `respondWith` is never called for it.
+ *
+ * 🔴 `/api/` is NEVER cached and NEVER served from a cache. It is auth-gated, and a
+ * browser whose session has since been revoked must not read yesterday's copy of a
+ * private response out of its own cache. That is not a default a config can switch
+ * off: `apiPrefixes` ADDS prefixes to `/api/`, it cannot remove it, a precache entry
+ * under an API prefix is refused when the worker is installed, and `shouldCache`
+ * refuses to store an `api` route even if a caller asks.
+ *
+ * 🔴 `noShellFallback` exists because of the 2026-08-12 frame incident in roms. A game
+ * boots by loading `/emulator-frame.html` into a sandboxed iframe — a NAVIGATION, so it
+ * went network-first, and offline with nothing cached under that path the fallback
+ * handed it the APP SHELL. The iframe rendered a second copy of the library where the
+ * game should be: no canvas, no error, no clue. Any document that is not the shell (an
+ * iframe, a popup, a print view) must be listed there, and must be in `precache` if it
+ * is meant to work offline at all — an offline miss on it then REJECTS, which is the
+ * honest answer, rather than resolving the wrong document.
+ *
+ * Imports nothing at runtime (`leafSubpathsImportNothing.spec.ts` holds it to that):
+ * it is bundled into a service worker, where every byte ships on every install.
+ * `scope` is typed structurally so this compiles without the WebWorker lib, is testable
+ * with a fake, and still accepts the real `self` — `shellWorker.webworker.spec.ts`
+ * typechecks exactly that against `lib.webworker.d.ts`.
+ */
+
+/** Where a request goes. */
+export type ShellRoute =
+  /** A document navigation — network-first, cached-document fallback offline. */
+  | 'navigate'
+  /** A same-origin static asset (JS/CSS/WASM/font/image/JSON) — cache-first. */
+  | 'asset'
+  /** An auth-gated API call — never cached, never answered from a cache. */
+  | 'api'
+  /** Everything else (non-GET, cross-origin, `passthroughPrefixes`) — untouched. */
+  | 'passthrough';
+
+/** The facts about a request that classification reads — nothing else. */
+export interface RequestFacts {
+  method: string;
+  /** Same origin as the worker (`new URL(request.url).origin === location.origin`). */
+  sameOrigin: boolean;
+  /** URL pathname, no query. */
+  pathname: string;
+  /** `request.mode === 'navigate'`. */
+  isNavigate: boolean;
+}
+
+export interface ShellWorkerConfig {
+  /**
+   * Every cache this worker owns is named `<cachePrefix><version>`, and `activate`
+   * deletes every OTHER cache starting with `cachePrefix`. So the prefix must be one
+   * nothing else in the app shares — `roms-shell-`, not `roms-`, or the app's own
+   * digest-keyed caches go with it.
+   */
+  cachePrefix: string;
+  /** Bump to evict the previous shell on the next activate. */
+  version: string;
+  /**
+   * Same-origin paths fetched into the cache at install. `shellPath` is always
+   * precached whether listed or not — a shell fallback with no shell is no fallback.
+   */
+  precache: readonly string[];
+  /**
+   * Extra API prefixes. `/api/` is ALWAYS one of them and cannot be removed — see the
+   * header. Default: `['/api/']`.
+   */
+  apiPrefixes?: readonly string[];
+  /**
+   * Same-origin prefixes the worker must leave alone even for GET assets — e.g. roms'
+   * `/_nes-roms/`, whose bytes the app caches itself under a content digest.
+   */
+  passthroughPrefixes?: readonly string[];
+  /**
+   * Exact pathnames that must NEVER be answered with the shell offline (roms'
+   * `/emulator-frame.html`). An offline miss on one rejects instead. See the header.
+   */
+  noShellFallback?: readonly string[];
+  /** Which same-origin pathnames count as static assets. Default: `DEFAULT_ASSET_EXT`. */
+  assetExtensions?: RegExp;
+  /** The app shell's path, the navigation fallback. Default: `'/'`. */
+  shellPath?: string;
+}
+
+/** A config with every default applied and every refusal already checked. */
+export interface ResolvedShellWorkerConfig {
+  cachePrefix: string;
+  version: string;
+  cacheName: string;
+  precache: readonly string[];
+  apiPrefixes: readonly string[];
+  passthroughPrefixes: readonly string[];
+  noShellFallback: readonly string[];
+  assetExtensions: RegExp;
+  shellPath: string;
+}
+
+/** roms' `ASSET_EXT`, verbatim. */
+export const DEFAULT_ASSET_EXT = /\.(?:js|mjs|css|wasm|woff2?|ttf|png|jpe?g|webp|svg|ico|json)$/i;
+
+/** Always an API prefix, whatever the config says. */
+export const ALWAYS_API_PREFIX = '/api/';
+
+const apiPrefixesOf = (config: Pick<ShellWorkerConfig, 'apiPrefixes'>): readonly string[] => {
+  const extra = config.apiPrefixes ?? [];
+  return extra.includes(ALWAYS_API_PREFIX) ? extra : [ALWAYS_API_PREFIX, ...extra];
+};
+
+const startsWithAny = (pathname: string, prefixes: readonly string[]): boolean =>
+  prefixes.some((prefix) => pathname.startsWith(prefix));
+
+/**
+ * Classify a request. Order matters and is roms' order: non-GET and cross-origin
+ * first, then the API (so an API path that happens to end in `.json` is still `api`),
+ * then the app's own passthrough prefixes, then navigation, then assets.
+ */
+export function classifyRequest(
+  facts: RequestFacts,
+  config: Pick<ShellWorkerConfig, 'apiPrefixes' | 'passthroughPrefixes' | 'assetExtensions'> = {},
+): ShellRoute {
+  if (facts.method !== 'GET') return 'passthrough';
+  if (!facts.sameOrigin) return 'passthrough';
+  if (startsWithAny(facts.pathname, apiPrefixesOf(config))) return 'api';
+  if (startsWithAny(facts.pathname, config.passthroughPrefixes ?? [])) return 'passthrough';
+  if (facts.isNavigate) return 'navigate';
+  if ((config.assetExtensions ?? DEFAULT_ASSET_EXT).test(facts.pathname)) return 'asset';
+  return 'passthrough';
+}
+
+/** Whether a response on this route may be written to the cache. Never `api`. */
+export function shouldCache(route: ShellRoute): boolean {
+  return route === 'asset' || route === 'navigate';
+}
+
+/** May an offline miss on this navigation be answered with the shell? */
+export function mayFallBackToShell(pathname: string, config: Pick<ShellWorkerConfig, 'noShellFallback'> = {}): boolean {
+  return !(config.noShellFallback ?? []).includes(pathname);
+}
+
+/**
+ * Apply defaults and refuse the configs that would break a promise in the header.
+ * `installShellWorker` calls this; it is exported so an app's own test can prove its
+ * config is accepted without standing up a worker.
+ */
+export function resolveShellWorkerConfig(config: ShellWorkerConfig): ResolvedShellWorkerConfig {
+  if (config.cachePrefix.trim() === '') {
+    // An empty prefix makes EVERY cache on the origin "an old version of ours", and
+    // activate would delete the app's other caches with it.
+    throw new Error('shell worker: cachePrefix must not be empty — activate deletes every cache it prefixes');
+  }
+  if (config.version.trim() === '') throw new Error('shell worker: version must not be empty');
+  const shellPath = config.shellPath ?? '/';
+  const apiPrefixes = apiPrefixesOf(config);
+  const precache = config.precache.includes(shellPath) ? [...config.precache] : [shellPath, ...config.precache];
+  for (const path of precache) {
+    if (!path.startsWith('/')) {
+      throw new Error(`shell worker: precache entry "${path}" must be a same-origin path starting with "/"`);
+    }
+    if (startsWithAny(path, apiPrefixes)) {
+      throw new Error(`shell worker: precache entry "${path}" is under an API prefix — the API is never cached`);
+    }
+  }
+  if (config.noShellFallback?.includes(shellPath)) {
+    throw new Error(`shell worker: the shell path "${shellPath}" cannot also be in noShellFallback`);
+  }
+  return {
+    cachePrefix: config.cachePrefix,
+    version: config.version,
+    cacheName: `${config.cachePrefix}${config.version}`,
+    precache,
+    apiPrefixes,
+    passthroughPrefixes: config.passthroughPrefixes ?? [],
+    noShellFallback: config.noShellFallback ?? [],
+    assetExtensions: config.assetExtensions ?? DEFAULT_ASSET_EXT,
+    shellPath,
+  };
+}
+
+// ── The structural slice of ServiceWorkerGlobalScope this worker touches ──────────
+// Method syntax throughout, on purpose: TypeScript checks method parameters
+// bivariantly, which is what lets the real `self` (whose `Request`/`Response` are
+// far wider than these) satisfy them.
+
+export interface ShellWorkerRequest {
+  readonly url: string;
+  readonly method: string;
+  readonly mode: string;
+}
+
+/**
+ * The structural mirror of `RequestInfo | URL` — a request, a string, or a URL-like —
+ * which is what the real `fetch`, `Cache` and `CacheStorage` accept. It has to be the
+ * whole union: with `ShellWorkerRequest` alone the real `self` is refused, because a
+ * `URL` is not a request in either direction (measured by the webworker spec).
+ */
+export type ShellWorkerRequestInfo = ShellWorkerRequest | string | { readonly href: string };
+
+export interface ShellWorkerResponse {
+  readonly ok: boolean;
+  clone(): ShellWorkerResponse;
+}
+
+export interface ShellWorkerCache {
+  addAll(requests: string[]): Promise<void>;
+  put(request: ShellWorkerRequestInfo, response: ShellWorkerResponse): Promise<void>;
+}
+
+export interface ShellWorkerCacheStorage {
+  open(cacheName: string): Promise<ShellWorkerCache>;
+  keys(): Promise<string[]>;
+  delete(cacheName: string): Promise<boolean>;
+  match(request: ShellWorkerRequestInfo, options?: { ignoreSearch?: boolean }): Promise<ShellWorkerResponse | undefined>;
+}
+
+export interface ShellExtendableEvent {
+  waitUntil(promise: Promise<unknown>): void;
+}
+
+export interface ShellFetchEvent extends ShellExtendableEvent {
+  readonly request: ShellWorkerRequest;
+  respondWith(response: Promise<ShellWorkerResponse>): void;
+}
+
+export interface ShellWorkerScope {
+  addEventListener(type: 'install', listener: (event: ShellExtendableEvent) => void): void;
+  addEventListener(type: 'activate', listener: (event: ShellExtendableEvent) => void): void;
+  addEventListener(type: 'fetch', listener: (event: ShellFetchEvent) => void): void;
+  readonly caches: ShellWorkerCacheStorage;
+  readonly clients: { claim(): Promise<void> };
+  readonly location: { readonly origin: string };
+  fetch(request: ShellWorkerRequestInfo): Promise<ShellWorkerResponse>;
+  skipWaiting(): Promise<void>;
+}
+
+/**
+ * Wire `install`, `activate` and `fetch` onto `scope` (the worker's `self`).
+ * Returns the resolved config, so an app can read `cacheName` for its own use.
+ */
+export function installShellWorker(scope: ShellWorkerScope, config: ShellWorkerConfig): ResolvedShellWorkerConfig {
+  const resolved = resolveShellWorkerConfig(config);
+  const { caches } = scope;
+
+  // Written after the response is handed back, like roms' `cache.put` — but kept
+  // alive with `waitUntil` so the worker is not stopped mid-write, and swallowed on
+  // failure: a full quota must not turn a good network response into an error.
+  const store = (event: ShellFetchEvent, route: ShellRoute, response: ShellWorkerResponse): void => {
+    if (!shouldCache(route) || !response.ok) return;
+    const copy = response.clone();
+    event.waitUntil(
+      caches
+        .open(resolved.cacheName)
+        .then((cache) => cache.put(event.request, copy))
+        .catch(() => undefined),
+    );
+  };
+
+  const cacheFirst = async (event: ShellFetchEvent): Promise<ShellWorkerResponse> => {
+    const cached = await caches.match(event.request);
+    if (cached) return cached;
+    const response = await scope.fetch(event.request);
+    store(event, 'asset', response);
+    return response;
+  };
+
+  const networkFirst = async (event: ShellFetchEvent): Promise<ShellWorkerResponse> => {
+    const { request } = event;
+    try {
+      const response = await scope.fetch(request);
+      store(event, 'navigate', response);
+      return response;
+    } catch (error) {
+      // Offline. The exact URL first, then the same path ignoring the query — roms'
+      // frame is `/emulator-frame.html?system=nes`, and one cached copy answers for
+      // every console.
+      const cached = (await caches.match(request)) ?? (await caches.match(request, { ignoreSearch: true }));
+      if (cached) return cached;
+      if (mayFallBackToShell(new URL(request.url).pathname, resolved)) {
+        const shell = await caches.match(resolved.shellPath);
+        if (shell) return shell;
+      }
+      // Nothing honest to serve: reject, and the browser shows its own offline page
+      // rather than a document that is not the one asked for.
+      throw error;
+    }
+  };
+
+  scope.addEventListener('install', (event) => {
+    event.waitUntil(
+      caches
+        .open(resolved.cacheName)
+        .then((cache) => cache.addAll([...resolved.precache]))
+        .then(() => scope.skipWaiting()),
+    );
+  });
+
+  scope.addEventListener('activate', (event) => {
+    event.waitUntil(
+      caches
+        .keys()
+        .then((keys) =>
+          Promise.all(
+            keys
+              .filter((key) => key.startsWith(resolved.cachePrefix) && key !== resolved.cacheName)
+              .map((key) => caches.delete(key)),
+          ),
+        )
+        .then(() => scope.clients.claim()),
+    );
+  });
+
+  scope.addEventListener('fetch', (event) => {
+    const url = new URL(event.request.url);
+    const route = classifyRequest(
+      {
+        method: event.request.method,
+        sameOrigin: url.origin === scope.location.origin,
+        pathname: url.pathname,
+        isNavigate: event.request.mode === 'navigate',
+      },
+      resolved,
+    );
+    if (route === 'asset') event.respondWith(cacheFirst(event));
+    else if (route === 'navigate') event.respondWith(networkFirst(event));
+    // `api` and `passthrough`: no respondWith, so the browser goes to the network as
+    // if this worker did not exist. Never a cache read, never a cache write.
+  });
+
+  return resolved;
+}

package/src/core/offline/shellWorker.webworker.spec.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'bun:test';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * `ShellWorkerScope` is structural so the module typechecks without the WebWorker lib
+ * and can be tested with a fake. The promise that makes that worth anything is the
+ * other half: an app's `src/sw.ts` passes the REAL `self` and it must compile. Nothing
+ * in this repo's own tsconfig can see that (it carries lib DOM, not WebWorker), so this
+ * spec typechecks a two-file fixture against `lib.webworker.d.ts` with no DOM at all:
+ *
+ *  - `sw.ts`       passes a `ServiceWorkerGlobalScope` — must be clean;
+ *  - `control.ts`  passes a scope with no `caches` — must be RED, or tsc was not
+ *                  checking anything and the clean result above is vacuous.
+ *
+ * It also proves `shellWorker.ts` itself compiles with no DOM lib, which is the lib a
+ * service-worker build has.
+ */
+const REPO = fileURLToPath(new URL('../../..', import.meta.url));
+const SOURCE = fileURLToPath(new URL('./shellWorker.ts', import.meta.url));
+
+const typecheck = async (): Promise<string> => {
+  const root = `${process.env.TMPDIR ?? '/tmp'}/shell-worker-webworker-${process.pid}`;
+  // Bun.write, NOT node:fs — this repo's test preload virtualizes node:fs, and the
+  // spawned tsc would read a directory the mock never wrote.
+  await Bun.write(
+    `${root}/tsconfig.json`,
+    JSON.stringify({
+      compilerOptions: {
+        target: 'ESNext',
+        module: 'ESNext',
+        moduleResolution: 'bundler',
+        lib: ['ESNext', 'WebWorker'],
+        types: [],
+        strict: true,
+        noEmit: true,
+        skipLibCheck: true,
+        allowImportingTsExtensions: true,
+      },
+      files: ['sw.ts', 'control.ts'],
+    }),
+  );
+  await Bun.write(
+    `${root}/sw.ts`,
+    `import { installShellWorker } from ${JSON.stringify(SOURCE)};
+declare const sw: ServiceWorkerGlobalScope;
+installShellWorker(sw, { cachePrefix: 'app-shell-', version: 'v1', precache: ['/'] });
+`,
+  );
+  await Bun.write(
+    `${root}/control.ts`,
+    `import { installShellWorker } from ${JSON.stringify(SOURCE)};
+declare const sw: ServiceWorkerGlobalScope;
+const { caches: _dropped, ...noCaches } = sw;
+installShellWorker(noCaches, { cachePrefix: 'app-shell-', version: 'v1', precache: ['/'] });
+`,
+  );
+  const child = Bun.spawnSync([process.execPath, `${REPO}/node_modules/typescript/bin/tsc`, '-p', root], {
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  return `${child.stdout.toString()}${child.stderr.toString()}`;
+};
+
+const output = await typecheck();
+const errorsIn = (file: string): string[] =>
+  output.split('\n').filter((line) => line.includes(`${file}(`) && line.includes('error TS'));
+
+describe('shell worker against lib.webworker', () => {
+  it('rejects a scope with no caches (negative control — tsc really checked)', () => {
+    const control = errorsIn('control.ts');
+    expect(control.length, `tsc output:\n${output}`).toBeGreaterThan(0);
+    // Red for the RIGHT reason — the missing member, not a broken fixture.
+    expect(output, `tsc output:\n${output}`).toContain("Property 'caches' is missing");
+  });
+
+  it('accepts the real ServiceWorkerGlobalScope, and the module compiles without DOM', () => {
+    expect(errorsIn('sw.ts'), `tsc output:\n${output}`).toEqual([]);
+    expect(errorsIn('shellWorker.ts'), `tsc output:\n${output}`).toEqual([]);
+  });
+});

package/src/leafSubpathsImportNothing.spec.ts

@@ -108,6 +108,11 @@ const LEAVES = [
     /** Wire-format types + the method⇄abbreviation maps. Trivially isomorphic on purpose. */
     evaluates: 'METHOD_TO_ABBREV',
   },
+  {
+    subpath: './offline/shell-worker',
+    /** Bundled into an app's service worker, where every byte ships on every install. */
+    evaluates: 'installShellWorker',
+  },
 ] as const;
 
 /**