@voithos-labs/aragonite 0.10.1

package/dist/search/regex-executor.js

@@ -0,0 +1,165 @@
+/**
+ * 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 { execAll } 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 const REGEX_SCAN_DEADLINE_MS = 2000;
+// ── Worker ───────────────────────────────────────────────────────────────────
+// Self-contained by necessity: a Blob worker has no module graph, so this repeats
+// `execAll`'s loop. `test/search/regex-worker-parity.test.ts` fails the day they diverge.
+export const regexScanWorkerSource = `
+self.onmessage = (event) => {
+	const { texts, pattern, flags, epoch } = event.data;
+	let re;
+	try {
+		re = new RegExp(pattern, flags);
+	} catch {
+		self.postMessage({ epoch, ok: false });
+		return;
+	}
+	const ranges = [];
+	for (const text of texts) {
+		const found = [];
+		re.lastIndex = 0;
+		let m;
+		while ((m = re.exec(text)) !== null) {
+			found.push({ start: m.index, end: m.index + m[0].length, groups: [...m] });
+			if (m.index === re.lastIndex) re.lastIndex++;
+		}
+		ranges.push(found);
+	}
+	self.postMessage({ epoch, ok: true, ranges });
+};
+`;
+// ── Executor ─────────────────────────────────────────────────────────────────
+export function createRegexExecutor(options = {}) {
+    const deadlineMs = options.deadlineMs ?? REGEX_SCAN_DEADLINE_MS;
+    let worker = null;
+    let workerUnavailable = false;
+    let pending = null;
+    let deadline = null;
+    function clearDeadline() {
+        if (deadline === null)
+            return;
+        clearTimeout(deadline);
+        deadline = null;
+    }
+    function killWorker() {
+        clearDeadline();
+        worker?.terminate();
+        worker = null;
+    }
+    function settle(outcome) {
+        const settled = pending;
+        pending = null;
+        clearDeadline();
+        settled?.resolve(outcome);
+    }
+    function abandonPending() {
+        if (!pending)
+            return;
+        const { epoch } = pending;
+        // The worker is inside an exec that cannot be asked to stop; termination is the
+        // only way to free the thread for the next scan.
+        killWorker();
+        settle({ ok: false, epoch, reason: 'cancelled' });
+    }
+    function ensureWorker() {
+        if (worker)
+            return worker;
+        if (workerUnavailable)
+            return null;
+        if (typeof Worker === 'undefined' ||
+            typeof Blob === 'undefined' ||
+            typeof URL === 'undefined' ||
+            typeof URL.createObjectURL !== 'function') {
+            workerUnavailable = true;
+            return null;
+        }
+        try {
+            const url = URL.createObjectURL(new Blob([regexScanWorkerSource], { type: 'text/javascript' }));
+            worker = new Worker(url);
+            URL.revokeObjectURL(url); // the worker holds its own reference past revocation
+            return worker;
+        }
+        catch {
+            // A CSP without `worker-src blob:` throws here. Latch, or every later scan pays
+            // the same construction cost to fail the same way.
+            workerUnavailable = true;
+            return null;
+        }
+    }
+    function runOnWorker(request, target) {
+        return new Promise((resolve) => {
+            pending = { epoch: request.epoch, resolve };
+            target.onmessage = (event) => {
+                const reply = event.data;
+                if (!pending || reply.epoch !== pending.epoch)
+                    return; // a killed worker's late reply
+                settle(reply.ok && reply.ranges
+                    ? { ok: true, epoch: reply.epoch, ranges: reply.ranges }
+                    : { ok: false, epoch: reply.epoch, reason: 'error' });
+            };
+            // An uncompilable pattern is caught inside the worker and posted back, so reaching
+            // here means the worker itself is broken (a CSP blocking the blob at load, not at
+            // construction). Latch, or regex search stays dead instead of degrading to sync.
+            const fail = () => {
+                const epoch = pending?.epoch ?? request.epoch;
+                workerUnavailable = true;
+                killWorker();
+                settle({ ok: false, epoch, reason: 'error' });
+            };
+            target.onerror = fail;
+            target.onmessageerror = fail;
+            deadline = setTimeout(() => {
+                const epoch = pending?.epoch ?? request.epoch;
+                killWorker();
+                settle({ ok: false, epoch, reason: 'timeout' });
+            }, deadlineMs);
+            target.postMessage({
+                texts: request.texts,
+                pattern: request.pattern,
+                flags: request.flags,
+                epoch: request.epoch
+            });
+        });
+    }
+    function scanSync(request) {
+        let re;
+        try {
+            re = new RegExp(request.pattern, request.flags);
+        }
+        catch {
+            return { ok: false, epoch: request.epoch, reason: 'error' };
+        }
+        const startedAt = Date.now();
+        const ranges = [];
+        for (let i = 0; i < request.texts.length; i++) {
+            // Between texts is the only place this path can bail, and checking before any
+            // work would be vacuous, so the first text always runs.
+            if (i > 0 && Date.now() - startedAt > deadlineMs) {
+                return { ok: false, epoch: request.epoch, reason: 'timeout' };
+            }
+            ranges.push(execAll(re, request.texts[i]));
+        }
+        return { ok: true, epoch: request.epoch, ranges };
+    }
+    return {
+        scan(request) {
+            abandonPending();
+            const target = ensureWorker();
+            if (!target)
+                return Promise.resolve(scanSync(request));
+            return runOnWorker(request, target);
+        },
+        release() {
+            abandonPending();
+            killWorker();
+        }
+    };
+}

package/dist/search/replace.d.ts

@@ -0,0 +1,15 @@
+/** Expand `$1`..`$9`, `$&`/`$0`, `$$`, and `\n`/`\t`/`\\` escapes against a regex match's
+ *  groups; literal mode passes `undefined` groups and is verbatim. A single-line replace
+ *  input can't carry a real newline, so escapes are regex-mode only, matching VS Code. */
+export declare function expandReplacement(template: string, groups: string[] | undefined): string;
+export interface ReplaceRange {
+    start: number;
+    end: number;
+    groups?: string[];
+}
+/**
+ * Apply ranges to `text`, substituting right-to-left so earlier offsets stay valid. No
+ * per-replacement escape hook: a structural leaf's delimiters escape over the WHOLE
+ * post-splice raw, so that is the caller's `toLegalRaw` pass over the result.
+ */
+export declare function applyRangesToText(text: string, ranges: ReplaceRange[], template: string): string;

