cursedbelt-core 2.7.0 → 2.9.0

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

@@ -13,7 +13,9 @@
  *  - `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
+ *  - `fetch`    — same-origin static ASSETS: cache-first when the NAME carries a content
+ *                 hash, otherwise revalidated with the network and the cache as the
+ *                 offline fallback (see {@link isContentHashed}); 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.
@@ -44,7 +46,7 @@
 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. */
+/** A same-origin static asset (JS/CSS/WASM/font/image/JSON) — cache-first if content-hashed, else revalidated. */
  | 'asset'
 /** An auth-gated API call — never cached, never answered from a cache. */
  | 'api'
@@ -110,6 +112,23 @@ export interface ResolvedShellWorkerConfig {
 /** roms' `ASSET_EXT`, verbatim. */
 export declare const DEFAULT_ASSET_EXT: RegExp;
 /** Always an API prefix, whatever the config says. */
+/**
+ * A built file whose NAME carries its content hash — Vite's `index-BcHBclrL.js` — so
+ * the bytes under that name can never change, and cache-first is exact.
+ *
+ * 🔴 Every other asset is REVALIDATED (network, then the cache when offline), because
+ * cache-first on a fixed name is "the first copy this device ever saw, for ever":
+ * the cache is named by `version`, which an app bumps by hand, and nothing else
+ * evicts an entry. Measured on roms 2026-09-27: its emulator cores
+ * (`/vendor/cores/melonds_libretro.js`) and frame runtime (`/emulator-runtime.js`)
+ * are fixed names under a `v4` cache, so the DS audio fix deployed that day — and
+ * every core or runtime fix before it — could never reach a device that had already
+ * played the console. The edge answers those names `no-cache` with an ETag, so a
+ * revalidation is a 304 and no body.
+ */
+export declare const CONTENT_HASHED_NAME: RegExp;
+/** Whether this pathname's last segment is a content-hashed build output. */
+export declare function isContentHashed(pathname: string): boolean;
 export declare const ALWAYS_API_PREFIX = "/api/";
 /**
  * Classify a request. Order matters and is roms' order: non-GET and cross-origin

package/dist/core/offline/shellWorker.js

@@ -13,7 +13,9 @@
  *  - `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
+ *  - `fetch`    — same-origin static ASSETS: cache-first when the NAME carries a content
+ *                 hash, otherwise revalidated with the network and the cache as the
+ *                 offline fallback (see {@link isContentHashed}); 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.
@@ -43,6 +45,25 @@
 /** 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. */
