@voithos-labs/aragonite 0.10.1

package/dist/schema/reserved-chords.js

@@ -0,0 +1,313 @@
+/**
+ * Which modifier chords a mounted editor consumes. The keymap tiers enumerate from the
+ * registries; chords claimed by hand-written keydown branches do not, so they ride the
+ * manifest below — G4.29's source scan fails until a new claiming site joins it. Bare keys
+ * stay out of contract: a focused document owns them whatever the manifest says. A manifested
+ * file must keep its literal key comparisons and modifier reads, which are the scan's evidence.
+ */
+import { getAllRegisteredKinds, tryGetBlockKindDescriptor } from './block-kind-descriptor';
+import { GLOBAL_KEYMAP, pluginGlobalChords, reservedUiChords } from './commands';
+import { eventToChord, normalizeChord } from './keybindings';
+export const HARDCODED_CHORD_SITES = [
+    {
+        file: 'components/Editor.svelte',
+        chords: [],
+        keys: [],
+        note: 'Mod-click link activation — no keystroke is consumed.'
+    },
+    {
+        file: 'components/editor-root-listeners.ts',
+        chords: [],
+        keys: [],
+        note: 'The Mod-held `data-mod-active` affordance tracks flag state only — no keystroke is consumed.'
+    },
+    {
+        file: 'components/GapCaret.svelte',
+        chords: [],
+        keys: [
+            'ArrowDown',
+            'ArrowLeft',
+            'ArrowRight',
+            'ArrowUp',
+            'Backspace',
+            'Delete',
+            'Enter',
+            'Escape'
+        ],
+        note: 'The gap caret proxy claims the exits plus the Enter that mints; Ctrl/Meta/Alt yields to the global table, and Shift takes the plain arrow arm.'
+    },
+    {
+        file: 'components/SearchBar.svelte',
+        chords: ['Shift+Enter'],
+        keys: ['Enter', 'Escape'],
+        note: 'Previous match from the find input. Reachable only with the bar open, and the prose keymap binds the same chord anyway.'
+    },
+    {
+        file: 'components/blocks/editable-leaf.ts',
+        chords: [],
+        keys: ['Enter'],
+        note: 'Shift-click gate on the rendered surface — a pointer read.'
+    },
+    {
+        file: 'components/link-card/LinkCard.svelte',
+        chords: ['Shift+Tab', 'Mod+K'],
+        keys: ['Enter', 'K', 'Tab', 'k'],
+        note: "Backwards step of the open card's focus trap, plus the entry chord swallowed as a no-op where the focus already is — the kind keymaps claim it everywhere else. Escape lives on the host, which must also close a card the document still holds the caret for."
+    },
+    {
+        file: 'components/blocks/table/TableActionMenu.svelte',
+        chords: ['Shift+Tab'],
+        keys: ['ArrowDown', 'ArrowLeft', 'ArrowRight', 'ArrowUp', 'End', 'Escape', 'Home', 'Tab'],
+        note: "Backwards step of the open menu's focus trap."
+    },
+    {
+        file: 'components/blocks/table/TableBlock.svelte',
+        chords: ['Shift+F10'],
+        keys: ['ContextMenu', 'F10'],
+        note: 'The keyboard route to the cell action menu.'
+    },
+    {
+        file: 'components/blocks/table/TableCellBlock.svelte',
+        chords: ['Shift+ArrowUp', 'Shift+ArrowDown'],
+        keys: ['ArrowDown', 'ArrowUp', 'Enter'],
+        note: 'Starts the intra-table rectangle before the prose extend can walk the next leaf; the second modifier read is the widget activation click, which consumes no keystroke.'
+    },
+    {
+        file: 'components/blocks/table/cell-keydown-plan.ts',
+        chords: ['Mod+A', 'Shift+Tab'],
+        keys: [
+            'A',
+            'ArrowDown',
+            'ArrowLeft',
+            'ArrowRight',
+            'ArrowUp',
+            'Backspace',
+            'Delete',
+            'Enter',
+            'Tab',
+            'a'
+        ]
+    },
+    {
+        file: 'components/blocks/text/TextEditableBlock.svelte',
+        chords: [],
+        keys: ['Home'],
+        note: 'Bare Home only; the modifier reads are the guard that keeps Shift+Home native and the widget activation click, which consumes no keystroke.'
+    },
+    {
+        file: 'components/blocks/text/click-snap-guard.ts',
+        chords: [],
+        keys: [],
+        note: 'The `hasModifier` predicate itself.'
+    },
+    {
+        file: 'components/blocks/text/construct-reveal.ts',
+        chords: [],
+        keys: ['ArrowLeft', 'ArrowRight', 'Backspace', 'Delete'],
+        note: 'Declines every modified key rather than claiming one.'
+    },
+    {
+        file: 'components/blocks/text/edge-policy-dispatch.ts',
+        chords: [],
+        keys: [' ', 'ArrowLeft', 'ArrowRight', 'Backspace', 'Delete'],
+        note: 'The caret-edge policy runs on plain keys; the modifier read is its gate. The bare space is container marker completion, consumed rather than claimed as a chord.'
+    },
+    {
+        file: 'components/blocks/text/widget-interaction.ts',
+        chords: ['Shift+ArrowLeft', 'Shift+ArrowRight'],
+        keys: ['Arrow*', 'ArrowLeft', 'ArrowRight', 'Backspace', 'Delete', 'Escape'],
+        note: 'Extends a selection into a widget. A modified arrow is also swallowed while a widget is selected, but that is a caret-coherence guard in a transient state, not a binding.'
+    },
+    {
+        file: 'components/image/ImageResizeHandles.svelte',
+        chords: [],
+        keys: [],
+        note: 'Shift locks the aspect ratio during a pointer drag.'
+    },
+    {
+        file: 'components/image/image-widget-editing.ts',
+        chords: ['Shift+ArrowLeft', 'Shift+ArrowRight'],
+        keys: ['ArrowLeft', 'ArrowRight'],
+        note: 'Keyboard resize of the selected image.'
+    },
+    {
+        file: 'components/image/widget-dom.ts',
+        chords: [],
+        keys: [],
+        note: 'Shift-click declines, so the block keeps cross-block extension.'
+    },
+    {
+        file: 'cursor/edge-affinity.ts',
+        chords: [],
+        keys: ['ArrowDown', 'ArrowLeft', 'ArrowRight', 'ArrowUp', 'End', 'Home', 'PageDown', 'PageUp'],
+        note: 'Classifies an arrival for the caret-side memory; consumes nothing.'
+    },
+    {
+        file: 'cursor/sticky-column.ts',
+        chords: [],
+        keys: ['ArrowDown', 'ArrowUp'],
+        note: 'Classifies a keystroke for the column memory; consumes nothing.'
+    },
+    {
+        file: 'editor-actions/container-block-component.ts',
+        chords: ['Mod+C', 'Mod+X'],
+        keys: [
+            'ArrowDown',
+            'ArrowLeft',
+            'ArrowRight',
+            'ArrowUp',
+            'Backspace',
+            'Delete',
+            'Enter',
+            'c',
+            'x'
+        ],
+        note: 'Whole-block copy/cut: a keydown carries no ClipboardEvent, so the chord is read here. The unchorded printable mints a paragraph below, so the same modifier reads gate that branch too.'
+    },
+    {
+        file: 'editor-actions/plugin/container.ts',
+        chords: ['Alt+ArrowUp', 'Alt+ArrowDown'],
+        keys: ['ArrowDown', 'ArrowUp'],
+        note: 'Reorder for plugin containers, whose command dispatch is inert.'
+    },
+    {
+        file: 'plugins/footnotes/FootnoteDefinition.svelte',
+        chords: [],
+        keys: [],
+        note: 'Mod-click on the `[^label]` marker jumps back to the reference — no keystroke is consumed.'
+    },
+    {
+        file: 'plugins/footnotes/FootnoteReference.svelte',
+        chords: [],
+        keys: [],
+        note: 'Mod-click jump to the definition, the link click’s gesture — no keystroke is consumed.'
+    },
+    {
+        file: 'plugins/mermaid/MermaidBlock.svelte',
+        chords: ['Mod+Enter'],
+        keys: ['ArrowDown', 'ArrowLeft', 'ArrowRight', 'ArrowUp', 'Enter', 'Escape', 'Tab'],
+        note: 'Commits the diagram edit; the arrows are the edit box’s boundary exits, and a modified one is declined rather than claimed. Bundled-plugin chord, listed unconditionally — it coincides with the table keymap, so gating it on the install would change no answer.'
+    },
+    {
+        file: 'schema/keybindings.ts',
+        chords: [],
+        keys: [],
+        note: 'The normalizer every other site reads.'
+    },
+    {
+        file: 'selection/cross-block/keydown.ts',
+        chords: [
+            'Mod+A',
+            'Mod+Shift+Home',
+            'Mod+Shift+End',
+            'Shift+ArrowUp',
+            'Shift+ArrowDown',
+            'Shift+ArrowLeft',
+            'Shift+ArrowRight'
+        ],
+        keys: [
+            'ArrowDown',
+            'ArrowLeft',
+            'ArrowRight',
+            'ArrowUp',
+            'B',
+            'Backspace',
+            'Delete',
+            'E',
+            'End',
+            'Enter',
+            'Escape',
+            'Home',
+            'I',
+            'K',
+            'Tab',
+            'X',
+            'a',
+            'b',
+            'e',
+            'i',
+            'k',
+            'x'
+        ],
+        note: 'Mod+0-6 routes to the merged command registry, where that binding lives. The rewrite chords are CLAIMED over a cross-block range and handed to the dispatch seam — the four format toggles route to the cross-block arm, the link card declines, since no single block can host its mint — because falling through read the chord as text (or ran Ctrl+K as kill-line). Mod+Shift+X takes an arm of its own: unshifted Mod+X is the whole-block cut.'
+    },
+    {
+        file: 'selection/cross-block/pointer.ts',
+        chords: [],
+        keys: [],
+        note: 'Shift-click anchoring.'
+    },
+    {
+        file: 'selection/dead-space-caret.ts',
+        chords: [],
+        keys: [],
+        note: 'A modified click is a platform command, so the dead-space caret declines it.'
+    },
+    {
+        file: 'selection/shared-keydown.ts',
+        chords: ['Shift+ArrowUp', 'Shift+ArrowDown', 'Shift+ArrowLeft', 'Shift+ArrowRight'],
+        keys: [
+            'Alt',
+            'AltGraph',
+            'ArrowDown',
+            'ArrowLeft',
+            'ArrowRight',
+            'ArrowUp',
+            'CapsLock',
+            'Control',
+            'Meta',
+            'Shift',
+            'a'
+        ],
+        note: 'Extends across a block boundary once the native extend runs out of room.'
+    }
+];
+const HARDCODED_CHORDS = new Set(HARDCODED_CHORD_SITES.flatMap((site) => site.chords).map(normalizeChord));
+/**
+ * Every modifier chord this editor consumes, normalized. Composed on each call: kind keymaps,
+ * the plugin tiers and the override map all change under a live editor.
+ */
+export function collectReservedChords(options) {
+    const claimed = new Set([
+        ...registeredKeymapChords(),
+        ...GLOBAL_KEYMAP.map((binding) => binding.chord),
+        ...pluginGlobalChords(options.activation),
+        ...HARDCODED_CHORDS,
+        ...(options.searchBar ? reservedUiChords() : []),
+        ...overrideBoundChords(options.keybindings)
+    ]
+        .map(normalizeChord)
+        .filter(carriesModifier));
+    // A global disable unbinds the chord at every command tier. A hardcoded branch never
+    // consults the override map, so it keeps its claim.
+    for (const chord of globallyDisabledChords(options.keybindings)) {
+        if (!HARDCODED_CHORDS.has(chord))
+            claimed.delete(chord);
+    }
+    return claimed;
+}
+/**
+ * True when `chords` claims this keystroke, under the editor's own normalization — Ctrl and
+ * Cmd both fold to `Mod`, so a consumer never re-derives the platform rule.
+ */
+export function chordIsClaimed(event, chords) {
+    const chord = eventToChord(event);
+    return chord !== null && chords.has(chord);
+}
+/** Modifier-carrying, so the fixed-order normal form puts something before the key. */
+function carriesModifier(chord) {
+    return chord.includes('+');
+}
+function registeredKeymapChords() {
+    return getAllRegisteredKinds().flatMap((kind) => tryGetBlockKindDescriptor(kind)?.keymap?.map((binding) => binding.chord) ?? []);
+}
+function overrideBoundChords(overrides) {
+    if (!overrides)
+        return [];
+    return [overrides.global, ...overrides.byKind.values()].flatMap((scope) => [...scope].filter(([, value]) => value !== 'disabled').map(([chord]) => chord));
+}
+function globallyDisabledChords(overrides) {
+    if (!overrides)
+        return [];
+    return [...overrides.global].filter(([, value]) => value === 'disabled').map(([chord]) => chord);
+}

