@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/core/parsers/table.js

@@ -1,10 +1,11 @@
+import { trimWhitespace } from '../lines';
 import { joinRaw, isBlankLine } from '../parser';
 import { lineStartsOuterBlock } from '../../schema/block-openers';
 // ── Cell splitter ──────────────────────────────────────────────────────────
-// Cell padding is cosmetic. Pre-edit bytes survive in `table.raw`; post-edit,
-// rebuildTableRowRaw emits canonical single-space padding for every row.
+// Cell padding is cosmetic: a rebuilt row writes single spaces. GFM §4.10 trims spaces, so a
+// non-breaking space at a cell's edge is content and survives the rebuild.
 export function splitRowCells(rowText) {
-    const trimmed = rowText.trim();
+    const trimmed = trimWhitespace(rowText);
     const head = trimmed.startsWith('|') ? trimmed.slice(1) : trimmed;
     const inner = head.endsWith('|') ? head.slice(0, -1) : head;
     const cells = [];
@@ -13,21 +14,18 @@ export function splitRowCells(rowText) {
     for (let i = 0; i < inner.length; i++) {
         const ch = inner[i];
         if (ch === '|' && !escaped) {
-            cells.push(current.trim());
+            cells.push(trimWhitespace(current));
             current = '';
             continue;
         }
         current += ch;
         escaped = ch === '\\' && !escaped;
     }
-    cells.push(current.trim());
+    cells.push(trimWhitespace(current));
     return cells;
 }
-/**
- * The cells a line offers as a table header row, or null when it offers none — the one home for
- * the shape, so a row the continuation scan accepts and the Enter completer refuses cannot exist.
- * Arity against the delimiter is the caller's check.
- */
+/** The cells a line offers as a header row, or null: the one definition, so the continuation scan
+ *  and the Enter completer cannot disagree. Arity against the delimiter is the caller's check. */
 export function tableHeaderCells(text) {
     if (!text.includes('|'))
         return null;
@@ -35,14 +33,14 @@ export function tableHeaderCells(text) {
 }
 // ── Delimiter row ──────────────────────────────────────────────────────────
 export function matchTableDelimiterRow(text) {
-    const trimmed = text.trim();
+    const trimmed = trimWhitespace(text);
     if (!trimmed.includes('|'))
         return null;
     const inner = trimmed.replace(/^\||\|$/g, '');
     const cells = inner.split('|');
     const alignments = [];
     for (const cell of cells) {
-        const c = cell.trim();
+        const c = trimWhitespace(cell);
         if (!/^:?-+:?$/.test(c))
             return null;
         const left = c.startsWith(':');
@@ -59,17 +57,17 @@ export function matchTableDelimiterRow(text) {
     return { columnCount: cells.length, alignments };
 }
 // ── Block parser ───────────────────────────────────────────────────────────
-export function parseTable(lines, startIndex, endIndex, leadingTrivia, delimiter) {
-    // GFM: the table breaks at a blank line or the start of another block, so a body row is a
-    // pipe-carrying line no opener claims. No paragraph is open here, so nothing is transparent
-    // but the definition, which is never a block start.
+/** Whether a table takes `lines[index]` as one more row, pipe or none: GFM ends a table only at a
+ *  blank line or a block start (spec example 201), judged in the editor's grammar. */
+export function tableTakesLine(lines, index, end, grammar) {
+    const line = lines[index];
+    return (!isBlankLine(line.text) &&
+        !lineStartsOuterBlock(line, { paragraphOpen: false, grammar, window: { lines, index, end } }));
+}
+export function parseTable(lines, startIndex, endIndex, leadingTrivia, delimiter, grammar) {
     let i = startIndex + 2;
-    while (i < endIndex &&
-        !isBlankLine(lines[i].text) &&
-        lines[i].text.includes('|') &&
-        !lineStartsOuterBlock(lines[i], { paragraphOpen: false })) {
+    while (i < endIndex && tableTakesLine(lines, i, endIndex, grammar))
         i++;
-    }
     const rows = [];
     rows.push(buildRow(lines[startIndex], delimiter.columnCount, true));
     for (let r = startIndex + 2; r < i; r++) {
@@ -87,14 +85,13 @@ export function parseTable(lines, startIndex, endIndex, leadingTrivia, delimiter
         consumed: i - startIndex
     };
 }
-// GFM pads short BODY rows and truncates long ones to the delimiter column count. The header
-// always matches: a mismatch rejects the whole table at recognition (GFM §4.10, paragraph.ts).
+// GFM pads short body rows and renders a long one's first cells, keeping the rest as surplus bytes;
+// a header mismatch rejects the whole table at recognition (paragraph.ts).
 function buildRow(line, columnCount, isHeader) {
     const cellTexts = splitRowCells(line.text);
     while (cellTexts.length < columnCount)
         cellTexts.push('');
-    if (cellTexts.length > columnCount)
-        cellTexts.length = columnCount;
+    const surplusCells = cellTexts.splice(columnCount);
     const cells = cellTexts.map((text) => ({
         kind: 'tableCell',
         leadingTrivia: '',
@@ -104,7 +101,7 @@ function buildRow(line, columnCount, isHeader) {
         kind: 'tableRow',
         leadingTrivia: '',
         raw: line.raw,
-        metadata: { isHeader },
+        metadata: surplusCells.length > 0 ? { isHeader, surplusCells } : { isHeader },
         children: cells
     };
 }

package/dist/core/parsers/thematic-break.js

@@ -1,19 +1,20 @@
 // Ambiguity with setext underlines is resolved in paragraph.ts; top-level
 // dispatch only reaches here after a blank line or a non-paragraph state.
+import { indentColumns, OPTIONAL_LINE_ENDING } from '../lines';
+// CommonMark §4.1: only spaces and tabs sit around the markers, so a non-breaking space makes the
+// line a paragraph.
+const breakOf = (marker) => new RegExp(`^[ \\t]*(?:\\${marker}[ \\t]*){3,}${OPTIONAL_LINE_ENDING}$`);
+const BREAKS = [
+    [breakOf('*'), '*'],
+    [breakOf('-'), '-'],
+    [breakOf('_'), '_']
+];
 export function matchThematicBreak(text) {
-    // CommonMark §4.1: 0-3 columns of indent; 4+ is indented code (tabs advance to the next 4).
-    let col = 0;
-    for (let i = 0; i < text.length && (text[i] === ' ' || text[i] === '\t'); i++) {
-        col += text[i] === '\t' ? 4 - (col % 4) : 1;
-        if (col >= 4)
-            return null;
-    }
-    const trimmed = text.trim();
-    if (/^(\*[ \t]*){3,}$/.test(trimmed))
-        return '*';
-    if (/^(-[ \t]*){3,}$/.test(trimmed))
-        return '-';
-    if (/^(_[ \t]*){3,}$/.test(trimmed))
-        return '_';
+    // 0-3 columns of indent; 4+ is indented code.
+    if (indentColumns(text) >= 4)
+        return null;
+    for (const [pattern, marker] of BREAKS)
+        if (pattern.test(text))
+            return marker;
     return null;
 }

package/dist/core/paths.d.ts

@@ -0,0 +1,13 @@
+/** Traversals of the block tree by path. */
+import type { CstNode, Document } from './nodes';
+import type { DocumentView, NodeView } from './node-views';
+type WalkControl = void | 'skip' | 'stop';
+/** Every block under `root`, not `root` itself, parents first; each path starts with `basePath` and
+ *  is the visitor's to keep. `'skip'` leaves out a node's children; `'stop'` ends it, returning true. */
+export declare function walkBlocks(root: Document | CstNode, visit: (node: CstNode, path: number[]) => WalkControl, basePath?: readonly number[]): boolean;
+export declare function walkBlocks(root: DocumentView | NodeView, visit: (node: NodeView, path: number[]) => WalkControl, basePath?: readonly number[]): boolean;
+/** The blocks strictly between `root` and the block at `path`, outermost first; the steps past a
+ *  missing child are left out. */
+export declare function ancestorsOf(root: Document | CstNode, path: readonly number[]): CstNode[];
+export declare function ancestorsOf(root: DocumentView | NodeView, path: readonly number[]): NodeView[];
+export {};

package/dist/core/paths.js

@@ -0,0 +1,31 @@
+/** Traversals of the block tree by path. */
+export function walkBlocks(root, visit, basePath = []) {
+    return walkChildren(root.children, [...basePath], visit);
+}
+export function ancestorsOf(root, path) {
+    const ancestors = [];
+    let children = root.children;
+    for (const index of path.slice(0, -1)) {
+        const node = children?.[index];
+        if (!node)
+            break;
+        ancestors.push(node);
+        children = node.children;
+    }
+    return ancestors;
+}
+// `trail` is the traversal's own path, copied for each visit so a visitor's array stays its own.
+function walkChildren(children, trail, visit) {
+    if (!children)
+        return false;
+    for (let index = 0; index < children.length; index++) {
+        trail.push(index);
+        const control = visit(children[index], trail.slice());
+        const stopped = control === 'stop' ||
+            (control !== 'skip' && walkChildren(children[index].children, trail, visit));
+        trail.pop();
+        if (stopped)
+            return true;
+    }
+    return false;
+}

package/dist/core/terminator-escalation.d.ts

@@ -1,8 +1 @@
-/**
- * The walk behind every "widen the opener past its own body" rule: raise `minimum` one past
- * each body line that would close the block at the width reached so far. A core leaf because
- * the fence grammar and the directive grammar both need it, and neither should import the
- * other's directory. Per-syntax knowledge stays in `closerRun`, which reports the closing
- * line's run length or `null` for a line that does not close.
- */
 export declare function escalateTerminatorRun(body: string, minimum: number, closerRun: (text: string, required: number) => number | null): number;

package/dist/core/terminator-escalation.js

@@ -1,15 +1,12 @@
 /**
- * The walk behind every "widen the opener past its own body" rule: raise `minimum` one past
- * each body line that would close the block at the width reached so far. A core leaf because
- * the fence grammar and the directive grammar both need it, and neither should import the
- * other's directory. Per-syntax knowledge stays in `closerRun`, which reports the closing
- * line's run length or `null` for a line that does not close.
+ * The run length a fence or directive opener needs so no body line closes it: `minimum`, raised
+ * one past each body line that would close the block at the width reached so far. `closerRun`
+ * reports a closing line's run length, or `null` for a line that does not close.
  */
+import { displayLines } from './lines';
 export function escalateTerminatorRun(body, minimum, closerRun) {
     let required = minimum;
-    for (const line of body.split('\n')) {
-        // Splitting on `\n` leaves a CRLF body's `\r` on the tail; a closer line's text excludes it.
-        const text = line.endsWith('\r') ? line.slice(0, -1) : line;
+    for (const { text } of displayLines(body)) {
         const run = closerRun(text, required);
         if (run !== null)
             required = run + 1;

package/dist/core/url-policy.d.ts

@@ -6,9 +6,6 @@
 export declare function isAllowedHrefScheme(url: string): boolean;
 /** Same rule as href over a different set: schemes that hand bytes to an `<img>`. */
 export declare function isAllowedImageSrcScheme(url: string): boolean;
-/**
- * The default when a consumer supplies no `onLinkActivate`, gated on the href allowlist. A block
- * is a security-relevant signal a production host can act on, so it reports through `onBlocked`
- * (the editor's `error` channel) rather than only reaching a dev console.
- */
+/** The default when a consumer supplies no `onLinkActivate`, gated on the href allowlist. A block
+ *  reports through `onBlocked` (the `error` channel), since a production host may act on it. */
 export declare function defaultLinkActivation(url: string, _event: MouseEvent, onBlocked?: (url: string) => void): void;

package/dist/core/url-policy.js

@@ -3,14 +3,13 @@
  * URLs cannot smuggle script execution into the DOM. `defaultLinkActivation` is the one DOM sink.
  */
 import { devWarn } from '../dev-warn';
-const ALLOWED_HREF_SCHEMES = new Set(['http', 'https', 'mailto', 'tel']);
-// `asset:` is a desktop shell's local-file protocol off Windows, where the same URL arrives as
-// `http://asset.localhost/...`, so omitting it blocks every image on macOS and Linux while
-// passing on a Windows dev box. It carries no script capability: no browser resolves it.
+// `xmpp` hands the address to a chat client the way `mailto` hands it to a mail client.
+const ALLOWED_HREF_SCHEMES = new Set(['http', 'https', 'mailto', 'tel', 'xmpp']);
+// `asset:` is a desktop shell's local-file protocol off Windows, needed for images on macOS and
+// Linux; it carries no script capability, since no browser resolves it.
 const ALLOWED_IMG_SCHEMES = new Set(['http', 'https', 'data', 'asset']);
-// Matches the WHATWG URL parser's pre-scheme normalization: it strips ASCII tab/newline anywhere
-// and leading C0-control-or-space. `java\tscript:` runs in the browser, so normalizing the same
-// way here is what stops a control byte from trivially bypassing the allowlist.
+// Mirrors the WHATWG URL parser's pre-scheme normalization, or a control byte (`java\tscript:`)
+// would slip past the allowlist.
 function schemeOf(url) {
     const stripped = url.replace(/[\t\n\r]/g, '');
     let i = 0;
@@ -29,11 +28,8 @@ export function isAllowedImageSrcScheme(url) {
     const scheme = schemeOf(url);
     return scheme === null || ALLOWED_IMG_SCHEMES.has(scheme);
 }
-/**
- * The default when a consumer supplies no `onLinkActivate`, gated on the href allowlist. A block
- * is a security-relevant signal a production host can act on, so it reports through `onBlocked`
- * (the editor's `error` channel) rather than only reaching a dev console.
- */
+/** The default when a consumer supplies no `onLinkActivate`, gated on the href allowlist. A block
+ *  reports through `onBlocked` (the `error` channel), since a production host may act on it. */
 export function defaultLinkActivation(url, _event, onBlocked) {
     if (isAllowedHrefScheme(url)) {
         window.open(url, '_blank', 'noopener,noreferrer');

package/dist/cursor/caret-memory.d.ts

@@ -0,0 +1,34 @@
+/**
+ * What the editor remembers about how the caret arrived: the sticky column (the x a run of
+ * Up/Down arrows keeps), the edge affinity (which side of a hidden marker run the caret means)
+ * and the pending marks (the formats a toggle promised the next typed byte). All three share one
+ * lifetime: a keydown updates them through `noteKey`, and any other caret move calls `forget`,
+ * which drops all three at once.
+ */
+import type { EditorX } from './coordinate-spaces';
+import { type EdgeAffinity } from './edge-affinity';
+import { type PendingMarks } from './pending-marks';
+import type { AnyCommandId } from '../schema/command-id';
+/** The parts of a keydown the classifiers read. */
+export type ArrivalKey = Pick<KeyboardEvent, 'key'> & Partial<Pick<KeyboardEvent, 'metaKey'>>;
+export interface CaretMemory {
+    /** The editor-relative x a vertical move aims for, or null outside an Up/Down run. */
+    column(): EditorX | null;
+    /** Which side of a hidden marker run the caret means; null leaves the typing path's default. */
+    side(): EdgeAffinity | null;
+    /** The marks a toggle at a collapsed caret promised; `forget` drops them with the rest. */
+    readonly pendingMarks: PendingMarks;
+    /** Classify a keydown; `command` is the chord's meaning at the focused block, so a rebound chord
+     *  reads as what it does. Without `measureX` (a caller holding a range) the column is kept. */
+    noteKey(e: ArrivalKey, command: AnyCommandId | null, measureX?: () => EditorX | null): void;
+    /** A committed keystroke: the byte belongs to the content, whatever arrival preceded it. */
+    noteTyping(): void;
+    /** The caret was placed at an end rather than stepped there, so it means the outside. */
+    noteExtreme(): void;
+    /** Record a column a surface measured itself on the way out (the table, which has no caret
+     *  of its own at the moment it leaves). Keeps a column already held. */
+    captureColumn(x: EditorX): void;
+    /** A caret move that is not a key: a click, a paste, an undo, a document swap, a blur. */
+    forget(): void;
+}
+export declare function createCaretMemory(): CaretMemory;

package/dist/cursor/caret-memory.js

@@ -0,0 +1,82 @@
+/**
+ * What the editor remembers about how the caret arrived: the sticky column (the x a run of
+ * Up/Down arrows keeps), the edge affinity (which side of a hidden marker run the caret means)
+ * and the pending marks (the formats a toggle promised the next typed byte). All three share one
+ * lifetime: a keydown updates them through `noteKey`, and any other caret move calls `forget`,
+ * which drops all three at once.
+ */
+import { classifyStickyKey } from './sticky-column';
+import { classifyArrivalKey } from './edge-affinity';
+import { flipMark } from './pending-marks';
+import { BLOCK_MOVE_COMMAND_IDS } from '../schema/commands';
+import { isInteractionTraceEnabled, traceStickyCapture, traceStickyReset } from '../debug/interaction-trace';
+export function createCaretMemory() {
+    let column = null;
+    let side = null;
+    let marks = null;
+    function dropColumn() {
+        // Runs on nearly every keystroke, so the enabled check short-circuits first.
+        if (isInteractionTraceEnabled() && column !== null)
+            traceStickyReset();
+        column = null;
+    }
+    function captureColumn(x) {
+        if (column !== null || !Number.isFinite(x))
+            return;
+        column = x;
+        traceStickyCapture(x);
+    }
+    // Promised marks belong to one side of the caret, so a caret that changed sides drops them.
+    function settleSide(next) {
+        side = next;
+        marks = null;
+    }
+    return {
+        column: () => column,
+        side: () => side,
+        pendingMarks: {
+            get: () => marks,
+            toggle: (kind) => {
+                marks = flipMark(marks, kind);
+            },
+            consume: () => {
+                const spent = marks;
+                marks = null;
+                return spent;
+            },
+            restore: (unspent) => {
+                if (marks === null)
+                    marks = unspent;
+            }
+        },
+        noteKey: (e, command, measureX) => {
+            // A block move leaves the caret where it was; the move's own commit forgets the memory.
+            if (command !== null && BLOCK_MOVE_COMMAND_IDS.has(command))
+                return;
+            const columnAction = classifyStickyKey(e.key);
+            if (columnAction === 'reset')
+                dropColumn();
+            else if (columnAction === 'capture') {
+                const x = measureX?.();
+                if (x !== null && x !== undefined)
+                    captureColumn(x);
+            }
+            const sideAction = classifyArrivalKey(e.key, e.metaKey);
+            // A preserved key left the caret where it was: the chord that pends a mark and the
+            // character that spends it both preserve, so neither may clear the marks.
+            if (sideAction === 'preserve')
+                return;
+            settleSide(sideAction === 'reset' ? null : sideAction);
+        },
+        noteTyping: () => {
+            dropColumn();
+            settleSide('near');
+        },
+        noteExtreme: () => settleSide('outside'),
+        captureColumn,
+        forget: () => {
+            dropColumn();
+            settleSide(null);
+        }
+    };
+}

package/dist/cursor/coordinate-spaces.d.ts

@@ -1,27 +1,26 @@
 /**
  * The editor's coordinate spaces as branded numbers (G3.7), so mixing them is a type error
- * at the seam instead of a caret bug later. A brand is produced only by its space's home
- * module or an `as*` boundary mint at a declared public door — the coordinate-brand-mints
- * lint holds that list closed — and moves between spaces only through the named
- * conversions below, one home per direction. Public API doors keep `number` and mint once.
+ * instead of a caret bug later. A brand is produced only by the module that owns its space or
+ * by an `as*` cast at a declared public entry point (G4.15's rows in `lint/file-rules.test.ts`
+ * hold that list closed), and moves between spaces only through the conversions below, one
+ * function per direction. Public API entry points take `number` and brand it once.
  */
 import type { DocPath } from '../selection/path-math';
 declare const rawOffsetBrand: unique symbol;
-/** Byte offset into a block node's raw content (CST-facing; ambient marker excluded). */
+/** Byte offset into a block node's raw content (CST-facing; the container's marker prefix excluded). */
 export type RawOffset = number & {
     readonly [rawOffsetBrand]: true;
 };
 declare const domTextOffsetBrand: unique symbol;
 /**
- * Offset in the widget-offset walk space: raw offset plus the leading ambient marker's
- * text length. Home: `cursor/widget-offset.ts`, with `cursor/content-offsets.ts` as the
- * widget-free equivalent.
+ * Offset as the DOM walk counts it: the raw offset plus the leading marker prefix's text length.
+ * Produced only by `cursor/widget-offset.ts`.
  */
 export type DomTextOffset = number & {
     readonly [domTextOffsetBrand]: true;
 };
 declare const editorXBrand: unique symbol;
-/** Editor-relative pixel X (viewport X minus the editor container's left) — scroll-invariant. */
+/** Editor-relative pixel X (viewport X minus the editor container's left), unaffected by scrolling. */
 export type EditorX = number & {
     readonly [editorXBrand]: true;
 };
@@ -31,15 +30,15 @@ export type ViewportX = number & {
     readonly [viewportXBrand]: true;
 };
 declare const cellIndexBrand: unique symbol;
-/** Row-major table cell index. Declared ahead of its home's conversion so the
+/** Row-major table cell index, declared here rather than in the table code so the
  *  `as CellIndex` lint rule exists before the first cast does. */
 export type CellIndex = number & {
     readonly [cellIndexBrand]: true;
 };
 export declare function toDomTextOffset(raw: RawOffset, ambientLength: number): DomTextOffset;
 export declare function toRawOffset(domText: DomTextOffset, ambientLength: number): RawOffset;
-/** `toRawOffset` clamped to raw 0, for DOM reads that may land inside the leading ambient
- *  marker, where the unclamped result goes negative. */
+/** `toRawOffset` clamped to raw 0, for DOM reads that may land inside the leading marker
+ *  prefix, where the unclamped result goes negative. */
 export declare function toClampedRawOffset(domText: DomTextOffset, ambientLength: number): RawOffset;
 export declare function toEditorX(viewport: ViewportX, editorLeft: number): EditorX;
 export declare function toViewportX(editor: EditorX, editorLeft: number): ViewportX;
@@ -48,18 +47,26 @@ export declare function asDomTextOffset(n: number): DomTextOffset;
 export declare function asEditorX(n: number): EditorX;
 export declare function asViewportX(n: number): ViewportX;
 export declare function asCellIndex(n: number): CellIndex;
-/**
- * Row-major cell index → `{ row, col }` for a table of `colCount` columns — the one home
- * for the divmod the selection and table-overlay paths otherwise hand-roll. Takes a plain
- * number so a `CellIndex` holder and a bare loop counter both reach it without a cast.
- */
+/** Row-major cell index to `{ row, col }` for a table of `colCount` columns. Takes a plain
+ *  number so a `CellIndex` and a bare loop counter both reach it without a cast. */
 export declare function cellRowCol(cellIdx: number, colCount: number): {
     row: number;
     col: number;
 };
-/** Append a child index to a parent path, yielding a doc-absolute path. */
+/** Grid coordinates to the row-major cell index {@link cellRowCol} decodes. */
+export declare function rowMajorCellIndex(row: number, col: number, colCount: number): CellIndex;
+/** A rectangle of table cells: its top-left cell plus its size. */
+export interface CellRect {
+    top: number;
+    left: number;
+    rows: number;
+    cols: number;
+}
+/** The rectangle two cells span as its corners, in either order. */
+export declare function cellRectBounds(cornerA: number, cornerB: number, colCount: number): CellRect;
+/** Append a child index to a parent path, yielding a document-absolute path. */
 export declare function extendDocPath(parent: readonly number[], index: number): DocPath;
-/** Brand a complete doc-absolute path (copied) for composers that already hold one;
+/** Brand a complete document-absolute path (copied) for callers that already hold one;
  *  `extendDocPath` covers the parent-plus-index case, this covers the rest. */
 export declare function docPathFrom(indices: readonly number[]): DocPath;
 export {};

package/dist/cursor/coordinate-spaces.js

@@ -1,19 +1,19 @@
 /**
  * The editor's coordinate spaces as branded numbers (G3.7), so mixing them is a type error
- * at the seam instead of a caret bug later. A brand is produced only by its space's home
- * module or an `as*` boundary mint at a declared public door — the coordinate-brand-mints
- * lint holds that list closed — and moves between spaces only through the named
- * conversions below, one home per direction. Public API doors keep `number` and mint once.
+ * instead of a caret bug later. A brand is produced only by the module that owns its space or
+ * by an `as*` cast at a declared public entry point (G4.15's rows in `lint/file-rules.test.ts`
+ * hold that list closed), and moves between spaces only through the conversions below, one
+ * function per direction. Public API entry points take `number` and brand it once.
  */
-// ── Conversions (the inter-space arithmetic — one home per direction) ────────
+// ── Conversions (between spaces, one function per direction) ─────────────────
 export function toDomTextOffset(raw, ambientLength) {
     return (raw + ambientLength);
 }
 export function toRawOffset(domText, ambientLength) {
     return (domText - ambientLength);
 }
-/** `toRawOffset` clamped to raw 0, for DOM reads that may land inside the leading ambient
- *  marker, where the unclamped result goes negative. */
+/** `toRawOffset` clamped to raw 0, for DOM reads that may land inside the leading marker
+ *  prefix, where the unclamped result goes negative. */
 export function toClampedRawOffset(domText, ambientLength) {
     return Math.max(0, toRawOffset(domText, ambientLength));
 }
@@ -23,7 +23,7 @@ export function toEditorX(viewport, editorLeft) {
 export function toViewportX(editor, editorLeft) {
     return (editor + editorLeft);
 }
-// ── Boundary mints (space homes and declared doors only — see the lint) ──────
+// ── Brand casts (owning modules and declared entry points only; see the lint) ─
 export function asRawOffset(n) {
     return n;
 }
@@ -40,26 +40,38 @@ export function asCellIndex(n) {
     return n;
 }
 // ── Cell grid decode ─────────────────────────────────────────────────────────
-/**
- * Row-major cell index → `{ row, col }` for a table of `colCount` columns — the one home
- * for the divmod the selection and table-overlay paths otherwise hand-roll. Takes a plain
- * number so a `CellIndex` holder and a bare loop counter both reach it without a cast.
- */
+/** Row-major cell index to `{ row, col }` for a table of `colCount` columns. Takes a plain
+ *  number so a `CellIndex` and a bare loop counter both reach it without a cast. */
 export function cellRowCol(cellIdx, colCount) {
     const row = Math.floor(cellIdx / colCount);
     return { row, col: cellIdx - row * colCount };
 }
-// ── DocPath composition (the doc-absolute path helpers, at the neutral leaf) ──
+/** Grid coordinates to the row-major cell index {@link cellRowCol} decodes. */
+export function rowMajorCellIndex(row, col, colCount) {
+    return asCellIndex(row * colCount + col);
+}
+/** The rectangle two cells span as its corners, in either order. */
+export function cellRectBounds(cornerA, cornerB, colCount) {
+    const a = cellRowCol(cornerA, colCount);
+    const b = cellRowCol(cornerB, colCount);
+    const top = Math.min(a.row, b.row);
+    const left = Math.min(a.col, b.col);
+    return {
+        top,
+        left,
+        rows: Math.max(a.row, b.row) - top + 1,
+        cols: Math.max(a.col, b.col) - left + 1
+    };
+}
+// ── DocPath composition (document-absolute path helpers, in a dependency-free module) ──
 //
-// `DocPath`'s type and base mint live in `selection/path-math.ts`; its composers live here
-// because `tree-operations/` must reach them without depending on `selection/`. Bare
-// `as DocPath` casts for the same reason — importing the runtime mint would reopen the
-// cursor↔selection cycle, while the type-only `DocPath` edge is erased.
-/** Append a child index to a parent path, yielding a doc-absolute path. */
+// Here so `tree-operations/` can compose paths without importing `selection/`; the casts are
+// bare because importing `selection/path-math.ts` at runtime would close an import cycle.
+/** Append a child index to a parent path, yielding a document-absolute path. */
 export function extendDocPath(parent, index) {
     return [...parent, index];
 }
-/** Brand a complete doc-absolute path (copied) for composers that already hold one;
+/** Brand a complete document-absolute path (copied) for callers that already hold one;
  *  `extendDocPath` covers the parent-plus-index case, this covers the rest. */
 export function docPathFrom(indices) {
     return [...indices];

package/dist/cursor/dom-walk.d.ts

@@ -1,18 +1,12 @@
 /**
- * The one iterative pre-order over rendered inline DOM — the caret-space twin of
- * `core/inline/walk.ts`, and here rather than beside it because `cursor/` is what a DOM walk may
- * import from (`ambient/` reads this direction too, `core/` never does). Nesting depth is
- * input-controlled, so a per-level call frame overflows the stack and strands the block in the
- * unhealable failed-block fallback.
- */
-/**
- * `root`, then its descendants, in document order. `fromEnd` MIRRORS that walk rather than
- * reversing it — each level's children come last-first, a parent still ahead of them — so the
- * leaves arrive reversed and a search for the last matching one reads them in the order it wants.
- * `descend` declines a node's children: the node itself is still yielded, and is asked only when
- * it has any. Each child list is read when its parent pops, so a consumer that rewrites the tree
- * must finish the walk first.
+ * The one iterative pre-order traversal of rendered inline DOM, the DOM counterpart of
+ * `core/inline/walk.ts`. It lives here rather than beside it because `cursor/` is what a DOM walk
+ * may import from (`ambient/` reads this direction too, `core/` never does). Nesting depth comes
+ * from the input, so recursion would overflow the stack and leave the block stuck in the
+ * failed-block fallback.
  */
+/** `root`, then its descendants in document order, or mirrored by `fromEnd` (a parent still ahead
+ *  of its children). Child lists are read lazily, so finish the walk before rewriting the tree. */
 export declare function domDescendants(root: Node, descend?: (node: Node) => boolean, options?: {
     fromEnd?: boolean;
 }): Generator<Node>;

package/dist/cursor/dom-walk.js

@@ -1,18 +1,12 @@
 /**
- * The one iterative pre-order over rendered inline DOM — the caret-space twin of
- * `core/inline/walk.ts`, and here rather than beside it because `cursor/` is what a DOM walk may
- * import from (`ambient/` reads this direction too, `core/` never does). Nesting depth is
- * input-controlled, so a per-level call frame overflows the stack and strands the block in the
- * unhealable failed-block fallback.
- */
-/**
- * `root`, then its descendants, in document order. `fromEnd` MIRRORS that walk rather than
- * reversing it — each level's children come last-first, a parent still ahead of them — so the
- * leaves arrive reversed and a search for the last matching one reads them in the order it wants.
- * `descend` declines a node's children: the node itself is still yielded, and is asked only when
- * it has any. Each child list is read when its parent pops, so a consumer that rewrites the tree
- * must finish the walk first.
+ * The one iterative pre-order traversal of rendered inline DOM, the DOM counterpart of
+ * `core/inline/walk.ts`. It lives here rather than beside it because `cursor/` is what a DOM walk
+ * may import from (`ambient/` reads this direction too, `core/` never does). Nesting depth comes
+ * from the input, so recursion would overflow the stack and leave the block stuck in the
+ * failed-block fallback.
  */
+/** `root`, then its descendants in document order, or mirrored by `fromEnd` (a parent still ahead
+ *  of its children). Child lists are read lazily, so finish the walk before rewriting the tree. */
 export function* domDescendants(root, descend, options = {}) {
     const stack = [root];
     while (stack.length > 0) {