@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/selection/nearest-block.js

@@ -1,13 +1,13 @@
 /**
  * The mounted block nearest a viewport point, and the endpoint that point addresses. A gesture
- * that must answer EVERY point — the dead-space click, a drag into the margin — resolves an
- * off-block point through here instead of declining it. The probe point never leaves the module:
- * a caller hit-testing at its own raw point gets no offset at all on a character surface.
- * Only mounted blocks are measured; a caller answering for a windowed-out tail reconciles itself.
+ * that must answer every point (a dead-space click, a drag into the margin) resolves an off-block
+ * point here: clamped into the nearest box, then handed down a container to the child level with
+ * it. Only mounted blocks are measured; a caller handling an unmounted tail does so itself.
  */
 import { clampPointIntoBox } from '../cursor/point-offset';
-import { blockAtPoint, endpointAtPoint } from './block-hit-test';
+import { blockAtPoint, endpointAtPoint, holdsOwnText } from './block-hit-test';
 import { readBlockPath } from './path-lookup';
+import { isStrictAncestorOf } from './path-math';
 /** Document order, since bands may nest and every walk over them depends on it. */
 export function measureBlocks(root) {
     return blockHosts(root).map((el) => ({
@@ -15,12 +15,8 @@ export function measureBlocks(root) {
         rect: el.getBoundingClientRect()
     }));
 }
-/**
- * The band a `y` belongs to. `belowAll` marks a point past the last band, the end-of-document
- * gesture, which lands at a trailing corner rather than under its own x. A y in a gap resolves to
- * the nearest band, so no point is left unanswered. Bands arrive in document order and may nest,
- * so containment scans forward, outermost wins.
- */
+/** The band a `y` belongs to; a y in a gap resolves to the nearest band, so no point is left
+ *  unanswered. `belowAll` marks a point past the last band, which lands at a trailing corner. */
 export function nearestBand(bands, y) {
     if (bands.length === 0)
         return null;
@@ -43,8 +39,8 @@ export function nearestBand(bands, y) {
     return { index: nearest, belowAll: false };
 }
 // ── Probing ────────────────────────────────────────────────────────────────
-/** The band's own probe point: {@link clampPointIntoBox}, except that `belowAll` takes the
- *  trailing corner — the block's last position — rather than the point's own x. */
+/** The point a band is hit-tested at: {@link clampPointIntoBox}, except that `belowAll` takes the
+ *  trailing corner (the block's last position) rather than the point's own x. */
 export function probePointIn(rect, x, y, belowAll) {
     const inside = clampPointIntoBox(rect, x, y);
     return { x: belowAll ? rect.right - 1 : inside.x, y: inside.y };
@@ -54,20 +50,43 @@ export function probePointIn(rect, x, y, belowAll) {
 export function blockNearPoint(editorRoot, clientX, clientY) {
     const direct = blockAtPoint(editorRoot, clientX, clientY);
     if (direct)
-        return addressedAt(direct, clientX, clientY);
+        return addressedAt(descendToLevelChild(editorRoot, { hit: direct, x: clientX, y: clientY }));
     const rects = blockHosts(editorRoot).map((el) => el.getBoundingClientRect());
     const band = nearestBand(rects, clientY);
     if (!band)
         return null;
     const probe = probePointIn(rects[band.index], clientX, clientY, band.belowAll);
     const hit = blockAtPoint(editorRoot, probe.x, probe.y);
-    return hit && addressedAt(hit, probe.x, probe.y);
+    return hit && addressedAt(descendToLevelChild(editorRoot, { hit, ...probe }, band.belowAll));
+}
+/** Hands a point on a container's own box (a quote's gutter, a list's indent) down to the child
+ *  level with it, at any depth; a container with its own editable row keeps an unmatched point. */
+export function descendToLevelChild(root, probed, belowAll = false) {
+    let current = probed;
+    for (;;) {
+        const { hit, x, y } = current;
+        // A grid kind resolves points inside itself through its own hooks.
+        if (hit.foreignDragHitTest || hit.caretTargetAtPoint)
+            return current;
+        const rects = blockHosts(hit.host).map((el) => el.getBoundingClientRect());
+        const band = nearestBand(rects, y);
+        if (!band)
+            return current;
+        if (holdsOwnText(hit) && !rects.some((r) => y >= r.top && y <= r.bottom))
+            return current;
+        const probe = probePointIn(rects[band.index], x, y, belowAll);
+        const next = blockAtPoint(root, probe.x, probe.y);
+        // Something drawn over the child answered instead, so the container keeps the point.
+        if (!next || !isStrictAncestorOf(hit.path, next.path))
+            return current;
+        current = { hit: next, ...probe };
+    }
 }
 // ── Internal ───────────────────────────────────────────────────────────────
-function addressedAt(hit, probeX, probeY) {
-    return { path: hit.path, endpointHere: () => endpointAtPoint(hit, probeX, probeY) };
+function addressedAt({ hit, x, y }) {
+    return { path: hit.path, endpointHere: () => endpointAtPoint(hit, x, y) };
 }
-/** The one selector for the mounted hosts, so the two walks above cannot drift apart. */
+/** The one selector for the mounted hosts, so the lookups above can't drift apart. */
 function blockHosts(root) {
     return [...root.querySelectorAll('[data-block-path]')];
 }

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

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

package/dist/selection/path-lookup.js

@@ -1,5 +1,7 @@
-/** Document-tree path navigation. Pure functions over a Document + path. */
-import { nodeAt } from '../tree-operations/node-primitives';
+/** Walks the document tree by path, and reads block paths off the DOM. */
+import { isBlockNode, nodeAt } from '../tree-operations/node-primitives';
+import { caretChildCount, isCollapsedContainer } from '../schema/reserved-chrome';
+import { TABLE_CELL_SELECTOR } from '../components/block-content-selector';
 /** Block immediately after `path` in doc order (children before siblings), else null. */
 export function nextPath(doc, path) {
     const node = nodeAt(doc, path);
@@ -65,7 +67,8 @@ export function firstLeafAtOrAfter(doc, path) {
 export function lastLeafAtOrBefore(doc, path) {
     let cur = path;
     while (cur) {
-        // Annotated: overload resolution + the `cur` reassignment below otherwise cycle inference.
+        // Annotated because overload resolution and the `cur` reassignment below otherwise make
+        // TypeScript's inference cycle.
         const node = nodeAt(doc, cur);
         if (!node)
             return null;
@@ -75,16 +78,101 @@ export function lastLeafAtOrBefore(doc, path) {
     }
     return null;
 }
-/**
- * The document path an element's own `data-block-path` carries. A plugin may own the attribute
- * with non-JSON content, so a parse failure resolves to null, never a throw.
- */
+// ── Caret-reachable order ──────────────────────────────────────────────────
+// The same order as above, but a collapsed container is only its title row, since a caret never
+// sits in its hidden body; select-all keeps the functions above, as its range covers that body.
+/** The first leaf a caret can reach at or inside `path`, or null when `path` does not resolve. */
+export function firstCaretLeaf(doc, path) {
+    return descendToCaretLeaf(doc, path, () => 0);
+}
+/** The last leaf a caret can reach at or inside `path`, or null when `path` does not resolve. */
+export function lastCaretLeaf(doc, path) {
+    return descendToCaretLeaf(doc, path, (node) => reachableChildCount(node) - 1);
+}
+/** The first caret leaf after `path` in document order, descending into it first when it has
+ *  children, as {@link nextPath} does. */
+export function nextCaretPath(doc, path) {
+    const node = nodeAt(doc, [...path]);
+    if (!node || path.length === 0)
+        return null;
+    if (reachableChildCount(node) > 0)
+        return firstCaretLeafFrom(doc, [...path, 0]);
+    return firstCaretLeafFrom(doc, [...path.slice(0, -1), path[path.length - 1] + 1]);
+}
+/** The last caret leaf before `path`'s subtree in document order; an ancestor of `path` is never
+ *  the answer. `path` need not resolve, so the position a removed block left reads the same. */
+export function previousCaretPath(doc, path) {
+    const hiding = collapsedContainerHiding(doc, path);
+    if (hiding)
+        return lastCaretLeaf(doc, [...hiding, 0]);
+    let slot = [...path];
+    while (slot.length > 0) {
+        const parentPath = slot.slice(0, -1);
+        const parent = nodeAt(doc, parentPath);
+        if (!parent)
+            return null;
+        const before = Math.min(slot[slot.length - 1], reachableChildCount(parent)) - 1;
+        if (before >= 0)
+            return lastCaretLeaf(doc, [...parentPath, before]);
+        slot = parentPath;
+    }
+    return null;
+}
+/** The first caret leaf at `slot` or after it, where `slot` may sit one past the end of its list
+ *  (the place a removed last child left). */
+export function firstCaretLeafFrom(doc, slot) {
+    const hiding = collapsedContainerHiding(doc, slot);
+    let at = hiding ? [...hiding.slice(0, -1), hiding[hiding.length - 1] + 1] : [...slot];
+    while (at.length > 0) {
+        const parentPath = at.slice(0, -1);
+        const parent = nodeAt(doc, parentPath);
+        if (!parent)
+            return null;
+        if (at[at.length - 1] < reachableChildCount(parent))
+            return firstCaretLeaf(doc, at);
+        if (parentPath.length === 0)
+            return null;
+        at = [...parentPath.slice(0, -1), parentPath[parentPath.length - 1] + 1];
+    }
+    return null;
+}
+/** The outermost collapsed container whose hidden body `path` runs through, or null. */
+export function collapsedContainerHiding(doc, path) {
+    for (let depth = 1; depth < path.length; depth++) {
+        if (path[depth] < 1)
+            continue;
+        const container = nodeAt(doc, path.slice(0, depth));
+        if (container && isBlockNode(container) && isCollapsedContainer(container)) {
+            return path.slice(0, depth);
+        }
+    }
+    return null;
+}
+function descendToCaretLeaf(doc, path, pick) {
+    const leaf = [...path];
+    let node = nodeAt(doc, leaf);
+    if (!node)
+        return null;
+    while (reachableChildCount(node) > 0) {
+        const index = pick(node);
+        leaf.push(index);
+        node = node.children[index];
+    }
+    return leaf.length > 0 ? leaf : null;
+}
+// The document root is never collapsed, and has no descriptor to ask.
+function reachableChildCount(node) {
+    return isBlockNode(node) ? caretChildCount(node) : node.children.length;
+}
+/** The path an element's own `data-block-path` carries, read in one place: a plugin may own the
+ *  attribute with content of its own, so anything but a list of numbers reads as null. */
 export function readBlockPath(el) {
     const attr = el?.getAttribute('data-block-path');
     if (!attr)
         return null;
     try {
-        return JSON.parse(attr);
+        const parsed = JSON.parse(attr);
+        return Array.isArray(parsed) && parsed.every((n) => typeof n === 'number') ? parsed : null;
     }
     catch {
         return null;
@@ -100,15 +188,10 @@ export function findBlockPathForElement(el) {
     }
     return null;
 }
-/**
- * The deep `[...tablePath, row, col]` path of an element inside a table cell. Only block hosts
- * emit `data-block-path`, so {@link findBlockPathForElement} stops at the table and returns a
- * path whose offsets are cell indices while a caret read from the same element is in characters.
- * Any producer resolving an endpoint path from the DOM must come through here. Null outside a
- * cell grid; addresses the grid by selector contract (`data-table-row-idx`, `role="cell"`).
- */
+/** The `[...tablePath, row, col]` path of an element in a table cell: only block hosts carry a
+ *  path, so a DOM-read endpoint in a cell must come through here or it reads as the table's. */
 export function findCellPathForElement(el) {
-    const cellEl = el?.closest('[role="cell"]') ?? null;
+    const cellEl = el?.closest(TABLE_CELL_SELECTOR) ?? null;
     if (!cellEl)
         return null;
     const rowEl = cellEl.closest('[data-table-row-idx]');
@@ -120,13 +203,20 @@ export function findCellPathForElement(el) {
     const rowIdx = Number(rowEl.getAttribute('data-table-row-idx'));
     if (!Number.isInteger(rowIdx))
         return null;
-    const colIdx = Array.from(rowEl.querySelectorAll(':scope > [role="cell"]')).indexOf(cellEl);
+    const colIdx = Array.from(rowEl.querySelectorAll(`:scope > ${TABLE_CELL_SELECTOR}`)).indexOf(cellEl);
     if (colIdx < 0)
         return null;
     return [...tablePath, rowIdx, colIdx];
 }
-/** The path of the editing SURFACE `el` sits in — the enclosing cell where there is one, else
- *  the enclosing block. The pairing {@link findCellPathForElement} says every producer owes. */
+/** The cell-then-block lookup {@link findCellPathForElement} requires, in one place. */
+export function findSurfaceForElement(el) {
+    const cellPath = findCellPathForElement(el);
+    if (cellPath)
+        return { path: cellPath, inCell: true };
+    const blockPath = findBlockPathForElement(el);
+    return blockPath ? { path: blockPath, inCell: false } : null;
+}
+/** {@link findSurfaceForElement} for a caller that needs only the path. */
 export function findSurfacePathForElement(el) {
-    return findCellPathForElement(el) ?? findBlockPathForElement(el);
+    return findSurfaceForElement(el)?.path ?? null;
 }

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

@@ -1,14 +1,14 @@
 /**
- * Pure predicates over CST paths, plus the `DocPath` brand home. No DOM, no document lookups.
- * The predicates take `readonly number[]`: they order any path-shaped array regardless of what
- * space it addresses, so brand-typing them to `DocPath` would force a cast at every call site.
+ * Pure predicates over CST paths, plus the `DocPath` brand. The predicates take
+ * `readonly number[]` rather than `DocPath`: they order any path-shaped array whatever it
+ * addresses, and the brand would force a cast at every call site.
  */
 declare const docPathBrand: unique symbol;
 /**
- * A path whose every prefix resolves from the document root: the dialect the commit seam
- * requires and G1.16 checks (`op.eventPath` and `snapshot.path` carry it). `asDocPath` is the
- * base mint; op families compose through `extendDocPath`/`docPathFrom` in
- * `cursor/coordinate-spaces.ts`. G1.16 stays the runtime belt for JS callers types don't bind.
+ * A path resolved from the document root, which a commit requires of `op.eventPath` and
+ * `snapshot.path`, checked at runtime for callers the types don't bind (G1.16). `asDocPath` is
+ * the base constructor; `extendDocPath` and `docPathFrom` in `cursor/coordinate-spaces.ts`
+ * build on it.
  */
 export type DocPath = number[] & {
     readonly [docPathBrand]: true;
@@ -27,9 +27,7 @@ export declare function sharedPrefixLength(a: readonly number[], b: readonly num
 export declare function lowestCommonAncestor(a: readonly number[], b: readonly number[]): number[];
 /** True if `path` is strictly between `start` and `end` in document order. */
 export declare function isPathBetween(path: readonly number[], start: readonly number[], end: readonly number[]): boolean;
-/**
- * True when path's entire subtree fits strictly inside (start, end). Stronger
- * than `walkBetween`'s doc-order "between", which includes endpoint ancestors.
- */
+/** True when `path`'s entire subtree fits strictly inside (start, end). Stronger than
+ *  `walkBetween`'s document-order "between", which includes endpoint ancestors. */
 export declare function isPathSubtreeBetween(path: readonly number[], start: readonly number[], end: readonly number[]): boolean;
 export {};

package/dist/selection/path-math.js

@@ -1,7 +1,7 @@
 /**
- * Pure predicates over CST paths, plus the `DocPath` brand home. No DOM, no document lookups.
- * The predicates take `readonly number[]`: they order any path-shaped array regardless of what
- * space it addresses, so brand-typing them to `DocPath` would force a cast at every call site.
+ * Pure predicates over CST paths, plus the `DocPath` brand. The predicates take
+ * `readonly number[]` rather than `DocPath`: they order any path-shaped array whatever it
+ * addresses, and the brand would force a cast at every call site.
  */
 export function asDocPath(indices) {
     return indices;
@@ -76,10 +76,8 @@ export function lowestCommonAncestor(a, b) {
 export function isPathBetween(path, start, end) {
     return comparePaths(path, start) > 0 && comparePaths(path, end) < 0;
 }
-/**
- * True when path's entire subtree fits strictly inside (start, end). Stronger
- * than `walkBetween`'s doc-order "between", which includes endpoint ancestors.
- */
+/** True when `path`'s entire subtree fits strictly inside (start, end). Stronger than
+ *  `walkBetween`'s document-order "between", which includes endpoint ancestors. */
 export function isPathSubtreeBetween(path, start, end) {
     return (!isStrictAncestorOf(path, start) &&
         !isStrictAncestorOf(start, path) &&

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

@@ -0,0 +1,9 @@
+/**
+ * The attribute a widget sets on an element whose pointer drags are its own gesture (a diagram's
+ * pan, a canvas's brush), so the editor's pointer handlers ignore a pointerdown inside it. It is
+ * an attribute because pointer events are delegated at the app root: a component's own
+ * `stopPropagation` runs after the editor's handler.
+ */
+/** Set on the gesture's element itself; a pointerdown on any descendant counts. */
+export declare const POINTER_GESTURE_ATTR = "data-pointer-gesture";
+export declare function claimsPointerGesture(target: EventTarget | null): boolean;

package/dist/selection/pointer-gesture.js

@@ -0,0 +1,11 @@
+/**
+ * The attribute a widget sets on an element whose pointer drags are its own gesture (a diagram's
+ * pan, a canvas's brush), so the editor's pointer handlers ignore a pointerdown inside it. It is
+ * an attribute because pointer events are delegated at the app root: a component's own
+ * `stopPropagation` runs after the editor's handler.
+ */
+/** Set on the gesture's element itself; a pointerdown on any descendant counts. */
+export const POINTER_GESTURE_ATTR = 'data-pointer-gesture';
+export function claimsPointerGesture(target) {
+    return target instanceof Element && target.closest(`[${POINTER_GESTURE_ATTR}]`) !== null;
+}

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

@@ -1,8 +1,8 @@
 /**
- * Shared pointer-drag session: the document-listener + rAF-coalescing scaffold every drag
- * lifecycle builds on. Owns the pointer-ownership filter, autoscroll wiring, and idempotent
- * teardown; callers supply the per-surface move/end behavior and the options that genuinely
- * differ. rAF here is frame-paced pointermove coalescing, not async sequencing (G4.4).
+ * The shared pointer-drag session every drag builds on: document-level listeners, one move per
+ * animation frame, the pointer-id filter, autoscroll, and a teardown that is safe to run twice.
+ * Callers supply the move and end behaviour. The rAF here coalesces pointermove events to one
+ * per frame; it is not used to sequence anything (G4.4).
  */
 import { type AutoScrollDeps } from './autoscroll';
 export interface PointerPosition {
@@ -13,29 +13,23 @@ export interface PointerDragSessionOptions {
     /** Coalesced to one call per animation frame with the latest pointer: intermediate positions
      *  are dropped, so a consumer must answer the point it gets rather than wait for a better one. */
     onMove(pointer: PointerPosition): void;
-    /**
-     * pointerup / pointercancel finalize, after the pending move flushes and the session tears
-     * down. NOT run on Escape or lifetime abort: those are pure teardowns.
-     */
+    /** Runs on pointerup or pointercancel, after the pending move flushes and the session tears
+     *  down; Escape and a lifetime abort only tear down. */
     onEnd?(reason: 'up' | 'cancel'): void;
     /** Caller cleanup, run once on every teardown path (up, cancel, Escape, abort). */
     onTeardown?(): void;
     /** Scroll targets + axis; the session supplies the live pointer and rescroll. */
     autoScroll: Pick<AutoScrollDeps, 'getTargets' | 'axis'>;
-    /**
-     * Drag/click discriminator in px: below this travel from `down` the gesture stays a click.
-     * Omit where the pointerdown already committed to a drag.
-     */
+    /** Drag/click discriminator in px: below this travel from `down` the gesture stays a click.
+     *  Omitted where the pointerdown already committed to a drag. */
     threshold?: number;
     onDragRecognized?(): void;
     /** Install a document keydown so Escape tears the session down. */
     escape?: boolean;
     /** Suppress native text selection for the drag's duration. */
     disableUserSelect?: boolean;
-    /**
-     * Aborted on editor unmount. Without it an unmount mid-drag leaks the document listeners:
-     * pointerup never fires once the originating element is gone.
-     */
+    /** Aborted on editor unmount; without it an unmount mid-drag leaks the document listeners,
+     *  since pointerup never fires once the originating element is gone. */
     lifetimeSignal?: AbortSignal;
 }
 export declare function createPointerDragSession(down: PointerEvent, opts: PointerDragSessionOptions): {

package/dist/selection/pointer-session.js

@@ -1,8 +1,8 @@
 /**
- * Shared pointer-drag session: the document-listener + rAF-coalescing scaffold every drag
- * lifecycle builds on. Owns the pointer-ownership filter, autoscroll wiring, and idempotent
- * teardown; callers supply the per-surface move/end behavior and the options that genuinely
- * differ. rAF here is frame-paced pointermove coalescing, not async sequencing (G4.4).
+ * The shared pointer-drag session every drag builds on: document-level listeners, one move per
+ * animation frame, the pointer-id filter, autoscroll, and a teardown that is safe to run twice.
+ * Callers supply the move and end behaviour. The rAF here coalesces pointermove events to one
+ * per frame; it is not used to sequence anything (G4.4).
  */
 import { createAutoScroll } from './autoscroll';
 export function createPointerDragSession(down, opts) {
@@ -41,9 +41,8 @@ export function createPointerDragSession(down, opts) {
             autoScroll.maybeStart();
         });
     }
-    // A release before the coalescing rAF runs would otherwise drop the final move (a stale drop
-    // index, or isCrossBlock false on a fast flick / pointercancel). Guard on a LIVE rAF so an
-    // already-processed move is never replayed.
+    // A release before the frame callback runs would otherwise drop the final move; the guard on
+    // a pending frame keeps an already processed move from replaying.
     function flushPendingMove() {
         if (rafId !== null && pending)
             opts.onMove(pending);

package/dist/selection/primitives.d.ts

@@ -1,10 +1,10 @@
 /**
- * Pure primitives for cross-block selection: types, document-order walking, overlay
- * classification, the delete-commit snapshot rule. No DOM, no state. Path-level predicates
- * live in `./path-math`.
+ * Pure primitives for cross-block selection: types, overlay classification of a covered range,
+ * the delete-commit snapshot rule. Path-level predicates live in `./path-math`.
  */
-import type { CommitSnapshotArg, UndoEntryMode } from '../action-contracts';
-import type { DocumentView } from '../core/node-views';
+import type { CommitSnapshotArg } from '../action-contracts';
+import type { RangeCoverage } from './range-coverage';
+import { type DocPath } from './path-math';
 import { type CellIndex, type RawOffset } from '../cursor/coordinate-spaces';
 /** Char-space endpoint: `offset` is a character index into the leaf's `raw`. */
 export interface CharSelectionPoint {
@@ -12,6 +12,26 @@ export interface CharSelectionPoint {
     offset: number;
     cellCoordinate?: false;
 }
+/** An inline widget selected whole, by the block it sits in and the byte it starts at. A snapshot:
+ *  a popover commit targets the image it opened on, and writes nothing once another holds it. */
+export interface WidgetTarget {
+    paragraphPath: number[];
+    sourceStart: number;
+    /** The caret just before the widget was selected: the edge it was entered from, and where
+     *  undo puts the caret back. */
+    preSelectOffset: number;
+}
+/** An inline widget selected whole (an image), as the raw span of the block at `path`. */
+export interface SelectedWidgetRange {
+    path: number[];
+    start: number;
+    end: number;
+}
+/** The widget selected whole, read live, and the way to end that selection. */
+export interface SelectedWidgetHandle {
+    range(): SelectedWidgetRange | null;
+    clear(): void;
+}
 /** Cell-space endpoint: `offset` is a row-major table cell index; `path` addresses the table block. */
 export interface CellSelectionPoint {
     path: number[];
@@ -19,23 +39,33 @@ export interface CellSelectionPoint {
     cellCoordinate: true;
 }
 /**
- * A single selection endpoint, discriminated on `cellCoordinate`; empty path is the
- * document root. `offset` keeps its name on both arms, and its space is the
- * discriminant's job: read it through {@link charOffsetOf} / {@link cellIndexOf}.
- * Exception: intra-table selections share the table path and carry cell-valued offsets
- * on UNFLAGGED points, established by their shared scope rather than the flag.
+ * One selection endpoint, discriminated on `cellCoordinate`; an empty path is the document
+ * root. `offset` keeps its name on both variants and the flag says which space it is in, so
+ * read it through {@link charOffsetOf} or {@link cellIndexOf}. `SelectionState` flags every
+ * point on a table path, so a host may pass plain numbers there.
  */
 export type SelectionPoint = CharSelectionPoint | CellSelectionPoint;
-/** An endpoint whose block offered no position to land on; the funnel resolves the side. */
+/** An endpoint whose block offered no position to land on; its side is resolved against the
+ *  other endpoint when the range is entered. */
 export interface WholeBlockEndpoint {
     path: number[];
     wholeBlock: true;
 }
 /**
- * What an entry path may hand the selection funnel. Only {@link SelectionPoint} is ever
- * stored, so an unresolved endpoint cannot reach a consumer.
+ * What a gesture may hand `enterCrossBlock`. Only a {@link SelectionPoint} is ever stored, so
+ * an unresolved endpoint cannot reach a consumer.
  */
 export type SelectionEndpoint = SelectionPoint | WholeBlockEndpoint;
+/** Where a caret goes after an edit: a document path, which may name a container, and an offset
+ *  into the node there, raw or one of the special caret values in `block-component.ts`. */
+export interface CaretPosition {
+    readonly path: DocPath;
+    readonly offset: number;
+}
+/** What an edit hands back for the caret: a position, or a stored selection to put back. */
+export type Landing = CaretPosition | EditorSelection;
+/** A cell endpoint: the grid's path, a row-major cell index, and the flag saying so. */
+export declare function cellPoint(path: readonly number[], cellIdx: number): CellSelectionPoint;
 export declare function isWholeBlockEndpoint(endpoint: SelectionEndpoint): endpoint is WholeBlockEndpoint;
 /**
  * Anchor/focus pair. Same path + same offset is collapsed; same path + different offsets
@@ -46,30 +76,31 @@ export interface EditorSelection {
     anchor: SelectionPoint;
     focus: SelectionPoint;
 }
-/** Offset as a char index into the leaf's `raw`. DEV-warns on a cell point, but always returns. */
+/** Whether two snapshots name the same selection. The coordinate space counts: the same
+ *  numbers as a cell index and as a character offset are different positions. */
+export declare function selectionsEqual(a: EditorSelection | null, b: EditorSelection | null): boolean;
+/** Offset as a char index into the leaf's `raw`. Warns in dev on a cell point, but always returns. */
 export declare function charOffsetOf(point: SelectionPoint, tag: string): RawOffset;
-/** Offset as a row-major table cell index. DEV-warns on a char point, but always returns. */
+/** Offset as a row-major table cell index. Warns in dev on a char point, but always returns. */
 export declare function cellIndexOf(point: SelectionPoint, tag: string): CellIndex;
-/**
- * `{start, end}` in document order: by path, then by offset when paths match. Published on the
- * consumer barrel as `normalizeSelection`, which is what a host anchors UI to. The offset tiebreak
- * is coordinate-space agnostic: two endpoints sharing a table's path carry row-major CELL indices,
- * whose order IS document order inside that table. A caller with no selection has nothing to
- * order, since `getSelection()` answers null with nothing focused and at a gap caret.
- */
+/** `{start, end}` in document order: by path, then by offset, which orders cell indices on a
+ *  shared table path too, since row-major order is document order inside the table. */
 export declare function normalize(selection: EditorSelection): {
     start: SelectionPoint;
     end: SelectionPoint;
 };
-/** A join delete rides the caller's snapshot; every other one seats undo at its own coordinate. */
-export declare function deleteSnapshot(options: {
-    undoEntry?: UndoEntryMode;
-} | undefined, path: number[], offset?: number): CommitSnapshotArg;
-/** Every block path strictly between `start` and `end`, at every nesting level. */
-export declare function walkBetween(doc: DocumentView, start: number[], end: number[]): number[][];
+/** Where undo puts the caret back after a range delete, when nothing is focused. */
+export declare function deleteSnapshot(path: number[], offset?: number): CommitSnapshotArg;
 export type BlockSelectionClass = 'outside' | 'start' | 'middle' | 'end' | 'single-block';
-/**
- * Position of a block relative to a selection, for overlay rendering. 'single-block'
- * tells the caller to delegate to the browser instead of painting.
- */
-export declare function classifyBlockForSelection(path: number[], selection: EditorSelection): BlockSelectionClass;
+/** Where a block stands in a covered range, for the overlay: 'single-block' delegates to the
+ *  browser, and a subtree the range holds whole is 'middle' with nothing inside it painting. */
+export declare function classifyBlockForSelection(path: readonly number[], coverage: RangeCoverage): BlockSelectionClass;
+/** Whether the block paints the range over its whole box, so a container's own decoration (an
+ *  alert's badge), which no child host covers, is painted too; its children then paint nothing. */
+export declare function blockPaintsWholeBox(path: readonly number[], coverage: RangeCoverage, wholeUnitPath: readonly number[] | null): boolean;
+/** The end-exclusive offsets an endpoint block measures its highlight between: a kept table
+ *  edge's cells, or its text from the start or up to the end. */
+export declare function endpointMeasureSpan(classification: BlockSelectionClass, coverage: RangeCoverage): {
+    from: number;
+    to: number;
+};