@voithos-labs/aragonite 0.10.1

package/dist/selection/native-bridge.js

@@ -0,0 +1,204 @@
+/**
+ * Bridge between the browser's native Selection API and SelectionPoint. Pure: callers provide
+ * target elements and paths, no tree walking. SelectionPoint offsets are raw-semantic, so
+ * DOM→raw conversion subtracts the length of a leading ambient marker span, whose textContent
+ * counts toward DOM offsets but not raw.
+ */
+import { asRawOffset, toClampedRawOffset, toDomTextOffset } from '../cursor/coordinate-spaces';
+import { clampToLandableRaw, createRangeAtDomTextOffsets, domTextOffsetAtNode } from '../cursor/widget-offset';
+import { ambientLengthOf, placeCaretAfterAmbientSpan } from '../ambient/ambient-dom';
+// ── Read native → SelectionPoint ────────────────────────────────────────────
+/**
+ * Read the collapsed caret inside `blockEl` into a raw-semantic SelectionPoint.
+ * Returns null when the caret isn't inside this element.
+ */
+export function readNativeCaretInBlock(blockEl, path) {
+    if (document.activeElement !== blockEl)
+        return null;
+    const sel = window.getSelection();
+    if (!sel || sel.rangeCount === 0)
+        return null;
+    const range = sel.getRangeAt(0);
+    // The anchor is the fixed end the selection grew from; for a BACKWARD selection it sits at
+    // range.end, so reading range.start would capture the moving focus and drop the highlighted
+    // span. Use the real anchor when it resolves inside this block, else keep range.start.
+    const useAnchor = !sel.isCollapsed && sel.anchorNode !== null && blockEl.contains(sel.anchorNode);
+    const node = useAnchor ? sel.anchorNode : range.startContainer;
+    const nodeOffset = useAnchor ? sel.anchorOffset : range.startOffset;
+    const content = domTextOffsetAtNode(blockEl, node, nodeOffset);
+    return {
+        path: path.slice(),
+        offset: toClampedRawOffset(content, ambientLengthOf(blockEl))
+    };
+}
+// ── Apply SelectionPoint → native ───────────────────────────────────────────
+/**
+ * Place a collapsed native caret at a raw-semantic SelectionPoint, translating through the block's
+ * ambient length. The park door's twin, so the same landable clamp applies: a caret may not sit
+ * past a hidden marker run, whatever offset the caller derived. Only collapsed carets clamp — a
+ * selection may COVER such a run, so `applySingleBlockRange` does not. Raw offset 0 under an
+ * ambient marker goes AFTER the span: Chromium bounces carets out of its contenteditable="false".
+ */
+export function applyCollapsedCaret(blockEl, point) {
+    const ambient = ambientLengthOf(blockEl);
+    const offset = clampToLandableRaw(blockEl, point.offset, ambient);
+    if (ambient > 0 && offset <= 0 && placeCaretAfterAmbientSpan(blockEl))
+        return;
+    const target = toDomTextOffset(asRawOffset(offset), ambient);
+    const range = createRangeAtDomTextOffsets(blockEl, target, target);
+    if (!range)
+        return;
+    const sel = window.getSelection();
+    sel?.removeAllRanges();
+    sel?.addRange(range);
+}
+/**
+ * Resolve `point.path` to its mounted block element and place a focused collapsed caret there.
+ * Returns whether an element was found; a missing target is a no-op.
+ */
+export function focusCollapsedCaret(getBlockElByPath, point) {
+    const blockEl = getBlockElByPath(point.path);
+    if (!blockEl)
+        return false;
+    applyCollapsedCaret(blockEl, point);
+    blockEl.focus();
+    return true;
+}
+export function applySingleBlockRange(blockEl, startOffset, endOffset) {
+    const ambient = ambientLengthOf(blockEl);
+    const range = createRangeAtDomTextOffsets(blockEl, toDomTextOffset(asRawOffset(startOffset), ambient), toDomTextOffset(asRawOffset(endOffset), ambient));
+    if (!range)
+        return;
+    const sel = window.getSelection();
+    sel?.removeAllRanges();
+    sel?.addRange(range);
+}
+export function clearNativeSelection() {
+    window.getSelection()?.removeAllRanges();
+}
+/**
+ * Keep focus inside the editor when an editable block holding it is windowed out; it would
+ * otherwise fall to <body>. The root is non-editable (`tabindex="-1"`), so focusing it creates
+ * no native range to sync. No-op unless this block holds focus and the root is still connected.
+ */
+export function parkFocusOnEditorRoot(blockEl, editorRoot) {
+    if (!blockEl || !editorRoot?.isConnected)
+        return;
+    // preventScroll: the implicit focus scroll would fight the reveal path's, whichever port
+    // owns the scrolling.
+    if (document.activeElement === blockEl)
+        editorRoot.focus({ preventScroll: true });
+}
+// ── Selection read/restore for undo ─────────────────────────────────────────
+/**
+ * Cross-block from SelectionState if active; otherwise the focused block's cursor as a deep
+ * path (via getCursorPosition) or a shallow one. Null when no block reports a cursor.
+ */
+export function readCurrentSelection(selectionState, blockRefs) {
+    if (selectionState.isCrossBlock && selectionState.anchor && selectionState.focus) {
+        return {
+            anchor: copySelectionPoint(selectionState.anchor),
+            focus: copySelectionPoint(selectionState.focus)
+        };
+    }
+    for (let i = 0; i < blockRefs.length; i++) {
+        const ref = blockRefs[i];
+        if (!ref)
+            continue;
+        const pos = ref.getCursorPosition?.();
+        if (pos) {
+            const path = [i, ...pos.path];
+            return nativeRangeInFocusedBlock(path) ?? collapsedSelectionAt(path, pos.offset);
+        }
+        const offset = ref.getCursorOffset();
+        if (offset !== null && offset !== undefined) {
+            return nativeRangeInFocusedBlock([i]) ?? collapsedSelectionAt([i], offset);
+        }
+    }
+    return null;
+}
+function collapsedSelectionAt(path, offset) {
+    return { anchor: { path: path.slice(), offset }, focus: { path: path.slice(), offset } };
+}
+/**
+ * The focused block's native selection as distinct anchor/focus raw offsets, so getSelection()
+ * reports a within-block range instead of collapsing it to the caret. Null when collapsed or
+ * outside the active block. Offsets convert through that block's ambient length.
+ */
+function nativeRangeInFocusedBlock(path) {
+    // Node-env callers (undo snapshot capture in unit tests) have no DOM; fall back to the
+    // single caret offset rather than touching document/window.
+    if (typeof document === 'undefined' || typeof window === 'undefined')
+        return null;
+    const active = document.activeElement;
+    if (!(active instanceof HTMLElement))
+        return null;
+    const sel = window.getSelection();
+    if (!sel || sel.isCollapsed || sel.anchorNode === null || sel.focusNode === null)
+        return null;
+    if (!active.contains(sel.anchorNode) || !active.contains(sel.focusNode))
+        return null;
+    const ambient = ambientLengthOf(active);
+    const anchorOffset = toClampedRawOffset(domTextOffsetAtNode(active, sel.anchorNode, sel.anchorOffset), ambient);
+    const focusOffset = toClampedRawOffset(domTextOffsetAtNode(active, sel.focusNode, sel.focusOffset), ambient);
+    return {
+        anchor: { path: path.slice(), offset: anchorOffset },
+        focus: { path: path.slice(), offset: focusOffset }
+    };
+}
+// A restored table endpoint must keep cellCoordinate, or it skips the whole-row snap and the
+// deep-cell collapse routing; the two-branch copy carries the union variant through undo.
+function copySelectionPoint(point) {
+    if (point.cellCoordinate) {
+        return { path: point.path.slice(), offset: point.offset, cellCoordinate: true };
+    }
+    return { path: point.path.slice(), offset: point.offset };
+}
+/**
+ * Restore an EditorSelection to the DOM: custom-rendered selections (intra-table, cross-block)
+ * route through SelectionState's overlay, same-path prose uses the native selection. State
+ * write and caret landing run inside ONE SelectionState batch, so the single notification
+ * carries the settled selection. False = the target resolved in the model but not in the DOM.
+ */
+export function applySelectionToDom(selection, selectionState, getBlockElByPath) {
+    let placed = false;
+    selectionState.batch(() => {
+        placed = placeRestoredSelection(selection, selectionState, getBlockElByPath);
+        // Announced, not inferred from the arm's own mutation: a restore onto an already-clear
+        // state changes no editor-owned field and still moves the caret subscribers read back.
+        selectionState.announceSelection();
+    });
+    return placed;
+}
+function placeRestoredSelection(selection, selectionState, getBlockElByPath) {
+    // Classify before mutating state so a single-block restore never mints a phantom transient
+    // cross-block state (enterCrossBlock → clear).
+    const route = selectionState.restoreRoute(selection.anchor, selection.focus);
+    if (route === 'collapsed') {
+        selectionState.clear();
+        // Through the landing like the custom arm below: a collapsed CELL point reaches this arm
+        // (equal offsets classify before coordinate space does) carrying a cell index, which a
+        // char walk on the table wrapper would seat somewhere in the grid's rendered text.
+        return focusCollapsedCaret(getBlockElByPath, selectionState.cellLandingFor(selection.anchor));
+    }
+    // No landing translation on this arm: a same-path pair whose block is a table routes 'custom',
+    // so every pair reaching here is a char range on a prose leaf.
+    if (route === 'single-block') {
+        selectionState.clear();
+        const blockEl = getBlockElByPath(selection.anchor.path);
+        if (!blockEl)
+            return false;
+        applySingleBlockRange(blockEl, selection.anchor.offset, selection.focus.offset);
+        blockEl.focus();
+        return true;
+    }
+    // Custom: the overlay paints. Park a collapsed caret in the focus block as a paste/key
+    // dispatch anchor (Chromium otherwise routes paste to <body>). A cell-coordinate focus
+    // addresses the table wrapper by cell index, so park in its deep cell instead.
+    selectionState.enterCrossBlock(selection.anchor, selection.focus);
+    if (focusCollapsedCaret(getBlockElByPath, selectionState.cellLandingFor(selection.focus))) {
+        return true;
+    }
+    clearNativeSelection();
+    return false;
+}

