@voithos-labs/aragonite 0.10.1

package/dist/cursor/height-model.js

@@ -0,0 +1,72 @@
+/**
+ * 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 class HeightModel {
+    tree; // 1-indexed Fenwick sums
+    heights; // per-index current height, for O(1) read-back
+    count;
+    constructor(initialHeights) {
+        this.count = initialHeights.length;
+        this.heights = initialHeights.slice();
+        this.tree = new Array(this.count + 1).fill(0);
+        for (let i = 0; i < this.count; i++)
+            this.bump(i, initialHeights[i]);
+    }
+    get size() {
+        return this.count;
+    }
+    /** Total pixel height of all entries. */
+    total() {
+        return this.prefix(this.count);
+    }
+    /** Pixel offset of the top of index `i` (sum of heights[0..i)); `offsetOf(count)` == total. */
+    offsetOf(i) {
+        // prefix(i) past `count` reads off the Fenwick array → NaN into every spacer.
+        return this.prefix(Math.max(0, Math.min(i, this.count)));
+    }
+    /** Current height stored for index `i`. */
+    heightOf(i) {
+        return this.heights[i] ?? 0;
+    }
+    /** Set index `i` to `height` in O(log n). No-op when unchanged or out of range. */
+    setHeight(i, height) {
+        // Out of range corrupts the model: i >= count poisons heights[] with no tree update,
+        // and i < 0 makes bump's `p += p & -p` stall at p=0 forever.
+        if (i < 0 || i >= this.count)
+            return;
+        const delta = height - this.heights[i];
+        if (delta === 0)
+            return;
+        this.heights[i] = height;
+        this.bump(i, delta);
+    }
+    /** Largest index whose top offset is <= `y` (the block visible at scroll y), clamped to [0, count-1]. */
+    indexAtOffset(y) {
+        if (this.count === 0)
+            return 0;
+        let idx = 0;
+        let remaining = y;
+        let bit = 1 << Math.floor(Math.log2(this.count));
+        while (bit > 0) {
+            const next = idx + bit;
+            if (next <= this.count && this.tree[next] <= remaining) {
+                idx = next;
+                remaining -= this.tree[next];
+            }
+            bit >>= 1;
+        }
+        return Math.min(idx, this.count - 1);
+    }
+    bump(i, delta) {
+        for (let p = i + 1; p <= this.count; p += p & -p)
+            this.tree[p] += delta;
+    }
+    prefix(i) {
+        let s = 0;
+        for (let p = i; p > 0; p -= p & -p)
+            s += this.tree[p];
+        return s;
+    }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Per-kind block-height estimator plus a measured-height cache for virtual rendering.
+ * `estimate` is O(1) from `node.raw` length even for containers (their raw is
+ * materialized, so no subtree walk). Measured heights supersede estimates and are keyed by
+ * stable block id, so structural index shifts and undo don't invalidate them.
+ */
+import type { NodeView } from '../core/node-views';
+export interface HeightOracleOptions {
+    lineHeight: number;
+    codeLineHeight: number;
+    avgCharWidth: number;
+    blockChrome: number;
+    imageBlockMinHeight: number;
+}
+export interface HeightOracle {
+    estimate(node: NodeView, width: number): number;
+    measured(id: string): number | undefined;
+    recordMeasured(id: string, height: number): void;
+    /** measured(id) ?? estimate(node, width). */
+    height(id: string, node: NodeView, width: number): number;
+    /** Drop every measured height; estimates carry the model until each block re-measures. */
+    dropMeasured(): void;
+}
+export declare function createHeightOracle(opts: HeightOracleOptions): HeightOracle;

package/dist/cursor/height-oracle.js

