@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/cursor/point-offset.d.ts

@@ -1,19 +1,25 @@
 /**
- * Viewport point → caret offset inside one element. The probe is the browser's, the arithmetic
- * is `widget-offset.ts`'s walk: this module mints no offset of its own, so an atomic widget and
- * a leading ambient marker count here exactly as they do for a live caret read.
- */
-/**
- * The caret offset in `el` NEAREST a viewport point: the point clamps into `el`'s box first, so a
- * press on chrome above or beside the text still names one. What `caretTargetAtPoint` owes, since
- * a caret-placing gesture must land. Null where the element holds no text position at all.
+ * Viewport point to caret offset inside one element. The browser finds the DOM position, and
+ * `widget-offset.ts`'s walk does the arithmetic: this module computes no offset of its own, so
+ * an atomic widget and a leading marker prefix count here exactly as they do for a live caret read.
  */
+/** The caret offset in `el` nearest a viewport point, clamped into `el`'s box first so a click on
+ *  the frame still names one. Null where `el` holds no text. */
 export declare function caretOffsetAtPoint(el: HTMLElement, clientX: number, clientY: number): number | null;
 /**
- * The EXACT twin: null for a point outside `el`, which a hit test must decline rather than
- * round into the nearest offset.
+ * The exact counterpart: null for a point outside `el`, which a hit test must decline rather
+ * than round into the nearest offset. A point inside `el` is first moved level with its lines.
  */
 export declare function offsetFromViewportPoint(blockEl: HTMLElement, clientX: number, clientY: number): number | null;
