@ansonlai/docx-redline-js 0.1.4 → 0.2.0

package/AGENTS.md

@@ -16,10 +16,12 @@ Input: (paragraph OOXML, original text, modified text, options)
 Engine routes to: format-only | surgical | reconstruction | list | table mode
   |
   v
-Output: { oxml: string, hasChanges: boolean, warnings?: string[] }
+Output: { oxml: string, hasChanges: boolean, status?: string, error?: object, warnings?: string[] }
 ```
 
-The engine works at paragraph scope. For full-document operations, callers iterate paragraph targets or use the standalone operation runner.
+The engine usually works at paragraph/range/table scope. For full-document
+operations, use the standalone operation runner so the result is safe to write
+back to `word/document.xml`.
 
 ## Entry Point
 
@@ -45,10 +47,15 @@ Browsers have native DOM APIs, so no provider injection is typically needed.
 ```js
 const result = await applyRedlineToOxml(oxml, originalText, modifiedText, {
   generateRedlines: true,
-  author: 'Agent Name'
+  author: 'Agent Name',
+  existingRevisions: 'reject-input'
 });
 ```
 
+`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.
+
 ### Apply a text edit without tracked changes
 
 ```js
@@ -90,6 +97,9 @@ const rejectedMine = rejectTrackedChangesInOoxml(documentXml, { author: 'Agent'
 const rejectedAll = rejectTrackedChangesInOoxml(documentXml, { allAuthors: true });
 ```
 
+Move revisions are consumed too: accept removes `w:moveFrom` and unwraps
+`w:moveTo`; reject unwraps `w:moveFrom` and removes `w:moveTo`.
+
 ### Delete comments from one user (or all users)
 
 ```js
@@ -105,6 +115,15 @@ import { applyOperationToDocumentXml } from '@ansonlai/docx-redline-js/services/
 const result = await applyOperationToDocumentXml(documentXml, operation, options);
 ```
 
+Use `result.documentXml` from this API when replacing full `word/document.xml`.
+
+### Detect existing tracked changes
+
+```js
+import { containsTrackedChanges } from '@ansonlai/docx-redline-js';
+const hasTrackedChanges = containsTrackedChanges(xmlDoc);
+```
+
 ### Convert paragraph text into a Word list
 
 ```js
@@ -130,15 +149,21 @@ adapters/
   logger.js
 core/
   types.js
+  word-xml.js
   paragraph-targeting.js
   list-targeting.js
   table-targeting.js
 engine/
   oxml-engine.js
   surgical-mode.js
+  surgical-run-splitting.js
+  surgical-diff-application.js
+  surgical-spans.js
   reconstruction-mode.js
+  reconstruction-writer.js
   format-application.js
   formatting-removal.js
+  run-builders.js
   table-mode.js
 pipeline/
   pipeline.js
@@ -169,7 +194,8 @@ orchestration/
 ```js
 {
   generateRedlines: true,
-  author: 'Name'
+  author: 'Name',
+  existingRevisions: 'reject-input'
 }
 ```
 
@@ -179,12 +205,17 @@ orchestration/
 {
   oxml: string,
   hasChanges: boolean,
+  status?: 'ok' | 'no-op' | 'error',
+  error?: { code: string, message: string },
   warnings?: string[],
   numberingXml?: string,
   useNativeApi?: boolean
 }
 ```
 
+Known error codes include `PARSE_ERROR`, `TARGET_NOT_FOUND`, and
+`EXISTING_REVISIONS`.
+
 ### OOXML wrapping for Word insertOoxml scenarios
 
 ```js
@@ -211,3 +242,21 @@ 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`.
+
+## Validation Commands
+
+```bash
+npm test
+npm run test:isolation
+npm run check:types
+node scripts/export-validation-fixtures.mjs
+```
+
+Optional Windows/Word smoke test for a completed `.docx`:
+
+```bash
+npm run smoke:word -- path/to/file.docx
+```

package/ARCHITECTURE.md

@@ -13,7 +13,8 @@ This repository contains only the publishable package surface:
 - `services/`
 - `orchestration/`
 - `index.js`
-- `standalone.js`
+- `index.d.ts`
+- `dist/`
 
 No Word add-in entrypoints or host-specific integration layers are part of this package.
 