@@ -0,0 +1,94 @@
+import { isCollapsedByDescriptor } from '../schema/reserved-chrome';
+import { tryGetBlockKindDescriptor } from '../schema/block-kind-descriptor';
+// Any image form, capturing the alt segment for its `|WxH` size hint. The char-based prose
+// estimate badly undercounts a rendered image, so an image-bearing block sizes off this.
+const IMAGE_ALT = /!\[([^\]]*)\]/g;
+// Size hint inside the alt, e.g. `Square|200x200` or `photo|400` (width only).
+const SIZE_HINT = /\|(\d+)(?:x(\d+))?/;
+const NEWLINE = 10;
+export function createHeightOracle(opts) {
+    const measuredById = new Map();
+    function wrappedLines(visibleLen, width) {
+        const perLine = Math.max(1, Math.floor(width / opts.avgCharWidth));
+        return Math.max(1, Math.ceil(visibleLen / perLine));
+    }
+    function sourceLines(raw) {
+        let n = 1;
+        // Code units, not `raw[i]`: the indexed read mints a one-character string per byte.
+        for (let i = 0; i < raw.length; i++)
+            if (raw.charCodeAt(i) === NEWLINE)
+                n++;
+        if (raw.endsWith('\n'))
+            n--; // trailing newline shouldn't add a phantom line
+        return Math.max(1, n);
+    }
+    // Each image contributes its `|WxH` hint height, else the min-height floor — an unsized
+    // image isn't knowable until decode, which the ResizeObserver corrects post-mount.
+    function imageHeights(raw) {
+        let total = 0;
+        IMAGE_ALT.lastIndex = 0;
+        let m;
+        while ((m = IMAGE_ALT.exec(raw)) !== null) {
+            const hint = SIZE_HINT.exec(m[1]);
+            total += hint && hint[2] ? Number(hint[2]) : opts.imageBlockMinHeight;
+        }
+        return total;
+    }
+    function estimate(node, width) {
+        // One registry lookup, read twice: the model seeds this once per block of the document.
+        const descriptor = tryGetBlockKindDescriptor(node.kind);
+        // A collapsed container's body lives in `raw` but never renders, so estimating from
+        // full `raw` over-counts it several-fold; only the chrome row paints.
+        if (isCollapsedByDescriptor(descriptor, node))
+            return opts.lineHeight + opts.blockChrome;
+        // A descriptor's own O(1) estimate supersedes the built-in arms (a rendered artifact
+        // is far taller than its source text); the oracle still adds chrome.
+        const custom = descriptor?.estimateHeight;
+        if (custom)
+            return custom(node, { width }) + opts.blockChrome;
+        const kind = node.kind;
+        const raw = node.raw;
+        switch (kind) {
+            case 'thematicBreak':
+                return opts.lineHeight + opts.blockChrome;
+            case 'fencedCode':
+            case 'indentedCode':
+            case 'htmlBlock':
+                return sourceLines(raw) * opts.codeLineHeight + opts.blockChrome;
+            case 'table':
+            case 'tableRow':
+                // Source lines model a normal table; a wide one wraps its cells far beyond its
+                // row count, which the blob-wrap of the whole raw catches.
+                return (Math.max(sourceLines(raw), wrappedLines(raw.length, width)) * opts.lineHeight +
+                    opts.blockChrome);
+            case 'blockquote':
+            case 'list':
+            case 'listItem': {
+                // Max of two terms, each alone wrong: the blob term ignores newlines and
+                // per-child chrome, the child-count term ignores wrap. Still O(1), no walk.
+                const childCount = Math.max(1, node.children?.length ?? 1);
+                const byChildren = childCount * (opts.lineHeight + opts.blockChrome);
+                const byText = wrappedLines(raw.length, width) * opts.lineHeight + opts.blockChrome;
+                return Math.max(byChildren, byText);
+            }
+            default: {
+                const prose = wrappedLines(raw.length, width) * opts.lineHeight + opts.blockChrome;
+                // Substring test first: the alt-capturing scan otherwise runs over every prose
+                // block in the document, and all but a handful carry no image at all.
+                if (!raw.includes('!['))
+                    return prose;
+                const images = imageHeights(raw);
+                return images > 0 ? Math.max(prose, images) : prose;
+            }
+        }
+    }
+    return {
+        estimate,
+        measured: (id) => measuredById.get(id),
+        recordMeasured: (id, height) => {
+            measuredById.set(id, height);
+        },
+        height: (id, node, width) => measuredById.get(id) ?? estimate(node, width),
+        dropMeasured: () => measuredById.clear()
+    };
+}

