@voithos-labs/aragonite 0.10.1

package/dist/editor-actions/container-block-component.js

@@ -0,0 +1,228 @@
+/** Shared `BlockComponent` shim for container blocks. */
+import { CURSOR_END, CURSOR_EXACT_START, CURSOR_START, FOCUS_LAST_START } from '../block-component';
+import { dispatchFocusByPath, dispatchFocusAtColumn, dispatchGetBlockComponentByPath } from './focus/focus-dispatch';
+import { revealChildOrWait } from '../reactivity/publish-ref.svelte';
+import { runGlobalChordOnKind } from '../schema/commands';
+import { isCharacterKey } from '../schema/keybindings';
+import { displayLength, trimTrailingLineEnding } from '../core/lines';
+import { isVerticallyTransparentNode } from '../core/inline/transparency';
+import { placeCaret } from '../selection/caret-doors';
+import { focusWholeBlockEl, holdsWholeBlockFocus } from './whole-block-focus-surface';
+import { devWarn } from '../dev-warn';
+/**
+ * Undo/redo for a block that IS its own focus target: no inner leaf carries the global tier for
+ * it, and the editor root declines while focus sits on the block. `true` means consumed —
+ * including in reading mode, since bypassing `dispatchKeyCommand` would otherwise hand a read-only
+ * document the browser's native undo.
+ */
+export function handleEditorGlobalChord(chord, deps) {
+    return runGlobalChordOnKind(chord, deps.getKind(), deps.getKeybindingOverrides(), {
+        isReading: deps.isReading(),
+        history: deps.history,
+        pluginEditor: deps.pluginEditor,
+        onCommandError: deps.onCommandError,
+        activation: deps.activation
+    });
+}
+/**
+ * The four plain-arrow exits out of a block, in the direction the key points. Shared by
+ * whole-block focus and the plugin container's `moveFocusOut`, so a surface that reaches its
+ * own edge lands the same way the built-ins do. False for any other key.
+ */
+export function focusAcrossBlockEdge(key, deps) {
+    const index = deps.getIndex();
+    if (key === 'ArrowUp')
+        void deps.focus.moveFocus(index - 1, { stickyColumnFrom: 'below' });
+    else if (key === 'ArrowLeft')
+        void deps.focus.moveFocus(index - 1, 'end');
+    else if (key === 'ArrowDown')
+        void deps.focus.moveFocus(index + 1, { stickyColumnFrom: 'above' });
+    else if (key === 'ArrowRight')
+        void deps.focus.moveFocus(index + 1, 'start');
+    else
+        return false;
+    return true;
+}
+/**
+ * The whole-block-focus key tail shared by ThematicBreakBlock and the plugin container
+ * factory, so a new gate lands once instead of at both. Navigation never gates.
+ */
+export function handleWholeBlockKeys(e, deps) {
+    // The classification doors, before any branch: skipping them let a column captured
+    // outside survive a horizontal traversal through, and the arrival side the exit lands
+    // with is the same one an arrow means anywhere. No `measureX` — no caret here.
+    deps.stickyColumn.noteKey(e);
+    deps.edgeAffinity.note(e);
+    if (e.key === 'Enter') {
+        e.preventDefault();
+        if (!deps.isReading())
+            void deps.blockEdit.splitBlock(deps.getIndex(), displayLength(deps.getRaw()));
+        return;
+    }
+    if (e.key === 'Backspace' || e.key === 'Delete') {
+        e.preventDefault();
+        if (!deps.isReading())
+            void deps.blockEdit.deleteBlock(deps.getIndex());
+        return;
+    }
+    // Mod+C / Mod+X on the block's own markdown: a keydown carries no ClipboardEvent,
+    // and preventDefault suppresses the native copy, so writeText is the sole writer.
+    if ((e.ctrlKey || e.metaKey) && !e.altKey && !e.shiftKey && (e.key === 'c' || e.key === 'x')) {
+        e.preventDefault();
+        void copyFocusedWholeBlock(deps, e.key === 'x');
+        return;
+    }
+    // A typed character has nowhere to land on a block that IS its own focus target, so it mints
+    // the paragraph below carrying it (`editor-actions/block-edit-core.ts :: insertParagraph`).
+    if (isCharacterKey(e.key) && !e.isComposing && !e.ctrlKey && !e.metaKey && !e.altKey) {
+        e.preventDefault();
+        if (!deps.isReading())
+            void deps.blockEdit.insertParagraph(deps.getIndex() + 1, e.key);
+        return;
+    }
+    const plainArrow = !e.altKey && !e.ctrlKey && !e.metaKey;
+    if (plainArrow && focusAcrossBlockEdge(e.key, deps))
+        e.preventDefault();
+}
+// Copy is a read, so it never gates; cut's delete gates on reading mode and only runs
+// once the write resolves, so a rejected write leaves the block in place.
+async function copyFocusedWholeBlock(deps, cut) {
+    try {
+        await navigator.clipboard.writeText(trimTrailingLineEnding(deps.getRaw()));
+    }
+    catch (err) {
+        devWarn('container-block', 'whole-block clipboard write rejected', err);
+        return;
+    }
+    if (cut && !deps.isReading())
+        void deps.blockEdit.deleteBlock(deps.getIndex());
+}
+export function createContainerBlockComponent(deps) {
+    const landFocus = (declared) => deps.inputProxy ? deps.inputProxy.focus(declared) : focusWholeBlockEl(declared);
+    /**
+     * `focus` lands in a child that never forwarded the park door; `parkCaret` skips it,
+     * because for an extend a missed park costs a caret and `focus` costs the range.
+     */
+    function walkInto(offset, land) {
+        // Whole-block focus: any caret entry lands on the block itself, so the element
+        // offset carries no meaning.
+        const focusEl = deps.getFocusEl?.();
+        if (focusEl) {
+            landFocus(focusEl);
+            return;
+        }
+        if (deps.nodeChildrenLength === 0)
+            return;
+        // Collapsed: only the chrome row is mounted, so a walk-in from below clamps to
+        // it rather than no-oping on the unmounted last child.
+        const last = deps.isCollapsed?.() ? 0 : deps.nodeChildrenLength - 1;
+        const entersFirst = offset === 0 || offset === CURSOR_START || offset === CURSOR_EXACT_START;
+        const child = entersFirst ? deps.innerBlockRefs[0] : deps.innerBlockRefs[last];
+        if (!child)
+            return;
+        if (offset === FOCUS_LAST_START)
+            land(child, FOCUS_LAST_START);
+        else if (entersFirst)
+            land(child, offset);
+        else
+            land(child, CURSOR_END);
+    }
+    function parkCaret(offset) {
+        walkInto(offset, (child, at) => child.parkCaret?.(at));
+    }
+    return {
+        get editable() {
+            return deps.editable ?? true;
+        },
+        focusable: true,
+        focus: placeCaret(deps.selection, (offset) => walkInto(offset, (child, at) => child.focus(at))),
+        parkCaret,
+        getCursorOffset() {
+            const focusEl = deps.getFocusEl?.();
+            if (focusEl)
+                return holdsWholeBlockFocus(focusEl, deps.inputProxy?.el()) ? 0 : null;
+            for (const ref of deps.innerBlockRefs) {
+                const offset = ref?.getCursorOffset();
+                if (offset !== null && offset !== undefined)
+                    return offset;
+            }
+            return null;
+        },
+        getCursorPosition() {
+            for (let i = 0; i < deps.innerBlockRefs.length; i++) {
+                const ref = deps.innerBlockRefs[i];
+                if (!ref)
+                    continue;
+                const subPos = ref.getCursorPosition?.();
+                if (subPos)
+                    return { path: [i, ...subPos.path], offset: subPos.offset };
+                const offset = ref.getCursorOffset();
+                if (offset !== null && offset !== undefined)
+                    return { path: [i], offset };
+            }
+            return null;
+        },
+        focusByPath(path, offset) {
+            dispatchFocusByPath(deps.innerBlockRefs, path, offset);
+        },
+        getBlockComponentByPath(path) {
+            return dispatchGetBlockComponentByPath(deps.innerBlockRefs, path);
+        },
+        async revealByPath(path) {
+            if (path.length === 0)
+                return null;
+            const [head, ...rest] = path;
+            // Only a body target needs the door opened; the chrome row stays mounted.
+            // Awaited because everything below must run against the post-commit window.
+            if (head >= 1 && deps.isCollapsed?.())
+                await deps.expandCollapsed?.();
+            if (deps.revealChild) {
+                await revealChildOrWait(head, {
+                    slots: deps.refSlots,
+                    childCount: deps.nodeChildrenLength,
+                    revealChild: deps.revealChild,
+                    isInWindow: deps.isInWindow
+                });
+            }
+            const ref = deps.innerBlockRefs[head];
+            if (!ref)
+                return null;
+            if (rest.length === 0)
+                return ref;
+            return ref.revealByPath
+                ? ref.revealByPath(rest)
+                : (ref.getBlockComponentByPath?.(rest) ?? null);
+        },
+        focusAtColumn(x, from) {
+            // Whole-block focus has no column to land in, so a vertical entry focuses the
+            // block itself, mirroring the plain-arrow path.
+            const focusEl = deps.getFocusEl?.();
+            if (focusEl) {
+                landFocus(focusEl);
+                return;
+            }
+            if (deps.nodeChildrenLength === 0)
+                return;
+            dispatchFocusAtColumn(deps.innerBlockRefs, x, from);
+        },
+        isVerticallyTransparent() {
+            return isVerticallyTransparentNode(deps.node);
+        },
+        enterEdgeWidget(side) {
+            if (deps.nodeChildrenLength === 0)
+                return false;
+            const edge = side === 'start' ? 0 : deps.nodeChildrenLength - 1;
+            return deps.innerBlockRefs[edge]?.enterEdgeWidget?.(side) ?? false;
+        },
+        measurePartialRects(start, end) {
+            // Opaque single-unit: a childless container paints the whole box. A
+            // child-bearing one returns nothing — the overlay routes to its children.
+            if (deps.nodeChildrenLength > 0)
+                return [];
+            const box = deps.getBoxEl?.();
+            if (!box || end <= start)
+                return [];
+            return [box.getBoundingClientRect()];
+        }
+    };
+}