package/dist/search/replace.js

@@ -0,0 +1,29 @@
+/** Expand `$1`..`$9`, `$&`/`$0`, `$$`, and `\n`/`\t`/`\\` escapes against a regex match's
+ *  groups; literal mode passes `undefined` groups and is verbatim. A single-line replace
+ *  input can't carry a real newline, so escapes are regex-mode only, matching VS Code. */
+export function expandReplacement(template, groups) {
+    if (!groups)
+        return template;
+    return template.replace(/\\([nt\\])|\$(\$|&|\d+)/g, (_, esc, token) => {
+        if (esc)
+            return esc === 'n' ? '\n' : esc === 't' ? '\t' : '\\';
+        if (token === '$')
+            return '$';
+        if (token === '&')
+            return groups[0] ?? '';
+        return groups[Number(token)] ?? '';
+    });
+}
+/**
+ * Apply ranges to `text`, substituting right-to-left so earlier offsets stay valid. No
+ * per-replacement escape hook: a structural leaf's delimiters escape over the WHOLE
+ * post-splice raw, so that is the caller's `toLegalRaw` pass over the result.
+ */
+export function applyRangesToText(text, ranges, template) {
+    let out = text;
+    const ordered = [...ranges].sort((a, b) => b.start - a.start);
+    for (const r of ordered) {
+        out = out.slice(0, r.start) + expandReplacement(template, r.groups) + out.slice(r.end);
+    }
+    return out;
+}

package/dist/search/search-state.svelte.d.ts

