@ansonlai/docx-redline-js 0.10.0 → 0.11.0

package/docs/AGENT_KNOWLEDGE_BASE.md

@@ -73,6 +73,7 @@ instructions that will exist in another clone or in CI.
 | Validation, receipts, and lifecycle oracles | `core/redline-validation.js`, `services/receipt-collector.js`, `services/revision-comment-management.js` | `tests/redline_validation_tests.mjs`, `tests/mutation_receipt_tests.mjs`, `tests/roundtrip_oracle_tests.mjs` |
 | Existing-revision policy resolution (`auto`) | `core/word-xml.js` (`resolveExistingRevisionsPolicy`), `services/document-operation-mutations.js`, `services/operation-preflight.js` | `tests/existing_revisions_auto_tests.mjs`, `tests/existing_revisions_auto_paths_tests.mjs` |
 | Comparing a committed document with a prepared one | `services/inspection-comparison.js` | `tests/inspection_comparison_tests.mjs` |
+| Comment parts outside a ZIP | `services/comment-parts-merge.js`, `services/standalone-docx-plumbing.js` (`mergeCommentsPartXml`), `services/comment-thread-parts.js` | `tests/comment_parts_merge_tests.mjs` |
 
 Run one focused suite with `node tests/<name>.mjs`. Run `npm test` only when the
 change crosses several subsystems or before release-level handoff. The Word COM,
