@voithos-labs/aragonite 0.10.4 → 0.10.7

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

@@ -1,50 +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;
-/** Select a surface's content whole, past its ambient prefix: the first-press Ctrl+A range and
- *  the triple-click one. */
+/** 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;
-export declare function applySingleBlockRange(blockEl: HTMLElement, startOffset: number, endOffset: number): 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,18 +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 { asDomTextOffset, asRawOffset, toClampedRawOffset, toDomTextOffset } from '../cursor/coordinate-spaces';
-import { createRangeFromOffsets } from '../cursor/content-offsets';
-import { clampToLandableRaw, createRangeAtDomTextOffsets, domTextOffsetAtNode } from '../cursor/widget-offset';
-import { ambientLengthOf, ambientSpanOf, 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;
@@ -20,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)
@@ -65,65 +39,44 @@ export function focusCollapsedCaret(getBlockElByPath, point) {
     blockEl.focus();
     return true;
 }
-/** Select a surface's content whole, past its ambient prefix: the first-press Ctrl+A range and
- *  the triple-click one. */
+// 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) {
-    const ambient = ambientSpanOf(el);
-    const ambientLen = ambient?.textContent?.length ?? 0;
-    const textLen = el.textContent?.length ?? 0;
-    if (ambient && textLen > ambientLen) {
-        if (!placeCaretAfterAmbientSpan(el))
-            return;
-        // textLen counts the full textContent (marker included) — a DomTextOffset by construction.
-        const endRange = createRangeFromOffsets(el, asDomTextOffset(textLen), asDomTextOffset(textLen));
-        if (endRange) {
-            window.getSelection()?.extend(endRange.endContainer, endRange.endOffset);
-        }
-        return;
-    }
-    const range = document.createRange();
-    range.selectNodeContents(el);
-    const sel = window.getSelection();
-    sel?.removeAllRanges();
-    sel?.addRange(range);
+    selectSurfaceContent(el);
 }