package/dist/schema/reserved-chrome.d.ts

@@ -0,0 +1,23 @@
+import type { AnyBlockKind } from '../core/nodes';
+import type { NodeView } from '../core/node-views';
+import { type BlockKindDescriptor } from './block-kind-descriptor';
+/**
+ * Reserved-chrome predicates: the declaration-driven surface the model layer dispatches on
+ * instead of a plugin kind name. These read a container's `reservedChrome` declaration, never
+ * a hard-coded kind.
+ */
+/** The reserved chrome kind a container declares, or undefined if it declares none. */
+export declare function reservedChromeKindOf(containerKind: AnyBlockKind): AnyBlockKind | undefined;
+/** True when `childIndex` is the reserved chrome slot (index 0) of a chrome-declaring container. */
+export declare function isReservedChromeChild(container: NodeView, childIndex: number): boolean;
+/** True only when the kind declares an `isCollapsed` probe and it reports this node collapsed. */
+export declare function isCollapsedContainer(node: NodeView): boolean;
+/** The same reading for a caller already holding the descriptor — the height oracle's per-node
+ *  path, where a second registry lookup is one per block of the document. */
+export declare function isCollapsedByDescriptor(descriptor: BlockKindDescriptor | undefined, node: NodeView): boolean;
+/**
+ * The metadata patch that expands `node`, or null when its kind declares no door. Sibling of
+ * `isCollapsedContainer` over the same declaration, so the clamp that hides a body and the
+ * reveal that opens it cannot disagree about which containers collapse.
+ */
+export declare function expandContainerPatch(node: NodeView): Record<string, unknown> | null;

