@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/selection/multi-click.js

@@ -0,0 +1,197 @@
+/**
+ * Double and triple click: the second click of a run selects the word under it, the third the
+ * whole block's text, and a drag from either grows by that unit. The editor owns the gesture
+ * from the second click so the browser paints nothing of its own: its word rule varies by
+ * platform, it walks into non-editable widgets, and a marker here never joins a word.
+ */
+import { asDomTextOffset } from '../cursor/coordinate-spaces';
+import { caretOffsetAtPoint } from '../cursor/point-offset';
+import { containerDomTextLength, maskedWalkText, rawOfWalkOffset, walkOffsetOfRaw } from '../cursor/widget-offset';
+import { isWholeBlockInputProxy } from '../editor-actions/whole-block-focus-surface';
+import { installDragListener } from './drag-pointer';
+import { applySingleBlockRange, applySurfaceContentRange } from './native-bridge';
+import { blockNearPoint } from './nearest-block';
+import { readBlockPath } from './path-lookup';
+// ── The word rule ────────────────────────────────────────────────────────────
+let segmenter;
+function wordSegmenter() {
+    if (segmenter === undefined) {
+        segmenter =
+            typeof Intl.Segmenter === 'function'
+                ? new Intl.Segmenter(undefined, { granularity: 'word' })
+                : null;
+    }
+    return segmenter;
+}
+/** The segment at `offset`: the word ending there if there is one, else the segment starting
+ *  there, as the browser takes it. Null on a platform with no segmenter. */
+export function wordSpanAt(text, offset) {
+    const seg = wordSegmenter();
+    if (!seg || text.length === 0)
+        return null;
+    const segments = seg.segment(text);
+    const at = Math.max(0, Math.min(offset, text.length));
+    const left = at > 0 ? segments.containing(at - 1) : undefined;
+    const right = at < text.length ? segments.containing(at) : undefined;
+    if (left && right && left.index === right.index)
+        return spanOf(left);
+    if (left?.isWordLike)
+        return spanOf(left);
+    const pick = right ?? left;
+    return pick ? spanOf(pick) : null;
+}
+function spanOf(segment) {
+    return { start: segment.index, end: segment.index + segment.segment.length };
+}
+/** The raw span `granularity` takes around a raw offset in `surface`; null where the word rule
+ *  has nothing to read. */
+export function spanAround(surface, granularity, rawOffset) {
+    if (granularity === 'block') {
+        return { start: 0, end: rawOfWalkOffset(surface, containerDomTextLength(surface)) };
+    }
+    const span = wordSpanAt(maskedWalkText(surface), walkOffsetOfRaw(surface, rawOffset));
+    if (!span)
+        return null;
+    return {
+        start: rawOfWalkOffset(surface, asDomTextOffset(span.start)),
+        end: rawOfWalkOffset(surface, asDomTextOffset(span.end))
+    };
+}
+/** The unit a click count selects; a run stays at the block unit past three clicks. */
+export function granularityForClickCount(clickCount) {
+    if (clickCount === 2)
+        return 'word';
+    return clickCount >= 3 ? 'block' : null;
+}
+/** Root listeners for the gesture. The mousedown and mouseup are cancelled so the browser paints
+ *  no caret over the range, but never the pointerdown, which would silence the click. */
+export function installMultiClickSelect(deps) {
+    let lastPointerDown = null;
+    let claimed = false;
+    const onPointerDown = (e) => {
+        lastPointerDown = e;
+    };
+    const onMouseUp = (e) => {
+        if (claimed)
+            e.preventDefault();
+    };
+    const onMouseDown = (e) => {
+        claimed = false;
+        const granularity = granularityForClickCount(e.detail);
+        if (!granularity || e.button !== 0 || e.shiftKey || e.ctrlKey || e.metaKey || e.altKey)
+            return;
+        if (granularity === 'word' && pressesInlineWidget(e.target))
+            return;
+        // A widget already selected whole took the run with its first click, so no later click of
+        // that run is the block's: claiming one would paint a range over an object selection.
+        if (deps.pressesSelectedWidget(e.target))
+            return;
+        const press = pressedSurface(deps, e);
+        if (!press)
+            return;
+        const anchorSpan = selectAtPoint(press.surface, granularity, e.clientX, e.clientY);
+        if (!anchorSpan)
+            return;
+        e.preventDefault();
+        claimed = true;
+        const anchor = press.anchor ?? blockNearPoint(deps.editorRoot, e.clientX, e.clientY)?.endpointHere();
+        if (!anchor || !lastPointerDown)
+            return;
+        installDragListener({
+            editorRoot: deps.editorRoot,
+            scrollContainer: deps.getScrollContainer(),
+            selection: deps.selection,
+            getBlockElByPath: deps.getBlockElByPath,
+            lifetimeSignal: deps.lifetimeSignal,
+            granularity: createGranularity(deps.getBlockElByPath, press.surface, granularity, anchorSpan)
+        }, anchor, lastPointerDown);
+    };
+    deps.editorRoot.addEventListener('pointerdown', onPointerDown);
+    deps.editorRoot.addEventListener('mousedown', onMouseDown);
+    deps.editorRoot.addEventListener('mouseup', onMouseUp);
+    return () => {
+        deps.editorRoot.removeEventListener('pointerdown', onPointerDown);
+        deps.editorRoot.removeEventListener('mousedown', onMouseDown);
+        deps.editorRoot.removeEventListener('mouseup', onMouseUp);
+    };
+}
+/** The editable element a click selects in: the one under it, else the nearest block's, the
+ *  way a single click in the margin lands there. A block with no text has no word to select. */
+function pressedSurface(deps, e) {
+    // Up through a non-editable span inside the editable (a list's `- ` prefix) to the editable.
+    const own = surfaceOf(e.target);
+    if (own)
+        return isWholeBlockInputProxy(own) ? null : { surface: own, anchor: null };
+    const path = deps.marginBlockAt(e.target, e.clientX, e.clientY);
+    const block = path && deps.getBlockElByPath(path);
+    if (!block)
+        return null;
+    // A container's own box (a quote's gutter) selects in the leaf nearest the click, the way a
+    // click beside a line lands in that line.
+    const surface = block.contentEditable === 'true' ? block : nearestSurfaceIn(block, e.clientY);
+    const surfacePath = surface && pathOfSurface(surface);
+    const offset = surface && caretOffsetAtPoint(surface, e.clientX, e.clientY);
+    if (!surface)
+        return null;
+    return { surface, anchor: surfacePath && offset !== null ? { path: surfacePath, offset } : null };
+}
+function nearestSurfaceIn(block, clientY) {
+    let best = null;
+    let bestDistance = Infinity;
+    for (const el of block.querySelectorAll('[contenteditable="true"]')) {
+        const rect = el.getBoundingClientRect();
+        const distance = clientY < rect.top ? rect.top - clientY : Math.max(0, clientY - rect.bottom);
+        if (distance < bestDistance) {
+            best = el;
+            bestDistance = distance;
+        }
+    }
+    return best;
+}
+/** The path of the block this editable element is the text of; null for one addressed some
+ *  other way (a table's cell), whose drag is not a character drag. */
+function pathOfSurface(surface) {
+    const host = surface.closest('[data-block-path]');
+    const path = readBlockPath(host);
+    if (!path || !host?.contains(surface))
+        return null;
+    return host.querySelector('[contenteditable="true"]') === surface ? path : null;
+}
+/** Selects the unit's span at the click and returns it, in raw offsets. */
+function selectAtPoint(surface, granularity, clientX, clientY) {
+    if (granularity === 'block') {
+        applySurfaceContentRange(surface);
+        return spanAround(surface, 'block', 0);
+    }
+    const offset = caretOffsetAtPoint(surface, clientX, clientY);
+    const span = offset === null ? null : spanAround(surface, 'word', offset);
+    if (!span || span.start === span.end)
+        return null;
+    applySingleBlockRange(surface, span.start, span.end);
+    return span;
+}
+function createGranularity(getBlockElByPath, surface, granularity, anchorSpan) {
+    return {
+        surface,
+        anchorSpan,
+        spanAround: (offset) => spanAround(surface, granularity, offset) ?? { start: offset, end: offset },
+        expandFocus: (point, side) => {
+            const el = point.cellCoordinate ? null : getBlockElByPath(point.path);
+            const span = el && spanAround(el, granularity, point.offset);
+            if (!span)
+                return point;
+            return { path: point.path.slice(), offset: side === 'after' ? span.end : span.start };
+        }
+    };
+}
+/** The second click on an inline widget is that widget's own gesture (a footnote's double-click
+ *  takes its whole token), so the word level does nothing there. */
+function pressesInlineWidget(target) {
+    return target instanceof Element && target.closest('[data-inline-widget]') !== null;
+}
+function surfaceOf(target) {
+    let el = target instanceof HTMLElement ? target : null;
+    while (el && el.contentEditable !== 'true')
+        el = el.parentElement;
+    return el;
+}

