cursedbelt-core 2.8.0 → 2.10.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/core/searchPattern.d.ts

@@ -0,0 +1,115 @@
+/**
+ * What a search box's text MEANS — plain words, a `*` wildcard, or a regular
+ * expression — decided once, in one place, for the browser and the server alike.
+ *
+ * ── Why this exists (owner request via flix, 2026-09-28) ────────────────────
+ * *"type * to mean any character in the search. Then if I know two words in a
+ * movie but not what is between them I can put the * between them like
+ * "the*the" could pull up "The hunt for the red October" … but not … "The mask".
+ * Also "hunt*red" would find "The hunt for the red October".*
+ *
+ * A word index cannot answer that: it knows the title contains `the`, not that it
+ * contains it TWICE, and not in which order its words came. So a `*` turns the
+ * search into an ordered substring match — `the*the` is "`the`, then anything,
+ * then `the`" — and a search without one is untouched, because every app already
+ * has a plain search it has tuned (flix ranks by FTS5 + bm25; see its
+ * `src/server/library.ts`).
+ *
+ * ── The semantics, all of them ──────────────────────────────────────────────
+ * - **Contains, never anchored.** `hunt*red` matches *The Hunt for Red October*
+ *   although the title does not START with `hunt`. So leading and trailing stars
+ *   are no-ops: `*clov*` ≡ `clov*` ≡ `clov` in what they match — but only the
+ *   starred forms are WILDCARD searches, which is what lets an app answer `*over*`
+ *   with *Cloverfield* (a substring inside a word) where its word index could not.
+ * - **Literal between the stars.** Spaces included, so `the *the` asks for a
+ *   `the` followed by a space — a power user's word boundary, and nobody else
+ *   notices. A part that is ONLY whitespace (`hunt * * red`) is dropped, because
+ *   it would demand two separate gaps and fail on titles it plainly describes.
+ * - **Case-insensitive, always** — in the matcher and the regex alike. A search
+ *   box that cares about capitals reads as broken.
+ * - **Regex is opt-in** (`regex: true`), and only in the unmistakable `/…/flags`
+ *   form, so `AC/DC` is never mistaken for one. Its matcher runs where the data is
+ *   in memory; there is deliberately no SQL form (SQLite and D1 ship no REGEXP),
+ *   and a server that ever evaluates one must bound it — a viewer-typed regex on a
+ *   shared server is a denial-of-service vector.
+ *
+ * ── How an app uses it ──────────────────────────────────────────────────────
+ * {@link parseSearchPattern} is the whole decision; everything else derives from
+ * its result. An app that filters in memory calls {@link createSearchMatcher}. An
+ * app that queries SQL asks {@link searchPatternToLike} for a `LIKE` pattern, and
+ * keeps its own tuned path for `kind: 'plain'`. The React `SearchInput` in
+ * `cursedbelt/react` parses with the SAME function, so the badge it shows is the
+ * syntax the query actually ran in.
+ *
+ * Isomorphic and dependency-free — it imports nothing.
+ */
+/** A syntax an app can switch on beyond plain words. */
+export type SearchSyntax = 'wildcard' | 'regex';
+/** Which syntaxes a search box understands. Absent means the defaults below. */
+export interface SearchSyntaxOptions {
+    /** `*` stands for any run of characters (including none). Default **on**. */
+    wildcard?: boolean;
+    /** `/source/flags` is a regular expression. Default **off**. */
+    regex?: boolean;
+}
+export declare const DEFAULT_SEARCH_SYNTAX: Readonly<Required<SearchSyntaxOptions>>;
+/** The wildcard character. One constant, so the help text can never disagree with the parser. */
+export declare const SEARCH_WILDCARD = "*";
+export type SearchPattern = 
+/** Nothing to search for — show everything. A lone `*` is this too. */
+{
+    kind: 'empty';
+    raw: string;
+}
+/** Ordinary words; `text` is trimmed with runs of whitespace collapsed. */
+ | {
+    kind: 'plain';
+    raw: string;
+    text: string;
+}
+/** `parts` must appear in this order, anything between them. Never empty. */
+ | {
+    kind: 'wildcard';
+    raw: string;
+    text: string;
+    parts: string[];
+} | {
+    kind: 'regex';
+    raw: string;
+    source: string;
+    flags: string;
+}
+/** The viewer's text uses a syntax but cannot be compiled — say why, match nothing. */
+ | {
+    kind: 'invalid';
+    raw: string;
+    syntax: SearchSyntax;
+    message: string;
+};
+/** Decide what a search box's text means under `options`. */
+export declare function parseSearchPattern(raw: string, options?: SearchSyntaxOptions): SearchPattern;
+/**
+ * The pattern as a `RegExp`, or `null` when it matches everything (`empty`) or
+ * nothing (`invalid`). Plain text becomes a case-insensitive contains.
+ */
+export declare function searchPatternToRegExp(pattern: SearchPattern): RegExp | null;
+/** Does `text` match? `empty` matches everything; `invalid` matches nothing. */
+export declare function matchesSearchPattern(pattern: SearchPattern, text: string): boolean;
+/**
+ * Parse once, compile once, then test many — the shape an in-memory list filter
+ * wants. `matcher(title)` for every row costs one regex test, not one parse.
+ */
+export declare function createSearchMatcher(raw: string, options?: SearchSyntaxOptions): {
+    pattern: SearchPattern;
+    test: (text: string) => boolean;
+};
+/**
+ * The pattern as a SQL `LIKE` pattern, escaped with `escape` — so the query must
+ * say `LIKE ? ESCAPE '\'` (or whatever `escape` is). `null` for `empty`, `regex`
+ * and `invalid`: none of those has a `LIKE` form, and the caller decides what
+ * each means rather than being handed a pattern that silently matches too much.
+ *
+ * Case is left as typed. SQLite's `LIKE` is already case-insensitive for ASCII;
+ * a database whose `LIKE` is not (Postgres) should use `ILIKE` with the same string.
+ */
+export declare function searchPatternToLike(pattern: SearchPattern, escape?: string): string | null;

