@superdoc/sdk 2.22.0-next.15 → 2.22.0-next.17

package/dist/agent/actions.cjs

@@ -165,13 +165,15 @@ function findSnapshotTextByNodeId(snapshot, nodeId) {
 }
 function createdBlockTarget(result) {
     const rec = asRecord(result);
-    const paragraph = asRecord(rec?.paragraph);
-    if (typeof paragraph?.nodeId === 'string' && paragraph.nodeId.length > 0) {
-        return { nodeId: paragraph.nodeId, nodeType: 'paragraph' };
-    }
-    const heading = asRecord(rec?.heading);
-    if (typeof heading?.nodeId === 'string' && heading.nodeId.length > 0) {
-        return { nodeId: heading.nodeId, nodeType: 'heading' };
+    for (const [key, nodeType] of [
+        ['paragraph', 'paragraph'],
+        ['heading', 'heading'],
+        ['item', 'listItem'],
+    ]) {
+        const block = asRecord(rec?.[key]);
+        if (typeof block?.nodeId === 'string' && block.nodeId.length > 0) {
+            return { nodeId: block.nodeId, nodeType };
+        }
     }
     return null;
 }
@@ -1547,7 +1549,7 @@ async function runInsertListItems(doc, args) {
     }
 }
 async function runAddListItems(doc, args, opts) {
-    const pre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
+    const pre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks', 'lists'] });
     try {
         const needle = args.anchorText?.trim();
         const anchorNodeId = args.anchorNodeId?.trim();
@@ -1598,25 +1600,47 @@ async function runAddListItems(doc, args, opts) {
         }
         const anchorPath = blockNumbering(anchor)?.path;
         const anchorLevel = Array.isArray(anchorPath) ? Math.max(0, anchorPath.length - 1) : 0;
+        const listByNodeId = new Map((pre.lists ?? []).flatMap((list) => list.items.map((item) => [item.nodeId, list.listId])));
+        const anchorListId = listByNodeId.get(anchor.nodeId);
+        // The lists snapshot is paged, so a missing item is unknown, not foreign.
+        const belongsToAnchorList = (row) => {
+            const rowListId = row.nodeId == null ? undefined : listByNodeId.get(row.nodeId);
+            return anchorListId == null || rowListId == null || rowListId === anchorListId;
+        };
         // Place new items AFTER the anchor's whole sub-tree — every following item
         // whose numbering PATH is nested under the anchor's path (e.g. [12] ⊂ [12,4]).
         // Match by path prefix, not merely "deeper level", and SKIP interleaved
         // non-numbered paragraphs (list-item continuations) rather than stopping at
         // them — real lists wrap sub-items across plain paragraphs. Stop at the first
         // numbered item that is NOT a descendant (a sibling/ancestor, or a different
-        // list). Without this, a new same-level item wedges in among the anchor's
+        // unrelated list). Without this, a new same-level item wedges in among the anchor's
         // children and steals the ones after it. No descendants → the anchor itself.
         let subtreeEnd = anchor;
         const anchorPathArr = Array.isArray(anchorPath) ? anchorPath : null;
         const anchorIdx = rows.findIndex((r) => r.nodeId === anchor.nodeId);
         if (anchorPathArr && anchorIdx >= 0) {
             const isDescendant = (p) => Array.isArray(p) && p.length > anchorPathArr.length && anchorPathArr.every((v, k) => p[k] === v);
+            const descendantListIds = new Set();
+            let lastDescendantIdx = anchorIdx;
             for (let i = anchorIdx + 1; i < rows.length; i += 1) {
                 const p = blockNumbering(rows[i])?.path;
-                if (isDescendant(p)) {
+                const listId = listByNodeId.get(rows[i].nodeId ?? '');
+                const foreign = !belongsToAnchorList(rows[i]) && listId != null;
+                // A separate numbering definition counts on its own, so its path need
+                // not start with the anchor's path ([1, 2] under [2]); go by depth.
+                const nestedForeign = foreign && Array.isArray(p) && p.length > anchorPathArr.length;
+                if (isDescendant(p) || nestedForeign) {
+                    if (foreign && !descendantListIds.has(listId)) {
+                        // Nested bullets can use a separate numbering definition. Its first
+                        // item must be contiguous; a new list after plain text is unrelated.
+                        if (i !== lastDescendantIdx + 1)
+                            break;
+                        descendantListIds.add(listId);
+                    }
                     subtreeEnd = rows[i]; // a nested child/grandchild of the anchor
+                    lastDescendantIdx = i;
                 }
-                else if (Array.isArray(p)) {
+                else if (Array.isArray(p) || (blockNumbering(rows[i]) && !belongsToAnchorList(rows[i]))) {
                     break; // a numbered item that is NOT a descendant → sub-tree ended
                 }
                 // else: non-numbered paragraph (a continuation) — skip and keep scanning
@@ -1634,30 +1658,55 @@ async function runAddListItems(doc, args, opts) {
         if (firstRelative < 0) {
             const firstTargetLevel = Math.max(0, anchorLevel + firstRelative);
             const startIdx = rows.findIndex((r) => r.nodeId === subtreeEnd.nodeId);
+            const descendantListIds = new Set();
+            let lastDescendantIdx = startIdx;
             for (let i = startIdx + 1; i >= 1 && i < rows.length; i += 1) {
                 const level = levelOfRow(rows[i]);
                 if (level == null)
                     continue; // non-numbered continuation paragraph
                 if (level <= firstTargetLevel)
                     break;
+                const listId = listByNodeId.get(rows[i].nodeId ?? '');
+                if (!belongsToAnchorList(rows[i]) && listId != null && !descendantListIds.has(listId)) {
+                    if (i !== lastDescendantIdx + 1)
+                        break;
+                    descendantListIds.add(listId);
+                }
                 subtreeEnd = rows[i];
+                lastDescendantIdx = i;
             }
         }
+        const anchorKind = blockNumbering(anchor)?.kind ?? null;
+        // Search nearest first within the destination level. A known list may mix
+        // ordered and bullet levels. Keep the numbering-kind fallback only when
+        // the paged snapshot cannot establish that both items share a list.
+        const findSiblingAt = (level) => {
+            const usable = (r) => !!r?.nodeId &&
+                belongsToAnchorList(r) &&
+                levelOfRow(r) === level &&
+                ((anchorListId != null && listByNodeId.get(r.nodeId) === anchorListId) ||
+                    (blockNumbering(r)?.kind ?? null) === anchorKind);
+            for (let delta = 1; delta <= rows.length; delta += 1) {
+                const before = anchorIdx >= 0 ? rows[anchorIdx - delta] : undefined;
+                if (usable(before))
+                    return before;
+                const after = anchorIdx >= 0 ? rows[anchorIdx + delta] : undefined;
+                if (usable(after))
+                    return after;
+            }
+            return undefined;
+        };
+        /** The existing item a new one should look like: same level, nearest first. */
+        const formattingSourceForLevel = (targetLevel) => targetLevel === anchorLevel ? anchor : findSiblingAt(targetLevel);
         const attachFn = maybeMethod(doc, ['lists', 'attach']);
-        if (!attachFn) {
-            throw new errors.SuperDocCliError('doc.lists.attach is not available on the document handle.', {
+        const insertFn = maybeMethod(doc, ['lists', 'insert']);
+        if (!attachFn || !insertFn) {
+            throw new errors.SuperDocCliError('doc.lists.insert and doc.lists.attach are required on the document handle.', {
                 code: 'TOOL_DISPATCH_NOT_FOUND',
             });
         }
         const executed = [];
-        let placement = {
-            kind: 'after',
-            target: {
-                kind: 'block',
-                nodeType: subtreeEnd.nodeType ?? 'listItem',
-                nodeId: subtreeEnd.nodeId ?? anchor.nodeId,
-            },
-        };
+        let insertionAnchorId = subtreeEnd.nodeId ?? anchor.nodeId;
         const createdItems = [];
         for (const entry of args.entries) {
             // Styled items carry ordered `runs`; a plain item is a single run. The
@@ -1670,11 +1719,25 @@ async function runAddListItems(doc, args, opts) {
             // outline level is clamped at 0 (can't go above the root).
             const rel = typeof entry?.level === 'number' ? Math.floor(entry.level) : 0;
             const targetLevel = Math.max(0, anchorLevel + rel);
-            const created = await executeCreateParagraph(doc, text, placement, args.changeMode);
+            const formattingSource = formattingSourceForLevel(targetLevel) ?? anchor;
+            // Placement can follow a child with different direction. Inherit from
+            // the intended list level independently of that insertion point.
+            const created = await insertFn({
+                target: { kind: 'block', nodeType: 'listItem', nodeId: insertionAnchorId },
+                position: 'after',
+                text,
+                ...(formattingSource.nodeId !== insertionAnchorId
+                    ? { inheritFrom: { kind: 'block', nodeType: 'listItem', nodeId: formattingSource.nodeId } }
+                    : {}),
+                ...(args.changeMode ? { changeMode: args.changeMode } : {}),
+            }, args.changeMode ? { changeMode: args.changeMode } : undefined);
             const target = createdBlockTarget(created);
-            executed.push({ operationId: 'doc.create.paragraph', result: created });
-            if (!target)
-                continue;
+            if (!target || target.nodeType !== 'listItem') {
+                throw new errors.SuperDocCliError('doc.lists.insert did not return a created list item.', {
+                    code: 'ACTION_FAILED',
+                });
+            }
+            executed.push({ operationId: 'doc.lists.insert', result: created });
             // changeMode is a MutationOption — pass it in the second options arg, not
             // the input (lists.attach reads options.changeMode; input.changeMode is ignored).
             const attachResult = await attachFn({
@@ -1690,53 +1753,10 @@ async function runAddListItems(doc, args, opts) {
                 rationale: `level ${targetLevel}`,
             });
             createdItems.push({ nodeId: target.nodeId, targetLevel, text, runs, itemMarks: entry?.marks });
-            // After attach the block is a listItem (same nodeId) — the next placement
-            // must address it as such or the create resolver rejects the anchor.
-            placement = { kind: 'after', target: { kind: 'block', nodeType: 'listItem', nodeId: target.nodeId } };
-        }
-        // A new item is created next to the ANCHOR, so it inherits the anchor's
-        // direct indentation — correct at the same level, wrong at any other one.
-        // `lists.attach` sets the numbering level (`w:ilvl`) but leaves that direct
-        // `w:ind` alone, so a level-changing add renders with a sub-item's indent
-        // under a top-level number: e.g. an item promoted to level 0 kept
-        // left=1800 while its "1./2./3." siblings sit at 1080. Copy the indentation
-        // from an EXISTING sibling at the item's own level. Best-effort: an
-        // unmatched indent is cosmetic and must not fail an item that landed.
-        const createdIds = new Set(createdItems.map((ci) => ci.nodeId));
-        const anchorKind = blockNumbering(anchor)?.kind ?? null;
-        // Search OUTWARD from the anchor, nearest first, and only accept items
-        // of the anchor's own numbering kind: a document holds several lists,
-        // and the first level-0 item in document order usually belongs to a
-        // different one (here: a bullet list far above the ordered list being
-        // extended), whose indentation is unrelated.
-        const findSiblingAt = (level) => {
-            const usable = (r) => !!r?.nodeId &&
-                !createdIds.has(r.nodeId) &&
-                levelOfRow(r) === level &&
-                (blockNumbering(r)?.kind ?? null) === anchorKind;
-            for (let delta = 1; delta <= rows.length; delta += 1) {
-                const before = anchorIdx >= 0 ? rows[anchorIdx - delta] : undefined;
-                if (usable(before))
-                    return before;
-                const after = anchorIdx >= 0 ? rows[anchorIdx + delta] : undefined;
-                if (usable(after))
-                    return after;
-            }
-            return undefined;
-        };
-        /** The existing item a new one should look like: same level, nearest first. */
-        const lookSourceFor = (targetLevel) => targetLevel === anchorLevel ? anchor : findSiblingAt(targetLevel);
-        // Most Word documents keep a list's look in a paragraph STYLE, not in direct
-        // properties: "MB Agr 2", "Quick 1.", even Heading3 carry the numbering, the
-        // indentation and the face. A created paragraph does not get the sibling's
-        // style — it gets the anchor's `next` style (Heading3 → BodyText), a default
-        // (ListParagraph, whose contextualSpacing changes the spacing), or the
-        // anchor's own style when the new item belongs to a DIFFERENT level (keeping
-        // "MB Agr 3" on an item whose numbering now says level 2). Reconcile it with
-        // the sibling at the item's own level.
-        //
-        // setStyleRef, not setStyle: setStyle clears direct run formatting, which
-        // would wipe the sampled run look applied below.
+            insertionAnchorId = target.nodeId;
+        }
+        // Insertion may select a style's `next` style; keep the destination list level's
+        // style instead. setStyleRef preserves the inherited direct run formatting.
         const styledItems = [];
         const styleSkipped = await bestEffort(async () => {
             const setStyleRefFn = maybeMethod(doc, ['styles', 'paragraph', 'setStyleRef']);
@@ -1745,7 +1765,7 @@ async function runAddListItems(doc, args, opts) {
                 return;
             let current = null;
             for (const ci of createdItems) {
-                const source = lookSourceFor(ci.targetLevel);
+                const source = formattingSourceForLevel(ci.targetLevel);
                 if (!source)
                     continue;
                 const wanted = source.styleId ?? null;
@@ -1763,6 +1783,8 @@ async function runAddListItems(doc, args, opts) {
                 styledItems.push({ nodeId: ci.nodeId, styleId: wanted });
             }
         });
+        // lists.attach changes numbering level without normalizing direct indentation.
+        // Match the existing destination level when its indentation is available.
         const indentedItems = [];
         const indentSkipped = await bestEffort(async () => {
             const setIndentFn = maybeMethod(doc, ['format', 'paragraph', 'setIndentation']);
@@ -1770,7 +1792,7 @@ async function runAddListItems(doc, args, opts) {
             if (!setIndentFn || !getNodeFn)
                 return;
             for (const ci of createdItems) {
-                const sibling = lookSourceFor(ci.targetLevel);
+                const sibling = formattingSourceForLevel(ci.targetLevel);
                 if (!sibling?.nodeId)
                     continue;
                 const node = (await getNodeFn({ id: sibling.nodeId }));
@@ -1853,7 +1875,7 @@ async function runAddListItems(doc, args, opts) {
             // The BASE layer must come from the row the item will sit beside, not
             // from the anchor: a promoted or demoted item crosses levels, and the
             // anchor's font/size/colour/emphasis is then the wrong level's look.
-            // `lookSourceFor(targetLevel)` already picks the destination sibling for
+            // `formattingSourceForLevel(targetLevel)` already picks the destination sibling for
             // style and indent, so the look follows the same source. Falls back to
             // the anchor only when the destination level has no sibling to sample.
             const anchorBase = inlineLookFromRow(anchor);
@@ -1891,7 +1913,7 @@ async function runAddListItems(doc, args, opts) {
                     // An item the agent styled itself is left alone by layers 1–2: its
                     // marks describe the whole intent, and sampling would fight them.
                     const unstyled = ci.itemMarks == null && !ci.runs.some((r) => r.marks);
-                    const source = unstyled ? lookSourceFor(ci.targetLevel) : undefined;
+                    const source = unstyled ? formattingSourceForLevel(ci.targetLevel) : undefined;
                     const sourceText = source?.nodeId ? fullTextById.get(source.nodeId) : undefined;
                     const pattern = source?.nodeId && sourceText ? await listItemRunPattern(doc, sourceText, source.nodeId) : null;
                     // 1. sampled base over the whole item (row fields first, run-level
@@ -1971,7 +1993,7 @@ async function runAddListItems(doc, args, opts) {
                 // promotion keeps the plain marker until that read lands.
                 let markProps = markRunPropsFromMarks({ ...ci.itemMarks, ...ci.runs[0]?.marks });
                 if (!markProps && getNodeFn) {
-                    const source = lookSourceFor(ci.targetLevel);
+                    const source = formattingSourceForLevel(ci.targetLevel);
                     if (source?.nodeId)
                         markProps = paragraphMarkRunPropsOf(await getNodeFn({ id: source.nodeId }));
                 }

package/dist/agent/actions.js

@@ -162,13 +162,15 @@ function findSnapshotTextByNodeId(snapshot, nodeId) {
 }
 function createdBlockTarget(result) {
     const rec = asRecord(result);
-    const paragraph = asRecord(rec?.paragraph);
-    if (typeof paragraph?.nodeId === 'string' && paragraph.nodeId.length > 0) {
-        return { nodeId: paragraph.nodeId, nodeType: 'paragraph' };
-    }
-    const heading = asRecord(rec?.heading);
-    if (typeof heading?.nodeId === 'string' && heading.nodeId.length > 0) {
-        return { nodeId: heading.nodeId, nodeType: 'heading' };
+    for (const [key, nodeType] of [
+        ['paragraph', 'paragraph'],
+        ['heading', 'heading'],
+        ['item', 'listItem'],
+    ]) {
+        const block = asRecord(rec?.[key]);
+        if (typeof block?.nodeId === 'string' && block.nodeId.length > 0) {
+            return { nodeId: block.nodeId, nodeType };
+        }
     }
     return null;
 }
@@ -1544,7 +1546,7 @@ async function runInsertListItems(doc, args) {
     }
 }
 async function runAddListItems(doc, args, opts) {
-    const pre = await buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
+    const pre = await buildMutationSnapshot(doc, { includeDomains: ['blocks', 'lists'] });
     try {
         const needle = args.anchorText?.trim();
         const anchorNodeId = args.anchorNodeId?.trim();
@@ -1595,25 +1597,47 @@ async function runAddListItems(doc, args, opts) {
         }
         const anchorPath = blockNumbering(anchor)?.path;
         const anchorLevel = Array.isArray(anchorPath) ? Math.max(0, anchorPath.length - 1) : 0;
+        const listByNodeId = new Map((pre.lists ?? []).flatMap((list) => list.items.map((item) => [item.nodeId, list.listId])));
+        const anchorListId = listByNodeId.get(anchor.nodeId);
+        // The lists snapshot is paged, so a missing item is unknown, not foreign.
+        const belongsToAnchorList = (row) => {
+            const rowListId = row.nodeId == null ? undefined : listByNodeId.get(row.nodeId);
+            return anchorListId == null || rowListId == null || rowListId === anchorListId;
+        };
         // Place new items AFTER the anchor's whole sub-tree — every following item
         // whose numbering PATH is nested under the anchor's path (e.g. [12] ⊂ [12,4]).
         // Match by path prefix, not merely "deeper level", and SKIP interleaved
         // non-numbered paragraphs (list-item continuations) rather than stopping at
         // them — real lists wrap sub-items across plain paragraphs. Stop at the first
         // numbered item that is NOT a descendant (a sibling/ancestor, or a different
-        // list). Without this, a new same-level item wedges in among the anchor's
+        // unrelated list). Without this, a new same-level item wedges in among the anchor's
         // children and steals the ones after it. No descendants → the anchor itself.
         let subtreeEnd = anchor;
         const anchorPathArr = Array.isArray(anchorPath) ? anchorPath : null;
         const anchorIdx = rows.findIndex((r) => r.nodeId === anchor.nodeId);
         if (anchorPathArr && anchorIdx >= 0) {
             const isDescendant = (p) => Array.isArray(p) && p.length > anchorPathArr.length && anchorPathArr.every((v, k) => p[k] === v);
+            const descendantListIds = new Set();
+            let lastDescendantIdx = anchorIdx;
             for (let i = anchorIdx + 1; i < rows.length; i += 1) {
                 const p = blockNumbering(rows[i])?.path;
-                if (isDescendant(p)) {
+                const listId = listByNodeId.get(rows[i].nodeId ?? '');
+                const foreign = !belongsToAnchorList(rows[i]) && listId != null;
+                // A separate numbering definition counts on its own, so its path need
+                // not start with the anchor's path ([1, 2] under [2]); go by depth.
+                const nestedForeign = foreign && Array.isArray(p) && p.length > anchorPathArr.length;
+                if (isDescendant(p) || nestedForeign) {
+                    if (foreign && !descendantListIds.has(listId)) {
+                        // Nested bullets can use a separate numbering definition. Its first
+                        // item must be contiguous; a new list after plain text is unrelated.
+                        if (i !== lastDescendantIdx + 1)
+                            break;
+                        descendantListIds.add(listId);
+                    }
                     subtreeEnd = rows[i]; // a nested child/grandchild of the anchor
+                    lastDescendantIdx = i;
                 }
-                else if (Array.isArray(p)) {
+                else if (Array.isArray(p) || (blockNumbering(rows[i]) && !belongsToAnchorList(rows[i]))) {
                     break; // a numbered item that is NOT a descendant → sub-tree ended
                 }
                 // else: non-numbered paragraph (a continuation) — skip and keep scanning
@@ -1631,30 +1655,55 @@ async function runAddListItems(doc, args, opts) {
         if (firstRelative < 0) {
             const firstTargetLevel = Math.max(0, anchorLevel + firstRelative);
             const startIdx = rows.findIndex((r) => r.nodeId === subtreeEnd.nodeId);
+            const descendantListIds = new Set();
+            let lastDescendantIdx = startIdx;
             for (let i = startIdx + 1; i >= 1 && i < rows.length; i += 1) {
                 const level = levelOfRow(rows[i]);
                 if (level == null)
                     continue; // non-numbered continuation paragraph
                 if (level <= firstTargetLevel)
                     break;
+                const listId = listByNodeId.get(rows[i].nodeId ?? '');
+                if (!belongsToAnchorList(rows[i]) && listId != null && !descendantListIds.has(listId)) {
+                    if (i !== lastDescendantIdx + 1)
+                        break;
+                    descendantListIds.add(listId);
+                }
                 subtreeEnd = rows[i];
+                lastDescendantIdx = i;
             }
         }
+        const anchorKind = blockNumbering(anchor)?.kind ?? null;
+        // Search nearest first within the destination level. A known list may mix
+        // ordered and bullet levels. Keep the numbering-kind fallback only when
+        // the paged snapshot cannot establish that both items share a list.
+        const findSiblingAt = (level) => {
+            const usable = (r) => !!r?.nodeId &&
+                belongsToAnchorList(r) &&
+                levelOfRow(r) === level &&
+                ((anchorListId != null && listByNodeId.get(r.nodeId) === anchorListId) ||
+                    (blockNumbering(r)?.kind ?? null) === anchorKind);
+            for (let delta = 1; delta <= rows.length; delta += 1) {
+                const before = anchorIdx >= 0 ? rows[anchorIdx - delta] : undefined;
+                if (usable(before))
+                    return before;
+                const after = anchorIdx >= 0 ? rows[anchorIdx + delta] : undefined;
+                if (usable(after))
+                    return after;
+            }
+            return undefined;
+        };
+        /** The existing item a new one should look like: same level, nearest first. */
+        const formattingSourceForLevel = (targetLevel) => targetLevel === anchorLevel ? anchor : findSiblingAt(targetLevel);
         const attachFn = maybeMethod(doc, ['lists', 'attach']);
-        if (!attachFn) {
-            throw new SuperDocCliError('doc.lists.attach is not available on the document handle.', {
+        const insertFn = maybeMethod(doc, ['lists', 'insert']);
+        if (!attachFn || !insertFn) {
+            throw new SuperDocCliError('doc.lists.insert and doc.lists.attach are required on the document handle.', {
                 code: 'TOOL_DISPATCH_NOT_FOUND',
             });
         }
         const executed = [];
-        let placement = {
-            kind: 'after',
-            target: {
-                kind: 'block',
-                nodeType: subtreeEnd.nodeType ?? 'listItem',
-                nodeId: subtreeEnd.nodeId ?? anchor.nodeId,
-            },
-        };
+        let insertionAnchorId = subtreeEnd.nodeId ?? anchor.nodeId;
         const createdItems = [];
         for (const entry of args.entries) {
             // Styled items carry ordered `runs`; a plain item is a single run. The
@@ -1667,11 +1716,25 @@ async function runAddListItems(doc, args, opts) {
             // outline level is clamped at 0 (can't go above the root).
             const rel = typeof entry?.level === 'number' ? Math.floor(entry.level) : 0;
             const targetLevel = Math.max(0, anchorLevel + rel);
-            const created = await executeCreateParagraph(doc, text, placement, args.changeMode);
+            const formattingSource = formattingSourceForLevel(targetLevel) ?? anchor;
+            // Placement can follow a child with different direction. Inherit from
+            // the intended list level independently of that insertion point.
+            const created = await insertFn({
+                target: { kind: 'block', nodeType: 'listItem', nodeId: insertionAnchorId },
+                position: 'after',
+                text,
+                ...(formattingSource.nodeId !== insertionAnchorId
+                    ? { inheritFrom: { kind: 'block', nodeType: 'listItem', nodeId: formattingSource.nodeId } }
+                    : {}),
+                ...(args.changeMode ? { changeMode: args.changeMode } : {}),
+            }, args.changeMode ? { changeMode: args.changeMode } : undefined);
             const target = createdBlockTarget(created);
-            executed.push({ operationId: 'doc.create.paragraph', result: created });
-            if (!target)
-                continue;
+            if (!target || target.nodeType !== 'listItem') {
+                throw new SuperDocCliError('doc.lists.insert did not return a created list item.', {
+                    code: 'ACTION_FAILED',
+                });
+            }
+            executed.push({ operationId: 'doc.lists.insert', result: created });
             // changeMode is a MutationOption — pass it in the second options arg, not
             // the input (lists.attach reads options.changeMode; input.changeMode is ignored).
             const attachResult = await attachFn({
@@ -1687,53 +1750,10 @@ async function runAddListItems(doc, args, opts) {
                 rationale: `level ${targetLevel}`,
             });
             createdItems.push({ nodeId: target.nodeId, targetLevel, text, runs, itemMarks: entry?.marks });
-            // After attach the block is a listItem (same nodeId) — the next placement
-            // must address it as such or the create resolver rejects the anchor.
-            placement = { kind: 'after', target: { kind: 'block', nodeType: 'listItem', nodeId: target.nodeId } };
-        }
-        // A new item is created next to the ANCHOR, so it inherits the anchor's
-        // direct indentation — correct at the same level, wrong at any other one.
-        // `lists.attach` sets the numbering level (`w:ilvl`) but leaves that direct
-        // `w:ind` alone, so a level-changing add renders with a sub-item's indent
-        // under a top-level number: e.g. an item promoted to level 0 kept
-        // left=1800 while its "1./2./3." siblings sit at 1080. Copy the indentation
-        // from an EXISTING sibling at the item's own level. Best-effort: an
-        // unmatched indent is cosmetic and must not fail an item that landed.
-        const createdIds = new Set(createdItems.map((ci) => ci.nodeId));
-        const anchorKind = blockNumbering(anchor)?.kind ?? null;
-        // Search OUTWARD from the anchor, nearest first, and only accept items
-        // of the anchor's own numbering kind: a document holds several lists,
-        // and the first level-0 item in document order usually belongs to a
-        // different one (here: a bullet list far above the ordered list being
-        // extended), whose indentation is unrelated.
-        const findSiblingAt = (level) => {
-            const usable = (r) => !!r?.nodeId &&
-                !createdIds.has(r.nodeId) &&
-                levelOfRow(r) === level &&
-                (blockNumbering(r)?.kind ?? null) === anchorKind;
-            for (let delta = 1; delta <= rows.length; delta += 1) {
-                const before = anchorIdx >= 0 ? rows[anchorIdx - delta] : undefined;
-                if (usable(before))
-                    return before;
-                const after = anchorIdx >= 0 ? rows[anchorIdx + delta] : undefined;
-                if (usable(after))
-                    return after;
-            }
-            return undefined;
-        };
-        /** The existing item a new one should look like: same level, nearest first. */
-        const lookSourceFor = (targetLevel) => targetLevel === anchorLevel ? anchor : findSiblingAt(targetLevel);
-        // Most Word documents keep a list's look in a paragraph STYLE, not in direct
-        // properties: "MB Agr 2", "Quick 1.", even Heading3 carry the numbering, the
-        // indentation and the face. A created paragraph does not get the sibling's
-        // style — it gets the anchor's `next` style (Heading3 → BodyText), a default
-        // (ListParagraph, whose contextualSpacing changes the spacing), or the
-        // anchor's own style when the new item belongs to a DIFFERENT level (keeping
-        // "MB Agr 3" on an item whose numbering now says level 2). Reconcile it with
-        // the sibling at the item's own level.
-        //
-        // setStyleRef, not setStyle: setStyle clears direct run formatting, which
-        // would wipe the sampled run look applied below.
+            insertionAnchorId = target.nodeId;
+        }
+        // Insertion may select a style's `next` style; keep the destination list level's
+        // style instead. setStyleRef preserves the inherited direct run formatting.
         const styledItems = [];
         const styleSkipped = await bestEffort(async () => {
             const setStyleRefFn = maybeMethod(doc, ['styles', 'paragraph', 'setStyleRef']);
@@ -1742,7 +1762,7 @@ async function runAddListItems(doc, args, opts) {
                 return;
             let current = null;
             for (const ci of createdItems) {
-                const source = lookSourceFor(ci.targetLevel);
+                const source = formattingSourceForLevel(ci.targetLevel);
                 if (!source)
                     continue;
                 const wanted = source.styleId ?? null;
@@ -1760,6 +1780,8 @@ async function runAddListItems(doc, args, opts) {
                 styledItems.push({ nodeId: ci.nodeId, styleId: wanted });
             }
         });
+        // lists.attach changes numbering level without normalizing direct indentation.
+        // Match the existing destination level when its indentation is available.
         const indentedItems = [];
         const indentSkipped = await bestEffort(async () => {
             const setIndentFn = maybeMethod(doc, ['format', 'paragraph', 'setIndentation']);
@@ -1767,7 +1789,7 @@ async function runAddListItems(doc, args, opts) {
             if (!setIndentFn || !getNodeFn)
                 return;
             for (const ci of createdItems) {
-                const sibling = lookSourceFor(ci.targetLevel);
+                const sibling = formattingSourceForLevel(ci.targetLevel);
                 if (!sibling?.nodeId)
                     continue;
                 const node = (await getNodeFn({ id: sibling.nodeId }));
@@ -1850,7 +1872,7 @@ async function runAddListItems(doc, args, opts) {
             // The BASE layer must come from the row the item will sit beside, not
             // from the anchor: a promoted or demoted item crosses levels, and the
             // anchor's font/size/colour/emphasis is then the wrong level's look.
-            // `lookSourceFor(targetLevel)` already picks the destination sibling for
+            // `formattingSourceForLevel(targetLevel)` already picks the destination sibling for
             // style and indent, so the look follows the same source. Falls back to
             // the anchor only when the destination level has no sibling to sample.
             const anchorBase = inlineLookFromRow(anchor);
@@ -1888,7 +1910,7 @@ async function runAddListItems(doc, args, opts) {
                     // An item the agent styled itself is left alone by layers 1–2: its
                     // marks describe the whole intent, and sampling would fight them.
                     const unstyled = ci.itemMarks == null && !ci.runs.some((r) => r.marks);
-                    const source = unstyled ? lookSourceFor(ci.targetLevel) : undefined;
+                    const source = unstyled ? formattingSourceForLevel(ci.targetLevel) : undefined;
                     const sourceText = source?.nodeId ? fullTextById.get(source.nodeId) : undefined;
                     const pattern = source?.nodeId && sourceText ? await listItemRunPattern(doc, sourceText, source.nodeId) : null;
                     // 1. sampled base over the whole item (row fields first, run-level
@@ -1968,7 +1990,7 @@ async function runAddListItems(doc, args, opts) {
                 // promotion keeps the plain marker until that read lands.
                 let markProps = markRunPropsFromMarks({ ...ci.itemMarks, ...ci.runs[0]?.marks });
                 if (!markProps && getNodeFn) {
-                    const source = lookSourceFor(ci.targetLevel);
+                    const source = formattingSourceForLevel(ci.targetLevel);
                     if (source?.nodeId)
                         markProps = paragraphMarkRunPropsOf(await getNodeFn({ id: source.nodeId }));
                 }