package/dist/cursor/overlay-rects.d.ts

@@ -0,0 +1,8 @@
+/** The client rects a block contributes when it is an endpoint of a cross-block selection. */
+import type { DomTextOffset } from './coordinate-spaces';
+/**
+ * Client rects covering the walk-space range [startOffset, endOffset) within `el` (see
+ * `cursor/widget-offset.ts`). The `getClientRects` guard keeps jsdom unit tests from
+ * crashing; real pixel geometry is covered by e2e.
+ */
+export declare function measurePartialRectsInContentEditable(el: HTMLElement, startOffset: DomTextOffset, endOffset: DomTextOffset): DOMRect[];

package/dist/cursor/overlay-rects.js

@@ -0,0 +1,19 @@
+/** The client rects a block contributes when it is an endpoint of a cross-block selection. */
+import { createRangeAtDomTextOffsets, widgetsIntersectingRange } from './widget-offset';
+/**
+ * Client rects covering the walk-space range [startOffset, endOffset) within `el` (see
+ * `cursor/widget-offset.ts`). The `getClientRects` guard keeps jsdom unit tests from
+ * crashing; real pixel geometry is covered by e2e.
+ */
+export function measurePartialRectsInContentEditable(el, startOffset, endOffset) {
+    if (startOffset === endOffset)
+        return [];
+    const range = createRangeAtDomTextOffsets(el, startOffset, endOffset);
+    const rects = range && typeof range.getClientRects === 'function' ? Array.from(range.getClientRects()) : [];
+    // An atomic widget adds 0 chars to textContent, so a range inside one emits no text
+    // rect; its bounding box is what keeps the highlight visible over it.
+    for (const widget of widgetsIntersectingRange(el, startOffset, endOffset)) {
+        rects.push(widget.getBoundingClientRect());
+    }
+    return rects;
+}

package/dist/cursor/overlay-remeasure.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared scroll-listener wiring for DecorationOverlay and SelectionOverlay: measure on
+ * mount, on scroll, and on the table's row-window `$derived` moving. That third trigger is
+ * load-bearing for windowed tables — a raw 'scroll' fires BEFORE the windowed `{#each}`
+ * mounts the new rows, so only the dep-based re-run measures post-commit.
+ */
+import type { BlockComponent } from '../block-component';
+export declare function wireOverlayRemeasure(opts: {
+    el: HTMLElement;
+    editorRoot: HTMLElement | null;
+    blockRef: BlockComponent | undefined;
+    measure: () => void;
+    /** Run the SETUP measure untracked, for a caller whose `measure` reads the document: tracking
+     *  it would tear down and re-wire these listeners on every keystroke. Scoped to that one call,
+     *  never the whole wiring — the row-window read below must stay tracked either way. */
+    untrackSetupMeasure?: boolean;
+}): () => void;

package/dist/cursor/overlay-remeasure.js

@@ -0,0 +1,31 @@
+/**
+ * Shared scroll-listener wiring for DecorationOverlay and SelectionOverlay: measure on
+ * mount, on scroll, and on the table's row-window `$derived` moving. That third trigger is
+ * load-bearing for windowed tables — a raw 'scroll' fires BEFORE the windowed `{#each}`
+ * mounts the new rows, so only the dep-based re-run measures post-commit.
+ */
+import { untrack } from 'svelte';
+import { firstScrollableDescendant, nearestScrollContainer } from './scroll-ancestors';
+export function wireOverlayRemeasure(opts) {
+    const { el, editorRoot, blockRef, measure } = opts;
+    // Plain synchronous read so the enclosing $effect registers as a dep of the table's win
+    // $derived. Must NOT be inside untrack().
+    blockRef?.mountedRowWindow?.();
+    if (opts.untrackSetupMeasure)
+        untrack(measure);
+    else
+        measure();
+    const scrollEl = firstScrollableDescendant(el) ?? (editorRoot ? nearestScrollContainer(el, editorRoot) : null);
+    const disposers = [];
+    if (scrollEl) {
+        scrollEl.addEventListener('scroll', measure, { passive: true });
+        disposers.push(() => scrollEl.removeEventListener('scroll', measure));
+    }
+    // The editor root's vertical scroll is distinct from a block's inner scroll container;
+    // this covers the non-windowed repaint-on-scroll path.
+    if (editorRoot && editorRoot !== scrollEl) {
+        editorRoot.addEventListener('scroll', measure, { passive: true });
+        disposers.push(() => editorRoot.removeEventListener('scroll', measure));
+    }
+    return () => disposers.forEach((dispose) => dispose());
+}