package/dist/editor-actions/container-edit.d.ts

@@ -0,0 +1,7 @@
+/**
+ * ContainerEditActions factory: the debounced checkpoint pusher for raw typing
+ * outside the commit primitive, the doc-root reactivity nudge, and `commitContainer`.
+ */
+import type { ContainerEditActions } from '../action-contracts';
+import type { EditorActionsDeps, UndoController } from './deps';
+export declare function createContainerEditActions(deps: EditorActionsDeps, controller: UndoController): ContainerEditActions;

package/dist/editor-actions/container-edit.js

@@ -0,0 +1,49 @@
+/**
+ * ContainerEditActions factory: the debounced checkpoint pusher for raw typing
+ * outside the commit primitive, the doc-root reactivity nudge, and `commitContainer`.
+ */
+import { ensureUnsharedPath, rebuildUnsharedChain } from '../tree-operations/unshare';
+import { publishAncestryFolds, publishScopeFold } from './ancestry-folds';
+export function createContainerEditActions(deps, controller) {
+    return {
+        pushDebouncedCheckpoint(leafPath, offset, batchKey) {
+            deps.stickyColumn.reset();
+            deps.edgeAffinity.reset();
+            controller.pushUndoSnapshotDebounced(leafPath, offset, batchKey);
+        },
+        armDebouncedPause() {
+            controller.armUndoPause();
+        },
+        nudgeReactivity() {
+            // Raw mutations made outside the commit primitive surface through this nudge,
+            // so Svelte re-reads doc.children.
+            deps.doc.children = [...deps.doc.children];
+        },
+        withUnsharedSpine(absPath, write) {
+            const chain = ensureUnsharedPath(deps.doc, absPath, deps.sharing);
+            // Read before the write: it is the one byte-state no level of the rebuild can capture
+            // for itself, and the ancestry splice needs it to place the leaf's own region.
+            const leafPreviousRaw = chain[chain.length - 1]?.raw;
+            const written = write(chain, deps.sharing) ?? { op: 'noop' };
+            // Unconditional: this door exists to carry bytes, and a short chain or a `noop`
+            // settle says nothing about whether `write` moved any.
+            deps.bumpContentVersion();
+            // The write's own settle can splice the scope it wrote in, and a short chain means the
+            // unshare never reached that scope, so there is nothing to publish against.
+            if (chain.length === absPath.length) {
+                publishScopeFold(deps, chain[absPath.length - 2], written);
+            }
+            // The ANCESTRY settle's folds — a container's own slot in its PARENT, not the write's
+            // scope published above. Their unwind is discarded on purpose: nothing rolls back at a
+            // door that is not a ceremony. Their caret landing (`foldLandingFor`) wants a tick this
+            // synchronous door has not got, and no producer reaches one.
+            const folds = [];
+            const replacements = rebuildUnsharedChain(deps.doc, chain, deps.sharing, folds, deps.grammar, leafPreviousRaw === undefined ? undefined : { path: absPath, leafPreviousRaw });
+            publishAncestryFolds(deps, folds);
+            return replacements.length > 0;
+        },
+        commitContainer(args) {
+            return controller.commitContainerStructural(args);
+        }
+    };
+}