package/dist/selection/nearest-block.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The mounted block nearest a viewport point, and the endpoint that point addresses. A gesture
+ * that must answer EVERY point — the dead-space click, a drag into the margin — resolves an
+ * off-block point through here instead of declining it. The probe point never leaves the module:
+ * a caller hit-testing at its own raw point gets no offset at all on a character surface.
+ * Only mounted blocks are measured; a caller answering for a windowed-out tail reconciles itself.
+ */
+import type { SelectionEndpoint } from './primitives';
+export interface BlockBand {
+    top: number;
+    bottom: number;
+}
+/** One mounted block's path and box. */
+export interface MeasuredBlock {
+    path: number[] | null;
+    rect: DOMRect;
+}
+/** Document order, since bands may nest and every walk over them depends on it. */
+export declare function measureBlocks(root: HTMLElement): MeasuredBlock[];
+/**
+ * The band a `y` belongs to. `belowAll` marks a point past the last band, the end-of-document
+ * gesture, which lands at a trailing corner rather than under its own x. A y in a gap resolves to
+ * the nearest band, so no point is left unanswered. Bands arrive in document order and may nest,
+ * so containment scans forward, outermost wins.
+ */
+export declare function nearestBand(bands: BlockBand[], y: number): {
+    index: number;
+    belowAll: boolean;
+} | null;
+/** The band's own probe point: {@link clampPointIntoBox}, except that `belowAll` takes the
+ *  trailing corner — the block's last position — rather than the point's own x. */
+export declare function probePointIn(rect: DOMRect, x: number, y: number, belowAll: boolean): {
+    x: number;
+    y: number;
+};
+export interface NearestBlock {
+    path: number[];
+    /** Lazy so a drag whose point falls back on its own anchor block never pays the hit-test. */
+    endpointHere(): SelectionEndpoint | null;
+}
+/** The block a point addresses: the one under it, else the nearest one with the point clamped
+ *  into its box. Null only where nothing is mounted. */
+export declare function blockNearPoint(editorRoot: HTMLElement, clientX: number, clientY: number): NearestBlock | null;