package/dist/cursor/pending-marks.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Pending marks: the inline constructs a collapsed-caret toggle promises the NEXT insertion,
+ * relative to the caret's construct chain — a kind already in the chain is a removal, one absent
+ * is an application. Live mode paints no delimiter, so materializing an empty pair in the bytes
+ * would leave invisible `****` behind on an abandoned toggle. SET by the toggle command, CONSUMED
+ * by the typing and composition seats, INVALIDATED by the edge affinity (live-mode.md § 4.3).
+ */
+import type { InlineMarkKind } from '../schema/inline-construct-policy';
+export interface PendingMarksState {
+    /** Null when nothing is pending; never an empty set, so a read is the whole question. */
+    get(): ReadonlySet<InlineMarkKind> | null;
+    /** A toggle chord at a collapsed caret. The same chord twice pends nothing again. */
+    toggle(kind: InlineMarkKind): void;
+    /** Read and clear: exactly one insertion spends the set. */
+    consume(): ReadonlySet<InlineMarkKind> | null;
+    /** Hand back a set taken for an insertion that never happened (an IME cancel). Declines once
+     *  anything else is pending: that is a newer instruction about the same caret. */
+    restore(marks: ReadonlySet<InlineMarkKind>): void;
+    reset(): void;
+}
+export declare function createPendingMarksState(): PendingMarksState;
+/** The set a chord press produces, or null once it empties. Pure, so the toggle matrix is
+ *  testable without an instance. */
+export declare function flipMark(marks: ReadonlySet<InlineMarkKind> | null, kind: InlineMarkKind): ReadonlySet<InlineMarkKind> | null;

package/dist/cursor/pending-marks.js

@@ -0,0 +1,36 @@
+/**
+ * Pending marks: the inline constructs a collapsed-caret toggle promises the NEXT insertion,
+ * relative to the caret's construct chain — a kind already in the chain is a removal, one absent
+ * is an application. Live mode paints no delimiter, so materializing an empty pair in the bytes
+ * would leave invisible `****` behind on an abandoned toggle. SET by the toggle command, CONSUMED
+ * by the typing and composition seats, INVALIDATED by the edge affinity (live-mode.md § 4.3).
+ */
+export function createPendingMarksState() {
+    let marks = null;
+    return {
+        get: () => marks,
+        toggle: (kind) => {
+            marks = flipMark(marks, kind);
+        },
+        consume: () => {
+            const spent = marks;
+            marks = null;
+            return spent;
+        },
+        restore: (unspent) => {
+            if (marks === null)
+                marks = unspent;
+        },
+        reset: () => {
+            marks = null;
+        }
+    };
+}
+/** The set a chord press produces, or null once it empties. Pure, so the toggle matrix is
+ *  testable without an instance. */
+export function flipMark(marks, kind) {
+    const next = new Set(marks ?? []);
+    if (!next.delete(kind))
+        next.add(kind);
+    return next.size > 0 ? next : null;
+}