package/dist/editor-actions/container-exit-overrides.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Override factory every plugin-seam container shares: the Enter-on-empty-last-child exit.
+ * Backspace unwrap (U2) is declaration-driven — the kind's `unwrapRole` selects strategies
+ * in `unwrap-strategies.ts`.
+ */
+import type { BlockEditActions } from '../action-contracts';
+import type { NestedActionsBundle, NodeScope } from './nested/nested-actions';
+export interface ContainerExitOverridesDeps {
+    scope: NodeScope;
+    parentBlockEdit: BlockEditActions;
+}
+export declare function createContainerExitOverrides(deps: ContainerExitOverridesDeps): (defaults: NestedActionsBundle) => {
+    blockEdit: {
+        splitBlock: (innerIndex: number, offset: number) => Promise<void>;
+    };
+};

package/dist/editor-actions/container-exit-overrides.js

@@ -0,0 +1,38 @@
+/**
+ * Override factory every plugin-seam container shares: the Enter-on-empty-last-child exit.
+ * Backspace unwrap (U2) is declaration-driven — the kind's `unwrapRole` selects strategies
+ * in `unwrap-strategies.ts`.
+ */
+import { displayLength } from '../core/lines';
+import { buildQuoteExitReplacement } from '../tree-operations/blockquote';
+export function createContainerExitOverrides(deps) {
+    return (defaults) => ({
+        blockEdit: {
+            // Enter on an empty trailing paragraph exits the container instead of appending another
+            // inner line, and MINTS the blank it lands on: Enter is never down-nav, so a block
+            // below is left alone and a nested container is escaped one level per press.
+            splitBlock: async (innerIndex, offset) => {
+                const { parentBlockEdit } = deps;
+                const { node, index } = deps.scope;
+                if (!node.children)
+                    return;
+                const child = node.children[innerIndex];
+                const isLastChild = innerIndex === node.children.length - 1;
+                const isEmpty = child.kind === 'paragraph' && child.raw.trim() === '';
+                if (isLastChild && isEmpty) {
+                    if (node.children.length <= 1) {
+                        await parentBlockEdit.splitBlock(index, displayLength(node.raw));
+                    }
+                    else {
+                        await parentBlockEdit.replaceBlock(index, buildQuoteExitReplacement(node), {
+                            replacementIndex: 1,
+                            offset: 0
+                        });
+                    }
+                    return;
+                }
+                return defaults.blockEdit.splitBlock(innerIndex, offset);
+            }
+        }
+    });
+}

