@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/cursor/scroll-owner.js

@@ -0,0 +1,283 @@
+/**
+ * The one writer of the editor's scroll position: every other module reads the scroll container
+ * through `port()`, and every write is a method here that first decides who owns the position.
+ * One per editor, built in `Editor.svelte`. See `docs/design/virtual-rendering.md` § Keeping the
+ * page still while heights change.
+ */
+import { tick } from 'svelte';
+import { devWarn } from '../dev-warn';
+import { createScrollport } from './scrollport';
+import { createSharedResizeWatch } from './observe-resize';
+// A placement's mount wave goes quiet within a few flushes; one still compensating past this many
+// is a loop worth a warning.
+const SETTLE_TURNS = 12;
+export function createScrollOwner(deps) {
+    const openPort = deps.openPort ?? createScrollport;
+    let port = null;
+    let resolver = null;
+    let placement = null;
+    // A new placement supersedes the last one made, not the current holder, or `place, release,
+    // place` would leave the first scroll believing it still owns the viewport.
+    let lastMinted = null;
+    let roundsOpened = 0;
+    let open = null;
+    const soon = new Set();
+    function writable() {
+        if (port)
+            return port;
+        const host = deps.getScrollHost();
+        if (host)
+            port = openPort(host);
+        return port;
+    }
+    function drop() {
+        placement = null;
+    }
+    /** Null with nothing held or nothing to place it by. Offsets come from the height table, since
+     *  the DOM hasn't laid out the table's latest writes yet. */
+    function targetScrollTop() {
+        const p = writable();
+        if (!placement || !resolver || !p)
+            return null;
+        const at = resolver.resolve(placement.path);
+        if (!at)
+            return null;
+        if (placement.offset !== null)
+            return at.top + placement.bias - placement.offset;
+        // Centred on the scroll container's height, not a list's, which reads list geometry
+        // mid-change and would centre on a briefly tiny viewport.
+        return placement.block === 'center'
+            ? at.top - Math.max(0, (p.viewportHeight() - at.height) / 2)
+            : at.top;
+    }
+    function recordLanding(held, el) {
+        const p = writable();
+        if (!p)
+            return;
+        const offset = el.getBoundingClientRect().top - p.viewportTop();
+        const at = resolver?.resolve(held.path);
+        held.offset = offset;
+        held.bias = at ? p.scrollTop() + offset - at.top : 0;
+    }
+    // Each round re-places a placed target from the height table itself, so nothing is left to
+    // follow by hand once a flush passes with no round.
+    async function settle(token, path) {
+        for (let turn = 1;; turn++) {
+            const seen = roundsOpened;
+            await tick();
+            if (token.superseded || (roundsOpened === seen && !open))
+                return;
+            if (turn > SETTLE_TURNS) {
+                devWarn('scroll', `a placement still compensating after ${SETTLE_TURNS} flushes`, { path });
+                return;
+            }
+        }
+    }
+    function measureQueued() {
+        const runs = [...soon];
+        soon.clear();
+        for (const queued of runs)
+            queued();
+    }
+    /** Every owner write but the round's own: it measures the queued blocks and closes the round
+     *  first, so it reads tables that know every mounted block, and no correction lands after it. */
+    function writeScroll(target) {
+        measureQueued();
+        closeRound();
+        const to = target();
+        const p = writable();
+        if (!to || !p)
+            return;
+        if ('reveal' in to) {
+            to.reveal.scrollIntoView({ block: to.block });
+            return;
+        }
+        if ('top' in to)
+            p.setScrollTop(to.top);
+        else
+            p.scrollBy(to.by);
+        resolver?.syncScrollTop();
+    }
+    // The round's own correction writes the port directly, so closing never recurses.
+    function closeRound() {
+        const round = open;
+        if (!round)
+            return;
+        const corrects = deps.editorCorrects();
+        // A held placement owns the position, and re-places from the same tables.
+        const placed = corrects ? targetScrollTop() : null;
+        const delta = corrects && placed === null ? (round.moved?.() ?? 0) + round.added : 0;
+        // Cleared after the reads, so a table they rebuild joins this round instead of opening one.
+        open = null;
+        const p = writable();
+        if (!p)
+            return;
+        // The absolute write survives the browser clamping `scrollTop` while images decode above.
+        if (placed !== null) {
+            p.setScrollTop(placed);
+            resolver?.syncScrollTop();
+        }
+        else if (delta !== 0)
+            p.scrollBy(delta);
+    }
+    // Whether the editor corrects at all is asked at the close: the root list's own table opens a
+    // round while it builds, and that question reads the root's window.
+    function beginRound() {
+        if (open)
+            return;
+        const round = { moved: resolver?.holdForRound() ?? null, added: 0 };
+        open = round;
+        roundsOpened++;
+        void tick().then(() => {
+            if (open === round)
+                closeRound();
+        });
+    }
+    const sizes = createSharedResizeWatch();
+    function elementInView(el, root) {
+        const br = el.getBoundingClientRect();
+        // Self mode: the root is the scroll container, and what lies outside it is the host
+        // page's business, not the editor's.
+        if (!deps.isHostScroll()) {
+            const er = root.getBoundingClientRect();
+            return br.top < er.bottom && br.bottom > er.top;
+        }
+        if (br.top >= window.innerHeight || br.bottom <= 0)
+            return false;
+        for (const bound of deps.getClipBounds()) {
+            const cr = bound.getBoundingClientRect();
+            if (br.top >= cr.bottom || br.bottom <= cr.top)
+                return false;
+        }
+        return true;
+    }
+    /** What the editor shows, as a band of viewport pixels: the scroll container's box, cut down
+     *  in host mode by the ancestors that clip it. */
+    function visibleBand() {
+        const p = writable();
+        if (!p)
+            return null;
+        let top = p.viewportTop();
+        let bottom = top + p.viewportHeight();
+        if (deps.isHostScroll()) {
+            for (const bound of deps.getClipBounds()) {
+                const r = bound.getBoundingClientRect();
+                top = Math.max(top, r.top);
+                bottom = Math.min(bottom, r.bottom);
+            }
+        }
+        return { top, bottom };
+    }
+    // Sub-pixel tolerance: a scroll lands its target a fraction of a pixel off the edge.
+    function bandShows(band, rect) {
+        return rect.top >= band.top - 1 && rect.bottom <= band.bottom + 1;
+    }
+    function landedInView(path) {
+        const el = deps.getBlockElByPath(path);
+        const root = deps.getEditorRoot();
+        return el != null && (!root || elementInView(el, root));
+    }
+    return {
+        port: writable,
+        isInView(path) {
+            const root = deps.getEditorRoot();
+            const el = deps.getBlockElByPath([...path]);
+            return !!root && !!el && elementInView(el, root);
+        },
+        shows(rect) {
+            const band = visibleBand();
+            return !!band && bandShows(band, rect);
+        },
+        showRect(read) {
+            writeScroll(() => {
+                // A newer scroll into view, like a newer placement: an older hold must not drag it back.
+                if (lastMinted)
+                    lastMinted.superseded = true;
+                drop();
+                const band = visibleBand();
+                const rect = read();
+                if (!band || !rect || bandShows(band, rect))
+                    return null;
+                // A rect already filling the band has nothing to gain; otherwise its top wins a tie.
+                if (rect.top < band.top && rect.bottom > band.bottom)
+                    return null;
+                const by = rect.bottom > band.bottom
+                    ? Math.min(rect.bottom - band.bottom, rect.top - band.top)
+                    : rect.top - band.top;
+                return { by };
+            });
+        },
+        beginRound,
+        roundOpen: () => open !== null,
+        watchSize: (el, onResize) => sizes.watch(el, onResize),
+        measureSoon(run) {
+            if (soon.size === 0)
+                void tick().then(measureQueued);
+            soon.add(run);
+        },
+        place(path, { block, hold }) {
+            const p = [...path];
+            const token = { superseded: false };
+            if (lastMinted)
+                lastMinted.superseded = true;
+            lastMinted = token;
+            const mine = { token, path: p, block, offset: null, bias: 0 };
+            placement = mine;
+            return {
+                async scroll() {
+                    // Checked first: a placement another scroll took over during a long mount wait
+                    // would otherwise yank the viewport once.
+                    if (token.superseded)
+                        return false;
+                    const el = deps.getBlockElByPath(p);
+                    // A fully visible target stays put under `'nearest'`: the browser moves nothing.
+                    writeScroll(() => el && { reveal: el, block });
+                    if (el && placement === mine)
+                        recordLanding(mine, el);
+                    await settle(token, p);
+                    const landed = !token.superseded && landedInView(p);
+                    // `'center'` places without holding, as `rects.scrollTo` promises, and a target that
+                    // didn't land has no position to keep.
+                    if ((!hold || block === 'center' || !landed) && placement === mine)
+                        drop();
+                    return landed;
+                }
+            };
+        },
+        scrollToMount(path) {
+            writeScroll(() => {
+                const top = resolver?.mountTop(path) ?? null;
+                return top === null ? null : { top };
+            });
+        },
+        keep() {
+            // Closed first, so the position kept is the one the open round's correction leaves.
+            closeRound();
+            const p = writable();
+            const before = p?.scrollTop() ?? 0;
+            return async () => {
+                await tick();
+                // Native anchoring can't undo a max-scroll clamp, so this writes in host mode too.
+                writeScroll(() => !p || placement !== null || p.scrollTop() === before ? null : { top: before });
+            };
+        },
+        release: drop,
+        resolveTargetsWith(next) {
+            resolver = next;
+            return {
+                // The header sits above every list, so its distance adds to the round's.
+                compensate(mutate, held) {
+                    beginRound();
+                    if (open)
+                        open.added += held(mutate);
+                    else
+                        mutate();
+                },
+                uninstall() {
+                    if (resolver === next)
+                        resolver = null;
+                }
+            };
+        }
+    };
+}

