@voithos-labs/aragonite 0.10.1

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

@@ -0,0 +1,138 @@
+/**
+ * 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 { parse } from '../../core/parser';
+import { cutRangeFromDisplay, isBlockNode, nodeAt } from '../node-ops';
+import { trailingLineEnding, trimTrailingLineEnding } from '../../core/lines';
+import { getPasteSurface } from '../paste-surfaces';
+import { isReservedChromeChild } from '../../schema/reserved-chrome';
+import { applyInlineResult, applyStructuralResult } from './apply';
+import { normalizeClipboardForBody } from './body-write';
+import { applyContainerMatchingPaste, findContainerMatchingUnwrap } from './container-match';
+import { defaultInlineHook, defaultStructuralHook } from './hooks';
+import { devWarn } from '../../dev-warn';
+import { applyListAbsorb, findListAbsorb } from './list-absorb';
+import { applyListBreakOut, findListBreakOut } from './list-break-out';
+import { applyPasteTransforms } from './paste-transforms';
+import { contentBlocks, pickPasteStrategy } from './strategy';
+/** Execute a paste at the specified target position. */
+export async function pasteDispatch(input, ctx) {
+    if (!input.pastedText)
+        return {};
+    // Once, before any branch below reads the text; a transform that empties it is an
+    // empty paste.
+    const transformed = applyPasteTransforms(input.pastedText, ctx.activePlugins);
+    if (!transformed)
+        return {};
+    // Ahead of the fragment parse, so the strategy pick and every landed kind follow the
+    // bytes a bodyWrite-declaring ancestor will actually accept.
+    const pastedText = normalizeClipboardForBody(ctx.doc, input.targetPath, transformed);
+    const parsed = parse(pastedText, { grammar: ctx.grammar, scope: 'fragment' });
+    if (parsed.children.length === 0)
+        return {};
+    const targetNode = nodeAt(ctx.doc, input.targetPath);
+    if (!targetNode)
+        return {};
+    // A reserved-chrome leaf is single-line by serialization, so paste there is forced inline
+    // ahead of the container-paste family: a multi-block clipboard must never split it. The trim
+    // drops the edge spaces the newline flattening minted, not bytes anyone copied.
+    const chromeParent = nodeAt(ctx.doc, input.targetPath.slice(0, -1));
+    if (chromeParent &&
+        isBlockNode(chromeParent) &&
+        isReservedChromeChild(chromeParent, input.targetPath[input.targetPath.length - 1])) {
+        const flattened = pastedText.replace(/(\r?\n)+/g, ' ').trim();
+        const hook = getPasteSurface(targetNode.kind)?.onInlinePaste ?? defaultInlineHook;
+        const result = hook(targetNode, input.offset, flattened, input.preDelete, ctx.seam);
+        const landing = await applyInlineResult(input.targetPath, result, ctx);
+        return inlineCaretResult(result.caretOffset, landing);
+    }
+    // The delete half the container routes never ran, spent ONCE and ahead of the strategy pick:
+    // each finder decides on the TARGET's bytes, and a range still standing there answers about
+    // bytes the paste is removing. The hook routes cut their own, kind rules included.
+    const target = targetAfterPreDelete(targetNode, input, ctx.seam);
+    const unwrap = findContainerMatchingUnwrap(ctx.doc, input.targetPath, target.offset, parsed, ctx.undoEntry === 'join', target.raw);
+    if (unwrap) {
+        await applyContainerMatchingPaste(unwrap, ctx);
+        return {};
+    }
+    // The rest of the container paste-merge family, for single-block non-empty targets:
+    // absorb when `matchesAncestor` accepts the enclosing container, break-out when it
+    // does not.
+    const absorb = findListAbsorb(ctx.doc, input.targetPath, parsed, target.offset, target.raw);
+    if (absorb) {
+        await applyListAbsorb(absorb, parsed.children[0], ctx);
+        return {};
+    }
+    const breakOut = findListBreakOut(ctx.doc, input.targetPath, parsed, target.offset, target.raw);
+    if (breakOut) {
+        await applyListBreakOut(breakOut, parsed.children, ctx);
+        return {};
+    }
+    const surface = getPasteSurface(targetNode.kind);
+    if (surface === undefined) {
+        devWarn('paste-dispatch', 'no paste surface registered for this kind; falling through to default hooks. Register ' +
+            'via registerPasteSurface() if the kind has its own paste semantics', targetNode.kind);
+    }
+    const blocks = surface?.blankEdgesArePackaging ? contentBlocks(parsed.children) : parsed.children;
+    const clipboardStrategy = pickPasteStrategy(blocks);
+    // A surface omitting both structural hooks (code blocks) forces paste inline, so its
+    // markdown stays verbatim.
+    const surfaceForcesInline = surface !== undefined &&
+        surface.onStructuralPaste === undefined &&
+        surface.onScopedStructuralPaste === undefined;
+    const strategy = surfaceForcesInline ? 'inline' : clipboardStrategy;
+    if (strategy === 'structural' && surface?.onScopedStructuralPaste) {
+        await surface.onScopedStructuralPaste({
+            doc: ctx.doc,
+            targetPath: input.targetPath,
+            blocks: blocks.slice(),
+            controller: ctx.controller,
+            undoEntry: ctx.undoEntry ?? 'own',
+            grammar: ctx.grammar
+        });
+        return {};
+    }
+    if (strategy === 'inline') {
+        const hook = surface?.onInlinePaste ?? defaultInlineHook;
+        const result = hook(targetNode, input.offset, pastedText, input.preDelete, ctx.seam);
+        const landing = await applyInlineResult(input.targetPath, result, ctx);
+        return inlineCaretResult(result.caretOffset, landing);
+    }
+    const hook = surface?.onStructuralPaste ?? defaultStructuralHook;
+    const result = hook(targetNode, input.offset, blocks.slice(), input.preDelete, ctx.seam);
+    await applyStructuralResult(input.targetPath, result, ctx, trailingSeparatorOf(parsed, result, surface));
+    return {};
+}
+/** The target's bytes and caret as the paste's delete half leaves them. */
+function targetAfterPreDelete(node, input, seam) {
+    if (!input.preDelete)
+        return { raw: node.raw, offset: input.offset };
+    const cut = cutRangeFromDisplay(node, trimTrailingLineEnding(node.raw), input.preDelete, seam?.presentationMode, seam?.linkRef);
+    return { raw: cut.display + trailingLineEnding(node.raw), offset: cut.offset };
+}
+/**
+ * A clipboard's trailing blank line is CONTENT: a parse folds exactly one into `suffix`
+ * while a second already materializes as a block, and the inline route splices the bytes verbatim
+ * — so consuming children alone made one route keep the copied separation and its twin lose it.
+ * Spent only where the splice leaves nothing behind the pasted blocks; a residue or a follower
+ * already carries a separator of its own, and a packaging surface declines the whole question.
+ */
+function trailingSeparatorOf(parsed, result, surface) {
+    if (surface?.blankEdgesArePackaging)
+        return '';
+    // `focusReplacementIndex` IS the last pasted node (`paste/focus-target.ts`), so anything past
+    // it is reattached residue.
+    return result.focusReplacementIndex === result.replacement.length - 1 ? parsed.suffix : '';
+}
+/** The hook's own caret offset, overridden by the settled landing where a fold moved it. */
+function inlineCaretResult(caretOffset, landing) {
+    if (!landing)
+        return { inlineCaretOffset: caretOffset };
+    return { inlineCaretOffset: landing.offset, inlineCaretPath: landing.path };
+}
+export { pickPasteStrategy } from './strategy';
+export { defaultInlineHook, defaultStructuralHook, __getDefaultTextSurface } from './hooks';