package/dist/selection/nearest-block.js

@@ -0,0 +1,73 @@
+/**
+ * The mounted block nearest a viewport point, and the endpoint that point addresses. A gesture
+ * that must answer EVERY point — the dead-space click, a drag into the margin — resolves an
+ * off-block point through here instead of declining it. The probe point never leaves the module:
+ * a caller hit-testing at its own raw point gets no offset at all on a character surface.
+ * Only mounted blocks are measured; a caller answering for a windowed-out tail reconciles itself.
+ */
+import { clampPointIntoBox } from '../cursor/point-offset';
+import { blockAtPoint, endpointAtPoint } from './block-hit-test';
+import { readBlockPath } from './path-lookup';
+/** Document order, since bands may nest and every walk over them depends on it. */
+export function measureBlocks(root) {
+    return blockHosts(root).map((el) => ({
+        path: readBlockPath(el),
+        rect: el.getBoundingClientRect()
+    }));
+}
+/**
+ * The band a `y` belongs to. `belowAll` marks a point past the last band, the end-of-document
+ * gesture, which lands at a trailing corner rather than under its own x. A y in a gap resolves to
+ * the nearest band, so no point is left unanswered. Bands arrive in document order and may nest,
+ * so containment scans forward, outermost wins.
+ */
+export function nearestBand(bands, y) {
+    if (bands.length === 0)
+        return null;
+    const last = bands.length - 1;
+    if (y > bands[last].bottom)
+        return { index: last, belowAll: true };
+    for (let i = 0; i < bands.length; i++) {
+        if (y >= bands[i].top && y <= bands[i].bottom)
+            return { index: i, belowAll: false };
+    }
+    let nearest = 0;
+    let smallestGap = Infinity;
+    for (let i = 0; i < bands.length; i++) {
+        const gap = y < bands[i].top ? bands[i].top - y : y - bands[i].bottom;
+        if (gap < smallestGap) {
+            smallestGap = gap;
+            nearest = i;
+        }
+    }
+    return { index: nearest, belowAll: false };
+}
+// ── Probing ────────────────────────────────────────────────────────────────
+/** The band's own probe point: {@link clampPointIntoBox}, except that `belowAll` takes the
+ *  trailing corner — the block's last position — rather than the point's own x. */
+export function probePointIn(rect, x, y, belowAll) {
+    const inside = clampPointIntoBox(rect, x, y);
+    return { x: belowAll ? rect.right - 1 : inside.x, y: inside.y };
+}
+/** The block a point addresses: the one under it, else the nearest one with the point clamped
+ *  into its box. Null only where nothing is mounted. */
+export function blockNearPoint(editorRoot, clientX, clientY) {
+    const direct = blockAtPoint(editorRoot, clientX, clientY);
+    if (direct)
+        return addressedAt(direct, clientX, clientY);
+    const rects = blockHosts(editorRoot).map((el) => el.getBoundingClientRect());
+    const band = nearestBand(rects, clientY);
+    if (!band)
+        return null;
+    const probe = probePointIn(rects[band.index], clientX, clientY, band.belowAll);
+    const hit = blockAtPoint(editorRoot, probe.x, probe.y);
+    return hit && addressedAt(hit, probe.x, probe.y);
+}
+// ── Internal ───────────────────────────────────────────────────────────────
+function addressedAt(hit, probeX, probeY) {
+    return { path: hit.path, endpointHere: () => endpointAtPoint(hit, probeX, probeY) };
+}
+/** The one selector for the mounted hosts, so the two walks above cannot drift apart. */
+function blockHosts(root) {
+    return [...root.querySelectorAll('[data-block-path]')];
+}