package/dist/editor-actions/deps.d.ts

@@ -0,0 +1,60 @@
+import type { BlockComponent } from '../block-component';
+import type { Document } from '../core/nodes';
+import type { StickyColumnState } from '../cursor/sticky-column';
+import type { EdgeAffinityState } from '../cursor/edge-affinity';
+import type { BlockElLookup, PresentationModeGetter } from '../editor-keys';
+import type { SelectionState } from '../selection/selection-state.svelte';
+import type { UndoEntry, UndoManager } from '../undo/types';
+import type { SharingState } from '../tree-operations/sharing';
+import type { EditorEvents } from '../editor-events';
+import type { CommitController } from '../action-contracts';
+import type { GrammarView } from '../schema/block-openers';
+import type { InlineResolverRef } from '../schema/inline-construct-policy';
+import type { RefSlots } from '../reactivity/publish-ref.svelte';
+export interface EditorActionsDeps {
+    get doc(): Document;
+    get blockIds(): string[];
+    get blockRefs(): (BlockComponent | undefined)[];
+    /** The top-level scope's slot identity, so the doc-scope adapter reports the same
+     *  scope the editor's own BlockList publishes into. */
+    blockRefSlots: RefSlots<BlockComponent>;
+    setDoc(doc: Document): void;
+    setBlockIds(ids: string[]): void;
+    setBlockRefs(refs: (BlockComponent | undefined)[]): void;
+    /** Announce that this door moved the document's bytes
+     *  (`reactivity/content-version.svelte.ts`). The ceremony owes one call per commit; the
+     *  writers outside it owe their own, which is the census G4.52 keeps honest. */
+    bumpContentVersion(): void;
+    undoManager: UndoManager;
+    sharing: SharingState;
+    stickyColumn: StickyColumnState;
+    edgeAffinity: EdgeAffinityState;
+    selectionState: SelectionState;
+    getBlockElByPath: BlockElLookup;
+    /** Scroll an off-window top-level block into the render window and await its
+     *  mount, then return its component (null if unreachable). Already-mounted
+     *  targets return synchronously without scrolling. */
+    revealPath(path: number[]): Promise<BlockComponent | null>;
+    events: EditorEvents;
+    /** The instance's block grammar, so a disabled kind's opener stays skipped when
+     *  the editor re-parses an edited block. Absent = the global grammar. */
+    grammar?: GrammarView;
+    /** Live EFFECTIVE mode, for the seams that must not act in reading mode. Absent in
+     *  harnesses, which `isReadingMode` reads as not-reading. */
+    getPresentationMode?: PresentationModeGetter;
+    /** The instance's link-reference resolver, for the byte rewrites that must parse the reference
+     *  forms the render path drew. Absent in harnesses, which have no definitions to resolve. */
+    linkRef?: InlineResolverRef;
+}
+/**
+ * The history-typed members added to the contracts-leaf `CommitController`. They stay here so
+ * that leaf keeps no edge to `undo/`.
+ */
+export interface UndoController extends CommitController {
+    captureCurrentState(): UndoEntry;
+    /** Monotonic stamp of the last history swap. A caret landing captures it before its
+     *  reveal and declines when it moved: the tree it was aimed at is no longer on screen. */
+    historyGeneration(): number;
+    /** Announce a swap. The restore road's own call — nothing else may bump it. */
+    noteHistorySwap(): void;
+}