+/** The DOM position a press at this point lands on, asked level with `el`'s lines when the point
+ *  is inside it; the position may lie outside `el`. */
+export declare function caretSeatInElement(el: HTMLElement, clientX: number, clientY: number): {
+    node: Node;
+    offset: number;
+} | null;
+/** Whether a point inside `el`'s box lies above its first line or below its last, in the padding
+ *  where Mac and Linux would place a press at that line's start or end. */
+export declare function isInPaddingRow(el: HTMLElement, clientX: number, clientY: number): boolean;
 /** A point one pixel inside `rect`, so the topmost element there is the box's own content. */
 export declare function clampPointIntoBox(rect: DOMRect, x: number, y: number): {
     x: number;

package/dist/cursor/point-offset.js

@@ -1,40 +1,51 @@
 /**
- * Viewport point → caret offset inside one element. The probe is the browser's, the arithmetic
- * is `widget-offset.ts`'s walk: this module mints no offset of its own, so an atomic widget and
- * a leading ambient marker count here exactly as they do for a live caret read.
- */
-import { ambientLengthOf } from '../ambient/ambient-dom';
-import { toClampedRawOffset } from './coordinate-spaces';
-import { domTextOffsetAtNode } from './widget-offset';
-/**
- * The caret offset in `el` NEAREST a viewport point: the point clamps into `el`'s box first, so a
- * press on chrome above or beside the text still names one. What `caretTargetAtPoint` owes, since
- * a caret-placing gesture must land. Null where the element holds no text position at all.
+ * Viewport point to caret offset inside one element. The browser finds the DOM position, and
+ * `widget-offset.ts`'s walk does the arithmetic: this module computes no offset of its own, so
+ * an atomic widget and a leading marker prefix count here exactly as they do for a live caret read.
  */
+import { rawOffsetAt } from './widget-offset';
+/** The caret offset in `el` nearest a viewport point, clamped into `el`'s box first so a click on
+ *  the frame still names one. Null where `el` holds no text. */
 export function caretOffsetAtPoint(el, clientX, clientY) {
     const probe = clampPointIntoBox(el.getBoundingClientRect(), clientX, clientY);
     return offsetFromViewportPoint(el, probe.x, probe.y);
 }
 /**
- * The EXACT twin: null for a point outside `el`, which a hit test must decline rather than
- * round into the nearest offset.
+ * The exact counterpart: null for a point outside `el`, which a hit test must decline rather
+ * than round into the nearest offset. A point inside `el` is first moved level with its lines.
  */
 export function offsetFromViewportPoint(blockEl, clientX, clientY) {
-    const doc = blockEl.ownerDocument;
-    // caretRangeFromPoint is Chromium/WebKit (all Tauri webviews);
-    // caretPositionFromPoint is the Firefox-style fallback.
-    const ambient = ambientLengthOf(blockEl);
+    // The browser answers a point beside an element with an offset inside it, so ask only inside.
+    if (!isInside(blockEl.getBoundingClientRect(), clientX, clientY))
+        return null;
+    const seat = caretSeatInElement(blockEl, clientX, clientY);
+    if (!seat || !blockEl.contains(seat.node))
+        return null;
+    return rawOffsetAt(blockEl, seat.node, seat.offset);
+}
+/** The DOM position a press at this point lands on, asked level with `el`'s lines when the point
+ *  is inside it; the position may lie outside `el`. */
+export function caretSeatInElement(el, clientX, clientY) {
+    return caretSeatFromPoint(el.ownerDocument, clientX, levelWithLines(el, clientX, clientY));
+}
+/** Whether a point inside `el`'s box lies above its first line or below its last, in the padding
+ *  where Mac and Linux would place a press at that line's start or end. */
+export function isInPaddingRow(el, clientX, clientY) {
+    const box = el.getBoundingClientRect();
+    if (!isInside(box, clientX, clientY))
+        return false;
+    const band = linesBandOf(el, box);
+    return band !== null && (clientY < band.top || clientY > band.bottom);
+}
+/** The browser's own hit test: `caretRangeFromPoint` on Chromium and WebKit,
+ *  `caretPositionFromPoint` as the Firefox fallback. */
+function caretSeatFromPoint(doc, clientX, clientY) {
     const rangeFromPoint = doc.caretRangeFromPoint?.(clientX, clientY);
-    if (rangeFromPoint && blockEl.contains(rangeFromPoint.startContainer)) {
-        const content = domTextOffsetAtNode(blockEl, rangeFromPoint.startContainer, rangeFromPoint.startOffset);
-        return toClampedRawOffset(content, ambient);
+    if (rangeFromPoint) {
+        return { node: rangeFromPoint.startContainer, offset: rangeFromPoint.startOffset };
     }
     const posFromPoint = doc.caretPositionFromPoint?.(clientX, clientY);
-    if (posFromPoint && blockEl.contains(posFromPoint.offsetNode)) {
-        const content = domTextOffsetAtNode(blockEl, posFromPoint.offsetNode, posFromPoint.offset);
-        return toClampedRawOffset(content, ambient);
-    }
-    return null;
+    return posFromPoint ? { node: posFromPoint.offsetNode, offset: posFromPoint.offset } : null;
 }
 /** A point one pixel inside `rect`, so the topmost element there is the box's own content. */
 export function clampPointIntoBox(rect, x, y) {
@@ -43,6 +54,30 @@ export function clampPointIntoBox(rect, x, y) {
         y: clamp(y, rect.top + 1, rect.bottom - 1)
     };
 }
+// Mac and Linux Chromium answer a point above the first line or below the last with that line's
+// start or end, and Windows with the column; a point level with a line gets the column everywhere.
+function levelWithLines(el, x, y) {
+    const box = el.getBoundingClientRect();
+    if (!isInside(box, x, y))
+        return y;
+    const band = linesBandOf(el, box);
+    return band ? clamp(y, band.top + 1, band.bottom - 1) : y;
+}
+function isInside(box, x, y) {
+    return x >= box.left && x <= box.right && y >= box.top && y <= box.bottom;
+}
+/** The rows between `el`'s top and bottom padding; null when they leave no row one pixel inside.
+ *  Only rows: a hanging list marker sits in the left padding, and the browser keeps a column there. */
+function linesBandOf(el, box) {
+    const style = getComputedStyle(el);
+    const px = (value) => parseFloat(value) || 0;
+    // The client box leaves out the border and a classic scrollbar; an inline element has none.
+    const inline = el.clientWidth === 0 && el.clientHeight === 0;
+    const top = box.top + (inline ? px(style.borderTopWidth) : el.clientTop);
+    const bottom = inline ? box.bottom - px(style.borderBottomWidth) : top + el.clientHeight;
+    const band = { top: top + px(style.paddingTop), bottom: bottom - px(style.paddingBottom) };
+    return band.bottom - band.top < 2 ? null : band;
+}
 function clamp(value, low, high) {
     return Math.min(Math.max(value, low), high);
 }

package/dist/cursor/reveal-source.d.ts

@@ -1,26 +1,22 @@
 /**
- * Rendered↔source reveal: the caret kernel shared by the inline-island and
- * render-primary-block swaps (both injected, along with the revealed flag). Placement runs
- * only through `cursor/widget-offset.ts`, offset translation's one home, converting
- * block-source offsets to walk space by `+ getAmbientLength()` at the single `placeCaret`
- * seam. Precondition `source.length === sourceEnd - sourceStart`, asserted at entry (G1.26).
+ * Swapping between a rendered view and its editable source: the caret logic shared by inline
+ * widgets and blocks that render by default (both inject the swap and the revealed flag).
+ * Precondition: `source.length === sourceEnd - sourceStart`, asserted at entry (G1.26).
  */
 export interface SourceRevealDeps {
-    /** The block's contenteditable host — where the offset walk runs. Null while a
-     *  reactive consumer has the source unmounted (the block case, while rendered). */
+    /** The block's contenteditable element, where the offset walk runs. Null while the source
+     *  is unmounted (a block that is showing its rendered view). */
     get container(): HTMLElement | null;
     /** Source's raw byte range [start, end) in the block source. */
     get sourceStart(): number;
     get sourceEnd(): number;
-    /** The source's raw bytes; `length` MUST equal `sourceEnd - sourceStart`. */
+    /** The source's raw bytes; `length` must equal `sourceEnd - sourceStart`. */
     get source(): string;
-    /** Rendered marker prefix length the DOM walk counts but block source excludes. */
-    getAmbientLength(): number;
     /** Whether the editable source is currently shown. Owned by the consumer
      *  (inline: a captured text node; block: a reactive flag). */
     isRevealed(): boolean;
     /** Swap the rendered view for editable source. May decline (leave `isRevealed`
-     *  false) — e.g. the inline widget island isn't in the DOM. */
+     *  false), for example when the inline widget is not in the DOM. */
     showSource(): void;
     /** Swap the editable source back for the rendered view (inverse of showSource). */
     showRendered(): void;

package/dist/cursor/reveal-source.js

@@ -1,38 +1,30 @@
 /**
- * Rendered↔source reveal: the caret kernel shared by the inline-island and
- * render-primary-block swaps (both injected, along with the revealed flag). Placement runs
- * only through `cursor/widget-offset.ts`, offset translation's one home, converting
- * block-source offsets to walk space by `+ getAmbientLength()` at the single `placeCaret`
- * seam. Precondition `source.length === sourceEnd - sourceStart`, asserted at entry (G1.26).
+ * Swapping between a rendered view and its editable source: the caret logic shared by inline
+ * widgets and blocks that render by default (both inject the swap and the revealed flag).
+ * Precondition: `source.length === sourceEnd - sourceStart`, asserted at entry (G1.26).
  */
 import { tick } from 'svelte';
-import { asRawOffset, toDomTextOffset } from './coordinate-spaces';
-import { restoreCaretAtWalkOffset } from './focused-caret';
-import { clampToLandableRaw } from './widget-offset';
+import { placeCaretAtRaw } from './widget-offset';
 import { assertInvariant } from '../assert';
 import { checkRevealSourceLength } from '../invariants/inline-transitions';
 export function createSourceReveal(deps) {
-    /** Places the caret at a BLOCK-source offset, converting to ambient-included walk space. */
+    // Offset 0 of a source that opens with hidden markers (a block hiding its `$$` fence lines) is
+    // before those markers, where typing would land outside the fence, so the write clamps.
     function placeCaret(container, blockSourceOffset) {
-        // Offset 0 of a source that opens with hidden chrome (a leaf painting `$$` fence lines) is
-        // BEFORE that chrome: typing there would land outside the fence. The seat is the nearest
-        // landable position, which is a no-op wherever nothing hides.
-        const ambient = deps.getAmbientLength();
-        const seat = clampToLandableRaw(container, blockSourceOffset, ambient);
-        restoreCaretAtWalkOffset(container, toDomTextOffset(asRawOffset(seat), ambient));
+        placeCaretAtRaw(container, blockSourceOffset, { clamp: 'reachable' });
     }
     async function reveal(atSourceOffset = 0) {
         assertInvariant('reveal-transition', () => checkRevealSourceLength(deps.source.length, deps.sourceStart, deps.sourceEnd));
         if (!deps.isRevealed())
             deps.showSource();
         if (!deps.isRevealed())
-            return; // swap declined (island not in the DOM)
+            return; // swap declined (the widget is not in the DOM)
         await tick();
         const settled = deps.container;
         if (!settled)
             return;
-        // Focus BEFORE the caret write: a caret placed in an unfocused editable receives no
-        // typing, and focusing after would reset the selection to the element start.
+        // Focus before the caret write: a caret placed in an unfocused editable receives no
+        // typing, and focusing afterwards would reset the selection to the element start.
         if (document.activeElement !== settled)
             settled.focus();
         const clamped = Math.max(0, Math.min(atSourceOffset, deps.source.length));

package/dist/cursor/scroll-ancestors.d.ts

@@ -1,28 +1,17 @@
 /**
- * "What scrolls" and "what clips" are two walks, never one: SCROLLING asks for
- * `auto`/`scroll` and stops at the first answer, CLIPPING asks for anything that bounds
- * the visible region and collects the whole chain, since visibility is their intersection.
- * An `overflow: hidden` auto-height card matches a clipping predicate while doing neither.
- * `selection/drag-pointer.ts` keeps its own inner walk, so a change here is not one to it.
+ * Ancestor walks for "what scrolls" (the first `auto`/`scroll` ancestor) and "what clips" (the
+ * whole chain of ancestors bounding the visible region, since visibility is their intersection).
+ * `selection/drag-pointer.ts` keeps its own inner walk, so a change here does not change it.
  */
 export declare function nearestScrollContainer(el: HTMLElement, stopAt: HTMLElement): HTMLElement | null;
 /** What a drag can autoscroll: an element, or the page's own viewport. */
 export type UserScrollport = HTMLElement | Window;
-/**
- * What a drag autoscrolls to bring more of `el` into reach: the nearest user-scrollable
- * ancestor, or the window when the page's own viewport is the scrollport. Total on
- * purpose — a null for the page-scrolled case reads as "no autoscroll targets", and
- * `document.scrollingElement` is no substitute (its rect is the document box).
- */
+/** What a drag autoscrolls to bring more of `el` into reach: the nearest user-scrollable ancestor,
+ *  or the window. Never null, which would read as "no autoscroll target". */
 export declare function userScrollportFor(el: HTMLElement): UserScrollport;
-/**
- * Every ancestor that bounds what can be seen of `el`, outermost-last. The whole chain,
- * not the nearest: only the intersection answers "is this visible", and the innermost
- * match alone can be a rounded card that bounds nothing. Callers intersect the window
- * viewport with these; an empty result means the window alone bounds it.
- */
+/** Every ancestor that bounds what can be seen of `el`, outermost last: only their intersection
+ *  with the window viewport answers visibility. Empty means the window alone bounds it. */
 export declare function clippingAncestors(el: HTMLElement): HTMLElement[];
-/** First scrollable descendant of `el` in document order. A block-host wrapper sits
- *  OUTSIDE a block's internal scroll container, so finding what scrolls beneath the host
- *  means looking inward, not up. */
+/** First scrollable descendant of `el` in document order: a block host wraps the block's own
+ *  scroll container, so what scrolls beneath it is found by looking inward. */
 export declare function firstScrollableDescendant(el: HTMLElement): HTMLElement | null;

package/dist/cursor/scroll-ancestors.js

@@ -1,24 +1,21 @@
 /**
- * "What scrolls" and "what clips" are two walks, never one: SCROLLING asks for
- * `auto`/`scroll` and stops at the first answer, CLIPPING asks for anything that bounds
- * the visible region and collects the whole chain, since visibility is their intersection.
- * An `overflow: hidden` auto-height card matches a clipping predicate while doing neither.
- * `selection/drag-pointer.ts` keeps its own inner walk, so a change here is not one to it.
+ * Ancestor walks for "what scrolls" (the first `auto`/`scroll` ancestor) and "what clips" (the
+ * whole chain of ancestors bounding the visible region, since visibility is their intersection).
+ * `selection/drag-pointer.ts` keeps its own inner walk, so a change here does not change it.
  */
-// Scrollable through script — `element.scrollTop = n` moves it. `hidden` qualifies.
+// Scrollable through script: `element.scrollTop = n` moves it. `hidden` qualifies.
 const SCRIPT_SCROLLABLE_VALUES = new Set(['auto', 'scroll', 'hidden']);
-// Scrollable by the USER, which is what a drag may autoscroll. `hidden` is excluded by
-// convention, not capability: a user cannot wheel it back, so autoscrolling it would
-// strand content out of reach.
+// Scrollable by the user, which is what a drag may autoscroll. `hidden` is left out: a user cannot
+// wheel it back, so autoscrolling it would strand content out of reach.
 const USER_SCROLLABLE_VALUES = new Set(['auto', 'scroll']);
-// What can bound the visible region. `clip` joins here and only here — it never scrolls,
+// What can bound the visible region. `clip` joins here and only here: it never scrolls,
 // so it is no autoscroll answer, but a block past its edge is unreachable.
 const VIEW_BOUNDING_VALUES = new Set([...SCRIPT_SCROLLABLE_VALUES, 'clip']);
 function isScriptScrollable(el) {
     const cs = getComputedStyle(el);
     return SCRIPT_SCROLLABLE_VALUES.has(cs.overflowX) || SCRIPT_SCROLLABLE_VALUES.has(cs.overflowY);
 }
-// Never a candidate in either walk: when the page box IS the scrollport, the window
+// Never a candidate in either walk: when the page box is the scroll container, the window
 // viewport is the rect to measure and the thing to scroll, and neither box is that rect.
 function isPageBox(el) {
     return el === document.body || el === document.documentElement;
@@ -32,12 +29,8 @@ export function nearestScrollContainer(el, stopAt) {
     }
     return null;
 }
-/**
- * What a drag autoscrolls to bring more of `el` into reach: the nearest user-scrollable
- * ancestor, or the window when the page's own viewport is the scrollport. Total on
- * purpose — a null for the page-scrolled case reads as "no autoscroll targets", and
- * `document.scrollingElement` is no substitute (its rect is the document box).
- */
+/** What a drag autoscrolls to bring more of `el` into reach: the nearest user-scrollable ancestor,
+ *  or the window. Never null, which would read as "no autoscroll target". */
 export function userScrollportFor(el) {
     let cur = el.parentElement;
     while (cur && !isPageBox(cur)) {
@@ -49,12 +42,8 @@ export function userScrollportFor(el) {
     }
     return window;
 }
-/**
- * Every ancestor that bounds what can be seen of `el`, outermost-last. The whole chain,
- * not the nearest: only the intersection answers "is this visible", and the innermost
- * match alone can be a rounded card that bounds nothing. Callers intersect the window
- * viewport with these; an empty result means the window alone bounds it.
- */
+/** Every ancestor that bounds what can be seen of `el`, outermost last: only their intersection
+ *  with the window viewport answers visibility. Empty means the window alone bounds it. */
 export function clippingAncestors(el) {
     const bounds = [];
     let cur = el.parentElement;
@@ -67,9 +56,8 @@ export function clippingAncestors(el) {
     }
     return bounds;
 }
-/** First scrollable descendant of `el` in document order. A block-host wrapper sits
- *  OUTSIDE a block's internal scroll container, so finding what scrolls beneath the host
- *  means looking inward, not up. */
+/** First scrollable descendant of `el` in document order: a block host wraps the block's own
+ *  scroll container, so what scrolls beneath it is found by looking inward. */
 export function firstScrollableDescendant(el) {
     const queue = [];
     for (const child of el.children) {

package/dist/cursor/scroll-owner.d.ts

@@ -0,0 +1,92 @@
+import type { BlockElLookup } from '../editor-keys';
+import type { UserScrollport } from './scroll-ancestors';
+import { type Scrollport, type ScrollportReader } from './scrollport';
+export type PlaceBlock = 'nearest' | 'center';
+export interface PlaceOptions {
+    block: PlaceBlock;
+    /** Keep the block where it landed against later layout shifts, until a user gesture or a newer
+     *  placement. */
+    hold: boolean;
+}
+export interface ScrollPlacement {
+    /** Scroll the mounted block into view once, then wait out the height changes that follow; true
+     *  when it ends in view. A newer placement stops it at once. */
+    scroll(): Promise<boolean>;
+}
+/** Where a block's top sits in the scroll container's content, and its height. */
+export interface TargetTop {
+    top: number;
+    height: number;
+}
+/** The root list's reads of the document's height tables, installed by the root list alone. */
+export interface TargetResolver {
+    /** Null when the list can't place the path: out of its range, or windowed out inside a
+     *  mounted container. */
+    resolve(path: readonly number[]): TargetTop | null;
+    /** The block a measure round keeps still, picked from the scroll before it, and a read of how far
+     *  it moved; the same walk `resolve` makes, so a held target and the round agree. */
+    holdForRound(): (() => number) | null;
+    /** Where to scroll so the block at `path` mounts in its list. */
+    mountTop(path: readonly number[]): number | null;
+    /** A scripted `scrollTop` write fires no `scroll` event in time, so the root window re-reads it. */
+    syncScrollTop(): void;
+}
+/** `held` runs the change and returns how far the block the caller keeps still moved across it. */
+export type Compensate = (mutate: () => void, held: (mutate: () => void) => number) => void;
+/** What the root list gets for installing its resolver: the header slot's correction. A round
+ *  measures below the root list's top, so the header's own growth joins it as a distance. */
+export interface RootListScroll {
+    compensate: Compensate;
+    uninstall(): void;
+}
+export interface ScrollOwner {
+    /** The scroll container, read-only; null until the editor root mounts. */
+    port(): ScrollportReader | null;
+    /** Whether any of the mounted block at `path` shows in the editor's viewport: the published
+     *  "placed and in view" answer, which a block partly on screen satisfies. */
+    isInView(path: readonly number[]): boolean;
+    /** Whether a viewport rect sits wholly inside what the editor shows, so a caret there needs no
+     *  scroll. */
+    shows(rect: DOMRectReadOnly): boolean;
+    /** Scroll the least distance that shows the rect `read` returns (a caret's line, a cell), read
+     *  after an open round's correction; null shows nothing. Holds nothing, and ends an older hold. */
+    showRect(read: () => DOMRectReadOnly | null): void;
+    /** Called before any list's height table changes: opens the round every height write of this
+     *  flush joins, picking the block to keep still now. The round writes once, at the next tick. */
+    beginRound(): void;
+    /** True from a round's first height write until it closes. */
+    roundOpen(): boolean;
+    /** Runs `run` after the current flush, with every other list's. */
+    measureSoon(run: () => void): void;
+    /** Watches a child's size with the editor's one observer; the callback only records heights. */
+    watchSize(el: Element, onResize: (entry: ResizeObserverEntry) => void): () => void;
+    /** Take the position for a scroll into view now, before the mount's awaits; `scroll()` once
+     *  the block is mounted. */
+    place(path: readonly number[], opts: PlaceOptions): ScrollPlacement;
+    /** Scroll so the block at `path` leads the viewport, to mount it there. */
+    scrollToMount(path: readonly number[]): void;
+    /** Read the position now; the returned call puts it back after a view swap renders. */
+    keep(): () => Promise<void>;
+    /** A keydown, pointerdown or wheel on the scroll container: drop any held placement. */
+    release(): void;
+    /** Called by the root list alone. */
+    resolveTargetsWith(resolver: TargetResolver): RootListScroll;
+}
+export interface ScrollOwnerDeps {
+    /** The element the editor scrolls, or null before the root mounts. */
+    getScrollHost(): UserScrollport | null;
+    /** Opens the scroll host as a scroll container the owner can write; a unit test hands in a
+     *  stub. */
+    openPort?: (host: UserScrollport) => Scrollport;
+    /** False while the browser's own scroll anchoring holds the user's place (host mode, root not
+     *  windowing): two writers on one position correct it twice. */
+    editorCorrects(): boolean;
+    getBlockElByPath: BlockElLookup;
+    getEditorRoot(): HTMLElement | null;
+    /** True when an ancestor owns the scroll: the root then spans the whole document, so
+     *  intersecting a block with it says nothing about visibility. */
+    isHostScroll(): boolean;
+    /** In host mode, the ancestors that bound what can be seen, intersected with the window. */
+    getClipBounds(): HTMLElement[];
+}
+export declare function createScrollOwner(deps: ScrollOwnerDeps): ScrollOwner;