-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();
-    // A start at raw 0 under an ambient marker goes AFTER the island, as a caret does: Chromium
-    // drops a range that opens inside its contenteditable="false".
-    if (ambient > 0 && startOffset <= 0 && placeCaretAfterAmbientSpan(blockEl)) {
-        sel?.extend(range.endContainer, range.endOffset);
-        return;
-    }
-    sel?.removeAllRanges();
-    sel?.addRange(range);
+/** 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),
@@ -149,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.
@@ -167,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;

package/dist/selection/nearest-block.js

@@ -1,13 +1,13 @@
 /**
  * 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 { clampPointIntoBox } from '../cursor/point-offset';
-import { blockAtPoint, endpointAtPoint } from './block-hit-test';
+import { blockAtPoint, endpointAtPoint, holdsOwnText } from './block-hit-test';
 import { readBlockPath } from './path-lookup';
+import { isStrictAncestorOf } from './path-math';
 /** Document order, since bands may nest and every walk over them depends on it. */
 export function measureBlocks(root) {
     return blockHosts(root).map((el) => ({
@@ -15,12 +15,8 @@ export function measureBlocks(root) {
         rect: el.getBoundingClientRect()
     }));
 }
-/**
- * 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 function nearestBand(bands, y) {
     if (bands.length === 0)
         return null;
@@ -43,8 +39,8 @@ export function nearestBand(bands, y) {
     return { index: nearest, belowAll: false };
 }
 // ── Probing ────────────────────────────────────────────────────────────────
-/** 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 function probePointIn(rect, x, y, belowAll) {
     const inside = clampPointIntoBox(rect, x, y);
     return { x: belowAll ? rect.right - 1 : inside.x, y: inside.y };
@@ -54,20 +50,43 @@ export function probePointIn(rect, x, y, belowAll) {
 export function blockNearPoint(editorRoot, clientX, clientY) {
     const direct = blockAtPoint(editorRoot, clientX, clientY);
     if (direct)
-        return addressedAt(direct, clientX, clientY);
+        return addressedAt(descendToLevelChild(editorRoot, { hit: direct, x: clientX, y: clientY }));
     const rects = blockHosts(editorRoot).map((el) => el.getBoundingClientRect());
     const band = nearestBand(rects, clientY);
     if (!band)
         return null;
     const probe = probePointIn(rects[band.index], clientX, clientY, band.belowAll);
     const hit = blockAtPoint(editorRoot, probe.x, probe.y);
-    return hit && addressedAt(hit, probe.x, probe.y);
+    return hit && addressedAt(descendToLevelChild(editorRoot, { hit, ...probe }, band.belowAll));
+}
+/** 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 function descendToLevelChild(root, probed, belowAll = false) {
+    let current = probed;
+    for (;;) {
+        const { hit, x, y } = current;
+        // A grid kind resolves points inside itself through its own hooks.
+        if (hit.foreignDragHitTest || hit.caretTargetAtPoint)
+            return current;
+        const rects = blockHosts(hit.host).map((el) => el.getBoundingClientRect());
+        const band = nearestBand(rects, y);
+        if (!band)
+            return current;
+        if (holdsOwnText(hit) && !rects.some((r) => y >= r.top && y <= r.bottom))
+            return current;
+        const probe = probePointIn(rects[band.index], x, y, belowAll);
+        const next = blockAtPoint(root, probe.x, probe.y);
+        // Something drawn over the child answered instead, so the container keeps the point.
+        if (!next || !isStrictAncestorOf(hit.path, next.path))
+            return current;
+        current = { hit: next, ...probe };
+    }
 }
 // ── Internal ───────────────────────────────────────────────────────────────
-function addressedAt(hit, probeX, probeY) {
-    return { path: hit.path, endpointHere: () => endpointAtPoint(hit, probeX, probeY) };
+function addressedAt({ hit, x, y }) {
+    return { path: hit.path, endpointHere: () => endpointAtPoint(hit, x, y) };
 }
-/** The one selector for the mounted hosts, so the two walks above cannot drift apart. */
+/** The one selector for the mounted hosts, so the lookups above can't drift apart. */
 function blockHosts(root) {
     return [...root.querySelectorAll('[data-block-path]')];
 }

package/dist/selection/path-lookup.d.ts

@@ -1,5 +1,6 @@
-/** Document-tree path navigation. Pure functions over a Document + path. */
+/** Walks the document tree by path, and reads block paths off the DOM. */
 import type { Document } from '../core/nodes';
+import type { DocumentView } from '../core/node-views';
 /** Block immediately after `path` in doc order (children before siblings), else null. */
 export declare function nextPath(doc: Document, path: number[]): number[] | null;
 /** Block immediately before `path` in doc order (deepest last descendant first), else null. */
@@ -12,29 +13,37 @@ export declare function lastPath(doc: Document): number[] | null;
 export declare function firstLeafAtOrAfter(doc: Document, path: number[]): number[] | null;
 /** Descend `path` to its last leaf, or null when `path` doesn't resolve to a node. */
 export declare function lastLeafAtOrBefore(doc: Document, path: number[]): number[] | null;
-/**
- * The document path an element's own `data-block-path` carries. A plugin may own the attribute
- * with non-JSON content, so a parse failure resolves to null, never a throw.
- */
+/** The first leaf a caret can reach at or inside `path`, or null when `path` does not resolve. */
+export declare function firstCaretLeaf(doc: DocumentView, path: readonly number[]): number[] | null;
+/** The last leaf a caret can reach at or inside `path`, or null when `path` does not resolve. */
+export declare function lastCaretLeaf(doc: DocumentView, path: readonly number[]): number[] | null;
+/** The first caret leaf after `path` in document order, descending into it first when it has
+ *  children, as {@link nextPath} does. */
+export declare function nextCaretPath(doc: DocumentView, path: readonly number[]): number[] | null;
+/** The last caret leaf before `path`'s subtree in document order; an ancestor of `path` is never
+ *  the answer. `path` need not resolve, so the position a removed block left reads the same. */
+export declare function previousCaretPath(doc: DocumentView, path: readonly number[]): number[] | null;
+/** The first caret leaf at `slot` or after it, where `slot` may sit one past the end of its list
+ *  (the place a removed last child left). */
+export declare function firstCaretLeafFrom(doc: DocumentView, slot: readonly number[]): number[] | null;
+/** The outermost collapsed container whose hidden body `path` runs through, or null. */
+export declare function collapsedContainerHiding(doc: DocumentView, path: readonly number[]): number[] | null;
+/** The path an element's own `data-block-path` carries, read in one place: a plugin may own the
+ *  attribute with content of its own, so anything but a list of numbers reads as null. */
 export declare function readBlockPath(el: Element | null): number[] | null;
 /** Walk up from `el` to the nearest ancestor carrying `data-block-path`. */
 export declare function findBlockPathForElement(el: Element | null): number[] | null;
-/**
- * The deep `[...tablePath, row, col]` path of an element inside a table cell. Only block hosts
- * emit `data-block-path`, so {@link findBlockPathForElement} stops at the table and returns a
- * path whose offsets are cell indices while a caret read from the same element is in characters.
- * Any producer resolving an endpoint path from the DOM must come through here. Null outside a
- * cell grid; addresses the grid by selector contract (`data-table-row-idx`, `role="cell"`).
- */
+/** The `[...tablePath, row, col]` path of an element in a table cell: only block hosts carry a
+ *  path, so a DOM-read endpoint in a cell must come through here or it reads as the table's. */
 export declare function findCellPathForElement(el: Element | null): number[] | null;
-/** The editing SURFACE `el` sits in: the enclosing cell where there is one, else the enclosing
- *  block, and which of the two answered — a caller whose bytes live at a different scope for a
- *  cell reads the flag rather than re-deriving the pairing. */
+/** The editable element `el` sits in: the enclosing cell where there is one, else the enclosing
+ *  block, plus which of the two answered, so a caller that treats cells differently reads the
+ *  flag rather than re-deriving it. */
 export interface EditingSurface {
     path: number[];
     inCell: boolean;
 }
-/** The pairing {@link findCellPathForElement} says every producer owes, in one place. */
+/** The cell-then-block lookup {@link findCellPathForElement} requires, in one place. */
 export declare function findSurfaceForElement(el: Element | null): EditingSurface | null;
 /** {@link findSurfaceForElement} for a caller that needs only the path. */
 export declare function findSurfacePathForElement(el: Element | null): number[] | null;