package/dist/cursor/point-offset.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Viewport point → caret offset inside one element. The probe is the browser's, the arithmetic
+ * is `widget-offset.ts`'s walk: this module mints no offset of its own, so an atomic widget and
+ * a leading ambient marker count here exactly as they do for a live caret read.
+ */
+/**
+ * The caret offset in `el` NEAREST a viewport point: the point clamps into `el`'s box first, so a
+ * press on chrome above or beside the text still names one. What `caretTargetAtPoint` owes, since
+ * a caret-placing gesture must land. Null where the element holds no text position at all.
+ */
+export declare function caretOffsetAtPoint(el: HTMLElement, clientX: number, clientY: number): number | null;
+/**
+ * The EXACT twin: null for a point outside `el`, which a hit test must decline rather than
+ * round into the nearest offset.
+ */
+export declare function offsetFromViewportPoint(blockEl: HTMLElement, clientX: number, clientY: number): number | null;
+/** A point one pixel inside `rect`, so the topmost element there is the box's own content. */
+export declare function clampPointIntoBox(rect: DOMRect, x: number, y: number): {
+    x: number;
+    y: number;
+};

package/dist/cursor/point-offset.js

@@ -0,0 +1,48 @@
+/**
+ * Viewport point → caret offset inside one element. The probe is the browser's, the arithmetic
+ * is `widget-offset.ts`'s walk: this module mints no offset of its own, so an atomic widget and
+ * a leading ambient marker count here exactly as they do for a live caret read.
+ */
+import { ambientLengthOf } from '../ambient/ambient-dom';
+import { toClampedRawOffset } from './coordinate-spaces';
+import { domTextOffsetAtNode } from './widget-offset';
+/**
+ * The caret offset in `el` NEAREST a viewport point: the point clamps into `el`'s box first, so a
+ * press on chrome above or beside the text still names one. What `caretTargetAtPoint` owes, since
+ * a caret-placing gesture must land. Null where the element holds no text position at all.
+ */
+export function caretOffsetAtPoint(el, clientX, clientY) {
+    const probe = clampPointIntoBox(el.getBoundingClientRect(), clientX, clientY);
+    return offsetFromViewportPoint(el, probe.x, probe.y);
+}
+/**
+ * The EXACT twin: null for a point outside `el`, which a hit test must decline rather than
+ * round into the nearest offset.
+ */
+export function offsetFromViewportPoint(blockEl, clientX, clientY) {
+    const doc = blockEl.ownerDocument;
+    // caretRangeFromPoint is Chromium/WebKit (all Tauri webviews);
+    // caretPositionFromPoint is the Firefox-style fallback.
+    const ambient = ambientLengthOf(blockEl);
+    const rangeFromPoint = doc.caretRangeFromPoint?.(clientX, clientY);
+    if (rangeFromPoint && blockEl.contains(rangeFromPoint.startContainer)) {
+        const content = domTextOffsetAtNode(blockEl, rangeFromPoint.startContainer, rangeFromPoint.startOffset);
+        return toClampedRawOffset(content, ambient);
+    }
+    const posFromPoint = doc.caretPositionFromPoint?.(clientX, clientY);
+    if (posFromPoint && blockEl.contains(posFromPoint.offsetNode)) {
+        const content = domTextOffsetAtNode(blockEl, posFromPoint.offsetNode, posFromPoint.offset);
+        return toClampedRawOffset(content, ambient);
+    }
+    return null;
+}
+/** A point one pixel inside `rect`, so the topmost element there is the box's own content. */
+export function clampPointIntoBox(rect, x, y) {
+    return {
+        x: clamp(x, rect.left + 1, rect.right - 1),
+        y: clamp(y, rect.top + 1, rect.bottom - 1)
+    };
+}
+function clamp(value, low, high) {
+    return Math.min(Math.max(value, low), high);
+}

