@voithos-labs/aragonite 0.10.1

package/dist/selection/range-delete.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Core range mutation primitive, in place: truncate both endpoints, delete between, re-parse
+ * the merged raw, cascade-clean empty ancestors, rebuild container raws. Caller pre-normalizes
+ * the range. The "start wins" rule: `docs/design/editor.md` § Cross-block selection.
+ */
+import type { GrammarView } from '../schema/block-openers';
+import type { PresentationMode } from '../presentation-mode';
+import type { InlineResolverRef } from '../schema/inline-construct-policy';
+import { type CstNode, type Document } from '../core/nodes';
+import type { SelectionPoint } from './primitives';
+import type { SharingState } from '../tree-operations/sharing';
+/** A whole-row window the table branch spliced out of `table.children`. */
+export interface TableRowSplice {
+    table: CstNode;
+    at: number;
+    count: number;
+}
+export interface RangeDeleteResult {
+    newDoc: Document;
+    collapsedCaret: SelectionPoint;
+    /**
+     * Row splices performed on endpoint tables, so the cross-block commit can descriptor-sync
+     * each table's row BlockListState without re-deriving snap math. Table branch only.
+     */
+    tableRowSplices?: TableRowSplice[];
+}
+/**
+ * Delete [start, end] in place, merge at start's position with its container context preserved,
+ * cascade-clean empty ancestors, rebuild container raws. Copy-path-on-write: every spliced or
+ * written spine is unshared BEFORE target identities are captured, so the identity gate compares
+ * post-unshare references. Caller pre-normalizes and keeps endpoints on focusable blocks.
+ */
+export declare function rangeDelete(doc: Document, start: SelectionPoint, end: SelectionPoint, sharing: SharingState, grammar: GrammarView | undefined, presentationMode: PresentationMode | undefined, linkRef: InlineResolverRef | undefined): RangeDeleteResult;

package/dist/selection/range-delete.js

