@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/search/regex-executor.d.ts

@@ -1,9 +1,8 @@
 /**
- * Bounds regex find. A pathological pattern spends minutes inside ONE `RegExp.exec`, which
- * no main-thread budget can interrupt, so the only bound is a killable thread. The worker
- * ships as source text through a Blob URL, not a bundler worker import, leaving dist
- * packaging and consumer bundlers untouched. Where that is unavailable (SSR, a CSP-restricted
- * embedder, the test runner) it degrades to a sync scan bounded only BETWEEN texts.
+ * Bounds regex find. A pathological pattern can spend minutes inside one `RegExp.exec`, so the
+ * only bound is a worker thread that can be killed. The worker ships as source text through a
+ * Blob URL, leaving dist packaging and consumer bundlers untouched. Where workers are unavailable
+ * (SSR, a strict CSP, the test runner) find falls back to a sync scan bounded between texts.
  */
 import { type RawRange } from './matcher';
 /** Wall-clock ceiling for one scan: long enough for an honest regex over a large document,
@@ -16,7 +15,7 @@ export interface RegexScanRequest {
     /** Correlation token, echoed back untouched, so the caller can drop a stale outcome. */
     readonly epoch: number;
 }
-/** `cancelled` covers supersession and release alike — nothing to report either way. */
+/** `cancelled` covers supersession and release alike: nothing to report either way. */
 export type RegexScanFailure = 'timeout' | 'error' | 'cancelled';
 export type RegexScanOutcome = {
     ok: true;

package/dist/search/regex-executor.js

@@ -1,9 +1,8 @@
 /**
- * Bounds regex find. A pathological pattern spends minutes inside ONE `RegExp.exec`, which
- * no main-thread budget can interrupt, so the only bound is a killable thread. The worker
- * ships as source text through a Blob URL, not a bundler worker import, leaving dist
- * packaging and consumer bundlers untouched. Where that is unavailable (SSR, a CSP-restricted
- * embedder, the test runner) it degrades to a sync scan bounded only BETWEEN texts.
+ * Bounds regex find. A pathological pattern can spend minutes inside one `RegExp.exec`, so the
+ * only bound is a worker thread that can be killed. The worker ships as source text through a
+ * Blob URL, leaving dist packaging and consumer bundlers untouched. Where workers are unavailable
+ * (SSR, a strict CSP, the test runner) find falls back to a sync scan bounded between texts.
  */
 import { execAll } from './matcher';
 /** Wall-clock ceiling for one scan: long enough for an honest regex over a large document,
@@ -105,9 +104,8 @@ export function createRegexExecutor(options = {}) {
                     ? { ok: true, epoch: reply.epoch, ranges: reply.ranges }
                     : { ok: false, epoch: reply.epoch, reason: 'error' });
             };
-            // An uncompilable pattern is caught inside the worker and posted back, so reaching
-            // here means the worker itself is broken (a CSP blocking the blob at load, not at
-            // construction). Latch, or regex search stays dead instead of degrading to sync.
+            // The worker posts an uncompilable pattern back, so an error here means the worker itself
+            // failed to load. Latch, or regex search stays dead instead of falling back to sync.
             const fail = () => {
                 const epoch = pending?.epoch ?? request.epoch;
                 workerUnavailable = true;

package/dist/search/replace.d.ts

@@ -7,9 +7,6 @@ export interface ReplaceRange {
     end: number;
     groups?: string[];
 }
-/**
- * Apply ranges to `text`, substituting right-to-left so earlier offsets stay valid. No
- * per-replacement escape hook: a structural leaf's delimiters escape over the WHOLE
- * post-splice raw, so that is the caller's `toLegalRaw` pass over the result.
- */
+/** Substitutes right-to-left so earlier offsets stay valid. Escaping a structural leaf's
+ *  delimiters is the caller's `toLegalRaw` pass over the result. */
 export declare function applyRangesToText(text: string, ranges: ReplaceRange[], template: string): string;

package/dist/search/replace.js

@@ -14,11 +14,8 @@ export function expandReplacement(template, groups) {
         return groups[Number(token)] ?? '';
     });
 }
