@ansonlai/docx-redline-js 0.8.3 → 0.9.0

package/scripts/word-com-visual-suite.ps1

@@ -67,11 +67,11 @@ function Export-View($word, [string]$docxPath, [string]$pdfPath, [string]$viewNa
     try {
         $document = $word.Documents.OpenNoRepairDialog($docxPath)
         if ($viewName -eq 'acceptAll') {
-            $document.AcceptAllRevisions()
+            $document.Revisions.AcceptAll()
             $exportItem = 0 # wdExportDocumentContent
         }
         elseif ($viewName -eq 'rejectAll') {
-            $document.RejectAllRevisions()
+            $document.Revisions.RejectAll()
             $exportItem = 0
         }
         else {

package/scripts/word-revision-semantics-matrix.ps1

@@ -0,0 +1,108 @@
+param(
+    [string]$FixturesDir = "tests/fixtures/word-revision-semantics"
+)
+
+# Run with pwsh (PowerShell 7): Windows PowerShell 5.1 hangs in SaveAs2 over COM here.
+# Records what desktop Word does on Reject All / Accept All for each paragraph-mark
+# revision shape in cases.json, and writes expectations.json (checked in). Run
+# `node scripts/generate-word-revision-semantics-matrix.mjs` first.
+
+$ErrorActionPreference = 'Stop'
+$FixturesDir = (Resolve-Path $FixturesDir).Path
+$cases = Get-Content (Join-Path $FixturesDir 'cases.json') -Raw -Encoding UTF8 | ConvertFrom-Json
+$work = Join-Path ([System.IO.Path]::GetTempPath()) ("word-rev-sem-" + [guid]::NewGuid().ToString('N'))
+New-Item -ItemType Directory -Path $work | Out-Null
+
+Add-Type -AssemblyName System.IO.Compression.FileSystem
+
+function Convert-Text([string]$t) {
+    $t = $t -replace [string][char]7, ''
+    $t = $t -replace [string][char]11, "`n"
+    $t = $t -replace "`r", ''
+    return $t
+}
+
+function Get-XmlParagraphCount([string]$path) {
+    $zip = [System.IO.Compression.ZipFile]::OpenRead($path)
+    try {
+        $entry = $zip.GetEntry('word/document.xml')
+        $reader = New-Object System.IO.StreamReader($entry.Open())
+        $xml = $reader.ReadToEnd(); $reader.Close()
+        return ([regex]::Matches($xml, '<w:p[ >/]')).Count
+    } finally { $zip.Dispose() }
+}
+
+function Get-Snapshot($doc) {
+    $items = @()
+    $count = $doc.Paragraphs.Count
+    for ($i = 1; $i -le $count; $i++) {
+        $p = $doc.Paragraphs.Item($i)
+        $r = $p.Range
+        $raw = [string]$r.Text
+        $inTable = [bool]$r.Information(12)
+        # End-of-row marks surface as paragraphs with text "\r\a" and no cell; skip them.
+        if ($inTable -and $raw -eq ("`r" + [char]7)) {
+            $cellCount = 0
+            try { $cellCount = $r.Cells.Count } catch { $cellCount = 0 }
+            if ($cellCount -eq 0) { continue }
+        }
+        $items += [ordered]@{
+            text = (Convert-Text $raw)
+            style = [string]$p.Style.NameLocal
+            listType = [int]$r.ListFormat.ListType
+            listString = [string]$r.ListFormat.ListString
+            inTable = $inTable
+        }
+    }
+    return ,$items
+}
+
+function Invoke-Mode($word, [string]$src, [string]$mode, [string]$name) {
+    $copy = Join-Path $work "$name-$mode.docx"
+    Copy-Item $src $copy
+    $doc = $word.Documents.Open($copy, $false, $false)
+    try {
+        $doc.TrackRevisions = $false
+        $before = $doc.Revisions.Count
+        if ($mode -eq 'reject') { $doc.Revisions.RejectAll() } else { $doc.Revisions.AcceptAll() }
+        $snap = Get-Snapshot $doc
+        $out = Join-Path $work "$name-$mode-out.docx"
+        $doc.SaveAs2($out, 16)
+    } finally { $doc.Close($false) }
+    return @{ paragraphs = $snap; xmlParagraphs = (Get-XmlParagraphCount $out); revisionsBefore = $before }
+}
+
+$word = New-Object -ComObject Word.Application
+try {
+    $word.Visible = $false
+    $word.DisplayAlerts = 0
+    $results = @()
+    foreach ($case in $cases) {
+        $src = Join-Path $FixturesDir ($case.name + '.docx')
+        $rej = Invoke-Mode $word $src 'reject' $case.name
+        $acc = Invoke-Mode $word $src 'accept' $case.name
+        Write-Output ("{0}: revisions={1} reject={2}p accept={3}p" -f $case.name, $rej.revisionsBefore, $rej.paragraphs.Count, $acc.paragraphs.Count)
+        $results += [ordered]@{
+            name = $case.name
+            description = $case.description
+            bodyXml = $case.bodyXml
+            revisionsBefore = $rej.revisionsBefore
+            reject = $rej.paragraphs
+            accept = $acc.paragraphs
+            rejectXmlParagraphs = $rej.xmlParagraphs
+            acceptXmlParagraphs = $acc.xmlParagraphs
+        }
+    }
+    $doc = [ordered]@{
+        wordVersion = [string]$word.Version
+        wordBuild = [string]$word.Build
+        generatedAt = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ')
+        cases = $results
+    }
+    $json = $doc | ConvertTo-Json -Depth 8
+    [System.IO.File]::WriteAllText((Join-Path $FixturesDir 'expectations.json'), $json + "`n", (New-Object System.Text.UTF8Encoding($false)))
+} finally {
+    try { $word.Quit(0) } catch {}
+    [void][System.Runtime.InteropServices.Marshal]::ReleaseComObject($word)
+    Remove-Item $work -Recurse -Force -ErrorAction SilentlyContinue
+}

package/services/batch-operation-orchestrator.js

@@ -24,6 +24,7 @@ import {
     reconcileReceiptsAgainstOutput
 } from './receipt-collector.js';
 import { compileOperationBatch } from './operation-batch-compiler.js';
+import { createDynamicNumberingIdState } from './numbering-helpers.js';
 import { createRetryPlan } from './error-recovery.js';
 
 const NS_W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
@@ -126,6 +127,18 @@ export function buildOperationDependencyPlan(operations = []) {
         }
     }
 
+    // Compiler-fixed order: a list-format composed with a redline on the same paragraph runs after that redline.
+    for (let i = 0; i < list.length; i++) {
+        const runAfter = Array.isArray(list[i]?._compiledRunAfter) ? list[i]._compiledRunAfter : [];
+        for (const producerIndex of runAfter) {
+            if (!Number.isInteger(producerIndex) || producerIndex < 0 || producerIndex >= list.length || producerIndex === i) continue;
+            if (dependencies[i].has(producerIndex)) continue;
+            dependencies[i].add(producerIndex);
+            dependents[producerIndex].add(i);
+            inDegrees[i]++;
+        }
+    }
+
     for (const [captureRef, consumers] of mutatingCaptureConsumers) {
         if (consumers.length < 2) continue;
         const selectors = consumers.map(consumer => consumer.select);
@@ -368,7 +381,18 @@ export async function applyOperationsToDocumentXml(documentXml, operations, auth
 
     const atomic = options.atomic === true;
     const continueOnError = options.continueOnError !== false;
+    // Generated list definitions must not collide with the supplied source numbering part.
+    // Always seed a state (bare document.xml has no numbering part) to match the packaged facade.
+    if (runtimeContext && typeof runtimeContext === 'object' && !runtimeContext.numberingIdState) {
+        const seedXml = typeof runtimeContext.numberingXml === 'string' && runtimeContext.numberingXml.trim()
+            ? runtimeContext.numberingXml
+            : undefined;
+        runtimeContext.numberingIdState = createDynamicNumberingIdState(seedXml);
+    }
     const context = cloneBatchRuntimeContext(runtimeContext);
+    if (!context.numberingIdState) {
+        context.numberingIdState = createDynamicNumberingIdState(undefined);
+    }
     if (!(context.targetRefSnapshot instanceof Map)) {
         context.targetRefSnapshot = session.initialTargetReferenceSnapshot;
     }
@@ -452,10 +476,12 @@ export async function applyOperationsToDocumentXml(documentXml, operations, auth
                 ...(result.resolvedTarget ? { resolvedTarget: result.resolvedTarget } : {}),
                 ...(result.resolvedAnchor ? { resolvedAnchor: result.resolvedAnchor } : {}),
                 ...(result.change ? { change: result.change } : {}),
+                ...(result.list && !isError ? { list: result.list } : {}),
                 ...(result.operationType === 'comment_resolve' && !isError
                     ? { resolved: result.resolved, threadRootId: result.threadRootId, commentIds: result.commentIds }
                     : {}),
                 ...(Array.isArray(result.warnings) && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
+                ...(Array.isArray(result.diagnostics) && result.diagnostics.length > 0 ? { diagnostics: result.diagnostics } : {}),
                 ...(result.error ? { error: result.error } : {}),
                 ...(result.receipt ? { receipt: result.receipt } : {})
             });

package/services/capture-engine.js

@@ -1,226 +1,228 @@
-/**
- * Capture entity management, resolution, and validation for batch operations.
- */
-
-import { NS_W } from '../core/types.js';
-import {
-    createParagraphFingerprint,
-    getDocumentParagraphNodes,
-    getParagraphId,
-    findContainingWordElement
-} from '../core/paragraph-targeting.js';
-import { extractCanonicalParagraphText } from '../core/paragraph-text.js';
-
-function createCaptureError(code, message) {
-    const error = new Error(message);
-    error.code = code;
-    return error;
-}
-
-export function ensureParagraphIdsOnImportedNode(_node, _session) {
-    // Preserves existing paragraph attributes without injecting undeclared namespaces into the document.
-}
-
-/**
- * Derives a serializable CapturedEntity record from the live DOM nodes produced by an operation.
- *
- * @param {import('./document-operation-session.js').DocumentOperationSession} session
- * @param {object} operation
- * @param {Array<Element>} liveNodes
- * @returns {object} CapturedEntity
- */
-export function deriveCapturedEntity(session, operation, liveNodes) {
-    const paragraphs = [];
-    let hasTable = false;
-    let hasList = false;
-
-    for (const node of (liveNodes || [])) {
-        if (!node) continue;
-        if (node.localName === 'tbl') {
-            hasTable = true;
-            paragraphs.push(...Array.from(node.getElementsByTagNameNS(NS_W, 'p')));
-        } else if (node.localName === 'p') {
-            if (node.getElementsByTagNameNS(NS_W, 'numPr').length > 0) {
-                hasList = true;
-            }
-            paragraphs.push(node);
-        }
-    }
-
-    const kind = hasTable
-        ? 'table'
-        : (hasList ? 'list' : (paragraphs.length > 1 ? 'range' : 'paragraph'));
-
-    const generatedParagraphIds = [];
-    const fingerprints = [];
-    const expectedText = [];
-    const structuralPathHints = [];
-
-    const xmlDoc = session.document;
-    const allDocParagraphs = getDocumentParagraphNodes(xmlDoc);
-
-    for (const p of paragraphs) {
-        const paraId = getParagraphId(p) || '';
-        generatedParagraphIds.push(paraId);
-        const text = extractCanonicalParagraphText(p);
-        expectedText.push(text);
-        const pIndex = allDocParagraphs.indexOf(p) + 1;
-        fingerprints.push(createParagraphFingerprint(p, {
-            text,
-            paragraphId: paraId || null,
-            index: pIndex > 0 ? pIndex : undefined,
-            inTable: hasTable || !!findContainingWordElement(p, 'tbl')
-        }));
-        const parentTag = p.parentNode?.localName || 'body';
-        structuralPathHints.push(`${parentTag}/${p.localName}`);
-    }
-
-    return {
-        captureKey: operation.captureKey,
-        operationIndex: typeof operation.index === 'number' ? operation.index : 0,
-        kind,
-        generatedParagraphIds,
-        fingerprints,
-        expectedText,
-        structuralPathHints,
-        stale: false
-    };
-}
-
-/**
- * Invalidates any captures in the session capture table that referenced removed or replaced paragraphs.
- *
- * @param {Map<string, object>} captureTable
- * @param {Array<Element>} removedNodes
- */
-export function invalidateAffectedCaptures(captureTable, removedNodes) {
-    if (!captureTable || !(captureTable instanceof Map) || !Array.isArray(removedNodes) || removedNodes.length === 0) return;
-    const removedIds = new Set();
-    for (const node of removedNodes) {
-        if (!node) continue;
-        if (node.localName === 'p') {
-            const id = getParagraphId(node);
-            if (id) removedIds.add(id);
-        } else if (typeof node.getElementsByTagNameNS === 'function') {
-            for (const p of Array.from(node.getElementsByTagNameNS(NS_W, 'p'))) {
-                const id = getParagraphId(p);
-                if (id) removedIds.add(id);
-            }
-        }
-    }
-    if (removedIds.size === 0) return;
-    for (const [, captured] of captureTable) {
-        if (captured.stale) continue;
-        if (captured.generatedParagraphIds.some(id => id && removedIds.has(id))) {
-            captured.stale = true;
-        }
-    }
-}
-
-/**
- * Resolves a target paragraph from an existing capture in the session capture table.
- *
- * @param {Document} xmlDoc
- * @param {import('./document-operation-session.js').DocumentOperationSession} session
- * @param {object} targetDescriptor
- * @param {string} opType
- * @param {object} options
- * @returns {{ paragraph: Element, resolvedBy: 'capture' }}
- */
-export function resolveTargetFromCapture(xmlDoc, session, targetDescriptor, _opType = 'redline', _options = {}) {
-    const captureRef = targetDescriptor?.captureRef;
-    if (!captureRef) {
-        throw createCaptureError('INVALID_OPERATION', 'Operation target is missing captureRef.');
-    }
-
-    if (!session || !session.captureTable || !session.captureTable.has(captureRef)) {
-        throw createCaptureError('CAPTURE_NOT_FOUND', `Capture "${captureRef}" was not found in the session capture table.`);
-    }
-
-    const captured = session.captureTable.get(captureRef);
-    if (captured.stale) {
-        throw createCaptureError('CAPTURE_STALE', `Capture "${captureRef}" is stale; the captured content was modified or removed.`);
-    }
-
-    const metadataIndex = session.getParagraphMetadataIndex();
-    const liveParagraphs = [];
-
-    for (let i = 0; i < captured.expectedText.length; i++) {
-        const expectedParaId = captured.generatedParagraphIds[i];
-        const expected = captured.expectedText[i];
-        let foundNode = null;
-
-        if (expectedParaId && metadataIndex.byId.has(expectedParaId)) {
-            foundNode = metadataIndex.byId.get(expectedParaId).paragraph;
-        }
-
-        if (!foundNode) {
-            const candidate = metadataIndex.entries.find(entry =>
-                entry.text === expected || entry.fingerprint === captured.fingerprints[i]
-            );
-            if (candidate) foundNode = candidate.paragraph;
-        }
-
-        if (!foundNode || !foundNode.parentNode) {
-            captured.stale = true;
-            throw createCaptureError('CAPTURE_STALE', `Capture "${captureRef}" is stale; paragraph ${i + 1} was removed from the document.`);
-        }
-
-        const currentText = extractCanonicalParagraphText(foundNode);
-        if (currentText !== expected) {
-            captured.stale = true;
-            throw createCaptureError('CAPTURE_STALE', `Capture "${captureRef}" is stale; paragraph ${i + 1} content drifted from "${expected}" to "${currentText}".`);
-        }
-
-        liveParagraphs.push(foundNode);
-    }
-
-    if (liveParagraphs.length === 0) {
-        captured.stale = true;
-        throw createCaptureError('CAPTURE_STALE', `Capture "${captureRef}" is stale; no live paragraphs found.`);
-    }
-
-    const select = targetDescriptor.select;
-    if (select == null || select === '') {
-        if (liveParagraphs.length === 1) {
-            return { paragraph: liveParagraphs[0], resolvedBy: 'capture' };
-        }
-        throw createCaptureError(
-            'AMBIGUOUS_CAPTURE_SELECTION',
-            `Capture "${captureRef}" contains ${liveParagraphs.length} paragraphs; target.select is required to disambiguate.`
-        );
-    }
-
-    let matched = [];
-    const trimmedSelect = String(select).trim();
-    if (trimmedSelect === ':first' || trimmedSelect === 'first') {
-        matched = [liveParagraphs[0]];
-    } else if (trimmedSelect === ':last' || trimmedSelect === 'last') {
-        matched = [liveParagraphs[liveParagraphs.length - 1]];
-    } else if (/^\d+$/.test(trimmedSelect)) {
-        const index1Based = parseInt(trimmedSelect, 10);
-        if (index1Based >= 1 && index1Based <= liveParagraphs.length) {
-            matched = [liveParagraphs[index1Based - 1]];
-        }
-    } else {
-        const exactMatches = liveParagraphs.filter(p => extractCanonicalParagraphText(p).trim() === trimmedSelect);
-        if (exactMatches.length > 0) {
-            matched = exactMatches;
-        } else {
-            matched = liveParagraphs.filter(p => extractCanonicalParagraphText(p).includes(trimmedSelect));
-        }
-    }
-
-    if (matched.length === 0) {
-        throw createCaptureError('TARGET_NOT_FOUND', `Target selection "${select}" was not found in capture "${captureRef}".`);
-    }
-
-    if (matched.length > 1) {
-        throw createCaptureError(
-            'AMBIGUOUS_CAPTURE_SELECTION',
-            `Target selection "${select}" matched ${matched.length} paragraphs in capture "${captureRef}".`
-        );
-    }
-
-    return { paragraph: matched[0], resolvedBy: 'capture' };
-}
+/**
+ * Capture entity management, resolution, and validation for batch operations.
+ */
+
+import { NS_W } from '../core/types.js';
+import { getCurrentParagraphProperties } from '../core/current-properties.js';
+import {
+    createParagraphFingerprint,
+    getDocumentParagraphNodes,
+    getParagraphId,
+    findContainingWordElement
+} from '../core/paragraph-targeting.js';
+import { extractCanonicalParagraphText } from '../core/paragraph-text.js';
+
+function createCaptureError(code, message) {
+    const error = new Error(message);
+    error.code = code;
+    return error;
+}
+
+export function ensureParagraphIdsOnImportedNode(_node, _session) {
+    // Preserves existing paragraph attributes without injecting undeclared namespaces into the document.
+}
+
+/**
+ * Derives a serializable CapturedEntity record from the live DOM nodes produced by an operation.
+ *
+ * @param {import('./document-operation-session.js').DocumentOperationSession} session
+ * @param {object} operation
+ * @param {Array<Element>} liveNodes
+ * @returns {object} CapturedEntity
+ */
+export function deriveCapturedEntity(session, operation, liveNodes) {
+    const paragraphs = [];
+    let hasTable = false;
+    let hasList = false;
+
+    for (const node of (liveNodes || [])) {
+        if (!node) continue;
+        if (node.localName === 'tbl') {
+            hasTable = true;
+            paragraphs.push(...Array.from(node.getElementsByTagNameNS(NS_W, 'p')));
+        } else if (node.localName === 'p') {
+            // Current numPr only; a pPrChange snapshot does not make the captured paragraph a list.
+            if (getCurrentParagraphProperties(node).numPr) {
+                hasList = true;
+            }
+            paragraphs.push(node);
+        }
+    }
+
+    const kind = hasTable
+        ? 'table'
+        : (hasList ? 'list' : (paragraphs.length > 1 ? 'range' : 'paragraph'));
+
+    const generatedParagraphIds = [];
+    const fingerprints = [];
+    const expectedText = [];
+    const structuralPathHints = [];
+
+    const xmlDoc = session.document;
+    const allDocParagraphs = getDocumentParagraphNodes(xmlDoc);
+
+    for (const p of paragraphs) {
+        const paraId = getParagraphId(p) || '';
+        generatedParagraphIds.push(paraId);
+        const text = extractCanonicalParagraphText(p);
+        expectedText.push(text);
+        const pIndex = allDocParagraphs.indexOf(p) + 1;
+        fingerprints.push(createParagraphFingerprint(p, {
+            text,
+            paragraphId: paraId || null,
+            index: pIndex > 0 ? pIndex : undefined,
+            inTable: hasTable || !!findContainingWordElement(p, 'tbl')
+        }));
+        const parentTag = p.parentNode?.localName || 'body';
+        structuralPathHints.push(`${parentTag}/${p.localName}`);
+    }
+
+    return {
+        captureKey: operation.captureKey,
+        operationIndex: typeof operation.index === 'number' ? operation.index : 0,
+        kind,
+        generatedParagraphIds,
+        fingerprints,
+        expectedText,
+        structuralPathHints,
+        stale: false
+    };
+}
+
+/**
+ * Invalidates any captures in the session capture table that referenced removed or replaced paragraphs.
+ *
+ * @param {Map<string, object>} captureTable
+ * @param {Array<Element>} removedNodes
+ */
+export function invalidateAffectedCaptures(captureTable, removedNodes) {
+    if (!captureTable || !(captureTable instanceof Map) || !Array.isArray(removedNodes) || removedNodes.length === 0) return;
+    const removedIds = new Set();
+    for (const node of removedNodes) {
+        if (!node) continue;
+        if (node.localName === 'p') {
+            const id = getParagraphId(node);
+            if (id) removedIds.add(id);
+        } else if (typeof node.getElementsByTagNameNS === 'function') {
+            for (const p of Array.from(node.getElementsByTagNameNS(NS_W, 'p'))) {
+                const id = getParagraphId(p);
+                if (id) removedIds.add(id);
+            }
+        }
+    }
+    if (removedIds.size === 0) return;
+    for (const [, captured] of captureTable) {
+        if (captured.stale) continue;
+        if (captured.generatedParagraphIds.some(id => id && removedIds.has(id))) {
+            captured.stale = true;
+        }
+    }
+}
+
+/**
+ * Resolves a target paragraph from an existing capture in the session capture table.
+ *
+ * @param {Document} xmlDoc
+ * @param {import('./document-operation-session.js').DocumentOperationSession} session
+ * @param {object} targetDescriptor
+ * @param {string} opType
+ * @param {object} options
+ * @returns {{ paragraph: Element, resolvedBy: 'capture' }}
+ */
+export function resolveTargetFromCapture(xmlDoc, session, targetDescriptor, _opType = 'redline', _options = {}) {
+    const captureRef = targetDescriptor?.captureRef;
+    if (!captureRef) {
+        throw createCaptureError('INVALID_OPERATION', 'Operation target is missing captureRef.');
+    }
+
+    if (!session || !session.captureTable || !session.captureTable.has(captureRef)) {
+        throw createCaptureError('CAPTURE_NOT_FOUND', `Capture "${captureRef}" was not found in the session capture table.`);
+    }
+
+    const captured = session.captureTable.get(captureRef);
+    if (captured.stale) {
+        throw createCaptureError('CAPTURE_STALE', `Capture "${captureRef}" is stale; the captured content was modified or removed.`);
+    }
+
+    const metadataIndex = session.getParagraphMetadataIndex();
+    const liveParagraphs = [];
+
+    for (let i = 0; i < captured.expectedText.length; i++) {
+        const expectedParaId = captured.generatedParagraphIds[i];
+        const expected = captured.expectedText[i];
+        let foundNode = null;
+
+        if (expectedParaId && metadataIndex.byId.has(expectedParaId)) {
+            foundNode = metadataIndex.byId.get(expectedParaId).paragraph;
+        }
+
+        if (!foundNode) {
+            const candidate = metadataIndex.entries.find(entry =>
+                entry.text === expected || entry.fingerprint === captured.fingerprints[i]
+            );
+            if (candidate) foundNode = candidate.paragraph;
+        }
+
+        if (!foundNode || !foundNode.parentNode) {
+            captured.stale = true;
+            throw createCaptureError('CAPTURE_STALE', `Capture "${captureRef}" is stale; paragraph ${i + 1} was removed from the document.`);
+        }
+
+        const currentText = extractCanonicalParagraphText(foundNode);
+        if (currentText !== expected) {
+            captured.stale = true;
+            throw createCaptureError('CAPTURE_STALE', `Capture "${captureRef}" is stale; paragraph ${i + 1} content drifted from "${expected}" to "${currentText}".`);
+        }
+
+        liveParagraphs.push(foundNode);
+    }
+
+    if (liveParagraphs.length === 0) {
+        captured.stale = true;
+        throw createCaptureError('CAPTURE_STALE', `Capture "${captureRef}" is stale; no live paragraphs found.`);
+    }
+
+    const select = targetDescriptor.select;
+    if (select == null || select === '') {
+        if (liveParagraphs.length === 1) {
+            return { paragraph: liveParagraphs[0], resolvedBy: 'capture' };
+        }
+        throw createCaptureError(
+            'AMBIGUOUS_CAPTURE_SELECTION',
+            `Capture "${captureRef}" contains ${liveParagraphs.length} paragraphs; target.select is required to disambiguate.`
+        );
+    }
+
+    let matched = [];
+    const trimmedSelect = String(select).trim();
+    if (trimmedSelect === ':first' || trimmedSelect === 'first') {
+        matched = [liveParagraphs[0]];
+    } else if (trimmedSelect === ':last' || trimmedSelect === 'last') {
+        matched = [liveParagraphs[liveParagraphs.length - 1]];
+    } else if (/^\d+$/.test(trimmedSelect)) {
+        const index1Based = parseInt(trimmedSelect, 10);
+        if (index1Based >= 1 && index1Based <= liveParagraphs.length) {
+            matched = [liveParagraphs[index1Based - 1]];
+        }
+    } else {
+        const exactMatches = liveParagraphs.filter(p => extractCanonicalParagraphText(p).trim() === trimmedSelect);
+        if (exactMatches.length > 0) {
+            matched = exactMatches;
+        } else {
+            matched = liveParagraphs.filter(p => extractCanonicalParagraphText(p).includes(trimmedSelect));
+        }
+    }
+
+    if (matched.length === 0) {
+        throw createCaptureError('TARGET_NOT_FOUND', `Target selection "${select}" was not found in capture "${captureRef}".`);
+    }
+
+    if (matched.length > 1) {
+        throw createCaptureError(
+            'AMBIGUOUS_CAPTURE_SELECTION',
+            `Target selection "${select}" matched ${matched.length} paragraphs in capture "${captureRef}".`
+        );
+    }
+
+    return { paragraph: matched[0], resolvedBy: 'capture' };
+}