package/dist/selection/path-lookup.d.ts

@@ -0,0 +1,32 @@
+/** Document-tree path navigation. Pure functions over a Document + path. */
+import type { Document } from '../core/nodes';
+/** Block immediately after `path` in doc order (children before siblings), else null. */
+export declare function nextPath(doc: Document, path: number[]): number[] | null;
+/** Block immediately before `path` in doc order (deepest last descendant first), else null. */
+export declare function previousPath(doc: Document, path: number[]): number[] | null;
+/** First block in document order, or null if the document is empty. */
+export declare function firstPath(doc: Document): number[] | null;
+/** Last block in document order (deepest last descendant), or null if empty. */
+export declare function lastPath(doc: Document): number[] | null;
+/** Descend `path` to its first leaf, or null when `path` doesn't resolve to a node. */
+export declare function firstLeafAtOrAfter(doc: Document, path: number[]): number[] | null;
+/** Descend `path` to its last leaf, or null when `path` doesn't resolve to a node. */
+export declare function lastLeafAtOrBefore(doc: Document, path: number[]): number[] | null;
+/**
+ * The document path an element's own `data-block-path` carries. A plugin may own the attribute
+ * with non-JSON content, so a parse failure resolves to null, never a throw.
+ */
+export declare function readBlockPath(el: Element | null): number[] | null;
+/** Walk up from `el` to the nearest ancestor carrying `data-block-path`. */
+export declare function findBlockPathForElement(el: Element | null): number[] | null;
+/**
+ * The deep `[...tablePath, row, col]` path of an element inside a table cell. Only block hosts
+ * emit `data-block-path`, so {@link findBlockPathForElement} stops at the table and returns a
+ * path whose offsets are cell indices while a caret read from the same element is in characters.
+ * Any producer resolving an endpoint path from the DOM must come through here. Null outside a
+ * cell grid; addresses the grid by selector contract (`data-table-row-idx`, `role="cell"`).
+ */
+export declare function findCellPathForElement(el: Element | null): number[] | null;
+/** The path of the editing SURFACE `el` sits in — the enclosing cell where there is one, else
+ *  the enclosing block. The pairing {@link findCellPathForElement} says every producer owes. */
+export declare function findSurfacePathForElement(el: Element | null): number[] | null;

