@ansonlai/docx-redline-js 0.2.0 → 0.4.0

package/AGENTS.md

@@ -54,7 +54,9 @@ const result = await applyRedlineToOxml(oxml, originalText, modifiedText, {
 
 `existingRevisions` defaults to `'reject-input'`. Use `'accept-all-first'` only
 when the caller intentionally wants to accept prior tracked changes before
-applying a new edit.
+applying a new edit. A no-op still returns the untouched input; use
+`'accept-all-first-keep-normalized'` only when accepted revisions should be
+returned as a real change even without a new redline.
 
 ### Apply a text edit without tracked changes
 
@@ -111,11 +113,24 @@ const removedAll = deleteCommentsByAuthorInOoxml(packageOrDocumentOoxml, { allAu
 ### Apply multiple operations to full document XML
 
 ```js
-import { applyOperationToDocumentXml } from '@ansonlai/docx-redline-js/services/standalone-operation-runner.js';
-const result = await applyOperationToDocumentXml(documentXml, operation, options);
+import {
+  applyOperationToDocumentXml,
+  applyOperationsToDocumentXml
+} from '@ansonlai/docx-redline-js/services/standalone-operation-runner.js';
+
+const result = await applyOperationsToDocumentXml(documentXml, operations, 'Agent', runtimeContext, options);
 ```
 
-Use `result.documentXml` from this API when replacing full `word/document.xml`.
+Use `result.documentXml` from these APIs when replacing full `word/document.xml`.
+For mixed batches, prefer `applyOperationsToDocumentXml(...)`; it applies comments
+before replacements so earlier edits cannot invalidate their anchors.
+
+Batches are atomic by default. If any operation fails, the batch returns the
+original `documentXml`, `hasChanges: false`, no comment/numbering artifacts, and
+`rolledBack: true`; `results` still describes every attempted operation because
+`continueOnError` defaults to `true`. Pass `{ atomic: false }` only when a
+partially applied document is intentional. Pass `{ continueOnError: false }` to
+stop attempting operations after the first error.
 
 ### Detect existing tracked changes
 
@@ -195,7 +210,9 @@ orchestration/
 {
   generateRedlines: true,
   author: 'Name',
-  existingRevisions: 'reject-input'
+  existingRevisions: 'reject-input',
+  removeFormatting: false,
+  sanitizeInput: false
 }
 ```
 
@@ -213,8 +230,13 @@ orchestration/
 }
 ```
 
-Known error codes include `PARSE_ERROR`, `TARGET_NOT_FOUND`, and
-`EXISTING_REVISIONS`.
+Known error codes include `PARSE_ERROR`, `TARGET_NOT_FOUND`, `PARTIAL_TARGET`,
+`EXISTING_REVISIONS`, `DIFF_TOKEN_LIMIT`, and `BATCH_OPERATION_FAILED`.
+
+For ingestion that must distinguish an empty document from malformed OOXML,
+use `ingestWordOoxmlToPlainTextResult` or
+`ingestWordOoxmlToMarkdownResult`. The legacy ingestion helpers intentionally
+retain their string-only return type and return `''` for parse failures.
 
 ### OOXML wrapping for Word insertOoxml scenarios
 
@@ -242,9 +264,13 @@ directly into `word/document.xml`.
 5. `useNativeApi: true` means standalone mode cannot fully handle that operation path.
 6. `deleteCommentsByAuthorInOoxml` removes matching `comments.xml` entries and linked comment anchors/references in the document.
 7. If output begins with `<pkg:package`, treat it as package-level OOXML and normalize it before writing anything back to `word/document.xml`.
-8. Existing revisions are rejected by default; pass `existingRevisions: 'accept-all-first'` only when that is desired.
-9. Hyperlinks, bookmarks, comment markers, tabs/breaks, and footnote/endnote references are structural OOXML and should survive adjacent redline edits.
-10. Internally, create Word elements through `createWordElement` and tracked-change metadata through `createRevisionMetadata`.
+8. Existing revisions are rejected by default; `accept-all-first` preserves the original OOXML on no-op, while `accept-all-first-keep-normalized` explicitly returns normalization as a change.
+9. Caller content is not sanitized by default. Pass `sanitizeInput: true` only for raw assistant output; literal dollar delimiters and `\\n` sequences are never rewritten.
+10. Hyperlinks, bookmarks, comment markers, tabs/breaks, and footnote/endnote references are structural OOXML and should survive adjacent redline edits.
+11. Internally, create Word elements through `createWordElement` and tracked-change metadata through `createRevisionMetadata`.
+12. Revision IDs are document-scoped in public operation paths. Thread the
+    internal allocator through new string-serialization paths; generated
+    `w:id` values are not stable across documents.
 
 ## Validation Commands
 

package/README.md

@@ -120,14 +120,21 @@ Common `applyRedlineToOxml` options:
 |--------|---------|
 | `generateRedlines` | When `true`, emit Word-native tracked changes; when `false`, apply clean text changes. |
 | `author` | Track-change author used for generated revisions. |
-| `existingRevisions` | Policy for source OOXML that already contains tracked changes: `'reject-input'` (default) returns `status: 'error'` with code `EXISTING_REVISIONS`; `'accept-all-first'` accepts existing revisions before applying the new edit. |
+| `existingRevisions` | Existing-revision policy. `'reject-input'` is the default. `'accept-all-first'` normalizes before a real edit but returns the untouched input on no-op. `'accept-all-first-keep-normalized'` explicitly returns accepted revisions as a change even on no-op. |
+| `removeFormatting` | When `true` and the text is unchanged with no Markdown hints, explicitly remove existing bold/italic/underline/strikethrough formatting. Defaults to `false`. |
+| `sanitizeInput` | Opt-in removal of a standalone leading assistant-preface line. Defaults to `false`; dollar-delimited text and literal `\\n` sequences are always preserved. |
 
 Common result fields:
 
 | Field | Purpose |
 |-------|---------|
 | `status` | Optional non-breaking status: `'ok'`, `'no-op'`, or `'error'`. |
-| `error` | Present when `status === 'error'`; includes a stable `code` such as `PARSE_ERROR`, `TARGET_NOT_FOUND`, or `EXISTING_REVISIONS`. |
+| `error` | Present when `status === 'error'`; includes a stable `code` such as `PARSE_ERROR`, `TARGET_NOT_FOUND`, `PARTIAL_TARGET`, `EXISTING_REVISIONS`, `DIFF_TOKEN_LIMIT`, or `BATCH_OPERATION_FAILED`. |
+
+Word diffs are deterministic by default (no wall-clock timeout). Inputs above
+the safe ceiling of 262,144 unique diff tokens return `DIFF_TOKEN_LIMIT` with
+the original OOXML unchanged so callers can split the operation without risking
+silent text loss.
 
 ### Pipeline (lower-level access)
 
@@ -136,6 +143,8 @@ Common result fields:
 | `ReconciliationPipeline` | Direct pipeline access (ingest, diff, patch, serialize). |
 | `ingestWordOoxmlToPlainText(oxml)` | Extract plain text from OOXML. |
 | `ingestWordOoxmlToMarkdown(oxml)` | Convert OOXML to markdown. |
+| `ingestWordOoxmlToPlainTextResult(oxml)` | Extract text as `{ text, status, error?, warnings? }`, distinguishing malformed input from an empty document. |
+| `ingestWordOoxmlToMarkdownResult(oxml)` | Markdown counterpart to the result-returning plain-text helper. |
 | `ingestOoxml(oxml)` | Flatten OOXML into an internal run model with offsets. |
 | `preprocessMarkdown(text)` | Normalize markdown and extract format hints. |
 | `containsTrackedChanges(xmlDoc)` | Detect `w:ins`, `w:del`, move revisions, property changes, and paragraph-mark revision markup in a parsed OOXML document/fragment. |
@@ -155,15 +164,34 @@ Common result fields:
 | `ensureCommentsArtifactsInZip(zip, commentsXml)` | Merge comments artifacts into a `.docx` package. |
 | `validateDocxPackage(zip)` | Validate `.docx` structural consistency. |
 
+Malformed OOXML never escapes these public transform APIs as a raw parser
+exception. Transforms return `status: 'error'` with `error.code === 'PARSE_ERROR'`;
+validators return a `PARSE_ERROR` issue. Recoverable XML parser
+diagnostics are forwarded through the configured logger and included in
+`warnings` where the result shape supports them.
+
 ### Deep Imports
 
 For advanced usage, import specific submodules:
 
 ```js
-import { applyOperationToDocumentXml } from '@ansonlai/docx-redline-js/services/standalone-operation-runner.js';
+import {
+  applyOperationToDocumentXml,
+  applyOperationsToDocumentXml,
+  orderOperationsForStableTargets
+} from '@ansonlai/docx-redline-js/services/standalone-operation-runner.js';
 import { getParagraphText } from '@ansonlai/docx-redline-js/core/paragraph-targeting.js';
 ```
 
+Use `applyOperationsToDocumentXml(...)` for mixed batches. It stably runs comments before text-changing operations so replacements cannot invalidate their original anchors. Other operation types retain their relative order. Batch results retain each operation's original 1-based index and expose the actual `executionOrder`.
+
+Batches are atomic by default: any operation error returns the original
+`documentXml`, `hasChanges: false`, empty package artifacts, and
+`rolledBack: true`. The default `continueOnError: true` still attempts the full
+batch so `results` describes what would have applied. Callers that intentionally
+consume partial results must pass `{ atomic: false }`; use
+`{ continueOnError: false }` to stop after the first error.
+
 ### Output Shape Matrix
 
 Different APIs return different OOXML shapes. Use this as a packaging safety check.
@@ -174,12 +202,14 @@ Different APIs return different OOXML shapes. Use this as a packaging safety che
 | `applyRedlineToOxmlWithListFallback(...)` | Paragraph or range-scope OOXML | `result.oxml` | Fragment, `<w:document>`, or package payload (`<pkg:package>`) | No. Inspect first. |
 | `reconcileMarkdownTableOoxml(...)` | Table or paragraph-scope OOXML | `result.oxml` | Same shapes as `applyRedlineToOxml(...)` for the supplied scope | No. Inspect first. |
 | `applyOperationToDocumentXml(...)` | Full `word/document.xml` string | `result.documentXml` | `<w:document>` | Yes. This is the document-safe helper. |
+| `applyOperationsToDocumentXml(...)` | Full `word/document.xml` plus an operation batch | `result.documentXml` | `<w:document>` | Yes. Atomic by default; comments are applied before text-changing operations. |
 | `extractReplacementNodesFromOoxml(...)` | Any OOXML payload | `{ replacementNodes, numberingXml, sourceType }` | Normalized to `fragment`, `document`, or `package` | Yes. Use this when consuming `result.oxml`. |
 
 ### Do / Don't for Packaging
 
 - Do use `applyOperationToDocumentXml(...).documentXml` when your intent is to replace `word/document.xml`.
-- Redline application now strips non-visible field scaffolding (`w:fldChar`, `w:instrText`) and proofing markers (`w:proofErr`) from the matched target paragraph before diffing, while preserving the visible field result text. This avoids a class of Word-open failures caused by tracked changes spanning hidden field instruction runs.
+- Do use `applyOperationsToDocumentXml(...)` rather than an unsorted loop for batches containing comments and replacements that target the same original paragraph.
+- Redline application strips proofing markers (`w:proofErr`) from the matched target paragraph before diffing, while preserving complex-field scaffolding (`w:fldChar`, `w:instrText`) and its cached visible result as inert structure. Adjacent edits do not revise or move an unchanged field result.
 - Hyperlinks, bookmarks, comment range markers, tabs/breaks, and footnote/endnote references are treated as structural OOXML that should survive adjacent redline edits instead of being orphaned or wrapped in deletions.
 - Do use `extractReplacementNodesFromOoxml(...)` when you are consuming `result.oxml` from paragraph/range/table APIs.
 - Do merge numbering/comments artifacts with `ensureNumberingArtifactsInZip(...)` and `ensureCommentsArtifactsInZip(...)` when those parts are present.
@@ -240,12 +270,17 @@ const output = await zip.generateAsync({ type: 'nodebuffer' });
 
 ## Validating Output
 
+For the test-lane design and instructions for adding regression, synthetic
+Word, and real-corpus cases, see [docs/TESTING.md](./docs/TESTING.md).
+
 Run the automated package checks:
 
 ```bash
 npm test
 npm run test:isolation
 npm run check:types
+npm run lint
+npm run test:coverage
 ```
 
 For release-time fixture export:
@@ -265,10 +300,29 @@ rejects the generated revisions and the resulting text is compared to the
 expected outcomes):
 
 ```bash
-node scripts/export-validation-fixtures.mjs
-npm run smoke:word:diff
+npm run test:word
 ```
 
+This Windows-only test command generates an English legal/administrative task
+suite under `tmp/word-validation/` and drives installed desktop Microsoft Word
+through COM. Its 33 cases include targeted reliability checks for literal
+content, multi-paragraph replacement, prior-revision no-op, atomic rollback,
+hostile revision IDs, bookmarks, internal hyperlinks, mixed formatted runs,
+content controls, table cells, structural tabs, locked complex fields,
+comments, footnotes/endnotes, headers/footers, and external hyperlinks.
+Structure-focused cases also assert required
+OOXML elements before Word independently checks Accept All and Reject All. The
+published library remains clean, host-independent JavaScript; Word automation
+exists only in development scripts.
+
+Use `npm run report:word:coverage` to print the validated task-by-structure
+matrix across all 33 synthetic and 31 SuperDoc scenarios. Before a release,
+`npm run review:word:prepare -- --cycle=0` creates a pending human-review
+manifest with changed cases, a rotating 20% synthetic sample, and legal plus
+administrative corpus representatives. See [docs/TESTING.md](./docs/TESTING.md)
+and [docs/WORD-MANUAL-REVIEW.md](./docs/WORD-MANUAL-REVIEW.md); preparation and
+AI preflight never count as human sign-off.
+
 A nightly GitHub Actions workflow additionally validates generated fixtures
 against the ECMA-376 transitional schemas (`xmllint`), opens them with
 LibreOffice, and runs an extended fuzz sweep of the accept/reject round-trip
@@ -281,3 +335,26 @@ See [ARCHITECTURE.md](./ARCHITECTURE.md) for module layout, data flow, and contr
 See [AGENTS.md](./AGENTS.md) for a concise reference for AI coding agents.
 
 See [docs/VALIDATION.md](./docs/VALIDATION.md) for release-time validation steps.
+
+See [docs/TESTING.md](./docs/TESTING.md) for how the test lanes work and how to
+add new cases.
+
+## Test Corpus Attribution
+
+Real-document reliability testing uses selected references from
+[docx-corpus](https://docxcorp.us/), built by
+[SuperDoc](https://superdoc.dev/). The dataset is licensed under the
+[Open Data Commons Attribution License (ODC-By) 1.0](https://opendatacommons.org/licenses/by/1-0/).
+
+Only explicitly pinned English legal and administrative documents are eligible
+for the initial corpus lane. References and provenance live in
+`tests/corpus/superdoc-english-legal-administrative.json`; downloaded documents
+are hash-verified and kept in ignored `tmp/` storage rather than committed. On
+Windows with desktop Word installed, run the reviewed 31-scenario/23-document lane with:
+
+```bash
+npm run test:corpus:word
+```
+
+ODC-By applies to the database; individual documents may carry additional
+rights, so each selected document must be reviewed before becoming a test case.

package/adapters/xml-adapter.js

@@ -3,10 +3,12 @@
  *
  * Default behavior uses browser-provided DOMParser/XMLSerializer.
  * Consumers can override these constructors for non-browser runtimes.
- */
-
-let _DOMParser = globalThis.DOMParser;
-let _XMLSerializer = globalThis.XMLSerializer;
+ */
+
+import { warn as logWarning, error as logError } from './logger.js';
+
+let _DOMParser = globalThis.DOMParser;
+let _XMLSerializer = globalThis.XMLSerializer;
 
 /**
  * Configures XML provider constructors.
@@ -25,14 +27,14 @@ export function configureXmlProvider(options = {}) {
  *
  * @returns {DOMParser}
  */
-export function createParser() {
+export function createParser(options = {}) {
     if (!_DOMParser && globalThis.DOMParser) {
         _DOMParser = globalThis.DOMParser;
     }
     if (!_DOMParser) {
         throw new Error('DOMParser is not configured. Call configureXmlProvider({ DOMParser, XMLSerializer }) first.');
     }
-    return new _DOMParser();
+    return new _DOMParser(options);
 }
 
 /**
@@ -57,10 +59,71 @@ export function createSerializer() {
  * @param {string} [contentType='text/xml'] - MIME type
  * @returns {Document}
  */
-export function parseXml(xmlString, contentType = 'text/xml') {
-    const parser = createParser();
-    return parser.parseFromString(xmlString, contentType);
-}
+export function parseXml(xmlString, contentType = 'text/xml') {
+    const result = parseOoxmlSafe(xmlString, contentType);
+    if (result.error) {
+        const parseError = new Error(result.error.message);
+        parseError.code = result.error.code;
+        throw parseError;
+    }
+    return result.doc;
+}
+
+function browserParseError(doc) {
+    if (!doc?.documentElement) return null;
+    if (String(doc.documentElement.localName || doc.documentElement.nodeName).toLowerCase() === 'parsererror') {
+        return doc.documentElement;
+    }
+    return doc.getElementsByTagName?.('parsererror')?.[0] || null;
+}
+
+/**
+ * Parses OOXML without allowing parser/provider exceptions to escape.
+ *
+ * `@xmldom/xmldom` reports recoverable diagnostics through `onError` and
+ * throws for fatal errors. Browser DOMParser implementations instead return a
+ * `<parsererror>` document. This helper normalizes both behaviors.
+ *
+ * @param {unknown} xmlString
+ * @param {string} [contentType='application/xml']
+ * @returns {{ doc: Document|null, error: {code:'PARSE_ERROR', message:string}|null, warnings: string[] }}
+ */
+export function parseOoxmlSafe(xmlString, contentType = 'application/xml') {
+    const warnings = [];
+    if (typeof xmlString !== 'string' || xmlString.trim() === '') {
+        return {
+            doc: null,
+            error: { code: 'PARSE_ERROR', message: 'Input is not a non-empty XML string.' },
+            warnings
+        };
+    }
+
+    const onError = (level, message) => {
+        const diagnostic = String(message || 'XML parser diagnostic.');
+        if (level === 'fatalError') {
+            logError('[XmlAdapter] XML fatal parse error:', diagnostic);
+        } else {
+            warnings.push(diagnostic);
+            logWarning(`[XmlAdapter] XML ${level || 'warning'}:`, diagnostic);
+        }
+    };
+
+    try {
+        const parser = createParser({ onError });
+        const doc = parser.parseFromString(xmlString, contentType);
+        const parseError = browserParseError(doc);
+        if (!doc?.documentElement || parseError) {
+            const message = parseError?.textContent || 'Could not parse XML input.';
+            logError('[XmlAdapter] XML parse error:', message);
+            return { doc: null, error: { code: 'PARSE_ERROR', message }, warnings };
+        }
+        return { doc, error: null, warnings };
+    } catch (caught) {
+        const message = caught?.message || String(caught || 'Could not parse XML input.');
+        logError('[XmlAdapter] XML parse error:', message);
+        return { doc: null, error: { code: 'PARSE_ERROR', message }, warnings };
+    }
+}
 
 /**
  * Serializes a node to XML text.

package/core/list-targeting.js

@@ -121,6 +121,9 @@ function shouldPromoteBulletInsertionsToChildDepth(parsedItems, normalizedTarget
     }
 
     if (firstItem?.kind === 'list' && firstItem.markerType === 'numbered') {
+        const firstLevel = firstItem.level || 0;
+        const alreadyIndented = trailingListItems.some(item => (item.level || 0) > firstLevel);
+        if (alreadyIndented) return false;
         return isNormalizedTextEqual(firstItem.text, normalizedTargetText);
     }
 

package/core/paragraph-targeting.js

@@ -9,6 +9,12 @@ function toArray(nodeList) {
     return Array.from(nodeList || []);
 }
 
+function createTargetNotFoundError(message) {
+    const error = new Error(message);
+    error.code = 'TARGET_NOT_FOUND';
+    return error;
+}
+
 export const WORD_MAIN_NS = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
 
 function getElementsByLocalName(node, localName) {
@@ -28,12 +34,29 @@ function getElementsByLocalName(node, localName) {
 }
 
 function toParagraphText(paragraph) {
-    const textNodes = getElementsByLocalName(paragraph, 't');
-    return textNodes.map(node => node.textContent || '').join('');
+    let text = '';
+
+    const visit = node => {
+        for (const child of toArray(node?.childNodes)) {
+            if (child?.nodeType !== 1) continue;
+            const localName = String(child.localName || child.nodeName || '').replace(/^.*:/, '');
+            if (localName === 't') {
+                text += child.textContent || '';
+            } else if (localName === 'tab') {
+                text += '\t';
+            } else {
+                visit(child);
+            }
+        }
+    };
+
+    visit(paragraph);
+    return text;
 }
 
 /**
- * Reads visible text from a paragraph by concatenating `w:t` nodes.
+ * Reads visible text from a paragraph by concatenating `w:t` nodes and mapping
+ * structural `w:tab` elements to a literal tab character.
  *
  * @param {Element|null|undefined} paragraph - OOXML paragraph node
  * @returns {string}
@@ -313,9 +336,9 @@ export function resolveTargetParagraph(xmlDoc, options = {}) {
         if (fuzzyMatch) return { paragraph: fuzzyMatch, resolvedBy: 'fuzzy_text' };
     }
 
-    if (cleanTargetText) throw new Error(`Target paragraph not found: "${cleanTargetText}"`);
-    if (parsedRef) throw new Error(`Target paragraph reference not found: [P${parsedRef}]`);
-    throw new Error('Operation target missing: provide "target" text or "targetRef" ([P#]).');
+    if (cleanTargetText) throw createTargetNotFoundError(`Target paragraph not found: "${cleanTargetText}"`);
+    if (parsedRef) throw createTargetNotFoundError(`Target paragraph reference not found: [P${parsedRef}]`);
+    throw createTargetNotFoundError('Operation target missing: provide "target" text or "targetRef" ([P#]).');
 }
 
 function isParagraphInTable(paragraph) {
@@ -444,7 +467,10 @@ export function resolveTargetParagraphWithSnapshot(xmlDoc, options = {}) {
         return { paragraph: bestCandidate.paragraph, resolvedBy: 'strict_text_after_ref_drift' };
     }
 
-    return resolved;
+    throw createTargetNotFoundError(
+        `Target paragraph [P${parsedRef}] no longer matches its batch-start anchor.`
+    );
+
 }
 
 /**

package/core/redline-validation.js

@@ -85,6 +85,28 @@ export function validateRedlineOoxml(oxml) {
     const delElements = elementsByLocalName(doc, 'del');
     const revisions = insElements.concat(delElements);
 
+    // Paragraphs cannot contain other paragraphs (CT_P has no w:p child).
+    for (const paragraph of elementsByLocalName(doc, 'p')) {
+        const nested = Array.from(paragraph.getElementsByTagName('*'))
+            .find(el => el !== paragraph && localNameOf(el) === 'p');
+        if (nested) {
+            addIssue('NESTED_PARAGRAPH', 'error', `<${paragraph.nodeName}> contains nested <${nested.nodeName}>.`);
+        }
+    }
+
+    // Body-level section properties must be the final body element.
+    for (const body of elementsByLocalName(doc, 'body')) {
+        const children = Array.from(body.childNodes || []).filter(child => child.nodeType === 1);
+        const sectPrIndexes = children
+            .map((child, index) => localNameOf(child) === 'sectPr' ? index : -1)
+            .filter(index => index >= 0);
+        if (sectPrIndexes.length > 1) {
+            addIssue('MULTIPLE_BODY_SECTPR', 'error', '<w:body> contains multiple direct <w:sectPr> elements.');
+        } else if (sectPrIndexes.length === 1 && sectPrIndexes[0] !== children.length - 1) {
+            addIssue('SECTPR_NOT_LAST', 'error', '<w:sectPr> is not the last element child of <w:body>.');
+        }
+    }
+
     // No w:ins/w:del nested inside another w:ins/w:del.
     for (const revision of revisions) {
         const nested = Array.from(revision.getElementsByTagName('*'))

package/core/types.js

@@ -157,15 +157,116 @@ export function escapeXml(str) {
         .replace(/'/g, ''');
 }
 
-// Global revision ID counter for track changes
-let revisionIdCounter = 1000;
+const DEFAULT_REVISION_ID_START = 1000;
+const MAX_PRACTICAL_REVISION_ID = 2147483647;
+const REVISION_ID_SAFETY_MARGIN = 10000;
+const REVISION_ELEMENT_NAMES = new Set([
+    'ins',
+    'del',
+    'moveFrom',
+    'moveTo',
+    'rPrChange',
+    'pPrChange',
+    'cellIns',
+    'cellDel',
+    'comment'
+]);
+const revisionAllocatorByDocument = new WeakMap();
+
+function isRevisionIdElement(element) {
+    if (!element || element.nodeType !== 1) return false;
+    const localName = String(element.localName || element.nodeName || '').replace(/^.*:/, '');
+    if (!REVISION_ELEMENT_NAMES.has(localName)) return false;
+    return !element.namespaceURI || element.namespaceURI === NS_W || String(element.nodeName || '').startsWith('w:');
+}
+
+function readWordId(element) {
+    const raw = element?.getAttributeNS?.(NS_W, 'id')
+        || element?.getAttribute?.('w:id')
+        || element?.getAttribute?.('id');
+    const parsed = Number.parseInt(String(raw ?? ''), 10);
+    return Number.isInteger(parsed) && parsed >= 0 ? parsed : null;
+}
+
+/**
+ * Document-scoped allocator for Word revision IDs.
+ */
+export class RevisionIdAllocator {
+    constructor(startValue = DEFAULT_REVISION_ID_START) {
+        this.startValue = Number.isInteger(startValue) && startValue >= 0
+            ? startValue
+            : DEFAULT_REVISION_ID_START;
+        this.nextId = this.startValue;
+        this.occupiedIds = new Set();
+    }
+
+    seed(xmlDoc) {
+        let maxFound = -1;
+        const elements = Array.from(xmlDoc?.getElementsByTagName?.('*') || []);
+        if (xmlDoc?.nodeType === 1) elements.unshift(xmlDoc);
+
+        for (const element of elements) {
+            if (!isRevisionIdElement(element)) continue;
+            const id = readWordId(element);
+            if (id == null) continue;
+            this.occupiedIds.add(id);
+            maxFound = Math.max(maxFound, id);
+        }
+
+        const highRiskBoundary = MAX_PRACTICAL_REVISION_ID - REVISION_ID_SAFETY_MARGIN;
+        this.nextId = maxFound >= highRiskBoundary
+            ? this.startValue
+            : Math.max(this.nextId, maxFound + 1);
+        this.advanceToAvailableId();
+        return this.nextId;
+    }
+
+    advanceToAvailableId() {
+        const highRiskBoundary = MAX_PRACTICAL_REVISION_ID - REVISION_ID_SAFETY_MARGIN;
+        if (this.nextId >= highRiskBoundary) this.nextId = this.startValue;
+        while (this.occupiedIds.has(this.nextId)) {
+            this.nextId += 1;
+            if (this.nextId >= highRiskBoundary) this.nextId = this.startValue;
+        }
+    }
+
+    next() {
+        this.advanceToAvailableId();
+        const id = this.nextId;
+        this.occupiedIds.add(id);
+        this.nextId += 1;
+        return id;
+    }
+}
+
+let defaultRevisionIdAllocator = new RevisionIdAllocator();
+
+export function setRevisionIdAllocatorForDocument(xmlNode, allocator) {
+    const xmlDoc = xmlNode?.nodeType === 9 ? xmlNode : xmlNode?.ownerDocument;
+    if (xmlDoc && allocator instanceof RevisionIdAllocator) {
+        revisionAllocatorByDocument.set(xmlDoc, allocator);
+    }
+    return allocator;
+}
+
+export function getRevisionIdAllocatorForDocument(xmlNode) {
+    const xmlDoc = xmlNode?.nodeType === 9 ? xmlNode : xmlNode?.ownerDocument;
+    return xmlDoc ? (revisionAllocatorByDocument.get(xmlDoc) || null) : null;
+}
+
+export function createRevisionIdAllocator(xmlDoc, startValue = DEFAULT_REVISION_ID_START) {
+    const allocator = new RevisionIdAllocator(startValue);
+    allocator.seed(xmlDoc);
+    setRevisionIdAllocatorForDocument(xmlDoc, allocator);
+    return allocator;
+}
 
 /**
  * Gets the next unique revision ID for track changes
  * @returns {number} Unique revision ID
  */
-export function getNextRevisionId() {
-    return revisionIdCounter++;
+export function getNextRevisionId() {
+    return defaultRevisionIdAllocator.next();
 }
 
 /**
@@ -182,15 +283,19 @@ export function getRevisionTimestamp(date = new Date()) {
  * Creates shared revision metadata for OOXML track-change tags.
  *
  * @param {string} [author] - Track-change author (defaults to configured default author)
+ * @param {RevisionIdAllocator|Document|Element|null} [allocatorOrNode] - Scoped allocator or registered OOXML node
  * @returns {{ id: number, author: string, date: string }}
  */
-export function createRevisionMetadata(author) {
+export function createRevisionMetadata(author, allocatorOrNode = null) {
     const resolvedAuthor = typeof author === 'string' && author.trim()
         ? author.trim()
         : getDefaultAuthor();
+    const allocator = allocatorOrNode instanceof RevisionIdAllocator
+        ? allocatorOrNode
+        : (getRevisionIdAllocatorForDocument(allocatorOrNode) || defaultRevisionIdAllocator);
 
     return {
-        id: getNextRevisionId(),
+        id: allocator.next(),
         author: resolvedAuthor,
         date: getRevisionTimestamp()
     };
@@ -200,32 +305,22 @@ export function createRevisionMetadata(author) {
  * Seeds the revision ID counter above any existing Word revision/comment id values.
  *
  * @param {Document|Element} xmlDoc - Parsed OOXML document or element
+ * @param {RevisionIdAllocator} [allocator=defaultRevisionIdAllocator] - Allocator to seed
  * @returns {number} Next revision id after seeding
  */
-export function seedRevisionIdsFromDocument(xmlDoc) {
-    let maxFound = -1;
-    const elements = Array.from(xmlDoc?.getElementsByTagName?.('*') || []);
-
-    for (const element of elements) {
-        for (const attr of Array.from(element.attributes || [])) {
-            if ((attr.localName || '').toLowerCase() !== 'id') continue;
-            const parsed = Number.parseInt(attr.value, 10);
-            if (Number.isFinite(parsed)) {
-                maxFound = Math.max(maxFound, parsed);
-            }
-        }
-    }
-
-    if (maxFound >= revisionIdCounter) {
-        revisionIdCounter = maxFound + 1;
-    }
-    return revisionIdCounter;
+export function seedRevisionIdsFromDocument(xmlDoc, allocator = defaultRevisionIdAllocator) {
+    const resolvedAllocator = allocator instanceof RevisionIdAllocator
+        ? allocator
+        : defaultRevisionIdAllocator;
+    const nextId = resolvedAllocator.seed(xmlDoc);
+    setRevisionIdAllocatorForDocument(xmlDoc, resolvedAllocator);
+    return nextId;
 }
 
 /**
  * Resets the revision ID counter (for testing)
  * @param {number} [startValue=1000] - Value to reset to
  */
-export function resetRevisionIdCounter(startValue = 1000) {
-    revisionIdCounter = startValue;
-}
+export function resetRevisionIdCounter(startValue = 1000) {
+    defaultRevisionIdAllocator = new RevisionIdAllocator(startValue);
+}

package/core/xml-query.js

@@ -89,7 +89,9 @@ export function getFirstElementByTagNSOrTag(node, namespaceUri, localName, fallb
 }
 
 /**
- * Returns XML parser error element if present.
+ * Returns XML parser error element if present. This is a browser DOMParser
+ * compatibility probe; xmldom reports diagnostics through `parseOoxmlSafe`
+ * and does not normally create `<parsererror>` elements.
  *
  * @param {Document|Element|null|undefined} xmlDoc - Parsed XML document
  * @returns {Element|null}