docrev 0.9.5 → 0.9.7

package/lib/import.ts

@@ -1,108 +1,108 @@
 /**
  * Import functionality - convert Word docs to annotated Markdown
+ *
+ * Orchestration workflows + re-exports from extraction/diff/restore modules
  */
 
 import * as fs from 'fs';
 import * as path from 'path';
-import { diffWords, Change } from 'diff';
 import { stripAnnotations } from './annotations.js';
 import { readImageRegistry } from './image-registry.js';
 import { exec } from 'child_process';
 import { promisify } from 'util';
+
+// Import from split modules
+import {
+  extractFromWord,
+  extractWordComments,
+  extractCommentAnchors,
+  extractWordTables,
+} from './word-extraction.js';
+import type {
+  WordComment,
+  CommentAnchorData,
+  WordTable,
+  ExtractFromWordResult,
+} from './word-extraction.js';
 import {
-  extractMarkdownPrefix,
-  protectAnchors,
-  restoreAnchors,
-  protectCrossrefs,
-  restoreCrossrefs,
-  simplifyMathForMatching,
-  protectMath,
-  restoreMath,
-  replaceRenderedMath,
-  protectCitations,
-  restoreCitations,
-  replaceRenderedCitations,
-  protectImages,
-  restoreImages,
-  matchWordImagesToOriginal,
-  protectTables,
-  restoreTables,
-} from './protect-restore.js';
-import { normalizeWhitespace } from './utils.js';
+  generateSmartDiff,
+  generateAnnotatedDiff,
+  cleanupAnnotations,
+  fixCitationAnnotations,
+} from './diff-engine.js';
+import {
+  restoreCrossrefFromWord,
+  restoreImagesFromRegistry,
+  parseVisibleComments,
+  convertVisibleComments,
+} from './restore-references.js';
+import { findAnchorInText } from './anchor-match.js';
+
+// Re-export everything so existing imports from './import.js' still work
+export {
+  extractFromWord,
+  extractWordComments,
+  extractCommentAnchors,
+  extractHeadings,
+  extractWordTables,
+} from './word-extraction.js';
+export type {
+  WordComment,
+  TextNode,
+  CommentAnchorData,
+  CommentAnchorsResult,
+  DocxHeading,
+  WordTable,
+  ParsedRow,
+  ExtractFromWordOptions,
+  ExtractMessage,
+  ExtractFromWordResult,
+} from './word-extraction.js';
+
+export {
+  generateSmartDiff,
+  generateAnnotatedDiff,
+  cleanupAnnotations,
+  fixCitationAnnotations,
+} from './diff-engine.js';
+export type {
+  GenerateSmartDiffOptions,
+} from './diff-engine.js';
+
+export {
+  restoreCrossrefFromWord,
+  restoreImagesFromRegistry,
+  parseVisibleComments,
+  convertVisibleComments,
+} from './restore-references.js';
+export type {
+  RestoreCrossrefResult,
+  RestoreImagesResult,
+} from './restore-references.js';
 
 const execAsync = promisify(exec);
 
 // ============================================
-// Type Definitions
+// Type Definitions (orchestration-specific)
 // ============================================
 