package/dist/cursor/reveal-anchor.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Reveal-target anchor. While a reveal is in flight the top-level windowing scope's
+ * `correctAnchor` re-asserts the target's screen position at its requested `block`
+ * placement instead of anchoring the top-of-viewport block, so image-decode churn
+ * above it can't shrink the document and clamp the scroll off it. One slot with
+ * per-call ownership; a plain closed-over value, never reactive `$state`.
+ */
+export type RevealBlock = 'nearest' | 'center';
+export interface RevealTarget {
+    /** The full path the reveal was asked for, not a top-level narrowing. */
+    path: number[];
+    block: RevealBlock;
+}
+/** One `scrollTo`'s hold on the slot. */
+export interface RevealClaim {
+    /** Drop the pin, iff this claim still holds it — a superseded claimant's release is a no-op. */
+    release(): void;
+    /** True once a LATER claim was minted — the only signal that another reveal owns the
+     *  viewport. An empty slot (a user or self release) is not one, and is no reason for a
+     *  reveal in flight to abandon what it was asked to do. */
+    isSuperseded(): boolean;
+}
+export interface RevealAnchorState {
+    get(): RevealTarget | null;
+    /** Take the slot, superseding whoever held it. */
+    claim(path: readonly number[], block?: RevealBlock): RevealClaim;
+    /** Drop the pin whoever holds it — the user-intent release. */
+    releaseAll(): void;
+}
+export declare function createRevealAnchorState(): RevealAnchorState;

package/dist/cursor/reveal-anchor.js

@@ -0,0 +1,31 @@
+export function createRevealAnchorState() {
+    let target = null;
+    // A new claim supersedes the last MINT, not the current holder: supersession is a fact
+    // about reveals, and reading the holder would let `claim → release → claim` leave the
+    // first reveal believing it still owns the viewport (two settle loops, one scrollTop).
+    let owner = null;
+    let lastMinted = null;
+    function drop() {
+        owner = null;
+        target = null;
+    }
+    return {
+        get: () => target,
+        claim(path, block = 'nearest') {
+            const token = { superseded: false };
+            if (lastMinted)
+                lastMinted.superseded = true;
+            lastMinted = token;
+            owner = token;
+            target = { path: [...path], block };
+            return {
+                release: () => {
+                    if (owner === token)
+                        drop();
+                },
+                isSuperseded: () => token.superseded
+            };
+        },
+        releaseAll: drop
+    };
+}

package/dist/cursor/reveal-source.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Rendered↔source reveal: the caret kernel shared by the inline-island and
+ * render-primary-block swaps (both injected, along with the revealed flag). Placement runs
+ * only through `cursor/widget-offset.ts`, offset translation's one home, converting
+ * block-source offsets to walk space by `+ getAmbientLength()` at the single `placeCaret`
+ * seam. Precondition `source.length === sourceEnd - sourceStart`, asserted at entry (G1.26).
+ */
+export interface SourceRevealDeps {
+    /** The block's contenteditable host — where the offset walk runs. Null while a
+     *  reactive consumer has the source unmounted (the block case, while rendered). */
+    get container(): HTMLElement | null;
+    /** Source's raw byte range [start, end) in the block source. */
+    get sourceStart(): number;
+    get sourceEnd(): number;
+    /** The source's raw bytes; `length` MUST equal `sourceEnd - sourceStart`. */
+    get source(): string;
+    /** Rendered marker prefix length the DOM walk counts but block source excludes. */
+    getAmbientLength(): number;
+    /** Whether the editable source is currently shown. Owned by the consumer
+     *  (inline: a captured text node; block: a reactive flag). */
+    isRevealed(): boolean;
+    /** Swap the rendered view for editable source. May decline (leave `isRevealed`
+     *  false) — e.g. the inline widget island isn't in the DOM. */
+    showSource(): void;
+    /** Swap the editable source back for the rendered view (inverse of showSource). */
+    showRendered(): void;
+}
+export interface SourceReveal {
+    isRevealed(): boolean;
+    /** Swap to editable source; caret at `sourceStart + atSourceOffset` (default edge). */
+    reveal(atSourceOffset?: number): Promise<void>;
+    /** Swap back to the rendered view; caret at the trailing edge (`sourceEnd`). */
+    commit(): Promise<void>;
+}
+export declare function createSourceReveal(deps: SourceRevealDeps): SourceReveal;

package/dist/cursor/reveal-source.js