+/**
+ * A built file whose NAME carries its content hash — Vite's `index-BcHBclrL.js` — so
+ * the bytes under that name can never change, and cache-first is exact.
+ *
+ * 🔴 Every other asset is REVALIDATED (network, then the cache when offline), because
+ * cache-first on a fixed name is "the first copy this device ever saw, for ever":
+ * the cache is named by `version`, which an app bumps by hand, and nothing else
+ * evicts an entry. Measured on roms 2026-09-27: its emulator cores
+ * (`/vendor/cores/melonds_libretro.js`) and frame runtime (`/emulator-runtime.js`)
+ * are fixed names under a `v4` cache, so the DS audio fix deployed that day — and
+ * every core or runtime fix before it — could never reach a device that had already
+ * played the console. The edge answers those names `no-cache` with an ETag, so a
+ * revalidation is a 304 and no body.
+ */
+export const CONTENT_HASHED_NAME = /-[A-Za-z0-9_-]{8,}\.[A-Za-z0-9]+$/;
+/** Whether this pathname's last segment is a content-hashed build output. */
+export function isContentHashed(pathname) {
+    return CONTENT_HASHED_NAME.test(pathname);
+}
 export const ALWAYS_API_PREFIX = '/api/';
 const apiPrefixesOf = (config) => {
     const extra = config.apiPrefixes ?? [];
@@ -143,6 +164,26 @@ export function installShellWorker(scope, config) {
         store(event, 'asset', response);
         return response;
     };
+    // A fixed-name asset: the network's answer when it has a good one (stored for
+    // offline), else the cached copy — offline, or an edge error — else whatever the
+    // network said. Never the cache first: see `isContentHashed`.
+    const revalidate = async (event) => {
+        let response;
+        try {
+            response = await scope.fetch(event.request);
+        }
+        catch (error) {
+            const cached = await caches.match(event.request);
+            if (cached)
+                return cached;
+            throw error;
+        }
+        if (response.ok) {
+            store(event, 'asset', response);
+            return response;
+        }
+        return (await caches.match(event.request)) ?? response;
+    };
     const networkFirst = async (event) => {
         const { request } = event;
         try {
@@ -190,7 +231,7 @@ export function installShellWorker(scope, config) {
             isNavigate: event.request.mode === 'navigate',
         }, resolved);
         if (route === 'asset')
-            event.respondWith(cacheFirst(event));
+            event.respondWith(isContentHashed(url.pathname) ? cacheFirst(event) : revalidate(event));
         else if (route === 'navigate')
             event.respondWith(networkFirst(event));
         // `api` and `passthrough`: no respondWith, so the browser goes to the network as

package/dist/ctgrClient/convertRequest.d.ts

@@ -0,0 +1,18 @@
+/** One converted request ready for `fetch`: the GET-twin path + the GET init. */
+export interface CtgrFetchRequest {
+    /** `/ctgr<xx><path>?<params>` — a path; the caller prepends any API prefix. */
+    url: string;
+    init: RequestInit;
+}
+/**
+ * Convert one request for the tunnel. Returns the chunked GET requests to send in
+ * order (usually one); when the mode is off, or it is already a body-less GET, the
+ * original request passes through unchanged as a single entry.
+ *
+ * `formData` may be passed explicitly, or left off and put on `init.body` (the shape
+ * a typed client already uses) — an `init.body` that is a `FormData` is detected and
+ * serialized the same way.
+ */
+export declare function convertIfOnlyGETRequests(url: string, init?: RequestInit, formData?: FormData): Promise<{
+    requests: CtgrFetchRequest[];
+}>;

package/dist/ctgrClient/convertRequest.js

@@ -0,0 +1,98 @@
+/*
+ * The browser half of the GET-only tunnel. When the mode is on, a mutating request
+ * is rewritten into one or more `/ctgr<xx>` GET twins via the isomorphic codec (gzip
+ * + single base64url + integrity); a plain GET passes through untouched. FormData
+ * uploads are serialized into the JSON body's `__files` shape (the server
+ * reconstructs the uploads from it). When the mode is off, every request passes
+ * through unchanged.
+ */
+import { encodeRequest, METHOD_TO_ABBREV, toBase64, } from '../ctgr/index.js';
+import { isCtgrModeOn } from './ctgrConfig.js';
+// 10 MB per-file cap for GET-only mode. base64 + URL transport inflates each file and
+// needs many sequential GETs per MB; beyond this the upload hangs/OOMs on mobile.
+const CTGR_MAX_FILE_BYTES = 10 * 1024 * 1024;
+const SAFE_METHODS = new Set(['GET', 'HEAD']);
+/**
+ * Convert one request for the tunnel. Returns the chunked GET requests to send in
+ * order (usually one); when the mode is off, or it is already a body-less GET, the
+ * original request passes through unchanged as a single entry.
+ *
+ * `formData` may be passed explicitly, or left off and put on `init.body` (the shape
+ * a typed client already uses) — an `init.body` that is a `FormData` is detected and
+ * serialized the same way.
+ */
+export async function convertIfOnlyGETRequests(url, init = { method: 'GET' }, formData) {
+    const form = formData ??
+        (typeof FormData !== 'undefined' && init.body instanceof FormData ? init.body : undefined);
+    const method = (init.method ?? (form ? 'POST' : 'GET')).toUpperCase();
+    if (!isCtgrModeOn() || (SAFE_METHODS.has(method) && !form)) {
+        return { requests: [{ url, init }] };
+    }
+    const upper = method;
+    if (!METHOD_TO_ABBREV[upper]) {
+        throw new Error(`ctgr: "${method}" is not a tunnelable method`);
+    }
+    const body = form ? await formDataToBody(form) : bodyFromInit(init.body);
+    const getInit = toGetInit(init);
+    const { chunks } = await encodeRequest(upper, url, body);
+    return { requests: chunks.map((chunk) => ({ url: chunk.url, init: getInit })) };
+}
+/** Turn a FormData upload into the `__files` JSON body shape the GET path carries. */
+async function formDataToBody(formData) {
+    const files = [];
+    const fields = {};
+    for (const [key, value] of formData.entries()) {
+        if (typeof value === 'object' && value !== null && 'arrayBuffer' in value) {
+            const file = value;
+            if (file.size > CTGR_MAX_FILE_BYTES) {
+                throw new Error(`"${file.name}" (${Math.round(file.size / 1024 / 1024)} MB) is too large to upload in ` +
+                    `GET-only mode`);
+            }
+            files.push({
+                field: key,
+                name: file.name,
+                type: file.type,
+                dataBase64: toBase64(new Uint8Array(await file.arrayBuffer())),
+            });
+        }
+        else {
+            fields[key] = String(value);
+        }
+    }
+    return { __files: files, ...fields };
+}
+/** The request body as a JS value: a JSON string is parsed; anything else passes through. */
+function bodyFromInit(body) {
+    if (typeof body !== 'string')
+        return body ?? undefined;
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return body;
+    }
+}
+/** A GET copy of the init: no body, and the now-meaningless content-type dropped. */
+function toGetInit(init) {
+    const next = { ...init, method: 'GET', headers: stripContentType(init.headers) };
+    delete next.body;
+    return next;
+}
+function stripContentType(headers) {
+    if (!headers)
+        return headers;
+    if (headers instanceof Headers) {
+        const next = new Headers(headers);
+        next.delete('content-type');
+        return next;
+    }
+    if (Array.isArray(headers)) {
+        return headers.filter(([key]) => key.toLowerCase() !== 'content-type');
+    }
+    const next = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() !== 'content-type')
+            next[key] = value;
+    }
+    return next;
+}

package/dist/ctgrClient/ctgrConfig.d.ts

@@ -0,0 +1,23 @@
+export declare const isCtgrModeOn: () => boolean;
+export declare const setCtgrMode: (on: boolean) => void;
+/**
+ * The state a `ctgr` query value asks for: on, off, or (unknown/absent) leave the
+ * device as it is. Pure — no storage, no DOM — so it is trivially testable and the
+ * one place the accepted spellings live.
+ */
+export declare const readCtgrIntent: (value: string | null | undefined) => "on" | "off" | "keep";
+/**
+ * Apply a `ctgr` query value to this device's persisted mode and report whether the
+ * mode is on afterwards. Called by `applyCtgrFromLocation` with the value read off
+ * the URL; exposed on its own so a host that already parsed its query can reuse it.
+ */
+export declare const applyCtgrIntent: (value: string | null | undefined) => boolean;
+/**
+ * Boot hook: read `?ctgr=…` off the current location (or a supplied search string /
+ * URL), persist the change for this device, and return whether the mode is on. Safe
+ * to call with no argument in the browser; returns `false` with no `window`.
+ *
+ * Call this ONCE, before the app issues its first request — pairing it with
+ * `installCtgrGuard()` so a request made during that first tick is still caught.
+ */
+export declare const applyCtgrFromLocation: (search?: string) => boolean;

package/dist/ctgrClient/ctgrConfig.js

