mcp-word-bridge 3.5.1 → 3.5.2

package/index.js

@@ -62,12 +62,18 @@ const sslOptions = {
   cert: fs.readFileSync(path.join(CERTS_DIR, 'cert.pem'))
 };
 
-const MIME = { '.html': 'text/html', '.js': 'application/javascript', '.css': 'text/css', '.png': 'image/png', '.json': 'application/json' };
+const MIME = { '.html': 'text/html', '.js': 'application/javascript', '.css': 'text/css', '.png': 'image/png', '.json': 'application/json', '.xml': 'application/xml' };
 
 const httpsServer = https.createServer(sslOptions, (req, res) => {
   let urlPath = req.url.split('?')[0];
   let filePath = urlPath === '/' ? '/taskpane.html' : urlPath;
-  filePath = path.join(__dirname, filePath);
+  filePath = path.resolve(__dirname, '.' + filePath);
+  // Prevent path traversal — resolved path must stay within __dirname
+  if (!filePath.startsWith(__dirname + path.sep) && filePath !== __dirname) {
+    res.writeHead(403);
+    res.end('Forbidden');
+    return;
+  }
   const ext = path.extname(filePath);
   const contentType = MIME[ext] || 'application/octet-stream';
   fs.readFile(filePath, (err, data) => {
@@ -88,7 +94,7 @@ const httpsServer = https.createServer(sslOptions, (req, res) => {
 });
 
 // WebSocket relay: taskpane ↔ bridge (MCP server)
-const wss = new WebSocketServer({ server: httpsServer });
+const wss = new WebSocketServer({ server: httpsServer, maxPayload: 10 * 1024 * 1024 });
 let taskpaneSocket = null;
 const bridgePending = new Map();
 
@@ -105,7 +111,15 @@ wss.on('connection', (ws, req) => {
         }
       } catch (_e) {}
     });
-    ws.on('close', () => { process.stderr.write('[bridge] Taskpane disconnected\n'); taskpaneSocket = null; });
+    ws.on('close', () => {
+      process.stderr.write('[bridge] Taskpane disconnected\n');
+      taskpaneSocket = null;
+      // Reject all pending operations immediately instead of waiting for timeout
+      for (const [_id, pending] of bridgePending) {
+        pending.reject(new Error('Word taskpane disconnected. Reopen the MCP Word Bridge add-in in Word.'));
+      }
+      bridgePending.clear();
+    });
   }
   // The /bridge endpoint is no longer needed — MCP server calls sendToTaskpane directly
 });
@@ -134,7 +148,7 @@ function sendToTaskpane(action, params) {
 }
 
 const mcpServer = new Server(
-  { name: 'mcp-word-bridge', version: '3.5.1' },
+  { name: 'mcp-word-bridge', version: '3.5.2' },
   { capabilities: { tools: {}, resources: {} } }
 );
 
@@ -207,17 +221,26 @@ async function executeTool(name, args) {
     if (toIndex < 0) throw new Error('toIndex must be non-negative');
     if (count < 1) throw new Error('count must be at least 1');
     if (fromIndex === toIndex && count === 1) throw new Error('fromIndex and toIndex must be different');
+    // Prevent overlapping moves that would cause data loss
+    if (toIndex >= fromIndex && toIndex < fromIndex + count) {
+      throw new Error('toIndex (' + toIndex + ') is inside the source range [' + fromIndex + ', ' + (fromIndex + count - 1) + ']. Move to a position outside the range being moved.');
+    }
     // Validate all indices are in bounds before mutating
     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).');
-    // Collect all paragraphs to move (text + style)
+    // 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 });
+      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
     for (let i = count - 1; i >= 0; i--) {
@@ -230,16 +253,33 @@ async function executeTool(name, args) {
     } else {
       adjustedTo = toIndex;
     }
-    // Insert in order at destination
+    // 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);
       }
     }
     return { content: [{ type: 'text', text: JSON.stringify({ success: true, moved: { from: fromIndex, count, to: adjustedTo, location } }) }] };