package/dist/selection/native-bridge.d.ts

@@ -1,47 +1,40 @@
 /**
- * Bridge between the browser's native Selection API and SelectionPoint. Pure: callers provide
- * target elements and paths, no tree walking. SelectionPoint offsets are raw-semantic, so
- * DOM→raw conversion subtracts the length of a leading ambient marker span, whose textContent
- * counts toward DOM offsets but not raw.
+ * Bridges the browser's Selection API and `SelectionPoint`. Callers provide the elements and
+ * paths; nothing here walks the tree. A `SelectionPoint` offset counts raw bytes, and every
+ * conversion goes through `cursor/widget-offset.ts`.
  */
-import type { SelectionPoint, EditorSelection } from './primitives';
+import { type SelectionPoint, type EditorSelection } from './primitives';
 import type { SelectionState } from './selection-state.svelte';
 import type { BlockComponent } from '../block-component';
-/**
- * Read the collapsed caret inside `blockEl` into a raw-semantic SelectionPoint.
- * Returns null when the caret isn't inside this element.
- */
+/** Reads the caret inside `blockEl` as a raw-offset point; null when the caret is elsewhere. */
 export declare function readNativeCaretInBlock(blockEl: HTMLElement, path: number[]): SelectionPoint | null;
-/**
- * Place a collapsed native caret at a raw-semantic SelectionPoint, translating through the block's
- * ambient length. The park door's twin, so the same landable clamp applies: a caret may not sit
- * past a hidden marker run, whatever offset the caller derived. Only collapsed carets clamp — a
- * selection may COVER such a run, so `applySingleBlockRange` does not. Raw offset 0 under an
- * ambient marker goes AFTER the span: Chromium bounces carets out of its contenteditable="false".
- */
+/** Places a collapsed native caret at a `SelectionPoint`, clamped as `parkCaret` clamps: never
+ *  behind a hidden marker run. */
 export declare function applyCollapsedCaret(blockEl: HTMLElement, point: SelectionPoint): void;