@@ -0,0 +1,94 @@
+/*
+ * Single source of truth for GET-only request mode. When on, the request layer
+ * rewrites every mutating call to a GET (see `convertIfOnlyGETRequests`) and the
+ * network-boundary guard hard-blocks any raw non-GET. Both read this one flag, so
+ * they can never disagree.
+ *
+ * The mode is per-DEVICE, persisted in localStorage so it survives reloads and is
+ * never tied to an account — a device that has it on keeps it on, a device that does
+ * not never gains it. Default is OFF.
+ *
+ * A site sets it up front, before its first request, by reading the URL:
+ *   • `?ctgr=t` (or `on`/`1`/`yes`)  → turn on, persist for this device.
+ *   • `?ctgr=f` (or `off`/`0`/`no`)  → turn off, clear it for this device.
+ *   • no `ctgr` param               → whatever this device already had.
+ * `applyCtgrFromLocation()` is the one call that does this on boot.
+ */
+const CTGR_KEY = 'ctgr';
+const ON_VALUES = new Set(['t', 'on', '1', 'yes', 'true']);
+const OFF_VALUES = new Set(['f', 'off', '0', 'no', 'false']);
+export const isCtgrModeOn = () => {
+    try {
+        return localStorage.getItem(CTGR_KEY) === 'on';
+    }
+    catch {
+        return false;
+    }
+};
+export const setCtgrMode = (on) => {
+    try {
+        if (on)
+            localStorage.setItem(CTGR_KEY, 'on');
+        else
+            localStorage.removeItem(CTGR_KEY);
+    }
+    catch {
+        // localStorage unavailable (private mode / SSR) — nothing to persist.
+    }
+};
+/**
+ * The state a `ctgr` query value asks for: on, off, or (unknown/absent) leave the
+ * device as it is. Pure — no storage, no DOM — so it is trivially testable and the
+ * one place the accepted spellings live.
+ */
+export const readCtgrIntent = (value) => {
+    if (value == null)
+        return 'keep';
+    const v = value.trim().toLowerCase();
+    if (ON_VALUES.has(v))
+        return 'on';
+    if (OFF_VALUES.has(v))
+        return 'off';
+    return 'keep';
+};
+/**
+ * Apply a `ctgr` query value to this device's persisted mode and report whether the
+ * mode is on afterwards. Called by `applyCtgrFromLocation` with the value read off
+ * the URL; exposed on its own so a host that already parsed its query can reuse it.
+ */
+export const applyCtgrIntent = (value) => {
+    const intent = readCtgrIntent(value);
+    if (intent === 'on')
+        setCtgrMode(true);
+    else if (intent === 'off')
+        setCtgrMode(false);
+    return isCtgrModeOn();
+};
+/**
+ * Boot hook: read `?ctgr=…` off the current location (or a supplied search string /
+ * URL), persist the change for this device, and return whether the mode is on. Safe
+ * to call with no argument in the browser; returns `false` with no `window`.
+ *
+ * Call this ONCE, before the app issues its first request — pairing it with
+ * `installCtgrGuard()` so a request made during that first tick is still caught.
+ */
+export const applyCtgrFromLocation = (search) => {
+    let query = search;
+    if (query === undefined) {
+        if (typeof window === 'undefined' || !window.location)
+            return isCtgrModeOn();
+        query = window.location.search;
+    }
+    let value = null;
+    try {
+        // Accept a bare search (`?ctgr=t`), a full href, or already-extracted params.
+        const params = query.includes('://')
+            ? new URL(query).searchParams
+            : new URLSearchParams(query.startsWith('?') ? query.slice(1) : query);
+        value = params.get(CTGR_KEY);
+    }
+    catch {
+        value = null;
+    }
+    return applyCtgrIntent(value);
+};

package/dist/ctgrClient/ctgrGuard.d.ts

@@ -0,0 +1 @@
+export declare const installCtgrGuard: () => void;

package/dist/ctgrClient/ctgrGuard.js

@@ -0,0 +1,83 @@
+/*
+ * Safety net for GET-only mode. Even though the request layer is supposed to rewrite
+ * every mutating call to a GET (`convertIfOnlyGETRequests`), this guard sits at the
+ * actual network boundary and hard-blocks any non-GET request to our own API surface
+ * when the mode is on — so a code path that forgot to run through the converter can
+ * never put a raw POST/PUT/PATCH/DELETE on the wire. Catches both `fetch` and
+ * `XMLHttpRequest`. It only ever tightens; it must never weaken.
+ */
+import { isCtgrModeOn } from './ctgrConfig.js';
+// Methods that never mutate and are always safe to allow.
+const SAFE_METHODS = new Set(['GET', 'HEAD']);
+const urlOf = (input) => {
+    if (typeof input === 'string')
+        return input;
+    if (input instanceof URL)
+        return input.href;
+    if (input instanceof Request)
+        return input.url;
+    return String(input);
+};
+// Only guard our OWN API surface — same-origin AND under a path the request layer
+// owns (`/api/…` or a `/ctgr<xx>` twin). Restricting to these prefixes (rather than
+// "any same-origin path") matters: same-origin also covers paths we do not own, like
+// Cloudflare's `/cdn-cgi/rum` beacon, which fires a raw POST on every page view —
+// guarding it would break RUM and fire for every ordinary visitor, not just a
+// misbehaving call site.
+const isGuardedPath = (rawUrl) => {
+    let path;
+    if (rawUrl.startsWith('/')) {
+        path = rawUrl;
+    }
+    else {
+        try {
+            const u = new URL(rawUrl, window.location.href);
+            if (u.origin !== window.location.origin)
+                return false;
+            path = u.pathname;
+        }
+        catch {
+            return false;
+        }
+    }
+    return path.startsWith('/api/') || path.startsWith('/ctgr');
+};
+// Deliberately generic: this message can reach the console of ANY visitor, so it says
+// nothing about the request layer, the call site, or what a blocked request was.
+const block = () => {
+    const message = 'Service unavailable.';
+    console.error(message, new Error('blocked request'));
+    return new Error(message);
+};
+let installed = false;
+export const installCtgrGuard = () => {
+    if (installed || typeof window === 'undefined')
+        return;
+    installed = true;
+    // ── fetch ──────────────────────────────────────────────────────────────────
+    if (typeof window.fetch === 'function') {
+        const originalFetch = window.fetch.bind(window);
+        const guardedFetch = (input, init) => {
+            const method = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();
+            const url = urlOf(input);
+            if (isCtgrModeOn() && !SAFE_METHODS.has(method) && isGuardedPath(url)) {
+                return Promise.reject(block());
+            }
+            return originalFetch(input, init);
+        };
+        window.fetch = guardedFetch;
+    }
+    // ── XMLHttpRequest ───────────────────────────────────────────────────────────
+    if (typeof XMLHttpRequest !== 'undefined') {
+        const originalOpen = XMLHttpRequest.prototype.open;
+        // biome-ignore lint/suspicious/noExplicitAny: matching XHR.open's variadic overloads
+        XMLHttpRequest.prototype.open = function open(method, url, ...rest) {
+            const upper = String(method).toUpperCase();
+            if (isCtgrModeOn() && !SAFE_METHODS.has(upper) && isGuardedPath(String(url))) {
+                throw block();
+            }
+            // biome-ignore lint/suspicious/noExplicitAny: forwarding the original variadic call
+            return originalOpen.call(this, method, url, ...rest);
+        };
+    }
+};

