@ansonlai/docx-redline-js 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## Unreleased
+
+### Added
+
+- **`mergeCommentParts(parts, output)`:** merges a batch result's comment output (`commentsXml` / `commentsXmlMode`,
+  `commentsExtendedXml` / `commentsExtendedXmlMode`) into comment parts held as XML strings, for hosts that keep package
+  parts outside a ZIP (a Flat OPC package, a browser parts map). Appends or replaces comments.xml, brings existing
+  commentsIds.xml / commentsExtensible.xml in line, and replaces commentsExtended.xml. Returns
+  `{ status, hasChanges, parts, changedParts, addedParts }`. It never throws for document content: `PARSE_ERROR`,
+  `INVALID_COMMENT_PARTS` (a non-string input or a part with the wrong root element), `DUPLICATE_COMMENT_ID` (an id
+  already used, or repeated within the incoming part, in every mode) and `UNSUPPORTED_EXISTING_COMMENT_THREAD_METADATA` (a `'merge'` thread-metadata delta for
+  parts that already have it) come back as `error`, with `error.part` naming the part, and the input parts unchanged.
+  Existing commentsIds/commentsExtensible parts are validated before they are reconciled, and an incoming comments part
+  with no comments changes nothing. Relationships and content types stay with the
+  host; `addedParts` lists parts new to the input (presence only, so hosts should also repair a missing relationship for
+  any part in `changedParts`). Same merge as `openDocx` (shared helper).
+
+### Fixed
+
+- **`structuredContent: false` now also covers paragraphs a redline adds.** A plain-text redline whose `modified` adds
+  paragraphs before or after the target (`'Intro.
+Use __literal__ text'`) kept the target literal but stripped inline
+  Markdown, and parsed `#` headings, in the new paragraphs. They now stay literal too, including list siblings, ranges,
+  `replace` and untracked edits. Inserting paragraphs this way still inherits the list of a list-item target.
+- **One-column tables:** a one-column Markdown separator (`| --- |`) is now recognized. Before, a multi-line redline of a
+  cell in a one-column table (`'Cell text.
+Second line'`) inserted a stray `---` row (`structuredContent: false`) or was
+  refused `TABLE_SEPARATOR_REQUIRED` (`true`), and a caller-written one-column table was refused the same way. A bare
+  `---` line is still not a table separator.
+- **`structuredContent: false` on the table route:** text added to or rewritten in table cells by a plain-text redline
+  (including the multi-line cell edit that inserts rows) keeps inline Markdown literal.
+- The `applyCommentReplyToParts` declaration now includes `documentXml`.
+- `ensureCommentsArtifactsInZip` (and so `openDocx`), when merging into an existing comments.xml, also refuses an id
+  repeated within the incoming part, and leaves comments.xml untouched when the incoming part has no comments.
+
+## 0.10.0
+
+### Added
+
+- **`existingRevisions: 'auto'`:** per target, `merge-same-author` when the target has no tracked changes or only the operation
+  author's, otherwise `slice-cross-author`. Unattributed changes count as another author's, and a `targetEnd` range resolves
+  over every paragraph in it. Accepted per operation, per batch, by `applyRedlineToOxml` and as `--existing-revisions auto`;
+  preflight reports the resolved policy. `resolveExistingRevisionsPolicy` is exported and accepts a node or an array of
+  paragraphs. CLI capability `existing-revisions-auto-v1`; the contract version stays 9.
+- **`compareDocumentInspections(expected, actual)`** (and `inspectionReviewShape`): compare two inspections by text, table position,
+  list label, review segments and comments, ignoring ids, dates and run boundaries. For verifying what a host committed.
+
+### Fixed
+
+- **Literal underscore runs are no longer Markdown emphasis:** `__x__` and `_x_` follow CommonMark flanking rules (not intraword,
+  not inside a longer underscore run, not around whitespace). Signature lines such as `_________________________` survive a
+  table reconciliation and a paragraph rewrite; `snake_case` stays literal.
+- **`structuredContent: false` is plain text:** a caller's plain-text `redline`/`replace` keeps inline Markdown markers literally
+  instead of turning them into formatting. Internal plain-structure calls are unchanged.
+- **Comment reply paraIds no longer collide with body paragraphs:** `applyCommentReplyToParts` (and the `comment_reply`
+  operation) now collects body `w14:paraId` values before allocating a reply's id. The scan's regex contained a literal
+  backspace instead of `\b`, so body ids were never seen.
+- **Internal:** the Reject All verifier's numbering check uses its memoized definition parser (it was never wired in), and the
+  reject-roundtrip matrix's revision-identity cross-check and `RECEIPT_RECONCILIATION_FAILED` gate now actually run (the
+  same backspace-for-`\b` defect had made them no-ops).
+- **Same-author checks count unattributed tracked changes as another author's:** a target holding the operation author's
+  revisions plus a change with no or a blank `w:author` passed as all same-author. `merge-same-author` then refused with
+  `UNSAFE_REVISION_NESTING` (`manual_resolution`) instead of `EXISTING_REVISIONS`, and `slice-cross-author` refused instead of
+  slicing; no revision was lost. Merge now refuses with `EXISTING_REVISIONS` (`revisionAuthors` lists named authors only; the
+  message adds `unattributed`), and slicing applies while Reject All still restores the unattributed change.
+
 ## 0.9.0
 
 ### Changed