-/**
- * Resolve `point.path` to its mounted block element and place a focused collapsed caret there.
- * Returns whether an element was found; a missing target is a no-op.
- */
+/** A focused collapsed caret in `point`'s mounted block, scrolled to by the focus call itself: kept
+ *  for the cross-block delete, typing and paste until they land through the caret landing. */
 export declare function focusCollapsedCaret(getBlockElByPath: (path: number[]) => HTMLElement | null, point: SelectionPoint): boolean;
-export declare function applySingleBlockRange(blockEl: HTMLElement, startOffset: number, endOffset: number): void;
+/** Selects an editable element's whole content, past its marker prefix: the first Ctrl+A
+ *  range and the triple-click one. */
+export declare function applySurfaceContentRange(el: HTMLElement): void;
+/** Selects raw `[anchorOffset, focusOffset]` in one block, backward when the focus comes first. */
+export declare function applySingleBlockRange(blockEl: HTMLElement, anchorOffset: number, focusOffset: number): void;
 export declare function clearNativeSelection(): void;
-/**
- * Keep focus inside the editor when an editable block holding it is windowed out; it would
- * otherwise fall to <body>. The root is non-editable (`tabindex="-1"`), so focusing it creates
- * no native range to sync. No-op unless this block holds focus and the root is still connected.
- */
+/** Keeps focus in the editor when a focused block is windowed out, or it would fall to <body>.
+ *  The root is non-editable, so focusing it creates no native range to sync. */
 export declare function parkFocusOnEditorRoot(blockEl: HTMLElement | null, editorRoot: HTMLElement | null): void;