package/dist/ctgrClient/index.d.ts

@@ -0,0 +1,3 @@
+export { applyCtgrFromLocation, applyCtgrIntent, isCtgrModeOn, readCtgrIntent, setCtgrMode, } from './ctgrConfig.js';
+export { type CtgrFetchRequest, convertIfOnlyGETRequests } from './convertRequest.js';
+export { installCtgrGuard } from './ctgrGuard.js';

package/dist/ctgrClient/index.js

@@ -0,0 +1,15 @@
+/*
+ * cursedbelt-core/ctgr-client — the browser adapters that turn any site into a
+ * GET-only client:
+ *   • the per-device mode flag + the `?ctgr=t|f` boot toggle (`ctgrConfig`),
+ *   • the request converter that rewrites a mutation into `/ctgr<xx>` GET twins,
+ *   • the network-boundary guard that blocks a stray raw verb.
+ *
+ * The wire codec is `cursedbelt-core/ctgr`; the server that decodes the twins is
+ * `cursedbelt-server` (`mountCtgrTunnel`). A site opts in with two boot calls —
+ * `applyCtgrFromLocation()` then `installCtgrGuard()` — and routes its requests
+ * through `convertIfOnlyGETRequests`.
+ */
+export { applyCtgrFromLocation, applyCtgrIntent, isCtgrModeOn, readCtgrIntent, setCtgrMode, } from './ctgrConfig.js';
+export { convertIfOnlyGETRequests } from './convertRequest.js';
+export { installCtgrGuard } from './ctgrGuard.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-core",
-	"version": "2.7.0",
+	"version": "2.9.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.",
@@ -371,6 +371,12 @@
 			"bun": "./src/client/wsWire.ts",
 			"source": "./src/client/wsWire.ts",
 			"import": "./dist/client/wsWire.js"
