@ansonlai/docx-redline-js 0.2.0 → 0.4.0

package/scripts/render-multilevel-bullet-images.py

@@ -0,0 +1,58 @@
+import os
+import fitz
+from PIL import Image
+
+out_dir = r'tmp/multilevel-bullet-visual'
+os.makedirs(out_dir, exist_ok=True)
+
+cases = [
+    {
+        'id': 'synthetic-nested-child',
+        'dir': r'tmp/word-visual-review/rendered',
+        'prefix': 'administrative-list-change-nested-child',
+        'page': 0
+    },
+    {
+        'id': 'superdoc-board-agenda-multiple-children',
+        'dir': r'tmp/superdoc-word-visual-review/rendered',
+        'prefix': '38-administrative-administrative-list-change-board-agenda-multiple-children',
+        'page': 0
+    },
+    {
+        'id': 'superdoc-bylaws-nested-list-batch',
+        'dir': r'tmp/superdoc-word-visual-review/rendered',
+        'prefix': '28-legal-legal-bylaws-nested-list-batch',
+        'page': 0
+    }
+]
+
+views = ['allMarkup', 'acceptAll', 'rejectAll']
+
+for c in cases:
+    case_images = []
+    for v in views:
+        pdf_path = os.path.join(c['dir'], f"{c['prefix']}-{v}.pdf")
+        doc = fitz.open(pdf_path)
+        page = doc.load_page(c['page'])
+        pix = page.get_pixmap(dpi=150)
+        img_name = f"{c['id']}--{v}.png"
+        img_path = os.path.join(out_dir, img_name)
+        pix.save(img_path)
+        print(f"Saved {img_path} ({pix.width}x{pix.height})")
+        case_images.append(img_path)
+        doc.close()
+
+    # Create 3-view contact sheet
+    imgs = [Image.open(p) for p in case_images]
+    total_w = sum(im.width for im in imgs) + 40
+    max_h = max(im.height for im in imgs) + 20
+    sheet = Image.new('RGB', (total_w, max_h), (240, 240, 240))
+    x = 10
+    for im in imgs:
+        sheet.paste(im, (x, 10))
+        x += im.width + 10
+    sheet_path = os.path.join(out_dir, f"{c['id']}--contact-sheet.png")
+    sheet.save(sheet_path)
+    print(f"Saved contact sheet {sheet_path}")
+
+print("ALL MULTILEVEL VISUAL CASES RENDERED.")

package/scripts/render-multilevel-bullet-visual.ps1

@@ -0,0 +1,32 @@
+param(
+    [string]$DocxPath,
+    [string]$OutputDir
+)
+
+$ErrorActionPreference = 'Stop'
+$resolvedDocx = (Resolve-Path -LiteralPath $DocxPath).Path
+$resolvedOut = (Resolve-Path -LiteralPath $OutputDir).Path
+
+$word = New-Object -ComObject Word.Application
+$word.Visible = $false
+$word.DisplayAlerts = 0
+
+try {
+    foreach ($view in @('allMarkup', 'acceptAll', 'rejectAll')) {
+        $pdfPath = Join-Path $resolvedOut "multilevel-bullet--$view.pdf"
+        $doc = $word.Documents.OpenNoRepairDialog($resolvedDocx)
+        try {
+            if ($view -eq 'acceptAll') { $doc.AcceptAllRevisions(); $exportItem = 0 }
+            elseif ($view -eq 'rejectAll') { $doc.RejectAllRevisions(); $exportItem = 0 }
+            else { $doc.ShowRevisions = $true; $doc.PrintRevisions = $true; $exportItem = 7 }
+            $pages = $doc.ComputeStatistics(2)
+            $doc.ExportAsFixedFormat($pdfPath, 17, $false, 0, 0, 1, 1, $exportItem, $true, $true, 0, $true, $true, $false)
+            $item = Get-Item -LiteralPath $pdfPath
+            Write-Output "Rendered $view -> $pdfPath (pages=$pages, bytes=$($item.Length))"
+        } finally {
+            $doc.Close(0)
+        }
+    }
+} finally {
+    $word.Quit()
+}

