@superdoc/sdk 2.13.1-next.2 → 2.13.1-next.4

package/dist/action-primitives/tools/structure-insert.cjs

@@ -713,15 +713,6 @@ async function executeMoveRangeStep(context, plan) {
             details: { startNodeId: plan.startNodeId, endNodeId: resolvedEndNodeId },
         });
     }
-    if (plan.changeMode === 'tracked') {
-        return engine.workflowStepFailure({
-            status: 'failed',
-            phase: 'execute',
-            code: 'WORKFLOW_STRUCTURE_INSERT_RANGE_TRACKED_UNSUPPORTED',
-            message: 'move_range is direct-only today. Tracked mode would require a tracked block-range move. Nothing was changed. Use move_text for tracked text-span moves or run move_range without changeMode.',
-            details: { startNodeId: plan.startNodeId, endNodeId: resolvedEndNodeId },
-        });
-    }
     const destinationIndex = findBlockIndexByNodeId(blocks, plan.destinationNodeId);
     if (destinationIndex < 0) {
         return engine.workflowStepFailure({
@@ -771,6 +762,30 @@ async function executeMoveRangeStep(context, plan) {
         });
     }
     const anchorBlock = blocks[anchorIndex] ?? destinationBlock;
+    const sourceStart = blocks[startIndex];
+    const sourceEnd = blocks[endIndex];
+    if (sourceStart == null || sourceEnd == null) {
+        return engine.workflowStepFailure({
+            status: 'failed',
+            phase: 'execute',
+            code: 'WORKFLOW_STRUCTURE_INSERT_RANGE_NOT_FOUND',
+            message: 'move_range lost the source range while preparing deletion.',
+        });
+    }
+    if (plan.changeMode === 'tracked') {
+        try {
+            await context.documentHandle.blocks.deleteRange({ start: toListedBlockTarget(sourceStart), end: toListedBlockTarget(sourceEnd), force: true }, {
+                ...withChangeModeOption(context.invokeOptions, plan.changeMode),
+                dryRun: true,
+                expectedRevision: beforeRevision,
+            });
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !('code' in error) || typeof error.code !== 'string')
+                throw error;
+            return engine.workflowStepFailure({ status: 'failed', phase: 'execute', code: error.code, message: error.message });
+        }
+    }
     const insertedBlockNodeIds = [];
     // First copy lands relative to the anchor with the requested position; every
     // subsequent copy lands right after the previous one, preserving range order.
@@ -790,16 +805,6 @@ async function executeMoveRangeStep(context, plan) {
         previousInserted = await createCopiedSectionBlock({ context, block, at: insertionAt, changeMode: plan.changeMode });
         insertedBlockNodeIds.push(previousInserted.nodeId);
     }
-    const sourceStart = blocks[startIndex];
-    const sourceEnd = blocks[endIndex];
-    if (sourceStart == null || sourceEnd == null) {
-        return engine.workflowStepFailure({
-            status: 'failed',
-            phase: 'execute',
-            code: 'WORKFLOW_STRUCTURE_INSERT_RANGE_NOT_FOUND',
-            message: 'move_range lost the source range while preparing deletion.',
-        });
-    }
     // Delete the ORIGINAL source range by nodeId. The freshly-created copies have
     // new nodeIds, so the delete cannot touch them (the copy is preserved).
     const deleteResult = await context.documentHandle.blocks.deleteRange({

package/dist/action-primitives/tools/structure-insert.js

@@ -710,15 +710,6 @@ async function executeMoveRangeStep(context, plan) {
             details: { startNodeId: plan.startNodeId, endNodeId: resolvedEndNodeId },
         });
     }