@@ -0,0 +1,121 @@
+/**
+ * Core range mutation primitive, in place: truncate both endpoints, delete between, re-parse
+ * the merged raw, cascade-clean empty ancestors, rebuild container raws. Caller pre-normalizes
+ * the range. The "start wins" rule: `docs/design/editor.md` § Cross-block selection.
+ */
+import { metadataOf } from '../core/nodes';
+import { walkBetween, charOffsetOf } from './primitives';
+import { comparePaths, lowestCommonAncestor, isPathSubtreeBetween } from './path-math';
+import { firstLeafAtOrAfter } from './path-lookup';
+import { blockNodeAt, cleanJoinedRaw, nodeAt, normalizeBodyWrite, normalizeOwnRaw, settleSeparatorOnBlank, writeOwnRaw } from '../tree-operations/node-ops';
+import { deleteSubtreesIdentityGated, installTruncatedEndpoint, reparseTruncatedEndpoint } from './range-delete-ceremony';
+import { ensureUnsharedNode, ensureUnsharedPath, rebuildUnsharedAncestry, rebuildUnsharedChain } from '../tree-operations/unshare';
+import { involvesTable, tableAwareRangeDelete } from './range-delete-table';
+import { involvesReservedChrome, chromeAwareRangeDelete } from './range-delete-chrome';
+/**
+ * Delete [start, end] in place, merge at start's position with its container context preserved,
+ * cascade-clean empty ancestors, rebuild container raws. Copy-path-on-write: every spliced or
+ * written spine is unshared BEFORE target identities are captured, so the identity gate compares
+ * post-unshare references. Caller pre-normalizes and keeps endpoints on focusable blocks.
+ */
+export function rangeDelete(doc, start, end, sharing, grammar, presentationMode, linkRef) {
+    const startBlock = blockNodeAt(doc, start.path);
+    const endBlock = blockNodeAt(doc, end.path);
+    if (!startBlock || !endBlock) {
+        throw new Error('rangeDelete: start or end path does not resolve to a block node');
+    }
+    // The wall branches join nothing, but a truncation still strands the runs whose partner went
+    // with the cut, so their prose endpoints cross the cleaner's unpaired-run half; only the
+    // chrome child's own raw writes stay byte-literal.
+    if (involvesTable(startBlock, endBlock)) {
+        return tableAwareRangeDelete(doc, start, end, sharing, grammar, presentationMode, linkRef);
+    }
+    if (involvesReservedChrome(doc, start, end)) {
+        return chromeAwareRangeDelete(doc, start, end, sharing, grammar, presentationMode, linkRef);
+    }
+    const sameBlock = comparePaths(start.path, end.path) === 0;
+    const startRaw = startBlock.raw;
+    const endRaw = endBlock.raw;
+    const startOffset = charOffsetOf(start, 'rangeDelete:prose-merge-start');
+    const endOffset = charOffsetOf(end, 'rangeDelete:prose-merge-end');
+    // The end slice answers to the END block's rule before the join: start's rule below speaks
+    // only for start's bytes, so a truncation from the end block's head strands its closer. A
+    // same-block merge is one block's bytes and takes that rule once, whole, on the arm below.
+    const endTail = endRaw.slice(endOffset);
+    // A join can MINT a line neither side held: two lines each carrying a mid-line `</details>`
+    // become one that opens with it. The survivor lands in start's container, so it answers to
+    // that container's body rule, applied here so the kinds derive from the bytes that land.
+    const mergedRaw = normalizeBodyWrite(blockNodeAt(doc, start.path.slice(0, -1))?.kind, startRaw.slice(0, startOffset) + (sameBlock ? endTail : normalizeOwnRaw(endBlock, endTail)));
+    // After both normalizers and ahead of both consumers: in live the runs the truncation left
+    // unpaired, and the pair a join brings back to back, are bytes the reader never saw
+    // (live-mode.md § 4.5).
+    const joined = cleanJoinedRaw({
+        mergedRaw,
+        seam: startOffset,
+        start: { node: startBlock, offset: startOffset },
+        end: { node: endBlock, offset: endOffset },
+        linkRef,
+        ambientPrefix: containerAmbientPrefix(doc, start.path)
+    }, presentationMode);
+    if (sameBlock) {
+        // May be nested in a blockquote/list/listItem whose raw depends on this leaf.
+        const chain = ensureUnsharedPath(doc, start.path, sharing);
+        // start.path resolved above, so the chain reaches the leaf; the fallback still routes
+        // through the unshare seam, never a raw capture.
+        const owned = chain[chain.length - 1] ?? ensureUnsharedNode(startBlock, sharing);
+        // No reparse on this arm, so the survivor's own grammar answers here: a join can mint
+        // a line the kind reads as its terminator (a fence run in a code body).
+        writeOwnRaw(owned, joined.raw, grammar);
+        // Ahead of the rebuild, which reads the body's trivia: a selection covering a block's whole
+        // text leaves it blank, and a blank block is the separating line of the one below it.
+        const parent = nodeAt(doc, start.path.slice(0, -1));
+        if (parent)
+            settleSeparatorOnBlank(parent, start.path[start.path.length - 1], sharing);
+        rebuildUnsharedChain(doc, chain, sharing, null, grammar);
+        return {
+            newDoc: doc,
+            collapsedCaret: { path: start.path.slice(), offset: joined.seam }
+        };
+    }
+    // Start's slot, start's rule: the survivor answers to it BEFORE the reparse re-derives
+    // metadata, and inherits the slot's separator a fragment reparse would mint empty.
+    const replacement = reparseTruncatedEndpoint(startBlock, joined.raw);
+    // walkBetween includes ancestors of `end` whose subtrees extend past it, so filter to
+    // subtrees fully inside (start, end). Cascade-cleanup handles ancestors emptied afterwards.
+    const betweenPaths = walkBetween(doc, start.path, end.path).filter((p) => isPathSubtreeBetween(p, start.path, end.path));
+    const deletionPaths = [...betweenPaths, end.path];
+    const lcaPath = lowestCommonAncestor(start.path, end.path);
+    // Unshare every spliced spine before capturing target identities: a copy made after capture
+    // would fail the identity gate and skip the deletion.
+    ensureUnsharedPath(doc, start.path, sharing);
+    for (const path of deletionPaths) {
+        ensureUnsharedPath(doc, path.slice(0, -1), sharing);
+    }
+    deleteSubtreesIdentityGated(doc, deletionPaths, lcaPath, sharing);
+    installTruncatedEndpoint(doc, start.path, replacement, sharing);
+    rebuildUnsharedAncestry(doc, start.path, sharing, null, grammar);
+    for (const path of deletionPaths) {
+        rebuildUnsharedAncestry(doc, path, sharing, null, grammar);
+    }
+    // The re-parse may change kind, including leaf → CONTAINER (a list marker joined to its item
+    // text). Caret restore walks the block element at its path, and a container path drops focus
+    // on a non-editable wrapper, so descend to the leaf. The offset stays a byte coordinate (the
+    // paste and type-replace splice at it); the restore door's landable clamp owns the caret seat.
+    const leafPath = firstLeafAtOrAfter(doc, start.path);
+    const collapsedCaret = leafPath && leafPath.length > start.path.length
+        ? { path: leafPath, offset: 0 }
+        : { path: start.path.slice(), offset: joined.seam };
+    return { newDoc: doc, collapsedCaret };
+}
+/** The container prefix the survivor renders under, so the join seam can read its candidate back
+ *  through it (live-mode.md § 4.5). An ambient marker rides the container's FIRST child only, the
+ *  way `BlockList` forwards it, and a list item is the one built-in container that paints one. */
+function containerAmbientPrefix(doc, path) {
+    if (path.length < 2 || path[path.length - 1] !== 0)
+        return '';
+    const parent = blockNodeAt(doc, path.slice(0, -1));
+    const item = parent?.kind === 'listItem' ? metadataOf(parent, 'listItem') : null;
+    // A task item's ambient carries its checkbox too, which this derivation does not model: '' skips
+    // the read-back rather than checking it against the wrong prefix.
+    return item && !item.taskItem ? item.marker : '';
+}

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