@@ -385,6 +386,31 @@ const inspection = inspectDocumentParts({ documentXml, commentsXml, numberingXml
 Reuse `exactText` plus `paragraphId` or `fingerprint` in an operation. Computed
 list labels and excerpts are for display, not replacements for exact targets.
 
+### Merge comment output into parts held outside a ZIP
+
+```js
+import { mergeCommentParts } from '@ansonlai/docx-redline-js';
+const merged = mergeCommentParts(
+  { commentsXml, commentsExtendedXml, commentsIdsXml, commentsExtensibleXml }, // current parts, null when absent
+  batchResult // commentsXml / commentsXmlMode, commentsExtendedXml / commentsExtendedXmlMode
+);
+if (merged.status === 'ok') { /* write merged.parts; ensure rels/content types for merged.changedParts */ }
+```
+
+Use it when a host holds package parts as strings (a Flat OPC package from a Word
+add-in, a browser parts map) instead of handing a ZIP to `openDocx`, which does the
+same merge internally. commentsIds.xml and commentsExtensible.xml are reconciled
+only when present, never created. A `'merge'` commentsExtended delta for parts that
+already have thread metadata is refused with
+`UNSUPPORTED_EXISTING_COMMENT_THREAD_METADATA`. Other codes: `PARSE_ERROR`,
+`INVALID_COMMENT_PARTS` (non-string input, wrong root element) and
+`DUPLICATE_COMMENT_ID`; `error.part` names the part (and `error.commentId` the
+duplicate). An unexpected merge failure reports `COMMENT_PARTS_MERGE_FAILED`. It
+never throws for document content. On any error the input parts
+come back unchanged. `addedParts` reflects part presence only; the function cannot see
+relationships, so a host that owns them should ensure one for every part in
+`changedParts` (a package can have comments.xml without its relationship).
+
 ### Verify a committed document against the prepared one
 
 ```js
@@ -892,9 +918,16 @@ Accept/Reject checks.
 
 ```js
 import { reconcileMarkdownTableOoxml } from '@ansonlai/docx-redline-js';
-const result = await reconcileMarkdownTableOoxml(tableOoxml, originalText, markdownTable);
+const result = await reconcileMarkdownTableOoxml(tableOoxml, originalText, markdownTable, options); // options optional
 ```
 
+A multi-line `redline` of a table-cell paragraph whose first line is the cell's
+current text (`'Cell text.\nSecond line'`) inserts the extra lines as new rows below
+the target row, in the target column (mirrored across columns for symmetric label
+rows such as signature blocks). It does not add paragraphs inside the cell. With
+`structuredContent: false` the new cell text stays literal. One-column tables use
+`| --- |` as the separator.
+
 ## Detailed Architecture
 
 Use the layout and task shortcuts at the top of this file for normal work.
@@ -911,7 +944,7 @@ reconstruct the architecture by repeatedly listing the repository.
 | `generateRedlines` | `boolean` | `true` | When `true`, emits Word-native tracked changes (`w:ins`/`w:del`). When `false`, applies direct text 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` environment variable. |
 | `atomic` | `boolean` | `false` | Batch transaction mode. By default (`false`), valid edits are applied directly and failing operations report errors. When `true`, any operation failure rolls back the entire batch to the original document state (`rolledBack: true`, `hasChanges: false`). Use `atomic: true` (or `--atomic` in CLI) for 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: inline Markdown markers (`**`, `__`, `_`, `~~`, `++`) are kept literally. With `true`, underscores follow CommonMark flanking rules, so signature lines (`_____`) and `snake_case` stay literal. |
+| `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, including paragraphs a redline adds and table-cell text: no headings, and inline Markdown markers (`**`, `__`, `_`, `~~`, `++`) are kept literally. 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 the same author's work and protects other authors with `EXISTING_REVISIONS`. `'slice-cross-author'` retains same-author merging 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). |

package/docs/TESTING.md

@@ -38,6 +38,10 @@ fixtures rarely contain.
 | Universal document facade & ZIP | `node tests/universal_docx_document_tests.mjs`, `node tests/universal_zip_archive_tests.mjs`, `node tests/universal_facade_edge_cases_tests.mjs` | Universal `Uint8Array` binary handling, `fflate` compression/decompression, optimistic concurrency, and complete-DOCX operations without Node built-ins | Desktop Word rendering |
 | Sandbox bundle isolation | `node tests/sandbox_bundle_isolation_tests.mjs` | Zero-dependency standalone ESM/CJS bundles execute in restricted VM sandboxes without `process`, `Buffer`, or `require`, with zero Node built-in imports | Web Worker latency |
 | Existing-revision policy `auto` | `node tests/existing_revisions_auto_tests.mjs`, `node tests/existing_revisions_auto_paths_tests.mjs` | Per-target resolution to `merge-same-author` or `slice-cross-author` (mixed, unattributed and deletion-only history, whole `targetEnd` ranges, table cells), equivalence with the explicit policy through `applyRedlineToOxml` and the runner, preflight reporting, untracked edits, `openDocx`, `--existing-revisions auto`, schema and the CLI capability | Desktop Word rendering |
+| Existing-revision policy `merge-same-author` | `node tests/merge_same_author_tests.mjs` | Same-author turns merge against their baseline, foreign-author and mixed-history targets are refused or protected, and an unattributed tracked change counts as another reviewer's (merge refused with `EXISTING_REVISIONS`; slicing keeps its baseline) | Desktop Word rendering |
+| Plain-text paragraph insertion | `node tests/plain_text_paragraph_insertion_tests.mjs` | A caller's `structuredContent: false` keeps paragraphs a redline adds literal (before/after/around the target, several, signature lines, headings, changed target, batch vs per-operation, `replace`, untracked, `openDocx`, ranges, list siblings at level 0/1 and bullets) with Reject All restoring the source | Desktop Word rendering |
+| Table-cell multi-line edits | `node tests/table_cell_paragraph_insertion_tests.mjs` | One-column separator recognition (and bare `---` rejection), multi-line cell edits inserting rows below the target in one- and two-column tables in every `structuredContent` mode, caller-written one-column tables (reconcile and text-to-table), the plain-text contract in cells, Reject All and validation, `openDocx` | Desktop Word rendering |
+| Comment parts merge | `node tests/comment_parts_merge_tests.mjs`, `node tests/comment_parts_merge_edge_tests.mjs` | `mergeCommentParts` append/replace, sibling reconciliation (never created, multi-paragraph and paraId-less comments, unique durable ids), structured refusals with unchanged input (types, roots, malformed siblings, duplicates), no-ops, idempotence, special characters, and part-for-part equivalence with `openDocx` for a new comment, a reply, a resolve, a first comment, a comments-only package, sequential batches and a mixed batch | A host's own package and relationship writing |
 | Comment reply paraIds | `node tests/comment_reply_para_id_tests.mjs` | A reply's `w14:paraId` avoids body paragraph ids (case-insensitive) and stays deterministic without a collision | Word's own id allocation |
 | Inspection comparison | `node tests/inspection_comparison_tests.mjs` | `compareDocumentInspections` ignores ids, dates, comment order and run splits and reports text, review-segment (author, kind, position), table, list-label and comment (text, author, anchor, resolved, thread) differences, capped at 10; works on `openDocx` inspections | A host's own write path |
 | Literal underscores and plain text | `node tests/literal_underscore_text_tests.mjs` | Signature lines and `snake_case` survive table reconciliation and rewrites; CommonMark underscore flanking; a caller's `structuredContent: false` keeps inline Markdown literal | Desktop Word rendering |
@@ -948,7 +952,8 @@ The corpus packager starts from the original `.docx`, replaces only the declared
 revision part (`word/document.xml` by default, or a named header part), and
 verifies every untouched ZIP part byte-for-byte before Word opens the result.
 The Word oracle derives multi-change expectations by applying each independently
-declared replacement to Word's source text and reads header-story text separately
+declared replacement to Word's source text and reads header-story text separately.
+
 ## Release validation and independent oracles
 
 This package works on OOXML strings and intentionally leaves `.docx` zip

package/engine/oxml-engine.js

@@ -577,12 +577,12 @@ export async function applyRedlineToOxml(oxml, originalText, modifiedText, optio
     if (isMarkdownTable && !hasTables) {
         recordRouteSelection(options, 'table', { transformation: 'text-to-table' });
         log('[OxmlEngine] Text-to-table transformation: generating new table from Markdown');
-        return finalize(applyTextToTableTransformation(xmlDoc, cleanModifiedText, serializer, null, author, generateRedlines));
+        return finalize(applyTextToTableTransformation(xmlDoc, cleanModifiedText, serializer, null, author, generateRedlines, { plainTextContent: options.plainTextContent === true }));
     }
 
     if (hasTables && isMarkdownTable) {
         recordRouteSelection(options, 'table', { transformation: 'table-reconciliation' });
-        return finalize(applyTableReconciliation(xmlDoc, cleanModifiedText, serializer, null, author, generateRedlines));
+        return finalize(applyTableReconciliation(xmlDoc, cleanModifiedText, serializer, null, author, generateRedlines, { plainTextContent: options.plainTextContent === true }));
     }
     if (usesSurgicalTextMode) {
         recordRouteSelection(options, 'surgical', { tableScoped: hasTables });

package/engine/table-mode.js

@@ -36,9 +36,10 @@ function noChanges(serializer, xmlDoc) {
  * @param {DOMParser} parser - Parser instance
  * @param {string} author - Author name
  * @param {boolean} [generateRedlines=true] - Track change toggle
+ * @param {{ plainTextContent?: boolean }} [extra] - plainTextContent keeps cell text literal
  * @returns {{ oxml: string, hasChanges: boolean }}
  */
-export function applyTableReconciliation(xmlDoc, modifiedText, serializer, parser, author, generateRedlines = true) {
+export function applyTableReconciliation(xmlDoc, modifiedText, serializer, parser, author, generateRedlines = true, extra = {}) {
     const tableNodes = getElementsByTagNSOrTag(xmlDoc, NS_W, 'tbl');
     const newTableData = parseTable(modifiedText);
     const hasNewContent = newTableData.rows.length > 0 || newTableData.headers.length > 0;
@@ -58,7 +59,8 @@ export function applyTableReconciliation(xmlDoc, modifiedText, serializer, parse
     const options = {
         generateRedlines,
         author,
-        revisionIdAllocator: getRevisionIdAllocatorForDocument(xmlDoc)
+        revisionIdAllocator: getRevisionIdAllocatorForDocument(xmlDoc),
+        plainTextContent: extra.plainTextContent === true
     };
     const reconciledOxml = serializeVirtualGridToOoxml(oldGrid, operations, options);
     const wrappedOxml = `<root xmlns:w="${NS_W}">${reconciledOxml}</root>`;
@@ -92,9 +94,10 @@ export function applyTableReconciliation(xmlDoc, modifiedText, serializer, parse
  * @param {DOMParser} parser - Parser instance
  * @param {string} author - Author name
  * @param {boolean} generateRedlines - Track change toggle
+ * @param {{ plainTextContent?: boolean }} [extra] - plainTextContent keeps cell text literal
  * @returns {{ oxml: string, hasChanges: boolean }}
  */
-export function applyTextToTableTransformation(xmlDoc, modifiedText, serializer, parser, author, generateRedlines) {
+export function applyTextToTableTransformation(xmlDoc, modifiedText, serializer, parser, author, generateRedlines, extra = {}) {
     const revisionIdAllocator = getRevisionIdAllocatorForDocument(xmlDoc);
     const tableData = parseTable(modifiedText);
     if (!tableData || (tableData.rows.length === 0 && tableData.headers.length === 0)) {
@@ -102,7 +105,7 @@ export function applyTextToTableTransformation(xmlDoc, modifiedText, serializer,
         return noChanges(serializer, xmlDoc);
     }
 
-    const tableOoxml = generateTableOoxml(tableData, { generateRedlines, author, revisionIdAllocator, trackAsBlock: true });
+    const tableOoxml = generateTableOoxml(tableData, { generateRedlines, author, revisionIdAllocator, trackAsBlock: true, plainTextContent: extra.plainTextContent === true });
     const tableDoc = parseOoxmlSafe(`<root xmlns:w="${NS_W}">${tableOoxml}</root>`, 'application/xml').doc;
     if (!tableDoc) return noChanges(serializer, xmlDoc);
 

package/index.d.ts

@@ -390,7 +390,29 @@ export function wrapInDocumentFragment(rawOoxml: string, options?: Record<string
 
 export function injectCommentsIntoOoxml(oxml: string, comments: unknown[], options?: Record<string, unknown>): unknown;
 export function injectCommentsIntoPackage(packageXml: string, comments: unknown[], options?: Record<string, unknown>): unknown;
-export function applyCommentReplyToParts(options: { commentsXml: string; commentsExtendedXml?: string | null; parentCommentId: string | number; commentId: string | number; commentContent: string; author: string; date?: string }): { status: 'ok' | 'error'; hasChanges?: boolean; commentsXml?: string; commentsExtendedXml?: string; commentsXmlMode?: 'replace'; commentsExtendedXmlMode?: 'replace'; parentCommentId?: string; paraId?: string; parentParaId?: string; error?: RedlineError };
+export function applyCommentReplyToParts(options: { commentsXml: string; commentsExtendedXml?: string | null; documentXml?: string | null; parentCommentId: string | number; commentId: string | number; commentContent: string; author: string; date?: string }): { status: 'ok' | 'error'; hasChanges?: boolean; commentsXml?: string; commentsExtendedXml?: string; commentsXmlMode?: 'replace'; commentsExtendedXmlMode?: 'replace'; parentCommentId?: string; paraId?: string; parentParaId?: string; error?: RedlineError };
+export interface CommentParts {
+  commentsXml: string | null;
+  commentsExtendedXml: string | null;
+  commentsIdsXml: string | null;
+  commentsExtensibleXml: string | null;
+}
+export type CommentPartName = 'comments' | 'commentsExtended' | 'commentsIds' | 'commentsExtensible';
+export interface MergeCommentPartsResult {
+  status: 'ok' | 'error';
+  hasChanges: boolean;
+  /** Updated parts on success; the input parts unchanged on error. Absent parts are null. */
+  parts: CommentParts;
+  changedParts: CommentPartName[];
+  /** Parts the input did not have; the host adds their relationship and content type. Part presence only: also repair a missing relationship for any changed part. */
+  addedParts: CommentPartName[];
+  error?: { code: 'PARSE_ERROR' | 'INVALID_COMMENT_PARTS' | 'DUPLICATE_COMMENT_ID' | 'UNSUPPORTED_EXISTING_COMMENT_THREAD_METADATA' | string; message: string; part?: CommentPartName; commentId?: string };
+}
+/** Merge a batch result's comment output into comment parts held as XML strings (no ZIP); reconciles commentsIds/commentsExtensible. */
+export function mergeCommentParts(
+  parts?: Partial<CommentParts>,
+  output?: { commentsXml?: string | null; commentsXmlMode?: 'merge' | 'replace'; commentsExtendedXml?: string | null; commentsExtendedXmlMode?: 'merge' | 'replace' }
+): MergeCommentPartsResult;
 export function acceptTrackedChangesInOoxml(oxml: string, options?: RevisionFilterOptions): AcceptTrackedChangesResult;
 export function rejectTrackedChangesInOoxml(oxml: string, options?: RevisionFilterOptions): RejectTrackedChangesResult;
 export function deleteCommentsByAuthorInOoxml(oxml: string, options?: RevisionFilterOptions): DeleteCommentsResult;

package/index.js

@@ -307,6 +307,7 @@ export {
     buildCommentsPartXml
 } from './services/comment-engine.js';
 export { applyCommentReplyToParts } from './services/comment-replies.js';
+export { mergeCommentParts } from './services/comment-parts-merge.js';
 export {
     acceptTrackedChangesInOoxml,
     rejectTrackedChangesInOoxml,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ansonlai/docx-redline-js",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Host-independent OOXML reconciliation engine for .docx manipulation with track changes",
   "license": "MIT",
   "type": "module",

package/pipeline/content-analysis.js

@@ -22,7 +22,8 @@ export function parseTable(text) {
 
     const isSeparatorLine = line => {
         const normalized = line.replace(/\s+/g, '');
-        return /^\|:?-{3,}:?(\|:?-{3,}:?)+\|?$/.test(normalized);
+        // One column needs a pipe on both sides ("|---|"), so a bare "---" or "|---" is not a separator.
+        return /^\|:?-{3,}:?(?:(\|:?-{3,}:?)+\|?|\|)$/.test(normalized);
     };
 
     const hasHeader = lines.some(isSeparatorLine);

package/pipeline/structured-content.js

@@ -9,7 +9,8 @@
 
 import { matchListMarker } from './list-markers.js';
 
-const TABLE_SEPARATOR = /^\s*\|?\s*:?-{3,}:?\s*(?:\|\s*:?-{3,}:?\s*)+\|?\s*$/;
+// A one-column separator needs a pipe on both sides ("| --- |"); two or more columns as before.
+const TABLE_SEPARATOR = /^\s*(?:\|\s*:?-{3,}:?\s*\||\|?\s*:?-{3,}:?\s*(?:\|\s*:?-{3,}:?\s*)+\|?)\s*$/;
 
 function isBlank(line) {
     return !line || line.trim().length === 0;

package/services/comment-parts-merge.js

@@ -0,0 +1,124 @@
+/**
+ * Parts-level comment merge: the comment half of writing a batch result back into a
+ * package, for hosts that hold package parts as XML strings rather than a ZIP (a Flat OPC
+ * package, a browser parts map). Strings in, strings out; no package, relationship or
+ * content-type handling, which stays with the host.
+ */
+
+import { mergeCommentsPartXml, parseXmlStrictStandalone } from './standalone-docx-plumbing.js';
+import { reconcileCommentSiblingParts } from './comment-thread-parts.js';
+
+const PART_KEYS = Object.freeze({
+    comments: 'commentsXml',
+    commentsExtended: 'commentsExtendedXml',
+    commentsIds: 'commentsIdsXml',
+    commentsExtensible: 'commentsExtensibleXml'
+});
+
+const partsOf = parts => Object.fromEntries(Object.values(PART_KEYS).map(key => [key, parts?.[key] || null]));
+
+/**
+ * Merges a batch result's comment output into a package's comment parts.
+ *
+ * - `commentsXml` is appended to the existing comments part (`commentsXmlMode: 'merge'`, the default) or replaces it
+ *   (`'replace'`). commentsIds.xml and commentsExtensible.xml, when the package has them, are then brought in line with
+ *   comments.xml; they are never created.
+ * - `commentsExtendedXml` replaces the thread-metadata part. A `'merge'` delta for a package that already has
+ *   commentsExtended.xml cannot be merged safely and is refused.
+ *
+ * Never throws for document content; on error the input parts are returned unchanged.
+ *
+ * @param {{ commentsXml?: string|null, commentsExtendedXml?: string|null, commentsIdsXml?: string|null, commentsExtensibleXml?: string|null }} parts
+ *   the package's current comment parts (absent parts null or omitted)
+ * @param {{ commentsXml?: string|null, commentsXmlMode?: 'merge'|'replace', commentsExtendedXml?: string|null, commentsExtendedXmlMode?: 'merge'|'replace' }} output
+ *   comment output of a batch, for example an `applyOperationsToDocumentXml` result
+ * @returns {{ status: 'ok'|'error', hasChanges: boolean, parts: { commentsXml: string|null, commentsExtendedXml: string|null, commentsIdsXml: string|null, commentsExtensibleXml: string|null }, changedParts: string[], addedParts: string[], error?: { code: string, message: string, part?: string, commentId?: string } }}
+ *   `changedParts` and `addedParts` name parts as `comments`, `commentsExtended`, `commentsIds`, `commentsExtensible`;
+ *   `addedParts` lists parts the input did not have, which need a relationship and content type. It reflects part
+ *   presence only: relationships are not visible here, so a host that owns them should also repair a missing
+ *   relationship for any part in `changedParts`.
+ */
+export function mergeCommentParts(parts = {}, output = {}) {
+    const before = partsOf(parts);
+    const after = { ...before };
+    const fail = error => ({ status: 'error', hasChanges: false, parts: before, changedParts: [], addedParts: [], error });
+    const commentsMode = output?.commentsXmlMode === 'replace' ? 'replace' : 'merge';
+    const extendedMode = output?.commentsExtendedXmlMode === 'replace' ? 'replace' : 'merge';
+
+    for (const [label, value] of [
+        ...Object.values(PART_KEYS).map(key => [`parts.${key}`, before[key]]),
+        ['output.commentsXml', output?.commentsXml], ['output.commentsExtendedXml', output?.commentsExtendedXml]
+    ]) {
+        if (value != null && typeof value !== 'string') {
+            return fail({ code: 'INVALID_COMMENT_PARTS', message: `${label} must be an XML string, null or omitted (got ${typeof value}).` });
+        }
+    }
+
+    // Parses a part and checks its root element, so a wrong part is refused rather than merged as empty.
+    const requirePart = (xml, part, rootName, label) => {
+        let doc;
+        try {
+            doc = parseXmlStrictStandalone(xml, label);
+        } catch (error) {
+            throw Object.assign(error, { part });
+        }
+        if (doc.documentElement?.localName !== rootName) {
+            throw Object.assign(new Error(`${label}: expected a <${rootName}> root element, found <${doc.documentElement?.localName || 'none'}>.`), { code: 'INVALID_COMMENT_PARTS', part });
+        }
+        return doc;
+    };
+
+    try {
+        if (output?.commentsXml) {
+            const incomingDoc = requirePart(output.commentsXml, 'comments', 'comments', 'word/comments.xml (incoming)');
+            // Ids must be unique within the incoming part in every mode (the merge below also checks them
+            // against the existing part).
+            const seen = new Set();
+            for (const node of Array.from(incomingDoc.getElementsByTagNameNS('*', 'comment'))) {
+                const id = node.getAttribute('w:id') || node.getAttribute('id');
+                if (!id) continue;
+                if (seen.has(id)) {
+                    throw Object.assign(new Error(`Duplicate comment id: ${id}`), { code: 'DUPLICATE_COMMENT_ID', commentId: id, part: 'comments' });
+                }
+                seen.add(id);
+            }
+            if (before.commentsXml) requirePart(before.commentsXml, 'comments', 'comments', 'word/comments.xml (existing)');
+            // Sibling parts are reconciled below; a malformed one would otherwise be skipped silently.
+            if (before.commentsIdsXml) requirePart(before.commentsIdsXml, 'commentsIds', 'commentsIds', 'word/commentsIds.xml (existing)');
+            if (before.commentsExtensibleXml) requirePart(before.commentsExtensibleXml, 'commentsExtensible', 'commentsExtensible', 'word/commentsExtensible.xml (existing)');
+            after.commentsXml = mergeCommentsPartXml(before.commentsXml, output.commentsXml, { replaceExisting: commentsMode === 'replace' });
+            Object.assign(after, reconcileCommentSiblingParts({
+                commentsXml: after.commentsXml,
+                commentsIdsXml: after.commentsIdsXml,
+                commentsExtensibleXml: after.commentsExtensibleXml
+            }));
+        }
+        if (output?.commentsExtendedXml) {
+            if (extendedMode !== 'replace' && before.commentsExtendedXml) {
+                return fail({
+                    code: 'UNSUPPORTED_EXISTING_COMMENT_THREAD_METADATA',
+                    part: 'commentsExtended',
+                    message: 'The output carries a commentsExtended delta (mode "merge") for parts that already have thread metadata; a delta cannot be merged into an existing commentsExtended.xml. Nothing was merged.'
+                });
+            }
+            requirePart(output.commentsExtendedXml, 'commentsExtended', 'commentsEx', 'word/commentsExtended.xml (incoming)');
+            after.commentsExtendedXml = output.commentsExtendedXml;
+        }
+    } catch (error) {
+        return fail({
+            code: error?.code || 'COMMENT_PARTS_MERGE_FAILED',
+            message: error?.message || String(error),
+            ...(error?.part || error?.code === 'DUPLICATE_COMMENT_ID' ? { part: error.part || 'comments' } : {}),
+            ...(error?.commentId ? { commentId: error.commentId } : {})
+        });
+    }
+
+    const changedParts = [];
+    const addedParts = [];
+    for (const [name, key] of Object.entries(PART_KEYS)) {
+        if (after[key] === before[key]) continue;
+        changedParts.push(name);
+        if (!before[key]) addedParts.push(name);
+    }
+    return { status: 'ok', hasChanges: changedParts.length > 0, parts: after, changedParts, addedParts };
+}

package/services/document-operation-mutations.js

@@ -658,7 +658,10 @@ async function buildInsertedPlainParagraph(xmlDoc, anchorParagraph, text, revisi
         String(text || ''),
         {
             author,
-            generateRedlines: false
+            generateRedlines: false,
+            // A caller's structuredContent: false keeps inserted paragraphs plain too: no headings,
+            // and inline Markdown markers stay literal.
+            ...(options.plainTextContent === true ? { structuredContent: false, plainTextContent: true } : {})
         }
     );
 
@@ -2388,7 +2391,7 @@ export async function applyToParagraphByExactText(documentXml, targetText, modif
                 author,
                 // A wholly inserted paragraph must track its own paragraph mark; otherwise Word's
                 // Reject All removes the text but leaves an empty paragraph behind.
-                { generateRedlines, trackParagraphMark: true }
+                { generateRedlines, trackParagraphMark: true, plainTextContent: options.plainTextContent === true }
             );
             const imported = xmlDoc.importNode(plainParagraph, true);
             ensureParagraphIdsOnImportedNode(imported, operationSession);
@@ -2563,6 +2566,7 @@ export async function applyToParagraphByExactText(documentXml, targetText, modif
             existingRevisions: options.existingRevisions || 'merge-same-author',
             structuredContent: options.structuredContent !== false,
             explicitStructuredContent: options.explicitStructuredContent === true,
+            plainTextContent: options.plainTextContent === true,
             _revisionIdAllocator: revisionIdAllocator,
             _isolatedTableCell: useTableScope
         })

package/services/operation-heuristics.js

@@ -192,6 +192,6 @@ export function deriveParagraphThenTableAppend(modifiedText) {
     const tableLines = lines.slice(1);
     if (!tableLines.every(line => line.trim().startsWith('|'))) return null;
     const separator = tableLines[1].replace(/\s+/g, '');
-    if (!/^\|:?-{3,}:?(\|:?-{3,}:?)+\|?$/.test(separator)) return null;
+    if (!/^\|:?-{3,}:?(?:(\|:?-{3,}:?)+\|?|\|)$/.test(separator)) return null;
     return { paragraphMarkdown: lines[0].trim(), tableText: tableLines.join('\n') };
 }

package/services/standalone-docx-plumbing.js

@@ -310,12 +310,47 @@ export async function ensureNumberingArtifactsInZip(zip, numberingXmlList, optio
     }
 }
 
+/**
+ * Merges incoming comment definitions into an existing comments.xml string. With no
+ * existing part, or `replaceExisting`, the incoming part is returned as is (unparsed).
+ * Otherwise throws a `PARSE_ERROR` for malformed XML and a `DUPLICATE_COMMENT_ID` for an
+ * incoming id the existing part (or an earlier incoming comment) already uses. An incoming
+ * part with no comments leaves the existing string as is.
+ *
+ * @param {string|null|undefined} existingXml
+ * @param {string} commentsXml
+ * @param {{ replaceExisting?: boolean }} [options]
+ * @returns {string}
+ */
+export function mergeCommentsPartXml(existingXml, commentsXml, options = {}) {
+    if (!existingXml || options.replaceExisting === true) return commentsXml;
+    const existingDoc = parseXmlStrictStandalone(existingXml, 'word/comments.xml (existing)');
+    const incomingDoc = parseXmlStrictStandalone(commentsXml, 'word/comments.xml (incoming)');
+    const incomingComments = Array.from(incomingDoc.documentElement.getElementsByTagNameNS(NS_W, 'comment'));
+    if (incomingComments.length === 0) return existingXml;
+    const existingRoot = existingDoc.documentElement;
+    const usedIds = new Set(
+        Array.from(existingRoot.getElementsByTagNameNS(NS_W, 'comment'))
+            .map(comment => comment.getAttribute('w:id') || comment.getAttribute('id'))
+            .filter(Boolean)
+    );
+    for (const incomingComment of incomingComments) {
+        const id = incomingComment.getAttribute('w:id') || incomingComment.getAttribute('id');
+        if (id && usedIds.has(id)) {
+            throw Object.assign(new Error(`Duplicate comment id: ${id}`), { code: 'DUPLICATE_COMMENT_ID', commentId: id });
+        }
+        if (id) usedIds.add(id);
+        existingRoot.appendChild(existingDoc.importNode(incomingComment, true));
+    }
+    return createSerializer().serializeToString(existingDoc);
+}
+
 /**
  * Ensures comments part + package metadata exist and merges incoming comments.
  *
  * @param {any} zip
  * @param {string|null|undefined} commentsXml
- * @param {{ onInfo?: (message: string) => void }} [options]
+ * @param {{ onInfo?: (message: string) => void, replaceExisting?: boolean }} [options]
  */
 export async function ensureCommentsArtifactsInZip(zip, commentsXml, options = {}) {
     const onInfo = typeof options?.onInfo === 'function' ? options.onInfo : () => {};
@@ -323,27 +358,8 @@ export async function ensureCommentsArtifactsInZip(zip, commentsXml, options = {
 
     const serializer = createSerializer();
     const existingText = await readZipText(zip, COMMENTS_PATH);
-    if (!existingText || options.replaceExisting === true) {
-        onInfo('[Demo] Adding comments.xml');
-        zip.file(COMMENTS_PATH, commentsXml);
-    } else {
-        const existingDoc = parseXmlStrictStandalone(existingText, 'word/comments.xml (existing)');
-        const incomingDoc = parseXmlStrictStandalone(commentsXml, 'word/comments.xml (incoming)');
-        const existingRoot = existingDoc.documentElement;
-        const existingIds = new Set(
-            Array.from(existingRoot.getElementsByTagNameNS(NS_W, 'comment'))
-                .map(comment => comment.getAttribute('w:id') || comment.getAttribute('id'))
-                .filter(Boolean)
-        );
-        for (const incomingComment of Array.from(incomingDoc.documentElement.getElementsByTagNameNS(NS_W, 'comment'))) {
-            const id = incomingComment.getAttribute('w:id') || incomingComment.getAttribute('id');
-            if (id && existingIds.has(id)) {
-                throw new Error(`Duplicate comment id: ${id}`);
-            }
-            existingRoot.appendChild(existingDoc.importNode(incomingComment, true));
-        }
-        zip.file(COMMENTS_PATH, serializer.serializeToString(existingDoc));
-    }
+    if (!existingText || options.replaceExisting === true) onInfo('[Demo] Adding comments.xml');
+    zip.file(COMMENTS_PATH, mergeCommentsPartXml(existingText, commentsXml, options));
 
     const ctText = await readZipText(zip, CONTENT_TYPES_PATH);
     if (ctText) {

package/services/table-reconciliation.js

@@ -8,7 +8,12 @@ import { computeWordLevelDiffOps } from '../pipeline/diff-engine.js';
 import { splitRunsAtDiffBoundaries, applyPatches } from '../pipeline/patching.js';
 import { serializeToOoxml } from '../pipeline/serialization.js';
 import { createRevisionMetadata, escapeXml, RunKind } from '../core/types.js';
-import { preprocessMarkdown } from '../pipeline/markdown-processor.js';
+import { preprocessMarkdown } from '../pipeline/markdown-processor.js';
+
+// A caller's structuredContent: false (options.plainTextContent) keeps cell text literal: no inline Markdown.
+const cellMarkdown = (text, options) => (options?.plainTextContent === true
+    ? { cleanText: String(text ?? ''), formatHints: [] }
+    : preprocessMarkdown(text));
 import { paragraphMarkPPrXml } from '../engine/paragraph-mark-revisions.js';
 
 /**
@@ -64,7 +69,7 @@ export function generateTableOoxml(tableData, options = {}) {
 
         for (let c = 0; c < numCols; c++) {
             const cellText = row[c] || '';
-            const { cleanText, formatHints } = preprocessMarkdown(cellText);
+            const { cleanText, formatHints } = cellMarkdown(cellText, options);
 
             // Build run model for the cell
             const runModel = [{
@@ -239,7 +244,7 @@ export function serializeVirtualGridToOoxml(grid, operations, options) {
         const rowInsertMeta = generateRedlines ? createRevisionMetadata(author, revisionIdAllocator) : null;
 
         for (const cellText of op.cells) {
-            const { cleanText, formatHints } = preprocessMarkdown(cellText);
+            const { cleanText, formatHints } = cellMarkdown(cellText, options);
             // Simple run model for new cell
             const runModel = [{
                 kind: generateRedlines ? RunKind.INSERTION : RunKind.TEXT,
@@ -340,7 +345,7 @@ function reconcileMultiBlockCellContent(cell, newText, options) {
             }
             return;
         }
-        const { cleanText, formatHints } = preprocessMarkdown(line);
+        const { cleanText, formatHints } = cellMarkdown(line, options);
         const diffOps = computeWordLevelDiffOps(block.acceptedText, cleanText);
         const model = applyPatches(splitRunsAtDiffBoundaries(block.runModel, diffOps), diffOps, {
             generateRedlines, author, formatHints
@@ -349,7 +354,7 @@ function reconcileMultiBlockCellContent(cell, newText, options) {
     });
 
     for (let i = cell.blocks.length; i < lines.length; i++) {
-        const { cleanText, formatHints } = preprocessMarkdown(lines[i]);
+        const { cleanText, formatHints } = cellMarkdown(lines[i], options);
         const runModel = [{
             kind: generateRedlines ? RunKind.INSERTION : RunKind.TEXT,
             text: cleanText, rPrXml: '', author, startOffset: 0, endOffset: cleanText.length
@@ -365,7 +370,7 @@ function reconcileCellContent(cell, newText, options) {
         return reconcileMultiBlockCellContent(cell, newText, options);
     }
     const { generateRedlines, author, revisionIdAllocator = null } = options;
-    const { cleanText, formatHints } = preprocessMarkdown(newText);
+    const { cleanText, formatHints } = cellMarkdown(newText, options);
 
     // For now, satisfy with single block or join blocks
     // In a full implementation, we'd diff paragraphs within the cell