@@ -247,7 +313,7 @@
 ### Known limitations
 
 - Plain paragraph to list conversion and list format changes are not yet supported canonically; see
-  `docs/plans/2026-09-30-canonical-list-operations.md`.
+  `docs/plans/completed/2026-09-30-canonical-list-operations.md`.
 - `1. Header` to `1. Header` on a bare `document.xml` (not a packaged `.docx`) can fail with `RECEIPT_RECONCILIATION_FAILED`.
 
 ## 0.8.2

package/README.md

@@ -21,7 +21,20 @@ Converts AI-generated or programmatic text/markdown edits into valid Office Open
 - 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
 
-## What's New in 0.9.0 and 0.8.x
+## What's New in 0.11.0, 0.10.0, 0.9.0 and 0.8.x
+
+0.11.0 adds `mergeCommentParts(parts, output)`, which merges a batch result's comment output into comment parts held as
+XML strings, for hosts that have no ZIP. It also fixes `structuredContent: false` so inline Markdown stays literal in
+paragraphs a redline adds and in table cells, recognizes one-column Markdown table separators (`| --- |`), and makes
+`ensureCommentsArtifactsInZip` refuse an incoming part that repeats a comment id while merging into an existing
+`comments.xml`. See the
+[0.11.0 release notes](./docs/releases/0.11.0.md).
+
+0.10.0 adds `existingRevisions: 'auto'` (capability `existing-revisions-auto-v1`, contract version stays 9), which
+merges a target's own-author history and slices around another reviewer's, per target. It also adds
+`compareDocumentInspections` for checking a committed document against a prepared one, and fixes underscore runs such as
+signature lines (`_____`) collapsing to one `_`. A caller's `structuredContent: false` now keeps inline Markdown markers
+literal. See the [0.10.0 release notes](./docs/releases/0.10.0.md).
 
 0.9.0 moves the CLI contract to version 9 and adds the `list-format` operation (`convert-plain`, `change-format`, `join`),
 `paragraph-format` numbering binding, list-conversion diagnostics, a single numbering allocator and merge, and a Reject All
@@ -292,7 +305,7 @@ docx-redline preflight contract.docx --operations operations.json --author "Edit
 All commands emit JSON on stdout. `apply` defaults:
 - **Author**: Defaults to `'AI Redliner'` (or `DOCX_REDLINE_AUTHOR` environment variable).
 - **Output overwrite**: Destination files provided via `--output` overwrite by default. Pass `--no-overwrite` or `--no-clobber` to safeguard existing destination files. The source input is never overwritten unless `--in-place` is specified.