-/**
- * Cross-block from SelectionState if active; otherwise the focused block's cursor as a deep
- * path (via getCursorPosition) or a shallow one. Null when no block reports a cursor.
- */
+/** The editor's live selection, for every caller outside a gesture. A selected widget reads as its
+ *  caret, ahead of the caret the browser briefly puts at its paragraph's start. */
 export declare function readCurrentSelection(selectionState: SelectionState, blockRefs: (BlockComponent | undefined)[]): EditorSelection | null;
-/**
- * Restore an EditorSelection to the DOM: custom-rendered selections (intra-table, cross-block)
- * route through SelectionState's overlay, same-path prose uses the native selection. State
- * write and caret landing run inside ONE SelectionState batch, so the single notification
- * carries the settled selection. False = the target resolved in the model but not in the DOM.
- */
-export declare function applySelectionToDom(selection: EditorSelection, selectionState: SelectionState, getBlockElByPath: (path: number[]) => HTMLElement | null): boolean;
+/** What a restore writes into, beside the selection state. */
+export interface RestoreTarget {
+    selectionState: SelectionState;
+    getBlockElByPath: (path: number[]) => HTMLElement | null;
+    /** Where the caret goes for an endpoint: the leaf a caret can sit in, never a hidden one. */
+    caretAt: (point: SelectionPoint) => SelectionPoint;
+    /** Takes focus for a block held whole, which has no text for a caret, as a drag leaves it. */
+    getEditorRoot: () => HTMLElement | null;
+}
+/** Restores an `EditorSelection` to the DOM in one `SelectionState` batch, so the single
+ *  notification carries the final selection. False when the target is not mounted. */
+export declare function applySelectionToDom(selection: EditorSelection, target: RestoreTarget): boolean;

package/dist/selection/native-bridge.js

@@ -1,17 +1,14 @@
 /**
- * Bridge between the browser's native Selection API and SelectionPoint. Pure: callers provide
- * target elements and paths, no tree walking. SelectionPoint offsets are raw-semantic, so
- * DOM→raw conversion subtracts the length of a leading ambient marker span, whose textContent
- * counts toward DOM offsets but not raw.
+ * Bridges the browser's Selection API and `SelectionPoint`. Callers provide the elements and
+ * paths; nothing here walks the tree. A `SelectionPoint` offset counts raw bytes, and every
+ * conversion goes through `cursor/widget-offset.ts`.
  */
-import { asRawOffset, toClampedRawOffset, toDomTextOffset } from '../cursor/coordinate-spaces';
-import { clampToLandableRaw, createRangeAtDomTextOffsets, domTextOffsetAtNode } from '../cursor/widget-offset';
-import { ambientLengthOf, placeCaretAfterAmbientSpan } from '../ambient/ambient-dom';
+import { cellPoint } from './primitives';
+import { assertInvariant } from '../assert';
+import { checkPlacementEndsWidget } from '../invariants/placement-ends-widget';
+import { placeCaretAtRaw, rawOffsetAt, selectRawRange, selectSurfaceContent } from '../cursor/widget-offset';
 // ── Read native → SelectionPoint ────────────────────────────────────────────