package/dist/selection/path-lookup.js

@@ -0,0 +1,132 @@
+/** Document-tree path navigation. Pure functions over a Document + path. */
+import { nodeAt } from '../tree-operations/node-ops';
+/** Block immediately after `path` in doc order (children before siblings), else null. */
+export function nextPath(doc, path) {
+    const node = nodeAt(doc, path);
+    if (node && 'children' in node && node.children && node.children.length > 0) {
+        return [...path, 0];
+    }
+    let p = path.slice();
+    while (p.length > 0) {
+        const parentPath = p.slice(0, -1);
+        const parent = nodeAt(doc, parentPath);
+        if (!parent || !parent.children)
+            return null;
+        const idx = p[p.length - 1];
+        if (idx + 1 < parent.children.length) {
+            return [...parentPath, idx + 1];
+        }
+        p = parentPath;
+    }
+    return null;
+}
+/** Block immediately before `path` in doc order (deepest last descendant first), else null. */
+export function previousPath(doc, path) {
+    if (path.length === 0)
+        return null;
+    const parentPath = path.slice(0, -1);
+    const parent = nodeAt(doc, parentPath);
+    if (!parent || !parent.children)
+        return null;
+    const idx = path[path.length - 1];
+    if (idx > 0) {
+        return lastLeafAtOrBefore(doc, [...parentPath, idx - 1]);
+    }
+    if (parentPath.length === 0)
+        return null;
+    return parentPath;
+}
+/** First block in document order, or null if the document is empty. */
+export function firstPath(doc) {
+    if (!doc.children || doc.children.length === 0)
+        return null;
+    return firstLeafAtOrAfter(doc, [0]);
+}
+/** Last block in document order (deepest last descendant), or null if empty. */
+export function lastPath(doc) {
+    if (!doc.children || doc.children.length === 0)
+        return null;
+    return lastLeafAtOrBefore(doc, [doc.children.length - 1]);
+}
+/** Descend `path` to its first leaf, or null when `path` doesn't resolve to a node. */
+export function firstLeafAtOrAfter(doc, path) {
+    let cur = path;
+    while (cur) {
+        const node = nodeAt(doc, cur);
+        if (!node)
+            return null;
+        if (!('children' in node) || !node.children || node.children.length === 0)
+            return cur;
+        cur = [...cur, 0];
+    }
+    return null;
+}
+/** Descend `path` to its last leaf, or null when `path` doesn't resolve to a node. */
+export function lastLeafAtOrBefore(doc, path) {
+    let cur = path;
+    while (cur) {
+        // Annotated: overload resolution + the `cur` reassignment below otherwise cycle inference.
+        const node = nodeAt(doc, cur);
+        if (!node)
+            return null;
+        if (!('children' in node) || !node.children || node.children.length === 0)
+            return cur;
+        cur = [...cur, node.children.length - 1];
+    }
+    return null;
+}
+/**
+ * The document path an element's own `data-block-path` carries. A plugin may own the attribute
+ * with non-JSON content, so a parse failure resolves to null, never a throw.
+ */
+export function readBlockPath(el) {
+    const attr = el?.getAttribute('data-block-path');
+    if (!attr)
+        return null;
+    try {
+        return JSON.parse(attr);
+    }
+    catch {
+        return null;
+    }
+}
+/** Walk up from `el` to the nearest ancestor carrying `data-block-path`. */
+export function findBlockPathForElement(el) {
+    let cur = el;
+    while (cur) {
+        if (cur.getAttribute('data-block-path'))
+            return readBlockPath(cur);
+        cur = cur.parentElement;
+    }
+    return null;
+}
+/**
+ * The deep `[...tablePath, row, col]` path of an element inside a table cell. Only block hosts
+ * emit `data-block-path`, so {@link findBlockPathForElement} stops at the table and returns a
+ * path whose offsets are cell indices while a caret read from the same element is in characters.
+ * Any producer resolving an endpoint path from the DOM must come through here. Null outside a
+ * cell grid; addresses the grid by selector contract (`data-table-row-idx`, `role="cell"`).
+ */
+export function findCellPathForElement(el) {
+    const cellEl = el?.closest('[role="cell"]') ?? null;
+    if (!cellEl)
+        return null;
+    const rowEl = cellEl.closest('[data-table-row-idx]');
+    if (!rowEl)
+        return null;
+    const tablePath = findBlockPathForElement(rowEl);
+    if (!tablePath)
+        return null;
+    const rowIdx = Number(rowEl.getAttribute('data-table-row-idx'));
+    if (!Number.isInteger(rowIdx))
+        return null;
+    const colIdx = Array.from(rowEl.querySelectorAll(':scope > [role="cell"]')).indexOf(cellEl);
+    if (colIdx < 0)
+        return null;
+    return [...tablePath, rowIdx, colIdx];
+}
+/** The path of the editing SURFACE `el` sits in — the enclosing cell where there is one, else
+ *  the enclosing block. The pairing {@link findCellPathForElement} says every producer owes. */
+export function findSurfacePathForElement(el) {
+    return findCellPathForElement(el) ?? findBlockPathForElement(el);
+}