package/dist/editor-actions/deps.js

@@ -0,0 +1 @@
+export {};

package/dist/editor-actions/enter-completion.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The Enter-completion seam: a lone typed line a registered completer claims becomes the
+ * structure it opens instead of splitting. `planEnterCompletion` is pure; `withEnterCompletion`
+ * is the one place the plan is spent, wrapped around a composed `splitBlock`.
+ */
+import type { BlockEditActions } from '../action-contracts';
+import type { CstNode } from '../core/nodes';
+import type { NodeView } from '../core/node-views';
+export interface EnterCompletion {
+    replacement: CstNode[];
+    caret: {
+        path: number[];
+        offset: number;
+    };
+}
+/**
+ * Wraps a COMPOSED `splitBlock` with the consult, at the two bundle composition sites only. Above
+ * the container overrides rather than inside the split body, so a container that replaces
+ * `splitBlock` cannot take the completion arm out of its subtree. One press consults once per
+ * NODE: the blockquote exit's hop to the parent scope is a second consult, on a different node,
+ * and an always-declining one — a container is never a prose line.
+ */
+export declare function withEnterCompletion(blockEdit: BlockEditActions, childAt: (index: number) => NodeView | undefined): BlockEditActions;
+/** The completion a press at `offset` earns, or null when the block or the caret disqualifies it. */
+export declare function planEnterCompletion(node: NodeView | undefined, offset: number): EnterCompletion | null;