package/dist/tree-operations/paste/find-enclosing-list.d.ts

@@ -0,0 +1,8 @@
+import type { CstNode, Document } from '../../core/nodes';
+/** Returns null when no list ancestor exists or the target isn't a direct leaf of a listItem. */
+export declare function findEnclosingListForPaste(doc: Document, targetPath: number[]): {
+    list: CstNode;
+    listPath: number[];
+    itemIndex: number;
+    innerIndex: number;
+} | null;

package/dist/tree-operations/paste/find-enclosing-list.js

@@ -0,0 +1,30 @@
+import { nodeAt } from '../node-ops';
+/** Returns null when no list ancestor exists or the target isn't a direct leaf of a listItem. */
+export function findEnclosingListForPaste(doc, targetPath) {
+    if (targetPath.length < 3)
+        return null;
+    let listDepth = -1;
+    let list = null;
+    for (let depth = targetPath.length - 1; depth >= 1; depth--) {
+        const ancestor = nodeAt(doc, targetPath.slice(0, depth));
+        if (!ancestor)
+            return null;
+        if (ancestor.kind === 'list') {
+            listDepth = depth;
+            list = ancestor;
+            break;
+        }
+    }
+    if (listDepth === -1 || !list)
+        return null;
+    // Merge semantics are undefined for a target nested in a deeper container, so only
+    // direct leaves of a listItem qualify; the rest fall through to structural paste.
+    if (targetPath.length !== listDepth + 2)
+        return null;
+    return {
+        list,
+        listPath: targetPath.slice(0, listDepth),
+        itemIndex: targetPath[listDepth],
+        innerIndex: targetPath[listDepth + 1]
+    };
+}