-interface WordComment {
-  id: string;
-  author: string;
-  date: string;
-  text: string;
-}
-
-interface TextNode {
-  xmlStart: number;
-  xmlEnd: number;
-  textStart: number;
-  textEnd: number;
-  text: string;
-}
-
-interface CommentAnchorData {
-  anchor: string;
-  before: string;
-  after: string;
-  docPosition: number;
-  docLength: number;
-  isEmpty: boolean;
-}
-
-interface CommentAnchorsResult {
-  anchors: Map<string, CommentAnchorData>;
-  fullDocText: string;
-}
-
-interface WordTable {
-  markdown: string;
-  rowCount: number;
-  colCount: number;
-}
-
-interface ParsedRow {
-  cells: string[];
-  colSpans: number[];
-}
-
-interface ExtractFromWordOptions {
-  mediaDir?: string;
-  skipMediaExtraction?: boolean;
-}
-
-interface ExtractMessage {
-  type: 'info' | 'warning';
-  message: string;
-}
-
-interface ExtractFromWordResult {
-  text: string;
-  comments: WordComment[];
-  anchors: Map<string, CommentAnchorData>;
-  messages: ExtractMessage[];
-  extractedMedia: string[];
-  tables: WordTable[];
-  hasTrackChanges: boolean;
-  trackChangeStats: { insertions: number; deletions: number };
-}
-
-interface InsertCommentsOptions {
+export interface InsertCommentsOptions {
   quiet?: boolean;
   sectionBoundary?: { start: number; end: number } | null;
-}
-
-interface CommentWithPos {
+  /**
+   * When true (default), comments wrap their anchor text in `[anchor]{.mark}`
+   * so the rebuilt docx restores the original Word comment range. When false,
+   * comments are inserted as standalone `{>>...<<}` blocks adjacent to the
+   * anchor — the prose stays byte-identical except for the inserted blocks.
+   *
+   * Set to false from `sync --comments-only` so a draft revised after the
+   * docx was sent for review keeps its prose intact, and so multiple
+   * comments sharing one anchor don't produce nested broken markup.
+   */
+  wrapAnchor?: boolean;
+}
+
+export interface CommentWithPos {
   id: string;
   author: string;
   text: string;
@@ -114,42 +114,19 @@ interface CommentWithPos {
   strategy?: string;
 }
 
-interface AnchorSearchResult {
-  occurrences: number[];
-  matchedAnchor: string | null;
-  strategy: string;
-  stripped?: boolean;
-}
+export type { AnchorSearchResult } from './anchor-match.js';
 
-interface MarkdownPrefixResult {
+export interface MarkdownPrefixResult {
   prefix: string;
   content: string;
 }
 
-interface GenerateSmartDiffOptions {
-  wordTables?: WordTable[];
-  imageRegistry?: any;
-}
-
-interface RestoreCrossrefResult {
-  text: string;
-  restored: number;
-  messages: string[];
-  restoredLabels: Set<string>;
-}
-
-interface RestoreImagesResult {
-  text: string;
-  restored: number;
-  messages: string[];
-}
-
-interface ImportWordWithTrackChangesOptions {
+export interface ImportWordWithTrackChangesOptions {
   mediaDir?: string;
   projectDir?: string;
 }
 
-interface ImportWordWithTrackChangesResult {
+export interface ImportWordWithTrackChangesResult {
   text: string;
   stats: {
     insertions: number;
@@ -164,14 +141,14 @@ interface ImportWordWithTrackChangesResult {
   comments: WordComment[];
 }
 
-interface ImportFromWordOptions {
+export interface ImportFromWordOptions {
   author?: string;
   sectionContent?: string;
   figuresDir?: string;
   wordTables?: WordTable[];
 }
 
-interface ImportFromWordResult {
+export interface ImportFromWordResult {
   annotated: string;
   stats: {
     insertions: number;
@@ -183,13 +160,13 @@ interface ImportFromWordResult {
   extractedMedia: string[];
 }
 
-interface MovedFile {
+export interface MovedFile {
   from: string;
   to: string;
   name: string;
 }
 
-interface MoveExtractedMediaResult {
+export interface MoveExtractedMediaResult {
   moved: MovedFile[];
   errors: string[];
 }
@@ -198,593 +175,6 @@ interface MoveExtractedMediaResult {
 // Functions
 // ============================================
 
-/**
- * Extract comments directly from Word docx comments.xml
- */
-export async function extractWordComments(docxPath: string): Promise<WordComment[]> {
-  const AdmZip = (await import('adm-zip')).default;
-  const { parseStringPromise } = await import('xml2js');
-
-  const comments: WordComment[] = [];
-
-  // Validate file exists
-  if (!fs.existsSync(docxPath)) {
-    throw new Error(`File not found: ${docxPath}`);
-  }
-
-  try {
-    let zip;
-    try {
-      zip = new AdmZip(docxPath);
-    } catch (err: any) {
-      throw new Error(`Invalid Word document (not a valid .docx file): ${err.message}`);
-    }
-
-    const commentsEntry = zip.getEntry('word/comments.xml');
-
-    if (!commentsEntry) {
-      return comments;
-    }
-
-    let commentsXml;
-    try {
-      commentsXml = commentsEntry.getData().toString('utf8');
-    } catch (err: any) {
-      throw new Error(`Failed to read comments from document: ${err.message}`);
-    }
-
-    const parsed = await parseStringPromise(commentsXml, { explicitArray: false });
-
-    const ns = 'w:';
-    const commentsRoot = parsed['w:comments'];
-    if (!commentsRoot || !commentsRoot['w:comment']) {
-      return comments;
-    }
-
-    // Ensure it's an array
-    const commentNodes = Array.isArray(commentsRoot['w:comment'])
-      ? commentsRoot['w:comment']
-      : [commentsRoot['w:comment']];
-
-    for (const comment of commentNodes) {
-      const id = comment.$?.['w:id'] || '';
-      const author = comment.$?.['w:author'] || 'Unknown';
-      const date = comment.$?.['w:date'] || '';
-
-      // Extract text from nested w:p/w:r/w:t elements
-      let text = '';
-      const extractText = (node: any): void => {
-        if (!node) return;
-        if (typeof node === 'string') {
-          text += node;
-          return;
-        }
-        if (node['w:t']) {
-          const t = node['w:t'];
-          text += typeof t === 'string' ? t : (t._ || t);
-        }
-        if (node['w:r']) {
-          const runs = Array.isArray(node['w:r']) ? node['w:r'] : [node['w:r']];
-          runs.forEach(extractText);
-        }
-        if (node['w:p']) {
-          const paras = Array.isArray(node['w:p']) ? node['w:p'] : [node['w:p']];
-          paras.forEach(extractText);
-        }
-      };
-      extractText(comment);
-
-      comments.push({ id, author, date: date.slice(0, 10), text: text.trim() });
-    }
-  } catch (err: any) {
-    // Re-throw with more context if it's already an Error we created
-    if (err.message.includes('Invalid Word document') || err.message.includes('File not found')) {
-      throw err;
-    }
-    throw new Error(`Error extracting comments from ${path.basename(docxPath)}: ${err.message}`);
-  }
-
-  return comments;
-}
-
-/**
- * Extract comment anchor texts from document.xml with surrounding context
- * Returns map of comment ID -> {anchor, before, after, docPosition, isEmpty} for better matching
- * Also returns fullDocText for section boundary matching
- */
-export async function extractCommentAnchors(docxPath: string): Promise<CommentAnchorsResult> {
-  const AdmZip = (await import('adm-zip')).default;
-  const anchors = new Map<string, CommentAnchorData>();
-  let fullDocText = '';
-
-  try {
-    const zip = new AdmZip(docxPath);
-    const docEntry = zip.getEntry('word/document.xml');
-
-    if (!docEntry) {
-      return { anchors, fullDocText };
-    }
-
-    const docXml = docEntry.getData().toString('utf8');
-
-    // ========================================
-    // STEP 1: Build text position mapping
-    // ========================================
-    const textNodePattern = /<w:t[^>]*>([^<]*)<\/w:t>/g;
-    const textNodes: TextNode[] = [];
-    let textPosition = 0;
-    let nodeMatch;
-
-    while ((nodeMatch = textNodePattern.exec(docXml)) !== null) {
-      const rawText = nodeMatch[1] ?? '';
-      const decodedText = decodeXmlEntities(rawText);
-      textNodes.push({
-        xmlStart: nodeMatch.index,
-        xmlEnd: nodeMatch.index + nodeMatch[0].length,
-        textStart: textPosition,
-        textEnd: textPosition + decodedText.length,
-        text: decodedText
-      });
-      textPosition += decodedText.length;
-    }
-
-    fullDocText = textNodes.map(n => n.text).join('');
-
-    // Helper: convert XML position to text position
-    function xmlPosToTextPos(xmlPos: number): number {
-      for (let i = 0; i < textNodes.length; i++) {
-        const node = textNodes[i];
-        if (!node) continue;
-        if (xmlPos >= node.xmlStart && xmlPos < node.xmlEnd) {
-          return node.textStart;
-        }
-        if (xmlPos < node.xmlStart) {
-          return node.textStart;
-        }
-      }
-      const lastNode = textNodes[textNodes.length - 1];
-      return lastNode ? lastNode.textEnd : 0;
-    }
-
-    // Helper: extract context before a position
-    function getContextBefore(position: number, maxLength: number = 150): string {
-      const beforeText = fullDocText.slice(Math.max(0, position - maxLength), position);
-      const sentenceStart = beforeText.search(/[.!?]\s+[A-Z][^.!?]*$/);
-      return sentenceStart >= 0
-        ? beforeText.slice(sentenceStart + 2).trim()
-        : beforeText.slice(-80).trim();
-    }
-
-    // Helper: extract context after a position
-    function getContextAfter(position: number, maxLength: number = 150): string {
-      const afterText = fullDocText.slice(position, position + maxLength);
-      const sentenceEnd = afterText.search(/[.!?]\s/);
-      return sentenceEnd >= 0
-        ? afterText.slice(0, sentenceEnd + 1).trim()
-        : afterText.slice(0, 80).trim();
-    }
-
-    // ========================================
-    // STEP 2: Collect all start/end markers separately
-    // ========================================
-    const startPattern = /<w:commentRangeStart[^>]*w:id="(\d+)"[^>]*\/?>/g;
-    const endPattern = /<w:commentRangeEnd[^>]*w:id="(\d+)"[^>]*\/?>/g;
-
-    const starts = new Map<string, number>();  // id -> position after start tag
-    const ends = new Map<string, number>();    // id -> position before end tag
-
-    let match;
-    while ((match = startPattern.exec(docXml)) !== null) {
-      const id = match[1];
-      if (!starts.has(id)) {
-        starts.set(id, match.index + match[0].length);
-      }
-    }
-
-    while ((match = endPattern.exec(docXml)) !== null) {
-      const id = match[1];
-      if (!ends.has(id)) {
-        ends.set(id, match.index);
-      }
-    }
-
-    // ========================================
-    // STEP 3: Process each comment range by ID
-    // ========================================
-    for (const [id, startXmlPos] of starts) {
-      const endXmlPos = ends.get(id);
-
-      // Missing end marker - skip with warning
-      if (endXmlPos === undefined) {
-        console.warn(`Comment ${id}: missing end marker`);
-        continue;
-      }
-
-      // Calculate text position
-      const docPosition = xmlPosToTextPos(startXmlPos);
-
-      // Handle empty or inverted ranges
-      if (endXmlPos <= startXmlPos) {
-        anchors.set(id, {
-          anchor: '',
-          before: getContextBefore(docPosition),
-          after: getContextAfter(docPosition),
-          docPosition,
-          docLength: fullDocText.length,
-          isEmpty: true
-        });
-        continue;
-      }
-
-      // Extract XML segment between markers
-      const segment = docXml.slice(startXmlPos, endXmlPos);
-
-      // Extract text from w:t (regular) AND w:delText (deleted text in track changes)
-      const textInRangePattern = /<w:t[^>]*>([^<]*)<\/w:t>|<w:delText[^>]*>([^<]*)<\/w:delText>/g;
-      let anchorText = '';
-      let tm;
-      while ((tm = textInRangePattern.exec(segment)) !== null) {
-        anchorText += tm[1] || tm[2] || '';
-      }
-      anchorText = decodeXmlEntities(anchorText);
-
-      // Get context
-      const anchorLength = anchorText.length;
-      const before = getContextBefore(docPosition);
-      const after = getContextAfter(docPosition + anchorLength);
-
-      // ALWAYS add entry (even if anchor is empty)
-      anchors.set(id, {
-        anchor: anchorText.trim(),
-        before,
-        after,
-        docPosition,
-        docLength: fullDocText.length,
-        isEmpty: !anchorText.trim()
-      });
-    }
-  } catch (err: any) {
-    console.error('Error extracting comment anchors:', err.message);
-    return { anchors, fullDocText: '' };
-  }
-
-  return { anchors, fullDocText };
-}
-
-/**
- * Decode XML entities in text
- */
-function decodeXmlEntities(text: string): string {
-  return text
-    .replace(/&amp;/g, '&')
-    .replace(/&lt;/g, '<')
-    .replace(/&gt;/g, '>')
-    .replace(/&quot;/g, '"')
-    .replace(/&apos;/g, "'")
-    .replace(/&#(\d+);/g, (_, code) => String.fromCharCode(parseInt(code, 10)))
-    .replace(/&#x([0-9a-fA-F]+);/g, (_, code) => String.fromCharCode(parseInt(code, 16)));
-}
-
-/**
- * Extract text content from a Word XML cell
- */
-function extractCellText(cellXml: string): string {
-  const parts: string[] = [];
-
-  // Check for OMML math - replace with [math] placeholder
-  if (cellXml.includes('<m:oMath')) {
-    // Try to extract the text representation of math
-    const mathTextMatches = cellXml.match(/<m:t>([^<]*)<\/m:t>/g) || [];
-    if (mathTextMatches.length > 0) {
-      const mathText = mathTextMatches.map((t) => t.replace(/<[^>]+>/g, '')).join('');
-      parts.push(mathText);
-    } else {
-      parts.push('[math]');
-    }
-  }
-
-  // Extract regular text from w:t elements
-  const textMatches = cellXml.match(/<w:t[^>]*>([^<]*)<\/w:t>/g) || [];
-  for (const match of textMatches) {
-    const text = match.replace(/<[^>]+>/g, '');
-    if (text) {
-      parts.push(text);
-    }
-  }
-
-  let result = parts.join('').trim();
-  result = decodeXmlEntities(result);
-
-  // Escape pipe characters in cell content (would break table)
-  result = result.replace(/\|/g, '\\|');
-
-  return result;
-}
-
-/**
- * Parse a table row, handling merged cells (gridSpan)
- */
-function parseTableRow(rowXml: string, expectedCols: number): ParsedRow {
-  // Match cells - handle both <w:tc> and <w:tc ...>
-  const cellMatches = rowXml.match(/<w:tc(?:\s[^>]*)?>[\s\S]*?<\/w:tc>/g) || [];
-  const cells: string[] = [];
-  const colSpans: number[] = [];
-
-  for (const cellXml of cellMatches) {
-    // Check for horizontal merge (gridSpan)
-    const gridSpanMatch = cellXml.match(/<w:gridSpan\s+w:val="(\d+)"/);
-    const span = gridSpanMatch ? parseInt(gridSpanMatch[1], 10) : 1;
-
-    // Check for vertical merge continuation (vMerge without restart)
-    // If vMerge is present without w:val="restart", it's a continuation - use empty
-    const vMergeMatch = cellXml.match(/<w:vMerge(?:\s+w:val="([^"]+)")?/);
-    const isVMergeContinuation = vMergeMatch && vMergeMatch[1] !== 'restart';
-
-    const cellText = isVMergeContinuation ? '' : extractCellText(cellXml);
-
-    // Add the cell content
-    cells.push(cellText);
-    colSpans.push(span);
-
-    // For gridSpan > 1, add empty cells to maintain column alignment
-    for (let i = 1; i < span; i++) {
-      cells.push('');
-      colSpans.push(0); // 0 indicates this is a spanned cell
-    }
-  }
-
-  return { cells, colSpans };
-}
-
-/**
- * Determine table grid column count from table XML
- */
-function getTableGridCols(tableXml: string): number {
-  // Try to get from tblGrid
-  const gridColMatches = tableXml.match(/<w:gridCol/g) || [];
-  if (gridColMatches.length > 0) {
-    return gridColMatches.length;
-  }
-
-  // Fallback: count max cells in any row
-  const rowMatches = tableXml.match(/<w:tr[\s\S]*?<\/w:tr>/g) || [];
-  let maxCols = 0;
-  for (const rowXml of rowMatches) {
-    const { cells } = parseTableRow(rowXml, 0);
-    maxCols = Math.max(maxCols, cells.length);
-  }
-  return maxCols;
-}
-
-/**
- * Extract tables directly from Word document XML and convert to markdown pipe tables
- */
-export async function extractWordTables(docxPath: string): Promise<WordTable[]> {
-  const AdmZip = (await import('adm-zip')).default;
-  const tables: WordTable[] = [];
-
-  try {
-    const zip = new AdmZip(docxPath);
-    const docEntry = zip.getEntry('word/document.xml');
-
-    if (!docEntry) {
-      return tables;
-    }
-
-    const xml = docEntry.getData().toString('utf8');
-
-    // Find all table elements
-    const tableMatches = xml.match(/<w:tbl>[\s\S]*?<\/w:tbl>/g) || [];
-
-    for (const tableXml of tableMatches) {
-      // Determine expected column count from grid
-      const expectedCols = getTableGridCols(tableXml);
-
-      // Extract rows
-      const rowMatches = tableXml.match(/<w:tr[\s\S]*?<\/w:tr>/g) || [];
-      const rows: string[][] = [];
-
-      for (const rowXml of rowMatches) {
-        const { cells } = parseTableRow(rowXml, expectedCols);
-        if (cells.length > 0) {
-          rows.push(cells);
-        }
-      }
-
-      if (rows.length > 0) {
-        // Convert to markdown pipe table
-        const markdown = convertRowsToMarkdownTable(rows);
-        tables.push({ markdown, rowCount: rows.length, colCount: expectedCols || rows[0]?.length || 0 });
-      }
-    }
-  } catch (err: any) {
-    console.error('Error extracting tables from Word:', err.message);
-  }
-
-  return tables;
-}
-
-/**
- * Convert array of rows (each row is array of cell strings) to markdown pipe table
- */
-function convertRowsToMarkdownTable(rows: string[][]): string {
-  if (rows.length === 0) return '';
-
-  // Normalize column count (use max across all rows)
-  const colCount = Math.max(...rows.map((r) => r.length));
-
-  // Pad rows to have consistent column count
-  const normalizedRows = rows.map((row) => {
-    while (row.length < colCount) {
-      row.push('');
-    }
-    return row;
-  });
-
-  // Build markdown table
-  const lines: string[] = [];
-
-  // Header row
-  const header = normalizedRows[0];
-  lines.push('| ' + header.join(' | ') + ' |');
-
-  // Separator row
-  lines.push('|' + header.map(() => '---').join('|') + '|');
-
-  // Data rows
-  for (let i = 1; i < normalizedRows.length; i++) {
-    lines.push('| ' + normalizedRows[i].join(' | ') + ' |');
-  }
-
-  return lines.join('\n');
-}
-
-/**
- * Extract text from Word document using pandoc with track changes preserved
- */
-export async function extractFromWord(
-  docxPath: string,
-  options: ExtractFromWordOptions = {}
-): Promise<ExtractFromWordResult> {
-  let text: string;
-  let messages: ExtractMessage[] = [];
-  let extractedMedia: string[] = [];
-  let hasTrackChanges = false;
-  let trackChangeStats = { insertions: 0, deletions: 0 };
-
-  // Determine media extraction directory
-  const docxDir = path.dirname(docxPath);
-  const mediaDir = options.mediaDir || path.join(docxDir, 'media');
-
-  // Skip media extraction if figures already exist (e.g., when re-importing with existing source)
-  const skipMediaExtraction = options.skipMediaExtraction || false;
-
-  // Extract tables directly from Word XML (reliable, no heuristics)
-  const wordTables = await extractWordTables(docxPath);
-
-  // Try pandoc first with --track-changes=all to preserve reviewer edits
-  try {
-    // Build pandoc command
-    let pandocCmd = `pandoc "${docxPath}" -t markdown --wrap=none --track-changes=all`;
-    if (!skipMediaExtraction) {
-      pandocCmd += ` --extract-media="${mediaDir}"`;
-    }
-
-    const { stdout } = await execAsync(pandocCmd, { maxBuffer: 50 * 1024 * 1024 });
-    text = stdout;
-
-    // Convert pandoc's track change format to CriticMarkup
-    const origLength = text.length;
-
-    // Use a more robust pattern that handles nested content
-    text = text.replace(/\[([^\[\]]*(?:\[[^\[\]]*\][^\[\]]*)*)\]\{\.insertion[^}]*\}/g, (match, content) => {
-      if (content.trim()) {
-        trackChangeStats.insertions++;
-        return `{++${content}++}`;
-      }
-      return ''; // Empty insertions are removed
-    });
-
-    text = text.replace(/\[([^\[\]]*(?:\[[^\[\]]*\][^\[\]]*)*)\]\{\.deletion[^}]*\}/g, (match, content) => {
-      if (content.trim()) {
-        trackChangeStats.deletions++;
-        return `{--${content}--}`;
-      }
-      return ''; // Empty deletions are removed
-    });
-
-    // Handle any remaining pandoc track change patterns
-    let prevText;
-    do {
-      prevText = text;
-      text = text.replace(/\[([^\]]*)\]\{\.insertion[^}]*\}/g, (match, content) => {
-        if (content.trim()) {
-          trackChangeStats.insertions++;
-          return `{++${content}++}`;
-        }
-        return '';
-      });
-      text = text.replace(/\[([^\]]*)\]\{\.deletion[^}]*\}/g, (match, content) => {
-        if (content.trim()) {
-          trackChangeStats.deletions++;
-          return `{--${content}--}`;
-        }
-        return '';
-      });
-    } while (text !== prevText);
-
-    // Handle pandoc comment patterns - remove comment text from body
-    text = text.replace(/\[[^\]]*\]\{\.comment-start[^}]*\}/g, '');
-    text = text.replace(/\[\]\{\.comment-end[^}]*\}/g, '');
-
-    // Also handle {.mark} spans
-    text = text.replace(/\[([^\]]*)\]\{\.mark\}/g, '$1');
-
-    hasTrackChanges = trackChangeStats.insertions > 0 || trackChangeStats.deletions > 0;
-
-    if (hasTrackChanges) {
-      messages.push({
-        type: 'info',
-        message: `Found ${trackChangeStats.insertions} insertion(s) and ${trackChangeStats.deletions} deletion(s) from track changes`
-      });
-    }
-
-    // Find extracted media files
-    const mediaSubdir = path.join(mediaDir, 'media');
-    if (fs.existsSync(mediaSubdir)) {
-      extractedMedia = fs.readdirSync(mediaSubdir)
-        .filter(f => /\.(png|jpg|jpeg|gif|svg|emf|wmf|tiff?)$/i.test(f))
-        .map(f => path.join(mediaSubdir, f));
-
-      if (extractedMedia.length > 0) {
-        messages.push({
-          type: 'info',
-          message: `Extracted ${extractedMedia.length} image(s) to ${mediaSubdir}`
-        });
-      }
-    }
-  } catch (pandocErr: any) {
-    // Pandoc not available — use XML-based extraction with track change support
-    const { extractPlainTextWithTrackChanges } = await import('./word.js');
-    const { getInstallInstructions } = await import('./dependencies.js');
-    const installCmd = getInstallInstructions('pandoc');
-
-    const xmlResult = await extractPlainTextWithTrackChanges(docxPath);
-    text = xmlResult.text;
-    hasTrackChanges = xmlResult.hasTrackChanges;
-    trackChangeStats = xmlResult.stats;
-
-    if (hasTrackChanges) {
-      messages.push({
-        type: 'warning',
-        message: `Pandoc not installed. Using built-in XML extractor (${trackChangeStats.insertions} insertions, ${trackChangeStats.deletions} deletions preserved). Formatting may differ. Install pandoc for best results: ${installCmd}`
-      });
-    } else {
-      messages.push({
-        type: 'warning',
-        message: `Pandoc not installed. Using built-in XML extractor (no track changes found). Install pandoc for better formatting: ${installCmd}`
-      });
-    }
-  }
-
-  // Extract comments directly from docx XML
-  const comments = await extractWordComments(docxPath);
-
-  // Extract comment anchor texts
-  const { anchors } = await extractCommentAnchors(docxPath);
-
-  return {
-    text,
-    comments,
-    anchors,
-    messages,
-    extractedMedia,
-    tables: wordTables,
-    hasTrackChanges,
-    trackChangeStats,
-  };
-}
-
 /**
  * Insert comments into markdown text based on anchor texts with context
  */
@@ -794,165 +184,14 @@ export function insertCommentsIntoMarkdown(
   anchors: Map<string, CommentAnchorData | string>,
   options: InsertCommentsOptions = {}
 ): string {
-  const { quiet = false, sectionBoundary = null } = options;
+  const { quiet = false, sectionBoundary = null, wrapAnchor = true } = options;
   let result = markdown;
   let unmatchedCount = 0;
   const duplicateWarnings: string[] = [];
   const usedPositions = new Set<number>(); // For tie-breaking: track used positions
 
-  // Helper: Strip CriticMarkup from text to get "clean" version for matching
-  function stripCriticMarkup(text: string): string {
-    return text
-      .replace(/\{\+\+([^+]*)\+\+\}/g, '$1')  // insertions: keep inserted text
-      .replace(/\{--([^-]*)--\}/g, '')         // deletions: remove deleted text
-      .replace(/\{~~([^~]*)~>([^~]*)~~\}/g, '$2')  // substitutions: keep new text
-      .replace(/\{>>[^<]*<<\}/g, '')           // comments: remove
-      .replace(/\[([^\]]*)\]\{\.mark\}/g, '$1'); // marked text: keep text
-  }
-
-  // Helper: Find anchor in text with multiple fallback strategies
-  function findAnchorInText(anchor: string, text: string, before: string = '', after: string = ''): AnchorSearchResult {
-    // If anchor is empty, skip directly to context-based matching
-    if (!anchor || anchor.trim().length === 0) {
-      // Jump to context-based strategies (Strategy 5)
-      if (before || after) {
-        const beforeLower = (before || '').toLowerCase();
-        const afterLower = (after || '').toLowerCase();
-        const textLower = text.toLowerCase();
-
-        if (before && after) {
-          const beforeIdx = textLower.indexOf(beforeLower.slice(-50));
-          if (beforeIdx !== -1) {
-            const searchStart = beforeIdx + beforeLower.slice(-50).length;
-            const afterIdx = textLower.indexOf(afterLower.slice(0, 50), searchStart);
-            if (afterIdx !== -1 && afterIdx - searchStart < 500) {
-              return { occurrences: [searchStart], matchedAnchor: null, strategy: 'context-both' };
-            }
-          }
-        }
-
-        if (before) {
-          const beforeIdx = textLower.lastIndexOf(beforeLower.slice(-30));
-          if (beforeIdx !== -1) {
-            return { occurrences: [beforeIdx + beforeLower.slice(-30).length], matchedAnchor: null, strategy: 'context-before' };
-          }
-        }
-
-        if (after) {
-          const afterIdx = textLower.indexOf(afterLower.slice(0, 30));
-          if (afterIdx !== -1) {
-            return { occurrences: [afterIdx], matchedAnchor: null, strategy: 'context-after' };
-          }
-        }
-      }
-      return { occurrences: [], matchedAnchor: null, strategy: 'empty-anchor' };
-    }
-
-    const anchorLower = anchor.toLowerCase();
-    const textLower = text.toLowerCase();
-
-    // Strategy 1: Direct match
-    let occurrences = findAllOccurrences(textLower, anchorLower);
-    if (occurrences.length > 0) {
-      return { occurrences, matchedAnchor: anchor, strategy: 'direct' };
-    }
-
-    // Strategy 2: Normalized whitespace
-    const normalizedAnchor = anchor.replace(/\s+/g, ' ').toLowerCase();
-    const normalizedText = text.replace(/\s+/g, ' ').toLowerCase();
-    let idx = normalizedText.indexOf(normalizedAnchor);
-    if (idx !== -1) {
-      return { occurrences: [idx], matchedAnchor: anchor, strategy: 'normalized' };
-    }
-
-    // Strategy 3: Try matching in stripped CriticMarkup version
-    const strippedText = stripCriticMarkup(text);
-    const strippedLower = strippedText.toLowerCase();
-    occurrences = findAllOccurrences(strippedLower, anchorLower);
-    if (occurrences.length > 0) {
-      return { occurrences, matchedAnchor: anchor, strategy: 'stripped', stripped: true };
-    }
-
-    // Strategy 4: First N words of anchor (for long anchors)
-    const words = anchor.split(/\s+/);
-    if (words.length > 3) {
-      for (let n = Math.min(6, words.length); n >= 3; n--) {
-        const partialAnchor = words.slice(0, n).join(' ').toLowerCase();
-        if (partialAnchor.length >= 15) {
-          occurrences = findAllOccurrences(textLower, partialAnchor);
-          if (occurrences.length > 0) {
-            return { occurrences, matchedAnchor: words.slice(0, n).join(' '), strategy: 'partial-start' };
-          }
-          occurrences = findAllOccurrences(strippedLower, partialAnchor);
-          if (occurrences.length > 0) {
-            return { occurrences, matchedAnchor: words.slice(0, n).join(' '), strategy: 'partial-start-stripped', stripped: true };
-          }
-        }
-      }
-    }
-
-    // Strategy 5: Use context (before/after) to find approximate position
-    if (before || after) {
-      const beforeLower = before.toLowerCase();
-      const afterLower = after.toLowerCase();
-
-      if (before && after) {
-        const beforeIdx = textLower.indexOf(beforeLower.slice(-50));
-        if (beforeIdx !== -1) {
-          const searchStart = beforeIdx + beforeLower.slice(-50).length;
-          const afterIdx = textLower.indexOf(afterLower.slice(0, 50), searchStart);
-          if (afterIdx !== -1 && afterIdx - searchStart < 500) {
-            return { occurrences: [searchStart], matchedAnchor: null, strategy: 'context-both' };
-          }
-        }
-      }
-
-      if (before) {
-        const beforeIdx = textLower.lastIndexOf(beforeLower.slice(-30));
-        if (beforeIdx !== -1) {
-          return { occurrences: [beforeIdx + beforeLower.slice(-30).length], matchedAnchor: null, strategy: 'context-before' };
-        }
-      }
-
-      if (after) {
-        const afterIdx = textLower.indexOf(afterLower.slice(0, 30));
-        if (afterIdx !== -1) {
-          return { occurrences: [afterIdx], matchedAnchor: null, strategy: 'context-after' };
-        }
-      }
-    }
-
-    // Strategy 6: Try splitting anchor on common transition words
-    const splitPatterns = [' ', ', ', '. ', ' - ', ' – '];
-    for (const sep of splitPatterns) {
-      if (anchor.includes(sep)) {
-        const parts = anchor.split(sep).filter(p => p.length >= 4);
-        for (const part of parts) {
-          const partLower = part.toLowerCase();
-          occurrences = findAllOccurrences(textLower, partLower);
-          if (occurrences.length > 0 && occurrences.length < 5) {
-            return { occurrences, matchedAnchor: part, strategy: 'split-match' };
-          }
-        }
-      }
-    }
-
-    return { occurrences: [], matchedAnchor: null, strategy: 'failed' };
-  }
-
-  // Helper: Find all occurrences of needle in haystack
-  function findAllOccurrences(haystack: string, needle: string): number[] {
-    if (!needle || needle.length === 0) {
-      return [];
-    }
-    const occurrences: number[] = [];
-    let idx = 0;
-    while ((idx = haystack.indexOf(needle, idx)) !== -1) {
-      occurrences.push(idx);
-      idx += 1;
-    }
-    return occurrences;
-  }
+  // Anchor matching primitives live in lib/anchor-match.ts so that
+  // `rev verify-anchors` can use the same strategies for drift reporting.
 
   // Get all positions in order (for sequential tie-breaking)
   const commentsWithPositions = comments.map((c): CommentWithPos => {
@@ -1108,18 +347,24 @@ export function insertCommentsIntoMarkdown(
   // Sort by position descending (insert from end to avoid offset issues)
   matched.sort((a, b) => b.pos - a.pos);
 
-  // Insert each comment with anchor marking
+  // Insert each comment. With `wrapAnchor` (the default), the anchor text
+  // gets wrapped in `[anchor]{.mark}` so the rebuilt docx restores the
+  // original Word comment range. Without it, the comment block is inserted
+  // adjacent to the anchor and prose stays untouched — required for
+  // comments-only sync where multiple comments may share one anchor.
   for (const c of matched) {
     const comment = `{>>${c.author}: ${c.text}<<}`;
-    if (c.anchorText && c.anchorEnd) {
-      // Replace anchor text with: {>>comment<<}[anchor]{.mark}
+    if (wrapAnchor && c.anchorText && c.anchorEnd) {
       const before = result.slice(0, c.pos);
       const anchor = result.slice(c.pos, c.anchorEnd);
       const after = result.slice(c.anchorEnd);
       result = before + comment + `[${anchor}]{.mark}` + after;
     } else {
-      // No anchor - just insert comment at position
-      result = result.slice(0, c.pos) + ` ${comment}` + result.slice(c.pos);
+      // Insert comment at the anchor position with no surrounding whitespace
+      // tweaks; CriticMarkup blocks are invisible to readers, and adding a
+      // leading space would shift prose byte-for-byte (relevant when callers
+      // verify that --comments-only didn't touch the original).
+      result = result.slice(0, c.pos) + comment + result.slice(c.pos);
     }
   }
 
@@ -1139,647 +384,6 @@ export function insertCommentsIntoMarkdown(
   return result;
 }
 
-/**
- * Fix citation and math annotations by preserving original markdown syntax
- */
-function fixCitationAnnotations(text: string, originalMd: string): string {
-  // Fix math annotations - preserve inline and display math
-  text = text.replace(/\{--(\$[^$]+\$)--\}/g, '$1');
-  text = text.replace(/\{--(\$\$[^$]+\$\$)--\}/g, '$1');
-
-  text = text.replace(/\{~~(\$[^$]+\$)~>[^~]+~~\}/g, '$1');
-  text = text.replace(/\{~~(\$\$[^$]+\$\$)~>[^~]+~~\}/g, '$1');
-
-  // Extract all citations from original markdown
-  const citationPattern = /\[@[^\]]+\]/g;
-  const originalCitations = [...originalMd.matchAll(citationPattern)].map(m => m[0]);
-
-  // Fix substitutions where left side has markdown citation
-  text = text.replace(/\{~~(\[@[^\]]+\])~>[^~]+~~\}/g, '$1');
-
-  // Fix substitutions where left side STARTS with markdown citation
-  text = text.replace(/\{~~(\[@[^\]]+\])\s*([^~]*)~>([^~]*)~~\}/g, (match, cite, oldText, newText) => {
-    if (oldText.trim() === '' && newText.trim() === '') {
-      return cite;
-    }
-    if (oldText.trim() || newText.trim()) {
-      return cite + (oldText.trim() !== newText.trim() ? ` {~~${oldText.trim()}~>${newText.trim()}~~}` : ` ${newText}`);
-    }
-    return cite;
-  });
-
-  // Fix deletions of markdown citations
-  text = text.replace(/\{--(\[@[^\]]+\])--\}/g, '$1');
-
-  // Fix insertions of rendered citations
-  text = text.replace(/\{\+\+\([A-Z][^)]*\d{4}[^)]*\)\+\+\}/g, '');
-
-  // Clean up broken multi-part substitutions
-  text = text.replace(/\{~~(@[A-Za-z]+\d{4})~>[^~]+~~\}/g, '[$1]');
-
-  // Fix citations split across substitution boundaries
-  text = text.replace(/\{~~\[@~>[^~]*~~\}([A-Za-z]+\d{4})\]/g, '[@$1]');
-
-  // Clean up any remaining partial citations
-  text = text.replace(/\{~~;\s*@([A-Za-z]+\d{4})\]~>[^~]*~~\}/g, '; [@$1]');
-
-  // Remove rendered citation insertions (with Unicode support)
-  text = text.replace(/\{\+\+\(\p{Lu}\p{L}*(?:\s+et\s+al\.?)?\s+\d{4}[a-z]?(?:[;,]\s*\p{Lu}\p{L}*(?:\s+et\s+al\.?)?\s+\d{4}[a-z]?)*\)\+\+\}/gu, '');
-  text = text.replace(/\{\+\+\(\p{Lu}\p{L}*(?:\s+et\s+al\.?)?\s+\d{4}[a-z]?(?:[;,]\s*\p{Lu}\p{L}*(?:\s+et\s+al\.?)?\s+\d{4}[a-z]?)*\)\.\s*\+\+\}/gu, '');
-
-  // Trailing citation fragments
-  text = text.replace(/\{\+\+\d{4}[a-z]?(?:[;,]\s*(?:\p{Lu}\p{L}*(?:\s+et\s+al\.?)?\s+)?\d{4}[a-z]?)*\)\.\s*\+\+\}/gu, '');
-  text = text.replace(/\{\+\+\d{4}[a-z]?(?:[;,]\s*(?:\p{Lu}\p{L}*(?:\s+et\s+al\.?)?\s+)?\d{4}[a-z]?)*\)\s*\+\+\}/gu, '');
-
-  // Just year with closing paren
-  text = text.replace(/\{\+\+\d{4}[a-z]?\)\.\s*\+\+\}/g, '');
-  text = text.replace(/\{\+\+\d{4}[a-z]?\)\s*\+\+\}/g, '');
-
-  // Leading citation fragments
-  text = text.replace(/\{\+\+\(?\p{Lu}\p{L}*(?:\s+et\s+al\.?)?\s*\+\+\}/gu, '');
-
-  // Semicolon-separated fragments
-  text = text.replace(/\{\+\+[;,]\s*\p{Lu}\p{L}*(?:\s+et\s+al\.?)?\s+\d{4}[a-z]?\+\+\}/gu, '');
-
-  // Year ranges with authors
-  text = text.replace(/\{\+\+\p{Lu}\p{L}*(?:\s+et\s+al\.?)?\s+\d{4}[a-z]?(?:[;,]\s*\p{Lu}\p{L}*(?:\s+et\s+al\.?)?\s+\d{4}[a-z]?)*\)\s*\+\+\}/gu, '');
-  text = text.replace(/\{\+\+\p{Lu}\p{L}*(?:\s+et\s+al\.?)?\s+\d{4}[a-z]?(?:[;,]\s*\p{Lu}\p{L}*(?:\s+et\s+al\.?)?\s+\d{4}[a-z]?)*\)\.\s*\+\+\}/gu, '');
-
-  // Clean up double spaces and orphaned punctuation
-  text = text.replace(/  +/g, ' ');
-  text = text.replace(/\s+\./g, '.');
-  text = text.replace(/\s+,/g, ',');
-
-  // Final cleanup - remove empty annotations
-  text = text.replace(/\{~~\s*~>\s*~~\}/g, '');
-  text = text.replace(/\{\+\+\s*\+\+\}/g, '');
-  text = text.replace(/\{--\s*--\}/g, '');
-
-  return text;
-}
-
-/**
- * Strip markdown syntax to get plain text
- */
-function stripMarkdownSyntax(md: string): string {
-  return md
-    .replace(/^---[\s\S]*?---\n*/m, '')
-    .replace(/^#{1,6}\s+/gm, '')
-    .replace(/(\*\*|__)(.*?)\1/g, '$2')
-    .replace(/(\*|_)(.*?)\1/g, '$2')
-    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
-    .replace(/!\[([^\]]*)\]\([^)]+\)/g, '')
-    .replace(/`([^`]+)`/g, '$1')
-    .replace(/```[\s\S]*?```/g, '')
-    .replace(/^>\s*/gm, '')
-    .replace(/^[-*_]{3,}\s*$/gm, '')
-    .replace(/^[\s]*[-*+]\s+/gm, '')
-    .replace(/^[\s]*\d+\.\s+/gm, '')
-    .replace(/\|/g, ' ')
-    .replace(/^[-:]+$/gm, '')
-    .replace(/\n{3,}/g, '\n\n')
-    .trim();
-}
-
-/**
- * Generate annotated markdown by diffing original MD against Word text
- */
-export function generateAnnotatedDiff(originalMd: string, wordText: string, author: string = 'Reviewer'): string {
-  const normalizedOriginal = normalizeWhitespace(originalMd);
-  const normalizedWord = normalizeWhitespace(wordText);
-
-  const changes = diffWords(normalizedOriginal, normalizedWord);
-
-  let result = '';
-
-  for (const part of changes) {
-    if (part.added) {
-      result += `{++${part.value}++}`;
-    } else if (part.removed) {
-      result += `{--${part.value}--}`;
-    } else {
-      result += part.value;
-    }
-  }
-
-  return result;
-}
-
-/**
- * Inject Word tables (extracted from XML) into pandoc text output
- */
-function injectWordTables(pandocText: string, wordTables: WordTable[]): string {
-  if (!wordTables || wordTables.length === 0) {
-    return pandocText;
-  }
-
-  let result = pandocText;
-
-  for (const table of wordTables) {
-    const firstLine = table.markdown.split('\n')[0];
-    const headerCells = firstLine
-      .split('|')
-      .map((c) => c.trim())
-      .filter((c) => c.length > 0);
-
-    if (headerCells.length === 0) continue;
-
-    const firstCell = headerCells[0];
-    const startIdx = result.indexOf(firstCell);
-
-    if (startIdx === -1) continue;
-
-    const lastLine = table.markdown.split('\n').pop();
-    const lastCells = lastLine!
-      .split('|')
-      .map((c) => c.trim())
-      .filter((c) => c.length > 0);
-    const lastCell = lastCells[lastCells.length - 1] || lastCells[0];
-
-    const endIdx = result.indexOf(lastCell, startIdx);
-    if (endIdx === -1) continue;
-
-    let regionStart = result.lastIndexOf('\n\n', startIdx);
-    if (regionStart === -1) regionStart = 0;
-    else regionStart += 2;
-
-    let regionEnd = result.indexOf('\n\n', endIdx + lastCell.length);
-    if (regionEnd === -1) regionEnd = result.length;
-
-    result = result.slice(0, regionStart) + table.markdown + '\n\n' + result.slice(regionEnd);
-  }
-
-  return result;
-}
-
-/**
- * Smart paragraph-level diff that preserves markdown structure
- */
-export function generateSmartDiff(
-  originalMd: string,
-  wordText: string,
-  author: string = 'Reviewer',
-  options: GenerateSmartDiffOptions = {}
-): string {
-  const { wordTables = [], imageRegistry = null } = options;
-
-  // Inject Word tables into pandoc output
-  let wordTextWithTables = injectWordTables(wordText, wordTables);
-
-  // Protect markdown tables
-  const { text: mdWithTablesProtected, tables } = protectTables(originalMd);
-
-  // Also protect tables in Word text
-  const { text: wordWithTablesProtected, tables: wordTableBlocks } = protectTables(wordTextWithTables);
-
-  // Protect images
-  const { text: mdWithImagesProtected, images: origImages } = protectImages(mdWithTablesProtected, imageRegistry);
-
-  const { text: wordWithImagesProtected, images: wordImages } = protectImages(wordWithTablesProtected, imageRegistry);
-
-  // Match Word images to original images
-  const imageMapping = matchWordImagesToOriginal(origImages, wordImages, imageRegistry);
-
-  // Replace Word image placeholders with matching original placeholders
-  let wordWithMappedImages = wordWithImagesProtected;
-  for (const [wordPlaceholder, origPlaceholder] of imageMapping) {
-    wordWithMappedImages = wordWithMappedImages.split(wordPlaceholder).join(origPlaceholder);
-  }
-
-  // Protect figure/table anchors
-  const { text: mdWithAnchorsProtected, anchors: figAnchors } = protectAnchors(mdWithImagesProtected);
-
-  // Protect cross-references
-  const { text: mdWithXrefsProtected, crossrefs } = protectCrossrefs(mdWithAnchorsProtected);
-
-  // Protect math
-  const { text: mdWithMathProtected, mathBlocks } = protectMath(mdWithXrefsProtected);
-
-  // Protect citations
-  const { text: mdProtected, citations } = protectCitations(mdWithMathProtected);
-
-  // Replace rendered elements in Word text
-  let wordProtected = wordWithMappedImages;
-  wordProtected = replaceRenderedMath(wordProtected, mathBlocks);
-  wordProtected = replaceRenderedCitations(wordProtected, citations.length);
-
-  // Split into paragraphs
-  const originalParas = mdProtected.split(/\n\n+/);
-  const wordParas = wordProtected.split(/\n\n+/);
-
-  const result: string[] = [];
-
-  // Try to match paragraphs intelligently
-  let wordIdx = 0;
-
-  for (let i = 0; i < originalParas.length; i++) {
-    const orig = originalParas[i] || '';
-    const { prefix: mdPrefix, content: origContent } = extractMarkdownPrefix(orig.split('\n')[0]);
-
-    // Find best matching word paragraph
-    let bestMatch = -1;
-    let bestScore = 0;
-
-    for (let j = wordIdx; j < Math.min(wordIdx + 3, wordParas.length); j++) {
-      const wordPara = wordParas[j] || '';
-      const origWords = new Set(origContent.toLowerCase().split(/\s+/));
-      const wordWords = wordPara.toLowerCase().split(/\s+/);
-      const common = wordWords.filter((w) => origWords.has(w)).length;
-      const score = common / Math.max(origWords.size, wordWords.length);
-
-      if (score > bestScore && score > 0.3) {
-        bestScore = score;
-        bestMatch = j;
-      }
-    }
-
-    if (bestMatch === -1) {
-      if (mdPrefix && wordIdx < wordParas.length) {
-        const wordPara = wordParas[wordIdx];
-        if (wordPara.toLowerCase().includes(origContent.toLowerCase().slice(0, 20))) {
-          bestMatch = wordIdx;
-        }
-      }
-    }
-
-    if (bestMatch >= 0) {
-      const word = wordParas[bestMatch];
-
-      const origStripped = stripMarkdownSyntax(orig);
-      const wordNormalized = normalizeWhitespace(word);
-
-      if (origStripped === wordNormalized) {
-        result.push(orig);
-      } else {
-        const changes = diffWords(origStripped, wordNormalized);
-        let annotated = mdPrefix;
-
-        for (const part of changes) {
-          if (part.added) {
-            annotated += `{++${part.value}++}`;
-          } else if (part.removed) {
-            annotated += `{--${part.value}--}`;
-          } else {
-            annotated += part.value;
-          }
-        }
-
-        result.push(annotated);
-      }
-
-      wordIdx = bestMatch + 1;
-    } else {
-      // Paragraph deleted entirely
-      if (mdPrefix && mdPrefix.match(/^#{1,6}\s+/)) {
-        result.push(orig);
-      } else {
-        result.push(`{--${orig}--}`);
-      }
-    }
-  }
-
-  // Any remaining word paragraphs are additions
-  for (let j = wordIdx; j < wordParas.length; j++) {
-    const word = wordParas[j];
-    if (word.trim()) {
-      result.push(`{++${word}++}`);
-    }
-  }
-
-  // Restore protected content
-  let finalResult = result.join('\n\n');
-  finalResult = restoreCitations(finalResult, citations);
-  finalResult = restoreMath(finalResult, mathBlocks);
-  finalResult = restoreCrossrefs(finalResult, crossrefs);
-  finalResult = restoreAnchors(finalResult, figAnchors);
-  finalResult = restoreImages(finalResult, origImages);
-  finalResult = restoreImages(finalResult, wordImages);
-  finalResult = restoreTables(finalResult, tables);
-  finalResult = restoreTables(finalResult, wordTableBlocks);
-
-  return finalResult;
-}
-
-/**
- * Clean up redundant adjacent annotations
- */
-export function cleanupAnnotations(text: string): string {
-  // Convert adjacent delete+insert to substitution
-  text = text.replace(/\{--(.+?)--\}\s*\{\+\+(.+?)\+\+\}/g, '{~~$1~>$2~~}');
-
-  // Also handle insert+delete
-  text = text.replace(/\{\+\+(.+?)\+\+\}\s*\{--(.+?)--\}/g, '{~~$2~>$1~~}');
-
-  // Fix malformed patterns
-  text = text.replace(/\{--([^}]+?)~>([^}]+?)~~\}/g, '{~~$1~>$2~~}');
-
-  // Fix malformed substitutions that got split
-  text = text.replace(/\{~~([^~]+)\s*--\}/g, '{--$1--}');
-  text = text.replace(/\{\+\+([^+]+)~~\}/g, '{++$1++}');
-
-  // Clean up empty annotations
-  text = text.replace(/\{--\s*--\}/g, '');
-  text = text.replace(/\{\+\+\s*\+\+\}/g, '');
-
-  // Clean up double spaces in prose, but preserve table formatting
-  const lines = text.split('\n');
-  let inTable = false;
-
-  const processedLines = lines.map((line, idx) => {
-    const isSeparator = /^[-]+(\s+[-]+)+\s*$/.test(line.trim());
-
-    const looksLikeTableRow = /\S+\s{2,}\S+/.test(line);
-
-    if (isSeparator) {
-      if (!inTable) {
-        inTable = true;
-      }
-      return line;
-    }
-
-    if (inTable) {
-      if (line.trim() === '') {
-        let lookAhead = idx + 1;
-        let foundTableContent = false;
-        let foundEndSeparator = false;
-
-        while (lookAhead < lines.length && lookAhead < idx + 20) {
-          const nextLine = lines[lookAhead].trim();
-
-          if (nextLine === '') {
-            lookAhead++;
-            continue;
-          }
-
-          if (/^[-]+(\s+[-]+)+\s*$/.test(nextLine)) {
-            foundEndSeparator = true;
-            break;
-          }
-
-          if (/\S+\s{2,}\S+/.test(nextLine)) {
-            foundTableContent = true;
-            break;
-          }
-
-          if (/^\*[^*]+\*\s*$/.test(nextLine)) {
-            foundTableContent = true;
-            break;
-          }
-
-          if (lines[lookAhead].startsWith('  ')) {
-            lookAhead++;
-            continue;
-          }
-
-          break;
-        }
-
-        if (foundTableContent || foundEndSeparator) {
-          return line;
-        }
-
-        inTable = false;
-        return line;
-      }
-
-      return line;
-    }
-
-    if (looksLikeTableRow) {
-      let nextIdx = idx + 1;
-      while (nextIdx < lines.length && lines[nextIdx].trim() === '') {
-        nextIdx++;
-      }
-      if (nextIdx < lines.length && /^[-]+(\s+[-]+)+\s*$/.test(lines[nextIdx].trim())) {
-        return line;
-      }
-    }
-
-    if (line.trim().startsWith('|')) {
-      return line;
-    }
-
-    return line.replace(/  +/g, ' ');
-  });
-  text = processedLines.join('\n');
-
-  return text;
-}
-
-/**
- * Parse visible comment markers from Word text
- */
-export function parseVisibleComments(text: string): Array<{ author: string; text: string; position: number }> {
-  const comments: Array<{ author: string; text: string; position: number }> = [];
-  const pattern = /\[([^\]:]+):\s*([^\]]+)\]/g;
-
-  let match;
-  while ((match = pattern.exec(text)) !== null) {
-    comments.push({
-      author: match[1].trim(),
-      text: match[2].trim(),
-      position: match.index,
-    });
-  }
-
-  return comments;
-}
-
-/**
- * Convert visible comments to CriticMarkup format
- */
-export function convertVisibleComments(text: string): string {
-  return text.replace(/\[([^\]:]+):\s*([^\]]+)\]/g, '{>>$1: $2<<}');
-}
-
-/**
- * Restore pandoc-crossref figure/table references from Word-rendered format
- */
-export function restoreCrossrefFromWord(
-  text: string,
-  projectDir: string,
-  restoredLabels: Set<string> | null = null
-): RestoreCrossrefResult {
-  const messages: string[] = [];
-  let restored = 0;
-  let result = text;
-
-  const registry = readImageRegistry(projectDir);
-
-  if (!restoredLabels) {
-    restoredLabels = new Set<string>();
-  }
-
-  // Pattern 1: [Figure]{.mark} [N]{.mark}
-  result = result.replace(/\[(Figure|Table|Fig\.?)\]\{\.mark\}\s*\[(\d+|S\d+)\]\{\.mark\}/gi, (match, type, num) => {
-    const prefix = type.toLowerCase().startsWith('tab') ? 'tbl' : 'fig';
-    if (registry) {
-      const entry = registry.byNumber?.get(`${prefix}:${num}`);
-      if (entry && entry.label) {
-        restored++;
-        return `@${prefix}:${entry.label}`;
-      }
-    }
-    restored++;
-    messages.push(`Restored ${type} ${num} (no label found, using placeholder)`);
-    return `@${prefix}:fig${num}`;
-  });
-
-  // Pattern 2: Plain "Figure N" or "Fig. N"
-  result = result.replace(/(?<!!)\b(Figure|Fig\.?|Table|Tbl\.?)\s+(\d+|S\d+)\b(?!\s*:)/gi, (match, type, num) => {
-    const prefix = type.toLowerCase().startsWith('tab') ? 'tbl' : 'fig';
-    if (registry) {
-      const entry = registry.byNumber?.get(`${prefix}:${num}`);
-      if (entry && entry.label) {
-        restored++;
-        return `@${prefix}:${entry.label}`;
-      }
-    }
-    return match;
-  });
-
-  // Pattern 3: Remove duplicate plain-text captions
-  result = result.replace(/(\!\[[^\]]+\]\([^)]+\)(?:\{[^}]*\})?)\s*\n+\s*(?:Figure|Fig\.?|Table|Tbl\.?)\s+\d+[:\.]?\s*[^\n]+/gi, '$1');
-
-  // Pattern 4: Clean up image captions that start with "Figure N: "
-  result = result.replace(/!\[(Figure|Fig\.?|Table|Tbl\.?)\s+(\d+|S\d+)[:\.]?\s*([^\]]*)\]\(([^)]+)\)(?:\{[^}]*\})?/gi,
-    (match, type, num, caption, imgPath) => {
-      const prefix = type.toLowerCase().startsWith('tab') ? 'tbl' : 'fig';
-      const labelKey = `${prefix}:${num}`;
-
-      if (registry) {
-        const entry = registry.byNumber?.get(labelKey);
-        if (entry) {
-          if (restoredLabels!.has(labelKey)) {
-            messages.push(`Skipped duplicate ${prefix}:${entry.label} (already restored)`);
-            return `![${entry.caption}](${entry.path})`;
-          }
-          restoredLabels!.add(labelKey);
-          restored++;
-          messages.push(`Restored image ${prefix}:${entry.label} from Figure ${num}`);
-          return `![${entry.caption}](${entry.path}){#${prefix}:${entry.label}}`;
-        }
-      }
-      const cleanCaption = caption.trim();
-      return `![${cleanCaption}](${imgPath})`;
-    });
-
-  return { text: result, restored, messages, restoredLabels };
-}
-
-/**
- * Restore proper markdown image syntax from Word-extracted text using image registry
- */
-export function restoreImagesFromRegistry(
-  text: string,
-  projectDir: string,
-  restoredLabels: Set<string> | null = null
-): RestoreImagesResult {
-  const messages: string[] = [];
-  let restored = 0;
-
-  const registry = readImageRegistry(projectDir);
-  if (!registry || !registry.figures || registry.figures.length === 0) {
-    return { text, restored: 0, messages: ['No image registry found'] };
-  }
-
-  if (!restoredLabels) {
-    restoredLabels = new Set<string>();
-  }
-
-  let result = text;
-
-  // Pattern 1: Caption-like text
-  const captionPatterns = [
-    /@(fig|tbl):([a-zA-Z0-9_-]+):\s*([^\n]+)/gi,
-    /^(Figure|Fig\.?)\s+(\d+|S\d+)[.:]\s*([^\n]+)/gim,
-    /\|\s*@(fig|tbl):([a-zA-Z0-9_-]+):\s*([^|]+)\s*\|/gi,
-  ];
-
-  // Fix @fig:label: caption patterns
-  result = result.replace(captionPatterns[0], (match, type, label, caption) => {
-    const key = `${type}:${label}`;
-    const entry = registry.byLabel.get(key);
-    if (entry) {
-      if (restoredLabels!.has(key)) {
-        messages.push(`Skipped duplicate ${key} (already restored)`);
-        return `![${entry.caption}](${entry.path})`;
-      }
-      restoredLabels!.add(key);
-      restored++;
-      messages.push(`Restored ${type}:${label} from registry`);
-      return `![${entry.caption}](${entry.path}){#${type}:${label}}`;
-    }
-    return match;
-  });
-
-  // Fix table-wrapped captions
-  result = result.replace(captionPatterns[2], (match, type, label, caption) => {
-    const key = `${type}:${label}`;
-    const entry = registry.byLabel.get(key);
-    if (entry) {
-      if (restoredLabels!.has(key)) {
-        messages.push(`Skipped duplicate ${key} from table wrapper`);
-        return `![${entry.caption}](${entry.path})`;
-      }
-      restoredLabels!.add(key);
-      restored++;
-      messages.push(`Restored ${type}:${label} from table wrapper`);
-      return `![${entry.caption}](${entry.path}){#${type}:${label}}`;
-    }
-    return match;
-  });
-
-  // Clean up empty table structures
-  result = result.replace(/\|\s*\|\s*\n\|:--:\|\s*\n/g, '');
-
-  // Fix "Figure N:" standalone lines
-  result = result.replace(captionPatterns[1], (match, prefix, num, caption) => {
-    const numKey = `fig:${num}`;
-    const entry = registry.byNumber.get(numKey);
-    if (entry) {
-      const labelKey = `fig:${entry.label}`;
-      if (restoredLabels!.has(labelKey)) {
-        messages.push(`Skipped duplicate Figure ${num} (already restored)`);
-        return `![${entry.caption}](${entry.path})`;
-      }
-      restoredLabels!.add(labelKey);
-      restored++;
-      messages.push(`Restored Figure ${num} by number lookup`);
-      return `![${entry.caption}](${entry.path}){#fig:${entry.label}}`;
-    }
-    return match;
-  });
-
-  // Fix generic media paths by matching caption text
-  const genericImagePattern = /!\[([^\]]*)\]\(media\/[^)]+\)/g;
-  result = result.replace(genericImagePattern, (match, caption) => {
-    if (!caption || caption.trim() === '') {
-      return match;
-    }
-
-    const captionKey = caption.slice(0, 50).toLowerCase().trim();
-    const entry = registry.byCaption.get(captionKey);
-    if (entry) {
-      const labelKey = entry.label ? `${entry.type}:${entry.label}` : null;
-      if (labelKey && restoredLabels!.has(labelKey)) {
-        messages.push(`Skipped duplicate by caption match: ${captionKey.slice(0, 30)}...`);
-        return `![${entry.caption}](${entry.path})`;
-      }
-      if (labelKey) {
-        restoredLabels!.add(labelKey);
-      }
-      restored++;
-      messages.push(`Restored image by caption match: ${captionKey.slice(0, 30)}...`);
-      const anchor = (entry.label && !restoredLabels!.has(labelKey!)) ? `{#${entry.type}:${entry.label}}` : '';
-      return `![${entry.caption}](${entry.path})${anchor}`;
-    }
-    return match;
-  });
-
-  return { text: result, restored, messages };
-}
-
 /**
  * Import Word document with track changes directly as CriticMarkup
  */