package/dist/editor-actions/enter-completion.js

@@ -0,0 +1,76 @@
+/**
+ * The Enter-completion seam: a lone typed line a registered completer claims becomes the
+ * structure it opens instead of splitting. `planEnterCompletion` is pure; `withEnterCompletion`
+ * is the one place the plan is spent, wrapped around a composed `splitBlock`.
+ */
+import { parse } from '../core/parser';
+import { displayLength, splitLines, trailingLineEnding } from '../core/lines';
+import { getBlockKindDescriptor } from '../schema/block-kind-descriptor';
+import { completeTypedLine } from '../schema/block-completions';
+/**
+ * Wraps a COMPOSED `splitBlock` with the consult, at the two bundle composition sites only. Above
+ * the container overrides rather than inside the split body, so a container that replaces
+ * `splitBlock` cannot take the completion arm out of its subtree. One press consults once per
+ * NODE: the blockquote exit's hop to the parent scope is a second consult, on a different node,
+ * and an always-declining one — a container is never a prose line.
+ */
+export function withEnterCompletion(blockEdit, childAt) {
+    return {
+        ...blockEdit,
+        async splitBlock(index, offset) {
+            const completion = planEnterCompletion(childAt(index), offset);
+            if (!completion) {
+                await blockEdit.splitBlock(index, offset);
+                return;
+            }
+            // `snapshotOffset` is where the caret WAS, so one undo restores the typed line with the
+            // caret at its end rather than in front of it.
+            await blockEdit.replaceBlock(index, completion.replacement, { replacementIndex: 0, ...completion.caret }, { snapshotOffset: offset });
+        }
+    };
+}
+/** The completion a press at `offset` earns, or null when the block or the caret disqualifies it. */
+export function planEnterCompletion(node, offset) {
+    if (!node)
+        return null;
+    const line = wholeTypedLine(node);
+    if (line === null || offset !== displayLength(node.raw))
+        return null;
+    const claim = completeTypedLine(line);
+    if (!claim)
+        return null;
+    // Through the parser rather than a hand-built node, so the mint is exactly what a reload of
+    // those bytes produces. Global grammar, as every other structural reparse.
+    const lineEnding = trailingLineEnding(node.raw);
+    const raw = claim.lines.map((text) => text + lineEnding).join('');
+    const replacement = parse(raw, { scope: 'fragment' }).children;
+    // A mint that paints nothing would replace the typed line with a delete, or with blank trivia
+    // a reload reads as neither. Blank lines parse back as empty paragraphs, so the reading is per
+    // node rather than the child count.
+    if (replacement.every((node) => node.raw.trim() === ''))
+        return null;
+    return { replacement, caret: resolveCaret(replacement[0], claim.caret) };
+}
+/** The claim's line/column as a byte offset inside the node its path addresses. Resolved here
+ *  because the line ending the count depends on is the seam's choice, not the completer's. */
+function resolveCaret(minted, caret) {
+    let target = minted;
+    for (const index of caret.path)
+        target = target?.children?.[index];
+    const lines = target ? splitLines(target.raw) : [];
+    return { path: caret.path, offset: (lines[caret.line]?.start ?? 0) + caret.column };
+}
+/** The one line this block's raw is, or null when it is not a single line of prose whose every
+ *  byte is content — a completer must never read a kind's own markers as typed text. */
+function wholeTypedLine(node) {
+    const descriptor = getBlockKindDescriptor(node.kind);
+    if (descriptor.mergeRole !== 'prose')
+        return null;
+    const lines = splitLines(node.raw);
+    if (lines.length !== 1)
+        return null;
+    const content = descriptor.getContentRange?.(node);
+    if (content && (content.start !== 0 || content.end !== displayLength(node.raw)))
+        return null;
+    return lines[0].text;
+}

