mcp-word-bridge 3.5.2 → 3.5.3

package/README.md

@@ -80,7 +80,7 @@ mcp-word-bridge/
 └── README.md
 ```
 
-## Tools (91)
+## Tools (92)
 
 ### Document
 | Tool | Description |
@@ -107,6 +107,7 @@ mcp-word-bridge/
 | `word_delete_paragraph` | Delete a paragraph by index |
 | `word_replace_paragraph_text` | Replace paragraph text by index (preserves style) |
 | `word_move_paragraph` | Move one or more consecutive paragraphs to another position |
+| `word_copy_paragraph` | Copy one or more consecutive paragraphs to another position |
 | `word_set_paragraph_style` | Change style or alignment of a paragraph |
 | `word_set_paragraph_spacing` | Set line spacing, before/after, and indentation |
 

package/index.js

@@ -148,7 +148,7 @@ function sendToTaskpane(action, params) {
 }
 
 const mcpServer = new Server(
-  { name: 'mcp-word-bridge', version: '3.5.2' },
+  { name: 'mcp-word-bridge', version: '3.5.3' },
   { capabilities: { tools: {}, resources: {} } }
 );
 
@@ -177,16 +177,19 @@ async function executeTool(name, args) {
       await sendToTaskpane('insertOoxml', { ooxml, location: args.location || 'End' });
     } else if (args.anchorText) {
       // Inline mode with anchor: search for anchor text, insert space+marker after it, insert equation at cursor, clean up marker
-      const marker = '\u200B\uFEFF'; // unique two-char sequence unlikely to exist in normal text
+      const marker = '\u200B\uFEFF\u200B'; // three-char zero-width sequence — virtually impossible in real documents
       const searchResult = await sendToTaskpane('search', { query: args.anchorText, matchCase: args.matchCase || false });
       if (!searchResult || searchResult.count === 0) throw new Error('Anchor not found: ' + args.anchorText);
       const occurrence = args.occurrence || 0;
       if (occurrence >= searchResult.count) throw new Error('Occurrence ' + occurrence + ' not found (only ' + searchResult.count + ' match' + (searchResult.count === 1 ? '' : 'es') + ')');
       // Insert space + marker to position cursor (space ensures equation doesn't glue to preceding text)
       await sendToTaskpane('insertText', { text: ' ' + marker, after: args.anchorText, occurrence: occurrence, matchCase: args.matchCase || false });
-      await sendToTaskpane('insertOoxmlAtSelection', { ooxml });
-      // Clean up the marker (space remains, giving proper separation)
-      await sendToTaskpane('searchAndReplace', { find: marker, replace: '' });
+      try {
+        await sendToTaskpane('insertOoxmlAtSelection', { ooxml });
+      } finally {
+        // Always clean up the marker, even if equation insertion fails
+        await sendToTaskpane('searchAndReplace', { find: marker, replace: '' });
+      }
     } else {
       await sendToTaskpane('insertOoxmlAtSelection', { ooxml });
     }
@@ -199,18 +202,25 @@ async function executeTool(name, args) {
     const result = await sendToTaskpane('getParagraphs', {});
     const headings = [];
     for (const para of result.paragraphs) {
+      // Skip TOC entries — they duplicate real headings
+      if (para.isTocEntry) continue;
+      let level = null;
+      // Primary: match style name "Heading N"
       const match = para.style && para.style.match(/^Heading (\d)$/i);
       if (match) {
-        const level = parseInt(match[1], 10);
-        if (level <= maxLevel) {
-          headings.push({ level, text: para.text, index: para.index });
-        }
+        level = parseInt(match[1], 10);
+      } else if (para.outlineLevel !== undefined && para.outlineLevel >= 1 && para.outlineLevel <= 9) {
+        // Fallback: use outlineLevel when style is empty or unrecognized (e.g. after TOC insertion)
+        level = para.outlineLevel;
+      }
+      if (level !== null && level <= maxLevel) {
+        headings.push({ level, text: para.text, index: para.index });
       }
     }
     return { content: [{ type: 'text', text: JSON.stringify({ count: headings.length, outline: headings }, null, 2) }] };
   }
 
-  // word_move_paragraph: atomic move (read text+style, delete, insert at new position)
+  // word_move_paragraph: OOXML round-trip move (preserves all rich content: footnotes, hyperlinks, formatting, images, comments)
   // Supports moving multiple consecutive paragraphs via optional 'count' parameter
   if (name === 'word_move_paragraph') {
     const fromIndex = args.fromIndex;
@@ -231,58 +241,55 @@ async function executeTool(name, args) {
     if (fromIndex >= total) throw new Error('fromIndex ' + fromIndex + ' out of range. Document has ' + total + ' paragraphs (0-indexed).');
     if (fromIndex + count - 1 >= total) throw new Error('fromIndex + count (' + (fromIndex + count) + ') exceeds paragraph count (' + total + ').');
     if (toIndex >= total) throw new Error('toIndex ' + toIndex + ' out of range. Document has ' + total + ' paragraphs (0-indexed).');
-    // Collect all paragraphs to move (text + style + formatting)
-    const collected = [];
-    for (let i = 0; i < count; i++) {
-      const details = await sendToTaskpane('getParagraphByIndex', { index: fromIndex + i });
-      collected.push({
-        text: details.text, style: details.style, alignment: details.alignment,
-        firstLineIndent: details.firstLineIndent, leftIndent: details.leftIndent,
-        rightIndent: details.rightIndent, lineSpacing: details.lineSpacing,
-        spaceBefore: details.spaceBefore, spaceAfter: details.spaceAfter
-      });
-    }
-    // Delete from last to first to preserve indices during deletion
+    // Step 1: Capture full OOXML of source paragraphs (preserves everything)
+    const ooxmlResult = await sendToTaskpane('getParaOoxml', { index: fromIndex, count: count });
+    const savedOoxml = ooxmlResult.ooxml;
+    // Step 2: Delete source paragraphs (last to first to preserve indices)
     for (let i = count - 1; i >= 0; i--) {
       await sendToTaskpane('deleteParagraph', { index: fromIndex + i });
     }
-    // Adjust destination index after deletions
+    // Step 3: Adjust destination index after deletions (same arithmetic as before)
     let adjustedTo;
     if (fromIndex < toIndex) {
       adjustedTo = toIndex - count;
     } else {
       adjustedTo = toIndex;
     }
-    // Insert in order at destination, then restore formatting
-    for (let i = 0; i < collected.length; i++) {
-      let insertedAt;
-      if (i === 0) {
-        await sendToTaskpane('insertParagraphAtIndex', { index: adjustedTo, text: collected[i].text, style: collected[i].style, location: location });
-        insertedAt = location === 'Before' ? adjustedTo : adjustedTo + 1;
-      } else {
-        // After the first insert, the paragraph we just inserted is at a known position.
-        // For 'Before': first para went to adjustedTo, so second goes After adjustedTo.
-        // For 'After': first para went to adjustedTo+1, so second goes After adjustedTo+1.
-        const prevInsertedAt = location === 'Before' ? adjustedTo + (i - 1) : adjustedTo + i;
-        await sendToTaskpane('insertParagraphAtIndex', { index: prevInsertedAt, text: collected[i].text, style: collected[i].style, location: 'After' });
-        insertedAt = prevInsertedAt + 1;
-      }
-      // Restore alignment if non-default
-      const c = collected[i];
-      if (c.alignment && c.alignment !== 'Left') {
-        await sendToTaskpane('setParagraphStyle', { index: insertedAt, alignment: c.alignment });
-      }
-      // Restore spacing/indentation if non-default
-      const spacingArgs = { index: insertedAt };
-      let hasSpacing = false;
-      if (c.firstLineIndent && c.firstLineIndent !== 0) { spacingArgs.firstLineIndent = c.firstLineIndent; hasSpacing = true; }
-      if (c.leftIndent && c.leftIndent !== 0) { spacingArgs.leftIndent = c.leftIndent; hasSpacing = true; }
-      if (c.rightIndent && c.rightIndent !== 0) { spacingArgs.rightIndent = c.rightIndent; hasSpacing = true; }
-      if (hasSpacing) {
-        await sendToTaskpane('setParagraphSpacing', spacingArgs);
+    // Step 4: Insert OOXML at destination (with restore-on-failure)
+    try {
+      await sendToTaskpane('insertOoxmlAtIndex', { ooxml: savedOoxml, index: adjustedTo, location: location });
+    } catch (insertErr) {
+      // Restore at original position on failure
+      try {
+        await sendToTaskpane('insertOoxmlAtIndex', { ooxml: savedOoxml, index: Math.min(fromIndex, adjustedTo), location: 'Before' });
+      } catch (_restoreErr) {
+        throw new Error('Move failed AND restore failed: ' + insertErr.message + '. Use Ctrl+Z to recover.');
       }
+      throw new Error('Move failed (content restored to original position): ' + insertErr.message);
     }
-    return { content: [{ type: 'text', text: JSON.stringify({ success: true, moved: { from: fromIndex, count, to: adjustedTo, location } }) }] };
+    return { content: [{ type: 'text', text: JSON.stringify({ success: true, moved: { from: fromIndex, count, to: adjustedTo, toIndexRequested: toIndex, location } }) }] };
+  }
+
+  // word_copy_paragraph: OOXML round-trip copy (preserves all rich content)
+  if (name === 'word_copy_paragraph') {
+    const fromIndex = args.fromIndex;
+    const toIndex = args.toIndex;
+    const count = args.count || 1;
+    const location = args.location || 'After';
+    if (fromIndex < 0) throw new Error('fromIndex must be non-negative');
+    if (toIndex < 0) throw new Error('toIndex must be non-negative');
+    if (count < 1) throw new Error('count must be at least 1');
+    // Validate all indices are in bounds
+    const paraCount = await sendToTaskpane('getParagraphs', {});
+    const total = paraCount.count;
+    if (fromIndex >= total) throw new Error('fromIndex ' + fromIndex + ' out of range. Document has ' + total + ' paragraphs (0-indexed).');
+    if (fromIndex + count - 1 >= total) throw new Error('fromIndex + count (' + (fromIndex + count) + ') exceeds paragraph count (' + total + ').');
+    if (toIndex >= total) throw new Error('toIndex ' + toIndex + ' out of range. Document has ' + total + ' paragraphs (0-indexed).');
+    // Step 1: Capture full OOXML of source paragraphs
+    const ooxmlResult = await sendToTaskpane('getParaOoxml', { index: fromIndex, count: count });
+    // Step 2: Insert OOXML at destination (no delete — it's a copy)
+    await sendToTaskpane('insertOoxmlAtIndex', { ooxml: ooxmlResult.ooxml, index: toIndex, location: location });
+    return { content: [{ type: 'text', text: JSON.stringify({ success: true, copied: { from: fromIndex, count, to: toIndex, location } }) }] };
   }
 
   // word_batch: execute multiple operations in a single call
@@ -296,7 +303,7 @@ async function executeTool(name, args) {
     }
 
     // Partition into taskpane-native ops (have action mapping) vs server-composed ops
-    const SERVER_HANDLED = new Set(['word_insert_equation', 'word_batch', 'word_get_document_outline', 'word_move_paragraph']);
+    const SERVER_HANDLED = new Set(['word_insert_equation', 'word_batch', 'word_get_document_outline', 'word_move_paragraph', 'word_copy_paragraph']);
     const results = [];
 
     // Collect consecutive taskpane-native ops into batches, flush when hitting a server op

package/lib/tools.js

@@ -23,7 +23,8 @@ const tools = [
   { name: 'word_insert_paragraph_at_index', description: '[Paragraphs] Insert a new paragraph Before or After a specific paragraph index. Use this for precise positioning within the document (preferred over word_insert_paragraph for mid-document insertions).', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Reference paragraph index (0-based)' }, text: { type: 'string', description: 'Text content for the new paragraph' }, location: { type: 'string', enum: ['Before', 'After'], description: 'Insert before or after the reference paragraph. Default: After' }, style: { type: 'string', description: 'Paragraph style (e.g. "Heading 1", "Normal")' }, alignment: { type: 'string', description: 'Paragraph alignment: Left, Center, Right, or Justified' } }, required: ['index', 'text'] } },
   { name: 'word_delete_paragraph', description: '[Paragraphs] Delete a paragraph by its 0-based index.', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Paragraph index (0-based)' } }, required: ['index'] } },
   { name: 'word_replace_paragraph_text', description: '[Paragraphs] Replace the entire text of a paragraph by index. Preserves style/formatting. Preferred over word_search_and_replace in collaborative editing (targets by position, immune to text-drift).', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Paragraph index (0-based)' }, text: { type: 'string', description: 'New text content for the paragraph' } }, required: ['index', 'text'] } },
-  { name: 'word_move_paragraph', description: '[Paragraphs] Move a paragraph from one position to another. Handles the delete+insert atomically with correct index adjustment.', inputSchema: { type: 'object', properties: { fromIndex: { type: 'number', description: 'Source paragraph index (0-based)' }, toIndex: { type: 'number', description: 'Destination paragraph index (0-based, position after removal)' }, location: { type: 'string', enum: ['Before', 'After'], description: 'Insert before or after the destination index. Default: After' }, count: { type: 'number', description: 'Number of consecutive paragraphs to move (default: 1). Use to move a heading + its body together.' } }, required: ['fromIndex', 'toIndex'] } },
+  { name: 'word_move_paragraph', description: '[Paragraphs] Move a paragraph from one position to another. Preserves all rich content including footnotes, hyperlinks, formatting, images, and comments.', inputSchema: { type: 'object', properties: { fromIndex: { type: 'number', description: 'Source paragraph index (0-based)' }, toIndex: { type: 'number', description: 'Destination paragraph index (0-based, position after removal)' }, location: { type: 'string', enum: ['Before', 'After'], description: 'Insert before or after the destination index. Default: After' }, count: { type: 'number', description: 'Number of consecutive paragraphs to move (default: 1). Use to move a heading + its body together.' } }, required: ['fromIndex', 'toIndex'] } },
+  { name: 'word_copy_paragraph', description: '[Paragraphs] Copy paragraph(s) to another position. Preserves all rich content including footnotes, hyperlinks, formatting, images, and comments. Source remains unchanged.', inputSchema: { type: 'object', properties: { fromIndex: { type: 'number', description: 'Source paragraph index (0-based)' }, toIndex: { type: 'number', description: 'Destination paragraph index (0-based)' }, location: { type: 'string', enum: ['Before', 'After'], description: 'Insert before or after the destination index. Default: After' }, count: { type: 'number', description: 'Number of consecutive paragraphs to copy (default: 1). Use to copy a heading + its body together.' } }, required: ['fromIndex', 'toIndex'] } },
   { name: 'word_set_paragraph_style', description: '[Paragraphs] Change the style or alignment of a paragraph by index. Alignment accepts: Left, Center, Right, Justified.', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Paragraph index (0-based)' }, style: { type: 'string' }, alignment: { type: 'string', description: 'Paragraph alignment: Left, Center, Right, or Justified' } }, required: ['index'] } },
   { name: 'word_set_paragraph_spacing', description: '[Paragraphs] Set line spacing (in points: 12=single for 12pt font, 18=1.5x, 24=double), before/after spacing, and indentation on a paragraph by index.', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Paragraph index (0-based)' }, lineSpacing: { type: 'number', description: 'Line spacing in points (e.g. 12=single for 12pt, 18=1.5x, 24=double)' }, spaceBefore: { type: 'number', description: 'Space before paragraph in points' }, spaceAfter: { type: 'number', description: 'Space after paragraph in points' }, firstLineIndent: { type: 'number', description: 'First line indent in points' }, leftIndent: { type: 'number', description: 'Left indent in points' }, rightIndent: { type: 'number', description: 'Right indent in points' } }, required: ['index'] } },
   // 3. SEARCH & TEXT
@@ -113,7 +114,7 @@ const tools = [
   // 18. EQUATIONS
   { name: 'word_insert_equation', description: '[Equations] Insert a LaTeX math equation as a native editable Word equation. Supports fractions, roots, integrals, matrices, Greek letters, and all standard LaTeX math. Display mode (default) inserts a centered block equation. Inline mode inserts after a search match (provide anchorText) or at cursor position.', inputSchema: { type: 'object', properties: { latex: { type: 'string', description: 'LaTeX math expression (e.g. "\\\\frac{a}{b}", "\\\\int_0^\\\\infty e^{-x} dx")' }, displayMode: { type: 'boolean', description: 'true (default) = centered block equation, false = inline equation' }, location: { type: 'string', enum: ['Start', 'End'], description: 'Where to insert display-mode equations. Default: End' }, anchorText: { type: 'string', description: 'For inline mode: search for this text and insert equation after it (avoids manual cursor positioning)' }, occurrence: { type: 'number', description: 'Which anchorText match to target: 0=first, 1=second, etc. Default: 0' }, matchCase: { type: 'boolean', description: 'Case-sensitive anchor matching. Default: false' } }, required: ['latex'] } },
   // 19. BATCH OPERATIONS
-  { name: 'word_batch', description: '[Batch] Execute multiple operations in a single call to reduce round-trips. Each operation is a tool call object with "tool" and "args" fields. Operations execute sequentially — if one fails, subsequent operations are skipped. Returns results array with success/error for each operation. Consecutive native operations are sent to Word in one message for maximum speed.', inputSchema: { type: 'object', properties: { operations: { type: 'array', items: { type: 'object', properties: { tool: { type: 'string', description: 'Tool name (e.g. "word_insert_paragraph")' }, args: { type: 'object', description: 'Arguments for the tool' } }, required: ['tool'] }, description: 'Array of {tool, args} objects to execute sequentially' } }, required: ['operations'] } },
+  { name: 'word_batch', description: '[Batch] Execute multiple operations in a single call. Each operation is a tool call object with "tool" and "args" fields. Operations execute sequentially — if one fails, subsequent operations are skipped. Returns results array with success/error for each operation.', inputSchema: { type: 'object', properties: { operations: { type: 'array', items: { type: 'object', properties: { tool: { type: 'string', description: 'Tool name (e.g. "word_insert_paragraph")' }, args: { type: 'object', description: 'Arguments for the tool' } }, required: ['tool'] }, description: 'Array of {tool, args} objects to execute sequentially' } }, required: ['operations'] } },
 ];
 
 const toolActionMap = {
@@ -163,7 +164,7 @@ const toolActionMap = {
   word_insert_html: 'insertHtml', word_insert_ooxml: 'insertOoxml',
   word_insert_table_of_contents: 'insertTableOfContents', word_get_fields: 'getFields',
   word_get_page_info: 'getPageInfo',
-  // word_insert_equation, word_batch, word_get_document_outline, word_move_paragraph
+  // word_insert_equation, word_batch, word_get_document_outline, word_move_paragraph, word_copy_paragraph
   // are handled directly in index.js (not via taskpane action map)
 };
 

package/lib/usage-guide.js

@@ -47,7 +47,7 @@ Controls a live Word document through an Office Add-in. All operations execute i
 \`\`\`
 Operations run sequentially. If one fails, the rest are skipped. Maximum 50 per batch.
 
-**Performance:** Consecutive standard operations (paragraphs, search, formatting, tables, etc.) are bundled into a single WebSocket message to Word — executing in one round-trip instead of one per operation. Only server-composed tools (equations, outline, move_paragraph) break the batch into segments.
+**Performance:** Batching is significantly faster than individual calls — use it whenever you have multiple operations to perform.
 
 ## Search Behavior (applies to ALL search-based tools)
 - Case-insensitive by default. Pass \`matchCase: true\` for exact case match.
@@ -116,7 +116,7 @@ After inserting a Table of Contents, heading text appears twice in the document
 - "Word taskpane not connected" — user must open the MCP Word Bridge add-in in Word
 - "Anchor not found" — search text not found in document
 - "Occurrence N not found" — match index out of range
-- Timeout: 30s default, 60s for HTML/OOXML/styles/TOC insertion
+- Operations on large documents or complex content (HTML, OOXML, TOC) may take longer
 
 ## Best Practices
 1. Start with \`word_get_document_outline\` to understand structure
@@ -129,6 +129,7 @@ After inserting a Table of Contents, heading text appears twice in the document
 6. \`word_save\` explicitly after significant changes
 7. Resolve comments rather than deleting them (preserves audit trail)
 8. Use \`word_move_paragraph\` to reorder content (avoids index-shifting bugs with manual delete+insert)
+9. Use \`word_copy_paragraph\` to duplicate content with full fidelity (footnotes, formatting, hyperlinks preserved)
 `;
 
 module.exports = USAGE_GUIDE;

