@voithos-labs/aragonite 0.10.1

package/dist/tree-operations/list/ordered-markers.js

@@ -0,0 +1,114 @@
+/** Ordered-list marker bookkeeping: reads, renumbering, and matching item style to a list. */
+import { metadataOf } from '../../core/nodes';
+import { rebuildListItemRaw } from '../../schema/container-rebuilders';
+import { ensureUnsharedChild } from '../unshare';
+// ── Marker reads ─────────────────────────────────────────────────────────────
+/** Read an item's marker as an integer base, defaulting to 1 for non-numeric markers. */
+export function orderedBaseOf(item) {
+    if (!item)
+        return 1;
+    const marker = metadataOf(item, 'listItem')?.marker ?? '';
+    const n = parseInt(marker, 10);
+    return Number.isFinite(n) && n > 0 ? n : 1;
+}
+/** The punctuation suffix (`. ` or `) `) from a list's first item; defaults to `. `. */
+export function readOrderedSuffix(list) {
+    const first = list.children?.[0];
+    if (!first)
+        return '. ';
+    const marker = metadataOf(first, 'listItem')?.marker ?? '1. ';
+    return marker.replace(/^\d+/, '') || '. ';
+}
+// ── Renumbering ──────────────────────────────────────────────────────────────
+/** Increment an ordered marker's numeric prefix, preserving its suffix. */
+export function bumpOrderedMarker(marker) {
+    return marker.replace(/^(\d+)/, (_, n) => String(Number(n) + 1));
+}
+/**
+ * Renumber an ordered list's items in place from `fromIndex`, preserving marker suffixes.
+ * `fromIndex = 0` resets the sequence to 1; `renumberOrderedListFrom` owns non-1 bases.
+ * Every renumbered item's metadata and raw is WRITTEN, so a live-tree caller must pass
+ * `sharing`; construction-time callers on fresh nodes may omit it.
+ */
+export function renumberOrderedList(list, fromIndex = 0, sharing) {
+    if (!list.children)
+        return;
+    if (!metadataOf(list, 'list')?.ordered)
+        return;
+    for (let j = fromIndex; j < list.children.length; j++) {
+        const item = sharing ? ensureUnsharedChild(list, j, sharing) : list.children[j];
+        const prevNum = j > 0 ? parseInt(metadataOf(list.children[j - 1], 'listItem').marker, 10) || 0 : 0;
+        const meta = metadataOf(item, 'listItem');
+        const suffix = meta.marker.replace(/^\d+/, '');
+        meta.marker = String(prevNum + 1) + suffix;
+        rebuildListItemRaw(item);
+    }
+}
+/**
+ * Renumber an ordered list from an arbitrary `base`: seed item 0's marker with `base`
+ * (suffix-preserving), then continue the sequence from item 1. No-op on unordered or
+ * childless lists.
+ */
+export function renumberOrderedListFrom(list, base, sharing) {
+    if (!metadataOf(list, 'list')?.ordered)
+        return;
+    if (!list.children || list.children.length === 0)
+        return;
+    const first = sharing ? ensureUnsharedChild(list, 0, sharing) : list.children[0];
+    const meta = metadataOf(first, 'listItem');
+    meta.marker = String(base) + (meta.marker.replace(/^\d+/, '') || '. ');
+    rebuildListItemRaw(first);
+    renumberOrderedList(list, 1, sharing);
+}
+// ── Style templating ─────────────────────────────────────────────────────────
+/**
+ * Rewrite `item`'s marker style to match `parentList`, templating the suffix from a
+ * sibling so the destination list's choices are preserved. Numbers stay the caller's
+ * renumber pass's job: only the glyph and punctuation suffix reconcile here.
+ */
+export function normalizeItemMarkerToList(item, parentList) {
+    const parentOrdered = metadataOf(parentList, 'list')?.ordered ?? false;
+    const meta = metadataOf(item, 'listItem');
+    const itemOrdered = /^\d/.test(meta.marker);
+    const siblings = parentList.children ?? [];
+    const templateMarker = siblings.length > 0 ? metadataOf(siblings[0], 'listItem').marker : undefined;
+    let target;
+    if (parentOrdered) {
+        const suffix = templateMarker?.replace(/^\d+/, '');
+        target = itemOrdered
+            ? meta.marker.replace(/\D.*$/, '') + (suffix || '. ')
+            : '1' + (suffix ?? '. ');
+    }
+    else {
+        target = templateMarker ?? '- ';
+    }
+    if (meta.marker === target)
+        return;
+    meta.marker = target;
+    rebuildListItemRaw(item);
+}
+/**
+ * Rewrite pasted items' markers to the enclosing list's style: an unordered list templates
+ * the bullet glyph, an ordered list continues the sequence from `firstIndex`. Runs BEFORE
+ * any splice: `$state` wraps entries lazily, so a marker written to a newly-spliced item
+ * bypasses reactivity.
+ */
+export function templatePastedItemMarkers(items, outer, firstIndex) {
+    if (outer.kind !== 'list')
+        return;
+    if (metadataOf(outer, 'list')?.ordered) {
+        const suffix = readOrderedSuffix(outer);
+        const base = orderedBaseOf(outer.children?.[0]);
+        items.forEach((item, i) => {
+            const meta = metadataOf(item, 'listItem');
+            if (!meta)
+                return;
+            meta.marker = String(base + firstIndex + i) + suffix;
+            rebuildListItemRaw(item);
+        });
+    }
+    else {
+        for (const item of items)
+            normalizeItemMarkerToList(item, outer);
+    }
+}

