@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/selection/selection-drop.js

@@ -0,0 +1,317 @@
+/**
+ * Dragging a selection and dropping it, as one undo entry over two raw writes (the cut, then
+ * the insert). The browser's own drag is two separate edits, which undo would take in two steps.
+ */
+import { emitClipboardError } from '../editor-events';
+import { rawOffsetAt, rawRangeToDomRange } from '../cursor/widget-offset';
+import { documentLineEnding, trailingLineEnding, trimTrailingLineEnding } from '../core/lines';
+import { blockContentElAt } from '../components/block-el-lookup';
+import { blockNodeAt, emptyParagraph, normalizeOwnRaw, writeOwnRaw } from '../tree-operations/node-primitives';
+import { cloneNode } from '../tree-operations/clone';
+import { replaceRangeInLeaf } from '../tree-operations/leaf-range';
+import { rebuildAncestryRaw } from '../schema/container-raw';
+import { applyPasteTransforms } from '../tree-operations/paste/paste-transforms';
+import { parseReplacement } from '../tree-operations/paste/replacement-parse';
+import { slotReaderAt } from '../tree-operations/list/task-paragraph';
+import { blockNearPoint } from './nearest-block';
+import { findSurfaceForElement } from './path-lookup';
+import { charOffsetOf } from './primitives';
+import { storedAsAt } from '../tree-operations/stored-as';
+import { docPathFrom } from '../cursor/coordinate-spaces';
+/** A drag of the editor's selection in a shape the drop can't move (leaving its element, empty,
+ *  holding a line break); the drop cancels it rather than handing it back to the browser. */
+const DECLINED = 'declined';
+// ── Public entry ───────────────────────────────────────────────────────────
+export function installSelectionDrop(deps) {
+    let source = null;
+    // Where the painted caret stands. A drag fires `dragover` over and over at one position,
+    // and only a move to a different drop point has a new caret to draw.
+    let caretAt = null;
+    function hideCaret() {
+        if (!caretAt)
+            return;
+        caretAt = null;
+        deps.setDropCaret(null);
+    }
+    /** The caret saying where a release would land: cancelling the browser's drop takes its own
+     *  caret away, so the editor's stands where the drop would land and declines where it does. */
+    function drawCaretAt(clientX, clientY, copy) {
+        const from = source;
+        if (!from || from === DECLINED || deps.isReadOnly())
+            return hideCaret();
+        const target = dropTarget(deps, clientX, clientY);
+        if (!target)
+            return hideCaret();
+        // The same refusal `dropOffsetAfterCut` makes once the cut has shrunk the block, tested
+        // here before the cut: a move has nowhere to put bytes inside the range it took them from.
+        const inside = pathsEqual(target.path, from.path) && insideRange(target.offset, from.start, from.end);
+        if (inside && !copy) {
+            return hideCaret();
+        }
+        if (caretAt && caretAt.offset === target.offset && pathsEqual(caretAt.path, target.path)) {
+            return;
+        }
+        const rect = dropCaretRect(deps.editorRoot, target.path, target.offset);
+        if (!rect)
+            return hideCaret();
+        caretAt = target;
+        deps.setDropCaret(rect);
+    }
+    const onDragStart = (e) => {
+        source = readSelectionSource(deps, e.target);
+    };
+    const onDragEnd = () => {
+        source = null;
+        hideCaret();
+    };
+    // The editor is the drop target for every drag recognised here, declined ones included: the
+    // drop handler below must run to cancel the browser's pair of native edits.
+    const onDragOver = (e) => {
+        if (!source)
+            return;
+        e.preventDefault();
+        drawCaretAt(e.clientX, e.clientY, isCopyDrag(e));
+    };
+    // `dragleave` also fires for every child the pointer crosses, so the caret goes only once
+    // the point is outside the editor's own box.
+    const onDragLeave = (e) => {
+        if (source && !isInside(deps.editorRoot, e.clientX, e.clientY))
+            hideCaret();
+    };
+    const onDrop = (e) => {
+        const from = source;
+        source = null;
+        hideCaret();
+        if (!from)
+            return;
+        // Before every decline below, not after: the browser's two edits land separately and its
+        // undo is not the editor's, so a declined shape changes nothing rather than half of it.
+        e.preventDefault();
+        if (from === DECLINED || deps.isReadOnly())
+            return;
+        const target = dropTarget(deps, e.clientX, e.clientY);
+        if (!target)
+            return;
+        void runDrop(deps, from, target, isCopyDrag(e)).catch((error) => {
+            // A throw between the two writes leaves half the move applied; the host hears about it on
+            // the same channel paste errors use.
+            emitClipboardError(deps.events, { error, path: from.path });
+        });
+    };
+    deps.editorRoot.addEventListener('dragstart', onDragStart);
+    deps.editorRoot.addEventListener('dragend', onDragEnd);
+    deps.editorRoot.addEventListener('dragover', onDragOver);
+    deps.editorRoot.addEventListener('dragleave', onDragLeave);
+    deps.editorRoot.addEventListener('drop', onDrop);
+    return () => {
+        // A reinstall mid-drag hands the new listeners no caret to clear, so it goes here.
+        hideCaret();
+        deps.editorRoot.removeEventListener('dragstart', onDragStart);
+        deps.editorRoot.removeEventListener('dragend', onDragEnd);
+        deps.editorRoot.removeEventListener('dragover', onDragOver);
+        deps.editorRoot.removeEventListener('dragleave', onDragLeave);
+        deps.editorRoot.removeEventListener('drop', onDrop);
+    };
+}
+/** Ctrl, or Alt (Option, macOS's copy key for a drag): the release copies instead of moving. */
+function isCopyDrag(e) {
+    return e.ctrlKey || e.altKey;
+}
+/** Where `target` ends up after a splice of `delta` blocks at `at` inside `parent`: what the
+ *  drop's second write addresses once the first write's reparse changed the block count. */
+export function shiftPathAfterSplice(target, parent, at, delta) {
+    if (delta === 0 || target.length <= parent.length)
+        return target;
+    for (let i = 0; i < parent.length; i++)
+        if (target[i] !== parent[i])
+            return target;
+    if (target[parent.length] <= at)
+        return target;
+    const shifted = target.slice();
+    shifted[parent.length] += delta;
+    return shifted;
+}
+/** Where a drop at `offset` lands once `[start, end)` has left the same block, which shrank by
+ *  `shrunkBy` bytes after the join cleanup. Null inside the range. */
+export function dropOffsetAfterCut(offset, start, end, shrunkBy) {
+    if (insideRange(offset, start, end))
+        return null;
+    return offset <= start ? offset : Math.max(0, offset - shrunkBy);
+}
+// ── Reading the gesture ────────────────────────────────────────────────────
+/** The native range the drag carries, in raw offsets: null leaves the drag to the browser, and
+ *  {@link DECLINED} is the editor's selection in a shape the drop cancels. */
+function readSelectionSource(deps, dragged) {
+    const sel = window.getSelection();
+    if (!sel || sel.isCollapsed || sel.rangeCount === 0)
+        return null;
+    const range = sel.getRangeAt(0);
+    // An element that is draggable on its own (a rendered link, an image) is not this gesture,
+    // even with a range painted elsewhere: a selection drag starts on a node the range covers.
+    if (!(dragged instanceof Node) || !range.intersectsNode(dragged))
+        return null;
+    const surface = surfaceOf(range.startContainer);
+    if (!surface || !deps.editorRoot.contains(surface))
+        return null;
+    // From here the drag is the editor's selection, so every remaining shape is declined.
+    if (!surface.contains(range.endContainer))
+        return DECLINED;
+    const found = findSurfaceForElement(surface);
+    if (!found)
+        return DECLINED;
+    const start = rawOffsetAt(surface, range.startContainer, range.startOffset);
+    const end = rawOffsetAt(surface, range.endContainer, range.endOffset);
+    if (start >= end)
+        return DECLINED;
+    const text = movedText(deps, { ...found, start, end });
+    return text === null ? DECLINED : { ...found, start, end, text };
+}
+/** The block and offset a drop point addresses, as a single-click caret would land. Null where
+ *  the point names no character position (a whole-block unit, a table cell). */
+function dropTarget(deps, clientX, clientY) {
+    const near = blockNearPoint(deps.editorRoot, clientX, clientY);
+    const point = near?.endpointHere();
+    if (!point || !('offset' in point) || point.cellCoordinate)
+        return null;
+    return blockNodeAt(deps.getDoc(), point.path) ? { path: point.path, offset: point.offset } : null;
+}
+/** Viewport rect of the caret at `offset` in the block at `path`. A block whose offset names no
+ *  text position falls back to its own box, and an unmounted one to null. */
+function dropCaretRect(root, path, offset) {
+    const el = blockContentElAt(root, path);
+    if (!el)
+        return null;
+    const at = charOffsetOf({ path, offset }, 'selection-drop:caret');
+    const rect = rawRangeToDomRange(el, at, at)?.getBoundingClientRect();
+    if (rect && rect.height > 0)
+        return { left: rect.left, top: rect.top, height: rect.height };
+    const box = el.getBoundingClientRect();
+    return box.height > 0 ? { left: box.left, top: box.top, height: box.height } : null;
+}
+function isInside(el, clientX, clientY) {
+    const box = el.getBoundingClientRect();
+    return clientX >= box.left && clientX <= box.right && clientY >= box.top && clientY <= box.bottom;
+}
+/** The source element's bytes for the range, after the paste transforms. Null for text this
+ *  module does not handle: a line break needs the structural paste path. */
+function movedText(deps, from) {
+    const node = blockNodeAt(deps.getDoc(), from.path);
+    if (!node)
+        return null;
+    const raw = trimTrailingLineEnding(node.raw).slice(from.start, from.end);
+    const text = applyPasteTransforms(raw, deps.activePlugins);
+    return text && !/[\r\n]/.test(text) ? text : null;
+}
+// ── The commit ─────────────────────────────────────────────────────────────
+export function runDrop(deps, from, to, copy) {
+    // One entry for the cut and the insert, and none when neither lands.
+    return deps.controller.undoStep({ path: docPathFrom(from.path), offset: from.start }, () => moveOrCopy(deps, from, to, copy));
+}
+async function moveOrCopy(deps, from, to, copy) {
+    const text = from.text;
+    if (copy) {
+        await writeBlockRaw(deps, to.path, insert(to.offset, text), to.offset + text.length);
+        return;
+    }
+    const cut = cutFrom(deps, from);
+    if (!cut)
+        return;
+    if (pathsEqual(cut.path, to.path)) {
+        const offset = dropOffsetAfterCut(to.offset, from.start, from.end, cut.shrunkBy);
+        if (offset === null)
+            return;
+        const merged = spliceAt(cut.raw, offset, text);
+        await writeBlockRaw(deps, cut.path, () => merged, offset + text.length);
+        return;
+    }
+    // A table's `focus` takes a cell, never a character offset, so the temporary caret the second
+    // write moves away from is its first cell (G1.29).
+    const sourceCaret = from.inCell ? 0 : from.start;
+    const spliced = await writeBlockRaw(deps, cut.path, () => cut.raw, sourceCaret);
+    // An insert after a cut that never landed would turn the move into a copy.
+    if (spliced === null)
+        return;
+    const at = cut.path[cut.path.length - 1];
+    const target = shiftPathAfterSplice(to.path, cut.path.slice(0, -1), at, spliced);
+    await writeBlockRaw(deps, target, insert(to.offset, text), to.offset + text.length);
+}
+function insert(offset, text) {
+    return (raw) => spliceAt(raw, offset, text);
+}
+/** The source element's display bytes with the dragged range gone, cut as any in-leaf edit is so
+ *  a live-mode join cleans up after itself. */
+function cutFrom(deps, from) {
+    const node = blockNodeAt(deps.getDoc(), from.path);
+    if (!node)
+        return null;
+    if (from.inCell)
+        return cutFromCell(deps, from, node);
+    const before = trimTrailingLineEnding(node.raw);
+    const store = storedAsAt(deps.getDoc(), from.path, deps.reading);
+    const edit = replaceRangeInLeaf(node, { start: from.start, end: from.end }, '', store);
+    const raw = trimTrailingLineEnding(edit.raw);
+    return { path: from.path, raw, shrunkBy: before.length - raw.length };
+}
+/** A cell's bytes are joined into its row, so the table is the block the cut rewrites: the cell's
+ *  own cut on a copy, then the kind's escaping and the ancestor rebuild around it. */
+function cutFromCell(deps, from, cell) {
+    const tablePath = from.path.slice(0, -2);
+    // The cell path is resolved from a DOM selector contract, so the kind is read, not assumed.
+    const table = blockNodeAt(deps.getDoc(), tablePath);
+    if (!table || table.kind !== 'table')
+        return null;
+    const store = storedAsAt(deps.getDoc(), from.path, deps.reading);
+    const cut = replaceRangeInLeaf(cell, { start: from.start, end: from.end }, '', store);
+    const rebuilt = cloneNode(table);
+    const inner = from.path.slice(-2);
+    const [rowIdx, colIdx] = inner;
+    const written = rebuilt.children?.[rowIdx]?.children?.[colIdx];
+    if (!written)
+        return null;
+    writeOwnRaw(written, trimTrailingLineEnding(cut.raw), documentLineEnding(deps.getDoc()), deps.reading.grammar);
+    rebuildAncestryRaw(rebuilt, inner, deps.reading.grammar);
+    const raw = trimTrailingLineEnding(rebuilt.raw);
+    return { path: tablePath, raw, shrunkBy: trimTrailingLineEnding(table.raw).length - raw.length };
+}
+/** Replaces the block at `path` with the reparse of `rewrite`'s bytes. Returns the change in block
+ *  count at that position, so a second write's path stays right, or null when nothing landed. */
+async function writeBlockRaw(deps, path, rewrite, caret) {
+    const doc = deps.getDoc();
+    const node = blockNodeAt(doc, path);
+    if (!node)
+        return null;
+    // The bytes are built outside the block's own element, so the kind's write rule runs here.
+    const lineEnding = documentLineEnding(doc);
+    const written = normalizeOwnRaw(node, rewrite(trimTrailingLineEnding(node.raw)), lineEnding);
+    // A block emptied by the cut keeps its position as a blank paragraph: no splice, so the
+    // second write's path is still the one resolved at the drop.
+    const read = slotReaderAt(doc, path, deps.reading.grammar);
+    const parsed = parseReplacement(node, written, lineEnding, read, () => [
+        emptyParagraph(node.leadingTrivia ?? '', trailingLineEnding(node.raw, lineEnding))
+    ]);
+    if (!parsed)
+        return null;
+    const landed = await deps.coordinator.replaceBlock(path, parsed.replacement, { replacementIndex: parsed.replacement.length - 1, offset: caret }, 
+    // The drop's undo step records the selection, so this offset is never read.
+    { source: 'selection-drop', snapshotOffset: 0 });
+    // The count that landed, not the parse's: a container's body rule can rewrite the list.
+    return landed === null ? null : landed - 1;
+}
+// ── Small helpers ──────────────────────────────────────────────────────────
+function spliceAt(raw, offset, text) {
+    const at = Math.max(0, Math.min(offset, raw.length));
+    return raw.slice(0, at) + text + raw.slice(at);
+}
+/** Strictly between `start` and `end`: a position the dragged range itself covers. */
+function insideRange(offset, start, end) {
+    return offset > start && offset < end;
+}
+function pathsEqual(a, b) {
+    return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+function surfaceOf(node) {
+    let el = node instanceof HTMLElement ? node : node.parentElement;
+    while (el && el.contentEditable !== 'true')
+        el = el.parentElement;
+    return el;
+}

package/dist/selection/selection-restore.d.ts

@@ -1,46 +1,33 @@
 /**
- * The one road from a stored selection back onto the live editor: resolve against the current
- * tree, reveal what the caret will be parked at, then land it. Both entry paths (undo/redo
- * swap, the consumer's `setSelection`) funnel through here, so the resolve/clamp/reveal rules
- * can't be carried by only one. A gap caret takes {@link restoreGapCaret}, the same road minus
- * the endpoint pair.
+ * The checks a stored selection passes before it goes back onto the live editor: each endpoint
+ * resolved against the current tree and clamped into its block. `caret-landing.ts :: restore` puts
+ * every stored selection back, a gap caret through {@link restoreGapCaret}.
  */
 import type { DocumentView } from '../core/node-views';
-import type { BlockElLookup } from '../editor-keys';
-import type { EditorSelection, SelectionPoint } from './primitives';
+import type { BlockComponent } from '../block-component';
+import { type SelectionPoint } from './primitives';
 import { type GapCaretPosition } from './gap-caret';
 import type { SelectionState } from './selection-state.svelte';
+import type { CaretMemory } from '../cursor/caret-memory';
 /**
  * `unresolvable` is decided before anything happens and is the only outcome that leaves the
- * editor untouched. `unplaced` is everything short of both halves landing; the reveal and, on
- * the custom route, the cross-block state write have already run.
+ * editor untouched. `unplaced` is everything short of both halves landing; the mount and, on
+ * the overlay route, the cross-block state write have already run.
  */
 export type SelectionRestoreOutcome = 'applied' | 'unresolvable' | 'unplaced';
-export interface SelectionRestoreDeps {
+export interface GapCaretRestoreDeps {
     getDoc(): DocumentView;
     selectionState: SelectionState;
-    getBlockElByPath: BlockElLookup;
-    /** Make the park target ready and report whether it is. Injected because WHICH path gets
-     *  revealed is this module's rule, how strongly is the caller's. */
-    revealTarget(path: number[]): Promise<boolean>;
+    /** Mounts the block at `path`: the caret landing's `mount`. */
+    mount(path: number[]): Promise<BlockComponent | null>;
+    /** Brings the mounted block into view as the restore's reveal policy says. */
+    reveal(path: number[]): Promise<void>;
+    /** Cleared on each restore, since a placed caret did not arrive by a key. */
+    caretMemory: Pick<CaretMemory, 'forget'>;
 }
-/**
- * Restore a snapshot. Never throws; an endpoint whose path no longer addresses a block is
- * declined before the reveal, so a dead snapshot cannot move the viewport or disturb a live
- * selection. What a decline does about the on-screen selection is the caller's policy.
- */
-export declare function restoreSelection(selection: EditorSelection, deps: SelectionRestoreDeps): Promise<SelectionRestoreOutcome>;
-/**
- * Restore a gap caret. The scope check is `gapEligibleAt`'s, not a full eligibility gate:
- * the tree being restored is the one the gap was minted against, so `gapEdges` cannot have
- * changed under it, but the PATH can now name something no BlockList renders.
- */
-export declare function restoreGapCaret(pos: GapCaretPosition, deps: SelectionRestoreDeps): Promise<SelectionRestoreOutcome>;
-/**
- * Clamp an endpoint into its block's addressable range, or null when its path no longer
- * resolves to a block (the document root included). The NODE KIND picks the coordinate space,
- * not the `cellCoordinate` flag: an intra-table endpoint is unflagged (see
- * {@link SelectionPoint}) yet still carries a cell index. The char-space bound is `raw`, which
- * on a marker-bearing kind runs past the content end; the DOM walk lands such an offset there.
- */
+/** Restores a gap caret with only the child-list check: the tree is the one the gap was made
+ *  against, so its `gapEdges` hold, but the path may name something no BlockList renders. */
+export declare function restoreGapCaret(pos: GapCaretPosition, deps: GapCaretRestoreDeps): Promise<SelectionRestoreOutcome>;
+/** Clamps an endpoint into its block's whole `raw`, markers included, or null when its path names
+ *  no block. An offset on a table path comes back flagged as a cell index, even a plain one. */
 export declare function resolveSelectionPoint(doc: DocumentView, point: SelectionPoint): SelectionPoint | null;

package/dist/selection/selection-restore.js

@@ -1,66 +1,43 @@
 /**
- * The one road from a stored selection back onto the live editor: resolve against the current
- * tree, reveal what the caret will be parked at, then land it. Both entry paths (undo/redo
- * swap, the consumer's `setSelection`) funnel through here, so the resolve/clamp/reveal rules
- * can't be carried by only one. A gap caret takes {@link restoreGapCaret}, the same road minus
- * the endpoint pair.
+ * The checks a stored selection passes before it goes back onto the live editor: each endpoint
+ * resolved against the current tree and clamped into its block. `caret-landing.ts :: restore` puts
+ * every stored selection back, a gap caret through {@link restoreGapCaret}.
  */
 import { isBlockNode, nodeAt } from '../tree-operations/node-primitives';
-import { applySelectionToDom } from './native-bridge';
+import { cellPoint } from './primitives';
 import { placeGapCaret } from './caret-doors';
 import { gapScopeChildren } from './gap-caret';
-import { tableCellCount } from './table-endpoint-snap';
-/**
- * Restore a snapshot. Never throws; an endpoint whose path no longer addresses a block is
- * declined before the reveal, so a dead snapshot cannot move the viewport or disturb a live
- * selection. What a decline does about the on-screen selection is the caller's policy.
- */
-export async function restoreSelection(selection, deps) {
-    const doc = deps.getDoc();
-    const anchor = resolveSelectionPoint(doc, selection.anchor);
-    const focus = resolveSelectionPoint(doc, selection.focus);
-    if (!anchor || !focus)
-        return 'unresolvable';
-    // Reveal exactly what the applier parks the caret at: a cell-coordinate focus parks in its
-    // deep [table, row, col] cell, and table rows window too.
-    const revealed = await deps.revealTarget(deps.selectionState.cellLandingFor(focus).path);
-    const placed = applySelectionToDom({ anchor, focus }, deps.selectionState, deps.getBlockElByPath);
-    return revealed && placed ? 'applied' : 'unplaced';
-}
-/**
- * Restore a gap caret. The scope check is `gapEligibleAt`'s, not a full eligibility gate:
- * the tree being restored is the one the gap was minted against, so `gapEdges` cannot have
- * changed under it, but the PATH can now name something no BlockList renders.
- */
+import { clampCellIndex, countsCells } from '../schema/block-kind-descriptor';
+/** Restores a gap caret with only the child-list check: the tree is the one the gap was made
+ *  against, so its `gapEdges` hold, but the path may name something no BlockList renders. */
 export async function restoreGapCaret(pos, deps) {
     const children = gapScopeChildren(deps.getDoc(), pos.parentPath);
     if (!children)
         return 'unresolvable';
+    deps.caretMemory.forget();
     const index = Math.min(Math.max(pos.index, 0), children.length);
     // The boundary itself mounts nothing; what must be on screen is the block it sits
     // against, so the gap's own BlockList is inside a live window when it renders.
     const neighbour = index < children.length ? index : index - 1;
-    const revealed = await deps.revealTarget([...pos.parentPath, neighbour]);
+    const neighbourPath = [...pos.parentPath, neighbour];
+    const mounted = (await deps.mount(neighbourPath)) !== null;
+    if (mounted)
+        await deps.reveal(neighbourPath);
     placeGapCaret(deps.selectionState, { parentPath: pos.parentPath, index });
-    return revealed ? 'applied' : 'unplaced';
+    return mounted ? 'applied' : 'unplaced';
 }
-/**
- * Clamp an endpoint into its block's addressable range, or null when its path no longer
- * resolves to a block (the document root included). The NODE KIND picks the coordinate space,
- * not the `cellCoordinate` flag: an intra-table endpoint is unflagged (see
- * {@link SelectionPoint}) yet still carries a cell index. The char-space bound is `raw`, which
- * on a marker-bearing kind runs past the content end; the DOM walk lands such an offset there.
- */
+/** Clamps an endpoint into its block's whole `raw`, markers included, or null when its path names
+ *  no block. An offset on a table path comes back flagged as a cell index, even a plain one. */
 export function resolveSelectionPoint(doc, point) {
     const node = nodeAt(doc, point.path);
     if (node === null || !isBlockNode(node))
         return null;
-    // Through the extent helper, not a local product: this ceiling and `cellEndpointDeepPath`'s
-    // bounds check must be the same number, or a clamped index is rejected by that check.
-    const limit = node.kind === 'table' ? tableCellCount(node) - 1 : node.raw.length;
-    const offset = Math.min(Math.max(point.offset, 0), Math.max(limit, 0));
+    const cells = countsCells(node);
+    const offset = cells
+        ? clampCellIndex(node, point.offset)
+        : Math.min(Math.max(point.offset, 0), node.raw.length);
     // Path copied so a restored endpoint never aliases the caller's snapshot.
-    return point.cellCoordinate
-        ? { path: point.path.slice(), offset, cellCoordinate: true }
+    return cells || point.cellCoordinate
+        ? cellPoint(point.path, offset)
         : { path: point.path.slice(), offset };
 }

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

@@ -1,32 +1,37 @@
 /**
- * Reactive state for the editor-owned selection modes: a cross-block `anchor`/`focus` pair,
- * and the collapsed `gapCaret` (`gap-caret.ts`). Both are null in single-block mode, where the
- * native browser selection rules, and the two are mutually exclusive here rather than at any
- * call site. Transitions: `docs/design/editor.md` § Cross-block selection.
+ * Reactive state for the selections the editor owns: a cross-block range, a gap caret
+ * (`gap-caret.ts`), or an inline widget selected whole. At most one is live, since every mutator
+ * writes all three through one private writer; all are null while the browser's own selection
+ * rules. Transitions: `docs/design/editor.md` § Cross-block selection.
  */
 import type { DocumentView } from '../core/node-views';
 import type { GapCaretPosition } from './gap-caret';
-import type { SelectionEndpoint, SelectionPoint } from './primitives';
+import type { SelectedWidgetRange, SelectionEndpoint, SelectionPoint, WidgetTarget } from './primitives';
 export interface SelectionStateOptions {
-    /**
-     * Fires after any mutation, or once at the end of a {@link SelectionState.batch} that
-     * contained one. No payload: subscribers read back via `editor.getSelection()`.
-     */
-    onChange?: () => void;
-    /**
-     * Document accessor. Absent in harnesses that only exercise cross-block semantics;
-     * without it `isCustomRendered` cannot see intra-table rects and mirrors `isCrossBlock`.
-     */
+    /** Fires after any mutation, or once at the end of a {@link SelectionState.batch} that held
+     *  one; `placementOnly` says a caret placement was all the flush held. */
+    onChange?: (change: {
+        placementOnly: boolean;
+    }) => void;
+    /** Document accessor. Absent in harnesses that only exercise cross-block semantics, where no
+     *  point is normalized and a table endpoint is stored as written. */
     getDoc?: () => DocumentView;
+    /** The live span of the widget a selection holds, or null once none starts there. Absent, a
+     *  selected widget has no range and reports the offset it was entered at. */
+    widgetSpan?: (target: WidgetTarget) => {
+        start: number;
+        end: number;
+    } | null;
 }
 export declare function createSelectionState(options?: SelectionStateOptions): SelectionState;
+export type RestoreRoute = 'collapsed' | 'single-block' | 'whole-block' | 'custom';
 export interface SelectionState {
     readonly anchor: SelectionPoint | null;
     readonly focus: SelectionPoint | null;
     readonly isCrossBlock: boolean;
     /**
      * True when the overlay paints instead of the native browser highlight: every
-     * cross-block selection, plus same-path multi-offset selections inside tables.
+     * cross-block selection, plus a rectangle of two or more cells inside one table.
      */
     readonly isCustomRendered: boolean;
     readonly start: SelectionPoint | null;
@@ -34,45 +39,48 @@ export interface SelectionState {
     readonly selectAllCount: number;
     /** The third mode: a collapsed caret in a between-blocks boundary (`gap-caret.ts`). */
     readonly gapCaret: GapCaretPosition | null;
-    /**
-     * One block taken whole as the entire range — a press on a surface-less leaf (an equation)
-     * dragged inside it. The stored pair spans the block's bytes on a shared path, which the
-     * same-path guard would otherwise refuse, so the overlay reads this to paint it as a unit.
-     */
+    /** One block taken whole as the range (a drag inside a leaf with no text, such as an equation),
+     *  which the same-path check would otherwise refuse; the overlay paints it as a unit. */
     readonly wholeUnitPath: number[] | null;
+    /** The inline widget selected whole, or null. Copied out, like `gapCaret`. */
+    readonly widget: WidgetTarget | null;
+    /** The selected widget's span read from the live document, since its own commits move its
+     *  end; null with no widget selected, or once no widget starts at its byte. */
+    widgetRange(): SelectedWidgetRange | null;
+    /** The caret a selected widget stands for: the edge of its span it was entered from. */
+    widgetCaret(): SelectionPoint | null;
     enterCrossBlock(anchor: SelectionEndpoint, focus: SelectionEndpoint): void;
     extendFocus(point: SelectionEndpoint): void;
     collapse(): void;
     clear(): void;
+    /** Drops whatever is live without notifying, for a document swap: it addresses the outgoing
+     *  tree, and the restore that follows announces the new selection. */
+    dropForDocumentSwap(): void;
     setGapCaret(pos: GapCaretPosition): void;
     clearGapCaret(): void;
+    /** Selects a widget whole and announces it. A widget ending by itself announces nothing: the
+     *  caret that replaces it announces itself. */
+    selectWidget(target: WidgetTarget): void;
+    /** Moves a selected widget by `delta` bytes when it sits in `path` at or past `editEnd`: an
+     *  edit to another widget earlier in the block moved its bytes, not its identity. Silent. */
+    followWidgetEdit(path: readonly number[], editEnd: number, delta: number): void;
     incrementSelectAllCount(): void;
     resetSelectAllCount(): void;
-    /**
-     * Fire the channel for a selection this state cannot see. Subscribers read the editor
-     * back through `getSelection()`, which also answers for a NATIVE caret the restore road
-     * lands and for a document a `source` swap replaced under it — neither of which moves a
-     * field the mutators above guard on. Coalesces inside a {@link SelectionState.batch}.
-     */
+    /** Notifies for a change no mutator above sees (a caret the editor placed, a restore, a source
+     *  swap), since subscribers read back through `getSelection()`. Coalesces inside a batch. */
     announceSelection(): void;
     /**
-     * Hold change notification until `mutate` returns, then fire once if anything mutated.
-     * Nests; flushes even when the body throws. An entry path that writes state AND lands a
-     * caret must wrap both: subscribers read the editor back on notify, so a notify between
-     * the two reports a caret the DOM half has not moved yet.
+     * Notifies for a caret placement. The flush says whether a placement was all it held, so a
+     * listener can drop one that put the caret where it already was.
      */
+    announcePlacement(): void;
+    /** Holds the change notification until `mutate` returns, then fires once; nests, and flushes on
+     *  a throw. Wrap a state write and its caret placement so no notify lands between the two. */
     batch(mutate: () => void): void;
-    /**
-     * Classify an anchor/focus pair for DOM restore WITHOUT mutating state, so no phantom
-     * cross-block onChange fires. Same-path prose is 'single-block' (native highlight); a
-     * cross-block or intra-table cell rect is 'custom' (overlay).
-     */
-    restoreRoute(anchor: SelectionPoint, focus: SelectionPoint): 'collapsed' | 'single-block' | 'custom';
-    /**
-     * Where a caret lands for `point`: an endpoint inside a table addresses the table block by
-     * cell INDEX, so its landing is the cell's own deep `[table,row,col]` leaf at offset 0.
-     * Any other point lands as itself. Every reveal and every park goes through here, so no
-     * caller can seat a cell index as a char offset on the table wrapper.
-     */
+    /** Classifies a pair `resolveSelectionPoint` returned, for a DOM restore, touching no state. A
+     *  same-path pair over a block with no character position is that block held whole. */
+    restoreRoute(anchor: SelectionPoint, focus: SelectionPoint): RestoreRoute;
+    /** Where a caret lands for `point`: a cell endpoint in its cell's `[table, row, col]` leaf at
+     *  offset 0, any other point as itself. Every mount and caret placement goes through here. */
     cellLandingFor(point: SelectionPoint): SelectionPoint;
 }