@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/selection/gap-caret.js

@@ -1,29 +1,23 @@
 /**
- * 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 { isBlockNode, nodeAt } from '../tree-operations/node-primitives';
 import { tryGetBlockKindDescriptor } from '../schema/block-kind-descriptor';
 import { isReadingMode } from '../presentation-mode';
 import { placeGapCaret } from './caret-doors';
-/**
- * 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 function gapEligibleAt(doc, parentPath, index) {
     const children = gapScopeChildren(doc, parentPath);
     if (!children)
         return false;
     return gapEligibleAmong(children, index, parentPath.length > 0);
 }
-/**
- * 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 function gapEligibleAmong(children, index, ownsTrailingBoundary) {
     if (index < 0 || index > children.length)
         return false;
@@ -34,11 +28,8 @@ export function gapEligibleAmong(children, index, ownsTrailingBoundary) {
     }
     return declaresEdge(children[index - 1], 'after') && declaresEdge(children[index], 'before');
 }
-/**
- * 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 function gapScopeChildren(doc, parentPath) {
     const parent = nodeAt(doc, parentPath);
     if (!parent)
@@ -52,18 +43,15 @@ function declaresEdge(node, edge) {
     const edges = tryGetBlockKindDescriptor(node.kind)?.gapEdges;
     return edges === edge || edges === 'both';
 }
-/**
- * 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 function canGapStop(scope, parentPath, boundaryIndex) {
     if (isReadingMode(scope.getPresentationMode))
         return false;
     return gapEligibleAt(scope.getDoc(), parentPath, boundaryIndex);
 }
-/** 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 function tryGapStop(scope, parentPath, boundaryIndex) {
     if (!canGapStop(scope, parentPath, boundaryIndex))
         return false;

package/dist/selection/grid-selection.d.ts

@@ -0,0 +1,12 @@
+/**
+ * What copying a rectangle of table cells writes: a GFM sub-table for plain text and an HTML
+ * table for spreadsheets. The cell's copy and the editor root's copy both write it.
+ */
+import type { DocumentView } from '../core/node-views';
+import type { GridCoverage } from './range-coverage';
+export interface GridClipboard {
+    text: string;
+    html: string;
+}
+/** Null for a single cell, whose copy is its own text. */
+export declare function gridClipboard(doc: DocumentView, grid: GridCoverage): GridClipboard | null;

package/dist/selection/grid-selection.js

@@ -0,0 +1,22 @@
+/**
+ * What copying a rectangle of table cells writes: a GFM sub-table for plain text and an HTML
+ * table for spreadsheets. The cell's copy and the editor root's copy both write it.
+ */
+import { isBlockNode, nodeAt } from '../tree-operations/node-primitives';
+import { copyRectangleAsSubTable } from '../tree-operations/sub-table-copy';
+import { gridToHtmlTable, rectangleGrid } from '../tree-operations/table-grid-clipboard';
+/** Null for a single cell, whose copy is its own text. */
+export function gridClipboard(doc, grid) {
+    const { top, left, rows, cols } = grid.rect;
+    if (rows * cols === 1)
+        return null;
+    const table = nodeAt(doc, grid.path);
+    if (!table || !isBlockNode(table))
+        return null;
+    const from = { rowIdx: top, colIdx: left };
+    const to = { rowIdx: top + rows - 1, colIdx: left + cols - 1 };
+    return {
+        text: copyRectangleAsSubTable(table, from, to),
+        html: gridToHtmlTable(rectangleGrid(table, from, to))
+    };
+}

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

@@ -1,43 +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, mirroring single-block focus dispatch;
- * '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,16 +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, mirroring single-block focus dispatch;
- * '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) {
@@ -95,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) {
@@ -114,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;
@@ -137,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);
@@ -156,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;
@@ -168,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;
@@ -182,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

@@ -0,0 +1,37 @@
+/**
+ * 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';
+import type { SelectionState } from './selection-state.svelte';
+export type ClickGranularity = 'word' | 'block';
+export interface Span {
+    start: number;
+    end: number;
+}
+/** 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 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;
+    selection: SelectionState;
+    getBlockElByPath: BlockElLookup;
+    getScrollContainer(): UserScrollport;
+    lifetimeSignal?: AbortSignal;
+    /** 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 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;