-- **Existing revisions**: Defaults to `'merge-same-author'`. Pass `--existing-revisions slice-cross-author` to edit inside another reviewer's pending insertions with native carrier slicing.
+- **Existing revisions**: Defaults to `'merge-same-author'`. Pass `--existing-revisions slice-cross-author` to edit inside another reviewer's pending insertions with native carrier slicing, or `--existing-revisions auto` to choose per target (slicing only where another reviewer's changes are present).
 - **Transactionality**: Defaults to `atomic: false` (applies valid operations and reports any failures). Pass `--atomic` for all-or-nothing rollback on any operation error.
 - **Complete-success exit**: Pass `--require-complete` when a progressive `partial` result must exit with code `3`; errors exit with code `2`. Without the flag, partial results retain the legacy zero exit code, so always inspect `completion`.
 - **Agent profile**: `--profile agent` enables complete-success exit behavior while retaining the ordinary progressive transaction and existing-revision defaults. Compose it with `--atomic` or an explicit `--existing-revisions` policy when intended, and verify the resolved `effectiveOptions`.
@@ -329,7 +342,8 @@ capabilities `revision-fidelity-v1`, `list-conversion-diagnostics-v1`, `paragrap
 `part` targeting, the `comment_resolve` operation and `delete-comments --comment-id` are advertised as
 `header-footer-parts-v1`, `comment-resolve-operation-v1` and `delete-comments-by-id-v1`. The remaining advertised
 capabilities are `atomic-batch-results-on-package-failure`, `baseline-aware-validation`, `compact-mutation-results`,
-`cross-author-revision-slicing`, `document-scoped-list-revision-ids` and `format-text-occurrence-v1`.
+`cross-author-revision-slicing`, `document-scoped-list-revision-ids` and `format-text-occurrence-v1`. 0.10.0 adds
+`existing-revisions-auto-v1` (`existingRevisions: 'auto'`) without a contract bump.
 Wrappers should negotiate only the
 capabilities they use. Run `docx-redline <command> --help` for that command's
 machine-readable options, behavior, exit codes, canonical GitHub documentation links, and compact examples.
@@ -375,10 +389,10 @@ See the [compact agent fast start](./docs/AGENT_FAST_START.md), the
 | `generateRedlines` | `boolean` | `true` | When `true`, emit Word-native tracked changes (`w:ins`/`w:del`). When `false`, apply clean direct edits without revision markup. **Note: Redlines are not always the preferred method** — pass `generateRedlines: false` (or `--no-redlines` via CLI) when producing clean execution drafts, restructuring documents, or when revision clutter is unwanted. |
 | `author` | `string` | `'AI Redliner'` | Reviewer/author name stamped on generated tracked changes and comments. Overridable via `DOCX_REDLINE_AUTHOR` env variable. |
 | `atomic` | `boolean` | `false` | Batch transaction mode. By default (`false`), valid edits are applied and failing operations report errors. When `true`, any operation failure rolls back the entire batch to the original document state (`rolledBack: true`, `hasChanges: false`). Feature prominently in high-assurance workflows. |
-| `structuredContent` | `boolean` | `true` | Auto-detects Markdown tables, headings (`#`), and lists in replacement text and renders them as native Word elements (`w:tbl`, `w:pStyle`, `w:numPr`). Pass `false` to treat replacement text strictly as plain text. |
+| `structuredContent` | `boolean` | `true` | Auto-detects Markdown tables, headings (`#`), and lists in replacement text and renders them as native Word elements (`w:tbl`, `w:pStyle`, `w:numPr`). Pass `false` to treat replacement text strictly as plain text: inline Markdown markers (`**`, `__`, `_`, `~~`, `++`) are kept literally, including in paragraphs a redline adds and in table cells. With `true`, underscores follow CommonMark flanking rules, so signature lines (`_____`) and `snake_case` stay literal. |
 | `pairReplacements` | `boolean` | `true` | Links adjacent `<w:del>` and `<w:ins>` revisions with matching timestamps so Word groups them as a single replacement in the Reviewing Pane. |
 | `strictTargets` | `boolean` | `true` (CLI/facade) | Requires exact target descriptors (`exactText`, `paragraphId`, `index`, `occurrence`, `fingerprint`) and forbids ambiguous matching. Defaults to `false` in low-level runner for backwards compatibility. |