@@ -22,6 +23,8 @@ No Word add-in entrypoints or host-specific integration layers are part of this
 - Preserve Word-compatible redlines by editing OOXML directly.
 - Keep core logic host-independent (no Office.js globals, no Word API calls).
 - Reuse the same engine in browser, Node.js, and other JavaScript runtimes.
+- Keep generated OOXML schema-safe through shared Word element creation and
+  centralized revision metadata helpers.
 
 ## Folder Layout
 
@@ -32,16 +35,23 @@ No Word add-in entrypoints or host-specific integration layers are part of this
 │   ├── logger.js
 │   └── xml-adapter.js
 ├── core/
+│   └── word-xml.js
 ├── engine/
+│   ├── oxml-engine.js
+│   ├── surgical-mode.js
+│   ├── reconstruction-mode.js
+│   ├── run-builders.js
 │   └── formatting-removal.js
 ├── orchestration/
 ├── pipeline/
 ├── services/
+│   ├── comment-engine.js
 │   ├── numbering-helpers.js
 │   ├── revision-comment-management.js
 │   ├── standalone-docx-plumbing.js
 │   └── standalone-operation-runner.js
-└── index.js
+├── index.js
+└── index.d.ts
 ```
 
 ## Entry Points
@@ -58,20 +68,32 @@ No Word add-in entrypoints or host-specific integration layers are part of this
   - Runtime logger injection and shared logging methods.
 - `core/*`
   - Shared types, OOXML identity helpers, target resolution, list/table targeting heuristics, and XML query helpers.
+- `core/word-xml.js`
+  - Namespace-safe Word element creation, tracked-change detection, and OOXML payload source-shape helpers.
+- `core/types.js`
+  - Shared model enums/types plus revision metadata generation and document-aware revision ID seeding.
+- `core/redline-validation.js`
+  - Runtime structural validation (`validateRedlineOoxml`) mirroring the test-suite invariants: no nested revisions, `w:delText` inside `w:del`, complete revision metadata, unique revision ids, preserved boundary whitespace.
 - `engine/oxml-engine.js`
-  - Main reconciliation router and mode selection.
+  - Main reconciliation router, mode selection, existing-revision policy gate, and status/error result handling.
+- `engine/run-builders.js`
+  - Shared builders for insertion/deletion wrappers, paragraph-mark revisions, visible run content, and run-property changes.
+- `engine/surgical-*.js`
+  - Surgical run splitting, diff application, and span helpers for localized edits that preserve surrounding markup.
 - `engine/formatting-removal.js`
   - Shared formatting removal and highlight helpers.
 - `pipeline/*`
-  - Ingestion, markdown preprocessing, diffing, patching, and serialization stages.
+  - Ingestion, markdown preprocessing, diffing, patching, and serialization stages. Ingestion treats deleted and moved-from content as non-visible text and inserted/moved-to content as visible text.
+- `services/comment-engine.js`
+  - Comment creation and package-level comment XML handling.
 - `services/numbering-helpers.js`
   - Dynamic numbering ID allocation, numbering payload remapping, and schema-order-safe numbering merges.
 - `services/standalone-docx-plumbing.js`
   - Package-level extraction/wiring/validation for `word/document.xml`, `word/numbering.xml`, and `word/comments.xml`.
 - `services/revision-comment-management.js`
-  - OOXML transforms for accepting/rejecting tracked changes by author/all-authors and deleting comments by author/all-authors.
+  - OOXML transforms for accepting/rejecting insertion, deletion, move, paragraph-mark, and property-change revisions by author/all-authors, plus deleting comments by author/all-authors.
 - `services/standalone-operation-runner.js`
-  - Host-agnostic operation bridge for `redline`, `highlight`, and `comment` workflows.
+  - Host-agnostic operation bridge for full-document `redline`, `highlight`, and `comment` workflows.
 - `orchestration/*`
   - Route planning and list fallback orchestration utilities.
 
@@ -81,14 +103,35 @@ No Word add-in entrypoints or host-specific integration layers are part of this
 2. Caller configures XML provider/logger/defaults when needed via `adapters/*`.
 3. Caller invokes reconciliation APIs (`applyRedlineToOxml`, operation runner, ingestion/export helpers).
 4. `engine/oxml-engine.js` routes to format, table, list, surgical, or reconstruction flows.
-5. Pipeline/services return OOXML and optional package artifacts (`numberingXml`, comments payloads).
-6. Optional revision/comment management transforms can accept/reject revisions or delete comments by author.
+5. Pipeline/services return OOXML, optional package artifacts (`numberingXml`, comments payloads), and non-breaking `status`/`error` fields where applicable.
+6. Optional revision/comment management transforms can accept/reject revisions, including move revisions, or delete comments by author.
 7. Caller writes resulting XML back to package/document boundaries.
 
 ## Public Surfaces
 
 - Primary: `index.js`
-Keep exports centralized through `index.js`.
+- Types: `index.d.ts`
+
+Keep public exports centralized through `index.js`; deep imports are supported by
+the package `exports` map for advanced consumers, but new public APIs should
+still be re-exported from `index.js`.
+
+## Reliability Guardrails
+
+- Create Word namespace elements with `createWordElement(xmlDoc, 'w:...')`.
+  Avoid direct `document.createElement('w:*')` or `createElementNS(NS_W, 'w:*')`
+  outside `core/word-xml.js`.
+- Generate tracked-change metadata through `createRevisionMetadata(author)` so
+  `w:id`, `w:author`, and `w:date` stay consistent and document-unique.
+- Seed revision IDs from parsed input with `seedRevisionIdsFromDocument(xmlDoc)`
+  before emitting new tracked changes.
+- Use `containsTrackedChanges(xmlDoc)` before redlining existing revisions unless
+  the caller explicitly chooses the `existingRevisions: 'accept-all-first'` policy.
+- Do not write unknown `result.oxml` payloads directly into `word/document.xml`;
+  normalize with `extractReplacementNodesFromOoxml(...)` or use
+  `applyOperationToDocumentXml(...).documentXml` for full-document replacement.
+- Run `validateRedlineOoxml(oxml)` on generated output before packaging it;
+  it reports structural invariant violations as `{ valid, issues }`.
 
 
 ## Build Output
@@ -108,8 +151,26 @@ The bundle inlines `diff-match-patch` and keeps `@xmldom/xmldom` external.
   - Runs the package test runner (`scripts/run-tests.mjs`) against all `tests/*.mjs` except setup helpers.
 - `npm run test:isolation`
   - Runs boundary checks for Word API markers and dependency-graph isolation.
-
-Use these checks before publishing or tagging.
+- `npm run check:types`
+  - Smoke-checks `index.d.ts`.
+- `node scripts/export-validation-fixtures.mjs`
+  - Writes release-time validation fixtures to `tmp/validation-docx/` as
+    `word/document.xml` parts, assembled `.docx` files, and expected-text sidecars.
+- `tests/roundtrip_fuzz_tests.mjs` (part of `npm test`)
+  - Seeded fuzz sweep of the accept/reject round-trip invariant; tune with
+    `FUZZ_SEED` / `FUZZ_ITERATIONS`.
+- `npm run smoke:word -- path/to/file.docx`
+  - Optional Windows/Word COM smoke test for a completed `.docx`.
+- `npm run smoke:word:diff`
+  - Windows/Word COM differential test: Word itself accepts/rejects the
+    generated fixtures and the resulting text is compared to expectations.
+- `bash scripts/validate-fixtures-xsd.sh`
+  - Validates exported fixtures against the ECMA-376 transitional `wml.xsd`.
+- `.github/workflows/validation.yml`
+  - Nightly independent-oracle validation: XSD schema check, LibreOffice
+    conversion, and an extended 20k-case fuzz sweep with a fresh seed.
+
+Use these checks before publishing or tagging. See `docs/VALIDATION.md`.
 
 ## Fast Orientation For Contributors
 
@@ -121,3 +182,6 @@ Use this sequence to understand or modify behavior without reading everything:
 4. For package wiring issues, inspect `services/standalone-docx-plumbing.js`.
 5. For revision/comment cleanup behavior, inspect `services/revision-comment-management.js`.
 6. For numbering/list issues, inspect `services/numbering-helpers.js` and orchestration list-fallback modules.
+7. For reliability regressions, start with `tests/roundtrip_invariant_tests.mjs`,
+   `tests/engine_reliability_tests.mjs`, `tests/paragraph_mark_revision_tests.mjs`,
+   `tests/move_revision_tests.mjs`, and `tests/hardening_status_tests.mjs`.

package/README.md

@@ -11,12 +11,14 @@ Converts AI-generated or programmatic text/markdown edits into valid Office Open
 - Lists: generate and edit real Word lists (`w:numPr`) from markdown
 - Tables: virtual-grid diffing for cell-level edits with merge safety
 - Comments: inject OOXML comments anchored to text ranges
-- Revision management: accept/reject tracked changes by author or for all authors
+- Revision management: detect existing revisions, consume move revisions, and accept/reject tracked changes by author or for all authors
 - Comment management: delete comments by author or for all authors
 - Highlights: apply highlight colors to runs
 - Markdown and OOXML conversion in both directions
+- Status/error result fields for parse, targeting, and existing-revision failures
 - Package plumbing helpers for numbering.xml, comments.xml, content types, and relationships
 - Zero host dependencies: works in Node.js, browsers, Deno, and similar JS runtimes with DOM parsing support
+- TypeScript declarations included via `index.d.ts`
 
 ## Install
 
@@ -112,6 +114,21 @@ const result = await applyRedlineToOxml(oxml, original, modified, {
 | `applyRedlineToOxmlWithListFallback(oxml, original, modified, options)` | Core engine with automatic single-line list structural fallback. |
 | `reconcileMarkdownTableOoxml(oxml, original, markdownTable, options)` | Table-specific reconciliation helper. |
 
+Common `applyRedlineToOxml` options:
+
+| Option | Purpose |
+|--------|---------|
+| `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. |
+
+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`. |
+
 ### Pipeline (lower-level access)
 
 | Function | Purpose |
@@ -121,14 +138,16 @@ const result = await applyRedlineToOxml(oxml, original, modified, {
 | `ingestWordOoxmlToMarkdown(oxml)` | Convert OOXML to markdown. |
 | `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. |
+| `validateRedlineOoxml(oxml)` | Validate generated redline OOXML against the package's structural invariants (no nested revisions, `w:delText` inside `w:del`, complete metadata, unique revision ids, preserved boundary whitespace). Returns `{ valid, issues }`; run it before writing output into a package. |
 
 ### Services
 
 | Function | Purpose |
 |----------|---------|
 | `injectCommentsIntoOoxml(oxml, comments, options)` | Add comments anchored to text ranges. |
-| `acceptTrackedChangesInOoxml(oxml, { author?, allAuthors? })` | Accept `w:ins` / `w:del` / `*PrChange` revisions for one author or all authors. |
-| `rejectTrackedChangesInOoxml(oxml, { author?, allAuthors? })` | Reject `w:ins` / `w:del` / `*PrChange` revisions for one author or all authors. |
+| `acceptTrackedChangesInOoxml(oxml, { author?, allAuthors? })` | Accept `w:ins` / `w:del` / `w:moveFrom` / `w:moveTo` / `*PrChange` revisions for one author or all authors. |
+| `rejectTrackedChangesInOoxml(oxml, { author?, allAuthors? })` | Reject `w:ins` / `w:del` / `w:moveFrom` / `w:moveTo` / `*PrChange` revisions for one author or all authors. |
 | `deleteCommentsByAuthorInOoxml(oxml, { author?, allAuthors? })` | Delete comments and matching anchors/references for one author or all authors. |
 | `generateTableOoxml(headers, rows, options)` | Generate a `w:tbl` from tabular data. |
 | `createDynamicNumberingIdState(numberingXml)` | Allocate numbering IDs without collisions. |
@@ -160,6 +179,8 @@ Different APIs return different OOXML shapes. Use this as a packaging safety che
 ### 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.
+- 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.
 - Don't write payloads that start with `<pkg:package` directly into `word/document.xml`.
@@ -217,8 +238,46 @@ await validateDocxPackage(zip);
 const output = await zip.generateAsync({ type: 'nodebuffer' });
 ```
 
+## Validating Output
+
+Run the automated package checks:
+
+```bash
+npm test
+npm run test:isolation
+npm run check:types
+```
+
+For release-time fixture export:
+
+```bash
+node scripts/export-validation-fixtures.mjs
+```
+
+On Windows with desktop Word installed, you can smoke-test a completed `.docx`:
+
+```bash
+npm run smoke:word -- path/to/file.docx
+```
+
+To validate against Word as an independent oracle (Word itself accepts and
+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
+```
+
+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
+invariant with a fresh seed. See [docs/VALIDATION.md](./docs/VALIDATION.md).
+
 ## Architecture
 
 See [ARCHITECTURE.md](./ARCHITECTURE.md) for module layout, data flow, and contributor guidance.
 
 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.

package/core/redline-validation.js

@@ -0,0 +1,156 @@
+/**
+ * Runtime structural validation for generated redline OOXML.
+ *
+ * Mirrors the invariants enforced by the test-suite round-trip harness so
+ * downstream consumers can verify output before writing it into a package:
+ * no nested revisions, deleted text uses w:delText, revision metadata is
+ * complete, revision ids are unique, and boundary whitespace is preserved.
+ */
+
+import { parseXml } from '../adapters/xml-adapter.js';
+import { NS_W } from './types.js';
+
+const REVISION_ID_ELEMENTS = new Set(['ins', 'del', 'rPrChange', 'pPrChange']);
+const REVISION_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}T/;
+
+function localNameOf(node) {
+    return String(node?.localName || node?.nodeName || '').replace(/^.*:/, '');
+}
+
+function elementsByLocalName(root, name) {
+    return Array.from(root.getElementsByTagName('*')).filter(el => localNameOf(el) === name);
+}
+
+function wordAttribute(node, name) {
+    return node.getAttribute(`w:${name}`) || node.getAttribute(name) || '';
+}
+
+function xmlSpaceAttribute(node) {
+    return node.getAttribute('xml:space') ||
+        node.getAttribute('space') ||
+        node.getAttributeNS?.('http://www.w3.org/XML/1998/namespace', 'space') ||
+        '';
+}
+
+function isParagraphMarkRevision(node) {
+    return localNameOf(node.parentNode) === 'rPr';
+}
+
+function parseOoxmlForValidation(oxml) {
+    const attempt = xml => {
+        const doc = parseXml(xml);
+        const parseError = doc.getElementsByTagName('parsererror')[0];
+        if (parseError) {
+            throw new Error(parseError.textContent || 'XML parse error');
+        }
+        return doc;
+    };
+
+    try {
+        return { doc: attempt(oxml) };
+    } catch {
+        try {
+            return { doc: attempt(`<w:root xmlns:w="${NS_W}">${oxml}</w:root>`) };
+        } catch (error) {
+            return { error: error?.message || 'XML parse error' };
+        }
+    }
+}
+
+/**
+ * Validates redline OOXML against the package's structural invariants.
+ *
+ * Issue severities: 'error' issues indicate output Word may repair or
+ * mis-resolve; 'warning' issues are suspicious but tolerated by Word.
+ *
+ * @param {string} oxml - OOXML string (fragment, document, or package scope)
+ * @returns {{ valid: boolean, issues: Array<{ code: string, severity: 'error'|'warning', message: string }> }}
+ */
+export function validateRedlineOoxml(oxml) {
+    const issues = [];
+    const addIssue = (code, severity, message) => issues.push({ code, severity, message });
+
+    if (typeof oxml !== 'string' || oxml.trim() === '') {
+        addIssue('PARSE_ERROR', 'error', 'Input is not a non-empty OOXML string.');
+        return { valid: false, issues };
+    }
+
+    const { doc, error } = parseOoxmlForValidation(oxml);
+    if (!doc) {
+        addIssue('PARSE_ERROR', 'error', `OOXML does not parse as XML: ${error}`);
+        return { valid: false, issues };
+    }
+
+    const insElements = elementsByLocalName(doc, 'ins');
+    const delElements = elementsByLocalName(doc, 'del');
+    const revisions = insElements.concat(delElements);
+
+    // No w:ins/w:del nested inside another w:ins/w:del.
+    for (const revision of revisions) {
+        const nested = Array.from(revision.getElementsByTagName('*'))
+            .filter(el => el !== revision && ['ins', 'del'].includes(localNameOf(el)));
+        if (nested.length > 0) {
+            addIssue('NESTED_REVISION', 'error',
+                `<${revision.nodeName}> (w:id="${wordAttribute(revision, 'id')}") contains nested <${nested[0].nodeName}>.`);
+        }
+    }
+
+    // Deleted runs must carry w:delText, never w:t.
+    for (const del of delElements) {
+        const plainTextNodes = elementsByLocalName(del, 't');
+        if (plainTextNodes.length > 0) {
+            addIssue('DEL_CONTAINS_T', 'error',
+                `<w:del> (w:id="${wordAttribute(del, 'id')}") contains <w:t>; deleted text must use <w:delText>.`);
+        }
+    }
+
+    // Every revision needs complete metadata.
+    for (const revision of revisions) {
+        const missing = [];
+        if (!wordAttribute(revision, 'id')) missing.push('w:id');
+        if (!wordAttribute(revision, 'author')) missing.push('w:author');
+        if (!REVISION_DATE_PATTERN.test(wordAttribute(revision, 'date'))) missing.push('w:date');
+        if (missing.length > 0) {
+            addIssue('MISSING_REVISION_METADATA', 'error',
+                `<${revision.nodeName}> is missing or has malformed ${missing.join(', ')}.`);
+        }
+    }
+
+    // Revision ids must be unique among ins/del/rPrChange/pPrChange.
+    const seenIds = new Set();
+    for (const node of Array.from(doc.getElementsByTagName('*'))) {
+        if (!REVISION_ID_ELEMENTS.has(localNameOf(node))) continue;
+        const id = wordAttribute(node, 'id');
+        if (!id) continue;
+        if (seenIds.has(id)) {
+            addIssue('DUPLICATE_REVISION_ID', 'error', `Revision id ${id} appears more than once.`);
+        }
+        seenIds.add(id);
+    }
+
+    // Boundary whitespace requires xml:space="preserve".
+    const textNodes = elementsByLocalName(doc, 't').concat(elementsByLocalName(doc, 'delText'));
+    for (const node of textNodes) {
+        const text = node.textContent || '';
+        if (/^\s|\s$/.test(text) && xmlSpaceAttribute(node) !== 'preserve') {
+            addIssue('MISSING_SPACE_PRESERVE', 'error',
+                `<${node.nodeName}> has boundary whitespace without xml:space="preserve".`);
+        }
+        if (text === '') {
+            addIssue('EMPTY_TEXT_ELEMENT', 'warning', `<${node.nodeName}> is empty.`);
+        }
+    }
+
+    // Empty w:ins/w:del wrappers (paragraph-mark revisions inside w:rPr are
+    // legitimately empty and excluded).
+    for (const revision of revisions) {
+        if (isParagraphMarkRevision(revision)) continue;
+        const hasElementChild = Array.from(revision.childNodes || []).some(child => child.nodeType === 1);
+        if (!hasElementChild) {
+            addIssue('EMPTY_REVISION_WRAPPER', 'warning',
+                `<${revision.nodeName}> (w:id="${wordAttribute(revision, 'id')}") wraps no content.`);
+        }
+    }
+
+    return { valid: !issues.some(issue => issue.severity === 'error'), issues };
+}

