@voithos-labs/aragonite 0.10.1

package/dist/tree-operations/parse-block.d.ts

@@ -0,0 +1,3 @@
+import type { CstNode } from '../core/nodes';
+/** Parse one block's `raw` and return its first block, falling back to a paragraph node. */
+export declare function parseFirstBlock(raw: string): CstNode;

package/dist/tree-operations/parse-block.js

@@ -0,0 +1,8 @@
+import { parse } from '../core/parser';
+/** Parse one block's `raw` and return its first block, falling back to a paragraph node. */
+export function parseFirstBlock(raw) {
+    const doc = parse(raw, { scope: 'fragment' });
+    if (doc.children.length > 0)
+        return doc.children[0];
+    return { kind: 'paragraph', leadingTrivia: '', raw };
+}

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

@@ -0,0 +1,12 @@
+/** Applies the results a paste surface hook produced to the document. */
+import type { InlinePasteResult, StructuralPasteResult } from '../paste-surfaces';
+import type { PasteDispatchContext, InlineCaretLanding } from './dispatch';
+/**
+ * Apply an inline paste. Single-block routes through `updateBlockContent`; cross-block
+ * commits the same re-parse funnel directly against the parent scope, because the
+ * originating bundle may not match the target's level. The single-block route stays
+ * synchronous through its mutation so the caller can set cursor state before the first
+ * reactivity flush.
+ */
+export declare function applyInlineResult(targetPath: number[], result: InlinePasteResult, ctx: PasteDispatchContext): Promise<InlineCaretLanding | undefined>;
+export declare function applyStructuralResult(targetPath: number[], result: StructuralPasteResult, ctx: PasteDispatchContext, trailingSeparator?: string): Promise<void>;

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

@@ -0,0 +1,75 @@
+/** Applies the results a paste surface hook produced to the document. */
+import { settledCaretTarget, updateNodeContent } from '../node-ops';
+import { ensureUnsharedChild } from '../unshare';
+import { docPathFrom } from '../../cursor/coordinate-spaces';
+import { stampStructuralChange } from '../structural-change';
+import { resolveParentScope } from './parent-scope';
+import { replaceBlockAtParent } from './replace-block-at-parent';
+/**
+ * Apply an inline paste. Single-block routes through `updateBlockContent`; cross-block
+ * commits the same re-parse funnel directly against the parent scope, because the
+ * originating bundle may not match the target's level. The single-block route stays
+ * synchronous through its mutation so the caller can set cursor state before the first
+ * reactivity flush.
+ */
+export async function applyInlineResult(targetPath, result, ctx) {
+    if (ctx.undoEntry === 'join') {
+        return commitInlineJoin(targetPath, result, ctx);
+    }
+    // Unawaited: the caller sets pendingCursorOffset in the same synchronous block, so both
+    // land in one reactive flush.
+    const blockIndex = targetPath[targetPath.length - 1];
+    void ctx.blockEdit.updateBlockContent(blockIndex, result.newRaw, result.caretOffset);
+    return undefined;
+}
+/**
+ * Cross-block inline paste. `'join'` means the caller already pushed the covering
+ * snapshot, not that the ceremony is skipped — committing is what keeps the parent's
+ * `childIds` aligned and puts the insertion on the `edit` stream. The mutation routes
+ * through the same-slot re-parse funnel, so a paste completing marker syntax re-mints the
+ * slot at the reparsed kind instead of leaving the old kind holding foreign bytes.
+ */
+async function commitInlineJoin(targetPath, result, ctx) {
+    const scope = resolveParentScope(ctx.doc, targetPath, ctx.controller);
+    if (!scope)
+        return undefined;
+    const leafIndex = targetPath[targetPath.length - 1];
+    let settled = { change: { op: 'noop' }, textStart: 0 };
+    let siblings = [];
+    await ctx.controller.commitMultiScope({
+        scopes: [scope],
+        snapshot: 'skip',
+        mutate: ([view]) => {
+            // The slot may still be snapshot-shared, and the funnel's same-kind branch writes
+            // its raw in place (G1.9).
+            ensureUnsharedChild(view, leafIndex, view.sharing);
+            settled = updateNodeContent({ children: view.children, ownerKind: view.node.kind, owner: view.node }, leafIndex, result.newRaw, ctx.grammar, view.sharing);
+            siblings = view.children;
+            stampStructuralChange(view.children, settled.change, view.sharing);
+            return [settled.change];
+        },
+        op: {
+            kind: 'updateContent',
+            detail: { length: result.newRaw.length },
+            eventPath: docPathFrom(targetPath)
+        }
+    });
+    // The paste can demote the slot's kind, and a settle that absorbed the join above it left
+    // the predecessor holding the pasted bytes — so the caller's own caret target is stale.
+    const target = settledCaretTarget(settled, leafIndex, result.caretOffset, siblings);
+    return { path: [...targetPath.slice(0, -1), target.index], offset: target.offset };
+}
+export async function applyStructuralResult(targetPath, result, ctx, trailingSeparator = '') {
+    await replaceBlockAtParent({
+        doc: ctx.doc,
+        blockPath: targetPath,
+        replacement: result.replacement,
+        controller: ctx.controller,
+        undoEntry: ctx.undoEntry ?? 'own',
+        focusReplacementIndex: result.focusReplacementIndex,
+        focusOffset: result.focusOffset,
+        source: 'paste-dispatch',
+        trailingSeparator,
+        ...(ctx.grammar ? { grammar: ctx.grammar } : {})
+    });
+}

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

