@voithos-labs/aragonite 0.10.1

package/dist/tree-operations/paste/parent-scope.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The commit scope a paste addresses when it re-mints or splices a block: the block's
+ * PARENT container, resolved from the path rather than from whatever `blockEdit` is in
+ * scope — a caller holding a nested-bundle blockEdit would misroute through the wrong
+ * container.
+ */
+import type { CstNode, Document } from '../../core/nodes';
+import type { MultiScopeTarget, PasteCommitCoordinator } from './paste-deps';
+/** Null when `blockPath`'s parent doesn't resolve to a container. */
+export declare function resolveParentScope(doc: Document, blockPath: number[], controller: PasteCommitCoordinator): MultiScopeTarget | null;
+/**
+ * A container's mounted `BlockListState`, or a detached stand-in. Never `expectState`:
+ * these routes can be a cross-block paste whose range delete ALREADY committed, so a throw
+ * would leave the selection deleted and nothing pasted. The ceremony writes ids to the
+ * owned node's `childIds`, so only ref alignment is lost on the stand-in.
+ */
+export declare function containerScopeState(controller: PasteCommitCoordinator, node: CstNode): MultiScopeTarget['state'];

package/dist/tree-operations/paste/parent-scope.js

@@ -0,0 +1,35 @@
+/**
+ * The commit scope a paste addresses when it re-mints or splices a block: the block's
+ * PARENT container, resolved from the path rather than from whatever `blockEdit` is in
+ * scope — a caller holding a nested-bundle blockEdit would misroute through the wrong
+ * container.
+ */
+import { nodeAt } from '../node-ops';
+import { devWarn } from '../../dev-warn';
+/** Null when `blockPath`'s parent doesn't resolve to a container. */
+export function resolveParentScope(doc, blockPath, controller) {
+    const parentPath = blockPath.slice(0, -1);
+    if (parentPath.length === 0)
+        return controller.getDocScope();
+    const parentNode = nodeAt(doc, parentPath);
+    if (!parentNode?.children)
+        return null;
+    return {
+        node: parentNode,
+        state: containerScopeState(controller, parentNode),
+        path: parentPath
+    };
+}
+/**
+ * A container's mounted `BlockListState`, or a detached stand-in. Never `expectState`:
+ * these routes can be a cross-block paste whose range delete ALREADY committed, so a throw
+ * would leave the selection deleted and nothing pasted. The ceremony writes ids to the
+ * owned node's `childIds`, so only ref alignment is lost on the stand-in.
+ */
+export function containerScopeState(controller, node) {
+    const mounted = controller.resolveState(node);
+    if (mounted)
+        return mounted;
+    devWarn('paste', `committing at an unmounted ${node.kind} scope — ids realign, component refs do not`);
+    return { innerBlockIds: [...(node.childIds ?? [])], innerBlockRefs: [] };
+}

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