package/manifest.xml

@@ -3,7 +3,7 @@
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:type="TaskPaneApp">
   <Id>a1b2c3d4-e5f6-7890-abcd-ef1234567890</Id>
-  <Version>3.5.2</Version>
+  <Version>3.5.3</Version>
   <ProviderName>Leonid Mokrushin</ProviderName>
   <DefaultLocale>en-US</DefaultLocale>
   <DisplayName DefaultValue="MCP Word Bridge"/>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-word-bridge",
-  "version": "3.5.2",
+  "version": "3.5.3",
   "description": "MCP server for live Word document editing via Office Add-in",
   "main": "index.js",
   "bin": {

package/taskpane-app.js

@@ -70,6 +70,13 @@ async function handleCommand(cmd) {
 // --- Command registry ---
 const commands = {};
 
+// Helper: validate search string length (Word's limit is ~255 characters)
+function checkSearchLength(text) {
+  if (text && text.length > 255) {
+    throw new Error('Search text is too long (max ~255 characters). Shorten the text or use a substring.');
+  }
+}
+
 // == BATCH EXECUTION (runs multiple actions in one WebSocket message) ==
 commands.batchExecute = async (p) => {
   if (!p.operations || !Array.isArray(p.operations) || p.operations.length === 0) {
@@ -179,11 +186,11 @@ commands.getParagraphs = (p) => Word.run(async (ctx) => {
   // If merged cells cause a failure, fall back to loading without it
   let hasTableInfo = true;
   try {
-    paragraphs.load('text,style,alignment,firstLineIndent,leftIndent,lineSpacing,isListItem,parentTableCellOrNullObject');
+    paragraphs.load('text,style,alignment,firstLineIndent,leftIndent,lineSpacing,isListItem,outlineLevel,parentTableCellOrNullObject');
     await ctx.sync();
   } catch (_e) {
     hasTableInfo = false;
-    paragraphs.load('text,style,alignment,firstLineIndent,leftIndent,lineSpacing,isListItem');
+    paragraphs.load('text,style,alignment,firstLineIndent,leftIndent,lineSpacing,isListItem,outlineLevel');
     await ctx.sync();
   }
   const start = p.start !== undefined ? p.start : 0;
@@ -197,9 +204,13 @@ commands.getParagraphs = (p) => Word.run(async (ctx) => {
       try { inTable = para.parentTableCellOrNullObject && !para.parentTableCellOrNullObject.isNullObject; } catch (_e) { inTable = false; }
     }
     const isTocEntry = !!(para.style && para.style.startsWith('TOC')) || (para.style === '' && /\t\d+$/.test(para.text));
-    items.push({ index: i, text: para.text, style: para.style, alignment: para.alignment, isListItem: para.isListItem, inTable: inTable, isTocEntry: isTocEntry });
+    items.push({ index: i, text: para.text, style: para.style, alignment: para.alignment, isListItem: para.isListItem, inTable: inTable, isTocEntry: isTocEntry, outlineLevel: para.outlineLevel });
   }
-  return { count: paragraphs.items.length, paragraphs: items };
+  const result = { count: paragraphs.items.length, paragraphs: items };
+  if (p.start !== undefined && p.start >= paragraphs.items.length) {
+    result.warning = 'start index (' + p.start + ') is beyond the last paragraph. Document has ' + paragraphs.items.length + ' paragraphs (valid indices: 0-' + (paragraphs.items.length - 1) + ').';
+  }
+  return result;
 });
 
 commands.insertParagraph = (p) => Word.run(async (ctx) => {
@@ -351,6 +362,7 @@ commands.search = (p) => Word.run(async (ctx) => {
 
 commands.searchAndReplace = (p) => Word.run(async (ctx) => {
   if (!p.find || typeof p.find !== 'string' || p.find.trim() === '') throw new Error('find string cannot be empty. Provide a non-empty search string.');
+  checkSearchLength(p.find);
   const results = ctx.document.body.search(p.find, { matchCase: p.matchCase || false, matchWholeWord: p.matchWholeWord || false });
   results.load('text');
   await ctx.sync();
@@ -372,6 +384,7 @@ commands.insertText = (p) => Word.run(async (ctx) => {
   if (p.occurrence !== undefined && p.occurrence < 0) throw new Error('occurrence must be non-negative (0-indexed)');
   const anchor = p.after || p.before;
   if (!anchor) throw new Error('Either "after" or "before" anchor text must be provided');
+  checkSearchLength(anchor);
   const results = ctx.document.body.search(anchor, { matchCase: p.matchCase || false });
   results.load('text');
   await ctx.sync();
@@ -393,6 +406,7 @@ commands.formatRange = (p) => Word.run(async (ctx) => {
   if (p.size !== undefined && p.size <= 0) throw new Error('size must be positive');
   if (p.size !== undefined && p.size > 1638) throw new Error('size must not exceed 1638 points (Word maximum)');
   if (p.color && !/^#[0-9A-Fa-f]{6}$/.test(p.color)) throw new Error('color must be a valid hex color (e.g. #FF0000)');
+  checkSearchLength(p.text);
   const results = ctx.document.body.search(p.text, { matchCase: p.matchCase || false });
   results.load('font');
   await ctx.sync();
@@ -541,6 +555,7 @@ commands.insertList = (p) => Word.run(async (ctx) => {
     if (firstPara.isListItem) {
       const sep = body.insertParagraph('', 'Start');
       sep.style = 'Normal';
+      sep.detachFromList();
       await ctx.sync();
     }
   }
@@ -569,6 +584,7 @@ commands.addComment = (p) => Word.run(async (ctx) => {
   if (p.occurrence !== undefined && p.occurrence < 0) throw new Error('occurrence must be non-negative (0-indexed)');
   if (!p.comment || typeof p.comment !== 'string' || p.comment.trim() === '') throw new Error('comment text must be a non-empty string');
   if (!p.anchorText || typeof p.anchorText !== 'string' || p.anchorText.trim() === '') throw new Error('anchorText cannot be empty. Provide a non-empty search string.');
+  checkSearchLength(p.anchorText);
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
   await ctx.sync();
@@ -635,6 +651,7 @@ commands.deleteComment = (p) => Word.run(async (ctx) => {
 commands.insertFootnote = (p) => Word.run(async (ctx) => {
   if (!p.text || typeof p.text !== 'string' || p.text.trim() === '') throw new Error('Footnote text must be a non-empty string');
   if (!p.anchorText || typeof p.anchorText !== 'string' || p.anchorText.trim() === '') throw new Error('anchorText cannot be empty. Provide a non-empty search string.');
+  checkSearchLength(p.anchorText);
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
   await ctx.sync();
@@ -651,6 +668,7 @@ commands.insertFootnote = (p) => Word.run(async (ctx) => {
 commands.insertEndnote = (p) => Word.run(async (ctx) => {
   if (!p.text || typeof p.text !== 'string' || p.text.trim() === '') throw new Error('Endnote text must be a non-empty string');
   if (!p.anchorText || typeof p.anchorText !== 'string' || p.anchorText.trim() === '') throw new Error('anchorText cannot be empty. Provide a non-empty search string.');
+  checkSearchLength(p.anchorText);
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
   await ctx.sync();
@@ -876,6 +894,7 @@ commands.insertBookmark = (p) => Word.run(async (ctx) => {
   if (!p.anchorText || typeof p.anchorText !== 'string' || p.anchorText.trim() === '') throw new Error('anchorText cannot be empty. Provide a non-empty search string.');
   if (!p.name || typeof p.name !== 'string' || p.name.trim() === '') throw new Error('Bookmark name must be a non-empty string.');
   if (!/^[A-Za-z_]\w*$/.test(p.name)) throw new Error('Invalid bookmark name: "' + p.name + '". Names must start with a letter or underscore and contain only letters, numbers, and underscores (no spaces).');
+  checkSearchLength(p.anchorText);
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
   // Check for existing bookmark with same name
@@ -1052,6 +1071,7 @@ commands.insertHyperlink = (p) => Word.run(async (ctx) => {
   // Reject URLs containing characters that must be percent-encoded (RFC 3986 unsafe chars)
   if (/[<>"{}|\\^`]/.test(p.url)) throw new Error('Malformed URL: "' + p.url + '". URL contains invalid characters that must be percent-encoded.');
   if (!p.anchorText || typeof p.anchorText !== 'string' || p.anchorText.trim() === '') throw new Error('anchorText cannot be empty. Provide a non-empty search string.');
+  checkSearchLength(p.anchorText);
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
   await ctx.sync();
@@ -1068,9 +1088,20 @@ commands.insertHyperlink = (p) => Word.run(async (ctx) => {
 // == FIELDS ==
 commands.getFields = () => Word.run(async (ctx) => {
   const fields = ctx.document.body.fields;
-  fields.load('code,result,type');
+  fields.load('code,type');
+  await ctx.sync();
+  const items = [];
+  for (let i = 0; i < fields.items.length; i++) {
+    const f = fields.items[i];
+    f.result.load('text');
+  }
   await ctx.sync();
-  const items = fields.items.map((f, i) => ({ index: i, code: (f.code || '').replace(/[\u0001\u0013\u0014\u0015]/g, '').trim(), result: f.result, type: f.type }));
+  for (let i = 0; i < fields.items.length; i++) {
+    const f = fields.items[i];
+    const code = (f.code || '').replace(/[\u0001\u0013\u0014\u0015]/g, '').trim();
+    const resultText = (f.result.text || '').replace(/[\u0001\u0002\u0013\u0014\u0015]/g, '').trim();
+    items.push({ index: i, code: code, result: resultText, type: f.type });
+  }
   return { count: items.length, fields: items };
 });
 
@@ -1080,6 +1111,7 @@ commands.insertContentControl = (p) => Word.run(async (ctx) => {
   let range;
   if (p.anchorText) {
     if (typeof p.anchorText === 'string' && p.anchorText.trim() === '') throw new Error('anchorText cannot be empty. Provide a non-empty search string or omit the parameter to use the current selection.');
+    checkSearchLength(p.anchorText);
     const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
     results.load('text');
     await ctx.sync();
@@ -1143,6 +1175,7 @@ commands.getPageLayout = (p) => Word.run(async (ctx) => {
 commands.getFontInfo = (p) => Word.run(async (ctx) => {
   if (p.occurrence !== undefined && p.occurrence < 0) throw new Error('occurrence must be non-negative (0-indexed)');
   if (!p.text || typeof p.text !== 'string' || p.text.trim() === '') throw new Error('text cannot be empty. Provide a non-empty search string.');
+  checkSearchLength(p.text);
   const results = ctx.document.body.search(p.text, { matchCase: p.matchCase || false });
   results.load('font');
   await ctx.sync();
@@ -1195,6 +1228,10 @@ commands.insertHtml = (p) => Word.run(async (ctx) => {
 });
 
 commands.insertOoxml = (p) => Word.run(async (ctx) => {
+  if (!p.ooxml || typeof p.ooxml !== 'string' || p.ooxml.trim() === '') throw new Error('ooxml parameter must be a non-empty string');
+  if (!p.ooxml.includes('pkg:package') && !p.ooxml.includes('pkg:part')) {
+    throw new Error('Invalid OOXML: missing pkg:package structure. The XML must be a valid Office Open XML flat package (containing pkg:package and pkg:part elements with a word/document.xml part).');
+  }
   const body = ctx.document.body;
   const range = body.insertOoxml(p.ooxml, p.location || 'End');
   range.getRange('End').select();
@@ -1292,9 +1329,11 @@ commands.insertParagraphAtIndex = (p) => Word.run(async (ctx) => {
     }
   }
   const paragraphs = ctx.document.body.paragraphs;
-  paragraphs.load('text');
+  paragraphs.load('text,parentTableCellOrNullObject');
   await ctx.sync();
   if (p.index >= paragraphs.items.length) throw new Error('Paragraph index out of range. Valid indices: 0-' + (paragraphs.items.length - 1) + ' (document has ' + paragraphs.items.length + ' paragraphs).');
+  let inTable = false;
+  try { inTable = paragraphs.items[p.index].parentTableCellOrNullObject && !paragraphs.items[p.index].parentTableCellOrNullObject.isNullObject; } catch (_e) { /* ignore */ }
   // Validate style exists (if provided)
   const styleName = p.style || 'Normal';
   if (p.style) {
@@ -1317,7 +1356,11 @@ commands.insertParagraphAtIndex = (p) => Word.run(async (ctx) => {
   }
   newPara.getRange('End').select();
   await ctx.sync();
-  return { success: true };
+  const result = { success: true };
+  if (inTable) {
+    result.warning = 'Paragraph inserted inside a table cell. This creates a multi-paragraph cell which may not be intended.';
+  }
+  return result;
 });
 
 // == BOOKMARK NAVIGATION ==
@@ -1491,6 +1534,7 @@ commands.getChangeTrackingMode = () => Word.run(async (ctx) => {
 commands.clearFormatting = (p) => Word.run(async (ctx) => {
   if (p.occurrence !== undefined && p.occurrence < 0) throw new Error('occurrence must be non-negative (0-indexed)');
   if (!p.text || typeof p.text !== 'string' || p.text.trim() === '') throw new Error('text cannot be empty. Provide a non-empty search string.');
+  checkSearchLength(p.text);
   const results = ctx.document.body.search(p.text, { matchCase: p.matchCase || false });
   results.load('font,style');
   await ctx.sync();
@@ -1659,6 +1703,7 @@ commands.getHyperlinks = () => Word.run(async (ctx) => {
 
 commands.removeHyperlink = (p) => Word.run(async (ctx) => {
   if (!p.anchorText || typeof p.anchorText !== 'string' || p.anchorText.trim() === '') throw new Error('anchorText cannot be empty. Provide a non-empty search string.');
+  checkSearchLength(p.anchorText);
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('hyperlink');
   await ctx.sync();
@@ -1747,6 +1792,7 @@ commands.setListLevel = (p) => Word.run(async (ctx) => {
 commands.insertLineBreak = (p) => Word.run(async (ctx) => {
   if (p.occurrence !== undefined && p.occurrence < 0) throw new Error('occurrence must be non-negative (0-indexed)');
   if (!p.anchorText || typeof p.anchorText !== 'string' || p.anchorText.trim() === '') throw new Error('anchorText cannot be empty. Provide a non-empty search string.');
+  checkSearchLength(p.anchorText);
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
   await ctx.sync();
@@ -1760,3 +1806,49 @@ commands.insertLineBreak = (p) => Word.run(async (ctx) => {
   await ctx.sync();
   return { success: true };
 });
+
+// == OOXML ROUND-TRIP (for move/copy paragraph with full fidelity) ==
+commands.getParaOoxml = (p) => Word.run(async (ctx) => {
+  if (p.index < 0) throw new Error('Index must be non-negative');
+  const count = p.count || 1;
+  if (count < 1) throw new Error('count must be at least 1');
+  const paragraphs = ctx.document.body.paragraphs;
+  paragraphs.load('text');
+  await ctx.sync();
+  if (p.index >= paragraphs.items.length) throw new Error('Paragraph index out of range. Valid indices: 0-' + (paragraphs.items.length - 1) + ' (document has ' + paragraphs.items.length + ' paragraphs).');
+  if (p.index + count - 1 >= paragraphs.items.length) throw new Error('index + count (' + (p.index + count) + ') exceeds paragraph count (' + paragraphs.items.length + ').');
+  let range;
+  if (count === 1) {
+    range = paragraphs.items[p.index].getRange('Whole');
+  } else {
+    const firstRange = paragraphs.items[p.index].getRange('Whole');
+    const lastRange = paragraphs.items[p.index + count - 1].getRange('Whole');
+    range = firstRange.expandTo(lastRange);
+  }
+  const ooxml = range.getOoxml();
+  await ctx.sync();
+  return { ooxml: ooxml.value };
+});
+
+commands.insertOoxmlAtIndex = (p) => Word.run(async (ctx) => {
+  if (p.index < 0) throw new Error('Index must be non-negative');
+  if (!p.ooxml || typeof p.ooxml !== 'string' || p.ooxml.trim() === '') throw new Error('ooxml parameter must be a non-empty string');
+  const paragraphs = ctx.document.body.paragraphs;
+  paragraphs.load('text');
+  await ctx.sync();
+  if (p.index >= paragraphs.items.length) throw new Error('Paragraph index out of range. Valid indices: 0-' + (paragraphs.items.length - 1) + ' (document has ' + paragraphs.items.length + ' paragraphs).');
+  const ref = paragraphs.items[p.index];
+  const location = p.location === 'Before' ? 'Before' : 'After';
+  const range = ref.getRange(location);
+  const inserted = range.insertOoxml(p.ooxml, 'Replace');
+  inserted.getRange('End').select();
+  try {
+    await ctx.sync();
+  } catch (e) {
+    if (e.message && e.message.includes('GeneralException')) {
+      throw new Error('Invalid OOXML or cannot insert at paragraph ' + p.index + '. Ensure the XML follows the Office Open XML package structure.');
+    }
+    throw e;
+  }
+  return { success: true };
+});