@voithos-labs/aragonite 0.10.1

package/dist/core/terminator-escalation.js

@@ -0,0 +1,18 @@
+/**
+ * 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 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;
+        const run = closerRun(text, required);
+        if (run !== null)
+            required = run + 1;
+    }
+    return required;
+}

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

@@ -0,0 +1,14 @@
+/**
+ * URL scheme allowlist for rendered href/src, enforced at the render sinks so author-controlled
+ * URLs cannot smuggle script execution into the DOM. `defaultLinkActivation` is the one DOM sink.
+ */
+/** A schemeless URL (relative, fragment, protocol-relative) is allowed. */
+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.
+ */
+export declare function defaultLinkActivation(url: string, _event: MouseEvent, onBlocked?: (url: string) => void): void;

package/dist/core/url-policy.js

@@ -0,0 +1,44 @@
+/**
+ * URL scheme allowlist for rendered href/src, enforced at the render sinks so author-controlled
+ * 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.
+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.
+function schemeOf(url) {
+    const stripped = url.replace(/[\t\n\r]/g, '');
+    let i = 0;
+    while (i < stripped.length && stripped.charCodeAt(i) <= 0x20)
+        i++;
+    const match = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(stripped.slice(i));
+    return match ? match[1].toLowerCase() : null;
+}
+/** A schemeless URL (relative, fragment, protocol-relative) is allowed. */
+export function isAllowedHrefScheme(url) {
+    const scheme = schemeOf(url);
+    return scheme === null || ALLOWED_HREF_SCHEMES.has(scheme);
+}
+/** Same rule as href over a different set: schemes that hand bytes to an `<img>`. */
+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.
+ */
+export function defaultLinkActivation(url, _event, onBlocked) {
+    if (isAllowedHrefScheme(url)) {
+        window.open(url, '_blank', 'noopener,noreferrer');
+        return;
+    }
+    devWarn('url-policy', `blocked link with disallowed scheme: ${url}`);
+    onBlocked?.(url);
+}

package/dist/cursor/content-offsets.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Cursor / range / selection helpers for contenteditable text surfaces. Offsets count DOM
+ * text characters ambient-inclusively (`Range.toString()` does not skip
+ * contenteditable=false islands), so they are `DomTextOffset`. An offset inside a span the
+ * cursor may not enter — an atomic inline widget, or marker text the mode hides — snaps to
+ * that span's leading or trailing edge.
+ */
+import { type DomTextOffset } from './coordinate-spaces';
+export declare function createRangeFromOffsets(container: HTMLElement, start: DomTextOffset, end: DomTextOffset): Range | null;
+export declare function setCursorOffset(container: HTMLElement, offset: DomTextOffset): void;
+/** The range START (anchor for forward selections); the moving endpoint during Shift+Arrow
+ *  extension is `getSelectionFocusOffset`. */
+export declare function getCursorOffset(container: HTMLElement): DomTextOffset | null;
+/** The moving endpoint of the selection, distinct from the anchor once extended. */
+export declare function getSelectionFocusOffset(container: HTMLElement): DomTextOffset | null;
+export declare function getSelectionOffsets(container: HTMLElement): {
+    start: DomTextOffset;
+    end: DomTextOffset;
+} | null;
+/**
+ * Offsets for an arbitrary range inside `container` — an InputEvent's `getTargetRanges()`
+ * pending-edit range is not the live selection (a word delete at a collapsed caret reports
+ * the whole word). Null when either endpoint sits outside the container.
+ */
+export declare function getRangeOffsets(container: HTMLElement, range: AbstractRange): {
+    start: DomTextOffset;
+    end: DomTextOffset;
+} | null;
+export declare function hasSelection(): boolean;

package/dist/cursor/content-offsets.js

