@docx4j/core-ts 0.3.0 → 0.3.2

package/dist/model/content/TrackedChange.mjs

@@ -1,9 +1,10 @@
 import { textOf } from '@docx4j/generated-objects-ts/builders/wml';
 import { Docx4JException } from '../../opc/exceptions.mjs';
-import { typeNameOf, runItemsOf, revisionKindOf, linkParents, segmentsOf, textOfView, cellsOf, rowsOf, childrenOf, W_NS } from './tree.mjs';
+import { typeNameOf, runItemsOf, revisionKindOf, linkParents, segmentsOf, textOfView, cellsOf, rowsOf, childrenOf, W_NS, itemTextOf } from './tree.mjs';
+import { removeMarkers } from './comments.mjs';
 import { Range } from './Range.mjs';
 import { rPrFromElements } from '@docx4j/generated-objects-ts/builders/wml';
-import { revisionDateOf, toRestoredText, toDeletedText, restoreRPr, restorePPr, pruneParagraphProperties } from './tracking.mjs';
+import { revisionDateOf, toRestoredText, toDeletedText, restoreRPr, restorePPr, pruneParagraphProperties, HOLDER_TYPES, holderItemsOf } from './tracking.mjs';
 import { tableRecordsOf, hasTableRecords, tableChangeText, rowText as tableRowText, acceptTable, rejectTable } from './tableRevisions.mjs';
 import { deepCopy } from '@docx4j/generated-objects-ts';
 /**
@@ -27,6 +28,7 @@ export class TrackedChange {
             case 'row': return t.row === 'ins' ? 'Added' : 'Deleted';
             case 'group': return t.revision === 'ins' ? 'Added' : t.revision === 'del' ? 'Deleted' : 'Formatted';
             case 'cell': return t.cell === 'ins' ? 'Added' : 'Deleted';
+            case 'holder': return 'Added';
             default: return 'Formatted';
         }
     }
@@ -55,6 +57,7 @@ export class TrackedChange {
             case 'tableProperties': return t.tbl;
             case 'cell': return t.tc;
             case 'sectionProperties': return t.sectPr;
+            case 'holder': return t.holder;
             default: return t.value;
         }
     }
@@ -117,7 +120,7 @@ export class TrackedChange {
                 if (t.revision === 'ins' || t.revision === 'moveTo')
                     unwrap(t);
                 else
-                    remove(t.owner, t.element);
+                    removeRevision(t, this.paragraph);
                 return;
             case 'mark':
                 if (t.mark === 'ins')
@@ -143,7 +146,7 @@ export class TrackedChange {
                     applyInner(t.inner, 'accept');
                 }
                 else
-                    remove(t.owner, t.tr);
+                    removeRow(t);
                 return;
             case 'group':
                 resolvePieces(t.pieces, 'accept');
@@ -167,6 +170,10 @@ export class TrackedChange {
             case 'sectionProperties':
                 delete t.sectPr.sectPrChange;
                 return;
+            case 'holder':
+                // the element stays, the markers go (check 30: accept all leaves the control, no marker)
+                removeHolderMarkers(t);
+                return;
         }
     }
     /**
@@ -181,7 +188,7 @@ export class TrackedChange {
                 if ((t.revision === 'moveFrom' || t.revision === 'moveTo') && (resolveMove(this, 'reject') || resolveRangelessHalf(this, 'reject')))
                     return;
                 if (t.revision === 'ins' || t.revision === 'moveTo')
-                    remove(t.owner, t.element);
+                    removeRevision(t, this.paragraph);
                 else
                     restoreDeleted(t);
                 return;
@@ -210,7 +217,7 @@ export class TrackedChange {
                     applyInner(t.inner, 'reject');
                 }
                 else
-                    remove(t.owner, t.tr);
+                    removeRow(t);
                 return;
             case 'group':
                 resolvePieces(t.pieces, 'reject');
@@ -230,6 +237,12 @@ export class TrackedChange {
             case 'sectionProperties':
                 restoreSection(t.sectPr, t.value);
                 return;
+            case 'holder':
+                // the element goes, its content stays where it stood: what is left of it after the pieces
+                // inside were rejected (nothing, for content inserted with it; check 30: reject all removes the
+                // control, and an existing control, which has no markers, stays)
+                unwrapHolder(t);
+                return;
         }
     }
     requireParagraph() {
@@ -245,21 +258,37 @@ export class TrackedChange {
  * is all `w:delText`).
  */
 function rowText(tr, view) {
-    const lines = [];
-    const visit = (items) => {
-        for (const el of items !== null && items !== void 0 ? items : []) {
-            if (typeNameOf(el) === 'org_docx4j_wml.P') {
-                lines.push(textOfView(el.value, { view }));
-                continue;
+    // Office JS's text for a row: its cells with a tab between them, then `\r\n`; a cell's paragraphs
+    // with `\r` between them, a nested table's rows each with their own `\r\n` and no separator of their
+    // own (checks 30 and 31: "row one\r\n", "nested\r\nouter cell\r\n")
+    const cellText = (tc) => {
+        var _a, _b;
+        let out = '';
+        let afterParagraph = false;
+        for (const el of (_a = childrenOf(tc)) !== null && _a !== void 0 ? _a : []) {
+            const tn = typeNameOf(el);
+            if (tn === 'org_docx4j_wml.P') {
+                out += (afterParagraph ? '\r' : '') + textOfView(el.value, { view });
+                afterParagraph = true;
+            }
+            else if (tn === 'org_docx4j_wml.Tbl') {
+                for (const row of rowsOf(el.value))
+                    out += rowText(row.element.value, view);
+                afterParagraph = false;
+            }
+            else if (typeof el.value === 'object' && el.value !== null) {
+                // a block control or custom XML element: what it holds, as if it were not there
+                for (const inner of (_b = childrenOf(el.value)) !== null && _b !== void 0 ? _b : []) {
+                    if (typeNameOf(inner) === 'org_docx4j_wml.P') {
+                        out += (afterParagraph ? '\r' : '') + textOfView(inner.value, { view });
+                        afterParagraph = true;
+                    }
+                }
             }
-            const v = el.value;
-            if (typeof v === 'object' && v !== null)
-                visit(childrenOf(v));
         }
+        return out;
     };
-    for (const cell of cellsOf(tr))
-        visit(childrenOf(cell.element.value));
-    return lines.join('\n');
+    return cellsOf(tr).map((cell) => cellText(cell.element.value)).join('\t') + '\r\n';
 }
 /** The changes inside a row, last first, so that a paragraph join never disturbs one still to do. */
 function applyInner(inner, what) {
@@ -330,10 +359,167 @@ function resolvePieces(pieces, what) {
     for (let i = marks.length - 1; i >= 0; i--)
         marks[i][what]();
 }
+/**
+ * The list an element is in now: `owner` as the change was listed, else the list its `PARENT` keeps -
+ * a piece listed inside a holder that was unwrapped since (its content moved out into the owner,
+ * check 30) is still found.
+ */
+function currentOwner(owner, element) {
+    var _a, _b;
+    if (owner.includes(element))
+        return owner;
+    const parent = (_a = element.value) === null || _a === void 0 ? void 0 : _a.PARENT;
+    const actual = parent ? (_b = runItemsOf(parent)) !== null && _b !== void 0 ? _b : childrenOf(parent) : undefined;
+    return (actual === null || actual === void 0 ? void 0 : actual.includes(element)) ? actual : owner;
+}
 function remove(owner, element) {
-    const i = owner.indexOf(element);
+    const list = currentOwner(owner, element);
+    const i = list.indexOf(element);
     if (i >= 0)
-        owner.splice(i, 1);
+        list.splice(i, 1);
+}
+/** A holder's four insertion markers taken away; the element stays. */
+function removeHolderMarkers(t) {
+    var _a;
+    remove(t.owner, t.outer[0]);
+    remove(t.owner, t.outer[1]);
+    const items = (_a = holderItemsOf(t.holder.value)) !== null && _a !== void 0 ? _a : [];
+    remove(items, t.inner[0]);
+    remove(items, t.inner[1]);
+}
+/** A holder's insertion rejected: the markers go, and its content takes its place in the owner. */
+function unwrapHolder(t) {
+    var _a;
+    removeHolderMarkers(t);
+    const owner = currentOwner(t.owner, t.holder);
+    const i = owner.indexOf(t.holder);
+    if (i < 0)
+        return;
+    const items = (_a = holderItemsOf(t.holder.value)) !== null && _a !== void 0 ? _a : [];
+    const moved = items.splice(0); // the holder keeps nothing
+    owner.splice(i, 1, ...moved);
+    linkParents(moved, t.holder.value.PARENT);
+}
+/**
+ * The insertion of a content control or custom XML element, when `items[i]` is a
+ * `w:customXmlInsRangeStart` and what follows is Word's form for one (check 30): the element, whose
+ * content starts with that marker's `w:customXmlInsRangeEnd` and ends with a second start, and that
+ * one's end right after the element. Anything else is not one (a marker on its own is left alone).
+ */
+export function holderInsertionAt(items, i, paragraph) {
+    var _a, _b, _c, _d, _e, _f;
+    const start = items[i];
+    if (((_a = start.name) === null || _a === void 0 ? void 0 : _a.localPart) !== 'customXmlInsRangeStart')
+        return undefined;
+    const holder = items[i + 1];
+    const outerEnd = items[i + 2];
+    if (!holder || !outerEnd || !HOLDER_TYPES.has((_b = typeNameOf(holder)) !== null && _b !== void 0 ? _b : '') || ((_c = outerEnd.name) === null || _c === void 0 ? void 0 : _c.localPart) !== 'customXmlInsRangeEnd')
+        return undefined;
+    const inner = (_d = childrenOf(holder.value)) !== null && _d !== void 0 ? _d : [];
+    const innerEnd = inner[0];
+    const innerStart = inner[inner.length - 1];
+    if (inner.length < 2 || !innerEnd || !innerStart || ((_e = innerEnd.name) === null || _e === void 0 ? void 0 : _e.localPart) !== 'customXmlInsRangeEnd' || ((_f = innerStart.name) === null || _f === void 0 ? void 0 : _f.localPart) !== 'customXmlInsRangeStart')
+        return undefined;
+    const idOf = (marker) => marker.value.id;
+    if (idOf(innerEnd) !== idOf(start) || idOf(outerEnd) !== idOf(innerStart))
+        return undefined;
+    return new TrackedChange({ kind: 'holder', holder, owner: items, outer: [start, outerEnd], inner: [innerEnd, innerStart], value: start.value }, paragraph);
+}
+/**
+ * A row taken away, and its table with it when it was the last: a table has no revision of its own,
+ * so one whose rows were all inserted was inserted, and one whose rows were all deleted was deleted.
+ * A `w:tbl` left with no rows is not a table any more (CR-002 section 37).
+ */
+function removeRow(t) {
+    remove(t.owner, t.tr);
+    if (t.table && rowsOf(t.table.element.value).length === 0)
+        remove(t.table.container, t.table.element);
+}
+/**
+ * A revision taken away with its runs - a rejected insertion, an accepted deletion - and the comments
+ * on it, by where their markers were (CR-002 section 38 item 1):
+ * - Word writes a comment's range start inside the `w:ins` of the text it is on; when that text goes,
+ *   current Word removes the comment with it - markers, reference run and entry (check 32, run
+ *   2026-10-02: rejecting the insertion, rejecting all, and accepting the deletion in the same shape,
+ *   each left no comment). A comment whose start comes out of the revision with no text left in its
+ *   range is removed here: the markers and the reference now, the entries in the comment parts when
+ *   the comments are next read or the package saved (`pendingCommentRemovals`).
+ * - A comment whose markers lie outside the revision (this package's own form before 0.3.1, and any
+ *   file's) is kept when its text goes: Word 2010 and Word 15, rejecting all in the editor's
+ *   `review-for-word.docx`, left its reference run alone, the range markers dropped and the entry kept
+ *   (the editor's finding of 2026-10-02). The range markers go here, the reference and the entry stay.
+ * A comment with text left in its range keeps its markers where the text was (not measured), and
+ * current Word's answer for the outside form, and the older Words' for the inside one, are not measured.
+ */
+function removeRevision(t, paragraph) {
+    var _a, _b, _c;
+    const owner = currentOwner(t.owner, t.element);
+    const i = owner.indexOf(t.element);
+    if (i < 0)
+        return;
+    const kept = ((_a = runItemsOf(t.element.value)) !== null && _a !== void 0 ? _a : []).filter((item) => { var _a, _b; return ((_a = item.name) === null || _a === void 0 ? void 0 : _a.localPart) === 'commentRangeStart' || ((_b = item.name) === null || _b === void 0 ? void 0 : _b.localPart) === 'commentRangeEnd'; });
+    // the comments whose range held the revision: a start inside it (Word's form), or one before it
+    // with its end after it (the engine's own, the markers beside the runs)
+    const idOf = (el) => el.value.id;
+    const inside = new Set(kept.filter((m) => { var _a; return ((_a = m.name) === null || _a === void 0 ? void 0 : _a.localPart) === 'commentRangeStart'; }).map(idOf));
+    const outside = new Set();
+    for (let s = 0; s < i; s++) {
+        const el = owner[s];
+        if (((_b = el.name) === null || _b === void 0 ? void 0 : _b.localPart) !== 'commentRangeStart')
+            continue;
+        const id = idOf(el);
+        if (owner.some((other, e) => { var _a; return e > i && ((_a = other.name) === null || _a === void 0 ? void 0 : _a.localPart) === 'commentRangeEnd' && idOf(other) === id; }))
+            outside.add(id);
+    }
+    owner.splice(i, 1, ...kept);
+    linkParents(kept, t.element.value.PARENT);
+    const body = paragraph === null || paragraph === void 0 ? void 0 : paragraph.parentBody;
+    if (!body)
+        return;
+    for (const id of [...inside, ...outside]) {
+        const start = owner.find((el) => { var _a; return ((_a = el.name) === null || _a === void 0 ? void 0 : _a.localPart) === 'commentRangeStart' && idOf(el) === id; });
+        if (!start || !rangeIsEmpty(owner, start, id))
+            continue;
+        if (inside.has(id)) {
+            removeMarkers(body.container, id);
+            const pkg = body.package_;
+            (_c = pkg === null || pkg === void 0 ? void 0 : pkg.pendingCommentRemovals) === null || _c === void 0 ? void 0 : _c.add(id);
+        }
+        else {
+            // the range markers only: the reference run and the entry stay (Word 2010 and 15)
+            const end = owner.find((el) => { var _a; return ((_a = el.name) === null || _a === void 0 ? void 0 : _a.localPart) === 'commentRangeEnd' && idOf(el) === id; });
+            for (const marker of [end, start])
+                if (marker)
+                    owner.splice(owner.indexOf(marker), 1);
+        }
+    }
+}
+/** True when nothing with text stands between a comment's range start and its end in the same list. */
+function rangeIsEmpty(owner, start, id) {
+    var _a;
+    const from = owner.indexOf(start);
+    if (from < 0)
+        return false;
+    for (let i = from + 1; i < owner.length; i++) {
+        const el = owner[i];
+        if (((_a = el.name) === null || _a === void 0 ? void 0 : _a.localPart) === 'commentRangeEnd' && el.value.id === id)
+            return true;
+        if (hasText(el))
+            return false;
+    }
+    return false; // the end is elsewhere: text may be
+}
+function hasText(el) {
+    var _a, _b;
+    const v = el.value;
+    if (typeof v !== 'object' || v === null)
+        return false;
+    if (typeNameOf(el) === 'org_docx4j_wml.R')
+        return ((_a = v.content) !== null && _a !== void 0 ? _a : []).some((item) => itemTextOf(item) !== undefined);
+    const kind = revisionKindOf(el);
+    if (kind === 'del' || kind === 'moveFrom')
+        return false; // deleted text is no text in the accepted view
+    return ((_b = runItemsOf(v)) !== null && _b !== void 0 ? _b : []).some(hasText);
 }
 /** A `w:ins` or `w:moveTo` accepted: its runs take its place. */
 function unwrap(t) {
@@ -377,7 +563,7 @@ function dropMark(paragraph, which) {
  */
 export function joinWithNext(paragraph, fallbackToPrevious = false) {
     var _a, _b, _c, _d, _e;
-    const container = paragraph.container;
+    const container = currentOwner(paragraph.container, paragraph.element);
     const i = container.indexOf(paragraph.element);
     const next = i >= 0 ? container[i + 1] : undefined;
     const p = paragraph.p;
@@ -800,8 +986,17 @@ function sectionText(items, end) {
         .map((el) => textOfView(el.value, { view: 'accepted' })).join('\r');
 }
 function tokensOfRunLevel(paragraph, items, out) {
-    var _a, _b;
-    for (const el of items) {
+    var _a, _b, _c;
+    for (let i = 0; i < items.length; i++) {
+        const el = items[i];
+        // an inline control or custom XML element that is itself an insertion: a piece, then what is in it
+        const inserted = holderInsertionAt(items, i, paragraph);
+        if (inserted) {
+            out.push(inserted);
+            tokensOfRunLevel(paragraph, (_a = childrenOf(items[i + 1].value)) !== null && _a !== void 0 ? _a : [], out);
+            i += 2;
+            continue;
+        }
         const kind = revisionKindOf(el);
         if (kind !== undefined) {
             // moved text is content Office JS cannot list (checks 16, 17), and is kept apart
@@ -824,17 +1019,27 @@ function tokensOfRunLevel(paragraph, items, out) {
             continue;
         }
         if (typeNameOf(el) === 'org_docx4j_wml.R') {
-            // a run whose formatting changed is a piece of its own; one that did not keeps pieces apart
+            // a run whose formatting changed is a piece of its own; one that did not keeps pieces apart -
+            // if it has text: a run holding only a comment reference does not (check 32: one author's two
+            // w:ins with the reference run between them listed as one change)
             const run = el.value;
-            if ((_a = run.rPr) === null || _a === void 0 ? void 0 : _a.rPrChange)
+            if ((_b = run.rPr) === null || _b === void 0 ? void 0 : _b.rPrChange)
                 out.push(new TrackedChange({ kind: 'runProperties', run, value: run.rPr.rPrChange }, paragraph));
-            else if (((_b = run.content) !== null && _b !== void 0 ? _b : []).length > 0)
+            else if (((_c = run.content) !== null && _c !== void 0 ? _c : []).some((item) => itemTextOf(item) !== undefined))
                 out.push(BREAK);
             continue;
         }
+        // a run holder that is not itself an insertion - a hyperlink, a field, a control or custom XML
+        // element that was there - keeps the insertions inside it apart from those outside: Office JS
+        // listed "before ", "link" and " after" as three changes over a w:ins in a w:hyperlink, and the same
+        // over a w:fldSimple and an unmarked inline w:sdt (check 30, part C), against one change over an
+        // inserted control (above) and over Word's own one-w:ins forms
         const nested = runItemsOf(el.value);
-        if (nested)
+        if (nested) {
+            out.push(BREAK);
             tokensOfRunLevel(paragraph, nested, out);
+            out.push(BREAK);
+        }
     }
 }
 /**
@@ -850,6 +1055,13 @@ function groupable(change) {
         return t.revision;
     if (t.kind === 'runProperties' || t.kind === 'markProperties')
         return 'format';
+    if (t.kind === 'holder')
+        return 'ins';
+    // an inserted or deleted row groups with rows and text touching it: Office JS lists an inserted
+    // table of three rows, with the inserted paragraphs before and after it, as one change, and rows
+    // added to a table that was there as one change per touching run of them (check 31)
+    if (t.kind === 'row')
+        return t.row;
     return undefined;
 }
 /**
@@ -894,13 +1106,13 @@ export function groupTouching(tokens) {
  * The `w:trPr/w:ins` and `w:trPr/w:del` revisions of a table row. `inner` is the revision markup
  * of the row's own cells, which the row's change owns rather than reporting separately.
  */
-export function trackedChangesOfRow(tr, owner, inner = []) {
+export function trackedChangesOfRow(tr, owner, inner = [], table) {
     const trPr = tr.value.trPr;
     const out = [];
     if (trPr === null || trPr === void 0 ? void 0 : trPr.ins)
-        out.push(new TrackedChange({ kind: 'row', row: 'ins', tr, owner, value: trPr.ins, inner }, undefined));
+        out.push(new TrackedChange({ kind: 'row', row: 'ins', tr, owner, value: trPr.ins, inner, table }, undefined));
     if (trPr === null || trPr === void 0 ? void 0 : trPr.del)
-        out.push(new TrackedChange({ kind: 'row', row: 'del', tr, owner, value: trPr.del, inner }, undefined));
+        out.push(new TrackedChange({ kind: 'row', row: 'del', tr, owner, value: trPr.del, inner, table }, undefined));
     return out;
 }
 // --- CR-002 section 35: tables, cells, marks and sections --------------------------------------------
@@ -996,17 +1208,26 @@ function restoreSection(sectPr, change) {
  * cannot list (check 27: `getTrackedChanges` throws); a `w:numberingChange`, which Word no longer
  * writes and drops when one is put in, and whose record is the old number's text, so that a reject
  * too can only drop it; and a table's records that change nothing. A merge rejected gets the merge it
- * recorded back (docx4j's reading; unmeasured).
+ * recorded back (docx4j's reading; unmeasured). A `w:customXmlInsRangeStart` or `End` left without
+ * the form `holderInsertionAt` lists marks nothing that can be found, and goes either way.
  */
 export function resolveUnlisted(items, what) {
     const visit = (list) => {
-        var _a;
-        for (const el of list !== null && list !== void 0 ? list : []) {
+        var _a, _b;
+        if (!list)
+            return;
+        for (let i = list.length - 1; i >= 0; i--) {
+            const name = (_a = list[i].name) === null || _a === void 0 ? void 0 : _a.localPart;
+            if (name === 'customXmlInsRangeStart' || name === 'customXmlInsRangeEnd')
+                list.splice(i, 1);
+        }
+        for (const el of list) {
             const tn = typeNameOf(el);
             if (tn === 'org_docx4j_wml.P') {
-                const numPr = (_a = el.value.pPr) === null || _a === void 0 ? void 0 : _a.numPr;
+                const numPr = (_b = el.value.pPr) === null || _b === void 0 ? void 0 : _b.numPr;
                 if (numPr === null || numPr === void 0 ? void 0 : numPr.numberingChange)
                     delete numPr.numberingChange;
+                sweepMarkers(el.value.content);
                 continue;
             }
             if (tn === 'org_docx4j_wml.Tbl') {
@@ -1030,6 +1251,22 @@ export function resolveUnlisted(items, what) {
     };
     visit(items);
 }
+/** Stray `w:customXmlInsRangeStart` / `End` markers taken out of run-level content, through its holders and revisions. */
+function sweepMarkers(items) {
+    var _a;
+    if (!items)
+        return;
+    for (let i = items.length - 1; i >= 0; i--) {
+        const name = (_a = items[i].name) === null || _a === void 0 ? void 0 : _a.localPart;
+        if (name === 'customXmlInsRangeStart' || name === 'customXmlInsRangeEnd') {
+            items.splice(i, 1);
+            continue;
+        }
+        const v = items[i].value;
+        if (typeof v === 'object' && v !== null)
+            sweepMarkers(runItemsOf(v));
+    }
+}
 function resolveCellMerge(tcPr, what) {
     const change = tcPr.cellMerge;
     delete tcPr.cellMerge;

package/dist/model/content/index.d.mts

@@ -13,7 +13,7 @@ export { contentOf, isFlatOpc, rewriteRelationshipIds, type OoxmlOptions } from
 export { type SearchOptions, searchPattern, findAll, matchesOf, expandReplacement } from './search.mjs';
 export { segmentsOf, runsOf, runItemsOf, childrenOf, rowsOf, cellsOf, BLOCK_LEVEL_TYPES, SDT_TYPES, runOf, paragraphOf, textOfView, revisionKindOf, type TextSegment, type Located, type TextView, type TextViewOptions, type RevisionKind, type RevisionHolder } from './tree.mjs';
 export { TrackedChange, trackedChangesOfParagraph, trackedChangesOfRow, joinWithNext, type TrackedChangeType, type TrackedChangeTarget } from './TrackedChange.mjs';
-export { ChangeTracker, trackerOf, calendarOf, dateOf, wordCalendarOf, revisionDateOf, copyRPr, markDeleted, markInserted, highestAnnotationId, MARKUP_TYPES, toDeletedText, toRestoredText, restoreRPr, restorePPr, trackInsertedParagraph, trackInsertedTable, wrapNewRuns, paraRPrOf, rowPrOf, pruneParagraphProperties, type ChangeTrackingMode, type TrackingHost, type TrackingScope, type TrackedPart, } from './tracking.mjs';
+export { ChangeTracker, trackerOf, calendarOf, dateOf, wordCalendarOf, revisionDateOf, copyRPr, markDeleted, markInserted, highestAnnotationId, MARKUP_TYPES, toDeletedText, toRestoredText, restoreRPr, restorePPr, trackInsertedParagraph, trackInsertedTable, trackInsertedBlocks, wrapNewRuns, wrapInsertedRuns, paraRPrOf, rowPrOf, pruneParagraphProperties, type ChangeTrackingMode, type TrackingHost, type TrackingScope, type TrackedPart, } from './tracking.mjs';
 export { wml, wmlOne, p, r, t, br, tab, tbl, tr, tc, sdt, sdtPr, nextSdtId, sdtProperty, sdtKindOf, inlinePicture, rPrToElements, rPrFromElements, textOf, walk, walkAll, find, linkParents, applyRunOptions, readRunOptions, UNDERLINE_TO_WML, isElement, typeNameOf, W_NS, type Element, type Wrapper, type WmlOptions, type Raw, type Interpolated, type RunOptions, type RunFormatting, type ParagraphOptions, type TableOptions, type CellOptions, type SdtKind, type SdtForm, type SdtOptions } from '@docx4j/generated-objects-ts/builders/wml';
 export { StylesFacade, type StylePackageLike } from './stylesFacade.mjs';
 export { bindSnapshot, boundsOf, pathOf, type Bound, type BoundSnapshot } from './binder.mjs';

package/dist/model/content/index.mjs

@@ -16,7 +16,7 @@ export { searchPattern, findAll, matchesOf, expandReplacement } from './search.m
 export { segmentsOf, runsOf, runItemsOf, childrenOf, rowsOf, cellsOf, BLOCK_LEVEL_TYPES, SDT_TYPES, runOf, paragraphOf, textOfView, revisionKindOf } from './tree.mjs';
 // change tracking (CR-002 phase F)
 export { TrackedChange, trackedChangesOfParagraph, trackedChangesOfRow, joinWithNext } from './TrackedChange.mjs';
-export { ChangeTracker, trackerOf, calendarOf, dateOf, wordCalendarOf, revisionDateOf, copyRPr, markDeleted, markInserted, highestAnnotationId, MARKUP_TYPES, toDeletedText, toRestoredText, restoreRPr, restorePPr, trackInsertedParagraph, trackInsertedTable, wrapNewRuns, paraRPrOf, rowPrOf, pruneParagraphProperties, } from './tracking.mjs';
+export { ChangeTracker, trackerOf, calendarOf, dateOf, wordCalendarOf, revisionDateOf, copyRPr, markDeleted, markInserted, highestAnnotationId, MARKUP_TYPES, toDeletedText, toRestoredText, restoreRPr, restorePPr, trackInsertedParagraph, trackInsertedTable, trackInsertedBlocks, wrapNewRuns, wrapInsertedRuns, paraRPrOf, rowPrOf, pruneParagraphProperties, } from './tracking.mjs';
 // The objects package's builders, re-exported so that one import serves the content API and the tree it works on.
 export { wml, wmlOne, p, r, t, br, tab, tbl, tr, tc, sdt, sdtPr, nextSdtId, sdtProperty, sdtKindOf, inlinePicture, rPrToElements, rPrFromElements, textOf, walk, walkAll, find, linkParents, applyRunOptions, readRunOptions, UNDERLINE_TO_WML, isElement, typeNameOf, W_NS } from '@docx4j/generated-objects-ts/builders/wml';
 export { StylesFacade } from './stylesFacade.mjs';

package/dist/model/content/stylesFacade.mjs

@@ -3,19 +3,25 @@ import { linkParents } from './tree.mjs';
 import { parseXml } from '../../xml/dom.mjs';
 import { DEFAULT_STYLES_XML } from '../../parts/wml/defaultStyles.mjs';
 import { SPLICEABLE_STYLES_XML } from '../../parts/wml/spliceableStyles.mjs';
+import { commentStyles } from '../../parts/wml/commentStyles.mjs';
+import { placeholderStyle } from '../../parts/wml/placeholderStyle.mjs';
 import { Docx4JException } from '../../opc/exceptions.mjs';
 /**
  * Where a definition is looked up, unmarshalled once and never handed out (a copy is spliced in):
  * the defaults `createPackage()` writes, and then the nine styles docx4j's own `styles.xml` carries
  * **commented out** - which is why a created document has no `FootnoteText` although the file
- * appears to contain one, and why this facade exists (CR-002 section 22.2).
+ * appears to contain one, and why this facade exists (CR-002 section 22.2) - with Word's two comment
+ * styles and its `PlaceholderText` after them.
  */
 let sources;
 function styleSources() {
     return (sources !== null && sources !== void 0 ? sources : (sources = (async () => {
         const read = async (xml) => { var _a; return (_a = (await unmarshalNode(parseXml(xml))).value.style) !== null && _a !== void 0 ? _a : []; };
         const defaults = await read(DEFAULT_STYLES_XML);
-        return { defaults, all: [...defaults, ...(await read(SPLICEABLE_STYLES_XML))] };
+        // and Word's two comment styles, which the comment parts add when they are made, for a caller
+        // that makes the comment itself (CR-002 section 37), and Word's PlaceholderText, which a
+        // placeholder run names (CR-002 section 40)
+        return { defaults, all: [...defaults, ...(await read(SPLICEABLE_STYLES_XML)), ...commentStyles(), placeholderStyle()] };
     })()));
 }
 /**
@@ -99,7 +105,7 @@ function closureOf(wanted, present, source) {
         seen.add(id);
         const template = source.find((s) => s.styleId === id);
         if (template === undefined) {
-            throw new Docx4JException(`No definition to splice for the style ${id}: neither docx4j's default styles nor the nine it comments out carry one. Define it yourself on the styles part.`);
+            throw new Docx4JException(`No definition to splice for the style ${id}: neither docx4j's default styles, the nine it comments out, the two comment styles nor PlaceholderText carry one. Define it yourself on the styles part.`);
         }
         // what it is based on and linked to must be there too, and before it reads better in the part
         for (const dependency of [(_a = template.basedOn) === null || _a === void 0 ? void 0 : _a.val, (_b = template.link) === null || _b === void 0 ? void 0 : _b.val]) {

package/dist/model/content/tracking.d.mts

@@ -92,6 +92,20 @@ export declare function canonical(value: unknown): string;
 export interface TrackedPart {
     readonly contents?: unknown;
 }
+/**
+ * Makes sure the part's root lists a prefix in `mc:Ignorable`, appending it when absent, so that
+ * content in that prefix's namespace may be written in it; the facade then declares the prefix.
+ * This is docx4j's pattern - the writer of the content adds its prefix
+ * (`Paginate.declareW14Ignorable`) - and Jason's decision (CR-002 section 29). Since objects 0.3.1
+ * (its CR-008) the marshaller does it for every writer as well; these calls stay as the writer's
+ * own statement. False when there is no unmarshalled root to put it on. Every part a
+ * `Body` is over (document, header, footer, notes, comments) has a root that binds `mc:Ignorable`.
+ *
+ * The prefix must be the facade's conventional one for its namespace (`w15`, `w16du`): an
+ * application that does not know the namespace (Word 2010 and `w15`) opens the part only when the
+ * prefix is ignorable, as Word's own files declare it (CR-002 section 40).
+ */
+export declare function declareIgnorable(part: TrackedPart | undefined, prefix: string): boolean;
 /**
  * The per-package writer of revision markup. Created by the package while
  * `changeTrackingMode` is not `Off`; every content-API mutation asks its `Body` for one and,
@@ -174,16 +188,62 @@ export declare class ChangeTracker {
     markRowDeleted(tr: wml.Tr): void;
 }
 /**
- * A whole paragraph inserted: the mark is marked inserted and every run of it goes into a
- * `w:ins`. Word, splitting a paragraph, marks the *first* paragraph's mark instead and leaves
- * the new one the original mark; marking the new paragraph's own mark is the same document once
+ * A whole paragraph inserted: the mark is marked inserted (unless it already is) and every run of it
+ * goes into a `w:ins` - the runs in its hyperlinks, inline content controls, fields and smart tags as
+ * well (`wrapNewRuns`). Word, splitting a paragraph, marks the *first* paragraph's mark instead and
+ * leaves the new one the original mark; marking the new paragraph's own mark is the same document once
  * accepted or rejected and keeps the edit to the element that was added (CR-002 section 13).
  */
 export declare function trackInsertedParagraph(tracker: ChangeTracker, p: wml.P): void;
-/** Every top-level run of the paragraph that is not already in a revision, wrapped in one `w:ins` per group. */
+/**
+ * Every run of the paragraph not already in a revision, wrapped in one `w:ins` per group of touching
+ * runs - at the top level and inside the run-level holders, where Word's form decides (`test/README.md`
+ * check 30, CR-002 section 37 item 7): in a hyperlink or a simple field the `w:ins` goes inside, since
+ * neither can be in one (`CT_RunTrackChange` holds `EG_ContentRunContent` only); a smart tag goes
+ * *into* the `w:ins` with the runs beside it, its own runs plain; an inline content control or custom
+ * XML element keeps the `w:ins` inside and is itself marked inserted (`markHolderInserted`). Before,
+ * only the top level was wrapped, so that rejecting an inserted paragraph left a link's text behind
+ * (the editor's finding on 0.3.0, CR-002 section 37 item 4).
+ */
 export declare function wrapNewRuns(tracker: ChangeTracker, p: wml.P): void;
-/** A whole table inserted: every row is marked inserted and every paragraph in it is an insertion. */
+/**
+ * `wrapNewRuns` over run-level items that are about to go into a paragraph (`Paragraph.insertItemsAt`):
+ * the runs among them, and those in their holders, wrapped in `w:ins`; a content control or custom
+ * XML element among them marked inserted. `parent` is what the items' array belongs to.
+ */
+export declare function wrapInsertedRuns(tracker: ChangeTracker, items: Element[] | undefined, parent: object): void;
+/** A whole table inserted: every row is marked inserted and everything in its cells is an insertion (`trackInsertedBlocks`). */
 export declare function trackInsertedTable(tracker: ChangeTracker, tbl: wml.Tbl): void;
+/**
+ * Block content inserted, whatever it holds: a paragraph (`trackInsertedParagraph`), a table
+ * (`trackInsertedTable`: rows inside row-level content controls, nested tables in its cells), and a
+ * block-level content control's or custom XML element's content, recursively, the element itself
+ * marked inserted (`markHolderInserted`; `owner` is the array holding `block`, which takes the
+ * markers). What `Body.insertElement` and `Table.addRows` track new content by (CR-002 section 37).
+ */
+export declare function trackInsertedBlock(tracker: ChangeTracker, block: Element, owner: Element[]): void;
+/** `trackInsertedBlock` over every item of a list, which is their owner. */
+export declare function trackInsertedBlocks(tracker: ChangeTracker, items: Element[] | undefined): void;
+/**
+ * The elements Word marks inserted as a whole with `w:customXmlInsRangeStart` / `End`: a content
+ * control or a custom XML element (check 30 measured the control at run and block level; a smart tag
+ * goes into the `w:ins` instead, and a hyperlink or field has no form of its own). Row- and cell-level
+ * ones are listed for the reader: `trackInsertedTable` walks through them to the rows and cells, and
+ * does not mark them.
+ */
+export declare const HOLDER_TYPES: ReadonlySet<string>;
+/** The list a holder's content is in (`w:sdtContent`'s for a control, its own for custom XML), created when absent. */
+export declare function holderItemsOf(value: object): Element[] | undefined;
+/**
+ * A content control or custom XML element inserted under tracking, as Word writes it (check 30): a
+ * `w:customXmlInsRangeStart` before the element with its `w:customXmlInsRangeEnd` first inside its
+ * content, and a second start last inside with its end after the element. Rejecting takes the element
+ * away and leaves its content where it stood (`TrackedChange`'s `holder` target); without the markers
+ * an element holding only an insertion reads as one that was there before and was typed into, which
+ * rejecting keeps (check 30, existing-control-typed). `inside` tracks the content between the two
+ * pairs, so that the ids run in document order as Word's do.
+ */
+export declare function markHolderInserted(tracker: ChangeTracker, holder: Element, owner: Element[], inside: () => void): void;
 /** The paragraph mark's run properties (`w:pPr/w:rPr`), created when absent. */
 export declare function paraRPrOf(p: wml.P): wml.ParaRPr;
 /** The row's properties (`w:trPr`), created when absent. */