package/dist/schema/reserved-chrome.js

@@ -0,0 +1,33 @@
+import { tryGetBlockKindDescriptor } from './block-kind-descriptor';
+/**
+ * Reserved-chrome predicates: the declaration-driven surface the model layer dispatches on
+ * instead of a plugin kind name. These read a container's `reservedChrome` declaration, never
+ * a hard-coded kind.
+ */
+/** The reserved chrome kind a container declares, or undefined if it declares none. */
+export function reservedChromeKindOf(containerKind) {
+    return tryGetBlockKindDescriptor(containerKind)?.reservedChrome?.kind;
+}
+/** True when `childIndex` is the reserved chrome slot (index 0) of a chrome-declaring container. */
+export function isReservedChromeChild(container, childIndex) {
+    return childIndex === 0 && reservedChromeKindOf(container.kind) !== undefined;
+}
+/** True only when the kind declares an `isCollapsed` probe and it reports this node collapsed. */
+export function isCollapsedContainer(node) {
+    return isCollapsedByDescriptor(tryGetBlockKindDescriptor(node.kind), node);
+}
+/** The same reading for a caller already holding the descriptor — the height oracle's per-node
+ *  path, where a second registry lookup is one per block of the document. */
+export function isCollapsedByDescriptor(descriptor, node) {
+    const probe = descriptor?.reservedChrome?.isCollapsed;
+    return probe !== undefined && probe(node);
+}
+/**
+ * The metadata patch that expands `node`, or null when its kind declares no door. Sibling of
+ * `isCollapsedContainer` over the same declaration, so the clamp that hides a body and the
+ * reveal that opens it cannot disagree about which containers collapse.
+ */
+export function expandContainerPatch(node) {
+    const door = tryGetBlockKindDescriptor(node.kind)?.reservedChrome?.expandPatch;
+    return door?.(node) ?? null;
+}