package/dist/editor-actions/focus/focus-dispatch.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure dispatchers for container focus — moveFocus, focusByPath, focusAtColumn.
+ * No Svelte context or reactivity; inputs are passed in as parameters.
+ */
+import type { FocusActions, MoveFocusOptions } from '../../action-contracts';
+import { type BlockComponent, type FocusPosition, type StickyColumnDirection } from '../../block-component';
+import type { StickyColumnState } from '../../cursor/sticky-column';
+/** What the calling scope contributes to a move beyond the target itself. */
+export interface MoveFocusScope {
+    /** Overrides `refs.length` for the upper bound: the two diverge for one render cycle
+     *  after a structural op, and without it the cursor escapes the container. */
+    childCount?: number;
+    /** The caller's own options, forwarded verbatim on upward delegation. */
+    options?: MoveFocusOptions;
+    /** Pre-bound to this scope's own boundaries (`selection/gap-caret.ts`). */
+    gapStop?: (boundaryIndex: number) => boolean;
+}
+/** Move focus within a container, or delegate upward when out of range. */
+export declare function dispatchMoveFocus(refs: (BlockComponent | undefined)[], innerIndex: number, position: FocusPosition, stickyColumn: StickyColumnState, parent: {
+    focus: FocusActions;
+    index: number;
+}, scope?: MoveFocusScope): Promise<void>;
+/**
+ * Direction a FocusPosition implies for traversal. A bare numeric offset is a
+ * targeted landing with no direction, so 0 tells the caller not to skip.
+ */
+export declare function traversalStep(position: FocusPosition): -1 | 0 | 1;
+/**
+ * Adjacent-only contract (VR-12, docs/design/virtual-rendering.md): sync, revealing
+ * nothing, so an unmounted `refs[first]` silently no-ops. The caller keeps the target
+ * within overscan; anything wider routes through the async `revealByPath`/`revealPath`.
+ */
+export declare function dispatchFocusByPath(refs: (BlockComponent | undefined)[], path: number[], offset: number): void;
+/** Null when the path doesn't resolve to a mounted ref. */
+export declare function dispatchGetBlockComponentByPath(refs: (BlockComponent | undefined)[], path: number[]): BlockComponent | null;
+export declare function dispatchFocusAtColumn(refs: (BlockComponent | undefined)[], x: number, from: StickyColumnDirection): void;

package/dist/editor-actions/focus/focus-dispatch.js