@@ -0,0 +1,19 @@
+/**
+ * The paste family's `bodyWrite` moment: paste builds nodes upstream of every
+ * node-ops 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.
+ */
+import type { AnyBlockKind, CstNode, Document } from '../../core/nodes';
+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;
+export interface BodyLegalReplacement {
+    replacement: CstNode[];
+    /** A pre-normalize replacement index, mapped past any escape reparse that grew the list. */
+    mapIndex: (index: number) => number;
+}
+/**
+ * Replacement nodes made legal as `ownerKind` 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;

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

@@ -0,0 +1,53 @@
+/**
+ * The paste family's `bodyWrite` moment: paste builds nodes upstream of every
+ * node-ops 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.
+ */
+import { parse } from '../../core/parser';
+import { tryGetBlockKindDescriptor } from '../../schema/block-kind-descriptor';
+import { ensureEditableContainers, isBlockNode, nodeAt, normalizeBodyWrite, normalizeReplacementTrivia } from '../node-ops';
+/** Clipboard text made legal inside every `bodyWrite`-declaring ancestor of the paste target. */
+export function normalizeClipboardForBody(doc, targetPath, text) {
+    let out = text;
+    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);
+    }
+    return out;
+}
+/**
+ * Replacement nodes made legal as `ownerKind` 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) {
+        return { replacement, mapIndex: (i) => i };
+    }
+    const out = [];
+    const starts = [];
+    for (const node of replacement) {
+        starts.push(out.length);
+        const escaped = normalizeBodyWrite(ownerKind, node.raw);
+        if (escaped === node.raw) {
+            out.push(node);
+            continue;
+        }
+        const reparsed = parse(escaped, {
+            scope: 'fragment',
+            ...(grammar ? { grammar } : {})
+        }).children;
+        if (reparsed.length === 0) {
+            out.push(node);
+            continue;
+        }
+        const carried = normalizeReplacementTrivia(node, reparsed);
+        for (const minted of carried)
+            ensureEditableContainers(minted);
+        out.push(...carried);
+    }
+    return {
+        replacement: out,
+        mapIndex: (i) => (starts.length === 0 ? 0 : (starts[Math.min(i, starts.length - 1)] ?? 0))
+    };
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Container-matching unwrap: when the clipboard's top block declares `containerPaste` and
+ * a same-kind ancestor passes its `matchesAncestor` predicate, splice items into that
+ * ancestor instead of nesting a sub-container.
+ */
+import type { CstNode, Document } from '../../core/nodes';
+import type { PasteDispatchContext } from './dispatch';
+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.
+     */
+    merge?: {
+        targetLeafPath: number[];
+        offset: number;
+        /** 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.
+ */
+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 {};

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

@@ -0,0 +1,238 @@
+/**
+ * Container-matching unwrap: when the clipboard's top block declares `containerPaste` and
+ * a same-kind ancestor passes its `matchesAncestor` predicate, splice items into that
+ * ancestor instead of nesting a sub-container.
+ */
+import { CURSOR_END } from '../../block-component';
+import { devWarn } from '../../dev-warn';
+import { trailingLineEnding, trimTrailingLineEnding } from '../../core/lines';
+import { nodeAt, settledCaretTarget, updateNodeContent, writeOwnRaw } from '../node-ops';
+import { containerPasteFor } from './container-paste';
+import { rebuildContainerRawIfContainer } from '../../schema/container-raw';
+import { ensureUnsharedNode, ensureUnsharedPath, rebuildUnsharedChain } from '../unshare';
+import { containerScopeState } from './parent-scope';
+import { applyStructuralChangeToIdsRefs, stampStructuralChange } from '../structural-change';
+import { renumberOrderedList, templatePastedItemMarkers } from '../list/ordered-markers';
+import { spliceTerminatedItems } from '../list/terminator';
+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.
+ */
+export function findContainerMatchingUnwrap(doc, targetPath, offset, parsed, crossBlockContext, targetRaw) {
+    if (parsed.children.length !== 1)
+        return null;
+    const topBlock = parsed.children[0];
+    const containerPaste = containerPasteFor(topBlock.kind);
+    if (!containerPaste)
+        return null;
+    if (!topBlock.children || topBlock.children.length === 0)
+        return null;
+    // The bytes the strategies decide on: the target's own, post-delete.
+    const targetLeaf = nodeAt(doc, targetPath);
+    const postDelete = { node: targetLeaf, raw: targetRaw ?? targetLeaf?.raw ?? '' };
+    for (let depth = targetPath.length - 1; depth >= 1; depth--) {
+        const ancestorPath = targetPath.slice(0, depth);
+        const ancestor = nodeAt(doc, ancestorPath);
+        if (!ancestor)
+            break;
+        if (ancestor.kind !== topBlock.kind)
+            continue;
+        if (!containerPaste.matchesAncestor(topBlock, ancestor))
+            continue;
+        const spliceIndex = targetPath[depth];
+        const targetChild = ancestor.children?.[spliceIndex];
+        if (!targetChild)
+            continue;
+        if (isEmptyContainerChild(targetChild, postDelete)) {
+            return { outerPath: ancestorPath, spliceIndex, items: topBlock.children };
+        }
+        // Merge-first / trailing-residue semantics are only well-defined for
+        // single-paragraph first and last items.
+        if (!crossBlockContext)
+            return null;
+        if (!singleParagraphChildOf(topBlock.children[0]))
+            return null;
+        if (!singleParagraphChildOf(topBlock.children[topBlock.children.length - 1]))
+            return null;
+        return {
+            outerPath: ancestorPath,
+            spliceIndex,
+            items: topBlock.children,
+            merge: { targetLeafPath: targetPath, offset, targetRaw: postDelete.raw }
+        };
+    }
+    return null;
+}
+/** One leaf child whose raw has no visible content (post-cross-block-delete stub). */
+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() === '';
+    if (node.children.length !== 1)
+        return false;
+    const c = node.children[0];
+    if (c.kind !== 'paragraph')
+        return false;
+    return rawOf(c).trim() === '';
+}
+/**
+ * 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.
+ */
+function singleParagraphChildOf(node) {
+    if (!node.children || node.children.length !== 1)
+        return null;
+    const child = node.children[0];
+    return child.kind === 'paragraph' ? child : null;
+}
+export async function applyContainerMatchingPaste(unwrap, ctx) {
+    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);
+        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,
+        mutate: ([scopeView]) => {
+            spliceTerminatedItems(scopeView.children, unwrap.spliceIndex, 1, unwrap.items);
+            const change = {
+                op: 'replace',
+                at: unwrap.spliceIndex,
+                count: 1,
+                newCount: unwrap.items.length
+            };
+            stampStructuralChange(scopeView.children, change, scopeView.sharing);
+            // The already-proxied tail; the pasted items carry precomputed markers.
+            renumberOrderedList(scopeView.node, unwrap.spliceIndex + unwrap.items.length, scopeView.sharing);
+            return [change];
+        },
+        op: {
+            kind: 'paste',
+            detail: { source: 'container-matching', outerPath: unwrap.outerPath },
+            eventPath: docPathFrom(unwrap.outerPath)
+        },
+        afterTick: () => {
+            const lastInsertedIdx = unwrap.spliceIndex + unwrap.items.length - 1;
+            return ctx.controller.landCaret([...unwrap.outerPath, lastInsertedIdx], CURSOR_END);
+        }
+    });
+}
+/** A single-item clipboard keeps everything in the target leaf. */
+async function applyContainerMatchingMerge(unwrap, merge, outer, outerState, ctx) {
+    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.
+        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);
+    const targetDisplay = trimTrailingLineEnding(merge.targetRaw);
+    const displayBefore = targetDisplay.slice(0, merge.offset);
+    const displayAfter = targetDisplay.slice(merge.offset);
+    const firstItemText = trimTrailingLineEnding(firstLeaf.raw);
+    const remainingItems = unwrap.items.slice(1);
+    // 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) };
+    };
+    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);
+                return [{ op: 'noop' }];
+            },
+            op: {
+                kind: 'paste',
+                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)
+        });
+        return;
+    }
+    const lastItem = remainingItems[remainingItems.length - 1];
+    const lastLineEnding = trailingLineEnding(lastLeaf.raw);
+    const lastDisplay = trimTrailingLineEnding(lastLeaf.raw);
+    let residue = { change: { op: 'noop' }, textStart: 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 + targetLineEnding, ctx.grammar);
+            // 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.
+            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
+            // raws in one reactive flush.
+            rebuildUnsharedChain(ctx.doc, chain, sharing, null, ctx.grammar);
+            rebuildContainerRawIfContainer(remainingItems[remainingItems.length - 1]);
+            // The siblings land after the merged target, which keeps its own slot.
+            const insertAt = unwrap.spliceIndex + 1;
+            const change = {
+                op: 'insert',
+                at: insertAt,
+                count: remainingItems.length
+            };
+            spliceTerminatedItems(scopeView.children, insertAt, 0, remainingItems);
+            stampStructuralChange(scopeView.children, change, sharing);
+            // The already-proxied tail below the spliced siblings; the merged target keeps
+            // its number.
+            renumberOrderedList(scopeView.node, insertAt + remainingItems.length, sharing);
+            return [change];
+        },
+        op: {
+            kind: 'paste',
+            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.
+            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);
+        }
+    });
+}

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