package/dist/schema/table-cell-raw.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The tableCell raw-write rule, declared on the kind as `normalizeRawWrite` and applied at the
+ * write sink (`tree-operations/node-ops.updateNodeContent`). A cell's bytes are joined verbatim
+ * into its row, and the parser truncates a row reparsing wider than the delimiter's column
+ * count, so a bare `|` or line break reaching a cell raw deletes the last column's content.
+ * Both passes are prefix-composable, which is what makes `escapedCellOffset` an exact caret image.
+ */
+/**
+ * Escape every `|` not already freed by an odd run of backslashes. Idempotent: the freeing
+ * backslash usually comes from text the writer never touched, so a re-run must be a no-op.
+ */
+export declare function escapeUnescapedPipes(s: string): string;
+/** Text made legal as a cell's `raw`: no line break, no unescaped delimiter. */
+export declare function normalizeCellRaw(raw: string): string;

package/dist/schema/table-cell-raw.js

@@ -0,0 +1,30 @@
+/**
+ * The tableCell raw-write rule, declared on the kind as `normalizeRawWrite` and applied at the
+ * write sink (`tree-operations/node-ops.updateNodeContent`). A cell's bytes are joined verbatim
+ * into its row, and the parser truncates a row reparsing wider than the delimiter's column
+ * count, so a bare `|` or line break reaching a cell raw deletes the last column's content.
+ * Both passes are prefix-composable, which is what makes `escapedCellOffset` an exact caret image.
+ */
+/**
+ * Escape every `|` not already freed by an odd run of backslashes. Idempotent: the freeing
+ * backslash usually comes from text the writer never touched, so a re-run must be a no-op.
+ */
+export function escapeUnescapedPipes(s) {
+    let out = '';
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        if (ch !== '|') {
+            out += ch;
+            continue;
+        }
+        let backslashes = 0;
+        for (let j = i - 1; j >= 0 && s[j] === '\\'; j--)
+            backslashes++;
+        out += backslashes % 2 === 0 ? '\\|' : '|';
+    }
+    return out;
+}
+/** Text made legal as a cell's `raw`: no line break, no unescaped delimiter. */
+export function normalizeCellRaw(raw) {
+    return escapeUnescapedPipes(raw.replace(/\r?\n/g, ' '));
+}