package/dist/cursor/scrollport.d.ts

@@ -1,29 +1,28 @@
 /**
- * The scroll container windowing measures and writes, as one shape whatever owns the scroll:
- * the editor root under `scrollMode="self"`, the ancestor `userScrollportFor` resolves (or the
- * page viewport) under `"host"`. One implementation reads this; the mode only picks the target.
+ * The scroll container windowing measures, as one shape whatever owns the scroll: the editor root
+ * under `scrollMode="self"`, the ancestor `userScrollportFor` resolves (or the page viewport) under
+ * `"host"`. Everything outside `cursor/scroll-owner.ts` holds the read-only `ScrollportReader`.
  * See `docs/design/virtual-rendering.md`.
  */
 import type { UserScrollport } from './scroll-ancestors';
-export interface Scrollport {
-    /** Client-coordinate top of the visible box — 0 when the page viewport is the port. Paired
-     *  with a block's own client rect, it maps that block into the port's content space. */
+export interface ScrollportReader {
+    /** Client-coordinate top of the visible box; 0 when the page viewport is the scroll container.
+     *  Paired with a block's own client rect, it maps that block into the container's content space. */
     viewportTop(): number;
     viewportHeight(): number;
-    /** Width available to content, for the height oracle's line-wrap estimates. */
+    /** Width available to content, for the height estimator's line-wrap estimates. */
     contentWidth(): number;
     scrollTop(): number;
+    /** Fires on user and programmatic scrolls alike; returns the unsubscribe. */
+    subscribe(onScroll: () => void): () => void;
+}
+/** The writable scroll container, which only the scroll owner holds. */
+export interface Scrollport extends ScrollportReader {
     setScrollTop(value: number): void;
     /** Move by `delta`. The only relative write: see {@link withRelativeScroll}. */
     scrollBy(delta: number): void;
-    /** Fires on user and programmatic scrolls alike; returns the unsubscribe. */
-    subscribe(onScroll: () => void): () => void;
 }
 export declare function createScrollport(target: UserScrollport): Scrollport;
-/**
- * Adds the relative write every corrector goes through. A scroller snaps a fractional write to
- * a whole device pixel and reports the snapped value back, so a run of relative corrections (a
- * mode flip fires one per re-measured block) would drop that fraction every time and slide the
- * reader's content by the sum. The refused fraction carries into the next call instead.
- */
+/** Adds the relative write every scroll correction goes through. The container snaps a fractional
+ *  write to a device pixel, so the refused fraction is kept, or a run of corrections would drift. */
 export declare function withRelativeScroll(base: Omit<Scrollport, 'scrollBy'>): Scrollport;

package/dist/cursor/scrollport.js

@@ -1,12 +1,8 @@
 export function createScrollport(target) {
     return withRelativeScroll(target === window ? pageScrollport() : elementScrollport(target));
 }
-/**
- * Adds the relative write every corrector goes through. A scroller snaps a fractional write to
- * a whole device pixel and reports the snapped value back, so a run of relative corrections (a
- * mode flip fires one per re-measured block) would drop that fraction every time and slide the
- * reader's content by the sum. The refused fraction carries into the next call instead.
- */
+/** Adds the relative write every scroll correction goes through. The container snaps a fractional
+ *  write to a device pixel, so the refused fraction is kept, or a run of corrections would drift. */
 export function withRelativeScroll(base) {
     let carried = 0;
     let written = null;
@@ -19,13 +15,13 @@ export function withRelativeScroll(base) {
         },
         scrollBy(delta) {
             const from = base.scrollTop();
-            // Anything that moved the port since our own write (the reader, a reveal) leaves the
-            // carried fraction describing a position nobody holds any more.
+            // Anything that moved the scroll container since our own write (the user, a
+            // scroll-into-view) leaves the kept fraction describing a position nobody holds any more.
             const target = from + (written === from ? carried : 0) + delta;
             base.setScrollTop(target);
             written = base.scrollTop();
             const refused = target - written;
-            // Only the snap's own fraction carries; a clamp at either end is a real refusal.
+            // Only the snap's own fraction is kept; a clamp at either end is a real refusal.
             carried = Math.abs(refused) < 1 ? refused : 0;
         }
     };
@@ -46,10 +42,8 @@ function elementScrollport(el) {
         }
     };
 }
