@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/tree-operations/paste/body-write.d.ts

@@ -1,9 +1,11 @@
 /**
- * The paste family's `bodyWrite` moment: paste builds nodes upstream of every
- * content-write byte sink, so a container's escape lands here instead — on the clipboard text
- * ahead of the strategy-picking parse, and on the built replacement at the splice.
+ * Where paste applies a container's `bodyWrite` escape: paste builds nodes before any content
+ * write sees them, so the escape is applied here instead, to the clipboard text before the
+ * strategy-picking parse and to the built replacement at the splice.
  */
-import type { AnyBlockKind, CstNode, Document } from '../../core/nodes';
+import type { CstNode, Document } from '../../core/nodes';
+import type { NodeView } from '../../core/node-views';
+import { type LineEnding } from '../../core/lines';
 import type { GrammarView } from '../../schema/block-openers';
 /** Clipboard text made legal inside every `bodyWrite`-declaring ancestor of the paste target. */
 export declare function normalizeClipboardForBody(doc: Document, targetPath: number[], text: string): string;
@@ -13,7 +15,7 @@ export interface BodyLegalReplacement {
     mapIndex: (index: number) => number;
 }
 /**
- * Replacement nodes made legal as `ownerKind` children. A changed raw reparses whole, so
+ * Replacement nodes made legal as `owner`'s children. A changed raw reparses whole, so
  * the landed kind follows the escaped bytes and a container's children stay in step.
  */
-export declare function normalizeReplacementForBody(ownerKind: AnyBlockKind | undefined, replacement: CstNode[], grammar?: GrammarView): BodyLegalReplacement;
+export declare function normalizeReplacementForBody(owner: NodeView | undefined, replacement: CstNode[], ending: LineEnding, grammar: GrammarView): BodyLegalReplacement;

package/dist/tree-operations/paste/body-write.js

@@ -1,49 +1,48 @@
 /**
- * The paste family's `bodyWrite` moment: paste builds nodes upstream of every
- * content-write byte sink, so a container's escape lands here instead — on the clipboard text
- * ahead of the strategy-picking parse, and on the built replacement at the splice.
+ * Where paste applies a container's `bodyWrite` escape: paste builds nodes before any content
+ * write sees them, so the escape is applied here instead, to the clipboard text before the
+ * strategy-picking parse and to the built replacement at the splice.
  */
-import { parse } from '../../core/parser';
+import { documentLineEnding } from '../../core/lines';
+import { readBlocks } from '../../core/parser';
 import { tryGetBlockKindDescriptor } from '../../schema/block-kind-descriptor';
 import { ensureEditableContainers, isBlockNode, nodeAt, normalizeBodyWrite, normalizeReplacementTrivia } from '../node-primitives';
 /** Clipboard text made legal inside every `bodyWrite`-declaring ancestor of the paste target. */
 export function normalizeClipboardForBody(doc, targetPath, text) {
     let out = text;
+    const lineEnding = documentLineEnding(doc);
     for (let depth = targetPath.length - 1; depth >= 1; depth--) {
         const ancestor = nodeAt(doc, targetPath.slice(0, depth));
         if (ancestor && isBlockNode(ancestor))
-            out = normalizeBodyWrite(ancestor.kind, out);
+            out = normalizeBodyWrite(ancestor, out, lineEnding);
     }
     return out;
 }
 /**
- * Replacement nodes made legal as `ownerKind` children. A changed raw reparses whole, so
+ * Replacement nodes made legal as `owner`'s children. A changed raw reparses whole, so
  * the landed kind follows the escaped bytes and a container's children stay in step.
  */