package/dist/tree-operations/list/reconcile-task.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Reconcile listItem task metadata against its first paragraph's raw. The parser stores
+ * the task marker on the item's metadata, but live typing only mutates `paragraph.raw` —
+ * so without this, typing `[ ] ` serializes as a task the live CST still calls plain.
+ */
+import type { CstNode } from '../../core/nodes';
+/**
+ * Align the item's task fields with what a fresh parse of its first line would produce.
+ * On demote the stripped marker bytes are restored into the paragraph raw, so the user's
+ * content survives.
+ */
+export declare function reconcileTaskMetadata(listItem: CstNode): void;

package/dist/tree-operations/list/reconcile-task.js

@@ -0,0 +1,47 @@
+/**
+ * Reconcile listItem task metadata against its first paragraph's raw. The parser stores
+ * the task marker on the item's metadata, but live typing only mutates `paragraph.raw` —
+ * so without this, typing `[ ] ` serializes as a task the live CST still calls plain.
+ */
+import { metadataOf } from '../../core/nodes';
+const TASK_REGEX = /^\[( |x|X)\]\s+/;
+/**
+ * Align the item's task fields with what a fresh parse of its first line would produce.
+ * On demote the stripped marker bytes are restored into the paragraph raw, so the user's
+ * content survives.
+ */
+export function reconcileTaskMetadata(listItem) {
+    if (listItem.kind !== 'listItem')
+        return;
+    const firstChild = listItem.children?.[0];
+    if (!firstChild || firstChild.kind !== 'paragraph')
+        return;
+    const meta = metadataOf(listItem, 'listItem');
+    if (!meta)
+        return;
+    const firstLineEnd = firstChild.raw.indexOf('\n');
+    const firstLineRaw = firstLineEnd === -1 ? firstChild.raw : firstChild.raw.slice(0, firstLineEnd);
+    const restRaw = firstLineEnd === -1 ? '' : firstChild.raw.slice(firstLineEnd);
+    const effectiveFirstLine = (meta.taskMarker ?? '') + firstLineRaw;
+    const match = effectiveFirstLine.match(TASK_REGEX);
+    if (match) {
+        const newTaskMarker = match[0];
+        const newTaskChecked = match[1].toLowerCase() === 'x';
+        const drift = meta.taskItem !== true ||
+            meta.taskMarker !== newTaskMarker ||
+            meta.taskChecked !== newTaskChecked;
+        if (drift) {
+            meta.taskItem = true;
+            meta.taskMarker = newTaskMarker;
+            meta.taskChecked = newTaskChecked;
+            firstChild.raw = effectiveFirstLine.slice(newTaskMarker.length) + restRaw;
+        }
+        return;
+    }
+    if (meta.taskItem === true || meta.taskMarker !== null) {
+        firstChild.raw = effectiveFirstLine + restRaw;
+        meta.taskItem = false;
+        meta.taskMarker = null;
+        meta.taskChecked = false;
+    }
+}