@@ -0,0 +1,59 @@
+import type { DocumentView } from '../core/node-views';
+import { type Match } from './document-scan';
+import { type RegexExecutor } from './regex-executor';
+import type { DecorationRegistry } from '../decorations/types';
+export interface SearchOptions {
+    caseSensitive: boolean;
+    wholeWord: boolean;
+    regex: boolean;
+}
+/** A match paired with its flat-list position — what the active highlight compares
+ *  against `activeIndex`. */
+export interface IndexedMatch {
+    match: Match;
+    index: number;
+}
+interface SearchDeps {
+    getDoc: () => DocumentView;
+    /** Bumped when the whole document is REPLACED, never on an in-place edit or undo —
+     *  those leave the tree under a position the user still owns. */
+    getDocumentGeneration: () => number;
+    /** Highlights ship as marks under source 'editor:search', registered on open and
+     *  disposed on close, so a closed bar costs nothing. */
+    decorations: DecorationRegistry;
+    replace: {
+        replaceOne(m: Match, t: string): Promise<number>;
+        replaceAll(m: Match[], t: string): Promise<number>;
+    };
+    reveal: (path: number[]) => Promise<unknown>;
+    /** Test seam; production builds the worker-backed executor internally. */
+    regexExecutor?: RegexExecutor;
+    onClose: () => void;
+}
+export declare function createSearchState(deps: SearchDeps): SearchState;
+/** Public controller surface — what `editor.getSearch()` exposes. Deliberately minimal:
+ *  adding a member later is non-breaking, removing one is not. */
+export interface SearchState {
+    readonly isOpen: boolean;
+    readonly query: string;
+    readonly replacement: string;
+    readonly options: SearchOptions;
+    readonly matches: Match[];
+    /** Matches owned by `path`'s leaf, grouped once per rescan so readers skip the scan. */
+    matchesForPath(path: number[]): IndexedMatch[];
+    readonly activeIndex: number;
+    readonly error: string | null;
+    /** True while a regex scan is off the main thread; literal search never sets it. */
+    readonly isScanning: boolean;
+    readonly replacedCount: number | null;
+    open(): void;
+    close(): void;
+    setQuery(q: string): void;
+    setReplacement(s: string): void;
+    setOptions(partial: Partial<SearchOptions>): void;
+    next(): void;
+    prev(): void;
+    replaceCurrent(): Promise<void>;
+    replaceAll(): Promise<void>;
+}
+export {};

package/dist/search/search-state.svelte.js