package/dist/core/searchPattern.js

@@ -0,0 +1,146 @@
+/**
+ * What a search box's text MEANS — plain words, a `*` wildcard, or a regular
+ * expression — decided once, in one place, for the browser and the server alike.
+ *
+ * ── Why this exists (owner request via flix, 2026-09-28) ────────────────────
+ * *"type * to mean any character in the search. Then if I know two words in a
+ * movie but not what is between them I can put the * between them like
+ * "the*the" could pull up "The hunt for the red October" … but not … "The mask".
+ * Also "hunt*red" would find "The hunt for the red October".*
+ *
+ * A word index cannot answer that: it knows the title contains `the`, not that it
+ * contains it TWICE, and not in which order its words came. So a `*` turns the
+ * search into an ordered substring match — `the*the` is "`the`, then anything,
+ * then `the`" — and a search without one is untouched, because every app already
+ * has a plain search it has tuned (flix ranks by FTS5 + bm25; see its
+ * `src/server/library.ts`).
+ *
+ * ── The semantics, all of them ──────────────────────────────────────────────
+ * - **Contains, never anchored.** `hunt*red` matches *The Hunt for Red October*
+ *   although the title does not START with `hunt`. So leading and trailing stars
+ *   are no-ops: `*clov*` ≡ `clov*` ≡ `clov` in what they match — but only the
+ *   starred forms are WILDCARD searches, which is what lets an app answer `*over*`
+ *   with *Cloverfield* (a substring inside a word) where its word index could not.
+ * - **Literal between the stars.** Spaces included, so `the *the` asks for a
+ *   `the` followed by a space — a power user's word boundary, and nobody else
+ *   notices. A part that is ONLY whitespace (`hunt * * red`) is dropped, because
+ *   it would demand two separate gaps and fail on titles it plainly describes.
+ * - **Case-insensitive, always** — in the matcher and the regex alike. A search
+ *   box that cares about capitals reads as broken.
+ * - **Regex is opt-in** (`regex: true`), and only in the unmistakable `/…/flags`
+ *   form, so `AC/DC` is never mistaken for one. Its matcher runs where the data is
+ *   in memory; there is deliberately no SQL form (SQLite and D1 ship no REGEXP),
+ *   and a server that ever evaluates one must bound it — a viewer-typed regex on a
+ *   shared server is a denial-of-service vector.
+ *
+ * ── How an app uses it ──────────────────────────────────────────────────────
+ * {@link parseSearchPattern} is the whole decision; everything else derives from
+ * its result. An app that filters in memory calls {@link createSearchMatcher}. An
+ * app that queries SQL asks {@link searchPatternToLike} for a `LIKE` pattern, and
+ * keeps its own tuned path for `kind: 'plain'`. The React `SearchInput` in
+ * `cursedbelt/react` parses with the SAME function, so the badge it shows is the
+ * syntax the query actually ran in.
+ *
+ * Isomorphic and dependency-free — it imports nothing.
+ */
+export const DEFAULT_SEARCH_SYNTAX = Object.freeze({
+    wildcard: true,
+    regex: false,
+});
+/** The wildcard character. One constant, so the help text can never disagree with the parser. */
+export const SEARCH_WILDCARD = '*';
+const REGEX_FORM = /^\/(.+)\/([a-z]*)$/;
+/** Flags that change what matches. `g` and `y` are dropped: they make `test()` stateful. */
+const REGEX_FLAGS = new Set(['i', 'm', 's', 'u', 'g', 'y']);
+const collapse = (text) => text.replace(/\s+/g, ' ');
+/** Decide what a search box's text means under `options`. */
+export function parseSearchPattern(raw, options = {}) {
+    const syntax = { ...DEFAULT_SEARCH_SYNTAX, ...options };
+    const text = collapse(raw.trim());
+    if (text.length === 0)
+        return { kind: 'empty', raw };
+    if (syntax.regex) {
+        const form = REGEX_FORM.exec(text);
+        if (form) {
+            const [, source = '', given = ''] = form;
+            const unknown = [...given].find((f) => !REGEX_FLAGS.has(f));
+            if (unknown) {
+                return { kind: 'invalid', raw, syntax: 'regex', message: `Unknown regex flag "${unknown}"` };
+            }
+            const flags = [...new Set(['i', ...given])].filter((f) => f !== 'g' && f !== 'y').join('');
+            try {
+                new RegExp(source, flags);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return { kind: 'invalid', raw, syntax: 'regex', message };
+            }
+            return { kind: 'regex', raw, source, flags };
+        }
+    }
+    if (syntax.wildcard && text.includes(SEARCH_WILDCARD)) {
+        const parts = text.split(SEARCH_WILDCARD).filter((part) => part.trim().length > 0);
+        if (parts.length === 0)
+            return { kind: 'empty', raw };
+        return { kind: 'wildcard', raw, text, parts };
+    }
+    return { kind: 'plain', raw, text };
+}
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+/**
+ * The pattern as a `RegExp`, or `null` when it matches everything (`empty`) or
+ * nothing (`invalid`). Plain text becomes a case-insensitive contains.
+ */
+export function searchPatternToRegExp(pattern) {
+    switch (pattern.kind) {
+        case 'empty':
+        case 'invalid':
+            return null;
+        case 'plain':
+            return new RegExp(escapeRegExp(pattern.text), 'i');
+        case 'wildcard':
+            // `[\s\S]*?` rather than `.*` so a gap may cross a newline in a
+            // multi-line field (a summary, a note) without needing the `s` flag.
+            return new RegExp(pattern.parts.map(escapeRegExp).join('[\\s\\S]*?'), 'i');
+        case 'regex':
+            return new RegExp(pattern.source, pattern.flags);
+    }
+}
+/** Does `text` match? `empty` matches everything; `invalid` matches nothing. */
+export function matchesSearchPattern(pattern, text) {
+    if (pattern.kind === 'empty')
+        return true;
+    return searchPatternToRegExp(pattern)?.test(text) ?? false;
+}
+/**
+ * Parse once, compile once, then test many — the shape an in-memory list filter
+ * wants. `matcher(title)` for every row costs one regex test, not one parse.
+ */
+export function createSearchMatcher(raw, options = {}) {
+    const pattern = parseSearchPattern(raw, options);
+    if (pattern.kind === 'empty')
+        return { pattern, test: () => true };
+    const re = searchPatternToRegExp(pattern);
+    return { pattern, test: re ? (text) => re.test(text) : () => false };
+}
+/**
+ * The pattern as a SQL `LIKE` pattern, escaped with `escape` — so the query must
+ * say `LIKE ? ESCAPE '\'` (or whatever `escape` is). `null` for `empty`, `regex`
+ * and `invalid`: none of those has a `LIKE` form, and the caller decides what
+ * each means rather than being handed a pattern that silently matches too much.
+ *
+ * Case is left as typed. SQLite's `LIKE` is already case-insensitive for ASCII;
+ * a database whose `LIKE` is not (Postgres) should use `ILIKE` with the same string.
+ */
+export function searchPatternToLike(pattern, escape = '\\') {
+    const literal = (text) => text.replace(/[%_]/g, (c) => `${escape}${c}`);
+    const escapeAll = (text) => literal(text.split(escape).join(`${escape}${escape}`));
+    switch (pattern.kind) {
+        case 'plain':
+            return `%${escapeAll(pattern.text)}%`;
+        case 'wildcard':
+            return `%${pattern.parts.map(escapeAll).join('%')}%`;
+        default:
+            return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-core",
-	"version": "2.8.0",
+	"version": "2.10.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.",
@@ -288,6 +288,12 @@
 			"source": "./src/core/passwordPolicy.ts",
 			"import": "./dist/core/passwordPolicy.js"
 		},
+		"./search-pattern": {
+			"types": "./dist/core/searchPattern.d.ts",
+			"bun": "./src/core/searchPattern.ts",
+			"source": "./src/core/searchPattern.ts",
+			"import": "./dist/core/searchPattern.js"
+		},
 		"./session/claims": {
 			"types": "./dist/core/session/claims.d.ts",
 			"bun": "./src/core/session/claims.ts",

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/core/offline/shellWorker.webworker.spec.ts

@@ -54,11 +54,13 @@ 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], {
+  const child = Bun.spawn([process.execPath, `${REPO}/node_modules/typescript/bin/tsc`, '-p', root], {
+    stdin: 'ignore',
     stdout: 'pipe',
     stderr: 'pipe',
   });
-  return `${child.stdout.toString()}${child.stderr.toString()}`;
+  const [stdout, stderr] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
+  return `${stdout}${stderr}`;
 };
 
 const output = await typecheck();

package/src/core/searchPattern.spec.ts

@@ -0,0 +1,130 @@
+/**
+ * The owner's own examples are the acceptance test — each one is a row below,
+ * against the titles he named.
+ */
+import { describe, expect, it } from 'bun:test';
+import {
+	createSearchMatcher,
+	matchesSearchPattern,
+	parseSearchPattern,
+	searchPatternToLike,
+	searchPatternToRegExp,
+} from './searchPattern';
+
+const TITLES = [
+	'The Hunt for Red October',
+	'The Mask',
+	'10 Cloverfield Lane',
+	'Cloverfield',
+	'The Agony and the Ecstasy',
+	'Other People',
+	'M*A*S*H',
+	'100% Wolf',
+	'Snake_Eyes',
+];
+const find = (raw: string, options = {}) => {
+	const { test } = createSearchMatcher(raw, options);
+	return TITLES.filter(test);
+};
+
+describe('the owner’s examples (flix, 2026-09-28)', () => {
+	it('"the*the" finds a title with `the` twice, and not one with it once', () => {
+		// The real title is "The Hunt for Red October" — ONE `the` — so it is
+		// correctly absent; the request remembered it as "…for the red October".
+		expect(find('the*the')).toEqual(['The Agony and the Ecstasy']);
+		expect(createSearchMatcher('the*the').test('The hunt for the red October')).toBe(true);
+	});
+	it('"hunt*red" finds The Hunt for Red October — contains, not starts-with', () => {
+		expect(find('hunt*red')).toEqual(['The Hunt for Red October']);
+	});
+	it('"*clov*" finds 10 Cloverfield Lane, exactly as "clov" does', () => {
+		expect(find('*clov*')).toEqual(['10 Cloverfield Lane', 'Cloverfield']);
+		expect(find('clov')).toEqual(find('*clov*'));
+	});
+	it('order matters: "red*hunt" does not find The Hunt for Red October', () => {
+		expect(find('red*hunt')).toEqual([]);
+	});
+	it('a star reaches INSIDE a word — "*over*" finds Cloverfield', () => {
+		expect(find('*over*')).toEqual(['10 Cloverfield Lane', 'Cloverfield']);
+	});
+});
+
+describe('parseSearchPattern', () => {
+	it('is empty for blank text and for stars alone', () => {
+		expect(parseSearchPattern('   ').kind).toBe('empty');
+		expect(parseSearchPattern('*').kind).toBe('empty');
+		expect(parseSearchPattern(' ** ').kind).toBe('empty');
+	});
+	it('is plain without a star, trimmed and whitespace-collapsed', () => {
+		expect(parseSearchPattern('  the   office ')).toEqual({ kind: 'plain', raw: '  the   office ', text: 'the office' });
+	});
+	it('splits on the star and keeps spaces as literal', () => {
+		const p = parseSearchPattern('the *the');
+		expect(p).toMatchObject({ kind: 'wildcard', parts: ['the ', 'the'] });
+	});
+	it('drops a whitespace-only part, which would otherwise demand two gaps', () => {
+		expect(parseSearchPattern('hunt * * red')).toMatchObject({ kind: 'wildcard', parts: ['hunt ', ' red'] });
+		expect(find('hunt * * red')).toEqual(['The Hunt for Red October']);
+	});
+	it('with wildcard OFF, a star is plain text', () => {
+		expect(parseSearchPattern('m*a*s*h', { wildcard: false })).toMatchObject({ kind: 'plain', text: 'm*a*s*h' });
+		expect(find('m*a*s*h', { wildcard: false })).toEqual(['M*A*S*H']);
+	});
+	it('regex is OFF by default — /…/ is plain text', () => {
+		expect(parseSearchPattern('/hunt.+red/').kind).toBe('plain');
+		expect(parseSearchPattern('/hunt.*red/').kind).toBe('wildcard');
+	});
+});
+
+describe('regex (opt-in)', () => {
+	const on = { regex: true };
+	it('compiles /source/flags, always case-insensitive, never stateful', () => {
+		expect(parseSearchPattern('/^the (mask|agony)/g', on)).toMatchObject({ kind: 'regex', source: '^the (mask|agony)', flags: 'i' });
+		expect(find('/^the (mask|agony)/g', on)).toEqual(['The Mask', 'The Agony and the Ecstasy']);
+	});
+	it('is invalid — and matches nothing — when it will not compile', () => {
+		const p = parseSearchPattern('/(unclosed/', on);
+		expect(p).toMatchObject({ kind: 'invalid', syntax: 'regex' });
+		expect(matchesSearchPattern(p, 'anything')).toBe(false);
+		expect(find('/(unclosed/', on)).toEqual([]);
+	});
+	it('names an unknown flag', () => {
+		expect(parseSearchPattern('/a/q', on)).toMatchObject({ kind: 'invalid', message: 'Unknown regex flag "q"' });
+	});
+	it('does not mistake a slash inside a title for a regex', () => {
+		expect(parseSearchPattern('AC/DC', on).kind).toBe('plain');
+	});
+});
+
+describe('searchPatternToRegExp', () => {
+	it('escapes regex metacharacters in plain and wildcard text', () => {
+		expect(find('100%')).toEqual(['100% Wolf']);
+		expect(searchPatternToRegExp(parseSearchPattern('a.b*(c)'))?.test('A.B then (C)')).toBe(true);
+		expect(searchPatternToRegExp(parseSearchPattern('a.b*(c)'))?.test('axb then (c)')).toBe(false);
+	});
+	it('lets a gap cross a newline', () => {
+		expect(matchesSearchPattern(parseSearchPattern('first*second'), 'first line\nsecond line')).toBe(true);
+	});
+	it('is null for empty and invalid', () => {
+		expect(searchPatternToRegExp(parseSearchPattern(''))).toBeNull();
+		expect(searchPatternToRegExp(parseSearchPattern('/(/', { regex: true }))).toBeNull();
+	});
+});
+
+describe('searchPatternToLike', () => {
+	it('is a contains for plain text and an ordered contains for a wildcard', () => {
+		expect(searchPatternToLike(parseSearchPattern('the office'))).toBe('%the office%');
+		expect(searchPatternToLike(parseSearchPattern('the*the'))).toBe('%the%the%');
+		expect(searchPatternToLike(parseSearchPattern('*clov*'))).toBe('%clov%');
+	});
+	it('escapes LIKE’s own wildcards and the escape character itself', () => {
+		expect(searchPatternToLike(parseSearchPattern('100%*snake_eyes'))).toBe('%100\\%%snake\\_eyes%');
+		expect(searchPatternToLike(parseSearchPattern('a\\b'))).toBe('%a\\\\b%');
+		expect(searchPatternToLike(parseSearchPattern('50%'), '!')).toBe('%50!%%');
+	});
+	it('has no form for empty, regex or invalid — the caller decides', () => {
+		expect(searchPatternToLike(parseSearchPattern(''))).toBeNull();
+		expect(searchPatternToLike(parseSearchPattern('/a/', { regex: true }))).toBeNull();
+		expect(searchPatternToLike(parseSearchPattern('/(/', { regex: true }))).toBeNull();
+	});
+});

package/src/core/searchPattern.ts

@@ -0,0 +1,179 @@
+/**
+ * What a search box's text MEANS — plain words, a `*` wildcard, or a regular
+ * expression — decided once, in one place, for the browser and the server alike.
+ *
+ * ── Why this exists (owner request via flix, 2026-09-28) ────────────────────
+ * *"type * to mean any character in the search. Then if I know two words in a
+ * movie but not what is between them I can put the * between them like
+ * "the*the" could pull up "The hunt for the red October" … but not … "The mask".
+ * Also "hunt*red" would find "The hunt for the red October".*
+ *
+ * A word index cannot answer that: it knows the title contains `the`, not that it
+ * contains it TWICE, and not in which order its words came. So a `*` turns the
+ * search into an ordered substring match — `the*the` is "`the`, then anything,
+ * then `the`" — and a search without one is untouched, because every app already
+ * has a plain search it has tuned (flix ranks by FTS5 + bm25; see its
+ * `src/server/library.ts`).
+ *
+ * ── The semantics, all of them ──────────────────────────────────────────────
+ * - **Contains, never anchored.** `hunt*red` matches *The Hunt for Red October*
+ *   although the title does not START with `hunt`. So leading and trailing stars
+ *   are no-ops: `*clov*` ≡ `clov*` ≡ `clov` in what they match — but only the
+ *   starred forms are WILDCARD searches, which is what lets an app answer `*over*`
+ *   with *Cloverfield* (a substring inside a word) where its word index could not.
+ * - **Literal between the stars.** Spaces included, so `the *the` asks for a
+ *   `the` followed by a space — a power user's word boundary, and nobody else
+ *   notices. A part that is ONLY whitespace (`hunt * * red`) is dropped, because
+ *   it would demand two separate gaps and fail on titles it plainly describes.
+ * - **Case-insensitive, always** — in the matcher and the regex alike. A search
+ *   box that cares about capitals reads as broken.
+ * - **Regex is opt-in** (`regex: true`), and only in the unmistakable `/…/flags`
+ *   form, so `AC/DC` is never mistaken for one. Its matcher runs where the data is
+ *   in memory; there is deliberately no SQL form (SQLite and D1 ship no REGEXP),
+ *   and a server that ever evaluates one must bound it — a viewer-typed regex on a
+ *   shared server is a denial-of-service vector.
+ *
+ * ── How an app uses it ──────────────────────────────────────────────────────
+ * {@link parseSearchPattern} is the whole decision; everything else derives from
+ * its result. An app that filters in memory calls {@link createSearchMatcher}. An
+ * app that queries SQL asks {@link searchPatternToLike} for a `LIKE` pattern, and
+ * keeps its own tuned path for `kind: 'plain'`. The React `SearchInput` in
+ * `cursedbelt/react` parses with the SAME function, so the badge it shows is the
+ * syntax the query actually ran in.
+ *
+ * Isomorphic and dependency-free — it imports nothing.
+ */
+
+/** A syntax an app can switch on beyond plain words. */
+export type SearchSyntax = 'wildcard' | 'regex';
+
+/** Which syntaxes a search box understands. Absent means the defaults below. */
+export interface SearchSyntaxOptions {
+	/** `*` stands for any run of characters (including none). Default **on**. */
+	wildcard?: boolean;
+	/** `/source/flags` is a regular expression. Default **off**. */
+	regex?: boolean;
+}
+
+export const DEFAULT_SEARCH_SYNTAX: Readonly<Required<SearchSyntaxOptions>> = Object.freeze({
+	wildcard: true,
+	regex: false,
+});
+
+/** The wildcard character. One constant, so the help text can never disagree with the parser. */
+export const SEARCH_WILDCARD = '*';
+
+export type SearchPattern =
+	/** Nothing to search for — show everything. A lone `*` is this too. */
+	| { kind: 'empty'; raw: string }
+	/** Ordinary words; `text` is trimmed with runs of whitespace collapsed. */
+	| { kind: 'plain'; raw: string; text: string }
+	/** `parts` must appear in this order, anything between them. Never empty. */
+	| { kind: 'wildcard'; raw: string; text: string; parts: string[] }
+	| { kind: 'regex'; raw: string; source: string; flags: string }
+	/** The viewer's text uses a syntax but cannot be compiled — say why, match nothing. */
+	| { kind: 'invalid'; raw: string; syntax: SearchSyntax; message: string };
+
+const REGEX_FORM = /^\/(.+)\/([a-z]*)$/;
+/** Flags that change what matches. `g` and `y` are dropped: they make `test()` stateful. */
+const REGEX_FLAGS = new Set(['i', 'm', 's', 'u', 'g', 'y']);
+
+const collapse = (text: string): string => text.replace(/\s+/g, ' ');
+
+/** Decide what a search box's text means under `options`. */
+export function parseSearchPattern(raw: string, options: SearchSyntaxOptions = {}): SearchPattern {
+	const syntax = { ...DEFAULT_SEARCH_SYNTAX, ...options };
+	const text = collapse(raw.trim());
+	if (text.length === 0) return { kind: 'empty', raw };
+
+	if (syntax.regex) {
+		const form = REGEX_FORM.exec(text);
+		if (form) {
+			const [, source = '', given = ''] = form;
+			const unknown = [...given].find((f) => !REGEX_FLAGS.has(f));
+			if (unknown) {
+				return { kind: 'invalid', raw, syntax: 'regex', message: `Unknown regex flag "${unknown}"` };
+			}
+			const flags = [...new Set(['i', ...given])].filter((f) => f !== 'g' && f !== 'y').join('');
+			try {
+				new RegExp(source, flags);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return { kind: 'invalid', raw, syntax: 'regex', message };
+			}
+			return { kind: 'regex', raw, source, flags };
+		}
+	}
+
+	if (syntax.wildcard && text.includes(SEARCH_WILDCARD)) {
+		const parts = text.split(SEARCH_WILDCARD).filter((part) => part.trim().length > 0);
+		if (parts.length === 0) return { kind: 'empty', raw };
+		return { kind: 'wildcard', raw, text, parts };
+	}
+
+	return { kind: 'plain', raw, text };
+}
+
+const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+
+/**
+ * The pattern as a `RegExp`, or `null` when it matches everything (`empty`) or
+ * nothing (`invalid`). Plain text becomes a case-insensitive contains.
+ */
+export function searchPatternToRegExp(pattern: SearchPattern): RegExp | null {
+	switch (pattern.kind) {
+		case 'empty':
+		case 'invalid':
+			return null;
+		case 'plain':
+			return new RegExp(escapeRegExp(pattern.text), 'i');
+		case 'wildcard':
+			// `[\s\S]*?` rather than `.*` so a gap may cross a newline in a
+			// multi-line field (a summary, a note) without needing the `s` flag.
+			return new RegExp(pattern.parts.map(escapeRegExp).join('[\\s\\S]*?'), 'i');
+		case 'regex':
+			return new RegExp(pattern.source, pattern.flags);
+	}
+}
+
+/** Does `text` match? `empty` matches everything; `invalid` matches nothing. */
+export function matchesSearchPattern(pattern: SearchPattern, text: string): boolean {
+	if (pattern.kind === 'empty') return true;
+	return searchPatternToRegExp(pattern)?.test(text) ?? false;
+}
+
+/**
+ * Parse once, compile once, then test many — the shape an in-memory list filter
+ * wants. `matcher(title)` for every row costs one regex test, not one parse.
+ */
+export function createSearchMatcher(
+	raw: string,
+	options: SearchSyntaxOptions = {},
+): { pattern: SearchPattern; test: (text: string) => boolean } {
+	const pattern = parseSearchPattern(raw, options);
+	if (pattern.kind === 'empty') return { pattern, test: () => true };
+	const re = searchPatternToRegExp(pattern);
+	return { pattern, test: re ? (text) => re.test(text) : () => false };
+}
+
+/**
+ * The pattern as a SQL `LIKE` pattern, escaped with `escape` — so the query must
+ * say `LIKE ? ESCAPE '\'` (or whatever `escape` is). `null` for `empty`, `regex`
+ * and `invalid`: none of those has a `LIKE` form, and the caller decides what
+ * each means rather than being handed a pattern that silently matches too much.
+ *
+ * Case is left as typed. SQLite's `LIKE` is already case-insensitive for ASCII;
+ * a database whose `LIKE` is not (Postgres) should use `ILIKE` with the same string.
+ */
+export function searchPatternToLike(pattern: SearchPattern, escape = '\\'): string | null {
+	const literal = (text: string) => text.replace(/[%_]/g, (c) => `${escape}${c}`);
+	const escapeAll = (text: string) => literal(text.split(escape).join(`${escape}${escape}`));
+	switch (pattern.kind) {
+		case 'plain':
+			return `%${escapeAll(pattern.text)}%`;
+		case 'wildcard':
+			return `%${pattern.parts.map(escapeAll).join('%')}%`;
+		default:
+			return null;
+	}
+}

package/src/leafSubpathsImportNothing.spec.ts

@@ -250,16 +250,20 @@ console.log(JSON.stringify(out));
 `,
   );
 
-  const child = Bun.spawnSync(['bun', 'run', 'entry.ts'], {
+  const child = Bun.spawn(['bun', 'run', 'entry.ts'], {
     cwd: root,
+    stdin: 'ignore',
     stdout: 'pipe',
     stderr: 'pipe',
   });
-  const stdout = child.stdout.toString().trim();
-  if (child.exitCode !== 0 || stdout === '') {
-    throw new Error(
-      `the fixture could not run at all (exit ${child.exitCode}) — that is a broken check, not a passing one:\n${child.stderr.toString()}`,
-    );
+  const [stdoutRaw, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ]);
+  const stdout = stdoutRaw.trim();
+  if (exitCode !== 0 || stdout === '') {
+    throw new Error(`the fixture could not run at all (exit ${exitCode}) — that is a broken check, not a passing one:\n${stderr}`);
   }
   return JSON.parse(stdout) as Record<string, Outcome>;
 };

package/src/lockfileIsTracked.spec.ts

@@ -23,7 +23,6 @@
  * to skip it. Ignored-vs-not is the property that actually regresses.
  */
 import { describe, expect, test } from 'bun:test'
-import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
@@ -37,13 +36,18 @@ describe('bun.lock is part of the checkout', () => {
     ).toBe(true)
   })
 
-  test('git is not told to ignore it', () => {
-    const git = spawnSync('git', ['check-ignore', '-q', 'bun.lock'], { cwd: repoRoot })
-    if (git.error) return // no git on this host: nothing to assert about ignore rules
+  test('git is not told to ignore it', async () => {
+    let status: number
+    try {
+      const child = Bun.spawn(['git', 'check-ignore', '-q', 'bun.lock'], { cwd: repoRoot, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' })
+      status = await child.exited
+    } catch {
+      return // no git on this host: nothing to assert about ignore rules
+    }
 
     // exit 0 = the path IS ignored; 1 = it is not; anything else = git could not tell us.
     expect(
-      git.status,
+      status,
       'bun.lock is gitignored, so a fresh clone has no lockfile and `bun install --frozen-lockfile` cannot pass there. Delete the stanza from .gitignore rather than the assertion.',
     ).not.toBe(0)
   })

package/src/shippedFilesAreTracked.spec.ts

@@ -25,7 +25,6 @@
  * when `git` cannot answer — a check that silently degrades to green is worse than none.
  */
 import { describe, expect, test } from 'bun:test';
-import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import pkg from '../package.json';
@@ -36,14 +35,15 @@ const repoRoot = fileURLToPath(new URL('..', import.meta.url));
 const shippedDirs = (): string[] =>
 	((pkg as { files?: string[] }).files ?? []).filter((f) => f !== 'dist' && existsSync(`${repoRoot}/${f}`));
 
-const git = (...args: string[]): { ok: boolean; out: string } => {
-	const r = spawnSync('git', ['-C', repoRoot, ...args], { encoding: 'utf8' });
-	return { ok: r.status === 0, out: (r.stdout ?? '').trim() };
+const git = async (...args: string[]): Promise<{ ok: boolean; out: string }> => {
+	const child = Bun.spawn(['git', '-C', repoRoot, ...args], { stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' });
+	const [out, , code] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
+	return { ok: code === 0, out: out.trim() };
 };
 
 describe('every file inside the published surface is tracked', () => {
-	test('git can answer at all — a degraded check must refuse, not pass', () => {
-		expect(git('rev-parse', '--is-inside-work-tree').ok, 'not a git checkout, so this check proves nothing').toBe(true);
+	test('git can answer at all — a degraded check must refuse, not pass', async () => {
+		expect((await git('rev-parse', '--is-inside-work-tree')).ok, 'not a git checkout, so this check proves nothing').toBe(true);
 	});
 
 	test('package.json names a shippable directory to scan', () => {
@@ -52,10 +52,10 @@ describe('every file inside the published surface is tracked', () => {
 		expect(shippedDirs().length, '`files` names no committed directory — nothing would be scanned').toBeGreaterThan(0);
 	});
 
-	test('no untracked file sits inside a directory `files` ships', () => {
+	test('no untracked file sits inside a directory `files` ships', async () => {
 		// --others = untracked; --exclude-standard honours .gitignore, so deliberately
 		// ignored paths (.agent.noindex, node_modules) are not offences.
-		const { ok, out } = git('ls-files', '--others', '--exclude-standard', '--', ...shippedDirs());
+		const { ok, out } = await git('ls-files', '--others', '--exclude-standard', '--', ...shippedDirs());
 		expect(ok, 'git ls-files failed').toBe(true);
 		const untracked = out === '' ? [] : out.split('\n');
 		expect(