@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/selection/dead-space-caret.js

@@ -1,41 +1,38 @@
 /**
- * Caret placement from a viewport point: the dead-space click (padding beside a block, the area
- * below the last one) and the public `placeCaretAtPoint`, which shares the walk under the gesture
- * guards. A y belonging to no band may name an eligible gap boundary; otherwise the point clamps
- * into the nearest mounted block's box (`nearest-block.ts`) and resolves there, no kind named.
- * Only what is mounted is measured, so "below the last block" resolves against the CST (VR-6).
+ * Places the caret from a viewport point, for a click in the editor's dead space (the padding
+ * beside a block, the area below the last one) and the public `placeCaretAtPoint` alike. A point
+ * between two blocks may become a gap caret; otherwise it clamps into the nearest mounted block
+ * and descends to the child level with it. Only mounted blocks are measured.
  */
 import { CURSOR_END } from '../block-component';
-import { blockAtPoint } from './block-hit-test';
-import { measureBlocks, nearestBand, probePointIn } from './nearest-block';
+import { blockAtPoint, holdsOwnText } from './block-hit-test';
+import { descendToLevelChild, measureBlocks, nearestBand, probePointIn } from './nearest-block';
 import { placeGapCaret } from './caret-doors';
 import { canGapStop } from './gap-caret';
