@ansonlai/docx-redline-js 0.1.4 → 0.1.6

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,30 @@ 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.
 - `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 +101,33 @@ 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.
 
 
 ## Build Output
@@ -108,6 +147,12 @@ 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.
+- `npm run check:types`
+  - Smoke-checks `index.d.ts`.
+- `node scripts/export-validation-fixtures.mjs`
+  - Writes release-time validation fixtures to `tmp/validation-docx/`.
+- `npm run smoke:word -- path/to/file.docx`
+  - Optional Windows/Word COM smoke test for a completed `.docx`.
 
 Use these checks before publishing or tagging.
 
@@ -121,3 +166,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,15 @@ 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. |
 
 ### 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 +178,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 +237,32 @@ 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
+```
+
 ## 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/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
  */

package/core/word-xml.js

@@ -0,0 +1,90 @@
+import { NS_W } from './types.js';
+
+/**
+ * Returns true when a node is a WordprocessingML element with the given local name.
+ *
+ * @param {Node|null|undefined} node - Candidate node
+ * @param {string} localName - Word local name, for example `r` or `tbl`
+ * @returns {boolean}
+ */
+export function isWordElement(node, localName) {
+    if (!node || node.nodeType !== 1) return false;
+    if (node.namespaceURI === NS_W && node.localName === localName) return true;
+    const nodeName = String(node.nodeName || '');
+    return nodeName === `w:${localName}` || nodeName === localName;
+}
+
+/**
+ * Creates a WordprocessingML element using namespace-aware DOM APIs when available.
+ *
+ * @param {Document} xmlDoc - Target document
+ * @param {string} qualifiedName - Qualified name, for example `w:r`
+ * @returns {Element}
+ */
+export function createWordElement(xmlDoc, qualifiedName) {
+    return typeof xmlDoc.createElementNS === 'function'
+        ? xmlDoc.createElementNS(NS_W, qualifiedName)
+        : xmlDoc.createElement(qualifiedName);
+}
+
+function wordElementsByLocalName(xmlDoc, localName) {
+    const namespaced = Array.from(xmlDoc?.getElementsByTagNameNS?.(NS_W, localName) || []);
+    if (namespaced.length > 0) return namespaced;
+    return Array.from(xmlDoc?.getElementsByTagName?.('*') || []).filter(node => isWordElement(node, localName));
+}
+
+/**
+ * Returns true if a document or fragment contains Word tracked-change markup.
+ *
+ * @param {Document|Element} xmlDoc - Parsed OOXML document or element
+ * @returns {boolean}
+ */
+export function containsTrackedChanges(xmlDoc) {
+    const trackedChangeNames = [
+        'ins',
+        'del',
+        'moveFrom',
+        'moveTo',
+        'moveFromRangeStart',
+        'moveFromRangeEnd',
+        'moveToRangeStart',
+        'moveToRangeEnd',
+        'rPrChange',
+        'pPrChange',
+        'cellIns',
+        'cellDel'
+    ];
+
+    return trackedChangeNames.some(localName => wordElementsByLocalName(xmlDoc, localName).length > 0);
+}
+
+/**
+ * Classifies the shape of an OOXML payload.
+ *
+ * @param {string} oxml - OOXML payload
+ * @returns {'package'|'document'|'fragment'}
+ */
+export function classifyOoxmlSourceType(oxml) {
+    const trimmed = String(oxml || '').trim();
+    if (/^<\?xml\b[^>]*>\s*<pkg:package\b/i.test(trimmed) || /^<pkg:package\b/i.test(trimmed)) {
+        return 'package';
+    }
+    if (/^<\?xml\b[^>]*>\s*<(?:w:)?document\b/i.test(trimmed) || /^<(?:w:)?document\b/i.test(trimmed)) {
+        return 'document';
+    }
+    return 'fragment';
+}
+
+/**
+ * Adds `sourceType` metadata to OOXML result objects without changing payloads.
+ *
+ * @template T
+ * @param {T & { oxml?: string, sourceType?: 'package'|'document'|'fragment' }} result - Result object
+ * @returns {T & { sourceType?: 'package'|'document'|'fragment' }}
+ */
+export function withOoxmlSourceType(result) {
+    if (!result || typeof result !== 'object' || result.sourceType || typeof result.oxml !== 'string') {
+        return result;
+    }
+    return { ...result, sourceType: classifyOoxmlSourceType(result.oxml) };
+}