package/lib/tools.js

@@ -20,7 +20,7 @@ const tools = [
   { name: 'word_get_paragraphs', description: '[Paragraphs] Get paragraphs with text, style, alignment, and isTocEntry flag. Supports pagination via optional start/end index range (0-based). Returns total paragraph count.', inputSchema: { type: 'object', properties: { start: { type: 'number', description: 'First paragraph index to return (0-based, inclusive)' }, end: { type: 'number', description: 'Last paragraph index (exclusive). Omit to get all from start.' } } } },
   { name: 'word_get_paragraph_by_index', description: '[Paragraphs] Get full details of a single paragraph including font, spacing, indentation, and outline level.', inputSchema: { type: 'object', properties: { index: { type: 'number', description: 'Paragraph index (0-based)' } }, required: ['index'] } },
   { name: 'word_insert_paragraph', description: '[Paragraphs] Append or prepend a styled paragraph to the document (Start or End only). For inserting at a specific position, use word_insert_paragraph_at_index instead.', inputSchema: { type: 'object', properties: { text: { type: 'string' }, location: { type: 'string', enum: ['Start', 'End'], description: 'Where in the document. Default: End' }, style: { type: 'string', description: 'Paragraph style (e.g. "Heading 1", "Normal"). Default: Normal' }, alignment: { type: 'string', description: 'Paragraph alignment: Left, Center, Right, or Justified' } }, required: ['text'] } },
-  { 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")' } }, required: ['index', 'text'] } },
+  { 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'] } },
@@ -34,7 +34,7 @@ const tools = [
   { name: 'word_insert_text_at_selection', description: '[Search] Insert text at the current cursor position, or replace the current selection (set replace=true). Cursor moves to end of inserted text.', inputSchema: { type: 'object', properties: { text: { type: 'string' }, replace: { type: 'boolean', description: 'Replace current selection instead of appending. Default: false' } }, required: ['text'] } },
   { name: 'word_insert_line_break', description: '[Search] Insert a soft line break (Shift+Enter) before or after a text match.', inputSchema: { type: 'object', properties: { anchorText: { type: 'string', description: 'Text to search for as anchor point' }, before: { type: 'boolean', description: 'Insert before the match (default: after)' }, occurrence: { type: 'number', description: 'Which match to target: 0=first, 1=second, etc. Default: 0' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' } }, required: ['anchorText'] } },
   // 4. FORMATTING
-  { name: 'word_format_text', description: '[Formatting] Apply formatting (bold, italic, color, size, font) to a text match found by search. Color must be hex (#FF0000). Size: 1-1638pt.', inputSchema: { type: 'object', properties: { text: { type: 'string', description: 'Text to search for and format' }, occurrence: { type: 'number', description: 'Which match to target: 0=first, 1=second, etc. Default: 0' }, bold: { type: 'boolean' }, italic: { type: 'boolean' }, underline: { type: 'boolean' }, strikeThrough: { type: 'boolean' }, color: { type: 'string', description: 'Hex color e.g. #FF0000' }, highlightColor: { type: 'string' }, size: { type: 'number', description: 'Font size in points (1-1638)' }, name: { type: 'string', description: 'Font name' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' } }, required: ['text'] } },
+  { name: 'word_format_text', description: '[Formatting] Apply formatting (bold, italic, color, size, font) to a text match found by search. Color must be hex (#FF0000). Size: 1-1638pt.', inputSchema: { type: 'object', properties: { text: { type: 'string', description: 'Text to search for and format' }, occurrence: { type: 'number', description: 'Which match to target: 0=first, 1=second, etc. Default: 0' }, bold: { type: 'boolean' }, italic: { type: 'boolean' }, underline: { type: 'boolean' }, strikeThrough: { type: 'boolean' }, color: { type: 'string', description: 'Hex color e.g. #FF0000' }, highlightColor: { type: 'string', description: 'Highlight color name (Yellow, Green, Cyan, Magenta, Blue, Red, DarkBlue, DarkCyan, DarkGreen, DarkMagenta, DarkRed, DarkYellow, Gray25, Gray50, Black, White) or hex.' }, size: { type: 'number', description: 'Font size in points (1-1638)' }, name: { type: 'string', description: 'Font name' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' } }, required: ['text'] } },
   { name: 'word_clear_formatting', description: '[Formatting] Clear direct formatting from a text match, reverting it to the paragraph style defaults.', inputSchema: { type: 'object', properties: { text: { type: 'string', description: 'Text to search for' }, occurrence: { type: 'number', description: 'Which match to target: 0=first, 1=second, etc. Default: 0' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' } }, required: ['text'] } },
   { name: 'word_get_font_info', description: '[Formatting] Inspect font properties (name, size, bold, italic, color) of a text match.', inputSchema: { type: 'object', properties: { text: { type: 'string', description: 'Text to search for' }, occurrence: { type: 'number', description: 'Which match to target: 0=first, 1=second, etc. Default: 0' }, matchCase: { type: 'boolean', description: 'Case-sensitive matching. Default: false' } }, required: ['text'] } },
   // 5. TABLES

package/lib/usage-guide.js

@@ -67,17 +67,17 @@ The bridge normalizes aliases: Left, Center/Centered, Right, Justify/Justified.
 - \`word_get_comments\` — returns all comments with their anchored document text, author, dates, resolved status
 
 ### Comment + text editing interaction
-**Problem:** \`word_search_and_replace\` on text anchoring a comment collapses the anchor (shrinks to empty). The comment survives but loses its positional context.
+**Problem:** \`word_search_and_replace\` on text anchoring a comment **deletes the comment entirely**. The comment does NOT survive — it is removed along with the anchor text.
 
 **Safe pattern:**
 1. \`word_get_comments\` — identify commented text via anchorText field
 2. If replacement overlaps a comment anchor:
    a. \`word_reply_to_comment\` explaining resolution (if appropriate)
    b. \`word_resolve_comment\`
-   c. THEN replace the text
-3. Resolved thread is preserved as a record
+   c. THEN replace the text (knowing the comment will be deleted)
+3. Resolved thread preserves context in the reply before deletion
 
-**Avoid:** replacing text first (anchor collapses), or deleting+recreating comments (loses author/date/thread).
+**Avoid:** replacing text first without checking comments (silently deletes them), or assuming comments survive anchor replacement (they do not).
 
 ## Tables
 - All indices 0-based: tableIndex, row, col

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>1.0.0</Version>
+  <Version>3.5.2</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.1",
+  "version": "3.5.2",
   "description": "MCP server for live Word document editing via Office Add-in",
   "main": "index.js",
   "bin": {

package/taskpane-app.js

@@ -30,7 +30,7 @@ Office.onReady(function(info) {
 // --- WebSocket ---
 let ws = null;
 function connectWebSocket() {
-  ws = new WebSocket('wss://localhost:3000/taskpane');
+  ws = new WebSocket('wss://' + window.location.host + '/taskpane');
   ws.onopen = function() {
     wsStatus.textContent = 'WebSocket: connected ✓';
     wsStatus.className = 'status ok';
@@ -175,15 +175,27 @@ commands.getParagraphs = (p) => Word.run(async (ctx) => {
   if (p.start !== undefined && p.start < 0) throw new Error('start index must be non-negative');
   if (p.end !== undefined && p.end < 0) throw new Error('end index must be non-negative');
   const paragraphs = ctx.document.body.paragraphs;
-  paragraphs.load('text,style,alignment,firstLineIndent,leftIndent,lineSpacing,isListItem,parentTableCellOrNullObject');
-  await ctx.sync();
+  // Try loading all properties including parentTableCellOrNullObject
+  // 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');
+    await ctx.sync();
+  } catch (_e) {
+    hasTableInfo = false;
+    paragraphs.load('text,style,alignment,firstLineIndent,leftIndent,lineSpacing,isListItem');
+    await ctx.sync();
+  }
   const start = p.start !== undefined ? p.start : 0;
   const end = p.end !== undefined ? p.end : paragraphs.items.length;
   if (start > end) throw new Error('start (' + start + ') must be less than or equal to end (' + end + ')');
   const items = [];
   for (let i = start; i < Math.min(end, paragraphs.items.length); i++) {
     const para = paragraphs.items[i];
-    const inTable = para.parentTableCellOrNullObject && !para.parentTableCellOrNullObject.isNullObject;
+    let inTable = false;
+    if (hasTableInfo) {
+      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 });
   }
@@ -253,8 +265,16 @@ commands.deleteParagraph = (p) => Word.run(async (ctx) => {
   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 countBefore = paragraphs.items.length;
   paragraphs.items[p.index].delete();
-  await ctx.sync();
+  try {
+    await ctx.sync();
+  } catch (e) {
+    if (e.message && e.message.includes('GeneralException')) {
+      throw new Error('Cannot delete paragraph ' + p.index + '. It may be a TOC field entry or inside a protected region.');
+    }
+    throw e;
+  }
   // Move cursor to the paragraph that now occupies this position (or previous if at end)
   const parasAfter = ctx.document.body.paragraphs;
   parasAfter.load('text');
@@ -264,7 +284,11 @@ commands.deleteParagraph = (p) => Word.run(async (ctx) => {
     parasAfter.items[cursorIdx].getRange('Start').select();
     await ctx.sync();
   }
-  return { success: true };
+  const result = { success: true };
+  if (parasAfter.items.length >= countBefore) {
+    result.warning = 'Paragraph was cleared but not removed (Word requires at least one paragraph).';
+  }
+  return result;
 });
 
 commands.setParagraphStyle = (p) => Word.run(async (ctx) => {
@@ -326,6 +350,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.');
   const results = ctx.document.body.search(p.find, { matchCase: p.matchCase || false, matchWholeWord: p.matchWholeWord || false });
   results.load('text');
   await ctx.sync();
@@ -361,24 +386,10 @@ commands.insertText = (p) => Word.run(async (ctx) => {
   return { success: true };
 });
 
-commands.getSelection = () => Word.run(async (ctx) => {
-  const sel = ctx.document.getSelection();
-  sel.load('text,style');
-  await ctx.sync();
-  return { text: sel.text, style: sel.style };
-});
-
-commands.replaceSelection = (p) => Word.run(async (ctx) => {
-  const sel = ctx.document.getSelection();
-  const inserted = sel.insertText(p.text, Word.InsertLocation.replace);
-  inserted.getRange('End').select();
-  await ctx.sync();
-  return { success: true };
-});
-
 // == FORMATTING ==
 commands.formatRange = (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 to format cannot be empty. Provide a non-empty search string.');
   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)');
@@ -511,17 +522,29 @@ commands.deleteTableRow = (p) => Word.run(async (ctx) => {
 commands.insertList = (p) => Word.run(async (ctx) => {
   if (!p.items || p.items.length === 0) throw new Error('items array must not be empty');
   const body = ctx.document.body;
-  // Check if last paragraph is a list item — if so, insert a non-list separator
-  const lastPara = body.paragraphs.getLast();
-  lastPara.load('isListItem');
-  await ctx.sync();
-  if (lastPara.isListItem && (p.location || 'End') === 'End') {
-    const sep = body.insertParagraph('', 'End');
-    sep.style = 'Normal';
-    sep.detachFromList();
+  const location = p.location || 'End';
+  // Check if adjacent paragraph is a list item — if so, insert a non-list separator
+  if (location === 'End') {
+    const lastPara = body.paragraphs.getLast();
+    lastPara.load('isListItem');
+    await ctx.sync();
+    if (lastPara.isListItem) {
+      const sep = body.insertParagraph('', 'End');
+      sep.style = 'Normal';
+      sep.detachFromList();
+      await ctx.sync();
+    }
+  } else if (location === 'Start') {
+    const firstPara = body.paragraphs.getFirst();
+    firstPara.load('isListItem');
     await ctx.sync();
+    if (firstPara.isListItem) {
+      const sep = body.insertParagraph('', 'Start');
+      sep.style = 'Normal';
+      await ctx.sync();
+    }
   }
-  const para = body.insertParagraph(p.items[0], p.location || 'End');
+  const para = body.insertParagraph(p.items[0], location);
   para.style = 'Normal';
   await ctx.sync();
   const list = para.startNewList();
@@ -545,6 +568,7 @@ commands.insertList = (p) => Word.run(async (ctx) => {
 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.');
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
   await ctx.sync();
@@ -610,6 +634,7 @@ commands.deleteComment = (p) => Word.run(async (ctx) => {
 // == FOOTNOTES & ENDNOTES ==
 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.');
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
   await ctx.sync();
@@ -625,6 +650,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.');
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
   await ctx.sync();
@@ -847,6 +873,9 @@ commands.getBookmarks = () => Word.run(async (ctx) => {
 
 commands.insertBookmark = (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.');
+  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).');
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
   // Check for existing bookmark with same name
@@ -885,7 +914,8 @@ commands.getStyles = () => Word.run(async (ctx) => {
   styles.load('nameLocal,type,builtIn');
   await ctx.sync();
   const items = styles.items.map(s => ({ name: s.nameLocal, type: s.type, builtIn: s.builtIn }));
-  return { count: items.length, styles: items.slice(0, 80) };
+  const returned = items.slice(0, 80);
+  return { count: returned.length, total: items.length, styles: returned };
 });
 
 // == COAUTHORING (Desktop only) ==
@@ -976,7 +1006,14 @@ commands.insertPageBreak = (p) => Word.run(async (ctx) => {
     lastPara.insertBreak('Page', 'After');
     lastPara.getRange('End').select();
   }
-  await ctx.sync();
+  try {
+    await ctx.sync();
+  } catch (e) {
+    if (e.message && e.message.includes('GeneralException')) {
+      throw new Error('Cannot insert page break at paragraph ' + (p.paragraphIndex !== undefined ? p.paragraphIndex : 'end') + '. The paragraph may be inside a table cell (page breaks are not allowed inside tables).');
+    }
+    throw e;
+  }
   return { success: true };
 });
 
@@ -1014,11 +1051,14 @@ commands.insertHyperlink = (p) => Word.run(async (ctx) => {
   if (!p.url || !/^https?:\/\/.+/i.test(p.url)) throw new Error('URL must be a valid HTTP or HTTPS URL (e.g. https://example.com)');
   // 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.');
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
   await ctx.sync();
   if (results.items.length === 0) throw new Error('Anchor not found: ' + p.anchorText);
-  const target = results.items[p.occurrence || 0];
+  const idx = p.occurrence || 0;
+  if (idx >= results.items.length) throw new Error('Occurrence ' + idx + ' not found (only ' + results.items.length + ' match' + (results.items.length === 1 ? '' : 'es') + ')');
+  const target = results.items[idx];
   target.hyperlink = p.url;
   target.getRange('End').select();
   await ctx.sync();
@@ -1039,11 +1079,14 @@ commands.insertContentControl = (p) => Word.run(async (ctx) => {
   const ccType = p.type || 'RichText';
   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.');
     const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
     results.load('text');
     await ctx.sync();
     if (results.items.length === 0) throw new Error('Anchor not found: ' + p.anchorText);
-    range = results.items[p.occurrence || 0];
+    const idx = p.occurrence || 0;
+    if (idx >= results.items.length) throw new Error('Occurrence ' + idx + ' not found (only ' + results.items.length + ' match' + (results.items.length === 1 ? '' : 'es') + ')');
+    range = results.items[idx];
   } else {
     range = ctx.document.getSelection();
   }
@@ -1099,6 +1142,7 @@ commands.getPageLayout = (p) => Word.run(async (ctx) => {
 // == FONT INFO ==
 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.');
   const results = ctx.document.body.search(p.text, { matchCase: p.matchCase || false });
   results.load('font');
   await ctx.sync();
@@ -1225,20 +1269,52 @@ commands.replaceParagraphText = (p) => Word.run(async (ctx) => {
   const para = paragraphs.items[p.index];
   const inserted = para.insertText(p.text, Word.InsertLocation.replace);
   inserted.getRange('End').select();
-  await ctx.sync();
+  try {
+    await ctx.sync();
+  } catch (e) {
+    if (e.message && e.message.includes('GeneralException')) {
+      throw new Error('Cannot replace text of paragraph ' + p.index + '. It may be a TOC field entry or inside a protected region.');
+    }
+    throw e;
+  }
   return { success: true };
 });
 
 commands.insertParagraphAtIndex = (p) => Word.run(async (ctx) => {
   if (p.index < 0) throw new Error('Index must be non-negative');
+  // Normalize and validate alignment
+  const ALIGNMENT_MAP = { 'Left': 'Left', 'Center': 'Centered', 'Centered': 'Centered', 'Right': 'Right', 'Justify': 'Justified', 'Justified': 'Justified' };
+  let alignment = null;
+  if (p.alignment) {
+    alignment = ALIGNMENT_MAP[p.alignment];
+    if (!alignment) {
+      throw new Error('Invalid alignment: "' + p.alignment + '". Valid values: Left, Center, Right, Justified');
+    }
+  }
   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).');
+  // Validate style exists (if provided)
+  const styleName = p.style || 'Normal';
+  if (p.style) {
+    const styleObj = ctx.document.getStyles().getByNameOrNullObject(p.style);
+    styleObj.load('nameLocal');
+    await ctx.sync();
+    if (styleObj.isNullObject) {
+      throw new Error('Style not found: "' + p.style + '". Use word_get_styles to see available styles.');
+    }
+  }
   const ref = paragraphs.items[p.index];
   const location = p.location === 'Before' ? Word.InsertLocation.before : Word.InsertLocation.after;
   const newPara = ref.insertParagraph(p.text, location);
-  newPara.style = p.style || 'Normal';
+  newPara.style = styleName;
+  await ctx.sync();
+  // Apply alignment in a separate sync
+  if (alignment) {
+    newPara.alignment = alignment;
+    await ctx.sync();
+  }
   newPara.getRange('End').select();
   await ctx.sync();
   return { success: true };
@@ -1318,13 +1394,23 @@ commands.mergeTableCells = (p) => Word.run(async (ctx) => {
 commands.splitTableCell = (p) => Word.run(async (ctx) => {
   if (p.rowCount !== undefined && p.rowCount <= 0) throw new Error('rowCount must be a positive integer (minimum 1)');
   if (p.colCount !== undefined && p.colCount <= 0) throw new Error('colCount must be a positive integer (minimum 1)');
+  if (p.tableIndex < 0) throw new Error('Table index must be non-negative');
+  if (p.row < 0) throw new Error('Row index must be non-negative');
+  if (p.col < 0) throw new Error('Column index must be non-negative');
   const tables = ctx.document.body.tables;
   tables.load('rowCount');
   await ctx.sync();
-  if (p.tableIndex >= tables.items.length) throw new Error('Table index out of range');
-  const cell = tables.items[p.tableIndex].getCell(p.row, p.col);
-  cell.split(p.rowCount || 1, p.colCount || 2);
-  await ctx.sync();
+  if (p.tableIndex >= tables.items.length) throw new Error('Table index out of range. Document has ' + tables.items.length + ' table(s).');
+  try {
+    const cell = tables.items[p.tableIndex].getCell(p.row, p.col);
+    cell.split(p.rowCount || 1, p.colCount || 2);
+    await ctx.sync();
+  } catch (e) {
+    if (e.message && e.message.includes('ItemNotFound')) {
+      throw new Error('Cell not found at row ' + p.row + ', col ' + p.col + '. Use word_get_table_data to inspect the table.');
+    }
+    throw e;
+  }
   return { success: true };
 });
 
@@ -1404,6 +1490,7 @@ commands.getChangeTrackingMode = () => Word.run(async (ctx) => {
 // == CLEAR FORMATTING ==
 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.');
   const results = ctx.document.body.search(p.text, { matchCase: p.matchCase || false });
   results.load('font,style');
   await ctx.sync();
@@ -1447,7 +1534,9 @@ commands.getPageInfo = async () => {
     allParas.load('text,style');
     await ctx.sync();
     const pageDetails = [];
-    const usedIndices = new Set();
+    // Forward-only cursor: pages are sequential, so each page's paragraphs
+    // must start at or after the previous page's last matched index.
+    let nextStart = 0;
     for (let i = 0; i < pages.items.length; i++) {
       const page = pages.items[i];
       page.load('index,height,width');
@@ -1458,11 +1547,11 @@ commands.getPageInfo = async () => {
       let lastIdx = -1;
       for (let j = 0; j < paras.items.length; j++) {
         const p = paras.items[j];
-        for (let k = 0; k < allParas.items.length; k++) {
-          if (!usedIndices.has(k) && allParas.items[k].text === p.text && allParas.items[k].style === p.style) {
-            usedIndices.add(k);
+        for (let k = nextStart; k < allParas.items.length; k++) {
+          if (allParas.items[k].text === p.text && allParas.items[k].style === p.style) {
             if (firstIdx === -1) firstIdx = k;
             lastIdx = k;
+            nextStart = k + 1;
             break;
           }
         }
@@ -1530,6 +1619,7 @@ commands.deleteImage = (p) => Word.run(async (ctx) => {
 
 // == TABLE CELL SHADING ==
 commands.setTableCellShading = (p) => Word.run(async (ctx) => {
+  if (!/^#[0-9A-Fa-f]{6}$/.test(p.color)) throw new Error('color must be a valid hex color (e.g. #FFD700)');
   const tables = ctx.document.body.tables;
   tables.load('rowCount');
   await ctx.sync();
@@ -1568,11 +1658,14 @@ 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.');
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('hyperlink');
   await ctx.sync();
   if (results.items.length === 0) throw new Error('Text not found: ' + p.anchorText);
-  const target = results.items[p.occurrence || 0];
+  const idx = p.occurrence || 0;
+  if (idx >= results.items.length) throw new Error('Occurrence ' + idx + ' not found (only ' + results.items.length + ' match' + (results.items.length === 1 ? '' : 'es') + ')');
+  const target = results.items[idx];
   target.hyperlink = '';
   target.getRange('End').select();
   await ctx.sync();
@@ -1652,11 +1745,15 @@ commands.setListLevel = (p) => Word.run(async (ctx) => {
 
 // == LINE BREAK ==
 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.');
   const results = ctx.document.body.search(p.anchorText, { matchCase: p.matchCase || false });
   results.load('text');
   await ctx.sync();
   if (results.items.length === 0) throw new Error('Anchor not found: ' + p.anchorText);
-  const target = results.items[p.occurrence || 0];
+  const idx = p.occurrence || 0;
+  if (idx >= results.items.length) throw new Error('Occurrence ' + idx + ' not found (only ' + results.items.length + ' match' + (results.items.length === 1 ? '' : 'es') + ')');
+  const target = results.items[idx];
   const loc = p.before ? Word.InsertLocation.before : Word.InsertLocation.after;
   target.insertBreak('Line', loc);
   target.getRange('End').select();