@@ -0,0 +1,231 @@
+import { buildRegexSpec, compileMatcher } from './matcher';
+import { collectScanTargets, matchesFromRanges, scanDocument } from './document-scan';
+import { createRegexExecutor } from './regex-executor';
+import { groupByPathKey, pathKey } from '../decorations/buckets';
+const EMPTY_MATCHES = [];
+// Both reuse the invalid-regex readout: a scan with no usable answer is one state to the
+// reader, whatever ended it.
+const REGEX_TOO_SLOW = 'Regex too slow';
+const REGEX_SCAN_FAILED = 'Regex search failed';
+export function createSearchState(deps) {
+    let isOpen = $state(false);
+    let query = $state('');
+    let replacement = $state('');
+    let options = $state({ caseSensitive: false, wholeWord: false, regex: false });
+    let matches = $state([]);
+    // One grouping per rescan, shared by every matchesForPath read.
+    const matchesByPath = $derived(groupByPathKey(matches, (match, index) => ({ match, index })));
+    let activeIndex = $state(0);
+    let error = $state(null);
+    // Cleared on the next search ACTION, not in rescan — the engine's post-commit re-run
+    // would otherwise wipe it instantly.
+    let replacedCount = $state(null);
+    // A regex scan lands asynchronously, so `matches` can trail the query that asked for
+    // it. `scanEpoch` is the drop token: every rescan and close bumps it, and an outcome
+    // tagged with a spent epoch is discarded.
+    let scanning = $state(false);
+    let scanEpoch = 0;
+    let pendingScan = null;
+    const regexExecutor = deps.regexExecutor ?? createRegexExecutor();
+    let lastGeneration = deps.getDocumentGeneration();
+    let handle = null;
+    // The scan runs for its side effects, so only the CURRENT key may skip it; cleared on
+    // close() so a reopen at the same key rescans rather than serving the empty set.
+    let lastScanKey = null;
+    // Keyed on editEpoch, NEVER doc.children identity: typing mutates children in place, so
+    // identity only changes on structural commits and would serve stale matches.
+    function provide(doc, ctx) {
+        const { caseSensitive, wholeWord, regex } = options;
+        const key = `${ctx.editEpoch}\0${+caseSensitive}${+wholeWord}${+regex}\0${query}`;
+        if (key !== lastScanKey) {
+            // Scan the document the registry is providing FOR, not whatever the deps getter
+            // resolves to — the plugin guide points decoration authors at this file.
+            rescan(doc);
+            lastScanKey = key;
+        }
+        return matches.map((m, i) => ({
+            type: 'mark',
+            path: m.path,
+            start: m.start,
+            end: m.end,
+            class: i === activeIndex ? 'match-overlay match-overlay-active' : 'match-overlay'
+        }));
+    }
+    function rescan(doc = deps.getDoc()) {
+        // A whole-document REPLACEMENT restarts navigation at the first match: the carried
+        // position indexes a document the user never navigated. Edits, undo and option
+        // toggles leave the user where they were, so they fall through to applyMatches' clamp.
+        const generation = deps.getDocumentGeneration();
+        const documentReplaced = generation !== lastGeneration;
+        lastGeneration = generation;
+        scanEpoch++;
+        pendingScan = null;
+        scanning = false;
+        if (documentReplaced)
+            activeIndex = 0;
+        const r = compileMatcher(query, options);
+        if (!r.ok) {
+            failScan(r.error);
+            return;
+        }
+        error = null;
+        if (options.regex && query !== '') {
+            startRegexScan(doc);
+            return;
+        }
+        applyMatches(scanDocument(doc, r.matcher));
+    }
+    function applyMatches(found) {
+        matches = found;
+        if (activeIndex >= matches.length)
+            activeIndex = 0;
+    }
+    function failScan(message) {
+        error = message;
+        matches = [];
+        activeIndex = 0;
+    }
+    // Regex is the only path that can run away, so the only one that leaves the main thread.
+    // Matches clear at kickoff so stale overlays don't sit over the document mid-scan.
+    function startRegexScan(doc) {
+        const epoch = scanEpoch;
+        const targets = collectScanTargets(doc);
+        const { pattern, flags } = buildRegexSpec(query, options);
+        matches = [];
+        scanning = true;
+        pendingScan = regexExecutor
+            .scan({ texts: targets.map((t) => t.raw), pattern, flags, epoch })
+            .then((outcome) => {
+            if (epoch !== scanEpoch)
+                return; // a newer scan, or a close, owns the state now
+            if (!outcome.ok && outcome.reason === 'cancelled')
+                return;
+            scanning = false;
+            pendingScan = null;
+            if (outcome.ok)
+                applyMatches(matchesFromRanges(targets, outcome.ranges));
+            else
+                failScan(outcome.reason === 'timeout' ? REGEX_TOO_SLOW : REGEX_SCAN_FAILED);
+            // invalidate, not refresh(): refresh's no-handle fallback re-runs rescan, which
+            // would start a second scan from inside this one's completion.
+            handle?.invalidate();
+        });
+    }
+    // Every state change routes through the engine so the published marks follow. invalidate
+    // is synchronous by contract, so setQuery's callers still observe fresh matches on
+    // return; the no-handle fallback keeps the headless setQuery-before-open path scanning.
+    function refresh() {
+        if (handle)
+            handle.invalidate();
+        else
+            rescan();
+    }
+    /** Walk the match list, wrapping at either end. */
+    function step(delta) {
+        replacedCount = null;
+        if (!matches.length)
+            return;
+        activeIndex = (activeIndex + delta + matches.length) % matches.length;
+        refresh();
+        void revealActive();
+    }
+    async function revealActive() {
+        await pendingScan; // a regex scan lands async; reveal the match we will actually show
+        const m = matches[activeIndex];
+        if (m)
+            await deps.reveal(m.path);
+    }
+    return {
+        get isOpen() {
+            return isOpen;
+        },
+        get query() {
+            return query;
+        },
+        get replacement() {
+            return replacement;
+        },
+        get options() {
+            return options;
+        },
+        get matches() {
+            return matches;
+        },
+        matchesForPath(path) {
+            return matchesByPath.get(pathKey(path)) ?? EMPTY_MATCHES;
+        },
+        get activeIndex() {
+            return activeIndex;
+        },
+        get error() {
+            return error;
+        },
+        get isScanning() {
+            return scanning;
+        },
+        get replacedCount() {
+            return replacedCount;
+        },
+        open() {
+            if (isOpen)
+                return; // Ctrl+H over an open find bar reuses the live source
+            isOpen = true;
+            handle = deps.decorations.addSource({ name: 'editor:search', provide });
+        },
+        close() {
+            isOpen = false;
+            handle?.dispose();
+            handle = null;
+            matches = [];
+            replacedCount = null;
+            // Bump before releasing: a scan settling after close must find its epoch spent.
+            scanEpoch++;
+            scanning = false;
+            pendingScan = null;
+            regexExecutor.release();
+            lastScanKey = null;
+            deps.onClose();
+        },
+        setQuery(q) {
+            // A new query restarts navigation; option toggles keep the position instead.
+            if (q !== query)
+                activeIndex = 0;
+            query = q;
+            replacedCount = null;
+            refresh();
+            void revealActive();
+        },
+        setReplacement(s) {
+            replacement = s;
+        },
+        setOptions(partial) {
+            options = { ...options, ...partial };
+            replacedCount = null;
+            refresh();
+            void revealActive();
+        },
+        next: () => step(1),
+        prev: () => step(-1),
+        async replaceCurrent() {
+            await pendingScan; // regex matches land async; replacing needs the settled set
+            const m = matches[activeIndex];
+            if (!m)
+                return;
+            const n = await deps.replace.replaceOne(m, replacement);
+            // The edit-epoch bump is deferred, so an invalidate-only refresh would hit the
+            // memo and republish the pre-replace matches.
+            rescan();
+            refresh();
+            replacedCount = n;
+        },
+        async replaceAll() {
+            await pendingScan;
+            if (!matches.length)
+                return;
+            const n = await deps.replace.replaceAll(matches, replacement);
+            rescan();
+            refresh();
+            replacedCount = n;
+        }
+    };
+}