-import { offsetFromViewportPoint } from '../cursor/point-offset';
+import { caretOffsetAtPoint } from '../cursor/point-offset';
+import { docPathFrom } from '../cursor/coordinate-spaces';
 export function createDeadSpaceCaret(deps) {
-    // The press half of the gesture, because `click` alone cannot tell a dead-space click from a
-    // drag that STARTED on a block and released in the margin: both report dead space as target.
+    // Tracked from pointerdown because `click` alone cannot tell a dead-space click from a drag
+    // that started on a block and released in the margin: both report dead space as the target.
     let pressedOnDeadSpace = false;
-    /** The end-of-document gesture when the tail is windowed out: reveal the real last block,
-     *  then land at its end — which is where the trailing-corner probe below lands when the
-     *  slice already reaches it. */
+    /** A click below the document when its tail is not mounted: land at the real last block's end,
+     *  which is where the clamped point below lands once the tail is mounted. */
     async function landAtDocumentEnd() {
         const index = deps.lastBlockIndex();
         if (index < 0)
             return;
-        const component = await deps.revealBlock(index);
-        if (!component?.focusable)
-            return;
+        // Before the landing, which then records the end it lands at as the outside of a closer.
         deps.resetSelectionForClick();
-        component.focus(CURSOR_END);
+        await deps.land({ path: docPathFrom([index]), offset: CURSOR_END });
     }
     function placeAtPoint(root, x, y) {
-        // One measuring pass for both walks: the boundary question and the band clamp read the
-        // same layout, and a second query would force it again inside one click.
+        // One measuring pass: the gap check and the nearest-block clamp read the same layout, and
+        // a second query would force layout again inside one click.
         const blocks = measureBlocks(root);
         const boundary = rootBoundaryOutsideBands(blocks, y);
         if (boundary !== null && canGapStop(deps.gapScope, [], boundary)) {
-            // The preamble first, as on the block landing below — it clears the gap, so
-            // nothing may run between it and the door. The door ends a live range (G2.12).
+            // The reset runs first, as for a block below: it clears the gap caret, so nothing may
+            // run between it and `placeGapCaret`, which also ends a live range (G2.12).
             deps.resetSelectionForClick();
             placeGapCaret(deps.gapScope.selection, { parentPath: [], index: boundary });
             return true;
@@ -43,22 +40,18 @@ export function createDeadSpaceCaret(deps) {
         const band = nearestBand(blocks.map((b) => b.rect), y);
         if (!band)
             return false;
-        // Below the last MOUNTED block is not below the document while a tail is windowed out,
-        // and a host's own below-the-editor handler resolves against the whole document — so
-        // the two would land a document apart. The reveal road is the only answer available
-        // here: the target has no box to probe until it mounts.
+        // Below the last mounted block is not below the document while a tail is windowed out,
+        // and the real last block has no box to hit-test until it mounts.
         if (band.belowAll && lastMountedTopLevel(blocks) !== deps.lastBlockIndex()) {
             void landAtDocumentEnd();
             return true;
         }
-        const { x: probeX, y: probeY } = probePointIn(blocks[band.index].rect, x, y, band.belowAll);
-        const hit = blockAtPoint(root, probeX, probeY);
-        if (!hit)
+        const near = hitInBand(root, blocks, band, x, y);
+        if (!near)
             return false;
-        // Prose lands the caret on the line the click is level with, as any editor does. A block
-        // with no character surface (an equation, a table, a rule) has no such line, and a revealed
-        // source is one only while it is being edited: a click that was not ON the block is a click
-        // on nothing, and focuses nothing (the click's owner then blurs what was being edited).
+        const { hit, x: probeX, y: probeY } = near;
+        // A block with no text line (an equation, a table, source shown only while editing) takes
+        // only a click on its content; a click beside it focuses nothing, so the edit blurs.
         const transient = hit.charSurface?.classList.contains('md-source-surface') ?? false;
         if ((!hit.charSurface || transient) && !pressedOnBlockContent(root, x, y))
             return false;
@@ -68,41 +61,44 @@ export function createDeadSpaceCaret(deps) {
         const component = deps.getBlockComponent(hit.path);
         if (!component?.focusable)
             return false;
-        // An internal landing needs the deep door; a block declaring the hook without it
-        // can't be reached, and declining here keeps the selection intact.
+        // A caret target inside a grid needs `focusByPath`; declining a block that lacks it keeps
+        // the selection intact.
         if (landing.path.length > 0 && !component.focusByPath)
             return false;
-        // Only once the landing is known, so a declined point leaves the selection as it
-        // found it: a live range stays painted over a caret placed elsewhere, and the next
-        // printable key type-replaces the whole of it.
+        // The reset waits for a known caret target, so a declined point leaves a live range painted
+        // and the next printable key replaces the whole of it.
         deps.resetSelectionForClick();
-        // Both doors end the live range (`selection/caret-doors.ts`); `focusByPath` reaches
-        // the leaf's own `focus`.
+        // Both calls end a live range (`selection/caret-doors.ts`); `focusByPath` reaches the
+        // leaf's own `focus`.
         if (landing.path.length === 0)
             component.focus(landing.offset);
         else
             component.focusByPath(landing.path, landing.offset);
-        // The probe point is inside the block's box, so the surface answers it exactly as it
-        // answers a click there: a landing at an atomic widget's edge has nothing to show for
-        // itself until the surface's own snap paints it.
-        leafOf(component, landing.path)?.snapCaretToPoint?.(probeX, probeY);
+        // The block's own snap answers the clamped point as a click there, so a caret beside a
+        // non-editable widget is painted rather than showing nothing.
+        const leaf = landing.path.length === 0
+            ? component
+            : deps.getBlockComponent([...hit.path, ...landing.path]);
+        leaf?.snapCaretToPoint?.(probeX, probeY);
         return true;
     }
-    function anchorAtPoint(root, x, y) {
+    /** The nearest block's hit for a click, with the point clamped into its box. */
+    function hitNearPoint(root, x, y) {
         const blocks = measureBlocks(root);
         const band = nearestBand(blocks.map((b) => b.rect), y);
         if (!band)
             return null;
         if (band.belowAll && lastMountedTopLevel(blocks) !== deps.lastBlockIndex())
             return null;
-        const { x: probeX, y: probeY } = probePointIn(blocks[band.index].rect, x, y, band.belowAll);
-        const hit = blockAtPoint(root, probeX, probeY);
-        if (!hit)
+        return hitInBand(root, blocks, band, x, y);
+    }
+    function anchorAtPoint(root, x, y) {
+        const near = hitNearPoint(root, x, y);
+        if (!near)
             return null;
-        // No character surface to measure against — a rendered equation, a rule, a table — so the
-        // block is the unit, and the funnel picks the side by the drag's direction. An offset would
-        // put a range END at the block's start and leave it out; a cell would make the drag a caret
-        // placement in the nearest column. A rule names no landing at all, and is a unit all the same.
+        const { hit, x: probeX, y: probeY } = near;
+        // No text to measure against: an offset would put a range end at the block's start and
+        // leave the block out, and a cell would turn the drag into a caret placement.
         if (!hit.charSurface)
             return { path: hit.path.slice(), wholeBlock: true };
         const landing = landingFor(hit, probeX, probeY);
@@ -112,9 +108,13 @@ export function createDeadSpaceCaret(deps) {
             return { path: hit.path.slice(), wholeBlock: true };
         return { path: hit.path.slice(), offset: landing.offset };
     }
+    function blockPathNearPoint(root, x, y) {
+        return hitNearPoint(root, x, y)?.hit.path.slice() ?? null;
+    }
     return {
         isDeadSpaceTarget: isDeadSpace,
         anchorAtPoint,
+        blockPathNearPoint,
         notePress(root, event) {
             pressedOnDeadSpace =
                 isDeadSpace(root, event.target) &&
@@ -127,9 +127,8 @@ export function createDeadSpaceCaret(deps) {
             pressedOnDeadSpace = false;
             if (!pressed || !isDeadSpace(root, event.target))
                 return false;
-            // A drag that ended in the margin leaves a real range behind; collapsing it would
-            // throw away what the user just selected. This sees only NATIVE ranges: a cross-block
-            // range is overlay-painted with the native selection empty, and is ended below instead.
+            // A drag that ended in the margin leaves a native range the user just selected. A
+            // cross-block range leaves the native selection empty, so it is ended below instead.
             const native = root.ownerDocument.defaultView?.getSelection();
             if (native && native.rangeCount > 0 && !native.isCollapsed)
                 return false;
@@ -139,7 +138,7 @@ export function createDeadSpaceCaret(deps) {
     };
 }
 // ── Internal ───────────────────────────────────────────────────────────────
-/** The last top-level index the slice currently holds; -1 when none is mounted. */
+/** The last mounted top-level index; -1 when none is mounted. */
 function lastMountedTopLevel(blocks) {
     for (let i = blocks.length - 1; i >= 0; i--) {
         const path = blocks[i].path;
@@ -148,18 +147,14 @@ function lastMountedTopLevel(blocks) {
     }
     return -1;
 }
-/**
- * The root-level boundary a `y` belonging to NO band names: the editor's leading padding,
- * and the space between two adjacent bands where a layout leaves one. Below the last band
- * is excluded — that y is the end-of-document gesture, and under windowing the last MOUNTED
- * band is not the last block. Indices come off the path attribute for the same reason.
- */
+/** The root-level gap a `y` outside every block's box names. Below the last block is excluded:
+ *  that click means end of document, and the last mounted block may not be the last block. */
 function rootBoundaryOutsideBands(blocks, y) {
     const bands = blocks.flatMap((b) => b.path?.length === 1 ? [{ index: b.path[0], top: b.rect.top, bottom: b.rect.bottom }] : []);
     if (bands.length === 0)
         return null;
-    // Only when the document's own first block is mounted: above a windowed-out slice the
-    // blocks the point sits over are not the ones the boundary would name.
+    // Only when the document's first block is mounted: above a windowed-out head, the blocks
+    // under the point are not the ones the gap would name.
     if (y < bands[0].top)
         return bands[0].index === 0 ? 0 : null;
     for (let i = 1; i < bands.length; i++) {
@@ -170,26 +165,22 @@ function rootBoundaryOutsideBands(blocks, y) {
     }
     return null;
 }
-/** The component the landing addresses: this one on a character surface, else the leaf a
- *  coordinate-addressed kind's internal path names. */
-function leafOf(component, path) {
-    if (path.length === 0)
-        return component;
-    return component.getBlockComponentByPath?.(path) ?? null;
+/** The block a band answers for a point: the point clamped into the band's box, then handed
+ *  down to the child level with it when the box is a container's. */
+function hitInBand(root, blocks, band, x, y) {
+    const probe = probePointIn(blocks[band.index].rect, x, y, band.belowAll);
+    const hit = blockAtPoint(root, probe.x, probe.y);
+    return hit && descendToLevelChild(root, { hit, ...probe }, band.belowAll);
 }
-/**
- * The targets that mean "dead space": the root, and any block list inside it. A host that
- * widens or pads `.block-list` moves the whole visible side gutter onto the list, which
- * reports itself rather than the root. Everything else the editor renders has its own
- * identity and is declined here.
- */
+/** The root and any block list inside it: a host that pads `.block-list` moves the side gutter
+ *  onto the list, which then reports itself as the click target. */
 function isDeadSpace(root, target) {
     if (target === root)
         return true;
     return target instanceof Element && target.classList.contains('block-list');
 }
-/** Whether the ORIGINAL point (not the clamped probe) sits inside some block's content: on a
- *  descendant of a host, not on the host's own box or the dead space around it. */
+/** Whether the original point (not the clamped one) sits inside some block's content: on a
+ *  descendant of a block host, not on the host's own box or the dead space around it. */
 function pressedOnBlockContent(root, x, y) {
     const direct = document.elementFromPoint(x, y);
     if (!(direct instanceof Element) || isDeadSpace(root, direct))
@@ -197,23 +188,24 @@ function pressedOnBlockContent(root, x, y) {
     const host = direct.closest('[data-block-path]');
     return host !== null && host !== direct;
 }
-/**
- * Where the caret goes for a resolved hit: an internal child path (empty for a
- * character-addressed surface) plus the offset within that leaf. Null declines the click.
- */
+/** Where the caret goes for a hit: an inner child path (empty for a text block) and the offset
+ *  within that leaf; null declines the click. */
 function landingFor(hit, probeX, probeY) {
     if (hit.caretTargetAtPoint)
         return hit.caretTargetAtPoint(probeX, probeY);
-    // A kind with only the drag hook addresses cells and named no caret landing.
+    // A kind with only the drag hook addresses cells and names no caret target.
     if (hit.foreignDragHitTest)
         return null;
-    // A leaf with no character surface (a rule, a folded equation) reached here was pressed on
-    // its own box: the block itself is the landing, and its `focus` ignores the offset.
+    // A leaf with no text (a rule, a rendered equation) reaches here only when clicked on its
+    // own box: the block itself is the target, and its `focus` ignores the offset.
     if (!hit.charSurface)
         return { path: [], offset: 0 };
-    // Reading mode flips contenteditable off, and a non-editable leaf has no character position.
-    if (!hit.charSurface.matches('[contenteditable="true"]'))
+    // Reading mode turns editing off, so no text is a block's own there. A container that kept
+    // the point has only its children's text, none of it level with the point.
+    if (!holdsOwnText(hit))
         return null;
-    const offset = offsetFromViewportPoint(hit.charSurface, probeX, probeY);
+    // A block whose box pads its own text (a code block) lands a point in that padding on the
+    // nearest line.
+    const offset = caretOffsetAtPoint(hit.charSurface, probeX, probeY);
     return offset === null ? null : { path: [], offset };
 }

package/dist/selection/drag-pointer.d.ts

@@ -7,6 +7,7 @@ import type { UserScrollport } from '../cursor/scroll-ancestors';
 import type { SelectionState } from './selection-state.svelte';
 import type { SelectionEndpoint } from './primitives';
 import type { BlockElLookup } from '../editor-keys';
+import { type SelectionPoint } from './primitives';
 export interface DragContext {
     editorRoot: HTMLElement;
     /** What autoscrolls this drag: an element, or the window (`cursor/scroll-ancestors`). */
@@ -15,11 +16,27 @@ export interface DragContext {
     getBlockElByPath: BlockElLookup;
     /** Aborted on editor unmount; forwarded to the session's teardown. */
     lifetimeSignal?: AbortSignal;
-    /**
-     * The press began outside every editable surface (the editor's margin), so no native drag
-     * is extending a selection underneath: the session paints the same-block range itself.
-     */
-    paintSameBlock?: boolean;
+    /** Read at each move: the drag began where no native drag extends a selection underneath (the
+     *  editor's margin, a press it placed itself), so the session paints the same-block range. */
+    paintSameBlock?: () => boolean;
+    /** A drag continuing a double or triple click: the range grows by that click's unit. */
+    granularity?: DragGranularity;
+}
+/** The unit a multi-click drag grows by. Spans are raw offsets; the span the click itself
+ *  selected is the floor the range never shrinks below. */
+export interface DragGranularity {
+    /** The element the click selected in; a pointer over no other block paints here. */
+    surface: HTMLElement;
+    anchorSpan: {
+        start: number;
+        end: number;
+    };
+    spanAround(offset: number): {
+        start: number;
+        end: number;
+    };
+    /** A focus in another block, pushed to the unit's boundary on the side away from the anchor. */
+    expandFocus(point: SelectionPoint, side: 'before' | 'after'): SelectionEndpoint;
 }
 /** Document-level pointer listeners for a cross-block drag started at `down`, plus a disposer. */
 export declare function installDragListener(ctx: DragContext, anchorPoint: SelectionEndpoint, down: PointerEvent): {

package/dist/selection/drag-pointer.js

@@ -3,6 +3,7 @@
  * `createPointerDragSession`, whose document-level listeners deliver events even after the
  * pointer leaves the originating block.
  */
+import { caretOffsetAtPoint } from '../cursor/point-offset';
 import { applyCollapsedCaret, applySingleBlockRange, clearNativeSelection } from './native-bridge';
 import { isWholeBlockEndpoint } from './primitives';
 import { comparePaths } from './path-math';
@@ -12,25 +13,27 @@ import { blockNearPoint } from './nearest-block';
 /** Document-level pointer listeners for a cross-block drag started at `down`, plus a disposer. */
 export function installDragListener(ctx, anchorPoint, down) {
     function processMove(clientX, clientY) {
-        // The nearest block, not the one under the pointer: moves coalesce to one per frame, so a
-        // burst ending in the margin would otherwise discard every on-block sample in it, and an
-        // autoscrolling drag sends nothing but off-block points.
+        // The nearest block, not the one under the pointer: moves coalesce to one per frame, and
+        // an autoscrolling drag sends nothing but off-block points.
         const near = blockNearPoint(ctx.editorRoot, clientX, clientY);
         if (!near)
             return;
+        if (ctx.granularity) {
+            processGranularMove(ctx.granularity, near, clientX, clientY);
+            return;
+        }
         if (comparePaths(near.path, anchorPoint.path) === 0) {
             if (!('offset' in anchorPoint)) {
-                if (ctx.paintSameBlock)
+                if (ctx.paintSameBlock?.())
                     takeAnchorBlockWhole();
                 return;
             }
             if (ctx.selection.isCrossBlock) {
-                // Pointer returned to the anchor block: collapse so the overlay stops painting a
-                // stale remote range. The browser's drag has been extending the native selection
-                // underneath all along, so handing back gives the right single-block highlight.
+                // Back in the anchor block: the browser's drag has been extending the native
+                // selection all along, so collapsing the cross-block range restores its highlight.
                 ctx.selection.collapse();
             }
-            if (ctx.paintSameBlock)
+            if (ctx.paintSameBlock?.())
                 paintSameBlockRange(near.endpointHere());
             return;
         }
@@ -39,8 +42,8 @@ export function installDragListener(ctx, anchorPoint, down) {
             return;
         if (isWholeBlockEndpoint(focusPoint) && !reachedCentreLine(near.path, clientY))
             return;
-        // A whole unit re-enters rather than extends: its anchor's side is resolved against the
-        // new focus by the entry, where an extend would keep the unit's start as the anchor.
+        // A whole-block range re-enters rather than extends: entering picks the anchor's side
+        // against the new focus, where extending would keep the block's start as the anchor.
         if (!ctx.selection.isCrossBlock || ctx.selection.wholeUnitPath) {
             ctx.selection.enterCrossBlock(anchorPoint, focusPoint);
         }
@@ -48,10 +51,45 @@ export function installDragListener(ctx, anchorPoint, down) {
             ctx.selection.extendFocus(focusPoint);
         }
     }
-    // A block with no positions inside it is in or out as a unit, and the unit joins the range
-    // once the pointer has crossed its centre line coming from the anchor's side: a sweep that
-    // merely touched its edge has not asked for it. Not reached, the last focus stands, so the
-    // range grows to the block only when the pointer commits to it.
+    // The anchor's side follows the drag's direction (the clicked span ends the range going up,
+    // starts it going down), so a direction change re-enters; a same-side move only extends.
+    let anchorAfter = null;
+    function processGranularMove(unit, near, clientX, clientY) {
+        const anchorIsChar = 'offset' in anchorPoint && !anchorPoint.cellCoordinate;
+        if (!anchorIsChar || comparePaths(near.path, anchorPoint.path) === 0) {
+            if (ctx.selection.isCrossBlock)
+                ctx.selection.collapse();
+            anchorAfter = null;
+            const offset = caretOffsetAtPoint(unit.surface, clientX, clientY);
+            if (offset === null)
+                return;
+            const span = unit.spanAround(offset);
+            unit.surface.focus({ preventScroll: true });
+            applySingleBlockRange(unit.surface, Math.min(unit.anchorSpan.start, span.start), Math.max(unit.anchorSpan.end, span.end));
+            return;
+        }
+        const focusPoint = near.endpointHere();
+        if (!focusPoint)
+            return;
+        if (isWholeBlockEndpoint(focusPoint) && !reachedCentreLine(near.path, clientY))
+            return;
+        const after = comparePaths(near.path, anchorPoint.path) > 0;
+        const focus = isWholeBlockEndpoint(focusPoint)
+            ? focusPoint
+            : unit.expandFocus(focusPoint, after ? 'after' : 'before');
+        if (!ctx.selection.isCrossBlock || anchorAfter !== after) {
+            anchorAfter = after;
+            ctx.selection.enterCrossBlock({
+                path: anchorPoint.path.slice(),
+                offset: after ? unit.anchorSpan.start : unit.anchorSpan.end
+            }, focus);
+        }
+        else {
+            ctx.selection.extendFocus(focus);
+        }
+    }
+    // A block with no positions inside joins the range only once the pointer crosses its centre
+    // line from the anchor's side; a sweep that merely touches its edge has not asked for it.
     function reachedCentreLine(path, clientY) {
         const box = ctx.getBlockElByPath(path)?.getBoundingClientRect();
         if (!box)
@@ -59,16 +97,13 @@ export function installDragListener(ctx, anchorPoint, down) {
         const middle = box.top + box.height / 2;
         return comparePaths(anchorPoint.path, path) < 0 ? clientY >= middle : clientY <= middle;
     }
-    // A whole-block anchor (a table, an equation) has nothing to paint natively either, and a range
-    // that only appears once the pointer reaches ANOTHER block reads as a drag that does nothing.
-    // The block is taken whole the moment the pointer moves, as the unit the state stores and the
-    // overlay paints (`wholeUnitPath`); a pointer returning from outside takes it whole again.
+    // A whole-block anchor (a table, an equation) has nothing to paint natively, so the block is
+    // taken whole the moment the pointer moves, or the drag would look like it does nothing.
     function takeAnchorBlockWhole() {
         if (ctx.selection.wholeUnitPath)
             return;
-        // Both ends whole: the pointer's position INSIDE the block is not a rectangle to grow (a
-        // press beside a table dragged up over it would otherwise select the rows below the
-        // pointer, the opposite of the sweep). The block is the unit until the drag leaves it.
+        // Both ends whole: a click beside a table dragged up over it would otherwise select the
+        // rows below the pointer, the opposite of the sweep.
         ctx.selection.enterCrossBlock(anchorPoint, {
             path: anchorPoint.path.slice(),
             wholeBlock: true
@@ -87,8 +122,8 @@ export function installDragListener(ctx, anchorPoint, down) {
         blockEl.focus({ preventScroll: true });
         applySingleBlockRange(blockEl, Math.min(anchorPoint.offset, focusPoint.offset), Math.max(anchorPoint.offset, focusPoint.offset));
     }
-    // Pointer may land on a scrollable element directly (the table's `.table-block` edge), so
-    // search from `target` itself, not its parent.
+    // The pointer may land on a scrollable element directly (the table's `.table-block` edge),
+    // so the search starts from `target` itself, not its parent.
     function scrollableSelfOrAncestor(target) {
         let cur = target;
         while (cur && cur !== ctx.editorRoot) {
@@ -122,24 +157,21 @@ export function installDragListener(ctx, anchorPoint, down) {
         lifetimeSignal: ctx.lifetimeSignal
     });
 }
-/**
- * Plant a collapsed native caret in the focus block as a paste/key-dispatch anchor; without it
- * Chromium routes paste events to <body>. The highlight still comes from SelectionOverlay.
- */
+/** Plants a collapsed native caret in the focus block so paste and key events have a target;
+ *  without it Chromium routes paste events to <body>. */
 function parkCaretInFocusBlock(ctx) {
     const focus = ctx.selection.focus;
     if (!focus)
         return;
-    // A whole unit has no text node for a caret: focus parks on the editor root, whose keydown
-    // and clipboard arms serve a custom range (as they do for a windowed-out block), with no
-    // native range left behind for the browser to act on.
+    // A whole-block range has no text node for a caret, so the editor root takes focus and its
+    // keydown and clipboard handlers serve the range.
     if (ctx.selection.wholeUnitPath) {
         clearNativeSelection();
         ctx.editorRoot.focus({ preventScroll: true });
         return;
     }
     // A drag ending inside a table leaves a focus addressing the table block by cell index; the
-    // landing is the cell that actually holds a caret.
+    // caret goes in the cell that actually holds one.
     const landing = ctx.selection.cellLandingFor(focus);
     const blockEl = ctx.getBlockElByPath(landing.path);
     if (!blockEl)

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

@@ -1,8 +1,8 @@
 /**
- * Where a caret can live BETWEEN two sibling blocks: the boundaries no block's own editing
- * surface can reach, read off the kinds' `gapEdges` declarations. Eligibility is pure — doc
- * in, boolean out; `tryGapStop` is the one seam that turns it into an arrival.
- * The gap is deliberately not a `SelectionPoint`: it is never a cross-block endpoint.
+ * Where a caret can sit between two sibling blocks: the boundaries no block's own editable
+ * element can reach, read off the kinds' `gapEdges`. The eligibility checks are pure (document
+ * in, boolean out); `tryGapStop` is the one call that places the caret. A gap is deliberately
+ * not a `SelectionPoint`: it is never a cross-block endpoint.
  */
 import type { DocumentView, NodeView } from '../core/node-views';
 import { type PresentationMode } from '../presentation-mode';
@@ -12,36 +12,25 @@ export interface GapCaretPosition {
     parentPath: number[];
     index: number;
 }
-/**
- * A boundary is eligible when every block facing it declares that edge — an unregistered or
- * undeclared kind refuses on its side. The root's trailing boundary is excluded: the
- * move-past-end append (`editor-actions/focus/focus.ts`) already owns it.
- */
+/** A boundary is eligible when every block facing it declares that edge. The root's trailing
+ *  boundary is excluded, since the move-past-end append already handles it. */
 export declare function gapEligibleAt(doc: DocumentView, parentPath: number[], index: number): boolean;
-/**
- * The same rule for a scope that already holds its own children — the renderer, which has them
- * in hand and no path to resolve. `ownsTrailingBoundary` is false for the root, whose trailing
- * boundary belongs to the move-past-end append.
- */
+/** The same rule for a caller that already has the children and no path to resolve;
+ *  `ownsTrailingBoundary` is false for the root. */
 export declare function gapEligibleAmong(children: readonly NodeView[], index: number, ownsTrailingBoundary: boolean): boolean;
-/**
- * The children a gap could live between at `parentPath`, or null when that path names no
- * scope a BlockList renders. Shared with the undo restore road, so a drifted path cannot
- * park a caret somewhere nothing would paint it.
- */
+/** The children a gap could sit between at `parentPath`, or null when that path names no child
+ *  list a BlockList renders, so a stale path cannot put a caret where nothing paints it. */
 export declare function gapScopeChildren(doc: DocumentView, parentPath: number[]): readonly NodeView[] | null;
-/** What an arrival needs beyond the boundary itself. Getters, so a bound stop reads live. */
+/** What placing a gap caret needs beyond the boundary itself. Its reads are getters, so a stop
+ *  bound early sees live values. */
 export interface GapStopScope {
     getDoc: () => DocumentView;
     selection: SelectionState;
-    getPresentationMode?: () => PresentationMode;
+    getPresentationMode: () => PresentationMode;
 }
-/**
- * Whether an arriving gesture may park here. Reading mode never may: it has no caret at
- * all, so the gesture keeps its old landing. A caller that must act BETWEEN the decision
- * and the landing asks this, then goes through the door itself.
- */
+/** Whether a gesture may put the caret in this gap; reading mode has no caret, so never. A caller
+ *  that must act between the decision and the placement asks this, then calls `placeGapCaret`. */
 export declare function canGapStop(scope: GapStopScope, parentPath: number[], boundaryIndex: number): boolean;
-/** Park the caret at an eligible `boundaryIndex`, reporting whether it did — so a
- *  traversal can stop instead of entering its target. */
+/** Puts the caret at an eligible `boundaryIndex` and reports whether it did, so a traversal
+ *  can stop instead of entering its target. */
 export declare function tryGapStop(scope: GapStopScope, parentPath: number[], boundaryIndex: number): boolean;