package/core/types.js

@@ -120,12 +120,13 @@ export const NumberSuffix = Object.freeze({
  * @property {FormatHint[]} formatHints - Position-based format information
  */
 
-/**
- * @typedef {Object} ReconciliationResult
- * @property {string} ooxml - The reconciled OOXML output
- * @property {boolean} isValid - Whether validation passed
- * @property {string[]} warnings - Any warnings during processing
- */
+/**
+ * @typedef {Object} ReconciliationResult
+ * @property {string} ooxml - The reconciled OOXML output
+ * @property {boolean} isValid - Whether validation passed
+ * @property {string[]} warnings - Any warnings during processing
+ * @property {'package'|'document'|'fragment'} [sourceType] - Shape of the OOXML payload when known
+ */
 
 /**
  * @typedef {Object} SerializationOptions
@@ -194,8 +195,34 @@ export function createRevisionMetadata(author) {
         date: getRevisionTimestamp()
     };
 }
-
-/**
+
+/**
+ * Seeds the revision ID counter above any existing Word revision/comment id values.
+ *
+ * @param {Document|Element} xmlDoc - Parsed OOXML document or element
+ * @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;
+}
+
+/**
  * Resets the revision ID counter (for testing)
  * @param {number} [startValue=1000] - Value to reset to
  */