@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/selection/keyboard-extend.d.ts

@@ -1,44 +1,31 @@
-/** Cross-block keyboard extension and collapse. Pure helpers over SelectionState. */
+/** Cross-block keyboard extension and collapse: `SelectionState` writes plus the native caret. */
 import type { SelectionState } from './selection-state.svelte';
+import type { SelectedWidgetHandle, SelectedWidgetRange, SelectionPoint } from './primitives';
 import type { Document } from '../core/nodes';
-import type { BlockComponent } from '../block-component';
+import type { GrammarView } from '../schema/block-openers';
+import type { CaretLanding } from './caret-landing';
 import type { BlockElLookup } from '../editor-keys';
-/**
- * Collapse to start/end, restore a native caret, exit cross-block mode. `revealPath` mounts an
- * off-window target first. A cell-coordinate target's offset is a cell index, not a char
- * offset, so the caret lands at the cell's edge via the cell ref.
- */
-export declare function collapseCrossBlock(selection: SelectionState, to: 'start' | 'end', doc: Document, getBlockElByPath: (path: number[]) => HTMLElement | null, revealPath: (path: number[]) => Promise<BlockComponent | null>): Promise<void>;
-/**
- * Scroll the focus block into view when mounted. Does not itself reveal a windowed-out block:
- * the doc-edge extend reveals its endpoint via `revealActiveEndpoint` first, and a single-step
- * Shift+Arrow extend lands adjacent to the mounted window.
- */
-export declare function scrollFocusBlockIntoView(selection: SelectionState, getBlockElByPath: (path: number[]) => HTMLElement | null): void;
-/**
- * Extend focus to the next leaf in document order (Shift+ArrowDown / Shift+ArrowRight leaving
- * the block), entering cross-block mode if needed. Returns true if focus moved. `axis` =
- * 'vertical' skips vertically-transparent leaves — a range covers one either way, so unlike a
- * collapsed caret it needs no object stop; 'horizontal' lands unconditionally so an image-only
- * paragraph is selectable in one step.
- */
-export declare function extendFocusToNextBlock(selection: SelectionState, doc: Document, currentBlockEl: HTMLElement, currentBlockPath: number[], axis?: 'horizontal' | 'vertical', getBlockElByPath?: BlockElLookup): boolean;
-/**
- * Extend focus to the previous leaf (Shift+ArrowUp / Shift+ArrowLeft). `side` = 'end' for
- * ArrowLeft (cross the boundary by one char), 'start' for ArrowUp (select the whole previous
- * line, matching native). The vertical path skips vertically-transparent leaves.
- */
-export declare function extendFocusToPreviousBlock(selection: SelectionState, doc: Document, currentBlockEl: HTMLElement, currentBlockPath: number[], side?: 'start' | 'end', getBlockElByPath?: BlockElLookup): boolean;
-/**
- * Extend focus to the document edge (Mod+Shift+Home / Mod+Shift+End). A transparent edge
- * leaf is bypassed for the nearest text-bearing one, matching the cross-block extension path.
- */
-export declare function extendFocusToDocEdge(selection: SelectionState, doc: Document, currentBlockEl: HTMLElement, currentBlockPath: number[], to: 'start' | 'end', getBlockElByPath?: BlockElLookup): boolean;
-/** Select the entire document as a cross-block range (second Ctrl+A press). */
+import type { ScrollOwner } from '../cursor/scroll-owner';
+/** Collapses a cross-block range to its start or end and puts the caret back there as a stored
+ *  byte, brought into view, mounting a windowed-out target and never opening a closed body. */
+export declare function collapseCrossBlock(selection: SelectionState, to: 'start' | 'end', doc: Document, restore: CaretLanding['restore']): Promise<void>;
+/** Scrolls the focus block into view if mounted, without mounting it: a document-edge extend
+ *  mounts its endpoint first, and one Shift+Arrow step lands beside the mounted range. */
+export declare function scrollFocusBlockIntoView(selection: SelectionState, scroll: Pick<ScrollOwner, 'place'>): void;
+/** Extends focus to the next leaf a caret can reach. The vertical axis skips leaves the caret
+ *  passes over (an image-only paragraph); the horizontal stops on each, so it stays selectable. */
+export declare function extendFocusToNextBlock(selection: SelectionState, doc: Document, grammar: GrammarView, currentBlockEl: HTMLElement, currentBlockPath: number[], axis?: 'horizontal' | 'vertical', getBlockElByPath?: BlockElLookup): boolean;
+/** Extends focus to the previous leaf: `'end'` crosses the boundary by one character, `'start'`
+ *  takes the whole previous line as native ArrowUp does, skipping leaves the caret passes over. */
+export declare function extendFocusToPreviousBlock(selection: SelectionState, doc: Document, grammar: GrammarView, currentBlockEl: HTMLElement, currentBlockPath: number[], side?: 'start' | 'end', getBlockElByPath?: BlockElLookup): boolean;
+/** Extends focus to the document edge; a transparent edge leaf is bypassed for the nearest
+ *  text-bearing one, as the one-step extension does. */
+export declare function extendFocusToDocEdge(selection: SelectionState, doc: Document, grammar: GrammarView, currentBlockEl: HTMLElement, currentBlockPath: number[], to: 'start' | 'end', getBlockElByPath?: BlockElLookup): boolean;
+/** Selects the entire document as a cross-block range (the second Ctrl+A). */
 export declare function selectWholeDocument(selection: SelectionState, doc: Document, getBlockElByPath?: (path: number[]) => HTMLElement | null): boolean;