@@ -0,0 +1,151 @@
+/**
+ * Cursor / range / selection helpers for contenteditable text surfaces. Offsets count DOM
+ * text characters ambient-inclusively (`Range.toString()` does not skip
+ * contenteditable=false islands), so they are `DomTextOffset`. An offset inside a span the
+ * cursor may not enter — an atomic inline widget, or marker text the mode hides — snaps to
+ * that span's leading or trailing edge.
+ */
+import { asDomTextOffset } from './coordinate-spaces';
+import { domDescendants } from './dom-walk';
+import { isAtomicInlineWidget, isHiddenMarkerRoot } from './widget-offset';
+/**
+ * Length of a span the cursor may not enter, or null when it is transparent. Atomic widgets
+ * and marker text the mode paints nothing for are both opaque: an offset inside either has
+ * no position to seat, and hiding is classified at its one home, never re-derived here.
+ */
+function opaqueSpanLength(node, container) {
+    if (node.nodeType !== Node.ELEMENT_NODE)
+        return null;
+    const el = node;
+    if (!isAtomicInlineWidget(el) && !isHiddenMarkerRoot(el, container))
+        return null;
+    return el.textContent?.length ?? 0;
+}
+export function createRangeFromOffsets(container, start, end) {
+    const range = document.createRange();
+    let charCount = 0;
+    let startSet = false;
+    let endFound = false;
+    // One classification per node, though the walk and the body below both ask: the read is a
+    // `contains` plus a `closest` per element, and a caret seat spends this walk on every step.
+    const opaque = new Map();
+    const opaqueLengthOf = (node) => {
+        if (!opaque.has(node))
+            opaque.set(node, opaqueSpanLength(node, container));
+        return opaque.get(node) ?? null;
+    };
+    for (const node of domDescendants(container, (node) => opaqueLengthOf(node) === null)) {
+        // The cursor never lands inside an opaque span: snap to the nearer edge.
+        const opaqueLen = opaqueLengthOf(node);
+        if (opaqueLen !== null) {
+            if (!startSet && start <= charCount + opaqueLen) {
+                if (start <= charCount)
+                    range.setStartBefore(node);
+                else
+                    range.setStartAfter(node);
+                startSet = true;
+            }
+            if (startSet && end <= charCount + opaqueLen) {
+                if (end <= charCount)
+                    range.setEndBefore(node);
+                else
+                    range.setEndAfter(node);
+                endFound = true;
+                break;
+            }
+            charCount += opaqueLen;
+            continue;
+        }
+        if (node.nodeType === Node.TEXT_NODE) {
+            const len = node.textContent?.length ?? 0;
+            if (!startSet && charCount + len >= start) {
+                range.setStart(node, start - charCount);
+                startSet = true;
+            }
+            if (startSet && charCount + len >= end) {
+                range.setEnd(node, end - charCount);
+                endFound = true;
+                break;
+            }
+            charCount += len;
+        }
+    }
+    if (!startSet) {
+        range.selectNodeContents(container);
+        range.collapse(false);
+    }
+    else if (!endFound) {
+        range.setEndAfter(container);
+    }
+    return range;
+}
+export function setCursorOffset(container, offset) {
+    const range = createRangeFromOffsets(container, offset, offset);
+    if (!range)
+        return;
+    const sel = window.getSelection();
+    sel?.removeAllRanges();
+    sel?.addRange(range);
+}
+/**
+ * The one "DOM (node, offset) → content-offset" read here. `Selection.toString()` skips
+ * text inside contenteditable=false islands and is unreliable across them; `Range.toString()`
+ * on a prefix range does not skip, so all readers funnel through this.
+ */
+function nodeOffsetToContent(container, node, offset) {
+    const preRange = document.createRange();
+    preRange.selectNodeContents(container);
+    try {
+        preRange.setEnd(node, offset);
+    }
+    catch {
+        return asDomTextOffset(0);
+    }
+    return asDomTextOffset(preRange.toString().length);
+}
+/** The range START (anchor for forward selections); the moving endpoint during Shift+Arrow
+ *  extension is `getSelectionFocusOffset`. */
+export function getCursorOffset(container) {
+    if (document.activeElement !== container)
+        return null;
+    const sel = window.getSelection();
+    if (!sel || sel.rangeCount === 0)
+        return null;
+    const range = sel.getRangeAt(0);
+    return nodeOffsetToContent(container, range.startContainer, range.startOffset);
+}
+/** The moving endpoint of the selection, distinct from the anchor once extended. */
+export function getSelectionFocusOffset(container) {
+    if (document.activeElement !== container)
+        return null;
+    const sel = window.getSelection();
+    if (!sel || sel.focusNode === null)
+        return null;
+    if (!container.contains(sel.focusNode))
+        return null;
+    return nodeOffsetToContent(container, sel.focusNode, sel.focusOffset);
+}
+export function getSelectionOffsets(container) {
+    const sel = window.getSelection();
+    if (!sel || sel.isCollapsed)
+        return null;
+    return getRangeOffsets(container, sel.getRangeAt(0));
+}
+/**
+ * Offsets for an arbitrary range inside `container` — an InputEvent's `getTargetRanges()`
+ * pending-edit range is not the live selection (a word delete at a collapsed caret reports
+ * the whole word). Null when either endpoint sits outside the container.
+ */
+export function getRangeOffsets(container, range) {
+    if (!container.contains(range.startContainer) || !container.contains(range.endContainer)) {
+        return null;
+    }
+    return {
+        start: nodeOffsetToContent(container, range.startContainer, range.startOffset),
+        end: nodeOffsetToContent(container, range.endContainer, range.endOffset)
+    };
+}
+export function hasSelection() {
+    const sel = window.getSelection();
+    return Boolean(sel && !sel.isCollapsed);
+}

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

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ */
+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). */
+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.
+ */
+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. */
+export type EditorX = number & {
+    readonly [editorXBrand]: true;
+};
+declare const viewportXBrand: unique symbol;
+/** Raw client-rect pixel X. */
+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
+ *  `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. */
+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;
+export declare function asRawOffset(n: number): RawOffset;
+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.
+ */
+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. */
+export declare function extendDocPath(parent: readonly number[], index: number): DocPath;
+/** Brand a complete doc-absolute path (copied) for composers 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

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ */
+// ── Conversions (the inter-space arithmetic — one home 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. */
+export function toClampedRawOffset(domText, ambientLength) {
+    return Math.max(0, toRawOffset(domText, ambientLength));
+}
+export function toEditorX(viewport, editorLeft) {
+    return (viewport - editorLeft);
+}
+export function toViewportX(editor, editorLeft) {
+    return (editor + editorLeft);
+}
+// ── Boundary mints (space homes and declared doors only — see the lint) ──────
+export function asRawOffset(n) {
+    return n;
+}
+export function asDomTextOffset(n) {
+    return n;
+}
+export function asEditorX(n) {
+    return n;
+}
+export function asViewportX(n) {
+    return n;
+}
+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.
+ */
+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) ──
+//
+// `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. */
+export function extendDocPath(parent, index) {
+    return [...parent, index];
+}
+/** Brand a complete doc-absolute path (copied) for composers 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

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+export declare function domDescendants(root: Node, descend?: (node: Node) => boolean, options?: {
+    fromEnd?: boolean;
+}): Generator<Node>;

package/dist/cursor/dom-walk.js

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ */
+export function* domDescendants(root, descend, options = {}) {
+    const stack = [root];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        yield node;
+        const children = node.childNodes;
+        if (children.length === 0)
+            continue;
+        if (descend && !descend(node))
+            continue;
+        // Reversed push, so pop order is the walk's order: document order, or its reverse.
+        for (let i = 0; i < children.length; i++) {
+            stack.push(children[options.fromEnd ? i : children.length - 1 - i]);
+        }
+    }
+}