-/** The page's own viewport. Measure and write come from different places on purpose, the split
- *  `selection/autoscroll.ts` makes: the viewport is the box the fold belongs to, whereas
- *  `document.scrollingElement` — whose box is the whole multi-thousand-pixel document — is the
- *  only thing that moves. */
+/** The page's own viewport, measured through the visible viewport but written through
+ *  `document.scrollingElement`, the only thing that moves (as `selection/autoscroll.ts` does). */
 function pageScrollport() {
     const scroller = () => document.scrollingElement;
     return {

package/dist/cursor/sticky-column.d.ts

@@ -1,35 +1,12 @@
 /**
- * Sticky column: the editor-relative pixel X that survives repeated vertical arrows and
- * intermediate clamping. Two-axis contract for `focusAtColumn` surfaces. CAPTURE: the focused
- * block records X before any cross-block transition, via `noteKey` (G2.10). CONSUME: landings
- * route through `consumeStickyLanding` (`editor-actions/focus/focus-landing.ts`), which null-checks
- * and falls back, so `focusAtColumn` is a pure receiver whose x is always finite.
- */
-import type { EditorX } from './coordinate-spaces';
-export interface StickyColumnState {
-    get(): EditorX | null;
-    /** Idempotent — the no-op-when-set is what preserves the original intent through
-     *  within-block clamping. Non-finite input is ignored. */
-    capture(x: EditorX): void;
-    reset(): void;
-    /**
-     * The only door a keydown handler may use; `reset()` stays public for the lifecycle,
-     * commit, undo and paste callers, whose unconditional clear has no key to classify.
-     * `measureX` is consulted only on the capture branch and only the caller can supply it
-     * (the X comes from the live caret) — a caller holding a range rather than a caret
-     * omits it, and a capture key then PRESERVES the column rather than clearing it.
-     */
-    noteKey(e: Pick<KeyboardEvent, 'key' | 'altKey'>, measureX?: () => EditorX | null): void;
-}
-export declare function createStickyColumnState(): StickyColumnState;
-/**
- * Keys that neither capture nor reset; every key not here and not a vertical arrow resets.
- * Bare modifiers are read from the chord parser rather than re-listed — a local copy
- * missing AltGraph/CapsLock is how a modifier tap mid-arrow-run dropped the column.
+ * What a keydown does to the sticky column, the editor-relative x that survives repeated
+ * vertical arrows and clamping on shorter lines. The column itself lives in the caret memory
+ * (`cursor/caret-memory.ts`); the arriving block reads it through `consumeStickyLanding`.
  */
+/** Keys that neither capture nor reset; any other key but a vertical arrow resets. Bare modifiers
+ *  come from the key-combination parser, which knows AltGraph and CapsLock. */
 export declare const PRESERVE_KEYS_NON_ARROW: readonly string[];
 /** What a keydown does to sticky column, decided purely from `e.key`. */
 export type StickyKeyAction = 'capture' | 'reset' | 'preserve';
-/** The decision {@link StickyColumnState.noteKey} enacts. Pure on the key, so the matrix is
- *  testable without a DOM or a state instance. */
+/** Pure on the key, so the matrix is testable without a DOM or a memory instance. */
 export declare function classifyStickyKey(key: string): StickyKeyAction;

package/dist/cursor/sticky-column.js

@@ -1,60 +1,17 @@
 /**
- * Sticky column: the editor-relative pixel X that survives repeated vertical arrows and
- * intermediate clamping. Two-axis contract for `focusAtColumn` surfaces. CAPTURE: the focused
- * block records X before any cross-block transition, via `noteKey` (G2.10). CONSUME: landings
- * route through `consumeStickyLanding` (`editor-actions/focus/focus-landing.ts`), which null-checks
- * and falls back, so `focusAtColumn` is a pure receiver whose x is always finite.
+ * What a keydown does to the sticky column, the editor-relative x that survives repeated
+ * vertical arrows and clamping on shorter lines. The column itself lives in the caret memory
+ * (`cursor/caret-memory.ts`); the arriving block reads it through `consumeStickyLanding`.
  */
-import { isInteractionTraceEnabled, traceStickyCapture, traceStickyReset } from '../debug/interaction-trace';
 import { BARE_MODIFIER_KEYS } from '../schema/keybindings';
-export function createStickyColumnState() {
-    let stickyX = null;
-    const state = {
-        get: () => stickyX,
-        capture: (x) => {
-            if (stickyX !== null)
-                return;
-            if (!Number.isFinite(x))
-                return;
-            stickyX = x;
-            traceStickyCapture(x);
-        },
-        // Reset fires on nearly every keystroke, so the enabled gate short-circuits first.
-        reset: () => {
-            if (isInteractionTraceEnabled() && stickyX !== null)
-                traceStickyReset();
-            stickyX = null;
-        },
-        noteKey: (e, measureX) => {
-            // Alt+Arrow is the block-reorder chord, not caret nav.
-            if (e.altKey && (e.key === 'ArrowUp' || e.key === 'ArrowDown'))
-                return;
-            const action = classifyStickyKey(e.key);
-            if (action === 'reset') {
-                state.reset();
-                return;
-            }
-            if (action !== 'capture')
-                return;
-            const x = measureX?.();
-            if (x !== null && x !== undefined)
-                state.capture(x);
-        }
-    };
-    return state;
-}
-/**
- * Keys that neither capture nor reset; every key not here and not a vertical arrow resets.
- * Bare modifiers are read from the chord parser rather than re-listed — a local copy
- * missing AltGraph/CapsLock is how a modifier tap mid-arrow-run dropped the column.
- */
+/** Keys that neither capture nor reset; any other key but a vertical arrow resets. Bare modifiers
+ *  come from the key-combination parser, which knows AltGraph and CapsLock. */
 export const PRESERVE_KEYS_NON_ARROW = [
     'PageUp',
     'PageDown',
     ...BARE_MODIFIER_KEYS
 ];
-/** The decision {@link StickyColumnState.noteKey} enacts. Pure on the key, so the matrix is
- *  testable without a DOM or a state instance. */
+/** Pure on the key, so the matrix is testable without a DOM or a memory instance. */
 export function classifyStickyKey(key) {
     if (key === 'ArrowUp' || key === 'ArrowDown')
         return 'capture';

package/dist/cursor/sticky-measure.d.ts

@@ -4,13 +4,18 @@
  */
 import type { StickyColumnDirection } from '../block-component';
 import { type DomTextOffset, type EditorX } from './coordinate-spaces';
+import { type CaretRect } from './visual-lines';
 export declare function getCurrentCursorEditorRelativeX(el: HTMLElement): EditorX | null;
-export declare function getOffsetRect(container: HTMLElement, offset: DomTextOffset): DOMRect | 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 declare function findOffsetNearestX(container: HTMLElement, editorRelativeX: EditorX, from: StickyColumnDirection, minOffset?: DomTextOffset): DomTextOffset;
+export interface CaretProbe {
+    offset: DomTextOffset;
+    rect: CaretRect;
+    /** The position has no box of its own and borrowed the neighbouring widget's, so nothing
+     *  paints a caret there: a landing of last resort. */
+    borrowed: boolean;
+}
+/** 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 declare function caretBoxAt(container: HTMLElement, offset: DomTextOffset): CaretProbe | null;
+/** 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 declare function findOffsetNearestX(container: HTMLElement, editorRelativeX: EditorX, from: StickyColumnDirection, minOffset?: DomTextOffset, maxOffset?: DomTextOffset): DomTextOffset;