-/**
- * Shift+click on a block: extend the cross-block selection, or enter cross-block mode using the
- * previously focused block's caret as the anchor. False when no anchor could be recovered, or
- * the click stayed within the same block (native shift-click handles that).
- */
-export declare function handleShiftClick(selection: SelectionState, clickedBlockEl: HTMLElement, clickedBlockPath: number[], clickedX: number, clickedY: number, previouslyFocusedBlockEl: HTMLElement | null, previouslyFocusedBlockPath: number[] | null): boolean;
+/** Shift+click on a block: extends the range, grows one from an image selected whole, or enters
+ *  cross-block mode from the last caret. False for a same-block click, left to the browser. */
+export declare function handleShiftClick(selection: SelectionState, clickedBlockEl: HTMLElement, clickedBlockPath: number[], clickedX: number, clickedY: number, previouslyFocusedBlockEl: HTMLElement | null, previouslyFocusedBlockPath: number[] | null, selectedWidget: SelectedWidgetHandle): boolean;
+/** The edge of a selected widget a shift-click grows from: the one away from the click, so the
+ *  range covers the widget and everything up to the click. */
+export declare function widgetShiftAnchor(widget: SelectedWidgetRange, press: SelectionPoint): SelectionPoint;

package/dist/selection/keyboard-extend.js

@@ -1,16 +1,14 @@
-/** Cross-block keyboard extension and collapse. Pure helpers over SelectionState. */
+/** Cross-block keyboard extension and collapse: `SelectionState` writes plus the native caret. */
 import { isVerticallyTransparentNode } from '../core/inline/transparency';
-import { readNativeCaretInBlock, applyCollapsedCaret, focusCollapsedCaret, applySingleBlockRange, clearNativeSelection } from './native-bridge';
+import { readNativeCaretInBlock, applyCollapsedCaret, applySingleBlockRange, clearNativeSelection } from './native-bridge';
 import { offsetFromViewportPoint } from '../cursor/point-offset';
-import { nextPath, previousPath, firstPath, lastPath, firstLeafAtOrAfter, lastLeafAtOrBefore, findCellPathForElement } from './path-lookup';
+import { firstPath, lastPath, firstCaretLeaf, lastCaretLeaf, nextCaretPath, previousCaretPath, findCellPathForElement } from './path-lookup';
 import { nodeAt } from '../tree-operations/node-primitives';
-import { comparePaths, isStrictAncestorOf, pathsEqual } from './path-math';
+import { comparePaths, pathsEqual } from './path-math';
 import { displayLength } from '../core/lines';
 // ── Enter / Collapse / Scroll ──────────────────────────────────────────────
