@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/cursor/sticky-measure.js

@@ -3,24 +3,24 @@
  * values are invariant to vertical scrolling inside the editor.
  */
 import { asDomTextOffset, asViewportX, toEditorX, toViewportX } from './coordinate-spaces';
-import { containerDomTextLength, findDomTextOffsetTarget } from './widget-offset';
-import { firstUsefulRect } from './visual-lines';
-// Half a line height of padding on each side of the probe line — wide enough for
-// ascender/descender variation, narrow enough to exclude the neighbouring line.
-const LINE_BAND_TOLERANCE = 0.5;
+import { containerDomTextLength, domTextOffsetAtNode, findDomTextLanding, holdsTextPast, widgetSpanContainingOffset } from './widget-offset';
+import { firstUsefulRect, neighbourCaretRect, sameLineTolerance } from './visual-lines';
 export function getCurrentCursorEditorRelativeX(el) {
     const sel = window.getSelection();
     if (!sel || sel.rangeCount === 0)
         return null;
     const range = sel.getRangeAt(0);
-    const rect = firstUsefulRect(range);
+    const rect = firstUsefulRect(range) ?? neighbourCaretRect(range);
     const viewportX = asViewportX(rect ? rect.left : el.getBoundingClientRect().left);
     return toEditorX(viewportX, editorLeftOf(el));
 }