-| `existingRevisions` | `string` | `'merge-same-author'` | How to handle paragraphs with existing tracked changes. `'merge-same-author'` merges revisions from the same author and protects other authors with `EXISTING_REVISIONS`. `'slice-cross-author'` keeps that same-author merge behavior while allowing Word-native edits inside another author's pending insertion. Pass `'accept-all-first'` to normalize prior revisions or `'reject-input'` to refuse editing revised paragraphs. |
+| `existingRevisions` | `string` | `'merge-same-author'` | How to handle paragraphs with existing tracked changes. `'merge-same-author'` merges revisions from the same author and protects other authors with `EXISTING_REVISIONS`. `'slice-cross-author'` keeps that same-author merge behavior while allowing Word-native edits inside another author's pending insertion. Pass `'accept-all-first'` to normalize prior revisions or `'reject-input'` to refuse editing revised paragraphs. `'auto'` chooses per target: `'merge-same-author'` when the target has no tracked changes or only the operation author's, otherwise `'slice-cross-author'` (preflight reports the resolved policy). |
 | `removeFormatting` | `boolean` | `false` | When `true` and the text is unchanged with no Markdown hints, strips existing bold/italic/underline/strikethrough formatting. |
 | `verifyRevisionFidelity` | `'enforce' \| 'warn' \| 'off'` | `'enforce'` | Post-apply Reject All check described under [Reject All verification](#reject-all-verification). CLI: `--revision-fidelity`; the agent profile rejects `off`. |
 | `listMarkers` | `'literal'` | unset | Per operation. Accepts list-marker text as literal text and suppresses `LIST_MARKER_NOT_BOUND`, `UNSUPPORTED_LIST_CONVERSION`, `LIST_FORMAT_NOT_APPLIED` and `UNSUPPORTED_LIST_FORMAT_CHANGE` for that operation. |
@@ -422,6 +436,19 @@ The engine applies Microsoft Word Desktop-native tracked change structures:
 - **Straddle deletions**: Deletions spanning between baseline text and pending insertions cleanly partition across their respective container contexts without invalid coalescing.
 - **Lifecycle parity**: Accepting or rejecting either reviewer independently produces identical results to Microsoft Word Desktop's native review pane.
 
+### Comparing inspections
+
+`compareDocumentInspections(expected, actual)` checks that two inspections describe the same reviewable document. It compares paragraph text, table position, list labels, review segments (adjacent segments of one kind and author are merged) and comments, and ignores ids, dates, rsids, paragraph ids and run boundaries. A host that writes a prepared package through another API can inspect what it prepared and what it committed, then compare them:
+
+```js
+import { inspectDocumentParts, compareDocumentInspections } from '@ansonlai/docx-redline-js';
+
+const check = compareDocumentInspections(inspectDocumentParts(preparedParts), inspectDocumentParts(committedParts));
+if (!check.matches) console.warn(check.differences); // at most the first 10 differences
+```
+
+`inspectionReviewShape(inspection)` returns the normalized shape the comparison uses.
+
 ### Replacing a heading with a tracked list
 
 The list route treats a one-paragraph heading expanded into multiple markdown
@@ -538,7 +565,7 @@ const result = await document.applyOperations([plan.operation], {
 });
 ```
 
-Every Markdown table must include a separator row immediately below its header.
+Every Markdown table must include a separator row immediately below its header (a one-column table uses `| --- |`).
 Missing separators, missing data rows, and inconsistent column counts are
 reported as structured errors instead of being inserted as visible pipe text.
 Use `#` through `#########` to request Word heading paragraphs; blank lines
@@ -560,6 +587,7 @@ an earlier block has already replaced.
 | `analyzeStructuredContent(markdown)` | Decompose mixed Markdown into typed blocks and report malformed table syntax without creating an operation. |
 | `planStructuredReplacement(target, markdown, options)` | Validate mixed content and return one atomic `structuredContent` replacement operation, or `operation: null` with issues. |
 | `containsTrackedChanges(xmlDoc)` | Detect `w:ins`, `w:del`, move revisions, property changes, and paragraph-mark revision markup in a parsed OOXML document/fragment. |
+| `resolveExistingRevisionsPolicy(policy, node, author)` | Resolve `existingRevisions: 'auto'` for a parsed paragraph, scope element, or an array of range paragraphs: `'slice-cross-author'` when any tracked change is by another or an unattributed author, otherwise `'merge-same-author'`. Other policies are returned unchanged. |
 | `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
@@ -567,14 +595,17 @@ an earlier block has already replaced.
 | Function | Purpose |
 |----------|---------|
 | `injectCommentsIntoOoxml(oxml, comments, options)` | Add comments anchored to text ranges. |
-| `applyCommentReplyToParts(options)` | Build a threaded reply in `comments.xml` and `commentsExtended.xml` without adding a document-body anchor. |
+| `applyCommentReplyToParts(options)` | Build a threaded reply in `comments.xml` and `commentsExtended.xml` without adding a document-body anchor. Pass `documentXml` so the reply's `w14:paraId` also avoids body paragraph ids. |
+| `mergeCommentParts(parts, output)` | Merge a batch result's comment output into comment parts held as XML strings (no ZIP): appends or replaces `comments.xml`, reconciles existing `commentsIds.xml` / `commentsExtensible.xml`, replaces `commentsExtended.xml`. Returns `{ status, hasChanges, parts, changedParts, addedParts, error? }`; never throws for document content. Error codes: `PARSE_ERROR`, `INVALID_COMMENT_PARTS`, `DUPLICATE_COMMENT_ID`, `UNSUPPORTED_EXISTING_COMMENT_THREAD_METADATA`, each with `error.part`. The host adds relationships and content types for `addedParts`; that list reflects part presence only, so also repair a missing relationship for any part in `changedParts`. |
+| `compareDocumentInspections(expected, actual)` | Compare two `inspectDocumentParts` / `inspect()` results by text, table position, list label, review segments and comments, ignoring ids, dates and run boundaries. Returns `{ matches, differences }` (at most 10). See [Comparing inspections](#comparing-inspections). |
+| `inspectionReviewShape(inspection)` | The normalized, host-independent shape `compareDocumentInspections` compares. |
 | `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 matching comment definitions and anchors present in the supplied OOXML payload. Real `.docx` packages require updating both `word/comments.xml` and `word/document.xml`. |
 | `generateTableOoxml(headers, rows, options)` | Generate a `w:tbl` from tabular data. |
 | `createDynamicNumberingIdState(numberingXml)` | Allocate numbering IDs without collisions. |
 | `ensureNumberingArtifactsInZip(zip, numberingXml, options)` | Add numbering artifacts to a `.docx` package. Always merges into an existing `word/numbering.xml` through the package's single numbering merge (`mergeNumberingParts`); an incoming id that already exists with different content fails with `NUMBERING_ID_CONFLICT`. The former `mergeNumberingXml` option is ignored. |
-| `ensureCommentsArtifactsInZip(zip, commentsXml)` | Merge comments artifacts into a `.docx` package. |
+| `ensureCommentsArtifactsInZip(zip, commentsXml)` | Merge comments artifacts into a `.docx` package. When merging into an existing `comments.xml`, refuses an id already in use, including one repeated within the incoming part (`DUPLICATE_COMMENT_ID`), and leaves `comments.xml` untouched when the incoming part has no comments. `replaceExisting` (or no existing part) writes the incoming part as is. |
 | `ensureCommentsExtendedArtifactsInZip(zip, commentsExtendedXml)` | Add or replace modern Word comment-thread metadata in a `.docx` package. |
 | `validateDocxPackage(zip)` | Validate `.docx` structural consistency. |
 

package/core/word-xml.js

@@ -1,118 +1,160 @@
-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));
-}
-
-// Keep revision discovery and author discovery on the same taxonomy. Cell
-// markers are included for fail-closed detection even though selective
-// acceptance/rejection of those structural revisions is not yet supported.
-const TRACKED_CHANGE_NAMES = [
-    'ins',
-    'del',
-    'moveFrom',
-    'moveTo',
-    'moveFromRangeStart',
-    'moveFromRangeEnd',
-    'moveToRangeStart',
-    'moveToRangeEnd',
-    'rPrChange',
-    'pPrChange',
-    'tblPrChange',
-    'trPrChange',
-    'tcPrChange',
-    'cellIns',
-    'cellDel'
-];
-
-/**
- * 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) {
-    return TRACKED_CHANGE_NAMES.some(localName => wordElementsByLocalName(xmlDoc, localName).length > 0);
-}
-
-/**
- * Collects all distinct author names from tracked changes in the given XML document or element.
- *
- * @param {Document|Element|null|undefined} xmlDocOrElement
- * @returns {string[]} Sorted unique list of author names.
- */
-export function getTrackedChangeAuthors(xmlDocOrElement) {
-    if (!xmlDocOrElement) return [];
-    const authors = new Set();
-    for (const localName of TRACKED_CHANGE_NAMES) {
-        for (const node of wordElementsByLocalName(xmlDocOrElement, localName)) {
-            const author = node.getAttribute?.('w:author')
-                || node.getAttribute?.('author')
-                || (typeof node.getAttributeNS === 'function' ? node.getAttributeNS(NS_W, 'author') : null);
-            if (author && typeof author === 'string' && author.trim()) {
-                authors.add(author.trim());
-            }
-        }
-    }
-    return [...authors].sort();
-}
-
-/**
- * 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) };
-}
+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));
+}
+
+// Keep revision discovery and author discovery on the same taxonomy. Cell
+// markers are included for fail-closed detection even though selective
+// acceptance/rejection of those structural revisions is not yet supported.
+const TRACKED_CHANGE_NAMES = [
+    'ins',
+    'del',
+    'moveFrom',
+    'moveTo',
+    'moveFromRangeStart',
+    'moveFromRangeEnd',
+    'moveToRangeStart',
+    'moveToRangeEnd',
+    'rPrChange',
+    'pPrChange',
+    'tblPrChange',
+    'trPrChange',
+    'tcPrChange',
+    'cellIns',
+    'cellDel'
+];
+
+/**
+ * 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) {
+    return TRACKED_CHANGE_NAMES.some(localName => wordElementsByLocalName(xmlDoc, localName).length > 0);
+}
+
+/**
+ * Collects all distinct author names from tracked changes in the given XML document or element.
+ *
+ * @param {Document|Element|null|undefined} xmlDocOrElement
+ * @returns {string[]} Sorted unique list of author names.
+ */
+export function getTrackedChangeAuthors(xmlDocOrElement) {
+    if (!xmlDocOrElement) return [];
+    const authors = new Set();
+    for (const localName of TRACKED_CHANGE_NAMES) {
+        for (const node of wordElementsByLocalName(xmlDocOrElement, localName)) {
+            const author = node.getAttribute?.('w:author')
+                || node.getAttribute?.('author')
+                || (typeof node.getAttributeNS === 'function' ? node.getAttributeNS(NS_W, 'author') : null);
+            if (author && typeof author === 'string' && author.trim()) {
+                authors.add(author.trim());
+            }
+        }
+    }
+    return [...authors].sort();
+}
+
+/**
+ * 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) };
+}
+
+/**
+ * Returns true if any tracked change in the node lacks a non-blank author.
+ * Same-author checks treat such a revision as another reviewer's, because
+ * `getTrackedChangeAuthors` omits it.
+ *
+ * @param {Document|Element|null|undefined} node
+ * @returns {boolean}
+ */
+export function hasUnattributedTrackedChange(node) {
+    if (!node) return false;
+    for (const localName of TRACKED_CHANGE_NAMES) {
+        for (const change of wordElementsByLocalName(node, localName)) {
+            const author = change.getAttribute?.('w:author')
+                || change.getAttribute?.('author')
+                || (typeof change.getAttributeNS === 'function' ? change.getAttributeNS(NS_W, 'author') : null);
+            if (!author || !String(author).trim()) return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * Resolves `existingRevisions: 'auto'` for one target. A target without tracked
+ * changes, or whose changes are all by `author`, merges same-author history;
+ * any other or unattributed reviewer's change selects 'slice-cross-author',
+ * which preserves that history. Other policies are returned unchanged.
+ * @param {string|null|undefined} policy
+ * @param {Node|Array<Node>} node - target paragraph, scope element or document, or every paragraph of a range
+ * @param {string} author
+ * @returns {string|null|undefined}
+ */
+export function resolveExistingRevisionsPolicy(policy, node, author) {
+    if (policy !== 'auto') return policy;
+    const nodes = (Array.isArray(node) ? node : [node]).filter(Boolean);
+    const own = String(author || '').trim().toLowerCase();
+    const foreign = nodes.some(item => containsTrackedChanges(item) && (
+        hasUnattributedTrackedChange(item)
+        || getTrackedChangeAuthors(item).some(name => name.trim().toLowerCase() !== own)
+    ));
+    return foreign ? 'slice-cross-author' : 'merge-same-author';
+}