package/dist/cursor/edge-affinity.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Edge affinity: which of the two raw offsets a caret means when it sits beside a hidden
+ * marker run, whose interior paints nothing so both offsets land on one pixel. CAPTURE: the
+ * arrival that put the caret there, via `note` on the shared keydown door. CONSUME: the
+ * typing seat, which reads `get()` and keeps its own default when it answers null.
+ */
+/**
+ * Which raw offset a hidden run's one pixel names. Two answers are positional — the run's
+ * `near` (earlier) or `far` (later) walk-order side — and one is construct-relative:
+ * `outside` means past the construct's delimiters whichever side that lands on, so it reads
+ * as the run's start at an opener and its end at a closer.
+ */
+export type EdgeAffinity = 'near' | 'far' | 'outside';
+export interface EdgeAffinityState {
+    get(): EdgeAffinity | null;
+    /**
+     * The only door a keydown handler may use; `reset()` stays public for the lifecycle,
+     * commit, undo and pointer callers, whose unconditional clear has no key to classify.
+     */
+    note(e: Pick<KeyboardEvent, 'key' | 'altKey'> & Partial<Pick<KeyboardEvent, 'metaKey'>>): void;
+    /** A committed keystroke belongs to the content whatever arrival preceded it. */
+    noteTyping(): void;
+    /**
+     * A caret seated at an EXTREME rather than stepped there — a range collapsing onto its own
+     * edge. The key that triggered it is directional, but the caret took no step, so the side it
+     * means is construct-relative, the same answer a line extreme gives.
+     */
+    noteExtreme(): void;
+    reset(): void;
+}
+export interface EdgeAffinityDeps {
+    /**
+     * Ephemeral caret state with this same lifetime rides the invalidation (pending marks,
+     * `cursor/pending-marks.ts`). Composed rather than copied at each seam: every seat below
+     * already reaches exactly one of these three doors.
+     */
+    onInvalidate?: () => void;
+}
+export declare function createEdgeAffinityState(deps?: EdgeAffinityDeps): EdgeAffinityState;
+/** What a keydown does to the affinity. */
+export type EdgeAffinityAction = EdgeAffinity | 'preserve' | 'reset';
+/** The decision {@link EdgeAffinityState.note} enacts. Pure on the key, so the matrix is
+ *  testable without a DOM or a state instance. */
+export declare function classifyArrivalKey(key: string, metaKey?: boolean): EdgeAffinityAction;