package/dist/tree-operations/list/sublist-separator.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The blank line a list whose first item is EMPTY owes the paragraph directly above it. A
+ * content-less marker cannot interrupt a paragraph (CommonMark § 5.2), so those bytes reload as
+ * a setext heading, and the marker is the item's only evidence, so the seam absorb has nothing
+ * to fold it into. A content-bearing list that stopped interrupting is the absorb's case.
+ */
+import type { CstNode } from '../../core/nodes';
+/**
+ * Give the child at `index` its separating line when it is a list no reload could read back.
+ * Idempotent, and a no-op for every child that already stands apart, so a nesting splice or a
+ * raw rebuild may call it unconditionally.
+ */
+export declare function settleSublistSeparator(children: CstNode[], index: number): void;

package/dist/tree-operations/list/sublist-separator.js

@@ -0,0 +1,34 @@
+/**
+ * The blank line a list whose first item is EMPTY owes the paragraph directly above it. A
+ * content-less marker cannot interrupt a paragraph (CommonMark § 5.2), so those bytes reload as
+ * a setext heading, and the marker is the item's only evidence, so the seam absorb has nothing
+ * to fold it into. A content-bearing list that stopped interrupting is the absorb's case.
+ */
+import { trailingLineEnding } from '../../core/lines';
+/**
+ * A marker line carrying nothing after it: the Enter+Tab mint, and an emptied nested item. The
+ * trailing run is required, matching `matchListItem` — a bare `-` never opened a list at all.
+ */
+const EMPTY_MARKER_LINE = /^ {0,3}(?:[-*+]|\d{1,9}[.)])[ \t]+$/;
+/**
+ * Give the child at `index` its separating line when it is a list no reload could read back.
+ * Idempotent, and a no-op for every child that already stands apart, so a nesting splice or a
+ * raw rebuild may call it unconditionally.
+ */
+export function settleSublistSeparator(children, index) {
+    const list = children[index];
+    const above = children[index - 1];
+    if (!list || list.kind !== 'list' || list.leadingTrivia !== '')
+        return;
+    if (!above || above.kind !== 'paragraph' || above.raw.trim() === '')
+        return;
+    if (!EMPTY_MARKER_LINE.test(firstLineOf(list.raw)))
+        return;
+    list.leadingTrivia = trailingLineEnding(above.raw);
+}
+function firstLineOf(raw) {
+    const nl = raw.indexOf('\n');
+    if (nl < 0)
+        return raw;
+    return raw[nl - 1] === '\r' ? raw.slice(0, nl - 1) : raw.slice(0, nl);
+}

package/dist/tree-operations/list/terminator.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Ensure a list item's `raw` ends with a line ending. Without it `rebuildListRaw`
+ * concatenates adjacent items' raws into one line, which re-parses as one item. The
+ * ending is a parameter, never a literal `'\n'`: an item arriving without one adopts the
+ * target's (G4.20), or a paste strands an LF line inside a CRLF list. Parse-time items
+ * keep their original state; only mid-list splices normalize.
+ */
+import type { CstNode } from '../../core/nodes';
+export declare function ensureListItemNewlineTerminated(item: CstNode, ending: '\n' | '\r\n'): void;
+/** Normalize every pasted listItem in `items` (non-listItems pass through). */
+export declare function newlineTerminateListItems(items: CstNode[], ending: '\n' | '\r\n'): void;
+/**
+ * THE way pasted items enter a list's children mid-array: termination is welded to the
+ * splice so a new paste path cannot forget it. The ending comes from the neighbours the
+ * items join — displaced target, then the item above, then the list head.
+ */
+export declare function spliceTerminatedItems(children: CstNode[], at: number, removeCount: number, items: CstNode[]): void;

package/dist/tree-operations/list/terminator.js