@@ -0,0 +1,7 @@
+/**
+ * AT announcement text for a cross-block selection. The overlay paints rects but suppresses
+ * native selection, so assistive tech sees nothing without this. Counts top-level blocks
+ * spanned; a selection nested inside one top-level block gets a generic phrase.
+ */
+import type { EditorSelection } from './primitives';
+export declare function createSelectionDescription(selection: EditorSelection): string;

package/dist/selection/selection-description.js

@@ -0,0 +1,18 @@
+/**
+ * AT announcement text for a cross-block selection. The overlay paints rects but suppresses
+ * native selection, so assistive tech sees nothing without this. Counts top-level blocks
+ * spanned; a selection nested inside one top-level block gets a generic phrase.
+ */
+import { normalize } from './primitives';
+import { pathsEqual } from './path-math';
+import { SELECTED_ACROSS_BLOCKS, selectedBlocks } from '../a11y-strings';
+export function createSelectionDescription(selection) {
+    const { start, end } = normalize(selection);
+    if (pathsEqual(start.path, end.path))
+        return ''; // single-block — native
+    // Endpoints inside one top-level block (two items of the same list) span no top-level
+    // blocks, and a count would read "1" and mislead.
+    if (start.path[0] === end.path[0])
+        return SELECTED_ACROSS_BLOCKS;
+    return selectedBlocks(end.path[0] - start.path[0] + 1);
+}

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

@@ -0,0 +1,46 @@
+/**
+ * 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.
+ */
+import type { DocumentView } from '../core/node-views';
+import type { BlockElLookup } from '../editor-keys';
+import type { EditorSelection, SelectionPoint } from './primitives';
+import { type GapCaretPosition } from './gap-caret';
+import type { SelectionState } from './selection-state.svelte';
+/**
+ * `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.
+ */
+export type SelectionRestoreOutcome = 'applied' | 'unresolvable' | 'unplaced';
+export interface SelectionRestoreDeps {
+    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>;
+}
+/**
+ * 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.
+ */
+export declare function resolveSelectionPoint(doc: DocumentView, point: SelectionPoint): SelectionPoint | null;