package/scripts/render-multilevel-cases.mjs

@@ -0,0 +1,80 @@
+import fs from 'fs';
+import { spawnSync } from 'child_process';
+import { resolve } from 'path';
+
+const cases = [
+    '37-administrative-administrative-list-change-board-agenda-child',
+    '40-administrative-administrative-list-change-ppg-agenda-addition'
+];
+
+const fixtureDir = 'tmp/superdoc-word-fixtures';
+const visualDir = 'tmp/multilevel-bullet-visual';
+const brainArtifactDir = 'C:/Users/Phara/.gemini/antigravity-ide/brain/ee12439b-cade-4f45-ab6e-a2a7b1bf1610';
+
+if (!fs.existsSync(visualDir)) {
+    fs.mkdirSync(visualDir, { recursive: true });
+}
+
+for (const baseName of cases) {
+    console.log('\n=== Rendering Word COM for', baseName, '===');
+    const docxPath = `${fixtureDir}/${baseName}.docx`;
+    const acceptedDocx = `${fixtureDir}/${baseName}.accepted.docx`;
+    const rejectedDocx = `${fixtureDir}/${baseName}.rejected.docx`;
+
+    const psScript = `
+    $ErrorActionPreference = 'Stop'
+    $word = New-Object -ComObject Word.Application
+    $word.Visible = $false
+    $word.DisplayAlerts = 0
+    try {
+        Write-Output 'Rendering allMarkup...'
+        $doc = $word.Documents.OpenNoRepairDialog((Resolve-Path '${docxPath}').Path)
+        $doc.ShowRevisions = $true
+        $doc.PrintRevisions = $true
+        $doc.ExportAsFixedFormat((Resolve-Path '${visualDir}').Path + '/${baseName}--allMarkup.pdf', 17, $false, 0, 0, 1, 1, 7, $true, $true, 0, $true, $true, $false)
+        $doc.Close(0)
+
+        Write-Output 'Rendering acceptAll...'
+        $docAcc = $word.Documents.OpenNoRepairDialog((Resolve-Path '${acceptedDocx}').Path)
+        $docAcc.ExportAsFixedFormat((Resolve-Path '${visualDir}').Path + '/${baseName}--acceptAll.pdf', 17, $false, 0, 0, 1, 1, 0, $true, $true, 0, $true, $true, $false)
+        $docAcc.Close(0)
+
+        Write-Output 'Rendering rejectAll...'
+        $docRej = $word.Documents.OpenNoRepairDialog((Resolve-Path '${rejectedDocx}').Path)
+        $docRej.ExportAsFixedFormat((Resolve-Path '${visualDir}').Path + '/${baseName}--rejectAll.pdf', 17, $false, 0, 0, 1, 1, 0, $true, $true, 0, $true, $true, $false)
+        $docRej.Close(0)
+        Write-Output 'SUCCESS: Rendered all 3 views for ${baseName}.'
+    } finally {
+        $word.Quit()
+    }
+    `;
+
+    const psRes = spawnSync('powershell', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', psScript], { encoding: 'utf8' });
+    console.log(psRes.stdout);
+    if (psRes.stderr) console.error(psRes.stderr);
+
+    const pyScript = `
+import pymupdf
+import shutil
+views = ['allMarkup', 'acceptAll', 'rejectAll']
+base = '${baseName}'
+vis_dir = '${visualDir}'
+art_dir = '${brainArtifactDir}'
+
+for v in views:
+    pdf_file = f"{vis_dir}/{base}--{v}.pdf"
+    doc = pymupdf.open(pdf_file)
+    print(f"{base} {v} page count: {len(doc)}")
+    for i, page in enumerate(doc):
+        pix = page.get_pixmap(dpi=150)
+        out_png = f"{vis_dir}/{base}--{v}-p{i+1}.png"
+        pix.save(out_png)
+        art_png = f"{art_dir}/{base}--{v}-p{i+1}.png"
+        shutil.copyfile(out_png, art_png)
+        print(f"  Rendered {out_png} -> {art_png}")
+`;
+
+    const pyRes = spawnSync('tmp/visual-qa-venv/Scripts/python.exe', ['-c', pyScript], { encoding: 'utf8' });
+    console.log(pyRes.stdout);
+    if (pyRes.stderr) console.error(pyRes.stderr);
+}

package/scripts/report-coverage-gaps.mjs

@@ -0,0 +1,103 @@
+import { existsSync, readFileSync } from 'fs';
+import { relative, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const repoRoot = resolve(fileURLToPath(new URL('..', import.meta.url)));
+const coveragePath = resolve(repoRoot, 'coverage', 'coverage-final.json');
+const baselinePath = resolve(repoRoot, 'tests', 'coverage-data', 'phase3-baseline.json');
+const reviewedGapsPath = resolve(repoRoot, 'tests', 'coverage-data', 'phase3-reviewed-gaps.json');
+const productionRoots = ['index.js', 'adapters/', 'core/', 'engine/', 'pipeline/', 'services/', 'orchestration/'];
+const priorities = new Map([
+    ['services/numbering-helpers.js', 'P0'],
+    ['orchestration/route-plan.js', 'P0'],
+    ['orchestration/list-markdown.js', 'P0'],
+    ['pipeline/patching.js', 'P0'],
+    ['engine/format-span-application.js', 'P0'],
+    ['orchestration/list-structural-fallback.js', 'P1'],
+    ['engine/table-mode.js', 'P1'],
+    ['core/table-targeting.js', 'P1'],
+    ['services/standalone-operation-runner.js', 'P1'],
+    ['pipeline/pipeline.js', 'P1']
+]);
+
+if (!existsSync(coveragePath)) {
+    throw new Error('coverage/coverage-final.json is missing; run npm run test:coverage first');
+}
+
+const raw = JSON.parse(readFileSync(coveragePath, 'utf8'));
+const files = [];
+for (const [absolutePath, coverage] of Object.entries(raw)) {
+    const file = relative(repoRoot, absolutePath).replaceAll('\\', '/');
+    if (!productionRoots.some(root => root.endsWith('/') ? file.startsWith(root) : file === root)) continue;
+    const uncoveredFunctions = Object.entries(coverage.fnMap || {})
+        .filter(([id]) => (coverage.f?.[id] || 0) === 0)
+        .map(([, fn]) => ({ name: fn.name || '(anonymous)', line: fn.decl?.start?.line || fn.loc?.start?.line }));
+    const functionHits = Object.values(coverage.f || {});
+    const branchHits = Object.values(coverage.b || {}).flat();
+    files.push({
+        file,
+        priority: priorities.get(file) || 'P2',
+        functions: { covered: functionHits.filter(hits => hits > 0).length, total: functionHits.length },
+        branches: { covered: branchHits.filter(hits => hits > 0).length, total: branchHits.length },
+        uncoveredFunctions
+    });
+}
+files.sort((a, b) => a.priority.localeCompare(b.priority) || a.file.localeCompare(b.file));
+
+const baseline = existsSync(baselinePath) ? JSON.parse(readFileSync(baselinePath, 'utf8')) : null;
+const reviewedGaps = existsSync(reviewedGapsPath) ? JSON.parse(readFileSync(reviewedGapsPath, 'utf8')) : { items: [] };
+const regressions = [];
+if (baseline) {
+    const currentByFile = new Map(files.map(item => [item.file, item]));
+    for (const expected of baseline.targetFiles) {
+        const current = currentByFile.get(expected.file);
+        if (!current || current.functions.covered < expected.functionsCovered
+            || current.branches.covered < expected.branchesCovered) {
+            regressions.push({ expected, current: current || null });
+        }
+    }
+}
+
+const actualPriorityGaps = new Set(files
+    .filter(item => item.priority === 'P0' || item.priority === 'P1')
+    .flatMap(item => item.uncoveredFunctions.map(fn => `${item.file}:${fn.line}`)));
+const classifiedPriorityGaps = new Set((reviewedGaps.items || [])
+    .flatMap(item => (item.lines || []).map(line => `${item.file}:${line}`)));
+const classificationErrors = [
+    ...[...actualPriorityGaps]
+        .filter(key => !classifiedPriorityGaps.has(key))
+        .map(key => `Unclassified priority gap: ${key}`),
+    ...[...classifiedPriorityGaps]
+        .filter(key => !actualPriorityGaps.has(key))
+        .map(key => `Stale priority-gap classification: ${key}`)
+];
+
+const report = {
+    schemaVersion: 1,
+    production: {
+        functionsCovered: files.reduce((sum, item) => sum + item.functions.covered, 0),
+        functionsTotal: files.reduce((sum, item) => sum + item.functions.total, 0),
+        branchesCovered: files.reduce((sum, item) => sum + item.branches.covered, 0),
+        branchesTotal: files.reduce((sum, item) => sum + item.branches.total, 0)
+    },
+    files,
+    regressions,
+    classificationErrors
+};
+
+if (process.argv.includes('--json')) {
+    console.log(JSON.stringify(report, null, 2));
+} else {
+    console.log(`Production functions: ${report.production.functionsCovered}/${report.production.functionsTotal}`);
+    console.log(`Production branches: ${report.production.branchesCovered}/${report.production.branchesTotal}`);
+    for (const item of files.filter(file => file.uncoveredFunctions.length > 0)) {
+        console.log(`\n${item.priority} ${item.file} (${item.functions.covered}/${item.functions.total} functions, ${item.branches.covered}/${item.branches.total} branches)`);
+        for (const fn of item.uncoveredFunctions) console.log(`  ${fn.line}: ${fn.name}`);
+    }
+}
+
+if (regressions.length > 0 || classificationErrors.length > 0) {
+    console.error(`Coverage regression in ${regressions.length} targeted file(s)`);
+    for (const issue of classificationErrors) console.error(issue);
+    process.exitCode = 1;
+}

package/scripts/report-word-coverage.mjs

@@ -0,0 +1,71 @@
+import {
+    COVERAGE_STRUCTURES,
+    COVERAGE_TASKS,
+    loadCoverageCatalogue,
+    validateCoveragePriorities
+} from './lib/word-coverage-catalogue.mjs';
+
+const { cases, priorities } = loadCoverageCatalogue();
+const cells = validateCoveragePriorities(cases, priorities);
+const dispositionByCell = new Map(
+    priorities.emptyCellDispositions.map(item => [`${item.task}/${item.structure}`, item])
+);
+const highPriority = new Set(
+    priorities.highPriorityCells.map(item => `${item.task}/${item.structure}`)
+);
+
+const report = {
+    schemaVersion: 1,
+    totals: {
+        cases: cases.length,
+        synthetic: cases.filter(item => item.lane === 'synthetic').length,
+        superdoc: cases.filter(item => item.lane === 'superdoc').length,
+        manualMissing: cases.filter(item => item.metadata.manualReview.status === 'missing').length,
+        manualStale: cases.filter(item => item.metadata.manualReview.status === 'stale').length,
+        aiPreflight: cases.filter(item => item.metadata.oracles.includes('ai-word-visual-preflight')).length,
+        syntheticWord: cases.filter(item => item.metadata.oracles.includes('synthetic-word')).length,
+        realDocumentWord: cases.filter(item => item.metadata.oracles.includes('real-document-word')).length
+    },
+    tasks: COVERAGE_TASKS.map(task => ({
+        task,
+        structures: COVERAGE_STRUCTURES.map(structure => {
+            const key = `${task}/${structure}`;
+            return {
+                structure,
+                count: cells.get(key).length,
+                highPriority: highPriority.has(key),
+                disposition: dispositionByCell.get(key) || null,
+                cases: cells.get(key)
+            };
+        })
+    })),
+    missingVisualReview: cases
+        .filter(item => item.metadata.manualReview.status !== 'current')
+        .map(item => ({
+            identity: item.identity,
+            status: item.metadata.manualReview.status,
+            aiPreflight: item.metadata.oracles.includes('ai-word-visual-preflight')
+        }))
+};
+
+if (process.argv.includes('--json')) {
+    console.log(JSON.stringify(report, null, 2));
+} else {
+    console.log('# Word task/structure coverage matrix\n');
+    console.log(`Cases: ${report.totals.cases} (${report.totals.synthetic} synthetic, ${report.totals.superdoc} SuperDoc)`);
+    console.log(`Human review: ${report.totals.manualMissing} missing, ${report.totals.manualStale} stale\n`);
+    console.log(`Automated Word: ${report.totals.syntheticWord} synthetic, ${report.totals.realDocumentWord} real-document; AI visual preflight: ${report.totals.aiPreflight}\n`);
+    console.log(`| Task | ${COVERAGE_STRUCTURES.join(' | ')} |`);
+    console.log(`|---|${COVERAGE_STRUCTURES.map(() => '---:').join('|')}|`);
+    for (const row of report.tasks) {
+        console.log(`| ${row.task} | ${row.structures.map(cell => cell.count || '—').join(' | ')} |`);
+    }
+    console.log('\n## High-priority empty cells\n');
+    const empty = report.tasks.flatMap(row => row.structures
+        .filter(cell => cell.highPriority && cell.count === 0)
+        .map(cell => ({ task: row.task, ...cell })));
+    for (const cell of empty) {
+        console.log(`- ${cell.task} / ${cell.structure}: ${cell.disposition.status} — ${cell.disposition.reason} Dependency: ${cell.disposition.dependency}.`);
+    }
+    console.log('\nUse `--json` for stable machine-readable case identities and review status.');
+}

package/scripts/sample-multimodal-visual-check.mjs

@@ -0,0 +1,221 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { execFileSync } from 'child_process';
+import { generateContactSheetWithPyMuPdf, loadManifest } from './inspect-visual-evidence.mjs';
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const pythonVenvExe = join(repoRoot, 'tmp', 'visual-qa-venv', 'Scripts', 'python.exe');
+
+export function renderPdfPageToImage(pdfPath, outputPngPath, pageIndex = 0, dpi = 150) {
+    if (!existsSync(pythonVenvExe) || !existsSync(pdfPath)) {
+        return false;
+    }
+
+    const pythonScript = `
+import sys
+import fitz
+
+pdf_path = sys.argv[1]
+output_png = sys.argv[2]
+page_idx = int(sys.argv[3]) if len(sys.argv) > 3 else 0
+dpi = int(sys.argv[4]) if len(sys.argv) > 4 else 150
+
+doc = fitz.open(pdf_path)
+if page_idx < 0 or page_idx >= len(doc):
+    page_idx = 0
+page = doc.load_page(page_idx)
+pix = page.get_pixmap(dpi=dpi)
+pix.save(output_png)
+doc.close()
+`;
+
+    try {
+        execFileSync(pythonVenvExe, ['-c', pythonScript, pdfPath, outputPngPath, String(pageIndex), String(dpi)], {
+            stdio: 'pipe',
+            encoding: 'utf8'
+        });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+export function sampleScenarios(scenarios, count = 3, seed = null) {
+    const list = [...scenarios];
+    if (seed !== null) {
+        // Simple seeded pseudo-random shuffle (mulberry32)
+        let s = seed;
+        const random = () => {
+            s |= 0;
+            s = (s + 0x6D2B79F5) | 0;
+            let t = Math.imul(s ^ (s >>> 15), 1 | s);
+            t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+            return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+        };
+        for (let i = list.length - 1; i > 0; i--) {
+            const j = Math.floor(random() * (i + 1));
+            [list[i], list[j]] = [list[j], list[i]];
+        }
+    } else {
+        // Standard shuffle
+        for (let i = list.length - 1; i > 0; i--) {
+            const j = Math.floor(Math.random() * (i + 1));
+            [list[i], list[j]] = [list[j], list[i]];
+        }
+    }
+    return list.slice(0, count);
+}
+
+function parseCliArgs() {
+    const args = process.argv.slice(2);
+    const options = {
+        count: 3,
+        seed: null,
+        cases: null
+    };
+
+    for (const arg of args) {
+        if (arg.startsWith('--count=')) {
+            options.count = parseInt(arg.split('=')[1], 10) || 3;
+        } else if (arg.startsWith('--seed=')) {
+            options.seed = parseInt(arg.split('=')[1], 10) || 12345;
+        } else if (arg.startsWith('--cases=')) {
+            options.cases = arg.split('=')[1].split(',').map(s => s.trim()).filter(Boolean);
+        }
+    }
+
+    return options;
+}
+
+export function buildMultimodalSpotCheckSamples(options = {}) {
+    const corpusDir = join(repoRoot, 'tmp', 'superdoc-word-visual-review', 'rendered');
+    const corpusManifestPath = join(corpusDir, 'manifest.json');
+    const manifest = loadManifest(corpusManifestPath);
+
+    if (!manifest || !Array.isArray(manifest.cases)) {
+        throw new Error(`Corpus visual manifest not found at ${corpusManifestPath}. Run: npm run test:corpus:word:visual`);
+    }
+
+    const scenariosPath = join(repoRoot, 'tests', 'corpus', 'superdoc-word-scenarios.json');
+    const scenariosData = JSON.parse(readFileSync(scenariosPath, 'utf8'));
+    const scenarioMap = new Map();
+    for (const sc of scenariosData.scenarios) {
+        if (sc.name) scenarioMap.set(sc.name, sc);
+    }
+
+    // Filter or sample cases
+    let selectedCases = [];
+    if (options.cases && options.cases.length > 0) {
+        selectedCases = manifest.cases.filter(c =>
+            options.cases.some(target => c.identity?.includes(target) || c.name?.includes(target) || c.scenarioKey?.includes(target))
+        );
+    } else {
+        selectedCases = sampleScenarios(manifest.cases, options.count || 3, options.seed);
+    }
+
+    if (selectedCases.length === 0) {
+        throw new Error('No matching corpus visual cases found to sample.');
+    }
+
+    const outputDir = join(repoRoot, 'tmp', 'multimodal-visual-spot-checks');
+    const imagesDir = join(outputDir, 'images');
+    mkdirSync(imagesDir, { recursive: true });
+
+    const sampleManifest = {
+        createdAt: new Date().toISOString(),
+        sampleCount: selectedCases.length,
+        cases: []
+    };
+
+    let promptMarkdown = '# Multimodal LLM Visual Inspection Prompt Bundle\n\n';
+    promptMarkdown += '> **Role:** You are an expert document layout quality assessor evaluating Microsoft Word tracked change renderings.\n';
+    promptMarkdown += '> **Task:** Visually inspect the provided side-by-side renders across three views (`allMarkup`, `acceptAll`, `rejectAll`) to detect visual layout, table, list, or typographic defects.\n\n';
+
+    for (let i = 0; i < selectedCases.length; i++) {
+        const testCase = selectedCases[i];
+        const scenarioKey = testCase.scenarioKey || testCase.name;
+        const caseRecord = {
+            index: i + 1,
+            scenarioKey,
+            category: testCase.category,
+            shape: testCase.shape,
+            pages: testCase.views?.allMarkup?.pages || 1,
+            images: {}
+        };
+
+        promptMarkdown += `## Sample ${i + 1}: \`${scenarioKey}\`\n`;
+        promptMarkdown += `- **Category:** ${testCase.category} | **Shape:** ${testCase.shape}\n`;
+        promptMarkdown += `- **Document Length:** ${caseRecord.pages} page(s)\n\n`;
+
+        for (const viewName of ['allMarkup', 'acceptAll', 'rejectAll']) {
+            const viewInfo = testCase.views?.[viewName];
+            if (!viewInfo || !viewInfo.pdf) continue;
+
+            const pdfPath = join(corpusDir, viewInfo.pdf);
+            const highResImageName = `${scenarioKey}--${viewName}--page1.png`;
+            const highResImagePath = join(imagesDir, highResImageName);
+            const sheetImageName = `${scenarioKey}--${viewName}--sheet.png`;
+            const sheetImagePath = join(imagesDir, sheetImageName);
+
+            // Render high-res page 1
+            renderPdfPageToImage(pdfPath, highResImagePath, 0, 150);
+            // Render contact sheet (up to 6 pages)
+            generateContactSheetWithPyMuPdf(pdfPath, sheetImagePath, 6);
+
+            caseRecord.images[viewName] = {
+                highRes: highResImagePath,
+                sheet: sheetImagePath
+            };
+
+            promptMarkdown += `### View: \`${viewName}\`\n`;
+            promptMarkdown += `- High-Res Page 1: \`${highResImagePath}\`\n`;
+            promptMarkdown += `- Contact Sheet: \`${sheetImagePath}\`\n\n`;
+        }
+
+        promptMarkdown += '### Visual Inspection Questions:\n';
+        promptMarkdown += '1. **Markup Visibility & Isolation (`allMarkup`):** Are tracked insertions (underlined/colored) and deletions (strikethrough) clearly visible and cleanly localized, without wrapping or clipping adjacent text?\n';
+        promptMarkdown += '2. **Accepted State Correctness (`acceptAll`):** Does the document render cleanly without any leftover deletion markers or awkward spacing?\n';
+        promptMarkdown += '3. **Rejected State Fidelity (`rejectAll`):** Does the page restore the exact original layout, fonts, and numbering without ghost bullets or shifted margins?\n';
+        promptMarkdown += '4. **Structural & Table Integrity:** Did table column widths, grid lines, background fills, or list indents remain stable across all three views?\n\n';
+        promptMarkdown += '---\n\n';
+
+        sampleManifest.cases.push(caseRecord);
+    }
+
+    const manifestOutPath = join(outputDir, 'sample-manifest.json');
+    const promptOutPath = join(outputDir, 'multimodal-prompt.md');
+
+    writeFileSync(manifestOutPath, JSON.stringify(sampleManifest, null, 2), 'utf8');
+    writeFileSync(promptOutPath, promptMarkdown, 'utf8');
+
+    return {
+        sampleManifest,
+        outputDir,
+        manifestOutPath,
+        promptOutPath
+    };
+}
+
+async function runCli() {
+    console.log('=== Multimodal Visual Spot Check Sample Generator ===\n');
+    const options = parseCliArgs();
+
+    try {
+        const result = buildMultimodalSpotCheckSamples(options);
+        console.log(`Generated ${result.sampleManifest.sampleCount} multimodal inspection samples:`);
+        for (const c of result.sampleManifest.cases) {
+            console.log(`  - [Sample ${c.index}] ${c.scenarioKey} (${c.category}, ${c.shape}, ${c.pages} pages)`);
+        }
+        console.log(`\nManifest: ${result.manifestOutPath}`);
+        console.log(`Prompt bundle: ${result.promptOutPath}`);
+    } catch (err) {
+        console.error('Error generating multimodal samples:', err.message);
+        process.exit(1);
+    }
+}
+
+const isCli = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isCli) {
+    runCli();
+}