-export function getOffsetRect(container, offset) {
-    const pos = findDomTextOffsetTarget(container, offset);
-    if (!pos)
+/** The caret's box at a DOM-walk offset, under the offset the caret would really take; a position
+ *  beside a widget borrows the widget's near edge. Null where the offset measures to nothing. */
+export function caretBoxAt(container, offset) {
+    const landing = findDomTextLanding(container, offset);
+    if (!landing)
         return null;
+    const pos = landing.position;
     const range = document.createRange();
     try {
         range.setStart(pos.node, pos.offset);
@@ -29,58 +29,68 @@ export function getOffsetRect(container, offset) {
         return null;
     }
     range.collapse(true);
-    return firstUsefulRect(range);
+    const measured = firstUsefulRect(range);
+    const rect = measured ?? neighbourCaretRect(range);
+    if (!rect)
+        return null;
+    return {
+        offset: landing.inTextAtTarget ? offset : domTextOffsetAtNode(container, pos.node, pos.offset),
+        rect,
+        borrowed: measured === null
+    };
 }
-/**
- * Offset on the first or last caret-bearing visual line whose collapsed-range rect is
- * closest to `editorRelativeX`. Linear scan — `getClientRects` left values are
- * non-monotonic on BiDi lines, so binary search is invalid. Widget-only lines are
- * transparent (their collapsed ranges return null rects); `minOffset` excludes the
- * ambient-marker prefix.
- */
-export function findOffsetNearestX(container, editorRelativeX, from, minOffset = asDomTextOffset(0)) {
-    const totalLen = containerDomTextLength(container);
+/** The offset on the first or last caret-bearing line nearest `editorRelativeX`, by linear scan
+ *  since BiDi rect lefts are non-monotonic. `minOffset` and `maxOffset` bound the answer. */
+export function findOffsetNearestX(container, editorRelativeX, from, minOffset = asDomTextOffset(0), maxOffset) {
+    const totalLen = Math.min(maxOffset ?? Infinity, containerDomTextLength(container));
     if (totalLen <= minOffset)
         return minOffset;
     const targetViewportX = toViewportX(editorRelativeX, editorLeftOf(container));
-    // Only offsets near the probed edge can be the answer, so walk inward and stop a few
-    // lines past it: the band filter below discards anything further regardless, making
-    // this identical to a full scan at O(lines-near-edge) instead of O(raw length).
+    // Only offsets near the probed edge can be the answer, so walk inward and stop past it: the
+    // band filter below discards anything further regardless.
     const forward = from === 'above';
-    const STOP_AFTER_LINES = 3;
+    const tolerance = sameLineTolerance(container);
+    const owned = createEdgeTracker(forward, (first) => STOP_AFTER_LINES * lineHeightOf(first));
+    // A caret beside a widget shows nothing, so a borrowed box sets the edge only in a block made
+    // of widgets alone, where offsets run line by line and the walk can stop past the edge's band.
+    const borrowed = holdsTextPast(container, minOffset)
+        ? null
+        : createEdgeTracker(forward, () => tolerance);
+    const walkEndsAt = (probe) => {
+        if (!probe.borrowed)
+            return owned.passes(probe.rect);
+        // Once text has set the edge, a widget box as far past it ends the walk as a text box would.
+        return owned.edge ? owned.isPast(probe.rect) : (borrowed?.passes(probe.rect) ?? false);
+    };
     const candidates = [];
-    // The probed edge's own line: min top (above) / max bottom (below), first candidate wins a tie.
-    let edgeRect = null;
-    let lineH = 0;
     for (let k = 0; k <= totalLen - minOffset; k++) {
-        const offset = asDomTextOffset(forward ? minOffset + k : totalLen - k);
-        const rect = getOffsetRect(container, offset);
-        if (!rect)
+        const target = asDomTextOffset(forward ? minOffset + k : totalLen - k);
+        // Every offset inside a widget lands beside it, where one of its boundaries measures: skip
+        // to the far boundary so the widget costs one probe.
+        const inside = widgetSpanContainingOffset(container, target);
+        if (inside) {
+            k = (forward ? inside.end - minOffset : totalLen - inside.start) - 1;
             continue;
-        if (lineH === 0)
-            lineH = Math.max(1, rect.bottom - rect.top);
-        if (edgeRect) {
-            const distancePastEdge = forward ? rect.top - edgeRect.top : edgeRect.bottom - rect.bottom;
-            if (distancePastEdge > STOP_AFTER_LINES * lineH)
-                break;
-        }
-        candidates.push({ offset, rect });
-        if (!edgeRect || (forward ? rect.top < edgeRect.top : rect.bottom > edgeRect.bottom)) {
-            edgeRect = rect;
         }
+        const probe = caretBoxAt(container, target);
+        if (!probe)
+            continue;
+        if (walkEndsAt(probe))
+            break;
+        candidates.push(probe);
     }
-    if (!edgeRect)
+    if (candidates.length === 0)
         return minOffset;
-    const lineTop = edgeRect.top;
-    const lineBottom = edgeRect.bottom;
-    const lineHeight = Math.max(1, lineBottom - lineTop);
-    const tolerance = lineHeight * LINE_BAND_TOLERANCE;
-    let bestOffset = candidates[0].offset;
+    // A block made of widgets alone has no line with a box of its own, and the widget edges are
+    // the only positions its caret can take.
+    const pool = owned.edge ? candidates.filter((probe) => !probe.borrowed) : candidates;
+    const edgeLine = owned.edge ?? edgeLineOf(pool, forward);
+    // Which offsets share the edge line: boxes ending within four fifths of the block's line
+    // height of it, which holds a tall widget on the line with a few pixels to spare over the gap.
+    let bestOffset = pool[0].offset;
     let bestDelta = Infinity;
-    for (const { offset, rect } of candidates) {
-        if (rect.top > lineBottom + tolerance)
-            continue;
-        if (rect.bottom < lineTop - tolerance)
+    for (const { offset, rect } of pool) {
+        if (Math.abs(rect.bottom - edgeLine.bottom) > tolerance)
             continue;
         const delta = Math.abs(rect.left - targetViewportX);
         if (delta < bestDelta) {
@@ -91,6 +101,46 @@ export function findOffsetNearestX(container, editorRelativeX, from, minOffset =
     return bestOffset;
 }
 // ── Internal ─────────────────────────────────────────────────────────────────
+const STOP_AFTER_LINES = 3;
+/** The probed edge's line as an inward walk sees it, and whether a box has gone further past it
+ *  than `allowance` (read off the first box) allows. Distances are between bottoms. */
+function createEdgeTracker(forward, allowance) {
+    let edge = null;
+    let limit = 0;
+    const isPast = (rect) => {
+        if (!edge)
+            return false;
+        return (forward ? rect.bottom - edge.bottom : edge.bottom - rect.bottom) > limit;
+    };
+    return {
+        get edge() {
+            return edge;
+        },
+        /** Reads the box against the edge without letting it move the edge. */
+        isPast,
+        /** Takes the box as the edge when it is the first, or sits nearer the edge than it. */
+        passes(rect) {
+            if (!edge) {
+                edge = rect;
+                limit = allowance(rect);
+                return false;
+            }
+            if (isPast(rect))
+                return true;
+            if (forward ? rect.top < edge.top : rect.bottom > edge.bottom)
+                edge = rect;
+            return false;
+        }
+    };
+}
+function lineHeightOf(rect) {
+    return Math.max(1, rect.bottom - rect.top);
+}
+/** The box on the probed edge's line: the highest top (above) or the lowest bottom (below), the
+ *  first of equals winning. */
+function edgeLineOf(probes, forward) {
+    return probes.reduce((held, probe) => (forward ? probe.rect.top < held.top : probe.rect.bottom > held.bottom) ? probe.rect : held, probes[0].rect);
+}
 function editorLeftOf(el) {
     const editor = el.closest('.editor');
     return editor ? editor.getBoundingClientRect().left : 0;

package/dist/cursor/surface-backend.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Caret reads and writes for an editable block element, in raw offsets, over the one offset walk
+ * in `widget-offset.ts`. Every editable surface (prose, code, table cell, plugin leaf) builds one.
+ * Reads answer only while the element holds focus.
+ */
+import { type RawOffset } from './coordinate-spaces';
+import { type CaretClamp } from './widget-offset';
+export interface SurfaceBackendDeps {
+    getEl: () => HTMLElement | null;
+    /** Where the user meant the caret, in raw units, when the browser holds no usable range: Chromium
+     *  drops an element-level caret beside an atomic widget across an event-loop yield. */
+    getSnapTarget?: () => number | null;
+}
+/** The caret calls the editable-surface factory needs from a block. */
+export interface CursorBackend {
+    /** Raw offset of the caret (the range start), or null when the element does not hold focus. */
+    getRaw(): RawOffset | null;
+    /** Place a collapsed caret; `clamp` says whether the offset may move onto a position the
+     *  caret can reach. */
+    setRaw(offset: RawOffset, placement: {
+        clamp: CaretClamp;
+    }): void;
+}
+export interface SurfaceBackend extends CursorBackend {
+    /** Raw offset of the selection's moving end, or null when it sits outside the element. */
+    getFocusOffset(): RawOffset | null;
+    /** Raw offsets of the selection's start and end, or null for a caret or an unfocused element. */
+    getRawSelection(): {
+        start: RawOffset;
+        end: RawOffset;
+    } | null;
+    /** Raw offsets of an arbitrary range inside the element: an InputEvent's target range, which a
+     *  word delete reports at a collapsed caret, so the selection cannot answer it. */
+    rawRangeOf(range: AbstractRange): {
+        start: RawOffset;
+        end: RawOffset;
+    } | null;
+    /** Move a focused caret that sits inside the marker prefix to raw 0, just past the prefix. */
+    clampOutOfMarkerPrefix(): void;
+}
+export declare function createSurfaceBackend(deps: SurfaceBackendDeps): SurfaceBackend;

package/dist/cursor/surface-backend.js

@@ -0,0 +1,78 @@
+/**
+ * Caret reads and writes for an editable block element, in raw offsets, over the one offset walk
+ * in `widget-offset.ts`. Every editable surface (prose, code, table cell, plugin leaf) builds one.
+ * Reads answer only while the element holds focus.
+ */
+import { asRawOffset } from './coordinate-spaces';
+import { domTextOffsetAtNode, markerPrefixLength, markerPrefixOf, placeCaretAtRaw, rawOffsetAt, rawSelectionFocus } from './widget-offset';
+export function createSurfaceBackend(deps) {
+    function snapTargetRaw() {
+        const target = deps.getSnapTarget?.() ?? null;
+        return target === null ? null : asRawOffset(target);
+    }
+    function getRaw() {
+        const live = readLiveRange(deps.getEl());
+        if (live.state === 'inactive')
+            return null;
+        // A dropped range, or one bounced into the read-only prefix: the snap target holds where the
+        // user meant the caret.
+        if (live.state === 'dropped' || live.inPrefix(live.range.startContainer))
+            return snapTargetRaw();
+        return rawOffsetAt(live.el, live.range.startContainer, live.range.startOffset);
+    }
+    function setRaw(offset, placement) {
+        const el = deps.getEl();
+        if (el)
+            placeCaretAtRaw(el, offset, placement);
+    }
+    function getFocusOffset() {
+        const el = deps.getEl();
+        return el ? rawSelectionFocus(el) : null;
+    }
+    function getRawSelection() {
+        const live = readLiveRange(deps.getEl());
+        if (live.state !== 'live' || live.collapsed)
+            return null;
+        // No snap-target fallback: one caret intent cannot stand in for one end of a pair, and an
+        // endpoint inside the prefix already reads as raw 0.
+        return rawEndpointsOf(live.el, live.range);
+    }
+    function rawRangeOf(range) {
+        const el = deps.getEl();
+        if (!el || !el.contains(range.startContainer) || !el.contains(range.endContainer))
+            return null;
+        return rawEndpointsOf(el, range);
+    }
+    function clampOutOfMarkerPrefix() {
+        const live = readLiveRange(deps.getEl());
+        if (live.state !== 'live' || !live.collapsed)
+            return;
+        const { startContainer, startOffset } = live.range;
+        const walk = domTextOffsetAtNode(live.el, startContainer, startOffset);
+        if (walk < markerPrefixLength(live.el))
+            placeCaretAtRaw(live.el, 0, { clamp: 'exact' });
+    }
+    return { getRaw, setRaw, getFocusOffset, getRawSelection, rawRangeOf, clampOutOfMarkerPrefix };
+}
+// ── Internal ────────────────────────────────────────────────────────────────
+function rawEndpointsOf(el, range) {
+    return {
+        start: rawOffsetAt(el, range.startContainer, range.startOffset),
+        end: rawOffsetAt(el, range.endContainer, range.endOffset)
+    };
+}
+function readLiveRange(el) {
+    if (!el || document.activeElement !== el)
+        return { state: 'inactive' };
+    const sel = window.getSelection();
+    if (!sel || sel.rangeCount === 0)
+        return { state: 'dropped' };
+    const prefix = markerPrefixOf(el);
+    return {
+        state: 'live',
+        el,
+        range: sel.getRangeAt(0),
+        collapsed: sel.isCollapsed,
+        inPrefix: (node) => prefix !== null && prefix.contains(node)
+    };
+}

package/dist/cursor/typography-estimates.d.ts

@@ -2,8 +2,8 @@
  * Empirical pixel estimates of the editor font's line box, measured at
  * {@link ESTIMATE_BASE_FONT_SIZE} and shared by `height-oracle.ts` and `visual-lines.ts`.
  * Character width has no CSS number to derive from, so the set is mirrored by hand at one scale.
- * The editor's type scale is font-relative, so consumers scale these by the root's live computed
- * font size — an estimate calibrated for one scale can miss the windowing watermark entirely.
+ * The editor's type scale is font-relative, so callers scale these by the root's live computed
+ * font size; an estimate calibrated for one scale can miss the windowing threshold entirely.
  */
 /** The computed root font size the estimates below were measured at. */
 export declare const ESTIMATE_BASE_FONT_SIZE = 16;
@@ -14,7 +14,7 @@ export declare const HEIGHT_ESTIMATES: {
     readonly blockChrome: 16;
     readonly imageBlockMinHeight: 200;
 };
-/** Fallback for a `normal` computed `lineHeight` (parses to NaN) — a generic line box,
+/** Fallback for a `normal` computed `lineHeight` (parses to NaN): a generic line box,
  *  independent of the per-kind estimates above. */
 export declare const FALLBACK_LINE_HEIGHT = 20;
 /** Fallback content width when no editor element is measurable yet (pre-mount, jsdom). */

package/dist/cursor/typography-estimates.js

@@ -2,8 +2,8 @@
  * Empirical pixel estimates of the editor font's line box, measured at
  * {@link ESTIMATE_BASE_FONT_SIZE} and shared by `height-oracle.ts` and `visual-lines.ts`.
  * Character width has no CSS number to derive from, so the set is mirrored by hand at one scale.
- * The editor's type scale is font-relative, so consumers scale these by the root's live computed
- * font size — an estimate calibrated for one scale can miss the windowing watermark entirely.
+ * The editor's type scale is font-relative, so callers scale these by the root's live computed
+ * font size; an estimate calibrated for one scale can miss the windowing threshold entirely.
  */
 /** The computed root font size the estimates below were measured at. */
 export const ESTIMATE_BASE_FONT_SIZE = 16;
@@ -14,7 +14,7 @@ export const HEIGHT_ESTIMATES = {
     blockChrome: 16, // px of margin/padding per block
     imageBlockMinHeight: 200 // px floor for an image-bearing paragraph
 };
-/** Fallback for a `normal` computed `lineHeight` (parses to NaN) — a generic line box,
+/** Fallback for a `normal` computed `lineHeight` (parses to NaN): a generic line box,
  *  independent of the per-kind estimates above. */
 export const FALLBACK_LINE_HEIGHT = 20;
 /** Fallback content width when no editor element is measurable yet (pre-mount, jsdom). */

package/dist/cursor/visual-lines.d.ts

@@ -1,26 +1,37 @@
 /**
- * Whether the cursor sits on the first or last visual line of a wrapping element. Offsets alone
- * can't answer it past 2 wrapped lines, so the cursor's line is compared to the edge line's.
- * Collapsed ranges beside non-text children (dimmed markers, atomic islands) measure to nothing,
- * so the edge line is measured around real text, and a rect-less caret reads the box it sits
- * against.
+ * Whether the cursor sits on the first or last visual line of a wrapping element, by comparing
+ * the cursor's line box with the edge line's. A caret beside a non-text child measures to
+ * nothing, so it borrows the box it sits against; that box and the line tolerance live here.
  */
 /** The first rect that can position a caret: the leading client rect when it has real
  *  height, else the bounding rect. `widthTolerant` also accepts a zero-height rect with width. */
 export declare function firstUsefulRect(range: Range, widthTolerant?: boolean): DOMRect | null;
 export declare function getRangeTop(range: Range): number | null;
+/** The box a caret sits in: what the line comparisons and the sticky column both read of it. */
+export interface CaretRect {
+    /** The caret's x. For a caret borrowing a widget's box, the edge it sits on. */
+    left: number;
+    top: number;
+    bottom: number;
+}
+/** The box a caret with no rect of its own borrows: the widget it precedes, else the one it follows.
+ *  Null off an element-level position, or when the neighbour measures to nothing. */
+export declare function neighbourCaretRect(range: Range): CaretRect | null;
+/** How far apart two carets' boxes may sit and still read as one visual line: under one line of
+ *  the element's own leading, so sub/superscript or inline-image jitter is not a new line. */
+export declare function sameLineTolerance(el: HTMLElement): number;
 /** Non-collapsed ranges reliably return rects where collapsed ones don't. */
 export declare function getCharRangeTop(container: Node, offset: number, atEnd: boolean): number | null;
 /** Skips non-text children (dimmed marker spans) that would otherwise leave the block's
  *  first line unmeasurable, and hidden marker text, which measures to no rect at all. */
 export declare function findFirstTextNode(root: Node): Text | null;
 export declare function findLastTextNode(root: Node): Text | null;
-/**
- * True if the selection inside `el` sits on the first visual line; empty containers return true.
- * `fallbackOffset` (the snapped caret intent from `ambient-cursor.getRaw`) resolves the case
- * where there is no live range — Chromium drops the caret range next to atomic
- * contenteditable=false islands across event-loop yields. It is compared against the block's
- * first LANDABLE offset, which a leading hidden run moves off raw 0.
- */
-export declare function isAtFirstVisualLine(el: HTMLElement, fallbackOffset: number, contentStart: number): boolean;
-export declare function isAtLastVisualLine(el: HTMLElement, fallbackOffset: number, contentEnd: number): boolean;
+/** The first and last offsets a caret can sit at in a block, which a hidden run moves inward. */
+export interface CaretBounds {
+    start: number;
+    end: number;
+}
+/** True if the selection in `el` sits on the first visual line, or holds no range. `fallbackOffset`
+ *  answers without a live range, which Chromium drops beside widgets across event-loop yields. */
+export declare function isAtFirstVisualLine(el: HTMLElement, fallbackOffset: number, bounds: CaretBounds): boolean;
+export declare function isAtLastVisualLine(el: HTMLElement, fallbackOffset: number, bounds: CaretBounds): boolean;

package/dist/cursor/visual-lines.js

@@ -1,15 +1,13 @@
 /**
- * Whether the cursor sits on the first or last visual line of a wrapping element. Offsets alone
- * can't answer it past 2 wrapped lines, so the cursor's line is compared to the edge line's.
- * Collapsed ranges beside non-text children (dimmed markers, atomic islands) measure to nothing,
- * so the edge line is measured around real text, and a rect-less caret reads the box it sits
- * against.
+ * Whether the cursor sits on the first or last visual line of a wrapping element, by comparing
+ * the cursor's line box with the edge line's. A caret beside a non-text child measures to
+ * nothing, so it borrows the box it sits against; that box and the line tolerance live here.
  */
 import { domDescendants } from './dom-walk';
 import { FALLBACK_LINE_HEIGHT } from './typography-estimates';
 import { isHiddenMarkerText } from './widget-offset';
-// Fraction of a line height within which the cursor Y counts as the boundary line —
-// sub-line, so sub/superscript or inline-image jitter doesn't read as a different line.
+// Fraction of a line height within which the cursor Y counts as the boundary line; under one
+// line, so sub/superscript or inline-image jitter doesn't read as a different line.
 const SAME_LINE_TOLERANCE = 0.8;
 /** The first rect that can position a caret: the leading client rect when it has real
  *  height, else the bounding rect. `widthTolerant` also accepts a zero-height rect with width. */
@@ -25,6 +23,22 @@ export function firstUsefulRect(range, widthTolerant = true) {
 export function getRangeTop(range) {
     return firstUsefulRect(range, false)?.top ?? null;
 }
+/** The box a caret with no rect of its own borrows: the widget it precedes, else the one it follows.
+ *  Null off an element-level position, or when the neighbour measures to nothing. */
+export function neighbourCaretRect(range) {
+    const container = range.startContainer;
+    if (container.nodeType !== Node.ELEMENT_NODE)
+        return null;
+    const children = container.childNodes;
+    return (nodeCaretRect(children[range.startOffset], false) ??
+        nodeCaretRect(children[range.startOffset - 1], true));
+}
+/** How far apart two carets' boxes may sit and still read as one visual line: under one line of
+ *  the element's own leading, so sub/superscript or inline-image jitter is not a new line. */
+export function sameLineTolerance(el) {
+    const lineHeight = parseFloat(getComputedStyle(el).lineHeight) || FALLBACK_LINE_HEIGHT;
+    return lineHeight * SAME_LINE_TOLERANCE;
+}
 /** Non-collapsed ranges reliably return rects where collapsed ones don't. */
 export function getCharRangeTop(container, offset, atEnd) {
     try {
@@ -52,16 +66,11 @@ export function findFirstTextNode(root) {
 export function findLastTextNode(root) {
     return measurableText(root, containerOf(root), true);
 }
-/**
- * True if the selection inside `el` sits on the first visual line; empty containers return true.
- * `fallbackOffset` (the snapped caret intent from `ambient-cursor.getRaw`) resolves the case
- * where there is no live range — Chromium drops the caret range next to atomic
- * contenteditable=false islands across event-loop yields. It is compared against the block's
- * first LANDABLE offset, which a leading hidden run moves off raw 0.
- */
-export function isAtFirstVisualLine(el, fallbackOffset, contentStart) {
-    return isAtEdgeVisualLine(el, () => fallbackOffset <= contentStart, {
-        isEmpty: (el.textContent ?? '').length === 0,
+/** True if the selection in `el` sits on the first visual line, or holds no range. `fallbackOffset`
+ *  answers without a live range, which Chromium drops beside widgets across event-loop yields. */
+export function isAtFirstVisualLine(el, fallbackOffset, bounds) {
+    return isAtEdgeVisualLine(el, () => fallbackOffset <= bounds.start, {
+        isEmpty: bounds.start === bounds.end,
         toStart: true,
         boundaryTop: () => {
             const firstText = findFirstTextNode(el);
@@ -70,9 +79,9 @@ export function isAtFirstVisualLine(el, fallbackOffset, contentStart) {
         }
     });
 }
-export function isAtLastVisualLine(el, fallbackOffset, contentEnd) {
-    return isAtEdgeVisualLine(el, () => fallbackOffset >= contentEnd, {
-        isEmpty: contentEnd === 0,
+export function isAtLastVisualLine(el, fallbackOffset, bounds) {
+    return isAtEdgeVisualLine(el, () => fallbackOffset >= bounds.end, {
+        isEmpty: bounds.start === bounds.end,
         toStart: false,
         boundaryTop: () => {
             const lastText = findLastTextNode(el);
@@ -82,8 +91,7 @@ export function isAtLastVisualLine(el, fallbackOffset, contentEnd) {
     });
 }
 // ── Internal ────────────────────────────────────────────────────────────────
-/** The shared skeleton of the two edge predicates: `fallback` answers where geometry cannot — a
- *  dropped range, a caret no box can be found for, an unmeasurable boundary line — and
+/** The shared skeleton of the two edge predicates: `fallback` answers where geometry cannot, and
  *  `boundaryTop` measures the edge line each side's own way. */
 function isAtEdgeVisualLine(el, fallback, edge) {
     const sel = window.getSelection();
@@ -92,16 +100,15 @@ function isAtEdgeVisualLine(el, fallback, edge) {
     if (edge.isEmpty)
         return true;
     const cursorRange = sel.getRangeAt(0);
-    const lineHeight = parseFloat(getComputedStyle(el).lineHeight) || FALLBACK_LINE_HEIGHT;
-    const tolerance = lineHeight * SAME_LINE_TOLERANCE;
+    const tolerance = sameLineTolerance(el);
     const cursorTop = getRangeTop(cursorRange);
     if (cursorTop === null) {
         if (!cursorRange.collapsed)
             return true;
-        // A caret beside an atomic island sits at an element-level position and measures to no rect
-        // of its own: it rides the island's box, and is at the edge line when nothing reaches past.
-        const band = neighbourBand(cursorRange);
-        const contents = bandOfRange(contentsRange(el));
+        // A caret beside an atomic widget sits at an element-level position and measures to no rect
+        // of its own: it borrows the widget's box, and is at the edge line when nothing reaches past.
+        const band = neighbourCaretRect(cursorRange);
+        const contents = contentsRect(el);
         if (!band || !contents)
             return fallback();
         return edge.toStart
@@ -113,36 +120,28 @@ function isAtEdgeVisualLine(el, fallback, edge) {
         return fallback();
     return Math.abs(cursorTop - edgeTop) < tolerance;
 }
-/** The vertical band of the box a rect-less caret sits against: the child it precedes, else the
- *  one it follows. Null where the caret is not at an element-level position. */
-function neighbourBand(range) {
-    const container = range.startContainer;
-    if (container.nodeType !== Node.ELEMENT_NODE)
-        return null;
-    const children = container.childNodes;
-    return (nodeBand(children[range.startOffset], false) ?? nodeBand(children[range.startOffset - 1], true));
-}
-function nodeBand(node, fromEnd) {
+function nodeCaretRect(node, fromEnd) {
     if (!node)
         return null;
     const range = document.createRange();
     range.selectNode(node);
     // A node that wraps has one rect per line, and the caret touches the line on its own side.
     const rects = range.getClientRects();
-    if (rects.length === 0)
-        return bandOfRange(range);
-    return bandOf(rects[fromEnd ? rects.length - 1 : 0]);
+    const rect = rects.length === 0 ? range.getBoundingClientRect() : rects[fromEnd ? rects.length - 1 : 0];
+    return caretRectOf(rect, fromEnd);
 }
 function contentsRange(el) {
     const range = document.createRange();
     range.selectNodeContents(el);
     return range;
 }
-function bandOfRange(range) {
-    return bandOf(range.getBoundingClientRect());
+function contentsRect(el) {
+    return caretRectOf(contentsRange(el).getBoundingClientRect(), false);
 }
-function bandOf(rect) {
-    return rect.height > 0 ? { top: rect.top, bottom: rect.bottom } : null;
+function caretRectOf(rect, fromEnd) {
+    if (rect.height <= 0)
+        return null;
+    return { left: fromEnd ? rect.right : rect.left, top: rect.top, bottom: rect.bottom };
 }
 /** The boundary line's collapsed-contents fallback measurement. */
 function collapsedContentsTop(el, toStart) {
@@ -150,7 +149,7 @@ function collapsedContentsTop(el, toStart) {
     range.collapse(toStart);
     return getRangeTop(range);
 }
-/** Hidden-run classification needs the walk container; a bare text-node root has none. */
+/** Deciding whether text is a hidden marker needs the walk container; a bare text-node root has none. */
 function containerOf(root) {
     return root instanceof HTMLElement ? root : null;
 }

package/dist/cursor/widget-edge-snap.d.ts

@@ -1,28 +1,23 @@
 /**
- * Which atomic island's raw edge a point lands on: the NEAREST edge among the islands the caller
- * measures, so a run of flush islands answers the one the point is actually beside. A point inside
- * one reads its kind: a character-like island names the edge on the point's side, while an island
- * that selects whole declines and keeps its own click handling.
+ * Which atomic inline widget's raw edge a point lands on: the nearest edge among the widgets the
+ * caller measures. A point on a widget that behaves like a character names the edge on its side;
+ * one on a widget that selects whole declines, leaving that widget's own click handling.
  */
 export interface WidgetEdgeCandidate {
-    /** The island's own raw source span; the caret seats at one end or the other. */
+    /** The widget's own raw source span; the caret goes at one end or the other. */
     start: number;
     end: number;
     rect: Pick<DOMRect, 'left' | 'right' | 'top' | 'bottom'>;
-    /** The kind reads as one character, so a press ON it names an edge by side rather than
-     *  selecting the island whole. */
+    /** The kind behaves as one character, so a click on it names an edge by side rather than
+     *  selecting the widget whole. */
     seatsInside: boolean;
 }
 export interface WidgetEdgeSeat {
     offset: number;
-    /** The press landed ON the island: the engine answers such a point with a position in the
-     *  neighbouring text, so its own caret is no reason to stand this seat down. */
+    /** The click landed on the widget itself. The browser would put the caret in the text
+     *  beside it, and that caret is no reason to drop this snap. */
     inside: boolean;
 }
-/**
- * The raw offset a point snaps to, in document order for ties. Null where the point snaps to none:
- * inside an island that selects whole, whose own click handling owns it, or with no island to
- * either side. A null `y` is a point with no line to compare against, so vertical distance drops
- * out and horizontal containment alone reads as inside.
- */
+/** The raw offset a point snaps to, ties in document order. Null inside a widget that selects whole
+ *  (its own click handling owns it) or with no widget; a null `y` compares columns alone. */
 export declare function nearestWidgetEdgeSeat(candidates: Iterable<WidgetEdgeCandidate>, x: number, y: number | null): WidgetEdgeSeat | null;