package/dist/selection/path-math.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Pure predicates over CST paths, plus the `DocPath` brand home. No DOM, no document lookups.
+ * The predicates take `readonly number[]`: they order any path-shaped array regardless of what
+ * space it addresses, so brand-typing them to `DocPath` would force a cast at every call site.
+ */
+declare const docPathBrand: unique symbol;
+/**
+ * A path whose every prefix resolves from the document root: the dialect the commit seam
+ * requires and G1.16 checks (`op.eventPath` and `snapshot.path` carry it). `asDocPath` is the
+ * base mint; op families compose through `extendDocPath`/`docPathFrom` in
+ * `cursor/coordinate-spaces.ts`. G1.16 stays the runtime belt for JS callers types don't bind.
+ */
+export type DocPath = number[] & {
+    readonly [docPathBrand]: true;
+};
+export declare function asDocPath(indices: number[]): DocPath;
+/** Document order, ancestor-before-descendant: `[2]` precedes `[2, 0]`. */
+export declare function comparePaths(a: readonly number[], b: readonly number[]): number;
+/** True if `prefix` equals `path` or is a strict ancestor of it. */
+export declare function pathHasPrefix(path: readonly number[], prefix: readonly number[]): boolean;
+/** True if `ancestor` is a strict prefix of `descendant`'s path. */
+export declare function isStrictAncestorOf(ancestor: readonly number[], descendant: readonly number[]): boolean;
+export declare function pathsEqual(a: readonly number[], b: readonly number[]): boolean;
+/** Number of shared leading indices between two paths. */
+export declare function sharedPrefixLength(a: readonly number[], b: readonly number[]): number;
+/** Longest shared prefix of two paths. */
+export declare function lowestCommonAncestor(a: readonly number[], b: readonly number[]): number[];
+/** True if `path` is strictly between `start` and `end` in document order. */
+export declare function isPathBetween(path: readonly number[], start: readonly number[], end: readonly number[]): boolean;
+/**
+ * True when path's entire subtree fits strictly inside (start, end). Stronger
+ * than `walkBetween`'s doc-order "between", which includes endpoint ancestors.
+ */
+export declare function isPathSubtreeBetween(path: readonly number[], start: readonly number[], end: readonly number[]): boolean;
+export {};

package/dist/selection/path-math.js

