@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/action-contracts.d.ts

@@ -1,148 +1,172 @@
 /**
- * Every action interface a block component invokes upward through Svelte context, plus
- * the commit vocabulary those calls are expressed in.
+ * Every action interface a block component calls upward through Svelte context, plus
+ * the commit types those calls are written in.
  */
 import type { CstNode, TableAlignment } from './core/nodes';
 import type { NodeView } from './core/node-views';
+import type { LineEnding } from './core/lines';
 import type { StructuralChange } from './tree-operations/structural-change';
 import type { TrackedPosition } from './tree-operations/settle';
 import type { SharingState } from './tree-operations/sharing';
+import type { BodyParent } from './tree-operations/node-primitives';
 import type { BlockComponent, FocusPosition } from './block-component';
-import type { ScopedOpDescriptor } from './schema/operations';
+import type { OperationDetailMap, ScopedOpDescriptor } from './schema/operations';
+import type { WriteMode } from './schema/block-kind-descriptor';
 import type { DocPath } from './selection/path-math';
+import type { CaretPosition, Landing } from './selection/primitives';
+import type { LegalWrite } from './tree-operations/content-write';
+import type { LandingOutcome, RevealPolicy } from './selection/caret-landing';
+import type { RemovalGesture } from './selection/caret-target';
 /**
- * Caret-restore coordinate stored with a commit's undo snapshot: `path` is the `DocPath`
- * dialect and must resolve in the pre-mutation tree; `'skip'` joins the caller's
- * already-pushed entry. Minted by the scope factories (`block-edit-scope.ts`) or the
- * `path-math` helpers, never composed at a call site.
+ * Where the caret goes back to on undo when nothing is focused: `path` is a document-absolute
+ * `DocPath` and must resolve in the tree before the mutation. Built by the block-list factories
+ * (`block-edit-scope.ts`) or the `path-math` helpers, never assembled at a call site.
  */
 export type CommitSnapshotArg = {
     path: DocPath;
     offset: number;
-} | 'skip';
+};
 /**
- * Who owns the undo entry: `'own'` (the default) pushes one, `'join'` means the caller
- * already pushed the entry covering this composite operation and this must not add one.
+ * Opt-in for structural commits that may legitimately do nothing. The commit then throws
+ * away the snapshot it took first: no undo entry, no edit event, nothing written to state
+ * (its landing still runs, since a refused merge still crosses the boundary the key pressed at).
+ * Not for content or metadata commits, whose `noop` `StructuralChange` means "structure held,
+ * bytes changed".
  */
-export type UndoEntryMode = 'own' | 'join';
+export type DiscardIfNoop = boolean;
 /**
- * Opt-in for structural commits that can legitimately no-op. The ceremony then discards
- * the pre-captured snapshot: no undo entry, no edit event, no publish (`afterTick` still
- * runs — caret placement is a view concern). NOT for content/metadata commits, whose
- * `noop` StructuralChange means "structure held, bytes changed" and MUST still publish.
+ * Where the caret goes after a commit, read after the tick so it sees the tree the commit left.
+ * It returns a value and places nothing; the commit puts the caret there through the editor's
+ * caret landing (`selection/caret-landing.ts`), and null leaves the caret where it is.
  */
-export type DiscardIfNoop = boolean;
+export type CommitLanding = () => Landing | null;
 /**
- * Post-tick view callback — where a commit lands its caret. Awaited, so a landing that
- * must first reveal an off-window target (VR-12) is expressible here; the reveal is
- * bounded (VR-5), so awaiting cannot hang. Returning nothing opts out of the wait.
+ * A callback that places the caret itself after the tick, left only for the delete and the typing
+ * over a range that spans blocks, not yet on {@link CommitLanding}. Awaited, before the landing.
  */
 export type CommitAfterTick = () => void | Promise<void>;