-/**
- * Read the collapsed caret inside `blockEl` into a raw-semantic SelectionPoint.
- * Returns null when the caret isn't inside this element.
- */
+/** Reads the caret inside `blockEl` as a raw-offset point; null when the caret is elsewhere. */
 export function readNativeCaretInBlock(blockEl, path) {
     if (document.activeElement !== blockEl)
         return null;
@@ -19,43 +16,21 @@ export function readNativeCaretInBlock(blockEl, path) {
     if (!sel || sel.rangeCount === 0)
         return null;
     const range = sel.getRangeAt(0);
-    // The anchor is the fixed end the selection grew from; for a BACKWARD selection it sits at
-    // range.end, so reading range.start would capture the moving focus and drop the highlighted
-    // span. Use the real anchor when it resolves inside this block, else keep range.start.
+    // In a backward selection the anchor sits at the range's end, so the range start would be the
+    // moving focus; the real anchor is used whenever it lies inside the block.
     const useAnchor = !sel.isCollapsed && sel.anchorNode !== null && blockEl.contains(sel.anchorNode);
     const node = useAnchor ? sel.anchorNode : range.startContainer;
     const nodeOffset = useAnchor ? sel.anchorOffset : range.startOffset;
-    const content = domTextOffsetAtNode(blockEl, node, nodeOffset);
-    return {
-        path: path.slice(),
-        offset: toClampedRawOffset(content, ambientLengthOf(blockEl))
-    };
+    return { path: path.slice(), offset: rawOffsetAt(blockEl, node, nodeOffset) };
 }
 // ── Apply SelectionPoint → native ───────────────────────────────────────────
-/**
- * Place a collapsed native caret at a raw-semantic SelectionPoint, translating through the block's
- * ambient length. The park door's twin, so the same landable clamp applies: a caret may not sit
- * past a hidden marker run, whatever offset the caller derived. Only collapsed carets clamp — a
- * selection may COVER such a run, so `applySingleBlockRange` does not. Raw offset 0 under an
- * ambient marker goes AFTER the span: Chromium bounces carets out of its contenteditable="false".
- */
+/** Places a collapsed native caret at a `SelectionPoint`, clamped as `parkCaret` clamps: never
+ *  behind a hidden marker run. */
 export function applyCollapsedCaret(blockEl, point) {
-    const ambient = ambientLengthOf(blockEl);
-    const offset = clampToLandableRaw(blockEl, point.offset, ambient);
-    if (ambient > 0 && offset <= 0 && placeCaretAfterAmbientSpan(blockEl))
-        return;
-    const target = toDomTextOffset(asRawOffset(offset), ambient);
-    const range = createRangeAtDomTextOffsets(blockEl, target, target);
-    if (!range)
-        return;
-    const sel = window.getSelection();
-    sel?.removeAllRanges();
-    sel?.addRange(range);
+    placeCaretAtRaw(blockEl, point.offset, { clamp: 'reachable' });
 }
-/**
- * Resolve `point.path` to its mounted block element and place a focused collapsed caret there.
- * Returns whether an element was found; a missing target is a no-op.
- */
+/** A focused collapsed caret in `point`'s mounted block, scrolled to by the focus call itself: kept
+ *  for the cross-block delete, typing and paste until they land through the caret landing. */
 export function focusCollapsedCaret(getBlockElByPath, point) {
     const blockEl = getBlockElByPath(point.path);
     if (!blockEl)
@@ -64,37 +39,44 @@ export function focusCollapsedCaret(getBlockElByPath, point) {
     blockEl.focus();
     return true;
 }
-export function applySingleBlockRange(blockEl, startOffset, endOffset) {
-    const ambient = ambientLengthOf(blockEl);
-    const range = createRangeAtDomTextOffsets(blockEl, toDomTextOffset(asRawOffset(startOffset), ambient), toDomTextOffset(asRawOffset(endOffset), ambient));
-    if (!range)
-        return;
-    const sel = window.getSelection();
-    sel?.removeAllRanges();
-    sel?.addRange(range);
+// A restore's caret; the restore's reveal policy decides the scroll.
+function restoreCollapsedCaret(getBlockElByPath, point) {
+    const blockEl = getBlockElByPath(point.path);
+    if (!blockEl)
+        return false;
+    applyCollapsedCaret(blockEl, point);
+    blockEl.focus({ preventScroll: true });
+    return true;
+}
+/** Selects an editable element's whole content, past its marker prefix: the first Ctrl+A
+ *  range and the triple-click one. */
+export function applySurfaceContentRange(el) {
+    selectSurfaceContent(el);
+}
+/** Selects raw `[anchorOffset, focusOffset]` in one block, backward when the focus comes first. */
+export function applySingleBlockRange(blockEl, anchorOffset, focusOffset) {
+    selectRawRange(blockEl, anchorOffset, focusOffset);
 }
 export function clearNativeSelection() {
     window.getSelection()?.removeAllRanges();
 }
-/**
- * Keep focus inside the editor when an editable block holding it is windowed out; it would
- * otherwise fall to <body>. The root is non-editable (`tabindex="-1"`), so focusing it creates
- * no native range to sync. No-op unless this block holds focus and the root is still connected.
- */
+/** Keeps focus in the editor when a focused block is windowed out, or it would fall to <body>.
+ *  The root is non-editable, so focusing it creates no native range to sync. */
 export function parkFocusOnEditorRoot(blockEl, editorRoot) {
     if (!blockEl || !editorRoot?.isConnected)
         return;
-    // preventScroll: the implicit focus scroll would fight the reveal path's, whichever port
-    // owns the scrolling.
+    // `preventScroll`: the focus call's own scroll would fight the scroll-into-view that mounts
+    // the block.
     if (document.activeElement === blockEl)
         editorRoot.focus({ preventScroll: true });
 }
-// ── Selection read/restore for undo ─────────────────────────────────────────
-/**
- * Cross-block from SelectionState if active; otherwise the focused block's cursor as a deep
- * path (via getCursorPosition) or a shallow one. Null when no block reports a cursor.
- */
+// ── Selection read/restore ───────────────────────────────────────────────────
+/** The editor's live selection, for every caller outside a gesture. A selected widget reads as its
+ *  caret, ahead of the caret the browser briefly puts at its paragraph's start. */
 export function readCurrentSelection(selectionState, blockRefs) {
+    const widget = selectionState.widgetCaret();
+    if (widget)
+        return collapsedSelectionAt(widget.path, widget.offset);
     if (selectionState.isCrossBlock && selectionState.anchor && selectionState.focus) {
         return {
             anchor: copySelectionPoint(selectionState.anchor),
@@ -120,11 +102,8 @@ export function readCurrentSelection(selectionState, blockRefs) {
 function collapsedSelectionAt(path, offset) {
     return { anchor: { path: path.slice(), offset }, focus: { path: path.slice(), offset } };
 }
-/**
- * The focused block's native selection as distinct anchor/focus raw offsets, so getSelection()
- * reports a within-block range instead of collapsing it to the caret. Null when collapsed or
- * outside the active block. Offsets convert through that block's ambient length.
- */
+/** The focused block's native selection as distinct raw offsets, so a within-block range is not
+ *  reported collapsed to the caret. Null when collapsed or outside the active block. */
 function nativeRangeInFocusedBlock(path) {
     // Node-env callers (undo snapshot capture in unit tests) have no DOM; fall back to the
     // single caret offset rather than touching document/window.
@@ -138,65 +117,66 @@ function nativeRangeInFocusedBlock(path) {
         return null;
     if (!active.contains(sel.anchorNode) || !active.contains(sel.focusNode))
         return null;
-    const ambient = ambientLengthOf(active);
-    const anchorOffset = toClampedRawOffset(domTextOffsetAtNode(active, sel.anchorNode, sel.anchorOffset), ambient);
-    const focusOffset = toClampedRawOffset(domTextOffsetAtNode(active, sel.focusNode, sel.focusOffset), ambient);
     return {
-        anchor: { path: path.slice(), offset: anchorOffset },
-        focus: { path: path.slice(), offset: focusOffset }
+        anchor: { path: path.slice(), offset: rawOffsetAt(active, sel.anchorNode, sel.anchorOffset) },
+        focus: { path: path.slice(), offset: rawOffsetAt(active, sel.focusNode, sel.focusOffset) }
     };
 }
-// A restored table endpoint must keep cellCoordinate, or it skips the whole-row snap and the
-// deep-cell collapse routing; the two-branch copy carries the union variant through undo.
+// A restored table endpoint must keep `cellCoordinate`, or it skips the whole-row snap and the
+// collapse into the cell; the two branches keep the union variant intact through undo.
 function copySelectionPoint(point) {
     if (point.cellCoordinate) {
-        return { path: point.path.slice(), offset: point.offset, cellCoordinate: true };
+        return cellPoint(point.path, point.offset);
     }
     return { path: point.path.slice(), offset: point.offset };
 }
-/**
- * Restore an EditorSelection to the DOM: custom-rendered selections (intra-table, cross-block)
- * route through SelectionState's overlay, same-path prose uses the native selection. State
- * write and caret landing run inside ONE SelectionState batch, so the single notification
- * carries the settled selection. False = the target resolved in the model but not in the DOM.
- */
-export function applySelectionToDom(selection, selectionState, getBlockElByPath) {
+/** Restores an `EditorSelection` to the DOM in one `SelectionState` batch, so the single
+ *  notification carries the final selection. False when the target is not mounted. */
+export function applySelectionToDom(selection, target) {
     let placed = false;
-    selectionState.batch(() => {
-        placed = placeRestoredSelection(selection, selectionState, getBlockElByPath);
-        // Announced, not inferred from the arm's own mutation: a restore onto an already-clear
-        // state changes no editor-owned field and still moves the caret subscribers read back.
-        selectionState.announceSelection();
+    target.selectionState.batch(() => {
+        placed = placeRestoredSelection(selection, target);
+        assertInvariant('placement-ends-widget', () => checkPlacementEndsWidget(target.selectionState.widget));
+        // Announced explicitly: a restore onto an already clear state changes no field of the
+        // selection state and still moves the caret that subscribers read back.
+        target.selectionState.announceSelection();
     });
     return placed;
 }
-function placeRestoredSelection(selection, selectionState, getBlockElByPath) {
-    // Classify before mutating state so a single-block restore never mints a phantom transient
-    // cross-block state (enterCrossBlock → clear).
+function placeRestoredSelection(selection, target) {
+    const { selectionState, getBlockElByPath } = target;
+    // Classify before touching state, so a single-block restore never passes through a transient
+    // cross-block state (`enterCrossBlock` then `clear`).
     const route = selectionState.restoreRoute(selection.anchor, selection.focus);
     if (route === 'collapsed') {
         selectionState.clear();
-        // Through the landing like the custom arm below: a collapsed CELL point reaches this arm
-        // (equal offsets classify before coordinate space does) carrying a cell index, which a
-        // char walk on the table wrapper would seat somewhere in the grid's rendered text.
-        return focusCollapsedCaret(getBlockElByPath, selectionState.cellLandingFor(selection.anchor));
+        return restoreCollapsedCaret(getBlockElByPath, target.caretAt(selection.anchor));
+    }
+    if (route === 'whole-block') {
+        const whole = { path: selection.anchor.path.slice(), wholeBlock: true };
+        selectionState.enterCrossBlock(whole, whole);
+        clearNativeSelection();
+        const root = target.getEditorRoot();
+        root?.focus({ preventScroll: true });
+        return root !== null;
     }
-    // No landing translation on this arm: a same-path pair whose block is a table routes 'custom',
-    // so every pair reaching here is a char range on a prose leaf.
+    // No cell translation here: a same-path pair inside a table routes to the overlay, so every
+    // pair reaching this branch is a character range on a text leaf.
     if (route === 'single-block') {
         selectionState.clear();
         const blockEl = getBlockElByPath(selection.anchor.path);
         if (!blockEl)
             return false;
         applySingleBlockRange(blockEl, selection.anchor.offset, selection.focus.offset);
-        blockEl.focus();
+        blockEl.focus({ preventScroll: true });
         return true;
     }
-    // Custom: the overlay paints. Park a collapsed caret in the focus block as a paste/key
-    // dispatch anchor (Chromium otherwise routes paste to <body>). A cell-coordinate focus
-    // addresses the table wrapper by cell index, so park in its deep cell instead.
+    // The overlay paints the range; a collapsed caret in the focus block (or its cell) gives paste
+    // and key events a target, since Chromium otherwise routes paste to <body>.
     selectionState.enterCrossBlock(selection.anchor, selection.focus);
-    if (focusCollapsedCaret(getBlockElByPath, selectionState.cellLandingFor(selection.focus))) {
+    // The stored focus, which normalization may have turned into a cell index.
+    const focus = selectionState.focus ?? selection.focus;
+    if (restoreCollapsedCaret(getBlockElByPath, target.caretAt(focus))) {
         return true;
     }
     clearNativeSelection();

package/dist/selection/nearest-block.d.ts

@@ -1,10 +1,10 @@
 /**
  * The mounted block nearest a viewport point, and the endpoint that point addresses. A gesture
- * that must answer EVERY point — the dead-space click, a drag into the margin — resolves an
- * off-block point through here instead of declining it. The probe point never leaves the module:
- * a caller hit-testing at its own raw point gets no offset at all on a character surface.
- * Only mounted blocks are measured; a caller answering for a windowed-out tail reconciles itself.
+ * that must answer every point (a dead-space click, a drag into the margin) resolves an off-block
+ * point here: clamped into the nearest box, then handed down a container to the child level with
+ * it. Only mounted blocks are measured; a caller handling an unmounted tail does so itself.
  */
+import { type BlockHit } from './block-hit-test';
 import type { SelectionEndpoint } from './primitives';
 export interface BlockBand {
     top: number;
@@ -17,18 +17,14 @@ export interface MeasuredBlock {
 }
 /** Document order, since bands may nest and every walk over them depends on it. */
 export declare function measureBlocks(root: HTMLElement): MeasuredBlock[];
-/**
- * The band a `y` belongs to. `belowAll` marks a point past the last band, the end-of-document
- * gesture, which lands at a trailing corner rather than under its own x. A y in a gap resolves to
- * the nearest band, so no point is left unanswered. Bands arrive in document order and may nest,
- * so containment scans forward, outermost wins.
- */
+/** The band a `y` belongs to; a y in a gap resolves to the nearest band, so no point is left
+ *  unanswered. `belowAll` marks a point past the last band, which lands at a trailing corner. */
 export declare function nearestBand(bands: BlockBand[], y: number): {
     index: number;
     belowAll: boolean;
 } | null;
-/** The band's own probe point: {@link clampPointIntoBox}, except that `belowAll` takes the
- *  trailing corner — the block's last position — rather than the point's own x. */
+/** The point a band is hit-tested at: {@link clampPointIntoBox}, except that `belowAll` takes the
+ *  trailing corner (the block's last position) rather than the point's own x. */
 export declare function probePointIn(rect: DOMRect, x: number, y: number, belowAll: boolean): {
     x: number;
     y: number;
@@ -41,3 +37,12 @@ export interface NearestBlock {
 /** The block a point addresses: the one under it, else the nearest one with the point clamped
  *  into its box. Null only where nothing is mounted. */
 export declare function blockNearPoint(editorRoot: HTMLElement, clientX: number, clientY: number): NearestBlock | null;
+/** A hit and the point it was hit-tested at. */
+export interface ProbedHit {
+    hit: BlockHit;
+    x: number;
+    y: number;
+}
+/** Hands a point on a container's own box (a quote's gutter, a list's indent) down to the child
+ *  level with it, at any depth; a container with its own editable row keeps an unmatched point. */
+export declare function descendToLevelChild(root: HTMLElement, probed: ProbedHit, belowAll?: boolean): ProbedHit;