-    if (plan.changeMode === 'tracked') {
-        return workflowStepFailure({
-            status: 'failed',
-            phase: 'execute',
-            code: 'WORKFLOW_STRUCTURE_INSERT_RANGE_TRACKED_UNSUPPORTED',
-            message: 'move_range is direct-only today. Tracked mode would require a tracked block-range move. Nothing was changed. Use move_text for tracked text-span moves or run move_range without changeMode.',
-            details: { startNodeId: plan.startNodeId, endNodeId: resolvedEndNodeId },
-        });
-    }
     const destinationIndex = findBlockIndexByNodeId(blocks, plan.destinationNodeId);
     if (destinationIndex < 0) {
         return workflowStepFailure({
@@ -768,6 +759,30 @@ async function executeMoveRangeStep(context, plan) {
         });
     }
     const anchorBlock = blocks[anchorIndex] ?? destinationBlock;
+    const sourceStart = blocks[startIndex];
+    const sourceEnd = blocks[endIndex];
+    if (sourceStart == null || sourceEnd == null) {
+        return workflowStepFailure({
+            status: 'failed',
+            phase: 'execute',
+            code: 'WORKFLOW_STRUCTURE_INSERT_RANGE_NOT_FOUND',
+            message: 'move_range lost the source range while preparing deletion.',
+        });
+    }
+    if (plan.changeMode === 'tracked') {
+        try {
+            await context.documentHandle.blocks.deleteRange({ start: toListedBlockTarget(sourceStart), end: toListedBlockTarget(sourceEnd), force: true }, {
+                ...withChangeModeOption(context.invokeOptions, plan.changeMode),
+                dryRun: true,
+                expectedRevision: beforeRevision,
+            });
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !('code' in error) || typeof error.code !== 'string')
+                throw error;
+            return workflowStepFailure({ status: 'failed', phase: 'execute', code: error.code, message: error.message });
+        }
+    }
     const insertedBlockNodeIds = [];
     // First copy lands relative to the anchor with the requested position; every
     // subsequent copy lands right after the previous one, preserving range order.
@@ -787,16 +802,6 @@ async function executeMoveRangeStep(context, plan) {
         previousInserted = await createCopiedSectionBlock({ context, block, at: insertionAt, changeMode: plan.changeMode });
         insertedBlockNodeIds.push(previousInserted.nodeId);
     }