package/dist/selection/selection-restore.js

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ */
+import { isBlockNode, nodeAt } from '../tree-operations/node-ops';
+import { applySelectionToDom } from './native-bridge';
+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.
+ */
+export async function restoreGapCaret(pos, deps) {
+    const children = gapScopeChildren(deps.getDoc(), pos.parentPath);
+    if (!children)
+        return 'unresolvable';
+    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]);
+    placeGapCaret(deps.selectionState, { parentPath: pos.parentPath, index });
+    return revealed ? '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.
+ */
+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));
+    // Path copied so a restored endpoint never aliases the caller's snapshot.
+    return point.cellCoordinate
+        ? { path: point.path.slice(), offset, cellCoordinate: true }
+        : { path: point.path.slice(), offset };
+}

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

@@ -0,0 +1,72 @@
+/**
+ * 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.
+ */
+import type { DocumentView } from '../core/node-views';
+import type { GapCaretPosition } from './gap-caret';
+import type { SelectionEndpoint, SelectionPoint } 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`.
+     */
+    getDoc?: () => DocumentView;
+}
+export declare function createSelectionState(options?: SelectionStateOptions): SelectionState;
+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.
+     */
+    readonly isCustomRendered: boolean;
+    readonly start: SelectionPoint | null;
+    readonly end: SelectionPoint | null;
+    readonly selectAllCount: number;
+    /** The third mode: a collapsed caret in a between-blocks boundary (`gap-caret.ts`). */
+    readonly gapCaret: GapCaretPosition | null;
+    enterCrossBlock(anchor: SelectionEndpoint, focus: SelectionEndpoint): void;
+    extendFocus(point: SelectionEndpoint): void;
+    collapse(): void;
+    clear(): void;
+    setGapCaret(pos: GapCaretPosition): void;
+    clearGapCaret(): 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}.
+     */
+    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.
+     */
+    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.
+     */
+    cellLandingFor(point: SelectionPoint): SelectionPoint;
+}

package/dist/selection/selection-state.svelte.js

@@ -0,0 +1,247 @@
+/**
+ * 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.
+ */
+import { nodeAt } from '../tree-operations/node-ops';
+import { isWholeBlockEndpoint, normalize } from './primitives';
+import { cellEndpointDeepPath, normalizeTableEndpoint, snapCrossBlockTableEndpoints } from './table-endpoint-snap';
+import { normalizeCharEndpoint } from './char-endpoint-snap';
+import { pathsEqual } from './path-math';
+import { assertInvariant } from '../assert';
+import { checkCrossBlockEndpointCoordinates } from '../invariants/selection-endpoints';
+export function createSelectionState(options) {
+    return new SelectionStateImpl(options);
+}
+// ── Implementation ──────────────────────────────────────────────────────────
+class SelectionStateImpl {
+    #anchor = $state(null);
+    #focus = $state(null);
+    #gapCaret = $state(null);
+    #selectAllCount = $state(0);
+    #onChange;
+    #getDoc;
+    #batchDepth = 0;
+    #notifyPending = false;
+    constructor(options) {
+        this.#onChange = options?.onChange;
+        this.#getDoc = options?.getDoc;
+    }
+    batch(mutate) {
+        this.#batchDepth += 1;
+        try {
+            mutate();
+        }
+        finally {
+            this.#batchDepth -= 1;
+            if (this.#batchDepth === 0 && this.#notifyPending) {
+                this.#notifyPending = false;
+                this.#onChange?.();
+            }
+        }
+    }
+    #notify() {
+        if (this.#batchDepth > 0) {
+            this.#notifyPending = true;
+            return;
+        }
+        this.#onChange?.();
+    }
+    get anchor() {
+        return this.#anchor;
+    }
+    get focus() {
+        return this.#focus;
+    }
+    // Copied out, as `setGapCaret` copies in: a consumer that mutates what it reads back
+    // would otherwise write state without notifying anyone.
+    get gapCaret() {
+        const gap = this.#gapCaret;
+        return gap && { parentPath: gap.parentPath.slice(), index: gap.index };
+    }
+    get isCrossBlock() {
+        return this.#anchor !== null && this.#focus !== null;
+    }
+    get isCustomRendered() {
+        const getDoc = this.#getDoc;
+        if (!getDoc)
+            return this.isCrossBlock;
+        const anchor = this.#anchor;
+        const focus = this.#focus;
+        if (!anchor || !focus)
+            return false;
+        if (!pathsEqual(anchor.path, focus.path))
+            return true;
+        if (anchor.offset === focus.offset)
+            return false;
+        const node = nodeAt(getDoc(), anchor.path);
+        if (!node)
+            return false;
+        return node.kind === 'table';
+    }
+    get start() {
+        return this.#normalizedSnapped()?.start ?? null;
+    }
+    get end() {
+        return this.#normalizedSnapped()?.end ?? null;
+    }
+    // Cross-block table endpoints snap to whole rows so highlight, copy, and delete agree
+    // (table-endpoint-snap.ts). Harnesses without getDoc never carry a table endpoint.
+    #normalizedSnapped() {
+        if (!this.#anchor || !this.#focus)
+            return null;
+        const range = normalize({ anchor: this.#anchor, focus: this.#focus });
+        const getDoc = this.#getDoc;
+        if (!getDoc)
+            return range;
+        return snapCrossBlockTableEndpoints(getDoc(), range.start, range.end);
+    }
+    get selectAllCount() {
+        return this.#selectAllCount;
+    }
+    enterCrossBlock(anchor, focus) {
+        this.#gapCaret = null;
+        const a = this.#normalizePoint(anchor, focus.path);
+        const f = this.#normalizePoint(focus, anchor.path);
+        // A same-path prose pair is a single-block range the browser owns; storing it mints an
+        // INVISIBLE cross-block state. Refuse it here so no entry path can. Intra-table rects
+        // share the table path but flag a cell coordinate, and the same-offset keyboard seed is
+        // kept so its immediate `extendFocus` has an anchor.
+        if (this.#isSamePathProseRange(a, f)) {
+            this.#anchor = null;
+            this.#focus = null;
+        }
+        else {
+            this.#assertEndpointCoordinates(a, f);
+            this.#anchor = a;
+            this.#focus = f;
+        }
+        this.#notify();
+    }
+    extendFocus(point) {
+        if (!this.#anchor) {
+            throw new Error('SelectionState.extendFocus called without an anchor');
+        }
+        this.#gapCaret = null;
+        const f = this.#normalizePoint(point, this.#anchor.path);
+        // A focus back on the anchor's prose leaf contracts to a single-block range. No
+        // `offset !== offset` guard, unlike #isSamePathProseRange: extendFocus never seeds, so
+        // landing exactly on the anchor offset is a collapse that must not be stored either.
+        if (pathsEqual(this.#anchor.path, f.path) &&
+            !this.#anchor.cellCoordinate &&
+            !f.cellCoordinate) {
+            this.#anchor = null;
+            this.#focus = null;
+        }
+        else {
+            this.#assertEndpointCoordinates(this.#anchor, f);
+            this.#focus = f;
+        }
+        this.#notify();
+    }
+    // G1.29 at the storing seam, the belt behind #normalizePoint: both entries carry it because
+    // both store an endpoint pair.
+    #assertEndpointCoordinates(anchor, focus) {
+        const getDoc = this.#getDoc;
+        if (!getDoc)
+            return;
+        assertInvariant('cross-block-endpoint-coordinates', () => checkCrossBlockEndpointCoordinates(getDoc(), anchor, focus));
+    }
+    // Same prose leaf, distinct offsets: the shape that must never enter cross-block state.
+    // Equal-offset pairs are excluded so the keyboard entry seed survives to its extend.
+    #isSamePathProseRange(a, f) {
+        return (pathsEqual(a.path, f.path) && !a.cellCoordinate && !f.cellCoordinate && a.offset !== f.offset);
+    }
+    // The funnel every entry path (keyboard, shift-click, drag, select-all, undo restore) goes
+    // through: a table endpoint can never be stored as a deep cell path with a char offset, and a
+    // char offset can never be stored outside the space its own block addresses (both funnels'
+    // headers). Never normalize at a call site instead. Idempotent; without a doc nothing can be
+    // measured, so points pass raw.
+    #normalizePoint(point, otherPath) {
+        const getDoc = this.#getDoc;
+        if (!getDoc) {
+            return isWholeBlockEndpoint(point) ? { path: point.path.slice(), offset: 0 } : point;
+        }
+        const doc = getDoc();
+        if (isWholeBlockEndpoint(point))
+            return normalizeCharEndpoint(doc, point, otherPath);
+        if (point.cellCoordinate)
+            return point;
+        const snapped = normalizeTableEndpoint(doc, point.path, point.offset);
+        return snapped.cellCoordinate ? snapped : normalizeCharEndpoint(doc, snapped, otherPath);
+    }
+    collapse() {
+        if (!this.#hasCaretClaim())
+            return;
+        this.#anchor = null;
+        this.#focus = null;
+        this.#gapCaret = null;
+        this.#notify();
+    }
+    clear() {
+        if (!this.#hasCaretClaim() && this.#selectAllCount === 0)
+            return;
+        this.#anchor = null;
+        this.#focus = null;
+        this.#gapCaret = null;
+        this.#selectAllCount = 0;
+        this.#notify();
+    }
+    // Every field the two clears zero: a guard reading fewer of them would swallow the
+    // notification for the ones it does not see.
+    #hasCaretClaim() {
+        return this.#anchor !== null || this.#focus !== null || this.#gapCaret !== null;
+    }
+    // The mutual exclusion's other half: a gap and a range are never live together, and the
+    // copy is what keeps a caller's own position object from writing through.
+    setGapCaret(pos) {
+        this.#anchor = null;
+        this.#focus = null;
+        this.#gapCaret = { parentPath: pos.parentPath.slice(), index: pos.index };
+        this.#notify();
+    }
+    clearGapCaret() {
+        if (this.#gapCaret === null)
+            return;
+        this.#gapCaret = null;
+        this.#notify();
+    }
+    incrementSelectAllCount() {
+        this.#selectAllCount += 1;
+        this.#notify();
+    }
+    restoreRoute(anchor, focus) {
+        if (!pathsEqual(anchor.path, focus.path))
+            return 'custom';
+        if (anchor.offset === focus.offset)
+            return 'collapsed';
+        // Same path, distinct offsets: a table cell rect (flagged endpoint, or a table node
+        // under the shared path) paints via the overlay; prose is a native range.
+        if (anchor.cellCoordinate || focus.cellCoordinate)
+            return 'custom';
+        const getDoc = this.#getDoc;
+        if (!getDoc)
+            return 'single-block';
+        const node = nodeAt(getDoc(), anchor.path);
+        return node?.kind === 'table' ? 'custom' : 'single-block';
+    }
+    cellLandingFor(point) {
+        const getDoc = this.#getDoc;
+        if (!getDoc)
+            return point;
+        // Resolution is the door's, on the node kind: a context-established intra-table endpoint
+        // is unflagged and still a cell index, and a non-table path answers null.
+        const deepPath = cellEndpointDeepPath(getDoc(), point);
+        return deepPath ? { path: deepPath, offset: 0 } : point;
+    }
+    resetSelectAllCount() {
+        if (this.#selectAllCount === 0)
+            return;
+        this.#selectAllCount = 0;
+        this.#notify();
+    }
+    announceSelection() {
+        this.#notify();
+    }
+}