+		},
+		"./ctgr-client": {
+			"types": "./dist/ctgrClient/index.d.ts",
+			"bun": "./src/ctgrClient/index.ts",
+			"source": "./src/ctgrClient/index.ts",
+			"import": "./dist/ctgrClient/index.js"
 		}
 	},
 	"dependencies": {

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

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'bun:test';
 import {
   classifyRequest,
   installShellWorker,
+  isContentHashed,
   mayFallBackToShell,
   type RequestFacts,
   resolveShellWorkerConfig,
@@ -353,16 +354,50 @@ describe('installShellWorker — fetch', () => {
     );
   });
 
-  it('serves assets cache-first and caches only an ok response', async () => {
+  it('serves CONTENT-HASHED 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();
+    world.server.set(`${ORIGIN}/assets/app-BcHBclrL.js`, new FakeResponse('app'));
+    expect((await world.dispatch(req('/assets/app-BcHBclrL.js')).settled())?.body).toBe('app');
+    expect((await world.dispatch(req('/assets/missing-DeadBeef.js')).settled())?.ok).toBe(false);
+    expect(world.cacheWrites).toEqual([`${ORIGIN}/assets/app-BcHBclrL.js`]);
     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
+    expect((await world.dispatch(req('/assets/app-BcHBclrL.js')).settled())?.body).toBe('app');
+    expect(world.networkCalls.length).toBe(calls); // from the cache, not the network — even online
+  });
+
+  it('🔴 a FIXED-NAME asset reaches the device when its bytes change — the roms core that never updated (2026-09-27)', async () => {
+    const world = await installedRoms();
+    const core = `${ORIGIN}/vendor/cores/melonds_libretro.js`;
+    world.server.set(core, new FakeResponse('old driver'));
+    expect((await world.dispatch(req('/vendor/cores/melonds_libretro.js')).settled())?.body).toBe('old driver');
+    world.server.set(core, new FakeResponse('new driver')); // a deploy
+    expect((await world.dispatch(req('/vendor/cores/melonds_libretro.js')).settled())?.body).toBe('new driver');
+    // …and the runtime precached at install is refreshed the same way.
+    world.server.set(`${ORIGIN}/emulator-runtime.js`, new FakeResponse('runtime 2'));
+    expect((await world.dispatch(req('/emulator-runtime.js')).settled())?.body).toBe('runtime 2');
+    // Offline, the LATEST copy answers, not the first one.
+    world.goOffline();
+    expect((await world.dispatch(req('/vendor/cores/melonds_libretro.js')).settled())?.body).toBe('new driver');
+    expect((await world.dispatch(req('/emulator-runtime.js')).settled())?.body).toBe('runtime 2');
+  });
+
+  it('a fixed-name asset the edge errors on is served from the cache; with no copy, the error stands', async () => {
+    const world = await installedRoms();
+    world.server.set(`${ORIGIN}/controller-ds.webp`, new FakeResponse('pad'));
+    await world.dispatch(req('/controller-ds.webp')).settled();
+    world.server.set(`${ORIGIN}/controller-ds.webp`, new FakeResponse('bad gateway', false));
+    expect((await world.dispatch(req('/controller-ds.webp')).settled())?.body).toBe('pad');
+    expect((await world.dispatch(req('/favicon.svg')).settled())?.ok).toBe(false);
+    world.goOffline();
+    await expect(world.dispatch(req('/favicon.svg')).response as Promise<ShellWorkerResponse>).rejects.toThrow('Failed to fetch');
+  });
+
+  it('isContentHashed: Vite names are, fixed names are not', () => {
+    expect(isContentHashed('/assets/index-BcHBclrL.js')).toBe(true);
+    expect(isContentHashed('/assets/ps2-C7Rs0q_e.css')).toBe(true);
+    expect(isContentHashed('/vendor/cores/melonds_libretro.wasm')).toBe(false);
+    expect(isContentHashed('/emulator-runtime.js')).toBe(false);
+    expect(isContentHashed('/controller-ds.webp')).toBe(false);
   });
 
   it('🔴 never intercepts, reads or caches /api/ — even with a stale copy planted in the cache', async () => {

package/src/core/offline/shellWorker.ts

@@ -13,7 +13,9 @@
  *  - `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
+ *  - `fetch`    — same-origin static ASSETS: cache-first when the NAME carries a content
+ *                 hash, otherwise revalidated with the network and the cache as the
+ *                 offline fallback (see {@link isContentHashed}); 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.
@@ -45,7 +47,7 @@
 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. */
+  /** A same-origin static asset (JS/CSS/WASM/font/image/JSON) — cache-first if content-hashed, else revalidated. */
   | 'asset'
   /** An auth-gated API call — never cached, never answered from a cache. */
   | 'api'
@@ -116,6 +118,27 @@ export interface ResolvedShellWorkerConfig {
 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. */
+/**
+ * A built file whose NAME carries its content hash — Vite's `index-BcHBclrL.js` — so
+ * the bytes under that name can never change, and cache-first is exact.
+ *
+ * 🔴 Every other asset is REVALIDATED (network, then the cache when offline), because
+ * cache-first on a fixed name is "the first copy this device ever saw, for ever":
+ * the cache is named by `version`, which an app bumps by hand, and nothing else
+ * evicts an entry. Measured on roms 2026-09-27: its emulator cores
+ * (`/vendor/cores/melonds_libretro.js`) and frame runtime (`/emulator-runtime.js`)
+ * are fixed names under a `v4` cache, so the DS audio fix deployed that day — and
+ * every core or runtime fix before it — could never reach a device that had already
+ * played the console. The edge answers those names `no-cache` with an ETag, so a
+ * revalidation is a 304 and no body.
+ */
+export const CONTENT_HASHED_NAME = /-[A-Za-z0-9_-]{8,}\.[A-Za-z0-9]+$/;
+
+/** Whether this pathname's last segment is a content-hashed build output. */
+export function isContentHashed(pathname: string): boolean {
+  return CONTENT_HASHED_NAME.test(pathname);
+}
+
 export const ALWAYS_API_PREFIX = '/api/';
 
 const apiPrefixesOf = (config: Pick<ShellWorkerConfig, 'apiPrefixes'>): readonly string[] => {
@@ -279,6 +302,25 @@ export function installShellWorker(scope: ShellWorkerScope, config: ShellWorkerC
     return response;
   };
 
+  // A fixed-name asset: the network's answer when it has a good one (stored for
+  // offline), else the cached copy — offline, or an edge error — else whatever the
+  // network said. Never the cache first: see `isContentHashed`.
+  const revalidate = async (event: ShellFetchEvent): Promise<ShellWorkerResponse> => {
+    let response: ShellWorkerResponse;
+    try {
+      response = await scope.fetch(event.request);
+    } catch (error) {
+      const cached = await caches.match(event.request);
+      if (cached) return cached;
+      throw error;
+    }
+    if (response.ok) {
+      store(event, 'asset', response);
+      return response;
+    }
+    return (await caches.match(event.request)) ?? response;
+  };
+
   const networkFirst = async (event: ShellFetchEvent): Promise<ShellWorkerResponse> => {
     const { request } = event;
     try {
@@ -336,7 +378,7 @@ export function installShellWorker(scope: ShellWorkerScope, config: ShellWorkerC
       },
       resolved,
     );
-    if (route === 'asset') event.respondWith(cacheFirst(event));
+    if (route === 'asset') event.respondWith(isContentHashed(url.pathname) ? cacheFirst(event) : revalidate(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.

package/src/ctgrClient/convertRequest.ts

@@ -0,0 +1,123 @@
+/*
+ * The browser half of the GET-only tunnel. When the mode is on, a mutating request
+ * is rewritten into one or more `/ctgr<xx>` GET twins via the isomorphic codec (gzip
+ * + single base64url + integrity); a plain GET passes through untouched. FormData
+ * uploads are serialized into the JSON body's `__files` shape (the server
+ * reconstructs the uploads from it). When the mode is off, every request passes
+ * through unchanged.
+ */
+import {
+  type CtgrMethod,
+  encodeRequest,
+  METHOD_TO_ABBREV,
+  type SerializedFile,
+  toBase64,
+} from '../ctgr/index.js';
+import { isCtgrModeOn } from './ctgrConfig.js';
+
+/** One converted request ready for `fetch`: the GET-twin path + the GET init. */
+export interface CtgrFetchRequest {
+  /** `/ctgr<xx><path>?<params>` — a path; the caller prepends any API prefix. */
+  url: string;
+  init: RequestInit;
+}
+
+// 10 MB per-file cap for GET-only mode. base64 + URL transport inflates each file and
+// needs many sequential GETs per MB; beyond this the upload hangs/OOMs on mobile.
+const CTGR_MAX_FILE_BYTES = 10 * 1024 * 1024;
+
+const SAFE_METHODS = new Set(['GET', 'HEAD']);
+
+/**
+ * Convert one request for the tunnel. Returns the chunked GET requests to send in
+ * order (usually one); when the mode is off, or it is already a body-less GET, the
+ * original request passes through unchanged as a single entry.
+ *
+ * `formData` may be passed explicitly, or left off and put on `init.body` (the shape
+ * a typed client already uses) — an `init.body` that is a `FormData` is detected and
+ * serialized the same way.
+ */
+export async function convertIfOnlyGETRequests(
+  url: string,
+  init: RequestInit = { method: 'GET' },
+  formData?: FormData,
+): Promise<{ requests: CtgrFetchRequest[] }> {
+  const form =
+    formData ??
+    (typeof FormData !== 'undefined' && init.body instanceof FormData ? init.body : undefined);
+  const method = (init.method ?? (form ? 'POST' : 'GET')).toUpperCase();
+
+  if (!isCtgrModeOn() || (SAFE_METHODS.has(method) && !form)) {
+    return { requests: [{ url, init }] };
+  }
+
+  const upper = method as CtgrMethod;
+  if (!METHOD_TO_ABBREV[upper]) {
+    throw new Error(`ctgr: "${method}" is not a tunnelable method`);
+  }
+
+  const body: unknown = form ? await formDataToBody(form) : bodyFromInit(init.body);
+  const getInit = toGetInit(init);
+  const { chunks } = await encodeRequest(upper, url, body);
+  return { requests: chunks.map((chunk) => ({ url: chunk.url, init: getInit })) };
+}
+
+/** Turn a FormData upload into the `__files` JSON body shape the GET path carries. */
+async function formDataToBody(formData: FormData): Promise<Record<string, unknown>> {
+  const files: SerializedFile[] = [];
+  const fields: Record<string, string> = {};
+  for (const [key, value] of formData.entries()) {
+    if (typeof value === 'object' && value !== null && 'arrayBuffer' in value) {
+      const file = value as File;
+      if (file.size > CTGR_MAX_FILE_BYTES) {
+        throw new Error(
+          `"${file.name}" (${Math.round(file.size / 1024 / 1024)} MB) is too large to upload in ` +
+            `GET-only mode`,
+        );
+      }
+      files.push({
+        field: key,
+        name: file.name,
+        type: file.type,
+        dataBase64: toBase64(new Uint8Array(await file.arrayBuffer())),
+      });
+    } else {
+      fields[key] = String(value);
+    }
+  }
+  return { __files: files, ...fields };
+}
+
+/** The request body as a JS value: a JSON string is parsed; anything else passes through. */
+function bodyFromInit(body: BodyInit | null | undefined): unknown {
+  if (typeof body !== 'string') return body ?? undefined;
+  try {
+    return JSON.parse(body);
+  } catch {
+    return body;
+  }
+}
+
+/** A GET copy of the init: no body, and the now-meaningless content-type dropped. */
+function toGetInit(init: RequestInit): RequestInit {
+  const next: RequestInit = { ...init, method: 'GET', headers: stripContentType(init.headers) };
+  delete next.body;
+  return next;
+}
+
+function stripContentType(headers: HeadersInit | undefined): HeadersInit | undefined {
+  if (!headers) return headers;
+  if (headers instanceof Headers) {
+    const next = new Headers(headers);
+    next.delete('content-type');
+    return next;
+  }
+  if (Array.isArray(headers)) {
+    return headers.filter(([key]) => key.toLowerCase() !== 'content-type');
+  }
+  const next: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() !== 'content-type') next[key] = value;
+  }
+  return next;
+}

package/src/ctgrClient/ctgrClient.spec.ts

@@ -0,0 +1,135 @@
+import { beforeEach, describe, expect, test } from 'bun:test';
+import { decodeRequest } from '../ctgr/index.js';
+import {
+  applyCtgrFromLocation,
+  applyCtgrIntent,
+  convertIfOnlyGETRequests,
+  isCtgrModeOn,
+  readCtgrIntent,
+  setCtgrMode,
+} from './index.js';
+
+beforeEach(() => {
+  localStorage.clear();
+});
+
+describe('the per-device mode flag', () => {
+  test('is off by default and round-trips through setCtgrMode', () => {
+    expect(isCtgrModeOn()).toBe(false);
+    setCtgrMode(true);
+    expect(isCtgrModeOn()).toBe(true);
+    setCtgrMode(false);
+    expect(isCtgrModeOn()).toBe(false);
+  });
+});
+
+describe('readCtgrIntent — the accepted spellings', () => {
+  test('on-values → on', () => {
+    for (const v of ['t', 'on', '1', 'yes', 'true', 'T', ' On ']) {
+      expect(readCtgrIntent(v)).toBe('on');
+    }
+  });
+  test('off-values → off', () => {
+    for (const v of ['f', 'off', '0', 'no', 'false']) {
+      expect(readCtgrIntent(v)).toBe('off');
+    }
+  });
+  test('absent or unknown → keep', () => {
+    expect(readCtgrIntent(null)).toBe('keep');
+    expect(readCtgrIntent(undefined)).toBe('keep');
+    expect(readCtgrIntent('maybe')).toBe('keep');
+  });
+});
+
+describe('applyCtgrIntent persists per device', () => {
+  test('on then off', () => {
+    expect(applyCtgrIntent('t')).toBe(true);
+    expect(isCtgrModeOn()).toBe(true);
+    expect(applyCtgrIntent('f')).toBe(false);
+    expect(isCtgrModeOn()).toBe(false);
+  });
+  test('an absent value leaves an already-on device on', () => {
+    setCtgrMode(true);
+    expect(applyCtgrIntent(null)).toBe(true);
+    expect(isCtgrModeOn()).toBe(true);
+  });
+});
+
+describe('applyCtgrFromLocation — the boot toggle', () => {
+  test('?ctgr=t turns it on, ?ctgr=f turns it off, from a bare search string', () => {
+    expect(applyCtgrFromLocation('?ctgr=t')).toBe(true);
+    expect(isCtgrModeOn()).toBe(true);
+    expect(applyCtgrFromLocation('?ctgr=f')).toBe(false);
+    expect(isCtgrModeOn()).toBe(false);
+  });
+  test('accepts a full href and other params alongside', () => {
+    expect(applyCtgrFromLocation('https://desk.example.com/x?foo=1&ctgr=on')).toBe(true);
+    expect(isCtgrModeOn()).toBe(true);
+  });
+  test('no ctgr param leaves the device as it was', () => {
+    setCtgrMode(true);
+    expect(applyCtgrFromLocation('?foo=1')).toBe(true);
+    setCtgrMode(false);
+    expect(applyCtgrFromLocation('?foo=1')).toBe(false);
+  });
+});
+
+describe('convertIfOnlyGETRequests', () => {
+  test('mode OFF: every request passes through unchanged', async () => {
+    const init = { method: 'POST', body: JSON.stringify({ a: 1 }) };
+    const { requests } = await convertIfOnlyGETRequests('/api/v1/files', init);
+    expect(requests).toHaveLength(1);
+    expect(requests[0].url).toBe('/api/v1/files');
+    expect(requests[0].init).toBe(init);
+  });
+
+  test('mode ON: a POST becomes a decodable GET twin', async () => {
+    setCtgrMode(true);
+    const body = { title: 'hello', n: 42 };
+    const { requests } = await convertIfOnlyGETRequests('/api/v1/files', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    expect(requests).toHaveLength(1);
+    const twin = requests[0];
+    expect(twin.url.startsWith('/ctgrpo/api/v1/files?')).toBe(true);
+    expect((twin.init.method ?? 'GET').toUpperCase()).toBe('GET');
+    expect(twin.init.body).toBeUndefined();
+    // The server codec reverses it exactly.
+    const params = new URL(twin.url, 'http://x').searchParams;
+    const decoded = await decodeRequest(params);
+    expect(decoded).not.toBe('partial');
+    if (decoded === 'partial') throw new Error('unreachable');
+    expect(decoded.method).toBe('POST');
+    expect(decoded.body).toEqual(body);
+  });
+
+  test('mode ON: a plain GET still passes through untouched', async () => {
+    setCtgrMode(true);
+    const { requests } = await convertIfOnlyGETRequests('/api/v1/files', { method: 'GET' });
+    expect(requests).toHaveLength(1);
+    expect(requests[0].url).toBe('/api/v1/files');
+  });
+
+  test('mode ON: a DELETE with no body tunnels too', async () => {
+    setCtgrMode(true);
+    const { requests } = await convertIfOnlyGETRequests('/api/v1/files/x', { method: 'DELETE' });
+    expect(requests[0].url.startsWith('/ctgrde/api/v1/files/x')).toBe(true);
+    const decoded = await decodeRequest(new URL(requests[0].url, 'http://x').searchParams);
+    if (decoded === 'partial') throw new Error('unreachable');
+    expect(decoded.method).toBe('DELETE');
+  });
+
+  test('mode ON: a FormData upload rides as __files and reconstructs', async () => {
+    setCtgrMode(true);
+    const form = new FormData();
+    form.append('name', 'pic');
+    form.append('file', new File([new Uint8Array([1, 2, 3])], 'p.bin', { type: 'image/png' }));
+    const { requests } = await convertIfOnlyGETRequests('/api/v1/media', { method: 'POST' }, form);
+    const decoded = await decodeRequest(new URL(requests[0].url, 'http://x').searchParams);
+    if (decoded === 'partial') throw new Error('unreachable');
+    expect(decoded.files?.[0]).toMatchObject({ originalname: 'p.bin', mimetype: 'image/png' });
+    expect(decoded.body).toEqual({ name: 'pic' });
+  });
+});

package/src/ctgrClient/ctgrConfig.ts

@@ -0,0 +1,89 @@
+/*
+ * Single source of truth for GET-only request mode. When on, the request layer
+ * rewrites every mutating call to a GET (see `convertIfOnlyGETRequests`) and the
+ * network-boundary guard hard-blocks any raw non-GET. Both read this one flag, so
+ * they can never disagree.
+ *
+ * The mode is per-DEVICE, persisted in localStorage so it survives reloads and is
+ * never tied to an account — a device that has it on keeps it on, a device that does
+ * not never gains it. Default is OFF.
+ *
+ * A site sets it up front, before its first request, by reading the URL:
+ *   • `?ctgr=t` (or `on`/`1`/`yes`)  → turn on, persist for this device.
+ *   • `?ctgr=f` (or `off`/`0`/`no`)  → turn off, clear it for this device.
+ *   • no `ctgr` param               → whatever this device already had.
+ * `applyCtgrFromLocation()` is the one call that does this on boot.
+ */
+const CTGR_KEY = 'ctgr';
+
+const ON_VALUES = new Set(['t', 'on', '1', 'yes', 'true']);
+const OFF_VALUES = new Set(['f', 'off', '0', 'no', 'false']);
+
+export const isCtgrModeOn = (): boolean => {
+  try {
+    return localStorage.getItem(CTGR_KEY) === 'on';
+  } catch {
+    return false;
+  }
+};
+
+export const setCtgrMode = (on: boolean): void => {
+  try {
+    if (on) localStorage.setItem(CTGR_KEY, 'on');
+    else localStorage.removeItem(CTGR_KEY);
+  } catch {
+    // localStorage unavailable (private mode / SSR) — nothing to persist.
+  }
+};
+
+/**
+ * The state a `ctgr` query value asks for: on, off, or (unknown/absent) leave the
+ * device as it is. Pure — no storage, no DOM — so it is trivially testable and the
+ * one place the accepted spellings live.
+ */
+export const readCtgrIntent = (value: string | null | undefined): 'on' | 'off' | 'keep' => {
+  if (value == null) return 'keep';
+  const v = value.trim().toLowerCase();
+  if (ON_VALUES.has(v)) return 'on';
+  if (OFF_VALUES.has(v)) return 'off';
+  return 'keep';
+};
+
+/**
+ * Apply a `ctgr` query value to this device's persisted mode and report whether the
+ * mode is on afterwards. Called by `applyCtgrFromLocation` with the value read off
+ * the URL; exposed on its own so a host that already parsed its query can reuse it.
+ */
+export const applyCtgrIntent = (value: string | null | undefined): boolean => {
+  const intent = readCtgrIntent(value);
+  if (intent === 'on') setCtgrMode(true);
+  else if (intent === 'off') setCtgrMode(false);
+  return isCtgrModeOn();
+};
+
+/**
+ * Boot hook: read `?ctgr=…` off the current location (or a supplied search string /
+ * URL), persist the change for this device, and return whether the mode is on. Safe
+ * to call with no argument in the browser; returns `false` with no `window`.
+ *
+ * Call this ONCE, before the app issues its first request — pairing it with
+ * `installCtgrGuard()` so a request made during that first tick is still caught.
+ */
+export const applyCtgrFromLocation = (search?: string): boolean => {
+  let query = search;
+  if (query === undefined) {
+    if (typeof window === 'undefined' || !window.location) return isCtgrModeOn();
+    query = window.location.search;
+  }
+  let value: string | null = null;
+  try {
+    // Accept a bare search (`?ctgr=t`), a full href, or already-extracted params.
+    const params = query.includes('://')
+      ? new URL(query).searchParams
+      : new URLSearchParams(query.startsWith('?') ? query.slice(1) : query);
+    value = params.get(CTGR_KEY);
+  } catch {
+    value = null;
+  }
+  return applyCtgrIntent(value);
+};

package/src/ctgrClient/ctgrGuard.ts

@@ -0,0 +1,86 @@
+/*
+ * Safety net for GET-only mode. Even though the request layer is supposed to rewrite
+ * every mutating call to a GET (`convertIfOnlyGETRequests`), this guard sits at the
+ * actual network boundary and hard-blocks any non-GET request to our own API surface
+ * when the mode is on — so a code path that forgot to run through the converter can
+ * never put a raw POST/PUT/PATCH/DELETE on the wire. Catches both `fetch` and
+ * `XMLHttpRequest`. It only ever tightens; it must never weaken.
+ */
+import { isCtgrModeOn } from './ctgrConfig.js';
+
+// Methods that never mutate and are always safe to allow.
+const SAFE_METHODS = new Set(['GET', 'HEAD']);
+
+const urlOf = (input: RequestInfo | URL): string => {
+  if (typeof input === 'string') return input;
+  if (input instanceof URL) return input.href;
+  if (input instanceof Request) return input.url;
+  return String(input);
+};
+
+// Only guard our OWN API surface — same-origin AND under a path the request layer
+// owns (`/api/…` or a `/ctgr<xx>` twin). Restricting to these prefixes (rather than
+// "any same-origin path") matters: same-origin also covers paths we do not own, like
+// Cloudflare's `/cdn-cgi/rum` beacon, which fires a raw POST on every page view —
+// guarding it would break RUM and fire for every ordinary visitor, not just a
+// misbehaving call site.
+const isGuardedPath = (rawUrl: string): boolean => {
+  let path: string;
+  if (rawUrl.startsWith('/')) {
+    path = rawUrl;
+  } else {
+    try {
+      const u = new URL(rawUrl, window.location.href);
+      if (u.origin !== window.location.origin) return false;
+      path = u.pathname;
+    } catch {
+      return false;
+    }
+  }
+  return path.startsWith('/api/') || path.startsWith('/ctgr');
+};
+
+// Deliberately generic: this message can reach the console of ANY visitor, so it says
+// nothing about the request layer, the call site, or what a blocked request was.
+const block = (): Error => {
+  const message = 'Service unavailable.';
+  console.error(message, new Error('blocked request'));
+  return new Error(message);
+};
+
+let installed = false;
+
+export const installCtgrGuard = (): void => {
+  if (installed || typeof window === 'undefined') return;
+  installed = true;
+
+  // ── fetch ──────────────────────────────────────────────────────────────────
+  if (typeof window.fetch === 'function') {
+    const originalFetch = window.fetch.bind(window);
+    const guardedFetch = (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+      const method = (
+        init?.method ?? (input instanceof Request ? input.method : 'GET')
+      ).toUpperCase();
+      const url = urlOf(input);
+      if (isCtgrModeOn() && !SAFE_METHODS.has(method) && isGuardedPath(url)) {
+        return Promise.reject(block());
+      }
+      return originalFetch(input, init);
+    };
+    window.fetch = guardedFetch as typeof window.fetch;
+  }
+
+  // ── XMLHttpRequest ───────────────────────────────────────────────────────────
+  if (typeof XMLHttpRequest !== 'undefined') {
+    const originalOpen = XMLHttpRequest.prototype.open;
+    // biome-ignore lint/suspicious/noExplicitAny: matching XHR.open's variadic overloads
+    XMLHttpRequest.prototype.open = function open(method: string, url: string, ...rest: any[]) {
+      const upper = String(method).toUpperCase();
+      if (isCtgrModeOn() && !SAFE_METHODS.has(upper) && isGuardedPath(String(url))) {
+        throw block();
+      }
+      // biome-ignore lint/suspicious/noExplicitAny: forwarding the original variadic call
+      return (originalOpen as any).call(this, method, url, ...rest);
+    };
+  }
+};

package/src/ctgrClient/index.ts

@@ -0,0 +1,21 @@
+/*
+ * cursedbelt-core/ctgr-client — the browser adapters that turn any site into a
+ * GET-only client:
+ *   • the per-device mode flag + the `?ctgr=t|f` boot toggle (`ctgrConfig`),
+ *   • the request converter that rewrites a mutation into `/ctgr<xx>` GET twins,
+ *   • the network-boundary guard that blocks a stray raw verb.
+ *
+ * The wire codec is `cursedbelt-core/ctgr`; the server that decodes the twins is
+ * `cursedbelt-server` (`mountCtgrTunnel`). A site opts in with two boot calls —
+ * `applyCtgrFromLocation()` then `installCtgrGuard()` — and routes its requests
+ * through `convertIfOnlyGETRequests`.
+ */
+export {
+  applyCtgrFromLocation,
+  applyCtgrIntent,
+  isCtgrModeOn,
+  readCtgrIntent,
+  setCtgrMode,
+} from './ctgrConfig.js';
+export { type CtgrFetchRequest, convertIfOnlyGETRequests } from './convertRequest.js';
+export { installCtgrGuard } from './ctgrGuard.js';