package/dist/tree-operations/paste/focus-target.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The caret a `[prefix?, ...pasted, residue?]` replacement lands, on both sides of the splice
+ * settle: which node the door aims at, the position the settle's folds carry for it, and the
+ * offset that position is landable at.
+ */
+import type { CstNode } from '../../core/nodes';
+import type { NodeView } from '../../core/node-views';
+import type { TrackedPosition } from '../node-ops';
+/**
+ * Focus index for the replacement: the last PASTED node. Single-sourced so every structural
+ * route skips the reattached residue identically. Applies only where the residue is a SEPARATE
+ * node; a route that reattaches it inside the last pasted leaf lands at a char offset in a
+ * different coordinate space.
+ */
+export declare function focusIndexBeforeResidue(replacementLength: number, hasResidue: boolean): number;
+/**
+ * The position the splice settle must carry: the end of the pasted bytes, in the scope's slots.
+ * `CURSOR_END` resolves to the node's own display end here — a sentinel handed to the tracker
+ * would clamp to whatever the fold reattached behind it, which is the bug it exists to prevent.
+ */
+export declare function trackedPasteCaret(replacement: readonly CstNode[], at: number, focusIndex: number, focusOffset: number): TrackedPosition;
+/**
+ * The offset {@link trackedPasteCaret}'s settled position is landable at. Only a known leaf spends
+ * the tracked byte: a container walks any numeric offset to its last child, so its raw offsets
+ * address no caret seat. Anything the caller named itself stands as given.
+ */
+export declare function landedPasteOffset(landed: NodeView | undefined, tracked: TrackedPosition, focusOffset: number): number;

package/dist/tree-operations/paste/focus-target.js