@@ -0,0 +1,10 @@
+/**
+ * The one door the paste gates reach 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.
+ */
+import type { AnyBlockKind } from '../../core/nodes';
+import type { BlockKindDescriptor } from '../../schema/block-kind-descriptor';
+export type ContainerPasteDeclaration = NonNullable<BlockKindDescriptor['containerPaste']>;
+export declare function containerPasteFor(kind: AnyBlockKind): ContainerPasteDeclaration | undefined;

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

@@ -0,0 +1,27 @@
+/**
+ * The one door the paste gates reach 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.
+ */
+import { tryGetBlockKindDescriptor } from '../../schema/block-kind-descriptor';
+import { devWarn } from '../../dev-warn';
+export function containerPasteFor(kind) {
+    const declared = tryGetBlockKindDescriptor(kind)?.containerPaste;
+    if (!declared)
+        return undefined;
+    return {
+        siblingAbsorb: declared.siblingAbsorb,
+        matchesAncestor: (clipboardTop, ancestor) => {
+            try {
+                return declared.matchesAncestor(clipboardTop, ancestor);
+            }
+            catch (error) {
+                // Decline, so a broken predicate degrades the paste to the generic structural
+                // path rather than aborting mid-gesture.
+                devWarn('container-paste', `matchesAncestor threw for kind "${kind}"`, error);
+                return false;
+            }
+        }
+    };
+}

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

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ */
+import type { BlockEditActions, UndoEntryMode } from '../../action-contracts';
+import type { Document } from '../../core/nodes';
+import type { GrammarView } from '../../schema/block-openers';
+import type { PluginActivation } from '../../schema/plugin-activation';
+import { type PasteRange, type PasteSeam } from '../paste-surfaces';
+import type { PasteCommitCoordinator } from './paste-deps';
+export type PasteStrategy = 'inline' | 'structural';
+export interface PasteDispatchInput {
+    /** Raw clipboard text. */
+    pastedText: string;
+    /** Path from Document root to the target node. Length ≥ 1. */
+    targetPath: number[];
+    /** Caret offset within the target node's raw. */
+    offset: number;
+    /** Selection range within the target's raw (not cross-block). */
+    preDelete?: PasteRange;
+}
+export interface PasteDispatchContext {
+    doc: Document;
+    /** Action bundle for the target's level. Not used in cross-block (undoEntry: 'join') mode. */
+    blockEdit: BlockEditActions;
+    /** 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;
+}
+/** Where an inline paste's caret belongs once the commit settled, when that moved it. */
+export interface InlineCaretLanding {
+    path: number[];
+    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.
+     */
+    inlineCaretOffset?: number;
+    /** The cross-block route's settled landing: a fold above the target moved the slot 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';