-export function normalizeReplacementForBody(ownerKind, replacement, grammar) {
-    if (ownerKind === undefined || !tryGetBlockKindDescriptor(ownerKind)?.bodyWrite) {
+export function normalizeReplacementForBody(owner, replacement, ending, grammar) {
+    if (owner === undefined || !tryGetBlockKindDescriptor(owner.kind)?.bodyWrite) {
         return { replacement, mapIndex: (i) => i };
     }
     const out = [];
     const starts = [];
     for (const node of replacement) {
         starts.push(out.length);
-        const escaped = normalizeBodyWrite(ownerKind, node.raw);
+        const escaped = normalizeBodyWrite(owner, node.raw, ending);
         if (escaped === node.raw) {
             out.push(node);
             continue;
         }
-        const reparsed = parse(escaped, {
-            scope: 'fragment',
-            ...(grammar ? { grammar } : {})
-        }).children;
+        const reparsed = readBlocks(escaped, { grammar, scope: 'fragment' }).children;
         if (reparsed.length === 0) {
             out.push(node);
             continue;
         }
         const carried = normalizeReplacementTrivia(node, reparsed);
         for (const minted of carried)
-            ensureEditableContainers(minted);
+            ensureEditableContainers(minted, ending);
         out.push(...carried);
     }
     return {

package/dist/tree-operations/paste/container-match.d.ts

@@ -5,28 +5,25 @@
  */
 import type { CstNode, Document } from '../../core/nodes';
 import type { PasteDispatchContext } from './dispatch';
+import type { CommitSnapshotArg } from '../../action-contracts';
 interface ContainerUnwrap {
     outerPath: number[];
     /** Index within outer.children of the target descendant. */
     spliceIndex: number;
     items: CstNode[];
-    /**
-     * Non-empty-target variant: merge the first clipboard item into the target leaf, splice
-     * the rest as siblings, reattach post-caret residue to the last. Absent means the
-     * descendant is empty and gets replaced wholesale.
-     */
+    /** A non-empty target: the first item merges into the target leaf, the rest land as siblings
+     *  with the residue on the last. Absent: the empty descendant is replaced whole. */
     merge?: {
         targetLeafPath: number[];
         offset: number;
-        /** The target leaf's bytes AFTER the paste's delete half. */
+        /** The target leaf's bytes after the paste's delete half. */
         targetRaw: string;
     };
 }
 /**
- * Whether to flatten the paste into a matching ancestor container. Empty target
- * descendants always unwrap; non-empty ones only in cross-block context, so a single-block
- * paste into a partially-filled item keeps the nested-sub-container behavior.
+ * Whether to flatten the paste into a matching ancestor container: an empty target always, a
+ * filled one only across blocks, so a single-block paste into a filled item nests a sub-container.
  */
 export declare function findContainerMatchingUnwrap(doc: Document, targetPath: number[], offset: number, parsed: Document, crossBlockContext: boolean, targetRaw?: string): ContainerUnwrap | null;
-export declare function applyContainerMatchingPaste(unwrap: ContainerUnwrap, ctx: PasteDispatchContext): Promise<void>;
+export declare function applyContainerMatchingPaste(unwrap: ContainerUnwrap, ctx: PasteDispatchContext, start: CommitSnapshotArg): Promise<void>;
 export {};

package/dist/tree-operations/paste/container-match.js

@@ -5,22 +5,22 @@
  */
 import { CURSOR_END } from '../../block-component';
 import { devWarn } from '../../dev-warn';
-import { trailingLineEnding, trimTrailingLineEnding } from '../../core/lines';
-import { nodeAt, writeOwnRaw } from '../node-primitives';
-import { settledCaretTarget, updateNodeContent } from '../content-write';
+import { documentLineEnding, isBlankText, trailingLineEnding, trimTrailingLineEnding } from '../../core/lines';
+import { nodeAt } from '../node-primitives';
+import { legalizeWrite, settledCaretPosition, updateNodeContent } from '../content-write';
+import { leafAtRawOffset } from '../container-offsets';
 import { containerPasteFor } from './container-paste';
-import { rebuildContainerRawIfContainer } from '../../schema/container-raw';
-import { ensureUnsharedNode, ensureUnsharedPath } from '../unshare';
+import { rebuildContainerRaw } from '../../schema/container-raw';
+import { ensureUnsharedPath } from '../unshare';
 import { rebuildUnsharedChain } from '../chain-rebuild';
 import { containerScopeState } from './parent-scope';
 import { applyStructuralChangeToIdsRefs, stampStructuralChange } from '../structural-change';
 import { renumberOrderedList, templatePastedItemMarkers } from '../list/ordered-markers';
-import { spliceTerminatedItems } from '../list/terminator';
+import { spliceMany } from '../splice-many';
 import { docPathFrom } from '../../cursor/coordinate-spaces';
 /**
- * Whether to flatten the paste into a matching ancestor container. Empty target
- * descendants always unwrap; non-empty ones only in cross-block context, so a single-block
- * paste into a partially-filled item keeps the nested-sub-container behavior.
+ * Whether to flatten the paste into a matching ancestor container: an empty target always, a
+ * filled one only across blocks, so a single-block paste into a filled item nests a sub-container.
  */
 export function findContainerMatchingUnwrap(doc, targetPath, offset, parsed, crossBlockContext, targetRaw) {
     if (parsed.children.length !== 1)
@@ -71,18 +71,17 @@ export function findContainerMatchingUnwrap(doc, targetPath, offset, parsed, cro
 function isEmptyContainerChild(node, postDelete) {
     const rawOf = (n) => (n === postDelete.node ? postDelete.raw : n.raw);
     if (!node.children || node.children.length === 0)
-        return rawOf(node).trim() === '';
+        return isBlankText(rawOf(node));
     if (node.children.length !== 1)
         return false;
     const c = node.children[0];
     if (c.kind !== 'paragraph')
         return false;
-    return rawOf(c).trim() === '';
+    return isBlankText(rawOf(c));
 }
 /**
- * The one paragraph an unwrapped item's text may be spliced as. The merge slices a DISPLAY
- * offset out of the target leaf and reattaches the residue, which only prose bytes address —
- * so both writes re-read this rather than trusting the finder's gate from a distance.
+ * The one paragraph an unwrapped item's text may be spliced as. Only prose bytes can take the
+ * merge's display offset, so both writes re-check rather than trust the finder.
  */
 function singleParagraphChildOf(node) {
     if (!node.children || node.children.length !== 1)
@@ -90,24 +89,21 @@ function singleParagraphChildOf(node) {
     const child = node.children[0];
     return child.kind === 'paragraph' ? child : null;
 }
-export async function applyContainerMatchingPaste(unwrap, ctx) {
+export async function applyContainerMatchingPaste(unwrap, ctx, start) {
     const outer = nodeAt(ctx.doc, unwrap.outerPath);
     if (!outer)
         return;
     const outerState = containerScopeState(ctx.controller, outer);
     if (unwrap.merge) {
-        await applyContainerMatchingMerge(unwrap, unwrap.merge, outer, outerState, ctx);
+        await applyContainerMatchingMerge(unwrap, unwrap.merge, outer, outerState, ctx, start);
         return;
     }
     templatePastedItemMarkers(unwrap.items, outer, unwrap.spliceIndex);
-    const snapshot = ctx.undoEntry === 'join'
-        ? 'skip'
-        : { path: docPathFrom(unwrap.outerPath), offset: 0 };
     await ctx.controller.commitMultiScope({
         scopes: [{ node: outer, state: outerState, path: unwrap.outerPath }],
-        snapshot,
+        snapshot: start,
         mutate: ([scopeView]) => {
-            spliceTerminatedItems(scopeView.children, unwrap.spliceIndex, 1, unwrap.items);
+            spliceMany(scopeView.children, unwrap.spliceIndex, 1, unwrap.items);
             const change = {
                 op: 'replace',
                 at: unwrap.spliceIndex,
@@ -124,30 +120,31 @@ export async function applyContainerMatchingPaste(unwrap, ctx) {
             detail: { source: 'container-matching', outerPath: unwrap.outerPath },
             eventPath: docPathFrom(unwrap.outerPath)
         },
-        afterTick: () => {
+        landing: () => {
             const lastInsertedIdx = unwrap.spliceIndex + unwrap.items.length - 1;
-            return ctx.controller.landCaret([...unwrap.outerPath, lastInsertedIdx], CURSOR_END);
+            return { path: docPathFrom([...unwrap.outerPath, lastInsertedIdx]), offset: CURSOR_END };
         }
     });
 }
 /** A single-item clipboard keeps everything in the target leaf. */
-async function applyContainerMatchingMerge(unwrap, merge, outer, outerState, ctx) {
+async function applyContainerMatchingMerge(unwrap, merge, outer, outerState, ctx, snapshot) {
     const targetLeaf = nodeAt(ctx.doc, merge.targetLeafPath);
     if (!targetLeaf)
         return;
     const firstLeaf = singleParagraphChildOf(unwrap.items[0]);
     const lastLeaf = singleParagraphChildOf(unwrap.items[unwrap.items.length - 1]);
     if (!firstLeaf || !lastLeaf) {
-        // Unreachable while the finder's gate holds. Declining before the commit keeps a drifted
-        // gate a clean no-op, and the diagnostic is what stops that drift being silent.
+        // Unreachable while the finder's check holds. Declining before the commit keeps a drifted
+        // check a clean no-op, and the warning is what stops that drift being silent.
         devWarn('paste-container-match', 'merge items are no longer single-paragraph', {
             first: unwrap.items[0].kind,
             last: unwrap.items[unwrap.items.length - 1].kind
         });
         return;
     }
-    // Post-delete bytes: the door spent the paste's delete half before picking this strategy.
-    const targetLineEnding = trailingLineEnding(merge.targetRaw);
+    // Post-delete bytes: dispatch applied the paste's delete half before picking this strategy.
+    const lineEnding = documentLineEnding(ctx.doc);
+    const targetLineEnding = trailingLineEnding(merge.targetRaw, lineEnding);
     const targetDisplay = trimTrailingLineEnding(merge.targetRaw);
     const displayBefore = targetDisplay.slice(0, merge.offset);
     const displayAfter = targetDisplay.slice(merge.offset);
@@ -156,23 +153,31 @@ async function applyContainerMatchingMerge(unwrap, merge, outer, outerState, ctx
     // The first item merges into the target leaf, keeping its marker; only the trailing
     // siblings splice in, landing after the target.
     templatePastedItemMarkers(remainingItems, outer, unwrap.spliceIndex + 1);
-    const snapshot = ctx.undoEntry === 'join'
-        ? 'skip'
-        : { path: docPathFrom(unwrap.outerPath), offset: 0 };
-    /** The merged leaf sits BELOW the scope node — own its full spine. */
-    const ownMergedLeafSpine = (sharing) => {
-        const chain = ensureUnsharedPath(ctx.doc, merge.targetLeafPath, sharing);
-        return { chain, ownedLeaf: chain[chain.length - 1] ?? ensureUnsharedNode(targetLeaf, sharing) };
+    const leafIndex = merge.targetLeafPath[merge.targetLeafPath.length - 1];
+    /**
+     * The merged leaf's new text through the content write against its holder, whose ids follow
+     * any kind change; the holder sits below the scope node, so its whole chain is copied first.
+     */
+    const writeMergedLeaf = (text, sharing) => {
+        const chain = ensureUnsharedPath(ctx.doc, merge.targetLeafPath, sharing).slice(0, -1);
+        const holder = chain[chain.length - 1];
+        const body = { children: holder.children, owner: holder, lineEnding };
+        const write = legalizeWrite(body, leafIndex, text, 'literal');
+        const settled = updateNodeContent(body, leafIndex, write, ctx.reading.grammar, sharing);
+        if (holder.childIds) {
+            applyStructuralChangeToIdsRefs(settled.change, holder.childIds, new Array(holder.childIds.length));
+        }
+        return { chain, settled, storedOffset: write.storedOffset };
     };
+    let merged = null;
     if (remainingItems.length === 0) {
         await ctx.controller.commitMultiScope({
             scopes: [{ node: outer, state: outerState, path: unwrap.outerPath }],
             snapshot,
             mutate: ([scopeView]) => {
                 const sharing = scopeView.sharing;
-                const { chain, ownedLeaf } = ownMergedLeafSpine(sharing);
-                writeOwnRaw(ownedLeaf, displayBefore + firstItemText + displayAfter + targetLineEnding, ctx.grammar);
-                rebuildUnsharedChain(ctx.doc, chain, sharing, null, ctx.grammar);
+                merged = writeMergedLeaf(displayBefore + firstItemText + displayAfter + targetLineEnding, sharing);
+                rebuildUnsharedChain(ctx.doc, merged.chain, sharing, null, ctx.reading.grammar);
                 return [{ op: 'noop' }];
             },
             op: {
@@ -180,15 +185,23 @@ async function applyContainerMatchingMerge(unwrap, merge, outer, outerState, ctx
                 detail: { source: 'container-matching-merge-singleton', outerPath: unwrap.outerPath },
                 eventPath: docPathFrom(unwrap.outerPath)
             },
-            afterTick: () => 
-            // A char offset inside the merged leaf, not a block index, so land on the leaf
-            // itself: a container's focus(number) would clamp to its last child's end.
-            ctx.controller.landCaret(merge.targetLeafPath, displayBefore.length + firstItemText.length)
+            landing: () => {
+                // A char offset inside the merged leaf, not a block index, so land on the leaf
+                // itself: a container's entry offset would take its last child's end.
+                const joined = displayBefore.length + firstItemText.length;
+                if (!merged)
+                    return { path: docPathFrom(merge.targetLeafPath), offset: joined };
+                const holderPath = merge.targetLeafPath.slice(0, -1);
+                const holder = nodeAt(ctx.doc, holderPath);
+                const children = holder?.children ?? [];
+                const at = settledCaretPosition(merged.settled, leafIndex, merged.storedOffset(joined), children);
+                return { path: docPathFrom([...holderPath, at.index]), offset: at.offset };
+            }
         });
         return;
     }
     const lastItem = remainingItems[remainingItems.length - 1];
-    const lastLineEnding = trailingLineEnding(lastLeaf.raw);
+    const lastLineEnding = trailingLineEnding(lastLeaf.raw, lineEnding);
     const lastDisplay = trimTrailingLineEnding(lastLeaf.raw);
     let residue = { change: { op: 'noop' }, textStart: 0 };
     await ctx.controller.commitMultiScope({
@@ -196,20 +209,19 @@ async function applyContainerMatchingMerge(unwrap, merge, outer, outerState, ctx
         snapshot,
         mutate: ([scopeView]) => {
             const sharing = scopeView.sharing;
-            const { chain, ownedLeaf } = ownMergedLeafSpine(sharing);
-            writeOwnRaw(ownedLeaf, displayBefore + firstItemText + targetLineEnding, ctx.grammar);
+            const { chain } = writeMergedLeaf(displayBefore + firstItemText + targetLineEnding, sharing);
             // The residue can cross a kind boundary (a fence closer landing in a paragraph),
-            // so it reattaches through the reparse funnel, never a bare write.
-            residue = updateNodeContent({ children: lastItem.children, ownerKind: lastItem.kind, owner: lastItem }, 0, lastDisplay + displayAfter + lastLineEnding, ctx.grammar, sharing);
-            // The write's settle can splice the item's own body, a scope this commit's descriptor
-            // does not cover: its ids stay in step here, and the caret rides it below.
+            // so it reattaches through the reparse path, never a bare write.
+            residue = updateNodeContent({ children: lastItem.children, owner: lastItem, lineEnding }, 0, lastDisplay + displayAfter + lastLineEnding, ctx.reading.grammar, sharing);
+            // The write's fix-up can splice the item's own body, a list this commit's descriptor
+            // does not cover: its ids stay in step here, and the caret follows it below.
             if (lastItem.childIds) {
                 applyStructuralChangeToIdsRefs(residue.change, lastItem.childIds, new Array(lastItem.childIds.length));
             }
-            // Both rebuilds run before the splice, so the published children carry correct
+            // Both rebuilds run before the splice, so the children written to state carry correct
             // raws in one reactive flush.
-            rebuildUnsharedChain(ctx.doc, chain, sharing, null, ctx.grammar);
-            rebuildContainerRawIfContainer(remainingItems[remainingItems.length - 1]);
+            rebuildUnsharedChain(ctx.doc, chain, sharing, null, ctx.reading.grammar);
+            rebuildContainerRaw(remainingItems[remainingItems.length - 1], ctx.reading.grammar);
             // The siblings land after the merged target, which keeps its own slot.
             const insertAt = unwrap.spliceIndex + 1;
             const change = {
@@ -217,7 +229,7 @@ async function applyContainerMatchingMerge(unwrap, merge, outer, outerState, ctx
                 at: insertAt,
                 count: remainingItems.length
             };
-            spliceTerminatedItems(scopeView.children, insertAt, 0, remainingItems);
+            spliceMany(scopeView.children, insertAt, 0, remainingItems);
             stampStructuralChange(scopeView.children, change, sharing);
             // The already-proxied tail below the spliced siblings; the merged target keeps
             // its number.
@@ -229,12 +241,18 @@ async function applyContainerMatchingMerge(unwrap, merge, outer, outerState, ctx
             detail: { source: 'container-matching-merge', outerPath: unwrap.outerPath },
             eventPath: docPathFrom(unwrap.outerPath)
         },
-        afterTick: () => {
-            // A char offset in the last spliced item's paragraph, so land on the paragraph
-            // rather than CURSOR_END on the item — at the slot the residue's own settle left it in.
+        landing: () => {
+            // A char offset in the last spliced item's paragraph, so land on the paragraph rather
+            // than CURSOR_END on the item, at the position the residue's own fix-up left it in.
             const lastInsertedIdx = unwrap.spliceIndex + remainingItems.length;
-            const target = settledCaretTarget(residue, 0, lastDisplay.length, lastItem.children ?? []);
-            return ctx.controller.landCaret([...unwrap.outerPath, lastInsertedIdx, target.index], target.offset);
+            const children = lastItem.children ?? [];
+            const at = settledCaretPosition(residue, 0, lastDisplay.length, children);
+            const block = children[at.index];
+            const leaf = (block?.children?.length && leafAtRawOffset(block, at.offset)) || null;
+            return {
+                path: docPathFrom([...unwrap.outerPath, lastInsertedIdx, at.index, ...(leaf?.path ?? [])]),
+                offset: leaf?.offset ?? at.offset
+            };
         }
     });
 }

package/dist/tree-operations/paste/container-paste.d.ts

@@ -1,8 +1,8 @@
 /**
- * The one door the paste gates reach a kind's `containerPaste` declaration through.
+ * The one place the paste checks read a kind's `containerPaste` declaration through.
  * `matchesAncestor` is plugin code, and on the cross-block route the covering range delete
- * has already committed when a gate consults it, so an escaping throw would leave the
- * selection deleted and nothing pasted. The returned declaration is already contained.
+ * has already committed when a check consults it, so an escaping throw would leave the
+ * selection deleted and nothing pasted. The returned declaration already catches it.
  */
 import type { AnyBlockKind } from '../../core/nodes';
 import type { BlockKindDescriptor } from '../../schema/block-kind-descriptor';

package/dist/tree-operations/paste/container-paste.js

@@ -1,8 +1,8 @@
 /**
- * The one door the paste gates reach a kind's `containerPaste` declaration through.
+ * The one place the paste checks read a kind's `containerPaste` declaration through.
  * `matchesAncestor` is plugin code, and on the cross-block route the covering range delete
- * has already committed when a gate consults it, so an escaping throw would leave the
- * selection deleted and nothing pasted. The returned declaration is already contained.
+ * has already committed when a check consults it, so an escaping throw would leave the
+ * selection deleted and nothing pasted. The returned declaration already catches it.
  */
 import { tryGetBlockKindDescriptor } from '../../schema/block-kind-descriptor';
 import { devWarn } from '../../dev-warn';

package/dist/tree-operations/paste/dispatch.d.ts

@@ -1,15 +1,14 @@
 /**
- * Single entry point for paste: parse the clipboard, pick inline vs structural, route
- * through the target's PasteSurface. Inline/structural surfaces are stateless transforms
- * this module applies; scoped-structural surfaces own their whole mutation including focus.
- * Cross-block paste (`undoEntry: 'join'`) uses DOM-level focus, because the originating
- * block's `pendingCursorOffset` may address a block the range delete is about to unmount.
+ * Single entry point for paste: parse the clipboard, pick inline or structural, and route through
+ * the target kind's `PasteSurface` (its paste handlers), whose inline and structural results this
+ * module applies; a scoped-structural handler owns its whole mutation, focus included. A
+ * cross-block paste focuses through the DOM, since its range delete may unmount the origin block.
  */
-import type { BlockEditActions, UndoEntryMode } from '../../action-contracts';
+import type { BlockEditActions } from '../../action-contracts';
 import type { Document } from '../../core/nodes';
-import type { GrammarView } from '../../schema/block-openers';
+import type { Reading } from '../../schema/reading';
 import type { PluginActivation } from '../../schema/plugin-activation';
-import { type PasteRange, type PasteSeam } from '../paste-surfaces';
+import { type PasteRange } from '../paste-surfaces';
 import type { PasteCommitCoordinator } from './paste-deps';
 export type PasteStrategy = 'inline' | 'structural';
 export interface PasteDispatchInput {
@@ -17,28 +16,28 @@ export interface PasteDispatchInput {
     pastedText: string;
     /** Path from Document root to the target node. Length ≥ 1. */
     targetPath: number[];
-    /** Caret offset within the target node's raw. */
+    /** Caret offset within the target node's raw; with `preDelete`, its start. */
     offset: number;
     /** Selection range within the target's raw (not cross-block). */
     preDelete?: PasteRange;
+    /** Where undo puts the caret back when the paste began elsewhere than the range's start: the
+     *  side a selected widget was selected from. */
+    caretBefore?: number;
 }
 export interface PasteDispatchContext {
     doc: Document;
-    /** Action bundle for the target's level. Not used in cross-block (undoEntry: 'join') mode. */
+    /** Action bundle for the target's level. Not used on the cross-block route. */
     blockEdit: BlockEditActions;
-    /** Commit coordinator — required by the multi-scope commit sites inside this module. */
+    /** Commit coordinator, required by the multi-scope commit sites inside this module. */
     controller: PasteCommitCoordinator;
-    /** `'join'`: the cross-block caller owns the undo entry, so no snapshot is pushed here. */
-    undoEntry?: UndoEntryMode;
-    /** The instance's grammar: the clipboard parse below and the join branch's same-slot
-     *  reparse both read it, so an unlisted plugin's opener never claims pasted bytes here.
-     *  Absent = global. */
-    grammar?: GrammarView;
-    /** The plugins this instance activated, so an unlisted plugin's paste transform stays out
-     *  of the pipeline; absent = every installed plugin. */
-    activePlugins?: PluginActivation;
-    /** What the paste's DELETE half needs to cross the join seam; absent leaves it byte-literal. */
-    seam?: PasteSeam;
+    /** The paste lands at the caret a cross-block range delete left: every write commits at the
+     *  target's parent list, and a partly filled item may take a matching container's items. */
+    crossBlock?: boolean;
+    /** The clipboard parse and the join's reparse use its grammar, so an unlisted plugin's opener
+     *  never takes pasted bytes; its mode decides the delete half's cleanup. */
+    reading: Reading;
+    /** The plugins this instance activated, so an unlisted plugin's paste hooks stay out. */
+    activePlugins: PluginActivation;
 }
 /** Where an inline paste's caret belongs once the commit settled, when that moved it. */
 export interface InlineCaretLanding {
@@ -46,16 +45,14 @@ export interface InlineCaretLanding {
     offset: number;
 }
 export interface PasteDispatchResult {
-    /**
-     * Inline-paste caret offset; undefined for structural paste, which handles focus
-     * itself. Single-block callers apply it synchronously with the raw mutation so both
-     * land in one reactive flush.
-     */
+    /** Undefined for a structural paste, which places its own caret. Single-block callers apply it
+     *  with the raw write, so both land in one reactive flush. */
     inlineCaretOffset?: number;
-    /** The cross-block route's settled landing: a fold above the target moved the slot itself. */
+    /** Where the cross-block route's caret ended up, when a merge above the target moved the
+     *  block itself. */
     inlineCaretPath?: number[];
 }
 /** Execute a paste at the specified target position. */
 export declare function pasteDispatch(input: PasteDispatchInput, ctx: PasteDispatchContext): Promise<PasteDispatchResult>;
 export { pickPasteStrategy } from './strategy';
-export { defaultInlineHook, defaultStructuralHook, __getDefaultTextSurface } from './hooks';
+export { defaultInlineHook, defaultStructuralHook } from './hooks';