-/**
- * Apply ranges to `text`, substituting right-to-left so earlier offsets stay valid. No
- * per-replacement escape hook: a structural leaf's delimiters escape over the WHOLE
- * post-splice raw, so that is the caller's `toLegalRaw` pass over the result.
- */
+/** Substitutes right-to-left so earlier offsets stay valid. Escaping a structural leaf's
+ *  delimiters is the caller's `toLegalRaw` pass over the result. */
 export function applyRangesToText(text, ranges, template) {
     let out = text;
     const ordered = [...ranges].sort((a, b) => b.start - a.start);

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

@@ -7,7 +7,7 @@ export interface SearchOptions {
     wholeWord: boolean;
     regex: boolean;
 }
-/** A match paired with its flat-list position — what the active highlight compares
+/** A match paired with its flat-list position, which the active highlight compares
  *  against `activeIndex`. */
 export interface IndexedMatch {
     match: Match;
@@ -15,8 +15,8 @@ export interface IndexedMatch {
 }
 interface SearchDeps {
     getDoc: () => DocumentView;
-    /** Bumped when the whole document is REPLACED, never on an in-place edit or undo —
-     *  those leave the tree under a position the user still owns. */
+    /** Bumped when the whole document is replaced, never on an in-place edit or undo,
+     *  since those leave the tree under a position the user still owns. */
     getDocumentGeneration: () => number;
     /** Highlights ship as marks under source 'editor:search', registered on open and
      *  disposed on close, so a closed bar costs nothing. */
@@ -26,12 +26,12 @@ interface SearchDeps {
         replaceAll(m: Match[], t: string): Promise<number>;
     };
     reveal: (path: number[]) => Promise<unknown>;
-    /** Test seam; production builds the worker-backed executor internally. */
+    /** Injected by tests; production builds the worker-backed executor internally. */
     regexExecutor?: RegexExecutor;
     onClose: () => void;
 }
 export declare function createSearchState(deps: SearchDeps): SearchState;
-/** Public controller surface — what `editor.getSearch()` exposes. Deliberately minimal:
+/** The public search controller, what `editor.getSearch()` exposes. Deliberately minimal:
  *  adding a member later is non-breaking, removing one is not. */
 export interface SearchState {
     readonly isOpen: boolean;

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

@@ -4,7 +4,7 @@ import { createRegexExecutor } from './regex-executor';
 import { groupByPathKey, pathKey } from '../decorations/buckets';
 const EMPTY_MATCHES = [];
 // Both reuse the invalid-regex readout: a scan with no usable answer is one state to the
-// reader, whatever ended it.
+// user, whatever ended it.
 const REGEX_TOO_SLOW = 'Regex too slow';
 const REGEX_SCAN_FAILED = 'Regex search failed';
 export function createSearchState(deps) {
@@ -17,29 +17,27 @@ export function createSearchState(deps) {
     const matchesByPath = $derived(groupByPathKey(matches, (match, index) => ({ match, index })));
     let activeIndex = $state(0);
     let error = $state(null);
-    // Cleared on the next search ACTION, not in rescan — the engine's post-commit re-run
-    // would otherwise wipe it instantly.
+    // Cleared on the next search action, not in rescan: the decoration registry's re-run
+    // after a commit would otherwise wipe it instantly.
     let replacedCount = $state(null);
-    // A regex scan lands asynchronously, so `matches` can trail the query that asked for
-    // it. `scanEpoch` is the drop token: every rescan and close bumps it, and an outcome
-    // tagged with a spent epoch is discarded.
+    // A regex scan lands asynchronously, so `matches` can trail its query: every rescan and close
+    // bumps `scanEpoch`, and an outcome tagged with an older epoch is dropped.
     let scanning = $state(false);
     let scanEpoch = 0;
     let pendingScan = null;
     const regexExecutor = deps.regexExecutor ?? createRegexExecutor();
     let lastGeneration = deps.getDocumentGeneration();
     let handle = null;
-    // The scan runs for its side effects, so only the CURRENT key may skip it; cleared on
+    // The scan runs for its side effects, so only the current key may skip it; cleared on
     // close() so a reopen at the same key rescans rather than serving the empty set.
     let lastScanKey = null;
-    // Keyed on editEpoch, NEVER doc.children identity: typing mutates children in place, so
+    // Keyed on editEpoch, never doc.children identity: typing mutates children in place, so
     // identity only changes on structural commits and would serve stale matches.
     function provide(doc, ctx) {
         const { caseSensitive, wholeWord, regex } = options;
         const key = `${ctx.editEpoch}\0${+caseSensitive}${+wholeWord}${+regex}\0${query}`;
         if (key !== lastScanKey) {
-            // Scan the document the registry is providing FOR, not whatever the deps getter
-            // resolves to — the plugin guide points decoration authors at this file.
+            // Scan the document the registry is providing for, not whatever the deps getter resolves to.
             rescan(doc);
             lastScanKey = key;
         }
@@ -52,9 +50,8 @@ export function createSearchState(deps) {
         }));
     }
     function rescan(doc = deps.getDoc()) {
-        // A whole-document REPLACEMENT restarts navigation at the first match: the carried
-        // position indexes a document the user never navigated. Edits, undo and option
-        // toggles leave the user where they were, so they fall through to applyMatches' clamp.
+        // A whole-document replacement restarts navigation at the first match. Edits, undo and option
+        // toggles keep the user's position through applyMatches' clamp.
         const generation = deps.getDocumentGeneration();
         const documentReplaced = generation !== lastGeneration;
         lastGeneration = generation;
@@ -111,9 +108,8 @@ export function createSearchState(deps) {
             handle?.invalidate();
         });
     }
-    // Every state change routes through the engine so the published marks follow. invalidate
-    // is synchronous by contract, so setQuery's callers still observe fresh matches on
-    // return; the no-handle fallback keeps the headless setQuery-before-open path scanning.
+    // Every change goes through the decoration registry so the marks follow; invalidate is
+    // synchronous, so setQuery's callers see fresh matches on return, even before open.
     function refresh() {
         if (handle)
             handle.invalidate();

package/dist/selection/autoscroll.d.ts

@@ -1,9 +1,8 @@
 /**
- * Pointer-edge autoscroll RAF loop, shared between cross-block and intra-table drag. The caller
- * supplies the live pointer and the scroll targets to evaluate each frame. A target may be the
- * window (`cursor/scroll-ancestors`), which answers the two halves from different places on
- * purpose: measure the viewport, write `document.scrollingElement`. Using the scrolling element
- * for both puts the document's own multi-thousand-pixel box into the edge math.
+ * Scrolls a container while a drag holds the pointer near its edge, one step per animation
+ * frame. When the target is the window, the edge band is measured against the viewport but the
+ * scroll is written to `document.scrollingElement`: measuring the scrolling element would put
+ * the document's full height into the edge math.
  */
 import type { UserScrollport } from '../cursor/scroll-ancestors';
 export interface AutoScrollDeps {
@@ -13,10 +12,8 @@ export interface AutoScrollDeps {
     } | null;
     getTargets: (clientX: number, clientY: number) => UserScrollport[];
     onScrolled?: () => void;
-    /**
-     * Restrict scrolling to one axis (default both). The column reorder drag pins the pointer in
-     * the table's top band, where vertical evaluation would spin on a horizontal-only scroller.
-     */
+    /** Restricts scrolling to one axis (default both), for a drag that pins the pointer in one
+     *  edge band, where the other axis would scroll a container meant to move only one way. */
     axis?: 'horizontal' | 'vertical' | 'both';
 }
 export interface AutoScrollHandle {

package/dist/selection/block-hit-test.d.ts

@@ -1,37 +1,29 @@
 /**
- * Viewport point to the block under it, for pointer hit-testing: walks ancestors of the topmost
- * element to the nearest `data-block-path` host. A kind with internal coordinate addressing
- * carries the point→internals hooks its descriptor declares, so a caller resolves a
- * cell-coordinate point without knowing the kind. What the hit does NOT carry is what a kind
- * cannot answer: a block with no character surface reports none.
+ * Finds the block under a viewport point for pointer hit-testing. The hit carries the
+ * point-to-cell hooks the block's kind descriptor declares, so a caller can resolve a table
+ * cell without knowing the kind, and it reports no text element for a block that has none.
  */
 import { type CaretTarget } from '../schema/block-kind-descriptor';
-import type { SelectionEndpoint } from './primitives';
+import { type SelectionEndpoint } from './primitives';
 export interface BlockHit {
     path: number[];
-    /**
-     * The surface a character offset may be hit-tested against, or null when the kind renders
-     * none: a coordinate-addressed grid, and a whole-block kind whose rendered body is chrome.
-     * A caller that character-hit-tests the wrapper instead gets a plausible-but-wrong offset
-     * across the whole subtree rather than a decline.
-     */
+    /** The element carrying the block's path; a container's children are block hosts inside it. */
+    host: HTMLElement;
+    /** The editable element a character offset is hit-tested against, or null when the kind has
+     *  none: hit-testing the wrapper instead returns a plausible but wrong offset. */
     charSurface: HTMLElement | null;
-    /**
-     * Point→internal-offset hook for kinds with coordinate addressing (a table's row-major
-     * cellIdx). Pre-bound to the block's wrapper, resolved from the kind descriptor.
-     */
+    /** Maps a point to a row-major cell index for a grid kind such as a table. */
     foreignDragHitTest?: (clientX: number, clientY: number) => number | null;
     /**
-     * The caret landing inside such a kind, as an internal child path plus offset. A
-     * caret-placing gesture reads this where the drag hook declines.
+     * Where a click inside a grid kind puts the caret, as a child path plus offset; read when
+     * the drag hook returns null.
      */
     caretTargetAtPoint?: (clientX: number, clientY: number) => CaretTarget | null;
 }
 export declare function blockAtPoint(editorRoot: HTMLElement, clientX: number, clientY: number): BlockHit | null;
-/**
- * The selection endpoint a pointer over `hit` addresses: a row-major cell index where the kind
- * declares the drag hook, a char offset on a character surface, and otherwise the block as a
- * whole — the selection funnel resolves which of its two ends this side of the range wants.
- * Shared by both drag consumers, so neither can hit-test characters against a block with none.
- */
+/** Whether the hit's editable text belongs to the block itself, not to a child inside it (a
+ *  quote's first line is its first child's). False where editing is off, as in reading mode. */
+export declare function holdsOwnText(hit: BlockHit): boolean;
+/** The selection endpoint a pointer over `hit` addresses. A block with no text yields the whole
+ *  block, so no drag hit-tests characters against it; its end is chosen against the other end. */
 export declare function endpointAtPoint(hit: BlockHit, clientX: number, clientY: number): SelectionEndpoint | null;

package/dist/selection/block-hit-test.js

@@ -1,14 +1,14 @@
 /**
- * Viewport point to the block under it, for pointer hit-testing: walks ancestors of the topmost
- * element to the nearest `data-block-path` host. A kind with internal coordinate addressing
- * carries the point→internals hooks its descriptor declares, so a caller resolves a
- * cell-coordinate point without knowing the kind. What the hit does NOT carry is what a kind
- * cannot answer: a block with no character surface reports none.
+ * Finds the block under a viewport point for pointer hit-testing. The hit carries the
+ * point-to-cell hooks the block's kind descriptor declares, so a caller can resolve a table
+ * cell without knowing the kind, and it reports no text element for a block that has none.
  */
 import { WHOLE_BLOCK_INPUT_ATTR } from '../editor-actions/whole-block-focus-surface';
 import { tryGetBlockKindDescriptor } from '../schema/block-kind-descriptor';
-import { offsetFromViewportPoint } from '../cursor/point-offset';
+import { cellPoint } from './primitives';
+import { caretOffsetAtPoint, offsetFromViewportPoint } from '../cursor/point-offset';
 import { readBlockPath } from './path-lookup';
+import { pathsEqual } from './path-math';
 export function blockAtPoint(editorRoot, clientX, clientY) {
     let el = document.elementFromPoint(clientX, clientY);
     while (el && el !== editorRoot) {
@@ -18,16 +18,15 @@ export function blockAtPoint(editorRoot, clientX, clientY) {
                 return null;
             const wrapper = el;
             const kind = wrapper.getAttribute('data-block-kind');
-            // tryGet tolerates junk DOM strings — unregistered kinds resolve undefined.
+            // `tryGet` tolerates an unregistered kind string read off the DOM.
             const descriptor = kind ? tryGetBlockKindDescriptor(kind) : undefined;
             const dragHitTest = descriptor?.foreignDragHitTest;
             const caretTarget = descriptor?.caretTargetAtPoint;
             return {
                 path,
-                // A cell-addressed kind's first contenteditable is one of its CELLS, so declaring
-                // the drag hook withdraws the block-level surface rather than offering that. The
-                // whole-block editing host is chrome, not characters, so it is excluded too, as is
-                // the selection overlay (`contenteditable="false"`, mounted while a range is live).
+                host: wrapper,
+                // A grid kind's first contenteditable is a cell, not the block; the whole-block
+                // input and the selection overlay hold none of the block's characters either.
                 charSurface: dragHitTest
                     ? null
                     : wrapper.querySelector(`[contenteditable]:not([${WHOLE_BLOCK_INPUT_ATTR}]):not(.selection-overlay)`),
@@ -39,22 +38,30 @@ export function blockAtPoint(editorRoot, clientX, clientY) {
     }
     return null;
 }
-/**
- * The selection endpoint a pointer over `hit` addresses: a row-major cell index where the kind
- * declares the drag hook, a char offset on a character surface, and otherwise the block as a
- * whole — the selection funnel resolves which of its two ends this side of the range wants.
- * Shared by both drag consumers, so neither can hit-test characters against a block with none.
- */
+/** Whether the hit's editable text belongs to the block itself, not to a child inside it (a
+ *  quote's first line is its first child's). False where editing is off, as in reading mode. */
+export function holdsOwnText(hit) {
+    const surface = hit.charSurface;
+    if (!surface?.matches('[contenteditable="true"]'))
+        return false;
+    const owner = readBlockPath(surface.closest('[data-block-path]'));
+    return owner !== null && pathsEqual(owner, hit.path);
+}
+/** The selection endpoint a pointer over `hit` addresses. A block with no text yields the whole
+ *  block, so no drag hit-tests characters against it; its end is chosen against the other end. */
 export function endpointAtPoint(hit, clientX, clientY) {
     if (hit.foreignDragHitTest) {
         const cellIdx = hit.foreignDragHitTest(clientX, clientY);
-        // The flag routes collapse/reveal to the deep cell, matching the keyboard path.
-        return cellIdx === null
-            ? null
-            : { path: hit.path, offset: cellIdx, cellCoordinate: true };
+        // A cell point's `cellCoordinate` routes a collapse and a scroll-into-view to the cell
+        // itself, as the keyboard path does.
+        return cellIdx === null ? null : cellPoint(hit.path, cellIdx);
     }
     if (!hit.charSurface)
         return { path: hit.path, wholeBlock: true };
-    const offset = offsetFromViewportPoint(hit.charSurface, clientX, clientY);
+    // A block's own text answers a point on its frame as a click there does; a container's first
+    // child's text answers only a point on it.
+    const offset = holdsOwnText(hit)
+        ? caretOffsetAtPoint(hit.charSurface, clientX, clientY)
+        : offsetFromViewportPoint(hit.charSurface, clientX, clientY);
     return offset === null ? null : { path: hit.path, offset };
 }

package/dist/selection/caret-doors.d.ts

@@ -1,20 +1,21 @@
 /**
- * The two caret doors a block component exposes. `parkCaret` is the primitive: it seats a caret
- * and touches nothing else, which is what the cross-block dispatcher needs while an extend is
- * still growing a range. `focus` is that primitive plus the claim-ending every other placement
- * owes, since a caret left in a live cross-block range leaves a document the next keystroke
- * type-replaces. The door a caller reaches for by default is the safe one.
+ * Where a caret, a gap caret or a widget selected whole is put down, each ending whatever the
+ * editor had selected before: a caret left inside a live range makes the next keystroke replace
+ * the whole range. A block's `parkCaret` alone ends nothing, which the cross-block dispatcher
+ * needs while a shift-extend is still growing a range.
  */
 import type { GapCaretPosition } from './gap-caret';
+import type { WidgetTarget } from './primitives';
 import type { SelectionState } from './selection-state.svelte';
-/**
- * Mint a component's public `focus` from its park primitive. Batched because `clear()` notifies:
- * an emission between the state write and the DOM landing reports a caret about to move.
- */
+/** Builds a component's public `focus` from its `parkCaret`, batched so no listener hears of
+ *  a caret between the state write and the DOM placement. */
 export declare function placeCaret(selection: SelectionState, parkCaret: (offset: number) => void): (offset: number) => void;
-/**
- * The gap's own door: every arrival path writes gap state through here and nowhere else. The
- * native clear is inside the batch because no native caret may outlive the landing — the gap
- * owns the caret from here until something else claims it.
- */
+/** Puts a browser range down inside one block (a first Mod+A, a block's `setSelection`) the way
+ *  `placeCaret` puts a caret down: whatever the editor had selected ends first. */
+export declare function selectInBlock(selection: SelectionState, select: () => void): void;
+/** The only place gap-caret state is written. The native selection is cleared in the batch
+ *  because no browser caret may outlive the gap caret. */
 export declare function placeGapCaret(selection: SelectionState, pos: GapCaretPosition): void;
+/** The only place a widget is selected whole. The native selection is cleared in the batch,
+ *  because no browser caret may outlive the widget selection taking its place. */
+export declare function selectWidgetWhole(selection: SelectionState, target: WidgetTarget): void;

package/dist/selection/caret-doors.js

@@ -1,26 +1,34 @@
 /**
- * The two caret doors a block component exposes. `parkCaret` is the primitive: it seats a caret
- * and touches nothing else, which is what the cross-block dispatcher needs while an extend is
- * still growing a range. `focus` is that primitive plus the claim-ending every other placement
- * owes, since a caret left in a live cross-block range leaves a document the next keystroke
- * type-replaces. The door a caller reaches for by default is the safe one.
+ * Where a caret, a gap caret or a widget selected whole is put down, each ending whatever the
+ * editor had selected before: a caret left inside a live range makes the next keystroke replace
+ * the whole range. A block's `parkCaret` alone ends nothing, which the cross-block dispatcher
+ * needs while a shift-extend is still growing a range.
  */
+import { assertInvariant } from '../assert';
+import { checkPlacementEndsWidget } from '../invariants/placement-ends-widget';
 import { clearNativeSelection } from './native-bridge';
-/**
- * Mint a component's public `focus` from its park primitive. Batched because `clear()` notifies:
- * an emission between the state write and the DOM landing reports a caret about to move.
- */
+/** Builds a component's public `focus` from its `parkCaret`, batched so no listener hears of
+ *  a caret between the state write and the DOM placement. */
 export function placeCaret(selection, parkCaret) {
-    return (offset) => selection.batch(() => {
+    return (offset) => putDown(selection, () => parkCaret(offset));
+}
+/** Puts a browser range down inside one block (a first Mod+A, a block's `setSelection`) the way
+ *  `placeCaret` puts a caret down: whatever the editor had selected ends first. */
+export function selectInBlock(selection, select) {
+    putDown(selection, select);
+}
+function putDown(selection, place) {
+    selection.batch(() => {
         endLiveCaretClaim(selection);
-        parkCaret(offset);
+        place();
+        assertInvariant('placement-ends-widget', () => checkPlacementEndsWidget(selection.widget));
+        // A plain caret or range changes no field the state checks, so subscribers hear of the
+        // placement only here, and one that lands where the selection already was says nothing.
+        selection.announcePlacement();
     });
 }
-/**
- * The gap's own door: every arrival path writes gap state through here and nowhere else. The
- * native clear is inside the batch because no native caret may outlive the landing — the gap
- * owns the caret from here until something else claims it.
- */
+/** The only place gap-caret state is written. The native selection is cleared in the batch
+ *  because no browser caret may outlive the gap caret. */
 export function placeGapCaret(selection, pos) {
     selection.batch(() => {
         endLiveCaretClaim(selection);
@@ -28,17 +36,20 @@ export function placeGapCaret(selection, pos) {
         clearNativeSelection();
     });
 }
-/**
- * Ends any editor-owned caret claim (cross-block range or gap) before a new caret lands. The
- * range arm takes the gap with it, so the split is on which claim is live rather than on which
- * field to zero. The native clear matters for a whole-block landing, which seats no DOM range
- * of its own.
- */
+/** The only place a widget is selected whole. The native selection is cleared in the batch,
+ *  because no browser caret may outlive the widget selection taking its place. */
+export function selectWidgetWhole(selection, target) {
+    selection.batch(() => {
+        selection.selectWidget(target);
+        clearNativeSelection();
+    });
+}
+/** Ends whatever the editor had selected (a range, a gap caret, a widget) before a new caret
+ *  lands. The native clear covers a whole-block range, which sets no DOM range of its own. */
 function endLiveCaretClaim(selection) {
-    if (selection.isCrossBlock) {
+    const hadRange = selection.isCrossBlock;
+    if (hadRange || selection.gapCaret !== null || selection.widget !== null)
         selection.clear();
+    if (hadRange)
         clearNativeSelection();
-        return;
-    }
-    selection.clearGapCaret();
 }

package/dist/selection/caret-landing.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The one way a caret is put down after an edit or a restore: resolve the position to a leaf, mount
+ * each level on the way, check the tree is still the one the caller aimed at, place, then bring
+ * the block into view. One per editor, built in `Editor.svelte`; nothing else scrolls for a landing.
+ */
+import { type BlockComponent } from '../block-component';
+import type { DocumentView } from '../core/node-views';
+import type { CaretMemory } from '../cursor/caret-memory';
+import type { ScrollOwner } from '../cursor/scroll-owner';
+import type { BlockElLookup } from '../editor-keys';
+import { type ChildList } from '../reactivity/child-list';
+import type { CaretPosition, EditorSelection } from './primitives';
+import { type SelectionRestoreOutcome } from './selection-restore';
+import { type GapCaretSelection } from '../undo/types';
+import type { SelectionState } from './selection-state.svelte';
+/** How far a landing moves the viewport: not at all, or just far enough to show the caret when it
+ *  isn't fully on screen. Holding a block in place is a navigation's alone (`navigate`). */
+export type RevealPolicy = 'mount' | 'into-view';
+export interface LandOptions {
+    /** `'into-view'` when absent. */
+    reveal?: RevealPolicy;
+    /** The tree generation the caller aimed at; read at the call when absent. */
+    stamp?: number;
+}
+/** `'stale'`: an undo, redo or document swap happened while the landing waited, so it placed
+ *  nothing. */
+export type LandingOutcome = 'placed' | 'unresolvable' | 'stale';
+export interface CaretLanding {
+    /** Put the caret at `pos` as an arrival, through the block's own `focus`. */
+    land(pos: CaretPosition, opts?: LandOptions): Promise<LandingOutcome>;
+    /** Land as a navigation: open a collapsed body on the way, and hold the block where it landed
+     *  until the user scrolls, so a late image decode can't move it. */
+    navigate(pos: CaretPosition): Promise<LandingOutcome>;
+    /** Put a stored selection back at the bytes it names, or a gap caret at its boundary. */
+    restore(selection: EditorSelection | GapCaretSelection, opts?: LandOptions): Promise<SelectionRestoreOutcome>;
+    /** Mount `pos` and park a caret there without ending a live range. */
+    park(pos: CaretPosition): Promise<boolean>;
+    /** Mount the block at `path` and hand back its component, for a caller that dispatches to it. */
+    mount(path: readonly number[], opts?: {
+        openCollapsed?: boolean;
+    }): Promise<BlockComponent | null>;
+    /** An arrow move put focus in the block at `path`: the page scrolls the least distance that
+     *  shows the caret's line, or the whole cell in a table. */
+    followArrival(path: readonly number[]): void;
+    /** Bumped by every undo, redo and document swap: a landing that waited across one is stale. */
+    generation(): number;
+    /** Called by the history restore and the document swap only, before the tree changes. */
+    noteTreeSwap(): void;
+}
+export interface CaretLandingDeps {
+    getDoc(): DocumentView;
+    /** The editor root's child list, where every descent starts. */
+    root: ChildList;
+    selectionState: SelectionState;
+    caretMemory: Pick<CaretMemory, 'forget' | 'noteExtreme'>;
+    getBlockElByPath: BlockElLookup;
+    /** The editor's own element, which holds focus while a block with no text is selected whole. */
+    getEditorRoot(): HTMLElement | null;
+    /** Null where nothing renders (a headless harness), so a landing only mounts. */
+    scroll: Pick<ScrollOwner, 'shows' | 'showRect' | 'place' | 'port'> | null;
+}
+export declare function createCaretLanding(deps: CaretLandingDeps): CaretLanding;