package/dist/cursor/edge-affinity.js

@@ -0,0 +1,60 @@
+/**
+ * Edge affinity: which of the two raw offsets a caret means when it sits beside a hidden
+ * marker run, whose interior paints nothing so both offsets land on one pixel. CAPTURE: the
+ * arrival that put the caret there, via `note` on the shared keydown door. CONSUME: the
+ * typing seat, which reads `get()` and keeps its own default when it answers null.
+ */
+import { BARE_MODIFIER_KEYS, isCharacterKey } from '../schema/keybindings';
+export function createEdgeAffinityState(deps = {}) {
+    let affinity = null;
+    /** Sets the side AND settles everything riding on it — the two are one act, so no caller
+     *  can do the first without the second. */
+    function settle(next) {
+        affinity = next;
+        deps.onInvalidate?.();
+    }
+    return {
+        get: () => affinity,
+        noteTyping: () => settle('near'),
+        noteExtreme: () => settle('outside'),
+        reset: () => settle(null),
+        note: (e) => {
+            // Alt+Arrow is the block-reorder chord, not caret nav.
+            if (e.altKey && (e.key === 'ArrowUp' || e.key === 'ArrowDown'))
+                return;
+            const action = classifyArrivalKey(e.key, e.metaKey);
+            // A preserved key left the caret where it was — the chord that pends a mark and the
+            // byte that spends it are both preserved, so neither may invalidate.
+            if (action === 'preserve')
+                return;
+            settle(action === 'reset' ? null : action);
+        }
+    };
+}
+/** The decision {@link EdgeAffinityState.note} enacts. Pure on the key, so the matrix is
+ *  testable without a DOM or a state instance. */
+export function classifyArrivalKey(key, metaKey = false) {
+    // macOS Cmd+Arrow is the line extreme — a seat, not a step, so it takes Home/End's
+    // construct-relative answer. Windows/Linux never deliver meta+arrow to the page.
+    if (metaKey && (key === 'ArrowLeft' || key === 'ArrowRight'))
+        return 'outside';
+    // A step stops on the side of the run it approached from, so one press never changes which
+    // construct the caret is in: forward keys reach the near side, backward keys the far one.
+    if (key === 'ArrowRight' || key === 'ArrowDown' || key === 'PageDown')
+        return 'near';
+    if (key === 'ArrowLeft' || key === 'ArrowUp' || key === 'PageUp')
+        return 'far';
+    // A line extreme is construct-relative, not directional: `Home` before a line-leading
+    // construct means before its opener, which is the run's EARLIER side — the opposite
+    // walk-order answer from `End` after a line-trailing one.
+    if (key === 'Home' || key === 'End')
+        return 'outside';
+    // Bare modifiers are read from the chord parser rather than re-listed — a local copy
+    // missing AltGraph is how a modifier tap mid-arrow-run drops the side. A printable key
+    // preserves because its write seat reads the side later in this same keydown.
+    if (BARE_MODIFIER_KEYS.includes(key) || isCharacterKey(key))
+        return 'preserve';
+    // Anything left lands by a mutation or a command, not by an arrival; the commit seams
+    // re-arm through `noteTyping`.
+    return 'reset';
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Carry a focused caret across an imperative DOM rebuild. A decoration-driven rebuild
+ * mints fresh spans with no edit-path pending offset, so the render path captures the
+ * caret in walk space before the rebuild and restores it after — through the single-home
+ * offset walk (`widget-offset.ts`), shared by the prose and table-cell render paths.
+ */
+import type { DomTextOffset } from './coordinate-spaces';
+/** The live caret as a walk-space offset, or null when `el` does not own focus. */
+export declare function captureFocusedCaretWalkOffset(el: HTMLElement): DomTextOffset | null;
+export declare function restoreCaretAtWalkOffset(el: HTMLElement, walkOffset: DomTextOffset): void;

package/dist/cursor/focused-caret.js

@@ -0,0 +1,24 @@
+/**
+ * Carry a focused caret across an imperative DOM rebuild. A decoration-driven rebuild
+ * mints fresh spans with no edit-path pending offset, so the render path captures the
+ * caret in walk space before the rebuild and restores it after — through the single-home
+ * offset walk (`widget-offset.ts`), shared by the prose and table-cell render paths.
+ */
+import { createRangeAtDomTextOffsets, domTextOffsetAtNode } from './widget-offset';
+/** The live caret as a walk-space offset, or null when `el` does not own focus. */
+export function captureFocusedCaretWalkOffset(el) {
+    if (!document.activeElement || !el.contains(document.activeElement))
+        return null;
+    const sel = window.getSelection();
+    if (!sel?.focusNode || !el.contains(sel.focusNode))
+        return null;
+    return domTextOffsetAtNode(el, sel.focusNode, sel.focusOffset);
+}
+export function restoreCaretAtWalkOffset(el, walkOffset) {
+    const range = createRangeAtDomTextOffsets(el, walkOffset, walkOffset);
+    if (!range)
+        return;
+    const sel = window.getSelection();
+    sel?.removeAllRanges();
+    sel?.addRange(range);
+}

package/dist/cursor/height-model.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Cumulative block-height model for one BlockList: a Fenwick tree giving O(log n)
+ * prefix-sum, offset→index lookup, and per-index update. Virtual rendering maps scrollTop
+ * to a window range through it without laying off-screen blocks out.
+ */
+export declare class HeightModel {
+    private tree;
+    private heights;
+    private count;
+    constructor(initialHeights: number[]);
+    get size(): number;
+    /** Total pixel height of all entries. */
+    total(): number;
+    /** Pixel offset of the top of index `i` (sum of heights[0..i)); `offsetOf(count)` == total. */
+    offsetOf(i: number): number;
+    /** Current height stored for index `i`. */
+    heightOf(i: number): number;
+    /** Set index `i` to `height` in O(log n). No-op when unchanged or out of range. */
+    setHeight(i: number, height: number): void;
+    /** Largest index whose top offset is <= `y` (the block visible at scroll y), clamped to [0, count-1]. */
+    indexAtOffset(y: number): number;
+    private bump;
+    private prefix;
+}