package/dist/schema/whole-block-unit.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The kind class with no character positions: `blockFocus: 'whole-block'` declares the opaque
+ * focus-then-delete model, and no children means no inner surface either, so the rendered body
+ * (an SVG, a toolbar) is chrome rather than the block's bytes. Its only addressable offsets are
+ * 0 and `displayLength(raw)`; `selection/char-endpoint-snap.ts` is what holds selection to them.
+ */
+import type { NodeView } from '../core/node-views';
+export declare function isWholeBlockUnit(node: NodeView): boolean;

package/dist/schema/whole-block-unit.js

@@ -0,0 +1,12 @@
+/**
+ * The kind class with no character positions: `blockFocus: 'whole-block'` declares the opaque
+ * focus-then-delete model, and no children means no inner surface either, so the rendered body
+ * (an SVG, a toolbar) is chrome rather than the block's bytes. Its only addressable offsets are
+ * 0 and `displayLength(raw)`; `selection/char-endpoint-snap.ts` is what holds selection to them.
+ */
+import { tryGetBlockKindDescriptor } from './block-kind-descriptor';
+export function isWholeBlockUnit(node) {
+    if ((node.children?.length ?? 0) !== 0)
+        return false;
+    return tryGetBlockKindDescriptor(node.kind)?.blockFocus === 'whole-block';
+}

package/dist/search/document-scan.d.ts

@@ -0,0 +1,22 @@
+import type { DocumentView } from '../core/node-views';
+import type { CompiledMatcher, RawRange } from './matcher';
+/** `start`/`end` are raw offsets into the matched block's own raw (public
+ *  surface, so they stay `number`; DOM entry points mint). */
+export interface Match {
+    path: number[];
+    start: number;
+    end: number;
+    groups?: string[];
+}
+/** One searchable leaf: the text a scan reads and the path its matches carry. */
+export interface ScanTarget {
+    path: number[];
+    raw: string;
+}
+/** The searchable leaves in document order. Split out from matching so one target list can
+ *  be matched here or shipped to the off-thread executor and re-joined against its ranges. */
+export declare function collectScanTargets(doc: DocumentView): ScanTarget[];
+/** Joins per-target ranges back onto their paths, positionally — the ranges must
+ *  come from the same target list, in the same order. */
+export declare function matchesFromRanges(targets: readonly ScanTarget[], perTarget: readonly RawRange[][]): Match[];
+export declare function scanDocument(doc: DocumentView, matcher: CompiledMatcher): Match[];