package/dist/selection/autoscroll.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Pointer-edge autoscroll RAF loop, shared between cross-block and intra-table drag. The caller
+ * supplies the live pointer and the scroll targets to evaluate each frame. A target may be the
+ * window (`cursor/scroll-ancestors`), which answers the two halves from different places on
+ * purpose: measure the viewport, write `document.scrollingElement`. Using the scrolling element
+ * for both puts the document's own multi-thousand-pixel box into the edge math.
+ */
+import type { UserScrollport } from '../cursor/scroll-ancestors';
+export interface AutoScrollDeps {
+    getPointer: () => {
+        clientX: number;
+        clientY: number;
+    } | null;
+    getTargets: (clientX: number, clientY: number) => UserScrollport[];
+    onScrolled?: () => void;
+    /**
+     * Restrict scrolling to one axis (default both). The column reorder drag pins the pointer in
+     * the table's top band, where vertical evaluation would spin on a horizontal-only scroller.
+     */
+    axis?: 'horizontal' | 'vertical' | 'both';
+}
+export interface AutoScrollHandle {
+    maybeStart(): void;
+    dispose(): void;
+}
+export declare function createAutoScroll(deps: AutoScrollDeps): AutoScrollHandle;

package/dist/selection/autoscroll.js

@@ -0,0 +1,91 @@
+const EDGE_THRESHOLD_PX = 30;
+function scrollportOf(target) {
+    if (target !== window)
+        return target.getBoundingClientRect();
+    // clientWidth/clientHeight, not innerWidth/innerHeight: the viewport without its
+    // scrollbars, which is the box the pointer's edge band belongs to.
+    const doc = document.documentElement;
+    return { left: 0, top: 0, right: doc.clientWidth, bottom: doc.clientHeight };
+}
+function scrollerOf(target) {
+    return target === window ? document.scrollingElement : target;
+}
+export function createAutoScroll(deps) {
+    const axis = deps.axis ?? 'both';
+    let rafId = null;
+    function dxFor(port, x) {
+        if (axis === 'vertical')
+            return 0;
+        if (x < port.left + EDGE_THRESHOLD_PX)
+            return -((port.left + EDGE_THRESHOLD_PX - x) / 2);
+        if (x > port.right - EDGE_THRESHOLD_PX)
+            return (x - (port.right - EDGE_THRESHOLD_PX)) / 2;
+        return 0;
+    }
+    function dyFor(port, y) {
+        if (axis === 'horizontal')
+            return 0;
+        if (y < port.top + EDGE_THRESHOLD_PX)
+            return -((port.top + EDGE_THRESHOLD_PX - y) / 2);
+        if (y > port.bottom - EDGE_THRESHOLD_PX)
+            return (y - (port.bottom - EDGE_THRESHOLD_PX)) / 2;
+        return 0;
+    }
+    const step = () => {
+        const p = deps.getPointer();
+        if (!p) {
+            rafId = null;
+            return;
+        }
+        let scrolled = false;
+        for (const t of deps.getTargets(p.clientX, p.clientY)) {
+            const port = scrollportOf(t);
+            const dx = dxFor(port, p.clientX);
+            const dy = dyFor(port, p.clientY);
+            const scroller = scrollerOf(t);
+            if (!scroller)
+                continue;
+            // Count only motion that actually moved the target: one already at its scroll limit
+            // ignores the write, and marking it scrolled would spin the rAF loop.
+            if (dx !== 0) {
+                const before = scroller.scrollLeft;
+                scroller.scrollLeft += dx;
+                if (scroller.scrollLeft !== before)
+                    scrolled = true;
+            }
+            if (dy !== 0) {
+                const before = scroller.scrollTop;
+                scroller.scrollTop += dy;
+                if (scroller.scrollTop !== before)
+                    scrolled = true;
+            }
+        }
+        if (!scrolled) {
+            rafId = null;
+            return;
+        }
+        deps.onScrolled?.();
+        rafId = requestAnimationFrame(step);
+    };
+    function maybeStart() {
+        if (rafId !== null)
+            return;
+        const p = deps.getPointer();
+        if (!p)
+            return;
+        const inAnyThreshold = deps.getTargets(p.clientX, p.clientY).some((t) => {
+            const port = scrollportOf(t);
+            return dxFor(port, p.clientX) !== 0 || dyFor(port, p.clientY) !== 0;
+        });
+        if (!inAnyThreshold)
+            return;
+        rafId = requestAnimationFrame(step);
+    }
+    function dispose() {
+        if (rafId !== null) {
+            cancelAnimationFrame(rafId);
+            rafId = null;
+        }
+    }
+    return { maybeStart, dispose };
+}