@@ -0,0 +1,60 @@
+/**
+ * Ensure a list item's `raw` ends with a line ending. Without it `rebuildListRaw`
+ * concatenates adjacent items' raws into one line, which re-parses as one item. The
+ * ending is a parameter, never a literal `'\n'`: an item arriving without one adopts the
+ * target's (G4.20), or a paste strands an LF line inside a CRLF list. Parse-time items
+ * keep their original state; only mid-list splices normalize.
+ */
+import { trailingLineEnding } from '../../core/lines';
+import { spliceMany } from '../splice-many';
+import { rebuildContainerRawIfContainer } from '../../schema/container-raw';
+import { getBlockKindDescriptor } from '../../schema/block-kind-descriptor';
+/**
+ * The child holding the node's last LINE, or null when the node's own raw holds it. Only a
+ * strip container serializes its children's raws as whole lines; a grid cell and an opaque
+ * body live inside a line their container emits, so the ending belongs to the container.
+ */
+function lastLineOwningChild(node) {
+    if (getBlockKindDescriptor(node.kind).containerContract !== 'strip')
+        return null;
+    const children = node.children;
+    if (!children || children.length === 0)
+        return null;
+    return children[children.length - 1];
+}
+/**
+ * Terminate the deepest node that owns its own last line, then rebuild every strip container
+ * above it: such a container's raw is DERIVED from its children, so appending to it directly
+ * leaves the two disagreeing (G1.1) and its tail item still unterminated.
+ */
+function terminateLastLine(node, ending) {
+    if (node.raw.endsWith('\n'))
+        return;
+    const child = lastLineOwningChild(node);
+    if (!child) {
+        node.raw += ending;
+        return;
+    }
+    terminateLastLine(child, ending);
+    rebuildContainerRawIfContainer(node);
+}
+export function ensureListItemNewlineTerminated(item, ending) {
+    terminateLastLine(item, ending);
+}
+/** Normalize every pasted listItem in `items` (non-listItems pass through). */
+export function newlineTerminateListItems(items, ending) {
+    for (const item of items) {
+        if (item.kind === 'listItem')
+            ensureListItemNewlineTerminated(item, ending);
+    }
+}
+/**
+ * THE way pasted items enter a list's children mid-array: termination is welded to the
+ * splice so a new paste path cannot forget it. The ending comes from the neighbours the
+ * items join — displaced target, then the item above, then the list head.
+ */
+export function spliceTerminatedItems(children, at, removeCount, items) {
+    const neighbour = (removeCount > 0 ? children[at] : undefined) ?? children[at - 1] ?? children[0];
+    newlineTerminateListItems(items, neighbour ? trailingLineEnding(neighbour.raw) : '\n');
+    spliceMany(children, at, removeCount, items);
+}

package/dist/tree-operations/list/unwrap-merge.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Structural list-item reshaping for U1 (unwrap a list's first item) and M1 (merge a
+ * non-first item into the deepest text leaf of the preceding item). Both preserve absolute
+ * indent and keep ordered-marker sequences intact.
+ */
+import type { CstNode } from '../../core/nodes';
+import type { NodeView } from '../../core/node-views';
+import type { PresentationMode } from '../../presentation-mode';
+import type { InlineResolverRef } from '../../schema/inline-construct-policy';
+import type { SharingState } from '../sharing';
+/**
+ * Unwrap a list's first item (Rule U1) without mutating the input. Output order: the item's
+ * non-promoting children lifted in place, then the shrunk parent list with the promoted
+ * sub-list items prepended and ordered markers renumbered.
+ */
+export declare function unwrapFirstItemFromList(list: NodeView): CstNode[];
+/**
+ * Merge the list item at `currentIndex` into the deepest text-bearing leaf of the
+ * preceding item, mutating `list` in place and returning the merge point for the caret.
+ * `targetPath`'s trailing index is the LAST paragraph in the target item, not always 0.
+ * Null when the previous item exposes only an opaque deepest leaf — that is a legitimate
+ * outcome the caller falls back from, unlike a bad `currentIndex`, which throws.
+ */
+export declare function mergeListItemIntoPrevious(list: CstNode, children: CstNode[], currentIndex: number, sharing: SharingState | undefined, presentationMode: PresentationMode | undefined, linkRef: InlineResolverRef | undefined): {
+    mergePoint: {
+        targetPath: number[];
+        offset: number;
+    };
+} | null;

package/dist/tree-operations/list/unwrap-merge.js