package/dist/search/document-scan.js

@@ -0,0 +1,39 @@
+import { getBlockKindDescriptor } from '../schema/block-kind-descriptor';
+// A childless opaque container has no leaves to carry its text, so its own raw matches like
+// a leaf. Strip/grid containers stay walk-only even when empty: their raw is marker syntax.
+const scansOwnRaw = (node, desc) => desc.containerContract === 'opaque' && (node.children?.length ?? 0) === 0;
+/** The searchable leaves in document order. Split out from matching so one target list can
+ *  be matched here or shipped to the off-thread executor and re-joined against its ranges. */
+export function collectScanTargets(doc) {
+    const out = [];
+    const walk = (nodes, prefix) => {
+        nodes.forEach((node, i) => {
+            const path = [...prefix, i];
+            const desc = getBlockKindDescriptor(node.kind);
+            if (desc.isContainer && !scansOwnRaw(node, desc)) {
+                walk(node.children ?? [], path);
+                return; // container raw duplicates child content; only leaves carry text
+            }
+            if (!desc.editable)
+                return; // thematicBreak and other non-editable kinds have no searchable text
+            out.push({ path, raw: node.raw });
+        });
+    };
+    walk(doc.children, []);
+    return out;
+}
+/** Joins per-target ranges back onto their paths, positionally — the ranges must
+ *  come from the same target list, in the same order. */
+export function matchesFromRanges(targets, perTarget) {
+    const out = [];
+    targets.forEach((target, i) => {
+        for (const r of perTarget[i] ?? []) {
+            out.push({ path: target.path, start: r.start, end: r.end, groups: r.groups });
+        }
+    });
+    return out;
+}
+export function scanDocument(doc, matcher) {
+    const targets = collectScanTargets(doc);
+    return matchesFromRanges(targets, targets.map((t) => matcher.findAll(t.raw)));
+}

package/dist/search/matcher.d.ts

@@ -0,0 +1,31 @@
+export interface MatcherOptions {
+    caseSensitive: boolean;
+    wholeWord: boolean;
+    regex: boolean;
+}
+export interface RawRange {
+    start: number;
+    end: number;
+    groups?: string[];
+}
+export interface CompiledMatcher {
+    findAll(text: string): RawRange[];
+}
+export type CompileResult = {
+    ok: true;
+    matcher: CompiledMatcher;
+} | {
+    ok: false;
+    error: string;
+};
+/** What a regex-mode query compiles to. The off-thread executor searches the same
+ *  language as the synchronous matcher because both mint the spec here. */
+export interface RegexSpec {
+    pattern: string;
+    flags: string;
+}
+export declare function buildRegexSpec(query: string, opts: MatcherOptions): RegexSpec;
+/** Every match of an already-compiled global regex. The scan worker ships as source text
+ *  and cannot import, so it carries its own copy, pinned to this one by a parity test. */
+export declare function execAll(re: RegExp, text: string): RawRange[];
+export declare function compileMatcher(query: string, opts: MatcherOptions): CompileResult;

package/dist/search/matcher.js