@@ -0,0 +1,90 @@
+/**
+ * Pure predicates over CST paths, plus the `DocPath` brand home. No DOM, no document lookups.
+ * The predicates take `readonly number[]`: they order any path-shaped array regardless of what
+ * space it addresses, so brand-typing them to `DocPath` would force a cast at every call site.
+ */
+export function asDocPath(indices) {
+    return indices;
+}
+// ── Path predicates ────────────────────────────────────────────────────────
+/** Document order, ancestor-before-descendant: `[2]` precedes `[2, 0]`. */
+export function comparePaths(a, b) {
+    const len = Math.min(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        if (a[i] < b[i])
+            return -1;
+        if (a[i] > b[i])
+            return 1;
+    }
+    if (a.length < b.length)
+        return -1;
+    if (a.length > b.length)
+        return 1;
+    return 0;
+}
+/** True if `prefix` equals `path` or is a strict ancestor of it. */
+export function pathHasPrefix(path, prefix) {
+    if (prefix.length > path.length)
+        return false;
+    for (let i = 0; i < prefix.length; i++) {
+        if (path[i] !== prefix[i])
+            return false;
+    }
+    return true;
+}
+/** True if `ancestor` is a strict prefix of `descendant`'s path. */
+export function isStrictAncestorOf(ancestor, descendant) {
+    if (ancestor.length >= descendant.length)
+        return false;
+    for (let i = 0; i < ancestor.length; i++) {
+        if (ancestor[i] !== descendant[i])
+            return false;
+    }
+    return true;
+}
+export function pathsEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+/** Number of shared leading indices between two paths. */
+export function sharedPrefixLength(a, b) {
+    const len = Math.min(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        if (a[i] !== b[i])
+            return i;
+    }
+    return len;
+}
+/** Longest shared prefix of two paths. */
+export function lowestCommonAncestor(a, b) {
+    const result = [];
+    const len = Math.min(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        if (a[i] !== b[i])
+            break;
+        result.push(a[i]);
+    }
+    return result;
+}
+// ── Range predicates ───────────────────────────────────────────────────────
+/** True if `path` is strictly between `start` and `end` in document order. */
+export function isPathBetween(path, start, end) {
+    return comparePaths(path, start) > 0 && comparePaths(path, end) < 0;
+}
+/**
+ * True when path's entire subtree fits strictly inside (start, end). Stronger
+ * than `walkBetween`'s doc-order "between", which includes endpoint ancestors.
+ */
+export function isPathSubtreeBetween(path, start, end) {
+    return (!isStrictAncestorOf(path, start) &&
+        !isStrictAncestorOf(start, path) &&
+        !isStrictAncestorOf(path, end) &&
+        !isStrictAncestorOf(end, path) &&
+        !pathsEqual(path, start) &&
+        !pathsEqual(path, end));
+}

package/dist/selection/pointer-session.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared pointer-drag session: the document-listener + rAF-coalescing scaffold every drag
+ * lifecycle builds on. Owns the pointer-ownership filter, autoscroll wiring, and idempotent
+ * teardown; callers supply the per-surface move/end behavior and the options that genuinely
+ * differ. rAF here is frame-paced pointermove coalescing, not async sequencing (G4.4).
+ */
+import { type AutoScrollDeps } from './autoscroll';
+export interface PointerPosition {
+    clientX: number;
+    clientY: number;
+}
+export interface PointerDragSessionOptions {
+    /** Coalesced to one call per animation frame with the latest pointer: intermediate positions
+     *  are dropped, so a consumer must answer the point it gets rather than wait for a better one. */
+    onMove(pointer: PointerPosition): void;
+    /**
+     * pointerup / pointercancel finalize, after the pending move flushes and the session tears
+     * down. NOT run on Escape or lifetime abort: those are pure teardowns.
+     */
+    onEnd?(reason: 'up' | 'cancel'): void;
+    /** Caller cleanup, run once on every teardown path (up, cancel, Escape, abort). */
+    onTeardown?(): void;
+    /** Scroll targets + axis; the session supplies the live pointer and rescroll. */
+    autoScroll: Pick<AutoScrollDeps, 'getTargets' | 'axis'>;
+    /**
+     * Drag/click discriminator in px: below this travel from `down` the gesture stays a click.
+     * Omit where the pointerdown already committed to a drag.
+     */
+    threshold?: number;
+    onDragRecognized?(): void;
+    /** Install a document keydown so Escape tears the session down. */
+    escape?: boolean;
+    /** Suppress native text selection for the drag's duration. */
+    disableUserSelect?: boolean;
+    /**
+     * Aborted on editor unmount. Without it an unmount mid-drag leaks the document listeners:
+     * pointerup never fires once the originating element is gone.
+     */
+    lifetimeSignal?: AbortSignal;
+}
+export declare function createPointerDragSession(down: PointerEvent, opts: PointerDragSessionOptions): {
+    dispose(): void;
+};