cursedbelt-core 2.9.0 → 2.10.0

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.9.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.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(