@@ -0,0 +1,70 @@
+export function buildRegexSpec(query, opts) {
+    return {
+        pattern: opts.wholeWord ? `\\b(?:${query})\\b` : query,
+        // no 's'/'m': . excludes newline, ^/$ stay per-block
+        flags: opts.caseSensitive ? 'g' : 'gi'
+    };
+}
+/** Every match of an already-compiled global regex. The scan worker ships as source text
+ *  and cannot import, so it carries its own copy, pinned to this one by a parity test. */
+export function execAll(re, text) {
+    const out = [];
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        out.push({ start: m.index, end: m.index + m[0].length, groups: [...m] });
+        if (m.index === re.lastIndex)
+            re.lastIndex++; // zero-width guard
+    }
+    return out;
+}
+const isWordChar = (ch) => !!ch && /\w/.test(ch);
+export function compileMatcher(query, opts) {
+    if (query === '')
+        return { ok: true, matcher: { findAll: () => [] } };
+    if (opts.regex) {
+        const { pattern, flags } = buildRegexSpec(query, opts);
+        let re;
+        try {
+            re = new RegExp(pattern, flags);
+        }
+        catch (e) {
+            return { ok: false, error: e instanceof Error ? e.message : 'invalid pattern' };
+        }
+        return { ok: true, matcher: { findAll: (text) => execAll(re, text) } };
+    }
+    const needle = opts.caseSensitive ? query : query.toLowerCase();
+    return {
+        ok: true,
+        matcher: {
+            findAll(text) {
+                const hay = opts.caseSensitive ? text : text.toLowerCase();
+                // Case folding is not length-preserving ('İ' → 2 code units), so a folded
+                // haystack's indices can drift off the original string.
+                if (hay.length !== text.length)
+                    return foldSafeFindAll(text, query, opts.wholeWord);
+                const out = [];
+                let from = 0;
+                let at;
+                while ((at = hay.indexOf(needle, from)) !== -1) {
+                    const end = at + needle.length;
+                    if (!opts.wholeWord || (!isWordChar(text[at - 1]) && !isWordChar(text[end]))) {
+                        out.push({ start: at, end });
+                    }
+                    from = end;
+                }
+                return out;
+            }
+        }
+    };
+}
+function foldSafeFindAll(text, query, wholeWord) {
+    const escaped = query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(wholeWord ? `\\b(?:${escaped})\\b` : escaped, 'gi');
+    const out = [];
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        out.push({ start: m.index, end: m.index + m[0].length });
+    }
+    return out;
+}

package/dist/search/regex-executor.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Bounds regex find. A pathological pattern spends minutes inside ONE `RegExp.exec`, which
+ * no main-thread budget can interrupt, so the only bound is a killable thread. The worker
+ * ships as source text through a Blob URL, not a bundler worker import, leaving dist
+ * packaging and consumer bundlers untouched. Where that is unavailable (SSR, a CSP-restricted
+ * embedder, the test runner) it degrades to a sync scan bounded only BETWEEN texts.
+ */
+import { type RawRange } from './matcher';
+/** Wall-clock ceiling for one scan: long enough for an honest regex over a large document,
+ *  short enough that overrun reads as a stall rather than a freeze. */
+export declare const REGEX_SCAN_DEADLINE_MS = 2000;
+export interface RegexScanRequest {
+    readonly texts: readonly string[];
+    readonly pattern: string;
+    readonly flags: string;
+    /** Correlation token, echoed back untouched, so the caller can drop a stale outcome. */
+    readonly epoch: number;
+}
+/** `cancelled` covers supersession and release alike — nothing to report either way. */
+export type RegexScanFailure = 'timeout' | 'error' | 'cancelled';
+export type RegexScanOutcome = {
+    ok: true;
+    epoch: number;
+    ranges: RawRange[][];
+} | {
+    ok: false;
+    epoch: number;
+    reason: RegexScanFailure;
+};
+export interface RegexExecutor {
+    /** Never rejects; every failure arrives as an `ok: false` outcome. Single-flight: a new
+     *  scan supersedes the one in flight rather than queueing behind a never-returning exec. */
+    scan(request: RegexScanRequest): Promise<RegexScanOutcome>;
+    /** Terminates the live worker; the next scan respawns one. */
+    release(): void;
+}
+export interface RegexExecutorOptions {
+    deadlineMs?: number;
+}
+export declare const regexScanWorkerSource = "\nself.onmessage = (event) => {\n\tconst { texts, pattern, flags, epoch } = event.data;\n\tlet re;\n\ttry {\n\t\tre = new RegExp(pattern, flags);\n\t} catch {\n\t\tself.postMessage({ epoch, ok: false });\n\t\treturn;\n\t}\n\tconst ranges = [];\n\tfor (const text of texts) {\n\t\tconst found = [];\n\t\tre.lastIndex = 0;\n\t\tlet m;\n\t\twhile ((m = re.exec(text)) !== null) {\n\t\t\tfound.push({ start: m.index, end: m.index + m[0].length, groups: [...m] });\n\t\t\tif (m.index === re.lastIndex) re.lastIndex++;\n\t\t}\n\t\tranges.push(found);\n\t}\n\tself.postMessage({ epoch, ok: true, ranges });\n};\n";
+export declare function createRegexExecutor(options?: RegexExecutorOptions): RegexExecutor;