@@ -0,0 +1,40 @@
+/**
+ * The caret a `[prefix?, ...pasted, residue?]` replacement lands, on both sides of the splice
+ * settle: which node the door aims at, the position the settle's folds carry for it, and the
+ * offset that position is landable at.
+ */
+import { CURSOR_END } from '../../block-component';
+import { trimTrailingLineEnding } from '../../core/lines';
+import { tryGetBlockKindDescriptor } from '../../schema/block-kind-descriptor';
+/**
+ * Focus index for the replacement: the last PASTED node. Single-sourced so every structural
+ * route skips the reattached residue identically. Applies only where the residue is a SEPARATE
+ * node; a route that reattaches it inside the last pasted leaf lands at a char offset in a
+ * different coordinate space.
+ */
+export function focusIndexBeforeResidue(replacementLength, hasResidue) {
+    return hasResidue && replacementLength >= 2 ? replacementLength - 2 : replacementLength - 1;
+}
+/**
+ * The position the splice settle must carry: the end of the pasted bytes, in the scope's slots.
+ * `CURSOR_END` resolves to the node's own display end here — a sentinel handed to the tracker
+ * would clamp to whatever the fold reattached behind it, which is the bug it exists to prevent.
+ */
+export function trackedPasteCaret(replacement, at, focusIndex, focusOffset) {
+    const displayEnd = trimTrailingLineEnding(replacement[focusIndex]?.raw ?? '').length;
+    return {
+        index: at + focusIndex,
+        offset: focusOffset === CURSOR_END ? displayEnd : Math.max(focusOffset, 0)
+    };
+}
+/**
+ * The offset {@link trackedPasteCaret}'s settled position is landable at. Only a known leaf spends
+ * the tracked byte: a container walks any numeric offset to its last child, so its raw offsets
+ * address no caret seat. Anything the caller named itself stands as given.
+ */
+export function landedPasteOffset(landed, tracked, focusOffset) {
+    if (focusOffset !== CURSOR_END)
+        return focusOffset;
+    const leaf = landed && tryGetBlockKindDescriptor(landed.kind)?.isContainer === false;
+    return leaf ? tracked.offset : CURSOR_END;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Default paste hooks for kinds with no bespoke PasteSurface, registered at module load
+ * for every built-in kind whose descriptor advertises `supportsInline`.
+ */
+import { type CstNode } from '../../core/nodes';
+import { type PasteSurface, type PasteRange, type PasteSeam, type InlinePasteResult, type StructuralPasteResult } from '../paste-surfaces';
+export declare function defaultInlineHook(node: CstNode, offset: number, text: string, preDelete?: PasteRange, seam?: PasteSeam): InlinePasteResult;
+export declare function defaultStructuralHook(node: CstNode, offset: number, blocks: CstNode[], preDelete?: PasteRange, seam?: PasteSeam): StructuralPasteResult;
+/**
+ * Caret target for a structural paste: the end of the PASTED content, not the trailing
+ * residue. A mid-block caret leaves the post-caret slice as the replacement's last node,
+ * so the pasted content ends one node earlier. Takes the display and offset the delete half
+ * already resolved — a seam cleanup moves both, and re-deriving them here would disagree.
+ */
+export declare function pastedContentFocusIndex(display: string, offset: number, replacementLength: number): number;
+/** Test-only: produce a default text surface descriptor. */
+export declare function __getDefaultTextSurface(kind: PasteSurface['kind']): PasteSurface;

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

@@ -0,0 +1,80 @@
+/**
+ * Default paste hooks for kinds with no bespoke PasteSurface, registered at module load
+ * for every built-in kind whose descriptor advertises `supportsInline`.
+ */
+import { CURSOR_END } from '../../block-component';
+import { isBuiltinBlockKind } from '../../core/nodes';
+import { trailingLineEnding, trimTrailingLineEnding } from '../../core/lines';
+import { buildPastedReplacement } from './paste-replacement';
+import { cutRangeFromDisplay } from '../node-ops';
+import { focusIndexBeforeResidue } from './focus-target';
+import { getAllRegisteredKinds, tryGetBlockKindDescriptor } from '../../schema/block-kind-descriptor';
+import { registerPasteSurface } from '../paste-surfaces';
+// Registered by their own component instead of the loop below. One registrar per kind, so
+// correctness doesn't hinge on module load order.
+const BESPOKE_SURFACE_KINDS = new Set(['tableCell']);
+/**
+ * The leaf's bytes and caret after the paste's DELETE half — through the one join seam, so a cut
+ * that stranded a delimiter run the reader never saw drops it here rather than pasting it into
+ * view (live-mode.md § 4.5). The range is forwarded whole: the endpoints are the seam's to read.
+ */
+function applyPreDelete(node, display, preDelete, offset, seam) {
+    if (!preDelete)
+        return { display, offset };
+    return cutRangeFromDisplay(node, display, preDelete, seam?.presentationMode, seam?.linkRef);
+}
+export function defaultInlineHook(node, offset, text, preDelete, seam) {
+    const display = trimTrailingLineEnding(node.raw);
+    const lineEnding = trailingLineEnding(node.raw);
+    const { display: effectiveDisplay, offset: effectiveOffset } = applyPreDelete(node, display, preDelete, offset, seam);
+    const newDisplay = effectiveDisplay.slice(0, effectiveOffset) + text + effectiveDisplay.slice(effectiveOffset);
+    return {
+        newRaw: newDisplay + lineEnding,
+        caretOffset: effectiveOffset + text.length
+    };
+}
+export function defaultStructuralHook(node, offset, blocks, preDelete, seam) {
+    const display = trimTrailingLineEnding(node.raw);
+    const cut = applyPreDelete(node, display, preDelete, offset, seam);
+    // Compare the BYTES rather than the range: a cleanup can drop more than the selection did,
+    // and an empty range leaves them equal, which is exactly when the original node stands.
+    const synthLeaf = cut.display === display ? node : { ...node, raw: cut.display + trailingLineEnding(node.raw) };
+    const replacement = buildPastedReplacement(synthLeaf, cut.offset, blocks);
+    return {
+        replacement,
+        focusReplacementIndex: pastedContentFocusIndex(cut.display, cut.offset, replacement.length),
+        focusOffset: CURSOR_END
+    };
+}
+/**
+ * Caret target for a structural paste: the end of the PASTED content, not the trailing
+ * residue. A mid-block caret leaves the post-caret slice as the replacement's last node,
+ * so the pasted content ends one node earlier. Takes the display and offset the delete half
+ * already resolved — a seam cleanup moves both, and re-deriving them here would disagree.
+ */
+export function pastedContentFocusIndex(display, offset, replacementLength) {
+    return focusIndexBeforeResidue(replacementLength, offset < display.length);
+}
+// Built-in kinds are all registered by the time this top level runs; a plugin kind
+// registering later must register its own paste surface.
+for (const kind of getAllRegisteredKinds()) {
+    if (!isBuiltinBlockKind(kind))
+        continue;
+    if (BESPOKE_SURFACE_KINDS.has(kind))
+        continue;
+    if (tryGetBlockKindDescriptor(kind)?.supportsInline) {
+        registerPasteSurface({
+            kind,
+            onInlinePaste: defaultInlineHook,
+            onStructuralPaste: defaultStructuralHook
+        });
+    }
+}
+/** Test-only: produce a default text surface descriptor. */
+export function __getDefaultTextSurface(kind) {
+    return {
+        kind,
+        onInlinePaste: defaultInlineHook,
+        onStructuralPaste: defaultStructuralHook
+    };
+}

package/dist/tree-operations/paste/list-absorb.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Paste absorb: a same-type list pasted into a non-empty list item flattens as siblings of
+ * the target, with markers normalized to the enclosing list's style — the flat result most
+ * markdown editors produce. Covers the single-block non-empty same-type case that runs
+ * after `findContainerMatchingUnwrap` and would otherwise fall through to the default
+ * structural paste; mismatched types go to `list-break-out` instead.
+ */
+import type { CstNode, Document } from '../../core/nodes';
+import type { PasteDispatchContext } from './dispatch';
+export interface ListAbsorb {
+    listPath: number[];
+    itemIndex: number;
+    innerIndex: number;
+    offset: number;
+    /** The target leaf's bytes AFTER the paste's delete half. */
+    targetRaw?: string;
+}
+/**
+ * The absorb plan, or null when any precondition fails: a single top block declaring
+ * `containerPaste.siblingAbsorb`, whose `matchesAncestor` accepts the nearest list
+ * ancestor, targeting a direct leaf of the listItem. Mismatched types fall through to
+ * `findListBreakOut`.
+ */
+export declare function findListAbsorb(doc: Document, targetPath: number[], parsed: Document, offset: number, targetRaw?: string): ListAbsorb | null;
+/**
+ * Split the target item at the caret, splice the pasted items between the halves,
+ * normalize markers, renumber. One undo entry on the list's scope.
+ */
+export declare function applyListAbsorb(plan: ListAbsorb, pastedList: CstNode, ctx: PasteDispatchContext): Promise<void>;

package/dist/tree-operations/paste/list-absorb.js

@@ -0,0 +1,106 @@
+/**
+ * Paste absorb: a same-type list pasted into a non-empty list item flattens as siblings of
+ * the target, with markers normalized to the enclosing list's style — the flat result most
+ * markdown editors produce. Covers the single-block non-empty same-type case that runs
+ * after `findContainerMatchingUnwrap` and would otherwise fall through to the default
+ * structural paste; mismatched types go to `list-break-out` instead.
+ */
+import { CURSOR_END } from '../../block-component';
+import { metadataOf } from '../../core/nodes';
+import { nodeAt, ensureEditableContainers } from '../node-ops';
+import { cloneNode } from '../clone';
+import { containerPasteFor } from './container-paste';
+import { stampStructuralChange } from '../structural-change';
+import { renumberOrderedList, templatePastedItemMarkers } from '../list/ordered-markers';
+import { spliceTerminatedItems } from '../list/terminator';
+import { containerScopeState } from './parent-scope';
+import { buildSplitItems } from '../list/list-builders';
+import { findEnclosingListForPaste } from './find-enclosing-list';
+import { focusIndexBeforeResidue } from './focus-target';
+import { docPathFrom } from '../../cursor/coordinate-spaces';
+/**
+ * The absorb plan, or null when any precondition fails: a single top block declaring
+ * `containerPaste.siblingAbsorb`, whose `matchesAncestor` accepts the nearest list
+ * ancestor, targeting a direct leaf of the listItem. Mismatched types fall through to
+ * `findListBreakOut`.
+ */
+export function findListAbsorb(doc, targetPath, parsed, offset, targetRaw) {
+    if (parsed.children.length !== 1)
+        return null;
+    const topBlock = parsed.children[0];
+    const containerPaste = containerPasteFor(topBlock.kind);
+    if (!containerPaste?.siblingAbsorb)
+        return null;
+    const enclosing = findEnclosingListForPaste(doc, targetPath);
+    if (!enclosing)
+        return null;
+    if (!containerPaste.matchesAncestor(topBlock, enclosing.list))
+        return null;
+    return {
+        listPath: enclosing.listPath,
+        itemIndex: enclosing.itemIndex,
+        innerIndex: enclosing.innerIndex,
+        offset,
+        targetRaw
+    };
+}
+/**
+ * Split the target item at the caret, splice the pasted items between the halves,
+ * normalize markers, renumber. One undo entry on the list's scope.
+ */
+export async function applyListAbsorb(plan, pastedList, ctx) {
+    const outer = nodeAt(ctx.doc, plan.listPath);
+    if (!outer?.children)
+        return;
+    const outerState = containerScopeState(ctx.controller, outer);
+    const item = outer.children[plan.itemIndex];
+    if (!item?.children)
+        return;
+    if (!item.children[plan.innerIndex])
+        return;
+    const { leadingItem, trailingItem } = buildSplitItems(item, plan.innerIndex, plan.offset, plan.targetRaw);
+    const pastedItems = (pastedList.children ?? []).map((c) => cloneNode(c));
+    const replacement = [];
+    if (leadingItem)
+        replacement.push(leadingItem);
+    for (const p of pastedItems)
+        replacement.push(p);
+    if (trailingItem)
+        replacement.push(trailingItem);
+    for (const node of replacement)
+        ensureEditableContainers(node);
+    const outerOrdered = metadataOf(outer, 'list')?.ordered ?? false;
+    templatePastedItemMarkers(replacement, outer, plan.itemIndex);
+    await ctx.controller.commitMultiScope({
+        scopes: [{ node: outer, state: outerState, path: plan.listPath }],
+        snapshot: ctx.undoEntry === 'join' ? 'skip' : { path: docPathFrom(plan.listPath), offset: 0 },
+        mutate: ([scopeView]) => {
+            const sharing = scopeView.sharing;
+            spliceTerminatedItems(scopeView.children, plan.itemIndex, 1, replacement);
+            // Only items AFTER the replacement region: their proxies already exist, so marker
+            // mutations propagate to the DOM.
+            const afterReplacementIdx = plan.itemIndex + replacement.length;
+            if (outerOrdered && afterReplacementIdx < scopeView.children.length) {
+                renumberOrderedList(scopeView.node, afterReplacementIdx, sharing);
+            }
+            const change = {
+                op: 'replace',
+                at: plan.itemIndex,
+                count: 1,
+                newCount: replacement.length
+            };
+            stampStructuralChange(scopeView.children, change, sharing);
+            return [change];
+        },
+        op: {
+            kind: 'paste',
+            detail: { source: 'list-absorb', listPath: plan.listPath },
+            eventPath: docPathFrom(plan.listPath)
+        },
+        afterTick: () => {
+            // The shared structural-paste landing rule: last pasted item, before the residue.
+            const lastPastedIdx = plan.itemIndex + focusIndexBeforeResidue(replacement.length, trailingItem !== null);
+            return ctx.controller.landCaret([...plan.listPath, lastPastedIdx], CURSOR_END);
+        }
+    });
+}

package/dist/tree-operations/paste/list-break-out.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Paste break-out: lift a pasted list out of an enclosing list rather than nesting it,
+ * whenever the two ordered flags disagree — keeping the pasted list separate preserves its
+ * semantic type. Same-type pastes go through `list-absorb`.
+ */
+import type { CstNode, Document } from '../../core/nodes';
+import type { PasteDispatchContext } from './dispatch';
+export interface ListBreakOut {
+    /** Path to the nearest enclosing list ancestor. */
+    listPath: number[];
+    /** Index of the enclosing listItem within the list. */
+    itemIndex: number;
+    /** Index of the target leaf within the enclosing listItem's children. */
+    innerIndex: number;
+    /** Caret offset within the target leaf's raw. */
+    offset: number;
+    /** The target leaf's bytes AFTER the paste's delete half. */
+    targetRaw?: string;
+}
+/**
+ * The break-out plan, or null: requires a top block declaring `containerPaste.siblingAbsorb`
+ * whose `matchesAncestor` REJECTS the nearest list ancestor (matching pastes belong to
+ * `list-absorb` and must not also trigger here), targeting a direct leaf of the listItem.
+ */
+export declare function findListBreakOut(doc: Document, targetPath: number[], parsed: Document, offset: number, targetRaw?: string): ListBreakOut | null;
+/**
+ * Split the enclosing list at the target item and splice the pasted blocks between the
+ * halves at the list's parent level, in one multi-scope entry.
+ */
+export declare function applyListBreakOut(plan: ListBreakOut, pastedBlocks: CstNode[], ctx: PasteDispatchContext): Promise<void>;
+export interface ListBreakOutReplacement {
+    /** `[firstHalfList?, ...pastedBlocks, secondHalfList?]` — halves omitted when empty. */
+    replacement: CstNode[];
+    /** The second-half list (post-caret residue) is present as the last node. */
+    hasTrailingResidue: boolean;
+}
+/**
+ * Split `list` at `(itemIndex, innerIndex, offset)` and splice `pastedBlocks` between the
+ * halves. `hasTrailingResidue` lets the caller land the caret on the last pasted block
+ * rather than the residue. Input nodes are cloned, not mutated.
+ */
+export declare function buildListBreakOutReplacement(list: CstNode, itemIndex: number, innerIndex: number, offset: number, pastedBlocks: CstNode[], targetRaw?: string): ListBreakOutReplacement;

package/dist/tree-operations/paste/list-break-out.js

@@ -0,0 +1,136 @@
+/**
+ * Paste break-out: lift a pasted list out of an enclosing list rather than nesting it,
+ * whenever the two ordered flags disagree — keeping the pasted list separate preserves its
+ * semantic type. Same-type pastes go through `list-absorb`.
+ */
+import { CURSOR_END } from '../../block-component';
+import { nodeAt, ensureEditableContainers } from '../node-ops';
+import { cloneNode } from '../clone';
+import { spliceMany } from '../splice-many';
+import { stampStructuralChange } from '../structural-change';
+import { containerPasteFor } from './container-paste';
+import { rebuildListRaw } from '../../schema/container-rebuilders';
+import { newlineTerminateListItems } from '../list/terminator';
+import { trailingLineEnding } from '../../core/lines';
+import { assembleListHalf, buildSplitItems } from '../list/list-builders';
+import { orderedBaseOf } from '../list/ordered-markers';
+import { findEnclosingListForPaste } from './find-enclosing-list';
+import { focusIndexBeforeResidue, landedPasteOffset, trackedPasteCaret } from './focus-target';
+import { docPathFrom } from '../../cursor/coordinate-spaces';
+import { resolveParentScope } from './parent-scope';
+/**
+ * The break-out plan, or null: requires a top block declaring `containerPaste.siblingAbsorb`
+ * whose `matchesAncestor` REJECTS the nearest list ancestor (matching pastes belong to
+ * `list-absorb` and must not also trigger here), targeting a direct leaf of the listItem.
+ */
+export function findListBreakOut(doc, targetPath, parsed, offset, targetRaw) {
+    if (parsed.children.length === 0)
+        return null;
+    const topBlock = parsed.children[0];
+    const containerPaste = containerPasteFor(topBlock.kind);
+    if (!containerPaste?.siblingAbsorb)
+        return null;
+    const enclosing = findEnclosingListForPaste(doc, targetPath);
+    if (!enclosing)
+        return null;
+    if (containerPaste.matchesAncestor(topBlock, enclosing.list))
+        return null;
+    return {
+        listPath: enclosing.listPath,
+        itemIndex: enclosing.itemIndex,
+        innerIndex: enclosing.innerIndex,
+        offset,
+        targetRaw
+    };
+}
+/**
+ * Split the enclosing list at the target item and splice the pasted blocks between the
+ * halves at the list's parent level, in one multi-scope entry.
+ */
+export async function applyListBreakOut(plan, pastedBlocks, ctx) {
+    const list = nodeAt(ctx.doc, plan.listPath);
+    if (!list?.children)
+        return;
+    const { replacement, hasTrailingResidue } = buildListBreakOutReplacement(list, plan.itemIndex, plan.innerIndex, plan.offset, pastedBlocks, plan.targetRaw);
+    if (replacement.length === 0)
+        return;
+    for (const node of replacement)
+        ensureEditableContainers(node);
+    const parentScope = resolveParentScope(ctx.doc, plan.listPath, ctx.controller);
+    if (!parentScope)
+        return;
+    const spliceIndex = plan.listPath[plan.listPath.length - 1];
+    // The last pasted block, never the second-half residue list — and carried through the settle,
+    // whose folds can move the slot out from under a landing chosen here.
+    const caret = trackedPasteCaret(replacement, spliceIndex, focusIndexBeforeResidue(replacement.length, hasTrailingResidue), CURSOR_END);
+    await ctx.controller.commitMultiScope({
+        scopes: [parentScope],
+        snapshot: ctx.undoEntry === 'join' ? 'skip' : { path: docPathFrom(plan.listPath), offset: 0 },
+        mutate: ([scopeView]) => {
+            spliceMany(scopeView.children, spliceIndex, 1, replacement);
+            const change = {
+                op: 'replace',
+                at: spliceIndex,
+                count: 1,
+                newCount: replacement.length
+            };
+            stampStructuralChange(scopeView.children, change, scopeView.sharing);
+            return [change];
+        },
+        op: {
+            kind: 'paste',
+            detail: { source: 'list-break-out', listPath: plan.listPath },
+            eventPath: docPathFrom(plan.listPath)
+        },
+        trackCaret: [caret],
+        afterTick: () => {
+            const landed = nodeAt(ctx.doc, parentScope.path)?.children?.[caret.index];
+            return ctx.controller.landCaret([...parentScope.path, caret.index], landedPasteOffset(landed, caret, CURSOR_END));
+        }
+    });
+}
+/**
+ * Split `list` at `(itemIndex, innerIndex, offset)` and splice `pastedBlocks` between the
+ * halves. `hasTrailingResidue` lets the caller land the caret on the last pasted block
+ * rather than the residue. Input nodes are cloned, not mutated.
+ */
+export function buildListBreakOutReplacement(list, itemIndex, innerIndex, offset, pastedBlocks, targetRaw) {
+    const items = list.children ?? [];
+    const item = items[itemIndex];
+    if (!item?.children)
+        return { replacement: [], hasTrailingResidue: false };
+    if (!item.children[innerIndex])
+        return { replacement: [], hasTrailingResidue: false };
+    const { leadingItem, trailingItem } = buildSplitItems(item, innerIndex, offset, targetRaw);
+    const itemsBefore = items.slice(0, itemIndex).map(cloneNode);
+    const itemsAfter = items.slice(itemIndex + 1).map(cloneNode);
+    if (itemsAfter[0])
+        itemsAfter[0].leadingTrivia = '';
+    const firstHalfItems = [...itemsBefore];
+    if (leadingItem)
+        firstHalfItems.push(leadingItem);
+    const secondHalfItems = trailingItem ? [trailingItem, ...itemsAfter] : [...itemsAfter];
+    const base = orderedBaseOf(items[0]);
+    const replacement = [];
+    if (firstHalfItems.length > 0) {
+        replacement.push(assembleListHalf(list, firstHalfItems, base));
+    }
+    for (const block of pastedBlocks) {
+        const cloned = cloneNode(block);
+        // Normalize the clone's items so its rebuilt raw can't mash into the next block.
+        // The ending comes from the list being broken out of — the pasted block lands
+        // among its lines.
+        if (cloned.kind === 'list' && cloned.children) {
+            newlineTerminateListItems(cloned.children, trailingLineEnding(list.raw));
+            rebuildListRaw(cloned);
+        }
+        replacement.push(cloned);
+    }
+    const hasTrailingResidue = secondHalfItems.length > 0;
+    if (hasTrailingResidue) {
+        // Continue numbering across the paste gap: the split item consumes one slot in each
+        // half, so the second half starts past the first half's count.
+        replacement.push(assembleListHalf(list, secondHalfItems, base + firstHalfItems.length));
+    }
+    return { replacement, hasTrailingResidue };
+}