@@ -0,0 +1,51 @@
+/**
+ * Rendered↔source reveal: the caret kernel shared by the inline-island and
+ * render-primary-block swaps (both injected, along with the revealed flag). Placement runs
+ * only through `cursor/widget-offset.ts`, offset translation's one home, converting
+ * block-source offsets to walk space by `+ getAmbientLength()` at the single `placeCaret`
+ * seam. Precondition `source.length === sourceEnd - sourceStart`, asserted at entry (G1.26).
+ */
+import { tick } from 'svelte';
+import { asRawOffset, toDomTextOffset } from './coordinate-spaces';
+import { restoreCaretAtWalkOffset } from './focused-caret';
+import { assertInvariant } from '../assert';
+import { checkRevealSourceLength } from '../invariants/inline-transitions';
+export function createSourceReveal(deps) {
+    /** Places the caret at a BLOCK-source offset, converting to ambient-included walk space. */
+    function placeCaret(container, blockSourceOffset) {
+        const walkOffset = toDomTextOffset(asRawOffset(blockSourceOffset), deps.getAmbientLength());
+        restoreCaretAtWalkOffset(container, walkOffset);
+    }
+    async function reveal(atSourceOffset = 0) {
+        assertInvariant('reveal-transition', () => checkRevealSourceLength(deps.source.length, deps.sourceStart, deps.sourceEnd));
+        if (!deps.isRevealed())
+            deps.showSource();
+        if (!deps.isRevealed())
+            return; // swap declined (island not in the DOM)
+        await tick();
+        const settled = deps.container;
+        if (!settled)
+            return;
+        // Focus BEFORE the caret write: a caret placed in an unfocused editable receives no
+        // typing, and focusing after would reset the selection to the element start.
+        if (document.activeElement !== settled)
+            settled.focus();
+        const clamped = Math.max(0, Math.min(atSourceOffset, deps.source.length));
+        placeCaret(settled, deps.sourceStart + clamped);
+    }
+    async function commit() {
+        if (!deps.isRevealed())
+            return;
+        deps.showRendered();
+        await tick();
+        const settled = deps.container;
+        if (!settled)
+            return;
+        placeCaret(settled, deps.sourceEnd);
+    }
+    return {
+        isRevealed: () => deps.isRevealed(),
+        reveal,
+        commit
+    };
+}

package/dist/cursor/scroll-ancestors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * "What scrolls" and "what clips" are two walks, never one: SCROLLING asks for
+ * `auto`/`scroll` and stops at the first answer, CLIPPING asks for anything that bounds
+ * the visible region and collects the whole chain, since visibility is their intersection.
+ * An `overflow: hidden` auto-height card matches a clipping predicate while doing neither.
+ * `selection/drag-pointer.ts` keeps its own inner walk, so a change here is not one to it.
+ */
+export declare function nearestScrollContainer(el: HTMLElement, stopAt: HTMLElement): HTMLElement | null;
+/** What a drag can autoscroll: an element, or the page's own viewport. */
+export type UserScrollport = HTMLElement | Window;
+/**
+ * What a drag autoscrolls to bring more of `el` into reach: the nearest user-scrollable
+ * ancestor, or the window when the page's own viewport is the scrollport. Total on
+ * purpose — a null for the page-scrolled case reads as "no autoscroll targets", and
+ * `document.scrollingElement` is no substitute (its rect is the document box).
+ */
+export declare function userScrollportFor(el: HTMLElement): UserScrollport;
+/**
+ * Every ancestor that bounds what can be seen of `el`, outermost-last. The whole chain,
+ * not the nearest: only the intersection answers "is this visible", and the innermost
+ * match alone can be a rounded card that bounds nothing. Callers intersect the window
+ * viewport with these; an empty result means the window alone bounds it.
+ */
+export declare function clippingAncestors(el: HTMLElement): HTMLElement[];
+/** First scrollable descendant of `el` in document order. A block-host wrapper sits
+ *  OUTSIDE a block's internal scroll container, so finding what scrolls beneath the host
+ *  means looking inward, not up. */
+export declare function firstScrollableDescendant(el: HTMLElement): HTMLElement | null;