@@ -0,0 +1,20 @@
+/**
+ * What paste modules need from the commit/undo layer. Declared here rather than imported,
+ * which is what keeps the `tree-operations -> editor-actions` and
+ * `tree-operations -> reactivity` back-edges out of the graph.
+ */
+import type { CommitMultiScopeArgs, MultiScopeTarget } from '../../action-contracts';
+import type { CstNode } from '../../core/nodes';
+export type { CommitMultiScopeArgs, MultiScopeTarget };
+export interface PasteCommitCoordinator {
+    commitMultiScope<const S extends readonly MultiScopeTarget[]>(args: CommitMultiScopeArgs<S>): Promise<void>;
+    getDocScope(): MultiScopeTarget;
+    /** Resolve a container node to its mounted reactive state. */
+    resolveState(node: CstNode): MultiScopeTarget['state'] | undefined;
+    /**
+     * Land the caret at a doc-absolute path, revealing an off-window target first. A
+     * structural paste lands at the END of the pasted run, so its target index scales with
+     * the clipboard and a sync ref lookup would no-op past the window's overscan (VR-12).
+     */
+    landCaret(path: number[], offset: number): Promise<void>;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * What paste modules need from the commit/undo layer. Declared here rather than imported,
+ * which is what keeps the `tree-operations -> editor-actions` and
+ * `tree-operations -> reactivity` back-edges out of the graph.
+ */
+export {};

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

@@ -0,0 +1,8 @@
+/**
+ * Replacement node list for a multi-block paste into a single leaf: the leaf's raw split
+ * at the cursor, with the pasted blocks between the slices. STRUCTURAL pastes only —
+ * routing a single-paragraph clipboard here would split it into three nodes.
+ */
+import type { CstNode } from '../../core/nodes';
+import type { NodeView } from '../../core/node-views';
+export declare function buildPastedReplacement(leaf: NodeView, offset: number, blocks: CstNode[]): CstNode[];

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

@@ -0,0 +1,60 @@
+/**
+ * Replacement node list for a multi-block paste into a single leaf: the leaf's raw split
+ * at the cursor, with the pasted blocks between the slices. STRUCTURAL pastes only —
+ * routing a single-paragraph clipboard here would split it into three nodes.
+ */
+import { snapToScalarBoundary, trailingLineEnding, trimTrailingLineEnding } from '../../core/lines';
+import { isBlankParagraph } from '../../core/parser';
+import { ensureEditableContainers } from '../node-ops';
+import { parseFirstBlock } from '../parse-block';
+export function buildPastedReplacement(leaf, offset, blocks) {
+    if (blocks.length === 0)
+        return [];
+    const leafRaw = leaf.raw;
+    const lineEnding = trailingLineEnding(leafRaw);
+    const display = trimTrailingLineEnding(leafRaw);
+    // Off any scalar interior before the cut: the halves land in DIFFERENT blocks, so a pair
+    // split here is unrecoverable bytes rather than a recoverable edit.
+    const cut = snapToScalarBoundary(display, offset);
+    const rawBefore = display.slice(0, cut);
+    const rawAfter = display.slice(cut);
+    const originalTrivia = leaf.leadingTrivia ?? '';
+    const newNodes = [];
+    // Re-parsed so heading/list leaves round-trip through their own parser rather than
+    // being forced back to a paragraph.
+    if (rawBefore.length > 0) {
+        const beforeRaw = rawBefore + lineEnding;
+        const beforeNode = parseFirstBlock(beforeRaw);
+        beforeNode.leadingTrivia = originalTrivia;
+        ensureEditableContainers(beforeNode);
+        newNodes.push(beforeNode);
+    }
+    // A blank-line separator is forced where source trivia is empty, or the block butts
+    // against its predecessor via a soft break and renders as one merged paragraph. A blank
+    // predecessor already holds a run open, so its successor takes no separator of its own.
+    for (let i = 0; i < blocks.length; i++) {
+        const node = { ...blocks[i] };
+        const prev = newNodes[newNodes.length - 1];
+        if (newNodes.length === 0) {
+            node.leadingTrivia = originalTrivia;
+        }
+        else if (prev !== undefined && isBlankParagraph(prev)) {
+            node.leadingTrivia = blocks[i].leadingTrivia ?? '';
+        }
+        else {
+            node.leadingTrivia = blocks[i].leadingTrivia ? blocks[i].leadingTrivia : lineEnding;
+        }
+        ensureEditableContainers(node);
+        newNodes.push(node);
+    }
+    // Separate node rather than merged into the last pasted block, which would let a
+    // non-paragraph tail absorb it as a continuation line.
+    if (rawAfter.length > 0) {
+        const afterRaw = rawAfter + lineEnding;
+        const afterNode = parseFirstBlock(afterRaw);
+        afterNode.leadingTrivia = lineEnding;
+        ensureEditableContainers(afterNode);
+        newNodes.push(afterNode);
+    }
+    return newNodes;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Content-keyed, pre-parse paste transforms: a plugin registers a named transform that
+ * rewrites the raw clipboard text or declines. Register-once, throw-on-duplicate — the
+ * `customElements` model shared with `paste-surfaces.ts`.
+ */
+import type { PluginActivation } from '../../schema/plugin-activation';
+export interface PasteTransform {
+    /** Unique across the process; a duplicate registration throws. */
+    readonly name: string;
+    /** A replacement for `text`, or null to decline. A throw is contained as a decline. */
+    transform(text: string): string | null;
+}
+export declare function registerPasteTransform(transform: PasteTransform): void;
+/**
+ * Non-throwing registration probe, so an idempotent module (HMR, a re-imported registrar) asks
+ * before registering instead of catching the duplicate throw.
+ */
+export declare function isPasteTransformRegistered(name: string): boolean;
+/**
+ * Run every transform over `text` in registration order, each seeing the prior's output;
+ * a null return leaves the running text untouched. `activation` scopes the run to one
+ * instance's plugins; absent = every installed one. A transform no plugin owns always runs.
+ */
+export declare function applyPasteTransforms(text: string, activation?: PluginActivation): string;
+export declare function __resetPasteTransformsForTests(): void;

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

@@ -0,0 +1,72 @@
+import { currentInstallingPlugin } from '../../schema/plugin-install';
+import { registerOnce } from '../../schema/register-once';
+import { devWarn } from '../../dev-warn';
+import { editorEnv } from '../../env';
+// Map iteration is insertion order, so `.values()` is the pipeline order while the keyed
+// lookup guards duplicates — one structure, no parallel array.
+const transforms = new Map();
+export function registerPasteTransform(transform) {
+    const existing = transforms.get(transform.name);
+    registerOnce(existing !== undefined, () => transforms.set(transform.name, { transform, owner: currentInstallingPlugin() }), `registerPasteTransform: "${transform.name}" is already registered` +
+        (existing?.owner ? ` by plugin '${existing.owner}'` : '') +
+        `. Paste transforms are register-once.`);
+}
+/**
+ * Non-throwing registration probe, so an idempotent module (HMR, a re-imported registrar) asks
+ * before registering instead of catching the duplicate throw.
+ */
+export function isPasteTransformRegistered(name) {
+    return transforms.has(name);
+}
+/**
+ * Run every transform over `text` in registration order, each seeing the prior's output;
+ * a null return leaves the running text untouched. `activation` scopes the run to one
+ * instance's plugins; absent = every installed one. A transform no plugin owns always runs.
+ */
+export function applyPasteTransforms(text, activation) {
+    if (transforms.size === 0)
+        return text;
+    let result = text;
+    for (const { transform, owner } of transforms.values()) {
+        if (owner !== null && activation && !activation.isActive(owner))
+            continue;
+        const next = runContained(transform, result, 'pipeline');
+        if (next === null)
+            continue;
+        warnIfNonIdempotent(transform, next);
+        result = next;
+    }
+    return result;
+}
+export function __resetPasteTransformsForTests() {
+    transforms.clear();
+}
+/**
+ * The one door plugin `transform()` code is called through. On the cross-block route the
+ * covering range delete has already committed, so an escaping throw would leave the
+ * selection deleted and nothing pasted; a throw becomes the null a decline returns. The
+ * warning names its phase because a probe-time throw read as a decline would send the
+ * author debugging a paste that worked.
+ */
+function runContained(transform, text, phase) {
+    try {
+        return transform.transform(text);
+    }
+    catch (error) {
+        const outcome = phase === 'pipeline'
+            ? 'in the paste pipeline; declining, so the running text is untouched'
+            : 'in the dev idempotence probe; the paste keeps its first result';
+        devWarn('paste-transform', `transform '${transform.name}' threw ${outcome}`, error);
+        return null;
+    }
+}
+// A transform whose own output feeds back into a further rewrite drives a paste feedback
+// loop, so in dev it is re-run on its result: it must decline or reproduce it.
+function warnIfNonIdempotent(transform, result) {
+    if (!editorEnv.isDev)
+        return;
+    const again = runContained(transform, result, 'probe');
+    if (again !== null && again !== result) {
+        devWarn('paste-transform', `transform '${transform.name}' is not idempotent — re-running it on its own output changed the text again`);
+    }
+}

package/dist/tree-operations/paste/replace-block-at-parent.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Replace the block at `blockPath`, committing at its parent scope (`parent-scope.ts`)
+ * rather than through the caller's blockEdit — paste-into-cell must mutate `doc.children`
+ * while holding the row-level nested bundle.
+ */
+import type { UndoEntryMode } from '../../action-contracts';
+import type { OperationDetailMap } from '../../schema/operations';
+import type { CstNode, Document } from '../../core/nodes';
+import type { GrammarView } from '../../schema/block-openers';
+import type { PasteCommitCoordinator } from './paste-deps';
+export interface ReplaceBlockAtParentArgs {
+    doc: Document;
+    /** Path to the block being replaced. Length ≥ 1. */
+    blockPath: number[];
+    replacement: CstNode[];
+    controller: PasteCommitCoordinator;
+    undoEntry: UndoEntryMode;
+    /** Index into `replacement` to focus after the commit. */
+    focusReplacementIndex: number;
+    focusOffset: number;
+    source: Extract<OperationDetailMap['replaceBlock'], {
+        source: unknown;
+    }>['source'];
+    /** Instance grammar for the escape's kind re-derive; absent = global. */
+    grammar?: GrammarView;
+    /** The clipboard's own trailing blank line, where nothing in the splice stands for it. */
+    trailingSeparator?: string;
+}
+export declare function replaceBlockAtParent(args: ReplaceBlockAtParentArgs): Promise<void>;

package/dist/tree-operations/paste/replace-block-at-parent.js

@@ -0,0 +1,75 @@
+/**
+ * Replace the block at `blockPath`, committing at its parent scope (`parent-scope.ts`)
+ * rather than through the caller's blockEdit — paste-into-cell must mutate `doc.children`
+ * while holding the row-level nested bundle.
+ */
+import { nodeAt } from '../node-ops';
+import { spliceMany } from '../splice-many';
+import { trailingLineEnding } from '../../core/lines';
+import { normalizeReplacementForBody } from './body-write';
+import { landedPasteOffset, trackedPasteCaret } from './focus-target';
+import { resolveParentScope } from './parent-scope';
+import { docPathFrom } from '../../cursor/coordinate-spaces';
+import { replacePreservingFirst, stampStructuralChange } from '../structural-change';
+/**
+ * Land the clipboard's trailing blank where a reload folds one: the DOCUMENT's own suffix, and
+ * only at a tail whose slot is empty — one separation is one separation. A container tail
+ * declines, since `innerSuffix` is the wrap-peel settle's register on this same commit. The
+ * clipboard says WHETHER a line lands, never which one: normalized to LF at every entry point,
+ * its own suffix would strand an LF line in a CRLF document (G4.20).
+ */
+function landTrailingSeparator(args, children, afterIndex, ending) {
+    if (!args.trailingSeparator || args.blockPath.length !== 1)
+        return;
+    if (args.doc.suffix !== '' || afterIndex !== children.length)
+        return;
+    args.doc.suffix = ending;
+}
+export async function replaceBlockAtParent(args) {
+    const { doc, blockPath, controller, undoEntry, focusOffset, source } = args;
+    const blockIdx = blockPath[blockPath.length - 1];
+    const scope = resolveParentScope(doc, blockPath, controller);
+    if (!scope)
+        return;
+    // A replacement is minted before any byte sink sees it, so the owner's bodyWrite escape
+    // lands here — on the clipboard blocks AND the target's split halves alike.
+    const ownerKind = blockPath.length > 1 ? scope.node.kind : undefined;
+    const { replacement, mapIndex } = normalizeReplacementForBody(ownerKind, args.replacement, args.grammar);
+    const focusReplacementIndex = mapIndex(args.focusReplacementIndex);
+    // The settle can fold the spliced window into its neighbours, which moves both halves of the
+    // landing: the residue reattaches inside the last pasted leaf, and an absorb above moves the
+    // slot itself. The commit carries this through its folds and `afterTick` reads it back.
+    const caret = trackedPasteCaret(replacement, blockIdx, focusReplacementIndex, focusOffset);
+    const oldBlock = nodeAt(doc, blockPath);
+    const sameKindFirst = oldBlock !== null && replacement.length > 0 && replacement[0].kind === oldBlock.kind;
+    // Read as bytes before the commit: the displaced block is the document's own ending, and a
+    // node held across a commit goes stale the moment the spine unshares.
+    const tailEnding = oldBlock ? trailingLineEnding(oldBlock.raw) : '\n';
+    await controller.commitMultiScope({
+        scopes: [scope],
+        snapshot: undoEntry === 'join' ? 'skip' : { path: docPathFrom(blockPath), offset: 0 },
+        mutate: ([scopeView]) => {
+            spliceMany(scopeView.children, blockIdx, 1, replacement);
+            // Identity preservation only helps on a kind match; BlockHost dispatches by kind,
+            // so a different kind remounts anyway.
+            const change = sameKindFirst
+                ? replacePreservingFirst(blockIdx, 1, replacement.length)
+                : { op: 'replace', at: blockIdx, count: 1, newCount: replacement.length };
+            stampStructuralChange(scopeView.children, change, scopeView.sharing);
+            landTrailingSeparator(args, scopeView.children, blockIdx + replacement.length, tailEnding);
+            return [change];
+        },
+        op: {
+            kind: 'replaceBlock',
+            detail: { source },
+            eventPath: docPathFrom(blockPath)
+        },
+        trackCaret: [caret],
+        afterTick: () => {
+            // Re-read from the document: the ceremony unshares the spine, so the scope node the
+            // caller resolved is a stale copy by now.
+            const landed = nodeAt(doc, scope.path)?.children?.[caret.index];
+            return controller.landCaret([...scope.path, caret.index], landedPasteOffset(landed, caret, focusOffset));
+        }
+    });
+}

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

@@ -0,0 +1,9 @@
+import type { CstNode } from '../../core/nodes';
+import type { PasteStrategy } from './dispatch';
+/**
+ * The clipboard's content blocks: a blank block at either edge is the copy's packaging, which a
+ * surface holding no blocks classifies past. Empty when nothing but packaging came across.
+ */
+export declare function contentBlocks(blocks: readonly CstNode[]): readonly CstNode[];
+/** One paragraph is text any leaf can take inline; anything else is structure. */
+export declare function pickPasteStrategy(blocks: readonly CstNode[]): PasteStrategy;

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

@@ -0,0 +1,20 @@
+import { isBlankParagraph } from '../../core/parser';
+/**
+ * The clipboard's content blocks: a blank block at either edge is the copy's packaging, which a
+ * surface holding no blocks classifies past. Empty when nothing but packaging came across.
+ */
+export function contentBlocks(blocks) {
+    let start = 0;
+    let end = blocks.length;
+    while (start < end && isBlankParagraph(blocks[start]))
+        start++;
+    while (end > start && isBlankParagraph(blocks[end - 1]))
+        end--;
+    return blocks.slice(start, end);
+}
+/** One paragraph is text any leaf can take inline; anything else is structure. */
+export function pickPasteStrategy(blocks) {
+    if (blocks.length === 0)
+        return 'inline';
+    return blocks.length === 1 && blocks[0].kind === 'paragraph' ? 'inline' : 'structural';
+}

package/dist/tree-operations/paste/table-slice.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Split a table at a row boundary. `rowGoes` sends the anchor row to whichever half
+ * preserves caret continuity for the break-and-splice paste path.
+ */
+import type { CstNode } from '../../core/nodes';
+export type RowGoes = 'first' | 'second';
+export declare function sliceTableAtRow(table: CstNode, sliceRow: number, rowGoes: RowGoes): {
+    firstHalf: CstNode | null;
+    secondHalf: CstNode | null;
+};

package/dist/tree-operations/paste/table-slice.js

@@ -0,0 +1,39 @@
+/**
+ * Split a table at a row boundary. `rowGoes` sends the anchor row to whichever half
+ * preserves caret continuity for the break-and-splice paste path.
+ */
+import { metadataOf } from '../../core/nodes';
+import { rebuildContainerRaw } from '../../schema/container-raw';
+export function sliceTableAtRow(table, sliceRow, rowGoes) {
+    const rows = table.children;
+    const meta = metadataOf(table, 'table');
+    const splitAt = rowGoes === 'first' ? sliceRow + 1 : sliceRow;
+    const firstRows = rows.slice(0, splitAt);
+    const secondRows = rows.slice(splitAt);
+    const firstHalf = buildHalf(firstRows, meta);
+    const secondHalf = buildHalf(secondRows, meta);
+    if (firstHalf)
+        rebuildContainerRaw(firstHalf);
+    if (secondHalf)
+        rebuildContainerRaw(secondHalf);
+    return { firstHalf, secondHalf };
+}
+function buildHalf(rows, sourceMeta) {
+    if (rows.length === 0)
+        return null;
+    const cloned = rows.map((row, idx) => ({
+        ...row,
+        metadata: { isHeader: idx === 0 },
+        children: row.children.map((cell) => ({ ...cell }))
+    }));
+    return {
+        kind: 'table',
+        leadingTrivia: '',
+        raw: '',
+        metadata: {
+            columnCount: sourceMeta.columnCount,
+            alignments: sourceMeta.alignments.slice()
+        },
+        children: cloned
+    };
+}

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

@@ -0,0 +1,61 @@
+import type { UndoEntryMode } from '../action-contracts';
+import type { AnyBlockKind, CstNode, Document } from '../core/nodes';
+import type { PresentationMode } from '../presentation-mode';
+import type { InlineResolverRef } from '../schema/inline-construct-policy';
+import type { GrammarView } from '../schema/block-openers';
+import type { PasteCommitCoordinator } from './paste/paste-deps';
+export interface PasteRange {
+    start: number;
+    end: number;
+}
+/**
+ * What the join-seam cleanup needs from the caller: the paste's delete half is a join, and in
+ * live the runs it strands are bytes the reader never saw. Absent leaves the cut byte-literal,
+ * which is every non-live mode's answer anyway.
+ */
+export interface PasteSeam {
+    presentationMode: PresentationMode | undefined;
+    linkRef: InlineResolverRef | undefined;
+}
+export interface InlinePasteResult {
+    /** New raw for the target node (including trailing line ending). */
+    newRaw: string;
+    caretOffset: number;
+}
+export interface StructuralPasteResult {
+    replacement: CstNode[];
+    focusReplacementIndex: number;
+    focusOffset: number;
+}
+export interface ScopedStructuralPasteInput {
+    doc: Document;
+    targetPath: number[];
+    /** Pasted blocks, blank-line-materialized. */
+    blocks: CstNode[];
+    controller: PasteCommitCoordinator;
+    undoEntry: UndoEntryMode;
+    /** The instance grammar the splice owes its bodyWrite escape reparse. Required-nullable, so
+     *  a new scoped surface cannot silently drop it; `undefined` = global. */
+    grammar: GrammarView | undefined;
+}
+export interface PasteSurface {
+    kind: AnyBlockKind;
+    /**
+     * This surface holds text, never blocks (a table cell), so a blank block at the clipboard's
+     * edge is the copy's packaging: it neither picks the route nor lands in a structural splice.
+     */
+    blankEdgesArePackaging?: boolean;
+    /** Splice `text` into `node` at `offset` (optionally pre-deleting a range). Pure. */
+    onInlinePaste?(node: CstNode, offset: number, text: string, preDelete?: PasteRange, seam?: PasteSeam): InlinePasteResult;
+    /** Splice CST blocks at the target. Pure data transform. */
+    onStructuralPaste?(node: CstNode, offset: number, blocks: CstNode[], preDelete?: PasteRange, seam?: PasteSeam): StructuralPasteResult;
+    /**
+     * Structural paste whose splice scope is an ancestor (a tableCell splices at the
+     * table's parent). The hook owns the whole mutation; dispatch does nothing afterward.
+     */
+    onScopedStructuralPaste?(input: ScopedStructuralPasteInput): Promise<void>;
+}
+export declare function registerPasteSurface(surface: PasteSurface): void;
+export declare function getPasteSurface(kind: AnyBlockKind): PasteSurface | undefined;
+export declare function __resetPasteSurfacesForTests(): void;
+export declare function __removePasteSurfaceForTests(kind: AnyBlockKind): void;

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

@@ -0,0 +1,15 @@
+import { registerOnce } from '../schema/register-once';
+// ── Registry ───────────────────────────────────────────────────────────────
+const surfaces = new Map();
+export function registerPasteSurface(surface) {
+    registerOnce(surfaces.has(surface.kind), () => surfaces.set(surface.kind, surface), `registerPasteSurface: "${surface.kind}" is already registered. Paste surfaces are register-once.`);
+}
+export function getPasteSurface(kind) {
+    return surfaces.get(kind);
+}
+export function __resetPasteSurfacesForTests() {
+    surfaces.clear();
+}
+export function __removePasteSurfaceForTests(kind) {
+    surfaces.delete(kind);
+}

package/dist/tree-operations/path-mutate.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Path-addressed child splices for the range-delete ceremony. Both route through
+ * `spliceChildrenSettled` (`node-ops.ts`): they address containers at arbitrary depth, which is
+ * exactly where a desynced `childIds` or an unsettled separator becomes permanent. `sharing` is
+ * REQUIRED, not optional: the settle writes the surviving neighbours' own bytes, so a door
+ * reached without it writes through a snapshot-shared node (G1.9). Callers unshare the PARENT
+ * spine themselves; `sharing` is what unshares the children the settle touches.
+ */
+import type { CstNode, Document } from '../core/nodes';
+import type { SharingState } from './sharing';
+export declare function deleteAtPath(doc: Document, path: number[], sharing: SharingState): void;
+export declare function replaceAtPath(doc: Document, path: number[], replacement: CstNode[], sharing: SharingState): void;

package/dist/tree-operations/path-mutate.js

@@ -0,0 +1,20 @@
+import { nodeAt, spliceChildrenSettled } from './node-ops';
+export function deleteAtPath(doc, path, sharing) {
+    if (path.length === 0)
+        return;
+    const parent = nodeAt(doc, path.slice(0, -1));
+    if (!parent || !parent.children)
+        return;
+    const idx = path[path.length - 1];
+    if (idx < parent.children.length) {
+        spliceChildrenSettled(parent, idx, 1, [], sharing);
+    }
+}
+export function replaceAtPath(doc, path, replacement, sharing) {
+    if (path.length === 0)
+        return;
+    const parent = nodeAt(doc, path.slice(0, -1));
+    if (!parent || !parent.children)
+        return;
+    spliceChildrenSettled(parent, path[path.length - 1], 1, replacement, sharing);
+}

package/dist/tree-operations/reorder-unit.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Resolve the reorderable unit a path points into: the nearest ancestor slot whose parent
+ * reorders its children among themselves. Membership is the parent's declared
+ * `reorderChildren` capability, never a kind name, so a plugin container opts in as the
+ * built-ins do. An opaque container is a hard boundary — reorder DECLINES there rather
+ * than walking past to the document and teleporting the container to a top-level index.
+ */
+import type { Document } from '../core/nodes';
+export interface ReorderUnit {
+    parentPath: number[];
+    index: number;
+    /** The root reorders structurally; a container reorders through its own commit scope. */
+    scope: 'document' | 'container';
+    /** The parent renumbers position-dependent child markers after the move (ordered list). */
+    renumberMarkers: boolean;
+}
+export declare function resolveReorderUnit(doc: Document, path: number[]): ReorderUnit | null;

package/dist/tree-operations/reorder-unit.js

@@ -0,0 +1,37 @@
+/**
+ * Resolve the reorderable unit a path points into: the nearest ancestor slot whose parent
+ * reorders its children among themselves. Membership is the parent's declared
+ * `reorderChildren` capability, never a kind name, so a plugin container opts in as the
+ * built-ins do. An opaque container is a hard boundary — reorder DECLINES there rather
+ * than walking past to the document and teleporting the container to a top-level index.
+ */
+import { tryGetBlockKindDescriptor } from '../schema/block-kind-descriptor';
+import { nodeAt } from './node-ops';
+export function resolveReorderUnit(doc, path) {
+    for (let depth = path.length; depth >= 1; depth--) {
+        const parentPath = path.slice(0, depth - 1);
+        // The root is identified structurally, never by kind: a plugin may mint 'document'
+        // as a block kind, and such a node is just another container.
+        if (parentPath.length === 0) {
+            return { parentPath, index: path[depth - 1], scope: 'document', renumberMarkers: false };
+        }
+        const parentKind = nodeAt(doc, parentPath)?.kind;
+        // `!== 'document'` narrows out the root's kind at the type level (nodeAt widens to
+        // include it); at runtime the root is already handled above.
+        if (parentKind && parentKind !== 'document') {
+            const descriptor = tryGetBlockKindDescriptor(parentKind);
+            const reorderChildren = descriptor?.reorderChildren;
+            if (reorderChildren) {
+                return {
+                    parentPath,
+                    index: path[depth - 1],
+                    scope: 'container',
+                    renumberMarkers: reorderChildren.renumberMarkers ?? false
+                };
+            }
+            if (descriptor?.containerContract === 'opaque')
+                return null;
+        }
+    }
+    return null;
+}

package/dist/tree-operations/reorder.d.ts

@@ -0,0 +1,13 @@
+import type { CstNode } from '../core/nodes';
+import type { SharingState } from './sharing';
+import { type SettledSplice } from './node-ops';
+import type { StructuralChange } from './structural-change';
+export declare function reorderChildren(children: CstNode[], from: number, to: number): StructuralChange;
+/**
+ * Reorder children while keeping block separators positional. A separator is stored as the next
+ * child's `leadingTrivia` but read per slot, so it belongs to the position, not the node. Writing
+ * it is a byte write, so spanned children are unshared first (`unshare.ts`) and `children` must
+ * already be an owned array. The landing rides the result: a fold settling a seam the move
+ * invalidated can sit above the moved block.
+ */
+export declare function reorderChildrenWithTrivia(children: CstNode[], from: number, to: number, sharing: SharingState): SettledSplice;