@@ -0,0 +1,106 @@
+/**
+ * Pure dispatchers for container focus — moveFocus, focusByPath, focusAtColumn.
+ * No Svelte context or reactivity; inputs are passed in as parameters.
+ */
+import { CURSOR_END, CURSOR_START } from '../../block-component';
+import { consumeStickyLanding } from './focus-landing';
+/** Move focus within a container, or delegate upward when out of range. */
+export async function dispatchMoveFocus(refs, innerIndex, position, stickyColumn, parent, scope = {}) {
+    const { childCount, options, gapStop } = scope;
+    // Omit the options arg when unset so the common path stays a two-arg call.
+    const delegate = (targetIndex) => options
+        ? parent.focus.moveFocus(targetIndex, position, options)
+        : parent.focus.moveFocus(targetIndex, position);
+    const step = traversalStep(position);
+    // Ahead of every ref read, so the CST alone decides the boundary and a windowed-out
+    // child cannot change the answer. The two scope edges are boundaries like any other:
+    // this is also what stops the delegate arms from leaving the container.
+    if (gapStop && step !== 0 && !options?.skipGapStop) {
+        if (gapStop(step > 0 ? innerIndex : innerIndex + 1))
+            return;
+    }
+    if (innerIndex < 0) {
+        await delegate(parent.index - 1);
+        return;
+    }
+    const upperBound = childCount ?? refs.length;
+    if (innerIndex >= upperBound) {
+        await delegate(parent.index + 1);
+        return;
+    }
+    const block = refs[innerIndex];
+    if (!block?.focusable) {
+        // A refless or non-focusable child must not dead-end the move — continue in
+        // its direction (editor.md § Focus traversal).
+        if (step !== 0) {
+            await dispatchMoveFocus(refs, innerIndex + step, position, stickyColumn, parent, scope);
+        }
+        return;
+    }
+    await consumeStickyLanding(block, innerIndex, position, stickyColumn, (i) => dispatchMoveFocus(refs, i, position, stickyColumn, parent, scope));
+}
+/**
+ * Direction a FocusPosition implies for traversal. A bare numeric offset is a
+ * targeted landing with no direction, so 0 tells the caller not to skip.
+ */
+export function traversalStep(position) {
+    if (typeof position === 'object')
+        return position.stickyColumnFrom === 'below' ? -1 : 1;
+    if (position === 'start')
+        return 1;
+    if (position === 'end')
+        return -1;
+    return 0;
+}
+/**
+ * Adjacent-only contract (VR-12, docs/design/virtual-rendering.md): sync, revealing
+ * nothing, so an unmounted `refs[first]` silently no-ops. The caller keeps the target
+ * within overscan; anything wider routes through the async `revealByPath`/`revealPath`.
+ */
+export function dispatchFocusByPath(refs, path, offset) {
+    if (path.length === 0) {
+        refs[0]?.focus(offset);
+        return;
+    }
+    const [first, ...rest] = path;
+    const child = refs[first];
+    if (!child)
+        return;
+    if (rest.length === 0) {
+        child.focus(offset);
+    }
+    else {
+        child.focusByPath?.(rest, offset);
+    }
+}
+/** Null when the path doesn't resolve to a mounted ref. */
+export function dispatchGetBlockComponentByPath(refs, path) {
+    if (path.length === 0)
+        return null;
+    const [first, ...rest] = path;
+    const child = refs[first];
+    if (!child)
+        return null;
+    if (rest.length === 0)
+        return child;
+    return child.getBlockComponentByPath?.(rest) ?? null;
+}
+export function dispatchFocusAtColumn(refs, x, from) {
+    if (refs.length === 0)
+        return;
+    const indices = from === 'above' ? refs.map((_, i) => i) : refs.map((_, i) => refs.length - 1 - i);
+    // Skip vertically-transparent refs so an entry from above/below lands on the
+    // first/last text-bearing child, not an image-only paragraph.
+    for (const i of indices) {
+        const ref = refs[i];
+        if (!ref?.focusable)
+            continue;
+        if (ref.isVerticallyTransparent?.())
+            continue;
+        if (ref.focusAtColumn)
+            ref.focusAtColumn(x, from);
+        else
+            ref.focus(from === 'above' ? CURSOR_START : CURSOR_END);
+        return;
+    }
+}

package/dist/editor-actions/focus/focus-landing.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared cross-block landing tail for the focus dispatchers. Sticky-X null handling
+ * lives here, so `focusAtColumn` receivers always get a finite x.
+ */
+import { type BlockComponent, type FocusPosition } from '../../block-component';
+import type { StickyColumnState } from '../../cursor/sticky-column';
+export declare function consumeStickyLanding(block: BlockComponent, index: number, position: FocusPosition, stickyColumn: StickyColumnState, retryAt: (index: number) => Promise<void> | void): Promise<void>;