+/**
+ * What a screen reader hears about a commit (a move, a table edit) in the editor's edit live
+ * region, read after the caret lands and only when bytes landed. That region hears nothing else, so a
+ * refused, failed or discarded commit says nothing there.
+ */
+export type CommitAnnouncement = () => string;
+/**
+ * A content write in flight, resolving to whether bytes landed. `admitted` is known the moment the
+ * call returns: false means the write was turned away before it touched anything (reading mode, or
+ * a list with no text of its own to write). Only an admitted write has a caret: the landing offset
+ * in the bytes as stored, with `storedOffset` mapping any other offset the same way.
+ */
+export type ContentWrite = Promise<boolean> & (RefusedContentWrite | AdmittedContentWrite);
+export interface RefusedContentWrite {
+    readonly admitted: false;
+}
+export interface AdmittedContentWrite {
+    readonly admitted: true;
+    readonly caret: number;
+    storedOffset(offset: number): number;
+    /** False when the write places the caret itself (a new kind, a merge, a changed container),
+     *  so the block must not put its own caret back. */
+    readonly keepsCaret: boolean;
+}
+/** Where the caret goes after an edit to one block, relative to it: `path` walks its children
+ *  (`[]` is the block itself) and `offset` is a byte there or an edge value (`CURSOR_END`). */
+export interface BlockCaret {
+    path: number[];
+    offset: number;
+}
+/** Every edit a block asks of its list. Each resolves to whether bytes landed; a focus move
+ *  that writes nothing resolves false. */
 export interface BlockEditActions {
-    splitBlock(blockIndex: number, offset: number): void | Promise<void>;
+    splitBlock(blockIndex: number, offset: number): Promise<boolean>;
     /**
-     * Focus the block after `blockIndex` in this scope, minting an empty paragraph when
-     * it is the last child. An off-window next block leaves the caret put, key consumed.
-     */
-    descendToBody(blockIndex: number): void | Promise<void>;
-    /**
-     * @internal Mint a paragraph carrying `text` at a BOUNDARY of this scope, caret after
-     * the text. `boundaryIndex === children.length` appends. The between-blocks caret's
-     * insertion door (`selection/gap-caret.ts`).
-     */
-    insertParagraph(boundaryIndex: number, text: string): void | Promise<void>;
-    mergeWithPrevious(blockIndex: number): void | Promise<void>;
-    mergeWithNext(blockIndex: number): void | Promise<void>;
-    deleteBlock(blockIndex: number): void | Promise<void>;
-    /**
-     * `preEditOffset` is the undo snapshot's cursor anchor; `postEditFocusOffset` is where
-     * the caret lands when a kind change remounts the block (typing `# ` on a paragraph),
-     * defaulting to `preEditOffset`.
-     */
-    updateBlockContent(blockIndex: number, text: string, preEditOffset?: number, postEditFocusOffset?: number): void | Promise<void>;
-    /**
-     * Where a caret at `offset` lands once this scope has committed `text` — the image of
-     * a container's `bodyWrite` rewrite, so a surface whose committed bytes differ from
-     * its DOM seats the caret on the bytes. Identity when the scope rewrites nothing.
-     */
-    mapCommittedOffset?(text: string, offset: number): number;
-    /**
-     * Mutate block metadata without touching raw — for state expressed as metadata (task
-     * checkboxes), NOT raw-driven metadata like heading level (use updateBlockContent).
-     * The patch is shallow-merged; an empty patch is a no-op.
+     * Focus the block after `blockIndex` in this list, creating an empty paragraph when it is
+     * the last child. If the next block is not mounted the caret stays put, key consumed.
      */
+    descendToBody(blockIndex: number): Promise<boolean>;
+    /** @internal Create a paragraph holding `text` at a boundary of this list, caret after the
+     *  text; `boundaryIndex === children.length` appends. */
+    insertParagraph(boundaryIndex: number, text: string): Promise<boolean>;
+    mergeWithPrevious(blockIndex: number): Promise<boolean>;
+    mergeWithNext(blockIndex: number): Promise<boolean>;
+    /** Remove the block; the caret lands once, on the side `gesture` points
+     *  (`selection/caret-target.ts :: survivorAfterRemoval`), and the caller places none. */
+    deleteBlock(blockIndex: number, gesture: RemovalGesture): Promise<boolean>;
+    /** Write `text` as the block's bytes through its kind's and this list's write rules. Undo
+     *  returns to `preEditOffset`, where the edit began; `caret` maps `postEditFocusOffset`. */
+    updateBlockContent(blockIndex: number, text: string, mode: WriteMode, preEditOffset: number, postEditFocusOffset?: number): ContentWrite;
+    /** Shallow-merges metadata the kind's rebuild writes into its bytes (a checkbox toggle). A key no
+     *  parse gives back is dropped at the next re-read; a heading's level goes through the text. */
     updateBlockMetadata(blockIndex: number, metadata: Record<string, unknown>, options?: {
-        undoEntry?: UndoEntryMode;
-        afterTick?: CommitAfterTick;
-    }): void | Promise<void>;
-    /**
-     * Replace the block at `blockIndex` with zero or more new blocks.
-     * `replacement.length === 0` is equivalent to deleteBlock. `focus.path` addresses a caret
-     * landing inside the replacement's own structure; `snapshotOffset` is where the caret was,
-     * for the undo entry, and defaults to where it lands.
-     */
-    replaceBlock(blockIndex: number, replacement: CstNode[], focus?: {
+        caret?: BlockCaret;
+    }): Promise<boolean>;
+    /** Replace the block with zero or more blocks (none is `deleteBlock`). `focus.path` addresses a
+     *  caret inside the replacement; `snapshotOffset` is the undo entry's caret. */
+    replaceBlock(blockIndex: number, replacement: CstNode[], focus: {
         replacementIndex: number;
         offset: number;
         path?: number[];
-    }, options?: {
-        undoEntry?: UndoEntryMode;
-        snapshotOffset?: number;
-    }): void | Promise<void>;
+    } | undefined, options: {
+        snapshotOffset: number;
+    }): Promise<boolean>;
 }
 export interface MoveFocusOptions {
-    /**
-     * When false, a move past the true document end no-ops instead of appending a trailing
-     * paragraph; only the root append is suppressed, sibling moves and upward delegation
-     * are unaffected. Defaults to true (Enter/split rely on the append).
-     */
+    /** False stops a move past the document end from appending a trailing paragraph; sibling moves
+     *  and upward delegation are unaffected. Defaults to true, which Enter's split relies on. */
     append?: boolean;
-    /** @internal Set by a move that LEAVES a gap caret, so the boundary it just left
-     *  cannot re-capture it. */
+    /** @internal Set by a move that leaves a between-blocks caret, so the boundary it just
+     *  left cannot capture it again. */
     skipGapStop?: boolean;
 }
 export interface FocusActions {
     moveFocus(blockIndex: number, position: FocusPosition, options?: MoveFocusOptions): void | Promise<void>;
-    /** Mount an off-window top-level block before placing a caret in it; see EditorActionsDeps.revealPath. */
-    revealPath(path: number[]): Promise<BlockComponent | null>;
-    /**
-     * @internal Park the caret at an eligible between-blocks boundary, reporting whether it
-     * did. Required, not optional: a dropped forward makes every gap arrival below it
-     * silently vanish.
-     */
+    /** @internal Put the caret at a between-blocks boundary that allows one. Required: a container
+     *  that fails to forward it makes every such caret below it vanish. */
     tryGapStop(parentPath: number[], boundaryIndex: number): boolean;
+    /** @internal An arrow move ended on the block at `path`: one focused whole comes into view.
+     *  Forwarded to the root like `tryGapStop`. */
+    followArrival(path: number[]): void;
 }
 export interface HistoryActions {
     requestUndo(): void | Promise<void>;
     requestRedo(): void | Promise<void>;
 }
 /**
- * Owned mutation view handed to a container/multi-scope commit's `mutate`: `node` is the
- * unshared copy already spliced into the live tree. Never write through references
- * captured before the commit — they may be stale snapshot-shared originals.
+ * The copy a container or multi-list commit hands its `mutate`: `node` is the unshared copy
+ * already spliced into the live tree. Never write through references captured before the
+ * commit; they may be the originals an undo snapshot still shares.
  */
 export interface ContainerScope {
     node: CstNode;
     children: CstNode[];
     sharing: SharingState;
+    /** The document's line ending, which every line the mutation writes takes. */
+    lineEnding: LineEnding;
+    /** `children` as the body the tree operations write; at the document root it has no owner. */
+    readonly body: BodyParent;
+    /** Rebuilds `node`'s raw as the commit does, for a node the commit won't rebuild whose bytes
+     *  the mutation reads before it returns; never the scope, which the commit rebuilds once. */
+    rebuild(node: CstNode): void;
 }
 export interface MultiScopeTarget {
-    /** Scope identity — a view suffices; the ceremony unshares the spine and mints the owned mutation view. */
+    /** Which block list this is; a view is enough, since the commit copies the ancestor chain
+     *  and makes its own mutable copy. */
     node: NodeView;
-    /** The `BlockListState` shape the ceremony writes: ids by assignment, refs only in
-     *  place — the array identity is the scope's, so a replacement strands its teardowns. */
+    /** The `BlockListState` fields the commit writes: ids by assignment, refs only in place,
+     *  because the array identity is the list's and replacing it strands its teardowns. */
     state: {
         innerBlockIds: string[];
         readonly innerBlockRefs: (BlockComponent | undefined)[];
     };
-    /** Doc-absolute path of `node`; the commit primitive unshares its spine. */
+    /** Document-absolute path of `node`; the commit copies its ancestor chain before writing. */
     path: number[];
 }
 export interface CommitMultiScopeArgs<S extends readonly MultiScopeTarget[] = readonly MultiScopeTarget[]> {
-    /** `scopes[0]` is the outermost — inner raws must be current before outer rebuilds. */
+    /** `scopes[0]` is the outermost: an inner block's raw must be current before an outer
+     *  one rebuilds. */
     scopes: S;
     snapshot: CommitSnapshotArg;
-    /** One view in, one StructuralChange out per scope, same order — tuple-checked for literal scope arrays. */
+    /** One view in, one `StructuralChange` out per list, same order; checked as a tuple. */
     mutate: (scopeViews: {
         [K in keyof S]: ContainerScope;
     }) => {
@@ -150,12 +174,14 @@ export interface CommitMultiScopeArgs<S extends readonly MultiScopeTarget[] = re
     };
     op?: ScopedOpDescriptor;
     afterTick?: CommitAfterTick;
+    /** Overridden when an ancestor collapsed: the collapse recreated the blocks it names. */
+    landing?: CommitLanding;
+    /** How far the landing moves the viewport; `'into-view'` when absent. */
+    reveal?: RevealPolicy;
+    announce?: CommitAnnouncement;
     discardIfNoop?: DiscardIfNoop;
-    /**
-     * Caret positions the scopes' settles carry through their folds, parallel to `scopes` —
-     * a fold re-tiles the bytes under a landing chosen before the settle ran. Written in
-     * place, so `afterTick` reads the settled seat back off the object it passed in.
-     */
+    /** Caret positions each list's fix-up updates in place, parallel to `scopes`, since a collapsing
+     *  container moves the bytes under them; the landing reads them back off the same objects. */
     trackCaret?: readonly (TrackedPosition | undefined)[];
 }
 export interface CommitStructuralArgs {
@@ -163,14 +189,21 @@ export interface CommitStructuralArgs {
     mutate: (children: CstNode[]) => StructuralChange;
     op?: ScopedOpDescriptor;
     afterTick?: CommitAfterTick;
-    /** Leaf(ves) for the dev invariant check when `mutate` returns `noop` (in-place kind change). */
+    landing?: CommitLanding;
+    reveal?: RevealPolicy;
+    announce?: CommitAnnouncement;
+    /** Leaves for the dev invariant check when `mutate` returns `noop` (an in-place kind change). */
     touchedNodes?: CstNode[];
     discardIfNoop?: DiscardIfNoop;
+    /** A caret position the document's fix-up updates in place; the landing reads it back. */
+    trackCaret?: TrackedPosition;
 }
 export interface CommitContainerStructuralArgs {
-    /** Scope identity — a view suffices; the ceremony unshares the spine and mints the owned mutation view. */
+    /** Which container this is; a view is enough, since the commit copies the ancestor chain
+     *  and makes its own mutable copy. */
     containerNode: NodeView;
-    /** Doc-absolute path of `containerNode` — the spine the primitive unshares + rebuilds. */
+    /** Document-absolute path of `containerNode`: the ancestor chain the commit copies and
+     *  rebuilds. */
     path: number[];
     state: {
         innerBlockIds: string[];
@@ -180,90 +213,144 @@ export interface CommitContainerStructuralArgs {
     mutate: (scope: ContainerScope) => StructuralChange;
     op?: ScopedOpDescriptor;
     afterTick?: CommitAfterTick;
+    landing?: CommitLanding;
+    reveal?: RevealPolicy;
+    announce?: CommitAnnouncement;
     discardIfNoop?: DiscardIfNoop;
+    /** A caret position the container's fix-up updates in place; the landing reads it back. */
+    trackCaret?: TrackedPosition;
 }
 /**
- * Selection-free commit surface, so the selection layer can depend on it without
- * dragging in `EditorSelection`/`UndoEntry`. `UndoController` (editor-actions/deps)
- * extends it with the two selection-typed members.
+ * The commit calls with no selection types in them, so `selection/` can depend on this
+ * without pulling in `EditorSelection` or `UndoEntry`. `UndoController`
+ * (editor-actions/deps) adds the two selection-typed members.
  */
 export interface CommitController {
-    /** Editor's sharing epoch state, exposed for out-of-ceremony copy-path-on-write. */
+    /** The editor's structural-sharing counters, for copy-before-write outside a commit. */
     sharing: SharingState;
-    pushUndoSnapshot(blockIndex: number, offset: number): void;
-    /** Snapshot whose no-caret fallback seeds a deep leaf path (e.g. a match nested in a list item). */
-    pushUndoSnapshotPath(path: number[], offset: number): void;
-    /** Debounced typing snapshot; `leafPath` is the edited leaf's doc-absolute path. */
+    /** Debounced typing snapshot; `leafPath` is the edited leaf's document-absolute path. */
     pushUndoSnapshotDebounced(leafPath: number[], offset: number, batchKey?: string | number): void;
-    /** Start the batch's pause window, once the keystroke's own edit has settled. Paired with
-     *  every `pushUndoSnapshotDebounced`, or the batch never ends by pause. */
+    /** Start the batch's pause timer, once the keystroke's own edit is done. Paired with
+     *  every `pushUndoSnapshotDebounced`, or the batch never ends on a pause. */
     armUndoPause(): void;
-    commitStructural(args: CommitStructuralArgs): Promise<void>;
-    commitContainerStructural(args: CommitContainerStructuralArgs): Promise<void>;
-    commitMultiScope<const S extends readonly MultiScopeTarget[]>(args: CommitMultiScopeArgs<S>): Promise<void>;
-    /**
-     * Expose the document root as a MultiScopeTarget so commitMultiScope
-     * callers can include doc-level splices alongside container scopes
-     * (e.g., a cross-block delete whose LCA is the document root).
-     */
+    /** Each commit resolves to whether bytes landed: false when declined, rolled back or a no-op
+     *  it discarded. */
+    commitStructural(args: CommitStructuralArgs): Promise<boolean>;
+    commitContainerStructural(args: CommitContainerStructuralArgs): Promise<boolean>;
+    commitMultiScope<const S extends readonly MultiScopeTarget[]>(args: CommitMultiScopeArgs<S>): Promise<boolean>;
+    /** The document root as a `MultiScopeTarget`, so a multi-scope commit can include root-level
+     *  changes (a cross-block delete whose common ancestor is the root). */
     getDocScope(): MultiScopeTarget;
-    /** Flush the pending keystroke batch — emit its `input` event and clear the
-     *  debounce timer — before a history swap, so the batch's bytes aren't lost. */
+    /** Flush the pending keystroke batch (emit its `input` event and clear the debounce
+     *  timer) before an undo or redo, so the batch's bytes aren't lost. */
     flushDebouncedCheckpoint(): void;
     /** Run a command's byte write as its own undo entry. A command is not typing, so the
-     *  keystroke batch breaks on BOTH sides: one Ctrl+Z takes the command and nothing else. */
+     *  keystroke batch breaks on both sides: one Ctrl+Z takes back the command alone. */
     isolateUndoEntry(write: () => void): void;
+    /** Make every write made while `run` is pending one undo entry, restoring the selection the step
+     *  opened with (`seed` when unfocused). Ends when `run` settles or at the author's next input. */
+    undoStep(seed: CommitSnapshotArg, run: () => Promise<unknown>): Promise<void>;
+    /** Called on the author's own input: every later write opens its own entry, even while a
+     *  step's run is still pending. */
+    endUndoStep(): void;
 }
+/** What a container reaches the editor root for, forwarded unchanged through nested containers.
+ *  A keystroke runs `typeInLeaf`, then a commit or `writeLeafInPlace` (`leaf-write.ts`). */
 export interface ContainerEditActions {
-    /**
-     * Push a debounced undo snapshot for routine text input. `leafPath` is the edited
-     * leaf's doc-absolute path; `batchKey` (its stable block id) breaks the batch on
-     * focus moves between sibling leaves.
-     */
-    pushDebouncedCheckpoint(leafPath: number[], offset: number, batchKey?: string | number): void;
-    /** The checkpoint's other half: open the pause window once the keystroke's edit has settled. */
-    armDebouncedPause(): void;
-    /**
-     * Publish a raw change made outside the commit primitive, forwarded unchanged through
-     * nested containers. Raw rebuilds are NOT part of the nudge — out-of-ceremony writers
-     * rebuild via `withUnsharedSpine`, which operates on owned copies.
-     */
-    nudgeReactivity(): void;
-    /**
-     * Copy-path-on-write wrapper for out-of-ceremony writes (routine typing): unshares the
-     * spine doc-root → `absPath`, calls `write` with the owned chain (outermost first) and the
-     * epoch to own anything OFF that spine, then rebuilds innermost-first. The caller still pushes
-     * its own checkpoint and nudges. True means the rebuild re-derived a container's kind (typing
-     * out a `> [!TIP]` marker), remounting the edited leaf — the caller re-places the caret.
-     * `write` returns the change its own settle made, so the wrapper can publish it.
-     */
-    withUnsharedSpine(absPath: number[], write: (chain: CstNode[], sharing: SharingState) => StructuralChange | void): boolean;
-    /**
-     * Preferred entry for structural container mutations: spine unshare, snapshot,
-     * publish, edit event, post-tick. `mutate` receives the OWNED container with its
-     * working children attached — mutate through it, never through captures.
-     */
-    commitContainer(args: CommitContainerStructuralArgs): Promise<void>;
+    /** The document's line ending, which every line a write below the root creates takes. */
+    lineEnding(): LineEnding;
+    /** Change a container's structure as one undo entry. `mutate` receives the copied container
+     *  with its working children attached; write through it, never through a captured node. */
+    commitContainer(args: CommitContainerStructuralArgs): Promise<boolean>;
+    /** Push the typing burst's undo entry for the leaf at `leafPath`, then run `work` joined to
+     *  it; `batchKey` is the leaf's id, so a move to a sibling leaf starts a new burst. */
+    typeInLeaf<T>(leafPath: DocPath, preEditOffset: number, batchKey: string, work: () => Promise<T>): Promise<T>;
+    /** The keystroke's write outside a commit, for a write that keeps the leaf's kind. */
+    writeLeafInPlace(leafPath: DocPath, write: LegalWrite, caret: number): InPlaceResult;
+    /** Put the caret at a document position through the editor's caret landing, for an edit that
+     *  moves the caret without a commit. */
+    land(pos: CaretPosition): Promise<LandingOutcome>;
+    /** Where the caret goes once the block at `removedPath` is gone, read on the document now. */
+    survivorAfterRemoval(removedPath: DocPath, gesture: RemovalGesture): CaretPosition | null;
+}
+export type InPlaceResult = {
+    readonly wrote: false;
+} | {
+    readonly wrote: true;
+    /** Where the caret goes when the write took it out of the leaf's element (a merge, an
+     *  ancestor that changed kind or collapsed); null when the leaf's element keeps it. */
+    readonly relanding: Relanding | null;
+};
+/** A caret to put back after a write, and the blocks the write left where it wrote: focus already
+ *  outside them means a blur committed the write, and the caret stays where it went. */
+export interface Relanding {
+    readonly caret: CaretPosition;
+    readonly window: {
+        readonly list: DocPath;
+        readonly at: number;
+        readonly count: number;
+    };
+}
+/** What a commit writing new text into one leaf resolves to. */
+export type LeafWriteResult = {
+    readonly wrote: false;
+} | LeafWriteLanded;
+/** `caret` is where the caret goes after the write and its list's fix-up, and `window` the
+ *  written block's replacement run; a collapsed ancestor places the caret itself afterwards. */
+export interface LeafWriteLanded extends Relanding {
+    readonly wrote: true;
+    /** Whether the write put new blocks in the position rather than rewriting the leaf. */
+    readonly replaced: boolean;
+}
+/** A leaf write by document path: `caret` is an offset into the text as written, `snapshotOffset`
+ *  one into the leaf's current bytes, where undo puts the caret back when nothing is focused. */
+export interface LeafTextOptions {
+    caret: number;
+    snapshotOffset: number;
+    /** Runs after the tick, before a collapsed ancestor places the caret itself. */
+    afterTick?: (landed: LeafWriteLanded) => void | Promise<void>;
+}
+/** Which replacement block the caret lands in, at `offset` (`CURSOR_END` for its end) or at
+ *  `path` below it. */
+export interface ReplaceFocus {
+    replacementIndex: number;
+    offset: number;
+    path?: number[];
+}
+export interface ReplaceOptions {
+    /** Where undo puts the caret back when nothing is focused: where the gesture began. */
+    snapshotOffset: number;
+    /** A clipboard's own trailing blank line, landed as the document's when nothing follows. */
+    trailingBlank?: boolean;
+    /** The route a paste or a drop names in the edit event, in place of the block count. */
+    source?: ReplaceSource;
 }
+export type ReplaceSource = Extract<OperationDetailMap['replaceBlock'], {
+    source: unknown;
+}>['source'];
+/** A list's item edits; each resolves to whether bytes landed. */
 export interface ListContext {
-    insertItemAfter(itemIndex: number, newItem?: CstNode): Promise<void>;
-    exitListAtItem(itemIndex: number): Promise<void>;
-    indentItem(itemIndex: number): Promise<void>;
-    unindentItem(itemIndex: number): Promise<void>;
+    insertItemAfter(itemIndex: number, newItem?: CstNode): Promise<boolean>;
+    exitListAtItem(itemIndex: number): Promise<boolean>;
+    indentItem(itemIndex: number): Promise<boolean>;
+    unindentItem(itemIndex: number): Promise<boolean>;
     /**
      * Split the item mid-content: first half stays, second half moves into a
      * new sibling item. Emits exactly one undo snapshot and one edit event.
      */
-    splitItemAtOffset(itemIndex: number, innerIndex: number, offset: number): Promise<void>;
-    /** Promote a nested list item to the parent list level. Called on the PARENT list's context.
-     *  `nestedListNode` is scope identity (a live-tree reference) — a view; writes go through the ceremony. */
-    promoteNestedItem(parentItemIndex: number, nestedListNode: NodeView, nestedItemIndex: number): Promise<void>;
+    splitItemAtOffset(itemIndex: number, innerIndex: number, offset: number): Promise<boolean>;
+    /** Promote a nested list item to this parent list's level; `nestedListNode` is a live-tree
+     *  reference, and writes go through the commit. */
+    promoteNestedItem(parentItemIndex: number, nestedListNode: NodeView, nestedItemIndex: number): Promise<boolean>;
     /** Returns this list's index in its enclosing list (for nested-list promotion). */
     getContainingItemIndex(): number;
 }
 export type CellPosition = 'start' | 'end' | number;
 export interface TableContext {
+    /** A key's move to another cell; the cell comes into view as any arrow arrival does. */
     focusCell(rowIdx: number, colIdx: number, position: CellPosition): void;
+    /** Scroll the grid sideways so the cell's column is inside the table's own box. */
+    revealColumn(rowIdx: number, colIdx: number): void;
     getStickyColumn(): number | null;
     setStickyColumn(colIdx: number): void;
     resetStickyColumn(): void;
@@ -288,7 +375,7 @@ export interface TableContext {
     moveColumnLeft(colIdx: number): Promise<void>;
     moveColumnRight(colIdx: number): Promise<void>;
     cycleAlignment(colIdx: number): Promise<void>;
-    /** Set a column's alignment directly — distinct from the cycle step. */
+    /** Set a column's alignment directly, as opposed to cycling it. */
     setColumnAlignment(colIdx: number, alignment: TableAlignment): Promise<void>;
     /** Write a grid of cell texts from `origin`, appending the rows and columns it needs, as one
      *  commit: a spreadsheet-like paste. Empty grids are a no-op. */
@@ -298,8 +385,8 @@ export interface TableContext {
     }, grid: string[][]): Promise<void>;
 }
 /**
- * The TableContext mutations addressed by ONE axis index, the vocabulary the affordance
- * menu and the cell's table commands both dispatch through. Derived from the contract
+ * The `TableContext` mutations addressed by a single row or column index, the names both the
+ * hover menu and the cell's table commands dispatch through. Derived from the interface
  * rather than listed beside it, so a member with any other signature cannot be named.
  */
 export type TableAxisAction = {

package/dist/action-contracts.js

@@ -1,5 +1,5 @@
 /**
- * Every action interface a block component invokes upward through Svelte context, plus
- * the commit vocabulary those calls are expressed in.
+ * Every action interface a block component calls upward through Svelte context, plus
+ * the commit types those calls are written in.
  */
 export {};

package/dist/active-editor.d.ts

@@ -4,11 +4,11 @@ export declare function markEditorInteracted(root: HTMLElement): void;
 /** True when a body-level chord routes to `root`. */
 export declare function claimsBodyChord(root: HTMLElement): boolean;
 /**
- * True when `active` is a text-entry surface outside every mounted editor. The reserved
- * chords (Ctrl+F / Ctrl+H) yield to it, so an editor never hijacks a consumer's own field.
+ * True when `active` is a text-entry element outside every mounted editor. The reserved
+ * chords (Ctrl+F, Ctrl+H) yield to it, so an editor never hijacks a consumer's own field.
  */
 export declare function isForeignTextEntry(active: Element | null): boolean;
-/** True when `el` takes text input — the surfaces a programmatic focus move must yield to. */
+/** True when `el` takes text input: the elements a programmatic focus move must yield to. */
 export declare function isTextEntrySurface(el: Element | null): boolean;
 /** Release the claim if this editor holds it, so a torn-down instance never keeps it. */
 export declare function releaseInteractedEditor(root: HTMLElement): void;

package/dist/active-editor.js

@@ -1,9 +1,8 @@
 /**
- * Which editor a document-level chord routes to when no block holds native focus. The
- * keydown listener sees every editor's keystrokes on the page, so the claimant is the
- * last-interacted editor while that claim is live, else the sole mounted one. Two mounted
- * editors with no live claim resolve to neither — guessing drives the wrong instance.
- * Module-level by design: cross-instance coordination is the point.
+ * Which editor a document-level chord goes to when no block has focus: the last editor the user
+ * touched while it is still mounted, otherwise the only mounted editor. Two mounted editors and
+ * no recent one resolve to neither, since guessing drives the wrong instance. Module-level on
+ * purpose: coordinating across instances is the point.
  */
 const mountedEditors = new Set();
 let lastInteracted = null;
@@ -24,7 +23,7 @@ export function claimsBodyChord(root) {
     return !hasLiveClaim && mountedEditors.size === 1 && mountedEditors.has(root);
 }
 // Text-like <input> types the reserved chords yield to. Non-text types are deliberately
-// absent: they don't consume Ctrl+F, so a sole editor keeps claiming while one has focus.
+// absent: they don't consume Ctrl+F, so a lone editor keeps taking it while one has focus.
 const TEXT_ENTRY_INPUT_TYPES = new Set([
     'text',
     'search',
@@ -35,8 +34,8 @@ const TEXT_ENTRY_INPUT_TYPES = new Set([
     'number'
 ]);
 /**
- * True when `active` is a text-entry surface outside every mounted editor. The reserved
- * chords (Ctrl+F / Ctrl+H) yield to it, so an editor never hijacks a consumer's own field.
+ * True when `active` is a text-entry element outside every mounted editor. The reserved
+ * chords (Ctrl+F, Ctrl+H) yield to it, so an editor never hijacks a consumer's own field.
  */
 export function isForeignTextEntry(active) {
     if (!isTextEntrySurface(active))
@@ -47,7 +46,7 @@ export function isForeignTextEntry(active) {
     }
     return true;
 }
-/** True when `el` takes text input — the surfaces a programmatic focus move must yield to. */
+/** True when `el` takes text input: the elements a programmatic focus move must yield to. */
 export function isTextEntrySurface(el) {
     if (el instanceof HTMLTextAreaElement)
         return true;

package/dist/ambient/ambient-dom.d.ts

@@ -1,9 +1,6 @@
 /**
- * DOM construction and lookup for the ambient marker span — the read-only
- * prefix container blocks contribute to their first prose child's textContent.
+ * Builds the marker prefix span (the "ambient" prefix): the read-only prefix a container block
+ * draws in front of its first prose child's text. Reading it back is `cursor/widget-offset.ts`.
  */
 import type { AmbientPrefix } from '../block-component';
 export declare function buildAmbientSpan(prefix: AmbientPrefix): HTMLSpanElement;
-export declare function ambientSpanOf(blockEl: ParentNode): HTMLElement | null;
-export declare function ambientLengthOf(blockEl: HTMLElement): number;
-export declare function placeCaretAfterAmbientSpan(blockEl: HTMLElement): boolean;