@@ -0,0 +1,202 @@
+/**
+ * Structural list-item reshaping for U1 (unwrap a list's first item) and M1 (merge a
+ * non-first item into the deepest text leaf of the preceding item). Both preserve absolute
+ * indent and keep ordered-marker sequences intact.
+ */
+import { metadataOf } from '../../core/nodes';
+import { trailingLineEnding } from '../../core/lines';
+import { cleanJoinedRaw } from '../node-ops';
+import { cloneMetadata, cloneNode } from '../clone';
+import { rebuildAncestryRaw } from '../../schema/container-raw';
+import { rebuildListRaw } from '../../schema/container-rebuilders';
+import { walkToDeepestMergeLeaf } from '../../schema/merge-rules';
+import { orderedBaseOf, renumberOrderedList, renumberOrderedListFrom } from './ordered-markers';
+import { partitionItemChildren } from './item-partition';
+import { ensureUnsharedChild, ensureUnsharedNode, ensureUnsharedPath } from '../unshare';
+import { assignIds } from '../../block-id';
+import { pushChild } from '../children';
+/**
+ * Unwrap a list's first item (Rule U1) without mutating the input. Output order: the item's
+ * non-promoting children lifted in place, then the shrunk parent list with the promoted
+ * sub-list items prepended and ordered markers renumbered.
+ */
+export function unwrapFirstItemFromList(list) {
+    if (list.kind !== 'list' || !list.children || list.children.length === 0) {
+        return [];
+    }
+    const parentOrdered = metadataOf(list, 'list')?.ordered ?? false;
+    const firstItem = list.children[0];
+    if (!firstItem.children || firstItem.children.length === 0) {
+        // Empty item: nothing to lift, so return the shrunk list.
+        const clonedList = cloneNode(list);
+        const rest = clonedList.children.slice(1);
+        if (rest.length === 0)
+            return [];
+        clonedList.children = rest;
+        // childIds pairs by index, so it slices with the children or every survivor
+        // inherits its predecessor's id.
+        clonedList.childIds = clonedList.childIds?.slice(1);
+        rebuildListRaw(clonedList);
+        return [clonedList];
+    }
+    const { promotedItems, liftedBlocks } = partitionItemChildren(firstItem.children, parentOrdered);
+    const restItems = list.children.slice(1).map(cloneNode);
+    const remainingItems = [...promotedItems, ...restItems];
+    if (remainingItems.length === 0) {
+        return liftedBlocks;
+    }
+    remainingItems[0].leadingTrivia = '';
+    const remainingList = {
+        kind: 'list',
+        leadingTrivia: '',
+        raw: '',
+        metadata: list.metadata
+            ? cloneMetadata(list.metadata)
+            : { ordered: parentOrdered },
+        children: remainingItems,
+        childIds: assignIds(remainingItems),
+        innerPrefix: list.innerPrefix ?? '',
+        innerSuffix: list.innerSuffix ?? ''
+    };
+    // Preserve the original list's starting number.
+    renumberOrderedListFrom(remainingList, orderedBaseOf(firstItem));
+    rebuildListRaw(remainingList);
+    liftedBlocks.push(remainingList);
+    return liftedBlocks;
+}
+/** M1's target-finder; null when no prose leaf is reachable. */
+function findDeepestVisibleTextTarget(list, targetItemIndex) {
+    if (!list.children || targetItemIndex < 0 || targetItemIndex >= list.children.length) {
+        return null;
+    }
+    const startItem = list.children[targetItemIndex];
+    const result = walkToDeepestMergeLeaf(startItem, [targetItemIndex]);
+    return result ? result.path : null;
+}
+/**
+ * The depth-1 sibling list that "preserve absolute indent" promotes into: the last list
+ * child of the merge target's top-level item, only when the target sits deep enough
+ * (path length >= 4). Unshares the list it resolves.
+ */
+function depthOneListFor(list, targetPath, sharing) {
+    if (targetPath.length < 4)
+        return null;
+    const depthOneParent = list.children[targetPath[0]];
+    if (!depthOneParent.children)
+        return null;
+    const idx = depthOneParent.children.findLastIndex((c) => c.kind === 'list');
+    if (idx === -1)
+        return null;
+    const depthOneList = sharing
+        ? ensureUnsharedChild(depthOneParent, idx, sharing)
+        : depthOneParent.children[idx];
+    return depthOneList.children ? depthOneList : null;
+}
+/**
+ * Relocate the merged-away item's remaining children by "preserve absolute indent":
+ * nested-list items promote to the depth-1 sibling container when the merge target sits
+ * deeper, everything else absorbs into the target item. Children are MOVED into the live
+ * tree and unshared individually, so the snapshot's view of the deleted item stays intact
+ * (G1.9).
+ */
+function relocateRemainingChildren(list, targetPath, targetItem, currentItem, lineEnding, sharing) {
+    const remainingChildren = currentItem
+        .children.slice(1)
+        .map((c) => (sharing ? ensureUnsharedNode(c, sharing) : c));
+    for (const child of remainingChildren) {
+        if (child.kind === 'list' && child.children) {
+            const depthOneList = depthOneListFor(list, targetPath, sharing);
+            if (depthOneList) {
+                for (let i = 0; i < child.children.length; i++) {
+                    const item = sharing ? ensureUnsharedChild(child, i, sharing) : child.children[i];
+                    item.leadingTrivia = '';
+                    // discovered-descendant mutation, see node-ops.ts header
+                    pushChild(depthOneList, item);
+                }
+                rebuildListRaw(depthOneList);
+                continue;
+            }
+            // discovered-descendant mutation, see node-ops.ts header
+            pushChild(targetItem, child);
+        }
+        else {
+            // A trailing paragraph keeps its blank-line separator, or the two lazy-continue
+            // into one on reload. Other leaves start fresh and need none.
+            child.leadingTrivia = child.kind === 'paragraph' ? lineEnding : '';
+            // discovered-descendant mutation, see node-ops.ts header
+            pushChild(targetItem, child);
+        }
+    }
+}
+/**
+ * Merge the list item at `currentIndex` into the deepest text-bearing leaf of the
+ * preceding item, mutating `list` in place and returning the merge point for the caret.
+ * `targetPath`'s trailing index is the LAST paragraph in the target item, not always 0.
+ * Null when the previous item exposes only an opaque deepest leaf — that is a legitimate
+ * outcome the caller falls back from, unlike a bad `currentIndex`, which throws.
+ */
+export function mergeListItemIntoPrevious(list, children, currentIndex, sharing, presentationMode, linkRef) {
+    // Targeting may read `list.children`, but the final splice MUST land in `children`
+    // (`node-ops.ts` header).
+    if (list.kind !== 'list' ||
+        !list.children ||
+        currentIndex <= 0 ||
+        currentIndex >= children.length) {
+        throw new Error(`mergeListItemIntoPrevious: invalid currentIndex ${currentIndex}`);
+    }
+    const previousIndex = currentIndex - 1;
+    const targetPath = findDeepestVisibleTextTarget(list, previousIndex);
+    if (!targetPath)
+        return null;
+    // Before any capture: the walk below must see the owned copies, and the target
+    // paragraph's raw is written in place.
+    if (sharing)
+        ensureUnsharedPath({ children: list.children }, targetPath, sharing);
+    let targetItem = list;
+    for (let i = 0; i < targetPath.length - 1; i++) {
+        targetItem = targetItem.children[targetPath[i]];
+    }
+    // A loose item's walker ends past 0, so reading children[0] would mutate the wrong
+    // paragraph.
+    const targetParagraphIndex = targetPath[targetPath.length - 1];
+    const targetParagraph = targetItem.children?.[targetParagraphIndex];
+    if (!targetParagraph || targetParagraph.kind !== 'paragraph') {
+        throw new Error('mergeListItemIntoPrevious: target path does not end at a paragraph');
+    }
+    const targetOriginalText = (targetParagraph.raw ?? '').replace(/\r?\n$/, '');
+    const currentItem = children[currentIndex];
+    if (!currentItem.children ||
+        currentItem.children.length === 0 ||
+        currentItem.children[0].kind !== 'paragraph') {
+        throw new Error('mergeListItemIntoPrevious: current item does not start with a paragraph');
+    }
+    const currentFirstParagraph = currentItem.children[0];
+    const currentFirstText = (currentFirstParagraph.raw ?? '').replace(/\r?\n$/, '');
+    const lineEnding = trailingLineEnding(targetParagraph.raw ?? '');
+    // Every destructive join crosses the seam cleaner, M1 included: a literal concatenation
+    // surfaces the marker runs the join orphaned, which live paints for nobody.
+    const joined = cleanJoinedRaw({
+        mergedRaw: targetOriginalText + currentFirstText,
+        seam: targetOriginalText.length,
+        start: { node: targetParagraph, offset: targetOriginalText.length },
+        end: { node: currentFirstParagraph, offset: 0 },
+        linkRef
+    }, presentationMode);
+    // The caret rides the CLEANED seam: a run dropped on the target's side moves where the
+    // two halves met.
+    const mergeOffset = joined.seam;
+    targetParagraph.raw = joined.raw + lineEnding;
+    relocateRemainingChildren(list, targetPath, targetItem, currentItem, lineEnding, sharing);
+    children.splice(currentIndex, 1);
+    // So the post-splice reads below see the new shape; idempotent with the commit's
+    // final publish.
+    list.children = children;
+    rebuildAncestryRaw(list, targetPath);
+    if (metadataOf(list, 'list')?.ordered) {
+        // M1 only removes a non-first item, so children[0] keeps the list's original base;
+        // renumber from 1 to continue it rather than resetting the sequence.
+        renumberOrderedList(list, 1, sharing);
+        rebuildListRaw(list);
+    }
+    return { mergePoint: { targetPath, offset: mergeOffset } };
+}