package/dist/selection/block-hit-test.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Viewport point to the block under it, for pointer hit-testing: walks ancestors of the topmost
+ * element to the nearest `data-block-path` host. A kind with internal coordinate addressing
+ * carries the point→internals hooks its descriptor declares, so a caller resolves a
+ * cell-coordinate point without knowing the kind. What the hit does NOT carry is what a kind
+ * cannot answer: a block with no character surface reports none.
+ */
+import { type CaretTarget } from '../schema/block-kind-descriptor';
+import type { SelectionEndpoint } from './primitives';
+export interface BlockHit {
+    path: number[];
+    /**
+     * The surface a character offset may be hit-tested against, or null when the kind renders
+     * none: a coordinate-addressed grid, and a whole-block kind whose rendered body is chrome.
+     * A caller that character-hit-tests the wrapper instead gets a plausible-but-wrong offset
+     * across the whole subtree rather than a decline.
+     */
+    charSurface: HTMLElement | null;
+    /**
+     * Point→internal-offset hook for kinds with coordinate addressing (a table's row-major
+     * cellIdx). Pre-bound to the block's wrapper, resolved from the kind descriptor.
+     */
+    foreignDragHitTest?: (clientX: number, clientY: number) => number | null;
+    /**
+     * The caret landing inside such a kind, as an internal child path plus offset. A
+     * caret-placing gesture reads this where the drag hook declines.
+     */
+    caretTargetAtPoint?: (clientX: number, clientY: number) => CaretTarget | null;
+}
+export declare function blockAtPoint(editorRoot: HTMLElement, clientX: number, clientY: number): BlockHit | null;
+/**
+ * The selection endpoint a pointer over `hit` addresses: a row-major cell index where the kind
+ * declares the drag hook, a char offset on a character surface, and otherwise the block as a
+ * whole — the selection funnel resolves which of its two ends this side of the range wants.
+ * Shared by both drag consumers, so neither can hit-test characters against a block with none.
+ */
+export declare function endpointAtPoint(hit: BlockHit, clientX: number, clientY: number): SelectionEndpoint | null;