-/**
- * Enter cross-block mode on a keyboard extension (Shift+Arrow leaving a block). Captures the
- * native caret as both anchor and focus; the caller immediately extendFocus()es to the target.
- */
+/** Enters cross-block mode on a Shift+Arrow leaving a block, with the native caret as both
+ *  anchor and focus; the caller extends the focus right after. */
 function enterCrossBlockFromKeyboard(selection, currentBlockEl, currentBlockPath) {
     const anchorPoint = readNativeCaretInBlock(currentBlockEl, currentBlockPath);
     if (!anchorPoint)
@@ -19,52 +17,37 @@ function enterCrossBlockFromKeyboard(selection, currentBlockEl, currentBlockPath
         path: anchorPoint.path.slice(),
         offset: anchorPoint.offset
     });
-    // Collapse (not clear) so the focus block retains a caret, or Chromium retargets clipboard
-    // events to <body> (same rule as `parkCaretInFocusBlock`). Best-effort: an endpoint hosting
-    // no text position gets no caret, which is why components/editor-root-clipboard.ts exists.
+    // A collapsed caret stays in the focus block, or Chromium sends clipboard events to <body>;
+    // an endpoint with no text position gets none, and `editor-root-clipboard.ts` covers it.
     applyCollapsedCaret(currentBlockEl, anchorPoint);
     return true;
 }
