@voithos-labs/aragonite 0.10.4 → 0.10.7

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

@@ -1,11 +1,13 @@
 /**
- * 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`.
+ * Enter completion: a lone typed line a registered completer recognises becomes the structure
+ * it opens instead of splitting. `planEnterCompletion` is pure; `withEnterCompletion` is the
+ * one place the plan is applied, wrapped around a composed `splitBlock`.
  */
+import { type LineEnding } from '../core/lines';
 import type { BlockEditActions } from '../action-contracts';
 import type { CstNode } from '../core/nodes';
 import type { NodeView } from '../core/node-views';
+import type { GrammarView } from '../schema/block-openers';
 export interface EnterCompletion {
     replacement: CstNode[];
     caret: {
@@ -13,15 +15,10 @@ export interface EnterCompletion {
         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;
-/** The completion a keystroke earns, consulting only the completers that answer on type. */
-export declare function planTypedCompletion(node: NodeView | undefined, offset: number): EnterCompletion | null;
+/** Wraps a composed `splitBlock` with the completer check, above the container overrides so a
+ *  container replacing `splitBlock` keeps the completion for its subtree. */
+export declare function withEnterCompletion(blockEdit: BlockEditActions, childAt: (index: number) => NodeView | undefined, grammar: GrammarView, getLineEnding: () => LineEnding): BlockEditActions;
+/** The completion Enter at `offset` produces, or null when the block or the caret rules it out. */
+export declare function planEnterCompletion(node: NodeView | undefined, offset: number, grammar: GrammarView, lineEnding: LineEnding): EnterCompletion | null;
+/** The completion a keystroke produces, asking only the completers that answer on type. */
+export declare function planTypedCompletion(node: NodeView | undefined, offset: number, grammar: GrammarView, lineEnding: LineEnding): EnterCompletion | null;

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

@@ -1,57 +1,56 @@
 /**
- * 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`.
+ * Enter completion: a lone typed line a registered completer recognises becomes the structure
+ * it opens instead of splitting. `planEnterCompletion` is pure; `withEnterCompletion` is the
+ * one place the plan is applied, wrapped around a composed `splitBlock`.
  */
-import { parse } from '../core/parser';
-import { displayLength, splitLines, trailingLineEnding } from '../core/lines';
+import { readBlocks } from '../core/parser';
+import { displayLength, isBlankText, splitLines, trailingLineEnding } from '../core/lines';
+import { withStoredCaret } from './stored-caret';
 import { getBlockKindDescriptor } from '../schema/block-kind-descriptor';
 import { completeLineOnType, 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) {
+/** Wraps a composed `splitBlock` with the completer check, above the container overrides so a
+ *  container replacing `splitBlock` keeps the completion for its subtree. */
+export function withEnterCompletion(blockEdit, childAt, grammar, getLineEnding) {
     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
+            const completion = planEnterCompletion(childAt(index), offset, grammar, getLineEnding());
+            if (!completion)
+                return blockEdit.splitBlock(index, offset);
+            // `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 });
+            return blockEdit.replaceBlock(index, completion.replacement, { replacementIndex: 0, ...completion.caret }, { snapshotOffset: offset });
         },
-        // The typed arm: a keystroke that leaves the block as a line an on-type completer claims
-        // (see `BlockCompleter.onType`) forms the structure at once, the way a typed ` ``` ` is a
-        // fence the moment the parser sees it. The write lands first, so the typed line is its own
-        // undo step and the mint replaces the bytes the CST actually holds.
-        async updateBlockContent(index, text, preEditOffset, postEditFocusOffset) {
-            await blockEdit.updateBlockContent(index, text, preEditOffset, postEditFocusOffset);
-            const offset = postEditFocusOffset ?? preEditOffset;
-            if (offset === undefined)
-                return;
-            const completion = planTypedCompletion(childAt(index), offset);
-            if (!completion)
-                return;
-            await blockEdit.replaceBlock(index, completion.replacement, { replacementIndex: 0, ...completion.caret }, { snapshotOffset: offset });
+        // A line an on-type completer recognises forms its structure at once. The write lands
+        // first, so the typed line is its own undo step and the replacement covers the stored bytes.
+        updateBlockContent(index, text, mode, preEditOffset, postEditFocusOffset) {
+            const write = blockEdit.updateBlockContent(index, text, mode, preEditOffset, postEditFocusOffset);
+            if (!write.admitted)
+                return write;
+            const plan = () => planTypedCompletion(childAt(index), write.caret, grammar, getLineEnding());
+            // A write that keeps the caret landed in place already, so its completion is known now.
+            const keepsCaret = write.keepsCaret && plan() === null;
+            const completed = write.then(async (wrote) => {
+                const completion = plan();
+                if (!completion)
+                    return wrote;
+                const replaced = await blockEdit.replaceBlock(index, completion.replacement, { replacementIndex: 0, ...completion.caret }, { snapshotOffset: write.caret });
+                return wrote || replaced;
+            });
+            return withStoredCaret(completed, write.caret, write.storedOffset, keepsCaret);
         }
     };
 }
-/** The completion a press at `offset` earns, or null when the block or the caret disqualifies it. */
-export function planEnterCompletion(node, offset) {
-    return planCompletion(node, offset, completeTypedLine);
+/** The completion Enter at `offset` produces, or null when the block or the caret rules it out. */
+export function planEnterCompletion(node, offset, grammar, lineEnding) {
+    return planCompletion(node, offset, grammar, lineEnding, (line) => completeTypedLine(line, grammar));
 }
-/** The completion a keystroke earns, consulting only the completers that answer on type. */
-export function planTypedCompletion(node, offset) {
-    return planCompletion(node, offset, completeLineOnType);
+/** The completion a keystroke produces, asking only the completers that answer on type. */
+export function planTypedCompletion(node, offset, grammar, lineEnding) {
+    return planCompletion(node, offset, grammar, lineEnding, (line) => completeLineOnType(line, grammar));
 }
-function planCompletion(node, offset, consult) {
+/** `ending` is the document's, for a typed line that has none of its own. */
+function planCompletion(node, offset, grammar, ending, consult) {
     if (!node)
         return null;
     const line = wholeTypedLine(node);
@@ -60,20 +59,19 @@ function planCompletion(node, offset, consult) {
     const claim = consult(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);
+    // Through the parser in the editor's grammar rather than a hand-built node, so the new blocks
+    // are exactly what a reload of those bytes produces.
+    const lineEnding = trailingLineEnding(node.raw, ending);
     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() === ''))
+    const replacement = readBlocks(raw, { grammar, scope: 'fragment' }).children;
+    // A completion of only blank lines would replace the typed line with a delete; the check is per
+    // node because blank lines parse back as empty paragraphs.
+    if (replacement.every((node) => isBlankText(node.raw)))
         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. */
+/** The completer's line and column as a byte offset inside the node its path addresses. Resolved
+ *  here because the line ending the count depends on is chosen here, not by the completer. */
 function resolveCaret(minted, caret) {
     let target = minted;
     for (const index of caret.path)
@@ -82,7 +80,7 @@ function resolveCaret(minted, caret) {
     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. */
+ *  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')

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

@@ -1,36 +1,35 @@
 /**
- * Pure dispatchers for container focus — moveFocus, focusByPath, focusAtColumn.
- * No Svelte context or reactivity; inputs are passed in as parameters.
+ * Pure dispatchers for focus across a block list: moveFocus for the root and every container,
+ * and focusByPath and focusAtColumn inside a container. Everything comes 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. */
+import type { CaretMemory } from '../../cursor/caret-memory';
+/** One block list's side of a focus move, the root's or a container's. */
 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;
+    /** The child count from the tree: the mounted refs lag a structural edit by a render. */
+    count(): number;
+    /** Child `index`'s component, scrolled into the mounted range first if it's windowed out. */
+    mount(index: number): Promise<BlockComponent | null>;
+    /** A move before the first child (-1) or past the last (1): a container hands it to its
+     *  parent, the root stops or appends a paragraph. */
+    leave(step: -1 | 1, position: FocusPosition, options?: MoveFocusOptions): Promise<void>;
+    /** Bound to this list's own boundaries (`selection/gap-caret.ts`). */
+    gapStop(boundaryIndex: number): boolean;
+    /** The move ended on child `index`: its focus call scrolled nothing, so this may. */
+    arrived(index: number): void;
 }
-/** 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>;
+/** The one focus traversal, run by the root and by every container over its own list. */
+export declare function dispatchMoveFocus(scope: MoveFocusScope, index: number, position: FocusPosition, caretMemory: Pick<CaretMemory, 'column' | 'noteExtreme'>, options?: MoveFocusOptions): Promise<void>;
+/** A move handed to `focus`, with the options argument left off when there are none, so the
+ *  common call keeps two arguments. */
+export declare function delegateMoveFocus(focus: Pick<FocusActions, 'moveFocus'>, index: number, position: FocusPosition, options?: MoveFocusOptions): void | 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.
+ * The direction a FocusPosition implies for traversal. A bare numeric offset is a targeted
+ * position 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`.
- */
+/** Scrolls nothing into view, so an unmounted target does nothing; a caller that cannot keep
+ *  the target mounted goes through `reactivity/child-list.ts :: descendTo`. */
 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

@@ -1,47 +1,40 @@
 /**
- * Pure dispatchers for container focus — moveFocus, focusByPath, focusAtColumn.
- * No Svelte context or reactivity; inputs are passed in as parameters.
+ * Pure dispatchers for focus across a block list: moveFocus for the root and every container,
+ * and focusByPath and focusAtColumn inside a container. Everything comes in as parameters.
  */
 import { CURSOR_END, CURSOR_START } from '../../block-component';
 import { consumeStickyLanding, verticalArrival } 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);
+/** The one focus traversal, run by the root and by every container over its own list. */
+export async function dispatchMoveFocus(scope, index, position, caretMemory, options) {
     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);
+    // Before any ref is read, so the tree alone decides the boundary; the list's own edges are
+    // boundaries too, which keeps the move from leaving it.
+    if (step !== 0 && !options?.skipGapStop && scope.gapStop(step > 0 ? index : index + 1))
         return;
-    }
-    const upperBound = childCount ?? refs.length;
-    if (innerIndex >= upperBound) {
-        await delegate(parent.index + 1);
+    if (index < 0 || index >= scope.count()) {
+        await scope.leave(index < 0 ? -1 : 1, position, options);
         return;
     }
-    const block = refs[innerIndex];
+    const block = await scope.mount(index);
+    const retry = (i) => dispatchMoveFocus(scope, i, position, caretMemory, options);
     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);
-        }
+        // A child that can't take focus must not stop the move: continue in its direction
+        // (`docs/design/editor.md` § Focus traversal).
+        if (step !== 0)
+            await retry(index + step);
         return;
     }
-    await consumeStickyLanding(block, innerIndex, position, stickyColumn, (i) => dispatchMoveFocus(refs, i, position, stickyColumn, parent, scope));
+    await consumeStickyLanding(block, index, position, caretMemory, retry);
+    scope.arrived(index);
+}
+/** A move handed to `focus`, with the options argument left off when there are none, so the
+ *  common call keeps two arguments. */
+export function delegateMoveFocus(focus, index, position, options) {
+    return options ? focus.moveFocus(index, position, options) : focus.moveFocus(index, position);
 }
 /**
- * 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.
+ * The direction a FocusPosition implies for traversal. A bare numeric offset is a targeted
+ * position with no direction, so 0 tells the caller not to skip.
  */
 export function traversalStep(position) {
     if (typeof position === 'object')
@@ -52,11 +45,8 @@ export function traversalStep(position) {
         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`.
- */
+/** Scrolls nothing into view, so an unmounted target does nothing; a caller that cannot keep
+ *  the target mounted goes through `reactivity/child-list.ts :: descendTo`. */
 export function dispatchFocusByPath(refs, path, offset) {
     if (path.length === 0) {
         refs[0]?.focus(offset);
@@ -73,24 +63,12 @@ export function dispatchFocusByPath(refs, path, offset) {
         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);
-    // Pass over transparent refs so an entry from above/below lands on the first/last
-    // text-bearing child.
+    // Pass over widget-only children so an entry from above or below lands on the first or
+    // last child that has text.
     for (const i of indices) {
         const ref = refs[i];
         if (!ref?.focusable)

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

@@ -1,16 +1,13 @@
 /**
- * Shared cross-block landing tail for the focus dispatchers. Sticky-X null handling
- * lives here, so `focusAtColumn` receivers always get a finite x.
+ * The last step of a cross-block focus move, once the target block is mounted: the side of a
+ * hidden closer, an edge widget, then the caret. A null sticky column is handled here, so
+ * `focusAtColumn` always receives a finite x.
  */
 import { type BlockComponent, type FocusPosition, type StickyColumnDirection } 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>;
-/** What a vertical arrival does at a block: enter its widget, pass over it, or seat a caret. */
+import type { CaretMemory } from '../../cursor/caret-memory';
+export declare function consumeStickyLanding(block: BlockComponent, index: number, position: FocusPosition, caretMemory: Pick<CaretMemory, 'column' | 'noteExtreme'>, retryAt: (index: number) => Promise<void> | void): Promise<void>;
+/** What a vertical arrival does at a block: enter its widget, pass over it, or place a caret. */
 export type VerticalArrival = 'entered' | 'transparent' | 'seat';
-/**
- * The vertical stop rule, asked by both vertical doors: the per-block landing and a container's
- * column entry. A widget-only block carries no column, so it is passed over unless its edge widget
- * takes the arrival, which is a stop of its own and reads alike from either side. `'entered'` means
- * the widget ALREADY took it, so the caller stops rather than repeating the entry.
- */
+/** Whether a vertical move stops at a block: a widget-only block is passed over unless its edge
+ *  widget takes the arrival (`'entered'`, so the caller must not enter it again). */
 export declare function verticalArrival(block: BlockComponent, from: StickyColumnDirection): VerticalArrival;

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

@@ -1,9 +1,14 @@
 /**
- * Shared cross-block landing tail for the focus dispatchers. Sticky-X null handling
- * lives here, so `focusAtColumn` receivers always get a finite x.
+ * The last step of a cross-block focus move, once the target block is mounted: the side of a
+ * hidden closer, an edge widget, then the caret. A null sticky column is handled here, so
+ * `focusAtColumn` always receives a finite x.
  */
 import { CURSOR_END, CURSOR_START } from '../../block-component';
-export async function consumeStickyLanding(block, index, position, stickyColumn, retryAt) {
+export async function consumeStickyLanding(block, index, position, caretMemory, retryAt) {
+    // Moving to a block's end is a jump, so each construct decides which side of a hidden
+    // closer it means, or the next byte typed joins it (`docs/design/live-mode.md` § 4.2).
+    if (position === 'end')
+        caretMemory.noteExtreme();
     const isStickyMove = typeof position === 'object' && 'stickyColumnFrom' in position;
     if (isStickyMove) {
         const from = position.stickyColumnFrom;
@@ -15,14 +20,14 @@ export async function consumeStickyLanding(block, index, position, stickyColumn,
             return;
         }
     }
-    // Enter an edge widget rather than dropping a no-op caret at its boundary, so the
-    // arrow key produces one visible step.
+    // Enter an edge widget rather than putting a caret that does nothing at its boundary, so
+    // the arrow key produces one visible step.
     if (position === 'start' && block.enterEdgeWidget?.('start'))
         return;
     if (position === 'end' && block.enterEdgeWidget?.('end'))
         return;
     if (isStickyMove) {
-        const x = stickyColumn.get();
+        const x = caretMemory.column();
         const from = position.stickyColumnFrom;
         if (x !== null && block.focusAtColumn) {
             block.focusAtColumn(x, from);
@@ -31,8 +36,8 @@ export async function consumeStickyLanding(block, index, position, stickyColumn,
         block.focus(from === 'above' ? CURSOR_START : CURSOR_END);
         return;
     }
-    // An ARRIVAL says "the start"/"the end" and the door seats it on a landable offset; a numeric
-    // position is a caller who knows its byte (a split's continuation) and is passed through.
+    // 'start' and 'end' are arrivals, and the block's focus clamps them to an offset the caret
+    // can sit at; a number is a caller that knows its byte (a split's second half), passed through.
     if (typeof position === 'number')
         block.focus(position);
     else if (position === 'start')
@@ -40,12 +45,8 @@ export async function consumeStickyLanding(block, index, position, stickyColumn,
     else
         block.focus(CURSOR_END);
 }
-/**
- * The vertical stop rule, asked by both vertical doors: the per-block landing and a container's
- * column entry. A widget-only block carries no column, so it is passed over unless its edge widget
- * takes the arrival, which is a stop of its own and reads alike from either side. `'entered'` means
- * the widget ALREADY took it, so the caller stops rather than repeating the entry.
- */
+/** Whether a vertical move stops at a block: a widget-only block is passed over unless its edge
+ *  widget takes the arrival (`'entered'`, so the caller must not enter it again). */
 export function verticalArrival(block, from) {
     if (!block.isVerticallyTransparent?.())
         return 'seat';

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

@@ -1,6 +1,7 @@
 /**
- * FocusActions factory: cursor movement across blocks, sticky-column-aware
- * vertical traversal, and trailing-paragraph creation past document end.
+ * The root FocusActions: caret movement across top-level blocks, vertical moves that keep
+ * the sticky column, and the paragraph appended when a move goes past the document's end
+ * (outside reading mode).
  */
 import type { FocusActions } from '../../action-contracts';
 import type { EditorActionsDeps, UndoController } from '../deps';

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

@@ -1,74 +1,57 @@
 /**
- * FocusActions factory: cursor movement across blocks, sticky-column-aware
- * vertical traversal, and trailing-paragraph creation past document end.
+ * The root FocusActions: caret movement across top-level blocks, vertical moves that keep
+ * the sticky column, and the paragraph appended when a move goes past the document's end
+ * (outside reading mode).
  */
 import { emptyParagraph } from '../../tree-operations';
-import { trailingLineEnding } from '../../core/lines';
-import { traversalStep } from './focus-dispatch';
-import { consumeStickyLanding } from './focus-landing';
+import { documentLineEnding } from '../../core/lines';
+import { dispatchMoveFocus } from './focus-dispatch';
 import { docPathFrom } from '../../cursor/coordinate-spaces';
 import { tryGapStop } from '../../selection/gap-caret';
+import { isReadingMode } from '../../presentation-mode';
 export function createFocusActions(deps, controller) {
     const gapScope = {
         getDoc: () => deps.doc,
         selection: deps.selectionState,
-        getPresentationMode: deps.getPresentationMode
+        getPresentationMode: deps.reading.mode
     };
     const gapStopAt = (parentPath, boundaryIndex) => tryGapStop(gapScope, parentPath, boundaryIndex);
+    /** Past the last block a move appends a paragraph (outside reading mode); before the first
+     *  it stops. */
+    async function leave(step, _position, options) {
+        // Reading mode writes nothing, so a move past the last block just stops there.
+        if (step < 0 || options?.append === false || isReadingMode(deps.reading.mode))
+            return;
+        // Appended through a commit so it is in undo history and edit events; the blank line
+        // and the paragraph's own line both take the document's line ending.
+        const lineEnding = documentLineEnding(deps.doc);
+        const newBlock = emptyParagraph(lineEnding, lineEnding);
+        // The appended index (one past the end) is the path for both the event and the
+        // undo restore fallback: it names the block this creates.
+        const appendPath = docPathFrom([deps.doc.children.length]);
+        await controller.commitStructural({
+            snapshot: { path: appendPath, offset: 0 },
+            mutate: (children) => {
+                const at = children.length;
+                children.push(newBlock);
+                return { op: 'insert', at, count: 1 };
+            },
+            op: { kind: 'appendBlock', eventPath: appendPath },
+            landing: () => ({ path: docPathFrom([deps.doc.children.length - 1]), offset: 0 })
+        });
+    }
+    const scope = {
+        count: () => deps.doc.children.length,
+        mount: (index) => deps.caretLanding.mount([index]),
+        leave,
+        // A directional move crosses the boundary at the greater adjacent index. `gapEligibleAt`
+        // declines out-of-range boundaries and the root's trailing one.
+        gapStop: (boundaryIndex) => gapStopAt([], boundaryIndex),
+        arrived: (index) => deps.caretLanding.followArrival([index])
+    };
     return {
-        revealPath: deps.revealPath,
         tryGapStop: gapStopAt,
-        async moveFocus(blockIndex, position, options) {
-            const step = traversalStep(position);
-            const stopsAtGaps = step !== 0 && !options?.skipGapStop;
-            // The boundary a directional move crosses is the greater of the two adjacent
-            // indices. Out-of-range boundaries and the root's trailing one decline in
-            // `gapEligibleAt`, so the arms below keep their behavior unguarded.
-            if (stopsAtGaps && gapStopAt([], step > 0 ? blockIndex : blockIndex + 1))
-                return;
-            if (blockIndex < 0)
-                return;
-            if (blockIndex >= deps.doc.children.length) {
-                if (options?.append === false)
-                    return;
-                // Past the last block — appended through the commit primitive so it participates in
-                // undo history and edit events. The separating blank line and the paragraph's own
-                // are both line endings, so both take the document's (G4.20).
-                const lastBlock = deps.doc.children[deps.doc.children.length - 1];
-                const lineEnding = trailingLineEnding(lastBlock?.raw ?? '\n');
-                const newBlock = emptyParagraph(lineEnding, lineEnding);
-                // The appended slot (one past the end) is the coordinate for both the
-                // event and the restore fallback — it names the block this op creates.
-                const appendPath = docPathFrom([deps.doc.children.length]);
-                await controller.commitStructural({
-                    snapshot: { path: appendPath, offset: 0 },
-                    mutate: (children) => {
-                        const at = children.length;
-                        children.push(newBlock);
-                        return { op: 'insert', at, count: 1 };
-                    },
-                    op: { kind: 'appendBlock', eventPath: appendPath },
-                    afterTick: () => {
-                        const lastIdx = deps.doc.children.length - 1;
-                        deps.blockRefs[lastIdx]?.focus(0);
-                    }
-                });
-                return;
-            }
-            const block = await deps.revealPath([blockIndex]);
-            if (!block?.focusable) {
-                // A refless or non-focusable block must not dead-end the move — skip it in
-                // the move's direction (editor.md § Focus traversal).
-                if (step !== 0)
-                    await this.moveFocus(blockIndex + step, position, options);
-                return;
-            }
-            // A landing AT a block's end is a seat at an extreme, not a step onto it, so the side
-            // it means is construct-relative (docs/design/live-mode.md § 4.2). Without this the
-            // first byte typed after a structural landing joins the closer it landed inside.
-            if (position === 'end')
-                deps.edgeAffinity.noteExtreme();
-            await consumeStickyLanding(block, blockIndex, position, deps.stickyColumn, (i) => this.moveFocus(i, position, options));
-        }
+        followArrival: deps.caretLanding.followArrival,
+        moveFocus: (blockIndex, position, options) => dispatchMoveFocus(scope, blockIndex, position, deps.caretMemory, options)
     };
 }

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

@@ -1,6 +1,6 @@
 /**
- * Editor-root action bundle factory. Composes the undo controller plus four
- * sub-interface bundles for Editor.svelte to wire into Svelte context.
+ * The editor root's action bundle: the undo controller plus the four action groups
+ * Editor.svelte puts into Svelte context.
  */
 import type { BlockEditActions, ContainerEditActions, FocusActions, HistoryActions } from '../action-contracts';
 import type { EditorActionsDeps, UndoController } from './deps';
@@ -11,5 +11,6 @@ export interface EditorActionsBundle {
     containerEdit: ContainerEditActions;
     controller: UndoController;
 }
-export declare function createEditorActions(deps: EditorActionsDeps): EditorActionsBundle;
+/** `announceEdit` goes to the undo controller alone (`createUndoController`). */
+export declare function createEditorActions(deps: EditorActionsDeps, announceEdit: (message: string) => void): EditorActionsBundle;
 export type { EditorActionsDeps } from './deps';

package/dist/editor-actions/index.js

@@ -1,14 +1,15 @@
 /**
- * Editor-root action bundle factory. Composes the undo controller plus four
- * sub-interface bundles for Editor.svelte to wire into Svelte context.
+ * The editor root's action bundle: the undo controller plus the four action groups
+ * Editor.svelte puts into Svelte context.
  */
 import { createUndoController } from './commit/undo-controller';
 import { createBlockEditActions } from './block-edit';
 import { createFocusActions } from './focus/focus';
 import { createHistoryActions } from './commit/history';
 import { createContainerEditActions } from './container-edit';
-export function createEditorActions(deps) {
-    const controller = createUndoController(deps);
+/** `announceEdit` goes to the undo controller alone (`createUndoController`). */
+export function createEditorActions(deps, announceEdit) {
+    const controller = createUndoController(deps, announceEdit);
     return {
         blockEdit: createBlockEditActions(deps, controller),
         focus: createFocusActions(deps, controller),