@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/editor-actions/nested/emptied-container.js

@@ -0,0 +1,5 @@
+/** Removes the container from its parent's list, for an edit that would take its last child: an
+ *  emptied container goes rather than stay childless. */
+export function removeEmptiedContainer(deps, gesture) {
+    return deps.parent.blockEdit.deleteBlock(deps.index, gesture);
+}

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

@@ -1,47 +1,44 @@
 /**
- * Composer for container nestedActions bundles. HistoryActions is deliberately
- * absent: containers never override history, and Svelte context delivers the
- * document-level HISTORY_KEY to any descendant.
+ * Builds a container's action bundle. HistoryActions is left out on purpose: containers
+ * never override history, and Svelte context delivers the document-level HISTORY_KEY to
+ * every descendant.
  */
 import type { BlockEditActions, ContainerEditActions, FocusActions, ListContext } from '../../action-contracts';
 import type { NodeView } from '../../core/node-views';
-import type { GrammarView } from '../../schema/block-openers';
-import { type PresentationModeGetter } from '../../editor-keys';
-import type { StickyColumnState } from '../../cursor/sticky-column';
+import type { CaretMemory } from '../../cursor/caret-memory';
 import type { BlockListState } from '../../reactivity/block-list-state.svelte';
-import type { InlineResolverRef } from '../../schema/inline-construct-policy';
+import type { ChildList } from '../../reactivity/child-list';
+import type { Reading } from '../../schema/reading';
 export interface NestedActionsBundle {
     blockEdit: BlockEditActions;
     focus: FocusActions;
     containerEdit: ContainerEditActions;
 }
 /**
- * The three container coordinates every nested factory reads live. A component mints
- * ONE of these and passes it BY REFERENCE to each factory it wires — never spread,
- * which invokes the getters and captures stale values.
+ * The three container coordinates every nested factory reads live. A component creates one
+ * of these and passes it by reference to each factory it wires, never spread: spreading
+ * calls the getters and captures stale values.
  */
 export interface NodeScope {
     get index(): number;
     get node(): NodeView;
-    /** Doc-absolute path of `node`; spine unsharing + ancestry rebuilds key off it. */
+    /** Document-absolute path of `node`; the copy-before-write and the ancestor rebuild use it. */
     get path(): number[];
 }
 export interface NestedActionsDeps {
     index: number;
     node: NodeView;
-    /** Doc-absolute path of `node`; spine unsharing + ancestry rebuilds key off it. */
+    /** Document-absolute path of `node`; the copy-before-write and the ancestor rebuild use it. */
     path: number[];
-    stickyColumn: StickyColumnState;
-    /** The instance's block grammar, so a disabled kind's opener stays skipped when a
-     *  nested block re-parses. Absent = the global grammar. */
-    grammar?: GrammarView;
-    /** Live EFFECTIVE mode, for interior mutations whose bytes depend on what the mode paints
-     *  (the split rebalance). Nullable rather than optional so each container answers. */
-    getPresentationMode: PresentationModeGetter | undefined;
-    /** The instance's link-reference resolver, required-nullable beside the mode. */
-    linkRef: InlineResolverRef | undefined;
-    /** Enclosing list's context, when this container is a list nested in one. */
+    caretMemory: Pick<CaretMemory, 'column' | 'forget' | 'noteExtreme'>;
+    /** The editor's reading, so a nested re-parse or completer reads only the syntax the editor
+     *  switched on and a split's rebalance knows what its mode shows. */
+    reading: Reading;
+    /** The enclosing list's context, when this container is a list nested in one. */
     parentListContext?: ListContext;
+    /** This container's children as a descent reads them, so a move onto a windowed-out child
+     *  mounts it. A headless suite omits it: with no render window, every stored ref is mounted. */
+    childList?: () => ChildList;
     parent: {
         blockEdit: BlockEditActions;
         focus: FocusActions;
@@ -49,13 +46,13 @@ export interface NestedActionsDeps {
     };
 }
 /**
- * `createStandardNestedActions`'s public input: the shared `NodeScope` by reference
- * plus the static config `NestedActionsDeps` carries.
+ * `createStandardNestedActions`'s input: the shared `NodeScope` by reference plus the static
+ * configuration `NestedActionsDeps` carries.
  */
 export type NestedActionsInput = Omit<NestedActionsDeps, 'index' | 'node' | 'path'> & {
     scope: NodeScope;
 };
-/** Receives stable default bundle references; chain via `defaults.blockEdit.foo(...)`. */
+/** Receives the stable default bundle; chain through `defaults.blockEdit.foo(...)`. */
 export type NestedActionsOverrideFactory = (defaults: NestedActionsBundle) => {
     blockEdit?: Partial<BlockEditActions>;
     focus?: Partial<FocusActions>;

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

@@ -1,7 +1,7 @@
 /**
- * Composer for container nestedActions bundles. HistoryActions is deliberately
- * absent: containers never override history, and Svelte context delivers the
- * document-level HISTORY_KEY to any descendant.
+ * Builds a container's action bundle. HistoryActions is left out on purpose: containers
+ * never override history, and Svelte context delivers the document-level HISTORY_KEY to
+ * every descendant.
  */
 import { setContext } from 'svelte';
 import { BLOCK_EDIT_KEY, CONTAINER_EDIT_KEY, FOCUS_KEY, HISTORY_KEY } from '../../editor-keys';
@@ -11,8 +11,8 @@ import { createNestedBlockEdit } from './nested-block-edit';
 import { createNestedFocus } from './nested-focus';
 import { withEnterCompletion } from '../enter-completion';
 export function createStandardNestedActions(state, input, overrideFactory) {
-    // Adapt `scope` to the inline shape the sub-factories read, once at the choke point
-    // rather than at every call site. Getters stay live; destructuring would snapshot.
+    // Adapt `scope` to the shape the sub-factories read, once here rather than at every call
+    // site. Getters stay live; destructuring would snapshot.
     const deps = {
         get index() {
             return input.scope.index;
@@ -23,29 +23,31 @@ export function createStandardNestedActions(state, input, overrideFactory) {
         get path() {
             return input.scope.path;
         },
-        stickyColumn: input.stickyColumn,
-        grammar: input.grammar,
-        getPresentationMode: input.getPresentationMode,
-        linkRef: input.linkRef,
+        caretMemory: input.caretMemory,
+        reading: input.reading,
         parentListContext: input.parentListContext,
+        childList: input.childList,
         parent: input.parent
     };
     const blockEdit = createNestedBlockEdit(state, deps);
     const focus = createNestedFocus(state, deps);
-    // Commit coordinates are doc-absolute at their mint point (block-edit-scope), so
+    // Commit paths are document-absolute where they are made (block-edit-scope), so
     // intermediate containers have nothing to remap and this passes straight through.
     const containerEdit = deps.parent.containerEdit;
     const defaults = { blockEdit, focus, containerEdit };
-    // Above the override spread, so a container replacing `splitBlock` keeps the completion arm
-    // its subtree owes. `defaults` stays undecorated: an override chaining back into it is
-    // already past the consult, and re-entering would spend one press on two.
+    // Above the override spread, so a container replacing `splitBlock` keeps its Enter completion;
+    // `defaults` stays unwrapped, or an override chaining into it would run the check twice.
     const childAt = (index) => deps.node.children?.[index];
+    const getLineEnding = () => containerEdit.lineEnding();
     if (!overrideFactory) {
-        return { ...defaults, blockEdit: withEnterCompletion(blockEdit, childAt) };
+        return {
+            ...defaults,
+            blockEdit: withEnterCompletion(blockEdit, childAt, deps.reading.grammar, getLineEnding)
+        };
     }
     const overrides = overrideFactory(defaults);
     return {
-        blockEdit: withEnterCompletion({ ...blockEdit, ...(overrides.blockEdit ?? {}) }, childAt),
+        blockEdit: withEnterCompletion({ ...blockEdit, ...(overrides.blockEdit ?? {}) }, childAt, deps.reading.grammar, getLineEnding),
         focus: { ...focus, ...(overrides.focus ?? {}) },
         containerEdit: { ...containerEdit, ...(overrides.containerEdit ?? {}) }
     };

package/dist/editor-actions/nested/nested-block-edit.d.ts

@@ -1,8 +1,7 @@
 /**
- * Container BlockEditActions factory. Interior mutations route through the shared
- * `block-edit-core` against a container `CommitScope`; this wrapper owns what the
- * core can't: the children guards, boundary delegation up to `parent.blockEdit`, the
- * unwrap dispatch, and `updateBlockContent`.
+ * A container's BlockEditActions: the shared `block-edit-core` against a container
+ * `CommitScope`, plus what the core cannot own: the children guards, handing edge cases up to
+ * `parent.blockEdit`, and the unwrap dispatch.
  */
 import type { BlockEditActions } from '../../action-contracts';
 import type { BlockListState } from '../../reactivity/block-list-state.svelte';

package/dist/editor-actions/nested/nested-block-edit.js

@@ -1,181 +1,87 @@
 /**
- * Container BlockEditActions factory. Interior mutations route through the shared
- * `block-edit-core` against a container `CommitScope`; this wrapper owns what the
- * core can't: the children guards, boundary delegation up to `parent.blockEdit`, the
- * unwrap dispatch, and `updateBlockContent`.
+ * A container's BlockEditActions: the shared `block-edit-core` against a container
+ * `CommitScope`, plus what the core cannot own: the children guards, handing edge cases up to
+ * `parent.blockEdit`, and the unwrap dispatch.
  */
-import { tick } from 'svelte';
-import { updateNodeContent as performUpdate, ensureUnsharedChild, reconcileTaskMetadata } from '../../tree-operations';
-import { stampStructuralChange } from '../../tree-operations/structural-change';
 import { tryGetBlockKindDescriptor } from '../../schema/block-kind-descriptor';
 import { isCollapsedContainer } from '../../schema/reserved-chrome';
-import { assertInvariant } from '../../assert';
 import { firstChildUnwrapStrategies, middleChildUnwrapStrategies } from '../unwrap-strategies';
-import { createContainerScope, scopeParentOf } from '../block-edit-scope';
-import { createBlockEditCore } from '../block-edit-core';
-import { previewContentReparse, focusAfterContentReplace } from '../replacement-focus';
-import { extendDocPath } from '../../cursor/coordinate-spaces';
+import { createContainerScope } from '../block-edit-scope';
+import { contentUpdate, createBlockEditCore } from '../block-edit-core';
+import { refusedWrite } from '../stored-caret';
+import { removeEmptiedContainer } from './emptied-container';
 export function createNestedBlockEdit(state, deps) {
     const { parent } = deps;
     const scope = createContainerScope(state, deps);
     const core = createBlockEditCore(scope);
-    /**
-     * Where a caret at `offset` lands once this container's body-write rule has
-     * rewritten `text`. Both caret doors read it, since either can arrive from a
-     * component that measured the DOM before the rewrite.
-     */
-    function mapCommittedOffset(text, offset) {
-        const bodyWrite = tryGetBlockKindDescriptor(deps.node.kind)?.bodyWrite;
-        return bodyWrite ? bodyWrite.mapOffset(text, offset) : offset;
-    }
+    const writeContent = contentUpdate(scope);
+    const takesLastChild = () => (deps.node.children?.length ?? 0) <= 1;
     const blockEdit = {
         // ── Structural mutations (interior → core, edges → parent) ─────────────
         async splitBlock(innerIndex, offset) {
             if (!deps.node.children)
-                return;
-            await core.split(innerIndex, offset);
+                return false;
+            return core.split(innerIndex, offset);
         },
         async descendToBody(innerIndex) {
             if (!deps.node.children)
-                return;
-            await core.descendToBody(innerIndex);
+                return false;
+            return core.descendToBody(innerIndex);
         },
         async insertParagraph(boundaryIndex, text) {
             if (!deps.node.children)
-                return;
-            await core.insertParagraph(boundaryIndex, text);
+                return false;
+            return core.insertParagraph(boundaryIndex, text);
         },
         async mergeWithPrevious(innerIndex) {
             if (!deps.node.children)
-                return;
+                return false;
             const unwrapRole = tryGetBlockKindDescriptor(deps.node.kind)?.unwrapRole;
             if (innerIndex <= 0) {
                 if (unwrapRole) {
-                    await firstChildUnwrapStrategies[unwrapRole.firstChildBackspace]({ deps, state });
-                    return;
+                    return firstChildUnwrapStrategies[unwrapRole.firstChildBackspace]({ deps, state });
                 }
-                // Undeclared containers delegate upward. Awaited so caller continuations
-                // (focus placement) run after the upward chain settles.
-                await parent.blockEdit.mergeWithPrevious(deps.index);
-                return;
+                // A container with no unwrap role hands the merge to its parent.
+                return parent.blockEdit.mergeWithPrevious(deps.index);
             }
             if (unwrapRole && unwrapRole.middleChildBackspace !== 'default-merge') {
-                await middleChildUnwrapStrategies[unwrapRole.middleChildBackspace]({ deps, state }, innerIndex);
-                return;
+                return middleChildUnwrapStrategies[unwrapRole.middleChildBackspace]({ deps, state }, innerIndex);
             }
-            await core.mergeWithPreviousInterior(innerIndex);
+            return core.mergeWithPreviousInterior(innerIndex);
         },
         async mergeWithNext(innerIndex) {
             if (!deps.node.children)
-                return;
+                return false;
             if (innerIndex >= deps.node.children.length - 1) {
                 return parent.blockEdit.mergeWithNext(deps.index);
             }
-            // A collapsed container's body is unmounted, so forward-Delete exits past the container
-            // rather than dead-ending on the invisible body — a focus move, no mutation.
-            // `append: false` keeps the last-block case inert rather than minting a paragraph.
+            // A collapsed container's body is unmounted, so forward Delete moves focus past the
+            // container without editing; `append: false` keeps a last block from appending one.
             if (isCollapsedContainer(deps.node)) {
                 await parent.focus.moveFocus(deps.index + 1, 'start', { append: false });
-                return;
+                return false;
             }
-            await core.mergeWithNextInterior(innerIndex);
+            return core.mergeWithNextInterior(innerIndex);
         },
-        async deleteBlock(innerIndex) {
+        async deleteBlock(innerIndex, gesture) {
             if (!deps.node.children)
-                return;
-            if (deps.node.children.length <= 1) {
-                return parent.blockEdit.deleteBlock(deps.index);
-            }
-            await core.deleteInterior(innerIndex);
+                return false;
+            if (takesLastChild())
+                return removeEmptiedContainer(deps, gesture);
+            return core.deleteInterior(innerIndex, gesture);
         },
         updateBlockMetadata: (innerIndex, metadata, options) => core.updateBlockMetadata(innerIndex, metadata, options),
-        replaceBlock: (innerIndex, replacement, focus, options) => core.replaceBlock(innerIndex, replacement, focus, options),
-        // ── In-place leaf edits (per-level) ────────────────────────────────────
-        mapCommittedOffset,
-        async updateBlockContent(innerIndex, text, preEditOffset, postEditFocusOffset) {
-            // The batch's pause window opens once this keystroke's own work is done, throw
-            // included: an unarmed batch never ends by pause.
-            try {
-                await applyContentUpdate(innerIndex, text, preEditOffset, postEditFocusOffset);
-            }
-            finally {
-                parent.containerEdit.armDebouncedPause();
+        async replaceBlock(innerIndex, replacement, focus, options) {
+            if (replacement.length === 0 && takesLastChild()) {
+                return removeEmptiedContainer(deps, 'keyless');
             }
+            return (await core.replaceBlock(innerIndex, replacement, focus, options)) !== null;
+        },
+        updateBlockContent(innerIndex, text, mode, preEditOffset, postEditFocusOffset) {
+            if (!deps.node.children)
+                return refusedWrite();
+            return writeContent(innerIndex, text, mode, preEditOffset, postEditFocusOffset);
         }
     };
-    async function applyContentUpdate(innerIndex, text, preEditOffset, postEditFocusOffset) {
-        if (!deps.node.children)
-            return;
-        // No tail suffix: the document-level fold has no container twin yet.
-        const preview = previewContentReparse(deps.node.children[innerIndex], text, deps.grammar, deps.node.kind, '');
-        const leafPath = extendDocPath(deps.path, innerIndex);
-        if (preview.op !== 'noop') {
-            // Mapped, because a caret measured before the rewrite names a position in
-            // bytes that never landed. Reachable here and not only on the routine path:
-            // completing `</details>` is a kind change, and a kind change commits.
-            const focusOffset = mapCommittedOffset(text, postEditFocusOffset ?? preEditOffset ?? 0);
-            let settled = { change: { op: 'noop' }, textStart: 0 };
-            await parent.containerEdit.commitContainer({
-                containerNode: deps.node,
-                path: deps.path,
-                state,
-                snapshot: { path: leafPath, offset: preEditOffset ?? 0 },
-                mutate: (scope) => {
-                    ensureUnsharedChild(scope.node, innerIndex, scope.sharing);
-                    settled = performUpdate(scopeParentOf(scope), innerIndex, text, deps.grammar, scope.sharing);
-                    stampStructuralChange(scope.children, settled.change, scope.sharing);
-                    return settled.change;
-                },
-                op: {
-                    kind: 'updateContent',
-                    detail: { length: text.length },
-                    eventPath: leafPath
-                },
-                afterTick: () => focusAfterContentReplace(deps.path, innerIndex, settled, focusOffset, scope)
-            });
-            return;
-        }
-        // Routine typing — debounced undo path, no structural commit. The inner leaf's
-        // id is the batch key, so a focus move between sibling leaves breaks the batch.
-        parent.containerEdit.pushDebouncedCheckpoint(leafPath, preEditOffset ?? 0, state.innerBlockIds[innerIndex]);
-        let settled = { change: { op: 'noop' }, textStart: 0 };
-        const reclassified = parent.containerEdit.withUnsharedSpine(leafPath, (chain, sharing) => {
-            assertInvariant('unshared-spine-depth', () => chain.length === leafPath.length
-                ? null
-                : {
-                    code: 'unshared-spine-depth',
-                    message: `withUnsharedSpine: chain depth ${chain.length} != leaf path depth ${leafPath.length}`
-                });
-            const ownedContainer = chain[leafPath.length - 2];
-            if (!ownedContainer?.children)
-                return;
-            settled = performUpdate({
-                children: ownedContainer.children,
-                ownerKind: ownedContainer.kind,
-                owner: ownedContainer
-            }, innerIndex, text, deps.grammar, sharing);
-            // taskItem metadata is extracted at parse time from the first stripped
-            // line, so without this it freezes while the serialized source drifts.
-            if (ownedContainer.kind === 'listItem' && innerIndex === 0) {
-                reconcileTaskMetadata(ownedContainer);
-            }
-            return settled.change;
-        });
-        parent.containerEdit.nudgeReactivity();
-        // The rebuild re-kinded a container on this spine (a typed `> [!TIP]` marker
-        // moves into the container's own bytes), so the edited leaf no longer exists.
-        // Re-enter at the container's start; its focus walk lands in the body.
-        if (reclassified) {
-            await tick();
-            await parent.focus.moveFocus(deps.index, 'start');
-            return;
-        }
-        // A blank-fill settle can fold here, which the single-node preview probe cannot see;
-        // the spine wrapper published the splice, and the caret follows the re-tiled bytes.
-        if (settled.change.op === 'noop')
-            return;
-        await tick();
-        focusAfterContentReplace(deps.path, innerIndex, settled, mapCommittedOffset(text, postEditFocusOffset ?? preEditOffset ?? 0), scope);
-    }
     return blockEdit;
 }

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

@@ -1,7 +1,6 @@
 /**
- * FocusActions factory for container nestedActions bundles. Delegates to the
- * pure dispatcher in `focus-dispatch`, supplying the container's live child
- * count so out-of-range delegation routes through the parent correctly.
+ * A container's FocusActions: the one traversal in `focus-dispatch` over the container's own
+ * child list, handing a move off either end to the parent.
  */
 import type { FocusActions } from '../../action-contracts';
 import type { BlockListState } from '../../reactivity/block-list-state.svelte';

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

@@ -1,30 +1,42 @@
 /**
- * FocusActions factory for container nestedActions bundles. Delegates to the
- * pure dispatcher in `focus-dispatch`, supplying the container's live child
- * count so out-of-range delegation routes through the parent correctly.
+ * A container's FocusActions: the one traversal in `focus-dispatch` over the container's own
+ * child list, handing a move off either end to the parent.
  */
-import { dispatchMoveFocus } from '../focus/focus-dispatch';
+import { descendTo } from '../../reactivity/child-list';
+import { delegateMoveFocus, dispatchMoveFocus } from '../focus/focus-dispatch';
 export function createNestedFocus(state, deps) {
-    const { stickyColumn, parent } = deps;
+    const { caretMemory, parent } = deps;
+    const children = () => deps.childList?.() ?? mountedOnly(state, deps);
+    const scope = {
+        // The tree's count, not the refs': those lag a structural edit by a render.
+        count: () => deps.node.children?.length ?? 0,
+        mount: (index) => descendTo(children(), [index]),
+        leave: async (step, position, options) => {
+            await delegateMoveFocus(parent.focus, deps.index + step, position, options);
+        },
+        // The boundaries this container owns are between its own children, so its
+        // document-absolute path is their parent. Read live: `path` moves under edits.
+        gapStop: (boundaryIndex) => parent.focus.tryGapStop(deps.path, boundaryIndex),
+        arrived: (index) => parent.focus.followArrival([...deps.path, index])
+    };
     return {
-        // A nested scope's reveal IS the editor's recursive revealPath descending
-        // through this container, so this scope doesn't own it. The gap stop is forwarded
-        // for the same reason: the root holds the doc and selection reads.
-        revealPath: parent.focus.revealPath,
+        // The root holds the document, the selection reads and the scroll, so both are forwarded.
         tryGapStop: parent.focus.tryGapStop,
-        // Sync, and does not reveal an off-window inner target, unlike the root
-        // `moveFocus`. The adjacent-only precondition is the caller's — VR-12
-        // (docs/design/virtual-rendering.md).
+        followArrival: parent.focus.followArrival,
         async moveFocus(innerIndex, position, options) {
-            await dispatchMoveFocus(state.innerBlockRefs, innerIndex, position, stickyColumn, { focus: parent.focus, index: deps.index }, {
-                // node.children.length is authoritative: refs.length lags after structural
-                // ops because bind:this fires asynchronously.
-                childCount: deps.node.children?.length,
-                options,
-                // The boundaries this scope owns are its own children's, so the container's
-                // doc-absolute path is their parent. Read live: `path` moves under edits.
-                gapStop: (boundaryIndex) => parent.focus.tryGapStop(deps.path, boundaryIndex)
-            });
+            await dispatchMoveFocus(scope, innerIndex, position, caretMemory, options);
+        }
+    };
+}
+/** A list with no render window, for a suite with no components: nothing mounts later, so an
+ *  empty ref is out of range. */
+function mountedOnly(state, deps) {
+    return {
+        count: () => deps.node.children?.length ?? 0,
+        refs: state.refSlots,
+        windowing: {
+            revealChild: async () => { },
+            isInWindow: (index) => state.refSlots.get(index) !== undefined
         }
     };
 }

package/dist/editor-actions/paste-coordinator.d.ts

@@ -1,4 +1,5 @@
-/** Lets paste modules depend on a narrow interface in their own layer instead of reaching up into editor-actions. */
+/** The narrow commit interface `tree-operations/paste/` depends on instead of importing
+ *  editor-actions. */
 import type { PasteCommitCoordinator } from '../tree-operations/paste/paste-deps';
 import type { EditorActionsDeps, UndoController } from './deps';
-export declare function createPasteCoordinator(controller: UndoController, revealPath: EditorActionsDeps['revealPath']): PasteCommitCoordinator;
+export declare function createPasteCoordinator(deps: EditorActionsDeps, controller: UndoController): PasteCommitCoordinator;

package/dist/editor-actions/paste-coordinator.js

@@ -1,20 +1,24 @@
-/** Lets paste modules depend on a narrow interface in their own layer instead of reaching up into editor-actions. */
+/** The narrow commit interface `tree-operations/paste/` depends on instead of importing
+ *  editor-actions. */
 import { getStateForNode } from '../reactivity/state-registry';
-export function createPasteCoordinator(controller, revealPath) {
-    return {
+import { commitLeafTextAt, createBlockEditCore } from './block-edit-core';
+import { createPathScope } from './block-edit-scope';
+import { docPathFrom } from '../cursor/coordinate-spaces';
+export function createPasteCoordinator(deps, controller) {
+    const root = { deps, controller };
+    const coordinator = {
         commitMultiScope: controller.commitMultiScope,
         getDocScope: controller.getDocScope,
-        // editor-actions may read reactivity and reveal (downward edges); supplying
-        // them here keeps `tree-operations/paste/` from importing either itself.
+        // editor-actions may import reactivity; handing it over here keeps `tree-operations/paste/`
+        // from importing it itself.
         resolveState: getStateForNode,
-        landCaret: async (path, offset) => {
-            const stamp = controller.historyGeneration();
-            const block = await revealPath(path);
-            // A history swap that resolved inside the reveal restored a different tree, so
-            // this path no longer addresses what the paste aimed at.
-            if (controller.historyGeneration() !== stamp)
-                return;
-            block?.focus(offset);
+        commitLeafText: (leafPath, text, opts) => commitLeafTextAt(root, leafPath, text, opts),
+        async replaceBlock(blockPath, replacement, focus, opts) {
+            const scope = createPathScope(root, docPathFrom(blockPath.slice(0, -1)));
+            if (!scope)
+                return null;
+            return createBlockEditCore(scope).replaceBlock(blockPath[blockPath.length - 1], replacement, focus, opts);
         }
     };
+    return coordinator;
 }

package/dist/editor-actions/plugin/chrome-leaf.d.ts

@@ -1,8 +1,8 @@
 /**
- * Register a container-chrome leaf kind: editable text at a reserved child slot of a plugin
- * container (a callout title, a details summary). The container declares the slot via
- * `reservedChrome`; this seam supplies the leaf. Chrome only, never standalone recognizer-backed
- * kinds — the contract is a single-line, plain-text child (`docs/design/plugin-contract.md`).
+ * Register a title-row leaf kind: editable text at a reserved child index of a plugin
+ * container (a callout title, a details summary). The container declares the index via
+ * `reservedChrome`; this registers the leaf. Only for such rows, never for a kind with its
+ * own parser: the child is one line of plain text (`docs/design/plugin-contract.md`).
  */
 import type { Component } from 'svelte';
 import { type MergeRole } from '../../schema/block-kind-descriptor';
@@ -10,16 +10,18 @@ import { type KeyBinding } from '../../schema/keybindings';
 import { type AnyBlockKind, type CstNode } from '../../core/nodes';
 import type { BlockComponent, BlockComponentProps } from '../../block-component';
 /**
- * Mint the reserved child-0 node for a chrome leaf. An empty title collapses to a
- * bare newline, so the empty leaf still holds a line.
+ * Create the reserved child-0 node for a title-row leaf. An empty title becomes a bare
+ * newline, so the empty leaf still holds a line.
  */
 export declare function chromeChild(kind: AnyBlockKind, text: string): CstNode;
 export interface ChromeLeafOptions {
-    /** CSS class on the leaf's surface, for chrome styling. */
+    /** What a screen reader and the block menu call the row; defaults to the kind in words. */
+    label?: string;
+    /** CSS class on the leaf's editable element, for styling the title row. */
     blockClass?: string;
-    /** A binding replaces the seam default for its chord; the defaults fill the rest. */
+    /** A binding replaces the default for its chord; the defaults fill the rest. */
     keymap?: KeyBinding[];
-    /** Defaults to 'not-mergeable' (chrome: body prose cannot merge into it). */
+    /** Defaults to 'not-mergeable': body prose cannot merge into a title row. */
     mergeRole?: MergeRole;
 }
 export declare function registerChromeLeaf<P extends Partial<BlockComponentProps> & Record<string, unknown>>(kind: AnyBlockKind, component: Component<P, BlockComponent>, opts?: ChromeLeafOptions): void;

package/dist/editor-actions/plugin/chrome-leaf.js

@@ -1,8 +1,8 @@
 /**
- * Register a container-chrome leaf kind: editable text at a reserved child slot of a plugin
- * container (a callout title, a details summary). The container declares the slot via
- * `reservedChrome`; this seam supplies the leaf. Chrome only, never standalone recognizer-backed
- * kinds — the contract is a single-line, plain-text child (`docs/design/plugin-contract.md`).
+ * Register a title-row leaf kind: editable text at a reserved child index of a plugin
+ * container (a callout title, a details summary). The container declares the index via
+ * `reservedChrome`; this registers the leaf. Only for such rows, never for a kind with its
+ * own parser: the child is one line of plain text (`docs/design/plugin-contract.md`).
  */
 import { registerBlockKind } from '../../schema/block-kind-descriptor';
 import { registerBlockComponent, defineBlockComponent } from '../../schema/block-component-registry';
@@ -11,14 +11,14 @@ import { registerPasteSurface } from '../../tree-operations/paste-surfaces';
 import { defaultInlineHook } from '../../tree-operations/paste/hooks';
 import { makeBlockNode } from '../../core/nodes';
 /**
- * Mint the reserved child-0 node for a chrome leaf. An empty title collapses to a
- * bare newline, so the empty leaf still holds a line.
+ * Create the reserved child-0 node for a title-row leaf. An empty title becomes a bare
+ * newline, so the empty leaf still holds a line.
  */
 export function chromeChild(kind, text) {
     return makeBlockNode({ kind, leadingTrivia: '', raw: text ? `${text}\n` : '\n' });
 }
-// Chrome is single-line by serialization, so Enter descends into the body
-// instead of splitting; Backspace/Delete take the ordinary merge walk.
+// A title row serializes as one line, so Enter moves into the body instead of splitting;
+// Backspace and Delete take the ordinary merge path.
 const CHROME_DEFAULT_KEYMAP = [
     { chord: 'Enter', command: 'chrome.descendToBody' },
     { chord: 'Backspace', command: 'block.mergePrev' },
@@ -35,14 +35,15 @@ function mergeChromeKeymap(overrides) {
 }
 export function registerChromeLeaf(kind, component, opts = {}) {
     registerBlockKind(kind, {
+        ...(opts.label !== undefined ? { label: opts.label } : {}),
         gapEdges: 'none',
         mergeRole: opts.mergeRole ?? 'not-mergeable',
         editable: true,
         supportsInline: false,
         contextDependentKind: true,
         keymap: mergeChromeKeymap(opts.keymap),
-        // No conformanceFixture: the container opener mints child-0, so a chrome leaf
-        // never stands alone as a document scan's result.
+        // No conformanceFixture: the container's parser creates child 0, so a title-row leaf
+        // never comes out of a document parse on its own.
         closure: {
             roundTrip: {
                 mode: 'implemented',
@@ -60,7 +61,7 @@ export function registerChromeLeaf(kind, component, opts = {}) {
             searchPaint: { mode: 'implemented', via: 'chrome raw scanned; matches painted as marks' },
             reorder: {
                 mode: 'not-supported',
-                reason: 'reserved child 0 — no independent block identity to move'
+                reason: 'reserved child 0: no independent block identity to move'
             },
             undo: { mode: 'inherit-default' },
             clipboard: {
@@ -74,7 +75,7 @@ export function registerChromeLeaf(kind, component, opts = {}) {
         }
     });
     registerBlockComponent(kind, defineBlockComponent(component, () => ({ blockClass: opts.blockClass })));
-    // Inline-only surface, so `surfaceForcesInline` holds if a paste ever reaches
-    // surface resolution — defense behind the gate that already flattens chrome pastes.
+    // Inline-only, so `surfaceForcesInline` holds if a paste ever reaches the paste-target lookup:
+    // a second line of defense behind the check that already flattens title-row pastes.
     registerPasteSurface({ kind, onInlinePaste: defaultInlineHook });
 }