-/**
- * Collapse to start/end, restore a native caret, exit cross-block mode. `revealPath` mounts an
- * off-window target first. A cell-coordinate target's offset is a cell index, not a char
- * offset, so the caret lands at the cell's edge via the cell ref.
- */
-export async function collapseCrossBlock(selection, to, doc, getBlockElByPath, revealPath) {
+/** Collapses a cross-block range to its start or end and puts the caret back there as a stored
+ *  byte, brought into view, mounting a windowed-out target and never opening a closed body. */
+export async function collapseCrossBlock(selection, to, doc, restore) {
     const target = to === 'start' ? selection.start : selection.end;
     if (!target)
         return;
     selection.collapse();
     clearNativeSelection();
-    // The cell landing seats at the cell's own edge; from there it takes the SAME seat as a
-    // prose leaf. Seating through the cell's own focus door instead would skip the collapse
-    // ceremony, and the byte typed at the arrival would join the construct the cell opens with
-    // rather than land in front of it. Only the END side overrides the landing's own offset.
+    // A cell target takes the text-leaf caret path: the cell's own `focus` skips the collapse
+    // steps, and a byte typed there would join the construct the cell opens with.
     const landing = selection.cellLandingFor(target);
     const point = to === 'end' && !pathsEqual(landing.path, target.path)
         ? { path: landing.path, offset: leafOffsetEnd(doc, landing.path) }
         : landing;
-    // The landable clamp (a caret may not sit past a hidden run) lives in applyCollapsedCaret.
-    await revealPath(landing.path);
-    focusCollapsedCaret(getBlockElByPath, point);
+    await restore({ anchor: point, focus: point }, { reveal: 'into-view' });
 }
-/**
- * Scroll the focus block into view when mounted. Does not itself reveal a windowed-out block:
- * the doc-edge extend reveals its endpoint via `revealActiveEndpoint` first, and a single-step
- * Shift+Arrow extend lands adjacent to the mounted window.
- */
-export function scrollFocusBlockIntoView(selection, getBlockElByPath) {
-    if (!selection.focus)
-        return;
-    const blockEl = getBlockElByPath(selection.focus.path);
-    blockEl?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+/** Scrolls the focus block into view if mounted, without mounting it: a document-edge extend
+ *  mounts its endpoint first, and one Shift+Arrow step lands beside the mounted range. */
+export function scrollFocusBlockIntoView(selection, scroll) {
+    if (selection.focus) {
+        void scroll.place(selection.focus.path, { block: 'nearest', hold: false }).scroll();
+    }
 }
 // ── Keyboard Extension ─────────────────────────────────────────────────────
-/**
- * Move the cross-block focus to `target`, or restore the resulting single-block range natively
- * when the seam collapses (focus contracted back onto the anchor's prose leaf). Keyboard entry
- * parks only a collapsed caret, so the range must be re-established here to stay visible.
- */
+/** Moves the cross-block focus to `target`, or re-creates the range natively when the focus is
+ *  back on the anchor's block, since keyboard entry left only a collapsed caret there. */
 function extendFocusOrRestore(selection, target, offset, getBlockElByPath) {
     const anchor = selection.anchor;
     selection.extendFocus({ path: target, offset });
@@ -76,17 +59,12 @@ function extendFocusOrRestore(selection, target, offset, getBlockElByPath) {
     blockEl.focus();
     applySingleBlockRange(blockEl, Math.min(anchor.offset, offset), Math.max(anchor.offset, offset));
 }
-/**
- * Extend focus to the next leaf in document order (Shift+ArrowDown / Shift+ArrowRight leaving
- * the block), entering cross-block mode if needed. Returns true if focus moved. `axis` =
- * 'vertical' skips vertically-transparent leaves — a range covers one either way, so unlike a
- * collapsed caret it needs no object stop; 'horizontal' lands unconditionally so an image-only
- * paragraph is selectable in one step.
- */
-export function extendFocusToNextBlock(selection, doc, currentBlockEl, currentBlockPath, axis = 'horizontal', getBlockElByPath) {
+/** Extends focus to the next leaf a caret can reach. The vertical axis skips leaves the caret
+ *  passes over (an image-only paragraph); the horizontal stops on each, so it stays selectable. */
+export function extendFocusToNextBlock(selection, doc, grammar, currentBlockEl, currentBlockPath, axis = 'horizontal', getBlockElByPath) {
     const leafTarget = axis === 'vertical'
-        ? firstNonTransparentLeafAfter(doc, currentBlockPath)
-        : firstLeafAfter(doc, currentBlockPath);
+        ? firstNonTransparentLeafAfter(doc, grammar, currentBlockPath)
+        : nextCaretPath(doc, currentBlockPath);
     if (!leafTarget)
         return false;
     if (!selection.isCrossBlock) {
@@ -96,15 +74,12 @@ export function extendFocusToNextBlock(selection, doc, currentBlockEl, currentBl
     extendFocusOrRestore(selection, leafTarget, 0, getBlockElByPath);
     return true;
 }
-/**
- * Extend focus to the previous leaf (Shift+ArrowUp / Shift+ArrowLeft). `side` = 'end' for
- * ArrowLeft (cross the boundary by one char), 'start' for ArrowUp (select the whole previous
- * line, matching native). The vertical path skips vertically-transparent leaves.
- */
-export function extendFocusToPreviousBlock(selection, doc, currentBlockEl, currentBlockPath, side = 'end', getBlockElByPath) {
+/** Extends focus to the previous leaf: `'end'` crosses the boundary by one character, `'start'`
+ *  takes the whole previous line as native ArrowUp does, skipping leaves the caret passes over. */
+export function extendFocusToPreviousBlock(selection, doc, grammar, currentBlockEl, currentBlockPath, side = 'end', getBlockElByPath) {
     const leafTarget = side === 'start'
-        ? lastNonTransparentLeafBefore(doc, currentBlockPath)
-        : lastLeafBefore(doc, currentBlockPath);
+        ? lastNonTransparentLeafBefore(doc, grammar, currentBlockPath)
+        : previousCaretPath(doc, currentBlockPath);
     if (!leafTarget)
         return false;
     if (!selection.isCrossBlock) {
@@ -115,18 +90,16 @@ export function extendFocusToPreviousBlock(selection, doc, currentBlockEl, curre
     extendFocusOrRestore(selection, leafTarget, offset, getBlockElByPath);
     return true;
 }
-/**
- * Extend focus to the document edge (Mod+Shift+Home / Mod+Shift+End). A transparent edge
- * leaf is bypassed for the nearest text-bearing one, matching the cross-block extension path.
- */
-export function extendFocusToDocEdge(selection, doc, currentBlockEl, currentBlockPath, to, getBlockElByPath) {
-    const edge = to === 'start' ? firstPath(doc) : lastPath(doc);
+/** Extends focus to the document edge; a transparent edge leaf is bypassed for the nearest
+ *  text-bearing one, as the one-step extension does. */
+export function extendFocusToDocEdge(selection, doc, grammar, currentBlockEl, currentBlockPath, to, getBlockElByPath) {
+    const edge = to === 'start' ? firstCaretLeaf(doc, [0]) : lastCaretLeaf(doc, [doc.children.length - 1]);
     if (!edge)
         return false;
-    const target = isTransparent(doc, edge)
+    const target = isTransparent(doc, grammar, edge)
         ? to === 'start'
-            ? firstNonTransparentLeafFrom(doc, edge)
-            : lastNonTransparentLeafFrom(doc, edge)
+            ? firstNonTransparentLeafFrom(doc, grammar, edge)
+            : lastNonTransparentLeafFrom(doc, grammar, edge)
         : edge;
     if (!target)
         return false;
@@ -138,16 +111,18 @@ export function extendFocusToDocEdge(selection, doc, currentBlockEl, currentBloc
     extendFocusOrRestore(selection, target, offset, getBlockElByPath);
     return true;
 }
-/** Select the entire document as a cross-block range (second Ctrl+A press). */
+/** Selects the entire document as a cross-block range (the second Ctrl+A). */
 export function selectWholeDocument(selection, doc, getBlockElByPath) {
+    // Not the caret-reachable order: the range has to cover a closed container's hidden body, so
+    // that a delete or a copy of the whole document takes it too.
     const first = firstPath(doc);
     const last = lastPath(doc);
     if (!first || !last)
         return false;
     const lastOffset = leafOffsetEnd(doc, last);
     selection.enterCrossBlock({ path: first, offset: 0 }, { path: last, offset: lastOffset });
-    // A single prose leaf (whole doc is one block) has no cross-block state to paint; the seam
-    // refuses it. Select natively so a 2nd Ctrl+A on a one-block doc doesn't deselect.
+    // A one-block document has no cross-block range to paint and `enterCrossBlock` refuses it,
+    // so select natively; otherwise a second Ctrl+A would deselect.
     if (!selection.isCustomRendered) {
         selection.collapse();
         const blockEl = getBlockElByPath?.(first);
@@ -157,8 +132,8 @@ export function selectWholeDocument(selection, doc, getBlockElByPath) {
         }
         return true;
     }
-    // Paste-dispatch anchor, see enterCrossBlockFromKeyboard. A table focus normalizes to the
-    // table block, whose wrapper holds no caret, so park in its deep cell.
+    // A collapsed caret for paste dispatch, as in `enterCrossBlockFromKeyboard`. A table focus
+    // names the table block, whose wrapper holds no caret, so the caret goes in the cell.
     const focus = selection.focus;
     const parkPoint = focus && selection.cellLandingFor(focus);
     const focusBlockEl = parkPoint ? getBlockElByPath?.(parkPoint.path) : null;
@@ -169,12 +144,14 @@ export function selectWholeDocument(selection, doc, getBlockElByPath) {
     return true;
 }
 // ── Shift+Click ────────────────────────────────────────────────────────────
-/**
- * Shift+click on a block: extend the cross-block selection, or enter cross-block mode using the
- * previously focused block's caret as the anchor. False when no anchor could be recovered, or
- * the click stayed within the same block (native shift-click handles that).
- */
-export function handleShiftClick(selection, clickedBlockEl, clickedBlockPath, clickedX, clickedY, previouslyFocusedBlockEl, previouslyFocusedBlockPath) {
+/** Shift+click on a block: extends the range, grows one from an image selected whole, or enters
+ *  cross-block mode from the last caret. False for a same-block click, left to the browser. */
+export function handleShiftClick(selection, clickedBlockEl, clickedBlockPath, clickedX, clickedY, previouslyFocusedBlockEl, previouslyFocusedBlockPath, selectedWidget) {
+    // While an image is selected whole there is no caret to grow from, so the image is the
+    // anchor; the click ends that selection either way, as a range and it never coexist.
+    const widget = selectedWidget.range();
+    if (widget)
+        selectedWidget.clear();
     const clickOffset = offsetFromViewportPoint(clickedBlockEl, clickedX, clickedY);
     if (clickOffset === null)
         return false;
@@ -183,71 +160,71 @@ export function handleShiftClick(selection, clickedBlockEl, clickedBlockPath, cl
         selection.extendFocus(focusPoint);
         return true;
     }
+    if (widget) {
+        const anchor = widgetShiftAnchor(widget, focusPoint);
+        if (comparePaths(anchor.path, focusPoint.path) === 0) {
+            applySingleBlockRange(clickedBlockEl, anchor.offset, focusPoint.offset);
+            return true;
+        }
+        selection.enterCrossBlock(anchor, focusPoint);
+        applyCollapsedCaret(clickedBlockEl, focusPoint);
+        return true;
+    }
     if (!previouslyFocusedBlockEl || !previouslyFocusedBlockPath)
         return false;
-    // The anchor path comes from the DOM, and no path host exists below a table, so a caret
-    // parked in a cell would carry the TABLE's path with a char offset. The endpoint seam can't
-    // tell that from a cell index, so deepen to the cell here and let the seam convert.
+    // Nothing below a table carries a path, so a caret in a cell would read as the table's path
+    // with a character offset, which the endpoint snap can't tell from a cell index.
     const anchorPath = findCellPathForElement(previouslyFocusedBlockEl) ?? previouslyFocusedBlockPath;
     const anchor = readNativeCaretInBlock(previouslyFocusedBlockEl, anchorPath);
     if (!anchor)
         return false;
-    // Same-block — native selection already produced a single-block range.
+    // Same block: the browser's own shift-click already made the range.
     if (comparePaths(anchor.path, focusPoint.path) === 0)
         return false;
     selection.enterCrossBlock(anchor, focusPoint);
-    // Paste-dispatch anchor (see enterCrossBlockFromKeyboard); the click default isn't relied on.
+    // A collapsed caret for paste dispatch (see `enterCrossBlockFromKeyboard`); the click's
+    // default is not relied on.
     applyCollapsedCaret(clickedBlockEl, focusPoint);
     return true;
 }
-// ── Internal ───────────────────────────────────────────────────────────────
-/** First leaf reachable from `fromPath` going forward (descend or step). */
-function firstLeafAfter(doc, fromPath) {
-    const next = nextPath(doc, fromPath);
-    return next ? firstLeafAtOrAfter(doc, next) : null;
-}
-/** Last leaf reachable from `fromPath` going backward (descend or step). */
-function lastLeafBefore(doc, fromPath) {
-    // previousPath is doc-order (ancestor-before-descendant), so a first-child leaf's "previous"
-    // is its own container, and descending into that ancestor's LAST leaf would move the walk
-    // forward. Skip ancestors until a genuinely preceding subtree is reached.
-    let prev = previousPath(doc, fromPath);
-    while (prev && isStrictAncestorOf(prev, fromPath))
-        prev = previousPath(doc, prev);
-    return prev ? lastLeafAtOrBefore(doc, prev) : null;
+/** The edge of a selected widget a shift-click grows from: the one away from the click, so the
+ *  range covers the widget and everything up to the click. */
+export function widgetShiftAnchor(widget, press) {
+    const order = comparePaths(press.path, widget.path);
+    const pressAfter = order > 0 || (order === 0 && press.offset > widget.start);
+    return { path: widget.path.slice(), offset: pressAfter ? widget.start : widget.end };
 }
-function isTransparent(doc, path) {
+// ── Internal ───────────────────────────────────────────────────────────────
+function isTransparent(doc, grammar, path) {
     const node = nodeAt(doc, path);
     // nodeAt returns the Document for an empty path; narrow it out (Document has no `raw`).
-    return node !== null && 'raw' in node && isVerticallyTransparentNode(node);
+    return node !== null && 'raw' in node && isVerticallyTransparentNode(node, grammar);
 }
-function firstNonTransparentLeafAfter(doc, fromPath) {
-    let leaf = firstLeafAfter(doc, fromPath);
-    while (leaf && isTransparent(doc, leaf)) {
-        leaf = firstLeafAfter(doc, leaf);
+function firstNonTransparentLeafAfter(doc, grammar, fromPath) {
+    let leaf = nextCaretPath(doc, fromPath);
+    while (leaf && isTransparent(doc, grammar, leaf)) {
+        leaf = nextCaretPath(doc, leaf);
     }
     return leaf;
 }
-function lastNonTransparentLeafBefore(doc, fromPath) {
-    let leaf = lastLeafBefore(doc, fromPath);
-    while (leaf && isTransparent(doc, leaf)) {
-        leaf = lastLeafBefore(doc, leaf);
+function lastNonTransparentLeafBefore(doc, grammar, fromPath) {
+    let leaf = previousCaretPath(doc, fromPath);
+    while (leaf && isTransparent(doc, grammar, leaf)) {
+        leaf = previousCaretPath(doc, leaf);
     }
     return leaf;
 }
-/**
- * Doc-edge resolver: start AT the edge leaf and step inward to a text-bearing leaf. Distinct
- * from the leafAfter/leafBefore walkers, which step away from `fromPath`.
- */
-function firstNonTransparentLeafFrom(doc, startPath) {
-    if (!isTransparent(doc, startPath))
+/** Starts at the edge leaf itself and steps inward, unlike `nextCaretPath` and
+ *  `previousCaretPath`, which step away from their start. */
+function firstNonTransparentLeafFrom(doc, grammar, startPath) {
+    if (!isTransparent(doc, grammar, startPath))
         return startPath;
-    return firstNonTransparentLeafAfter(doc, startPath);
+    return firstNonTransparentLeafAfter(doc, grammar, startPath);
 }
-function lastNonTransparentLeafFrom(doc, startPath) {
-    if (!isTransparent(doc, startPath))
+function lastNonTransparentLeafFrom(doc, grammar, startPath) {
+    if (!isTransparent(doc, grammar, startPath))
         return startPath;
-    return lastNonTransparentLeafBefore(doc, startPath);
+    return lastNonTransparentLeafBefore(doc, grammar, startPath);
 }
 function leafOffsetEnd(doc, path) {
     const node = nodeAt(doc, path);

package/dist/selection/multi-click.d.ts

@@ -1,8 +1,8 @@
 /**
- * The click ladder past the caret: the second press of a run selects the word under it, the
- * third the surface's content, and a drag from either extends at that granularity. Owned from
- * the second press, so the browser paints nothing of its own: its word rule is per platform,
- * its walk enters atomic islands, and a marker here never joins a word.
+ * 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 type { UserScrollport } from '../cursor/scroll-ancestors';
 import type { BlockElLookup } from '../editor-keys';
@@ -12,16 +12,13 @@ export interface Span {
     start: number;
     end: number;
 }
-/**
- * [start, end) of the segment at `offset` in `text`: the word ending there when it is one, else
- * the segment starting there (whitespace or punctuation, as the engine would take). Null on
- * empty text, or on a platform with no 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 declare function wordSpanAt(text: string, offset: number): Span | null;
 /** The raw span `granularity` takes around a raw offset in `surface`; null where the word rule
  *  has nothing to read. */
 export declare function spanAround(surface: HTMLElement, granularity: ClickGranularity, rawOffset: number): Span | null;
-/** The rung a press's click count reaches; the run stays at the block rung past three. */
+/** The unit a click count selects; a run stays at the block unit past three clicks. */
 export declare function granularityForClickCount(clickCount: number): ClickGranularity | null;
 export interface MultiClickDeps {
     editorRoot: HTMLElement;
@@ -29,14 +26,12 @@ export interface MultiClickDeps {
     getBlockElByPath: BlockElLookup;
     getScrollContainer(): UserScrollport;
     lifetimeSignal?: AbortSignal;
-    /** A press outside every editable surface (the margin, a container's own box) names the
-     *  nearest block, as a single click there does; null where the press is chrome's. */
+    /** A click outside every editable element (the margin, a container's own box) names the
+     *  nearest block, as a single click there does; null when the click is on a button or handle. */
     marginBlockAt(target: EventTarget | null, clientX: number, clientY: number): number[] | null;
+    /** Whether the click landed on an inline widget the editor already holds selected whole. */
+    pressesSelectedWidget(target: EventTarget | null): boolean;
 }
-/**
- * Root listeners for the ladder. The count rides the mousedown (a pointer event carries none),
- * and the drag rides the pointerdown of the same press, so both are heard. The mousedown is
- * cancelled, never the pointerdown (that would silence the click), and so is the mouseup: the
- * browser's release seats a caret at a press that landed off a glyph, over the range just painted.
- */
+/** 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 declare function installMultiClickSelect(deps: MultiClickDeps): () => void;

package/dist/selection/multi-click.js

@@ -1,17 +1,17 @@
 /**
- * The click ladder past the caret: the second press of a run selects the word under it, the
- * third the surface's content, and a drag from either extends at that granularity. Owned from
- * the second press, so the browser paints nothing of its own: its word rule is per platform,
- * its walk enters atomic islands, and a marker here never joins a word.
+ * 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 { ambientLengthOf } from '../ambient/ambient-dom';
-import { asDomTextOffset, asRawOffset, toClampedRawOffset, toDomTextOffset } from '../cursor/coordinate-spaces';
+import { asDomTextOffset } from '../cursor/coordinate-spaces';
 import { caretOffsetAtPoint } from '../cursor/point-offset';
-import { containerDomTextLength, maskedWalkText } from '../cursor/widget-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() {
@@ -23,11 +23,8 @@ function wordSegmenter() {
     }
     return segmenter;
 }
-/**
- * [start, end) of the segment at `offset` in `text`: the word ending there when it is one, else
- * the segment starting there (whitespace or punctuation, as the engine would take). Null on
- * empty text, or on a platform with no 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)
@@ -49,31 +46,25 @@ function spanOf(segment) {
 /** 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) {
-    const ambient = ambientLengthOf(surface);
     if (granularity === 'block') {
-        return { start: 0, end: toClampedRawOffset(containerDomTextLength(surface), ambient) };
+        return { start: 0, end: rawOfWalkOffset(surface, containerDomTextLength(surface)) };
     }
-    const walk = toDomTextOffset(asRawOffset(rawOffset), ambient);
-    const span = wordSpanAt(maskedWalkText(surface), walk);
+    const span = wordSpanAt(maskedWalkText(surface), walkOffsetOfRaw(surface, rawOffset));
     if (!span)
         return null;
     return {
-        start: toClampedRawOffset(asDomTextOffset(span.start), ambient),
-        end: toClampedRawOffset(asDomTextOffset(span.end), ambient)
+        start: rawOfWalkOffset(surface, asDomTextOffset(span.start)),
+        end: rawOfWalkOffset(surface, asDomTextOffset(span.end))
     };
 }
-/** The rung a press's click count reaches; the run stays at the block rung past three. */
+/** 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 ladder. The count rides the mousedown (a pointer event carries none),
- * and the drag rides the pointerdown of the same press, so both are heard. The mousedown is
- * cancelled, never the pointerdown (that would silence the click), and so is the mouseup: the
- * browser's release seats a caret at a press that landed off a glyph, over the range just painted.
- */
+/** 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;
@@ -89,7 +80,11 @@ export function installMultiClickSelect(deps) {
         const granularity = granularityForClickCount(e.detail);
         if (!granularity || e.button !== 0 || e.shiftKey || e.ctrlKey || e.metaKey || e.altKey)
             return;
-        if (pressesInlineWidget(e.target))
+        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)
@@ -120,10 +115,10 @@ export function installMultiClickSelect(deps) {
         deps.editorRoot.removeEventListener('mouseup', onMouseUp);
     };
 }
-/** The surface a press selects in: the editable under it, else the nearest block's, the way a
- *  single click in the margin lands there. A block with no text surface is nobody's word. */
+/** 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 an island inside the editable (a list's `- ` prefix) to the surface itself.
+    // 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 };
@@ -131,7 +126,7 @@ function pressedSurface(deps, e) {
     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 press, the way a
+    // 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);
@@ -153,17 +148,16 @@ function nearestSurfaceIn(block, clientY) {
     }
     return best;
 }
-/** The path of the block a surface is the content of; null for a surface addressed some other
- *  way (a table's cell), whose drag is not a char-point drag. */
+/** 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 raw = host?.getAttribute('data-block-path');
-    if (!raw || !host?.contains(surface))
+    const path = readBlockPath(host);
+    if (!path || !host?.contains(surface))
         return null;
-    const path = JSON.parse(raw);
     return host.querySelector('[contenteditable="true"]') === surface ? path : null;
 }
-/** Paint the rung's span at the press and answer it, in raw offsets. */
+/** 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);
@@ -190,8 +184,8 @@ function createGranularity(getBlockElByPath, surface, granularity, anchorSpan) {
         }
     };
 }
-/** A press on an inline widget is that widget's own gesture (a footnote's double-click takes
- *  its whole token), so the ladder leaves it alone. */
+/** 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;
 }