-    const sourceStart = blocks[startIndex];
-    const sourceEnd = blocks[endIndex];
-    if (sourceStart == null || sourceEnd == null) {
-        return workflowStepFailure({
-            status: 'failed',
-            phase: 'execute',
-            code: 'WORKFLOW_STRUCTURE_INSERT_RANGE_NOT_FOUND',
-            message: 'move_range lost the source range while preparing deletion.',
-        });
-    }
     // Delete the ORIGINAL source range by nodeId. The freshly-created copies have
     // new nodeIds, so the delete cannot touch them (the copy is preserved).
     const deleteResult = await context.documentHandle.blocks.deleteRange({

package/dist/agent/action-change-mode.cjs

@@ -0,0 +1,35 @@
+'use strict';
+
+var documentEvidence = require('../runtime/document-evidence.cjs');
+var operationCatalog = require('./operation-catalog.cjs');
+
+function bindActionChangeMode(document, changeMode) {
+    const wrap = (value, path, owner) => new Proxy(value, {
+        get(target, property, receiver) {
+            const member = Reflect.get(target, property, receiver);
+            if (typeof property !== 'string')
+                return member;
+            const memberPath = [...path, property];
+            if (typeof member === 'function' && operationCatalog.getOperationCatalogEntry(`doc.${memberPath.join('.')}`)?.isMutating) {
+                return (input = {}, options) => Reflect.apply(member, target, [
+                    // CLI inputs can already contain a mode. Keep it consistent with
+                    // the options used by in-process Document API hosts.
+                    input.changeMode === undefined ? input : { ...input, changeMode },
+                    { ...options, changeMode },
+                ]);
+            }
+            if (member && (typeof member === 'object' || typeof member === 'function')) {
+                return wrap(member, memberPath, target);
+            }
+            return member;
+        },
+        apply(target, receiver, args) {
+            return Reflect.apply(target, owner ?? receiver, args);
+        },
+    });
+    const wrapped = wrap(document, []);
+    documentEvidence.forwardDocumentEvidence(document, wrapped);
+    return wrapped;
+}
+
+exports.bindActionChangeMode = bindActionChangeMode;

package/dist/agent/action-change-mode.d.ts

@@ -0,0 +1,3 @@
+import type { BoundDocApi } from '../generated/client.js';
+import type { AgentChangeMode } from './ir.js';
+export declare function bindActionChangeMode(document: BoundDocApi, changeMode: AgentChangeMode): BoundDocApi;

package/dist/agent/action-change-mode.js

@@ -0,0 +1,30 @@
+import { forwardDocumentEvidence } from '../runtime/document-evidence.js';
+import { getOperationCatalogEntry } from './operation-catalog.js';
+export function bindActionChangeMode(document, changeMode) {
+    const wrap = (value, path, owner) => new Proxy(value, {
+        get(target, property, receiver) {
+            const member = Reflect.get(target, property, receiver);
+            if (typeof property !== 'string')
+                return member;
+            const memberPath = [...path, property];
+            if (typeof member === 'function' && getOperationCatalogEntry(`doc.${memberPath.join('.')}`)?.isMutating) {
+                return (input = {}, options) => Reflect.apply(member, target, [
+                    // CLI inputs can already contain a mode. Keep it consistent with
+                    // the options used by in-process Document API hosts.
+                    input.changeMode === undefined ? input : { ...input, changeMode },
+                    { ...options, changeMode },
+                ]);
+            }
+            if (member && (typeof member === 'object' || typeof member === 'function')) {
+                return wrap(member, memberPath, target);
+            }
+            return member;
+        },
+        apply(target, receiver, args) {
+            return Reflect.apply(target, owner ?? receiver, args);
+        },
+    });
+    const wrapped = wrap(document, []);
+    forwardDocumentEvidence(document, wrapped);
+    return wrapped;
+}

package/dist/agent/actions.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 var executionContext = require('./execution-context.cjs');
+var actionChangeMode = require('./action-change-mode.cjs');
 var errors = require('../runtime/errors.cjs');
 var listTransform = require('../action-primitives/tools/list-transform.cjs');
 var structureInsert = require('../action-primitives/tools/structure-insert.cjs');
@@ -67,7 +68,7 @@ const ACTION_HINTS = {
     create_table: 'rows, columns, cellTexts? (2D: rows of cells; each cell is a plain string OR a STYLED object {runs:[{text,marks}], marks?} to format the cell — marks: bold/italic/underline/strikethrough/fontFamily/fontSize(points)/color(hex)/highlight), placement?, changeMode? — style cells HERE, do not format_text afterward; changeMode:"tracked" makes the table insertion itself a tracked change',
     rewrite_block: "selector, text, changeMode? — REPLACES the whole block text using the document API's formatting preservation. For appending a NEW paragraph/clause use insert_paragraphs, and for small wording edits prefer replace_text with a minimal find span",
     fill_placeholders: 'values[] and/or fields[{label?,value}], changeMode?',
-    move_range: 'fromText (text in the FIRST block of the range to move), toText? (text in the LAST block — omit to auto-extend across the whole VISUAL SECTION: from fromText up to the next heading-like/ALL-CAPS/bold title), then exactly ONE destination: afterText OR beforeText (text in the block to land after/before). Direct-only today: changeMode:"tracked" fails with no mutation because block-range deletion cannot be tracked. Moves plain paragraph/heading text only; a range containing a table, list, or image is refused with nothing changed. THE way to MOVE a contiguous block range or a visual "section" identified BY TEXT (works on styled-paragraph sections like PREAMBLE / SCHEDULE A that are NOT Word heading nodes). afterText on a heading-like block lands the range after that block\'s WHOLE section.',
+    move_range: 'fromText (text in the FIRST block of the range to move), toText? (text in the LAST block — omit to auto-extend across the whole VISUAL SECTION: from fromText up to the next heading-like/ALL-CAPS/bold title), then exactly ONE destination: afterText OR beforeText (text in the block to land after/before). changeMode:"tracked" records both the copies and source deletion for review. Moves plain paragraph/heading text only; a range containing a table, list, or image is refused with nothing changed. THE way to MOVE a contiguous block range or a visual "section" identified BY TEXT (works on styled-paragraph sections like PREAMBLE / SCHEDULE A that are NOT Word heading nodes). afterText on a heading-like block lands the range after that block\'s WHOLE section.',
     comment_paragraphs: 'commentText, scope?: all|body, excludeBlockQuotes?',
     add_comments: 'commentText, selector (one block) OR selectors[] to comment MANY blocks in ONE call (same text) — use selectors[] for "comment every heading/section/clause"; NEVER emit multiple add_comments calls, batch the targets into selectors[]',
     resolve_comments: 'anchorText? (resolve only comments anchored on text containing this; omit to resolve ALL open comments), reopen? (true = reopen resolved comments instead) — THE way to resolve (or reopen) comments. Use for "resolve the comment(s)" / "mark comments resolved".',
@@ -86,7 +87,7 @@ const ACTION_HINTS = {
     delete_table_column: 'tableOrdinal?, columnIndex, changeMode?',
     split_table: 'tableOrdinal?, rowIndex, separatorText?, changeMode?',
     convert_list: 'kind: ordered|bullet, listOrdinal? 1-based or anchorText? text inside an item of the target list, OR fromMarker+toMarker rendered clause numbers like "2.1."/"2.3." to convert a numbered-clause range, OR fromText+toText exact text inside the first/last of consecutive plain paragraphs to convert them into a list IN PLACE, changeMode? — converts lists, clause ranges, or plain paragraphs to a list without touching text; never recreate-and-delete to make existing paragraphs a list',
-    split_list: 'anchorText (text inside the item that should START the second list), restartNumbering? (default true — the new list restarts at 1; false keeps continuous numbering) — THE way to SPLIT one list into two at an item ("split the list starting at item 7 into a new list with reset numbering"). Nested sub-items stay with their parent. Direct edit (not tracked).',
+    split_list: 'anchorText (text inside the item that should START the second list), restartNumbering? (default true — the new list restarts at 1; false keeps continuous numbering) — THE way to SPLIT one list into two at an item ("split the list starting at item 7 into a new list with reset numbering"). Nested sub-items stay with their parent. changeMode? records the change for review.',
     undo_changes: 'untilMarker? rendered marker to restore e.g. "2.1.", steps? 1-25 — deterministic revert that steps document history back until the marker reappears',
     redo_changes: 'steps? 1-25 (default 1) — the inverse of undo_changes: steps history FORWARD to re-apply edits a prior undo removed. THE recovery when an undo overshot. Only works right after an undo, before any new edit.',
     attach_numbering: 'anchorText|nodeId, likeMarker e.g. "10.", changeMode? — make an existing block a numbered clause at the same scheme/level as the sibling rendering likeMarker; changeMode:"tracked" records the former unnumbered state as a w:pPrChange',
@@ -100,9 +101,9 @@ const ACTION_HINTS = {
     style_table: 'tableOrdinal? (1-based, default 1), accentColor? (header fill hex, default dark navy) — THE way to make a table look professional: filled accent header row with white bold text, bold first-column labels, banded rows, clean borders. Use after create_table or on any existing table.',
     move_table: 'tableOrdinal? (1-based, default 1), placement {at:"document_end"|"document_start"|"after"|"before", selector?} — THE way to MOVE a whole table (with all its content) to a new position IN ONE call. Use for "move the table to the end / under section X". NEVER delete-and-recreate a table to relocate it, and never chain inserts/undos to fake a move.',
     delete_table: 'tableOrdinal? (1-based, default 1), changeMode? — THE way to DELETE an entire table in one call. Use for "remove/delete the table". Do NOT delete rows one by one or hijack another table.',
-    set_paragraph_spacing: 'selector (block/blocks to space), lineSpacing? (multiplier e.g. 1.5 or 2), spaceBefore? / spaceAfter? (points) — THE way to set line spacing or space before/after paragraphs. Use this for "add spacing" / "1.5 line spacing" / "more room between paragraphs" — NEVER insert blank paragraphs for spacing. Direct edit (not tracked).',
-    insert_page_break: 'selector (block that should start on a new page) — THE way to "start X on a new page" / add a page break before a block (sets pageBreakBefore). Use instead of inserting empty paragraphs to push content down. Direct edit (not tracked).',
-    add_hyperlink: 'text (exact text to turn into a link), url, tooltip? — THE way to make existing text a clickable hyperlink to a URL. Direct edit (not tracked).',
+    set_paragraph_spacing: 'selector (block/blocks to space), lineSpacing? (multiplier e.g. 1.5 or 2), spaceBefore? / spaceAfter? (points) — THE way to set line spacing or space before/after paragraphs. Use this for "add spacing" / "1.5 line spacing" / "more room between paragraphs" — NEVER insert blank paragraphs for spacing. changeMode? records the change for review.',
+    insert_page_break: 'selector (block that should start on a new page) — THE way to "start X on a new page" / add a page break before a block (sets pageBreakBefore). Use instead of inserting empty paragraphs to push content down. changeMode? records the change for review.',
+    add_hyperlink: 'text (exact text to turn into a link), url, tooltip? — THE way to make existing text a clickable hyperlink to a URL. changeMode? records the change for review.',
 };
 /** Category grouping for the rendered tool description. Must cover ACTION_NAMES exactly (unit-tested). */
 const ACTION_GROUPS = [
@@ -197,7 +198,7 @@ const ACTION_ARGS = {
     delete_table_column: ['tableOrdinal', 'columnIndex', 'changeMode'],
     split_table: ['tableOrdinal', 'rowIndex', 'separatorText', 'changeMode'],
     convert_list: ['kind', 'fromMarker', 'toMarker', 'fromText', 'toText', 'listOrdinal', 'anchorText', 'changeMode'],
-    split_list: ['anchorText', 'restartNumbering'],
+    split_list: ['anchorText', 'restartNumbering', 'changeMode'],
     undo_changes: ['untilMarker', 'steps'],
     redo_changes: ['steps'],
     attach_numbering: ['likeMarker', 'nodeId', 'anchorText', 'changeMode'],
@@ -216,15 +217,15 @@ const ACTION_ARGS = {
         'fontSize',
         'changeMode',
     ],
-    apply_style: ['selector', 'styleId', 'headingLevel', 'likeText'],
+    apply_style: ['selector', 'styleId', 'headingLevel', 'likeText', 'changeMode'],
     format_paragraph: ['selector', 'alignment', 'changeMode', 'evidence'],
     move_text: ['text', 'afterText', 'changeMode'],
-    style_table: ['tableOrdinal', 'accentColor'],
-    move_table: ['tableOrdinal', 'placement'],
+    style_table: ['tableOrdinal', 'accentColor', 'changeMode'],
+    move_table: ['tableOrdinal', 'placement', 'changeMode'],
     delete_table: ['tableOrdinal', 'changeMode'],
-    set_paragraph_spacing: ['selector', 'lineSpacing', 'spaceBefore', 'spaceAfter'],
-    insert_page_break: ['selector'],
-    add_hyperlink: ['text', 'url', 'tooltip'],
+    set_paragraph_spacing: ['selector', 'lineSpacing', 'spaceBefore', 'spaceAfter', 'changeMode'],
+    insert_page_break: ['selector', 'changeMode'],
+    add_hyperlink: ['text', 'url', 'tooltip', 'changeMode'],
 };
 const ACTION_DISPOSITIONS = {
     insert_paragraphs: 'tracked',
@@ -245,7 +246,7 @@ const ACTION_DISPOSITIONS = {
     set_font_family: 'tracked',
     apply_letter_spacing: 'tracked',
     fill_placeholders: 'tracked',
-    move_range: 'direct',
+    move_range: 'tracked',
     insert_toc: 'tracked',
     insert_table_row: 'tracked',
     insert_table_column: 'tracked',
@@ -253,21 +254,21 @@ const ACTION_DISPOSITIONS = {
     delete_table_column: 'tracked',
     split_table: 'tracked',
     convert_list: 'tracked',
-    split_list: 'direct',
+    split_list: 'tracked',
     undo_changes: 'direct',
     redo_changes: 'direct',
     attach_numbering: 'tracked',
     add_list_items: 'tracked',
     format_text: 'tracked',
-    apply_style: 'direct',
+    apply_style: 'tracked',
     format_paragraph: 'tracked',
     move_text: 'tracked',
-    style_table: 'direct',
-    move_table: 'direct',
+    style_table: 'tracked',
+    move_table: 'tracked',
     delete_table: 'tracked',
-    set_paragraph_spacing: 'direct',
-    insert_page_break: 'direct',
-    add_hyperlink: 'direct',
+    set_paragraph_spacing: 'tracked',
+    insert_page_break: 'tracked',
+    add_hyperlink: 'tracked',
 };
 /** Fresh copy of {@link ACTION_DISPOSITIONS} for integrators (safe to mutate). */
 function getActionDispositions() {
@@ -886,14 +887,7 @@ async function executeCommentCreate(doc, snapshot, commentText, blockId) {
         target,
     });
 }
-async function applyTableCellTexts(doc, tableNodeId, tableOrdinal, cellTexts, changeMode, 
-/**
- * Force the cell fill to run as a direct edit even under `changeMode:'tracked'`.
- * Set only by the column-insert caller, whose new cells land in pre-existing
- * rows that carry no tracked-insertion marker for the adapter to absorb them
- * into. See the tracked-mode note below.
- */
-forceDirectFill = false) {
+async function applyTableCellTexts(doc, tableNodeId, tableOrdinal, cellTexts, changeMode) {
     const nonEmptyCells = cellTexts.filter((cell) => cell.text.trim().length > 0);
     if (nonEmptyCells.length === 0)
         return [];
@@ -933,19 +927,6 @@ forceDirectFill = false) {
     // block rewrite the v2 collab backend silently drops for freshly-inserted
     // cells (rows/columns land empty), so it is only a fallback for non-collab or
     // older hosts without the op.
-    //
-    // Tracked mode: the adapter accepts a tracked cell fill only where the target
-    // cell's row carries a same-author `<w:trPr><w:ins/>` marker, which already
-    // owns the accept/reject fate of everything inside it. A tracked row insert
-    // and a tracked new table both produce such rows, so their fills go through
-    // tracked and the transport now lets them reach the adapter
-    // (supportsConditionalTrackedMode, SD-4035).
-    //
-    // A tracked COLUMN insert is the exception: its new cells are added to
-    // PRE-EXISTING rows, which carry no marker, so the adapter fails closed with
-    // CAPABILITY_UNAVAILABLE and the column would land empty. Those fills stay
-    // direct — the table-level insertion still owns the redline.
-    const cellFillChangeMode = forceDirectFill && changeMode === 'tracked' ? undefined : changeMode;
     const setCellFn = maybeMethod(doc, ['tables', 'setCellText']);
     const legacySteps = [];
     const resolved = [];
@@ -964,7 +945,7 @@ forceDirectFill = false) {
                 rowIndex: cell.rowIndex,
                 columnIndex: cell.columnIndex,
                 text: cell.text,
-                ...(cellFillChangeMode ? { changeMode: cellFillChangeMode } : {}),
+                ...(changeMode ? { changeMode: changeMode } : {}),
             });
         }
         else {
@@ -977,7 +958,7 @@ forceDirectFill = false) {
         }
     }
     if (legacySteps.length > 0)
-        await executeMutations(doc, legacySteps, cellFillChangeMode);
+        await executeMutations(doc, legacySteps, changeMode);
     return resolved;
 }
 /**
@@ -2242,7 +2223,7 @@ async function runAddListItems(doc, args, opts) {
  * split_list — split one list into two at a target item, restarting the new
  * half's numbering (default). Thin wrapper over doc.lists.split (separate +
  * setValue). The split point is the item that should START the second list,
- * located by anchorText. Direct-only: lists.split rejects tracked mode.
+ * located by anchorText.
  */
 async function runSplitList(doc, args) {
     const pre = await docSnapshot.buildDocumentSnapshot(doc, { includeDomains: ['blocks', 'lists'] });
@@ -4317,9 +4298,7 @@ async function runInsertTableColumn(doc, args) {
             columnCells = [{ rowIndex: 0, columnIndex: newColumnIndex, text: args.headerText }];
         }
         if (columnCells.length > 0) {
-            // forceDirectFill: a new column's cells live in pre-existing rows, which
-            // carry no tracked-insertion marker, so a tracked fill fails closed.
-            const applied = await applyTableCellTexts(doc, table.nodeId, table.ordinal, columnCells, args.changeMode, true);
+            const applied = await applyTableCellTexts(doc, table.nodeId, table.ordinal, columnCells, args.changeMode);
             if (applied.length > 0) {
                 executed.push({
                     operationId: 'doc.mutations.apply',
@@ -5933,13 +5912,14 @@ function indentsEqual(a, b) {
 }
 async function matchOneBlock(doc, postBlocks, preIds, created, createdIndex, anchorRow, allowNumberingAttach, isTitle = false, allowLeadPattern = true, createdText = '') {
     try {
-        // Reference: placement anchor first, then nearest same-type sibling
-        // (previous preferred), skipping empties and other fresh blocks.
-        let reference = anchorRow && !anchorRow.isEmpty ? anchorRow : null;
+        // A requested heading level constrains style matching, including explicit
+        // placement anchors: copying another level would change document structure.
+        const compatibleHeading = (row) => created.headingLevel == null || row.headingLevel === created.headingLevel;
+        let reference = anchorRow && !anchorRow.isEmpty && compatibleHeading(anchorRow) ? anchorRow : null;
         if (!reference) {
             for (let i = createdIndex - 1; i >= 0; i--) {
                 const b = postBlocks[i];
-                if (preIds.has(b.nodeId) && b.nodeType === created.nodeType && !b.isEmpty) {
+                if (preIds.has(b.nodeId) && b.nodeType === created.nodeType && !b.isEmpty && compatibleHeading(b)) {
                     reference = b;
                     break;
                 }
@@ -5948,7 +5928,7 @@ async function matchOneBlock(doc, postBlocks, preIds, created, createdIndex, anc
         if (!reference) {
             for (let i = createdIndex + 1; i < postBlocks.length; i++) {
                 const b = postBlocks[i];
-                if (preIds.has(b.nodeId) && b.nodeType === created.nodeType && !b.isEmpty) {
+                if (preIds.has(b.nodeId) && b.nodeType === created.nodeType && !b.isEmpty && compatibleHeading(b)) {
                     reference = b;
                     break;
                 }
@@ -5983,11 +5963,28 @@ async function matchOneBlock(doc, postBlocks, preIds, created, createdIndex, anc
         if (reference.styleId && reference.styleId !== created.styleId) {
             const setStyleFn = maybeMethod(doc, ['styles', 'paragraph', 'setStyle']);
             if (setStyleFn) {
-                await setStyleFn({
-                    target: { kind: 'block', nodeType: created.nodeType, nodeId: created.nodeId },
-                    styleId: reference.styleId,
-                });
-                applied.styleId = reference.styleId;
+                const target = { kind: 'block', nodeType: created.nodeType, nodeId: created.nodeId };
+                let canCopyStyle = true;
+                if (created.headingLevel != null) {
+                    // The reference's effective level can come from a direct outline
+                    // override that its style does not contain. Preserve it before copying.
+                    const setOutlineFn = maybeMethod(doc, ['format', 'paragraph', 'setOutlineLevel']);
+                    if (!setOutlineFn) {
+                        canCopyStyle = false;
+                        applied.styleSkipped = 'Heading outline preservation is unavailable.';
+                    }
+                    else {
+                        const result = asRecord(await setOutlineFn({ target, outlineLevel: created.headingLevel - 1 }));
+                        if (result?.success === false) {
+                            canCopyStyle = false;
+                            applied.styleSkipped = 'Heading outline preservation failed.';
+                        }
+                    }
+                }
+                if (canCopyStyle) {
+                    await setStyleFn({ target, styleId: reference.styleId });
+                    applied.styleId = reference.styleId;
+                }
             }
         }
         // Same "inline look" the style-copy paths use, minus properties the
@@ -7161,7 +7158,8 @@ function parseExactTrackedChangeIdList(value) {
 }
 async function superdocPerformAction(doc, args) {
     try {
-        return await dispatchSuperdocPerformAction(doc, args);
+        const changeMode = isRecord(args) ? parseChangeMode(args.changeMode) : undefined;
+        return await dispatchSuperdocPerformAction(changeMode ? actionChangeMode.bindActionChangeMode(doc, changeMode) : doc, args);
     }
     catch (error) {
         if (!(error instanceof docSnapshot.MutationSnapshotError))
@@ -7180,7 +7178,9 @@ async function superdocPerformAction(doc, args) {
 function parseChangeMode(value) {
     if (value === 'direct' || value === 'tracked')
         return value;
-    return undefined;
+    if (value === undefined)
+        return undefined;
+    throw new errors.SuperDocCliError('changeMode must be direct or tracked.', { code: 'INVALID_ARGUMENT' });
 }
 function parseReplaceTextChangeMode(value) {
     if (value === undefined)

package/dist/agent/actions.d.ts

@@ -284,6 +284,7 @@ export type InsertTocArgs = {
     changeMode?: AgentChangeMode;
 };
 export type StyleTableArgs = {
+    changeMode?: AgentChangeMode;
     action: 'style_table';
     /** 1-based table ordinal (default 1). */
     tableOrdinal: number;
@@ -291,6 +292,7 @@ export type StyleTableArgs = {
     accentColor?: string;
 };
 export type MoveTableArgs = {
+    changeMode?: AgentChangeMode;
     action: 'move_table';
     /** 1-based table ordinal to move (default 1). */
     tableOrdinal?: number;
@@ -362,6 +364,7 @@ export type RedoChangesArgs = {
     steps?: number;
 };
 export type SplitListArgs = {
+    changeMode?: AgentChangeMode;
     action: 'split_list';
     /** Text inside the list item that should START the new (second) list. */
     anchorText: string;
@@ -375,6 +378,7 @@ export type AttachNumberingArgs = {
     likeMarker: string;
 };
 export type ApplyStyleArgs = {
+    changeMode?: AgentChangeMode;
     action: 'apply_style';
     /** Block to restyle. */
     selector: AgentSelector;
@@ -437,13 +441,9 @@ export declare const ACTION_ARGS: Record<ActionName, readonly string[]>;
  * What an action does with `changeMode`.
  *
  * - `tracked`: honors `changeMode: "tracked"` and records a reviewable tracked
- *   change (a multi-step action may run a bookkeeping step directly on purpose —
- *   insert_table_column fills the new cells directly so a column shows up as ONE
- *   Word-style tracked change, not one per cell).
- * - `direct`: edits the document directly whatever `changeMode` says. Either the
- *   action never reads the argument (apply_style, insert_page_break, …), the
- *   engine refuses the tracked form (move_range), or the action is a review /
- *   comment operation that has no tracked form by nature.
+ *   change.
+ * - `direct`: performs a review, comment, or history operation that does not
+ *   create a tracked document edit.
  *
  * Source of truth for the tracked-only agent policy (`enforceChangeMode`):
  * `direct` actions are hidden and refused unless a host allowlists them.
@@ -482,6 +482,7 @@ export type MoveTextArgs = {
     changeMode?: AgentChangeMode;
 };
 export type SetParagraphSpacingArgs = {
+    changeMode?: AgentChangeMode;
     action: 'set_paragraph_spacing';
     selector: AgentSelector;
     /** Line-spacing multiplier (1, 1.5, 2). */
@@ -492,10 +493,12 @@ export type SetParagraphSpacingArgs = {
     spaceAfter?: number;
 };
 export type InsertPageBreakArgs = {
+    changeMode?: AgentChangeMode;
     action: 'insert_page_break';
     selector: AgentSelector;
 };
 export type AddHyperlinkArgs = {
+    changeMode?: AgentChangeMode;
     action: 'add_hyperlink';
     /** Exact text to turn into a hyperlink. */
     text: string;