@docx4j/core-ts 0.2.2 → 0.3.1

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

@@ -195,15 +195,27 @@ export declare class Body {
      * paragraph is marked deleted and every row's `w:trPr` takes a `w:del` instead.
      */
     clear(): void;
-    /** Every tracked change in this body, in document order. */
+    /**
+     * Every tracked change in this body, in document order. Touching insertions or deletions by one
+     * author - a deleted paragraph's text and mark, a deletion across a mark - are one change, as
+     * Office JS lists them (CR-002 section 29, checks 22 and 23).
+     */
     getTrackedChanges(): TrackedChange[];
     /**
      * Accepts every tracked change, last first so that a paragraph join never disturbs one still
-     * to do (docx4j `AcceptTrackedChanges` is the reference). Returns how many were accepted.
+     * to do (docx4j `AcceptTrackedChanges` is the reference). Returns how many were listed.
      */
     acceptAll(): number;
-    /** Rejects every tracked change, last first. Returns how many were rejected. */
+    /** Rejects every tracked change, last first. Returns how many were listed. */
     rejectAll(): number;
+    /**
+     * Resolving one change can leave another to be listed afresh: accepting a move carries a deletion
+     * nested in its moved text out of it, and resolving a broken move dissolves the rest of it into a
+     * new `w:ins` or `w:del` (CR-002 section 29), so the list read first goes stale. The list is read
+     * again after each pass until nothing is left, as "all" promises (found by the editor's C5); a
+     * pass that resolves nothing ends it.
+     */
+    private resolveAll;
     /** Every `w:tr` in this body's tables, in document order (rows of nested tables included). */
     private rowElements;
     /** The part's XML (extension; Office JS getOoxml wraps it in a package). */

package/dist/model/content/Body.mjs

@@ -11,8 +11,8 @@ import { InlinePicture, addImage, writableWidthEmu } from './InlinePicture.mjs';
 import { contentOf } from './ooxml.mjs';
 import { expandReplacement } from './search.mjs';
 import { commentApi } from './comments.mjs';
-import { trackerOf, trackInsertedParagraph, trackInsertedTable } from './tracking.mjs';
-import { trackedChangesOfRow } from './TrackedChange.mjs';
+import { trackerOf, trackInsertedBlock, markHolderInserted } from './tracking.mjs';
+import { trackedChangesOfRow, trackedChangeTokensOfParagraph, groupTouching, BREAK, tablePropertiesChangeOf, cellChangeOf, bodySectionChangeOf, resolveUnlisted, holderInsertionAt } from './TrackedChange.mjs';
 import { listsOf, listLabelsOf } from './List.mjs';
 /**
  * A subset of Office JS `Word.Body` over any container with block-level content: the main
@@ -215,7 +215,8 @@ export class Body {
     }
     /** The package's change tracker while `changeTrackingMode` is on; undefined when it is off (CR-002 phase F). */
     get changeTracker() {
-        return trackerOf(this.package_);
+        var _a;
+        return (_a = trackerOf(this.package_)) === null || _a === void 0 ? void 0 : _a.forPart(this.part);
     }
     insertParagraph(text, location) {
         const el = paragraphOf(text === '' ? [] : [textRun(text)]);
@@ -300,14 +301,12 @@ export class Body {
         for (const el of elements) {
             linkParents(el, owner);
             const tn = typeNameOf(el);
-            if (tn === 'org_docx4j_wml.P') {
+            if (tn === 'org_docx4j_wml.P')
                 this.assignParaId(el.value);
-                if (tracker)
-                    trackInsertedParagraph(tracker, el.value);
-            }
-            else if (tn === 'org_docx4j_wml.Tbl' && tracker) {
-                trackInsertedTable(tracker, el.value);
-            }
+            // everything it holds is an insertion: the runs in its links and inline controls, the rows and
+            // nested tables of a table, a block control's content and the control itself (CR-002 section 37)
+            if (tracker)
+                trackInsertedBlock(tracker, el, container);
         }
         const first = elements[0];
         return typeNameOf(first) === 'org_docx4j_wml.P' ? new Paragraph(first, container, this) : { element: first, container };
@@ -378,57 +377,116 @@ export class Body {
             p.delete();
     }
     // --- change tracking (CR-002 phase F) ---------------------------------------------------
-    /** Every tracked change in this body, in document order. */
+    /**
+     * Every tracked change in this body, in document order. Touching insertions or deletions by one
+     * author - a deleted paragraph's text and mark, a deletion across a mark - are one change, as
+     * Office JS lists them (CR-002 section 29, checks 22 and 23).
+     */
     getTrackedChanges() {
         const out = [];
         const visit = (items, into) => {
-            var _a;
-            for (const el of items) {
+            var _a, _b;
+            for (let i = 0; i < items.length; i++) {
+                const el = items[i];
                 const tn = typeNameOf(el);
                 if (tn === 'org_docx4j_wml.P') {
-                    into.push(...new Paragraph(el, items, this).getTrackedChanges());
+                    into.push(...trackedChangeTokensOfParagraph(new Paragraph(el, items, this)));
+                    continue;
+                }
+                // a block control or custom XML element that is itself an insertion (check 30): one piece,
+                // grouping with the insertions around and inside it, as Word lists them
+                const inserted = holderInsertionAt(items, i, undefined);
+                if (inserted) {
+                    into.push(inserted);
+                    visit((_a = childrenOf(items[i + 1].value)) !== null && _a !== void 0 ? _a : [], into);
+                    i += 2;
                     continue;
                 }
                 const v = el.value;
                 if (typeof v !== 'object' || v === null)
                     continue;
                 if (tn === 'org_docx4j_wml.Tbl') {
+                    // A table is no break of its own: an inserted or deleted row groups with the rows and the
+                    // inserted text touching it, as Office JS lists them (check 31: a three-row table between two
+                    // inserted paragraphs is one change; rows added at a table's end with a paragraph typed after
+                    // it, one; a paragraph whose mark is plain before rows added at the start, two). Its property
+                    // records are one change of their own where the table stands (CR-002 section 35), kept apart.
+                    const tableChange = tablePropertiesChangeOf(el);
+                    if (tableChange)
+                        into.push(BREAK, tableChange, BREAK);
                     for (const row of rowsOf(v)) {
                         // A row that is itself a revision reports as one change, as Office JS does: the
                         // markup its cells carry (Word marks every run and mark of a deleted or inserted row)
                         // belongs to that change, which accepts or rejects it along with the row.
-                        const inner = [];
-                        for (const cell of cellsOf(row.element.value))
-                            visit((_a = childrenOf(cell.element.value)) !== null && _a !== void 0 ? _a : [], inner);
-                        const rowChanges = trackedChangesOfRow(row.element, row.container, inner);
-                        into.push(...(rowChanges.length > 0 ? rowChanges : inner));
+                        const tokens = [];
+                        for (const cell of cellsOf(row.element.value)) {
+                            const cellChange = cellChangeOf(cell.element, cell.container, row.element.value);
+                            if (cellChange)
+                                tokens.push(cellChange, BREAK);
+                            visit((_b = childrenOf(cell.element.value)) !== null && _b !== void 0 ? _b : [], tokens);
+                            tokens.push(BREAK);
+                        }
+                        const inner = groupTouching(tokens);
+                        const rowChanges = trackedChangesOfRow(row.element, row.container, inner, { element: el, container: items });
+                        if (rowChanges.length > 0)
+                            into.push(...rowChanges);
+                        else {
+                            into.push(BREAK);
+                            for (const change of inner)
+                                into.push(change, BREAK);
+                        }
                     }
                     continue;
                 }
+                // a block-level content control or custom XML element keeps what is inside it apart; a
+                // marker between paragraphs (a bookmark or range end) keeps nothing apart
                 const children = childrenOf(v);
-                if (children)
+                if (children) {
+                    into.push(BREAK);
                     visit(children, into);
+                    into.push(BREAK);
+                }
             }
         };
         visit(this.content, out);
-        return out;
+        // the body's last section, after everything in it
+        const section = bodySectionChangeOf(this.container);
+        if (section)
+            out.push(BREAK, section);
+        return groupTouching(out);
     }
     /**
      * Accepts every tracked change, last first so that a paragraph join never disturbs one still
-     * to do (docx4j `AcceptTrackedChanges` is the reference). Returns how many were accepted.
+     * to do (docx4j `AcceptTrackedChanges` is the reference). Returns how many were listed.
      */
     acceptAll() {
-        const changes = this.getTrackedChanges();
-        for (let i = changes.length - 1; i >= 0; i--)
-            changes[i].accept();
-        return changes.length;
+        return this.resolveAll('accept');
     }
-    /** Rejects every tracked change, last first. Returns how many were rejected. */
+    /** Rejects every tracked change, last first. Returns how many were listed. */
     rejectAll() {
-        const changes = this.getTrackedChanges();
-        for (let i = changes.length - 1; i >= 0; i--)
-            changes[i].reject();
-        return changes.length;
+        return this.resolveAll('reject');
+    }
+    /**
+     * Resolving one change can leave another to be listed afresh: accepting a move carries a deletion
+     * nested in its moved text out of it, and resolving a broken move dissolves the rest of it into a
+     * new `w:ins` or `w:del` (CR-002 section 29), so the list read first goes stale. The list is read
+     * again after each pass until nothing is left, as "all" promises (found by the editor's C5); a
+     * pass that resolves nothing ends it.
+     */
+    resolveAll(what) {
+        let changes = this.getTrackedChanges();
+        const count = changes.length;
+        while (changes.length > 0) {
+            for (let i = changes.length - 1; i >= 0; i--)
+                changes[i][what]();
+            const left = this.getTrackedChanges();
+            if (left.length >= changes.length)
+                break;
+            changes = left;
+        }
+        // and what is never listed: a cell merge, a numbering change, records that change nothing
+        resolveUnlisted(this.content, what);
+        return count;
     }
     /** Every `w:tr` in this body's tables, in document order (rows of nested tables included). */
     rowElements() {
@@ -690,6 +748,10 @@ export class Body {
         this.content.length = 0;
         this.content.push(sdt);
         linkParents(sdt, this.container);
+        // under tracking the control itself is the insertion, its content what it was (check 30)
+        const tracker = this.changeTracker;
+        if (tracker)
+            markHolderInserted(tracker, sdt, this.content, () => { });
         return new ContentControl(sdt, this.content, this);
     }
 }

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

@@ -2,7 +2,7 @@ import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
 import { Body } from './Body.mjs';
 import { Paragraph } from './Paragraph.mjs';
 import { Range } from './Range.mjs';
-import { type CommentContent, type CommentOptions, type CommentParts } from './comments.mjs';
+import { type CommentContent, type CommentOptions, type CommentEntry, type CommentParts } from './comments.mjs';
 /**
  * A subset of Office JS `Word.Comment` over a `w:comment` and the markers that anchor it. A view:
  * the tree is the state, and a view may be created and discarded freely. Replies are `Comment`s
@@ -33,7 +33,12 @@ export declare class Comment {
     get initials(): string;
     /** The author's email from `w:people`, '' when the document records none. */
     get authorEmail(): string;
-    /** `w:date`; undefined when the comment carries none. */
+    /**
+     * When the comment was made, as Word means it (CR-002 section 29, the revision dates' rule): its
+     * `w16cex:dateUtc` when the document has one for it, which is UTC; else `w:date`, which Word writes
+     * on the author's local wall clock whatever its `Z` says, read as local time. Undefined when the
+     * comment carries neither.
+     */
     get creationDate(): Date | undefined;
     /** The comment's paragraphs as a `Body` (extension: the same content API as the document's). */
     get commentBody(): Body;
@@ -80,9 +85,29 @@ export declare class Comment {
  * throws.
  */
 export declare function insertComment(range: Range, content: CommentContent, options?: CommentOptions): Promise<Comment>;
+/**
+ * A comment's entry for markers the caller placed (CR-002 section 36, asked by the editor for its
+ * E4.e, which places a new comment's markers itself: a selection may span paragraphs, where
+ * `Range.insertComment` anchors in one). Everything `insertComment` writes but the markers: the
+ * `w:comment` with the given id, author, initials, date and paragraphs (the first with a
+ * `w14:paraId`); its `w15:commentEx` (`w15:done="0"`, and `w15:paraIdParent` for a reply); its
+ * `w16cid:commentId` where that part exists, and its `w16cex:commentExtensible` where that one does;
+ * and the author's `w15:person`. The comment parts are created as `insertComment` creates them, and
+ * the date follows section 29's rule (`w:date` on the local wall clock, `w16cex:dateUtc` the date
+ * given). The id must be unused in the comments part - markers naming it are expected, being the
+ * caller's - and is not checked against them; a comment with no markers is still a comment, which
+ * Word shows unanchored.
+ */
+export declare function addCommentEntry(body: Body, entry: CommentEntry): Promise<Comment>;
 /**
  * `getComments()` on a body, a paragraph or a range: the comments anchored there in document
  * order, replies nested under their parent (a reply is in the array only when its parent is not).
  */
 export declare function commentsOf(scope: Body | Paragraph | Range): Promise<Comment[]>;
+/**
+ * Comments whose anchored text went with a rejected insertion or an accepted deletion (check 32;
+ * `TrackedChange`'s `removeRevision`) had their markers removed then; their entries go here, with
+ * their replies, when the comments are next read or the package is saved (`WordprocessingMLPackage.saveTo`).
+ */
+export declare function flushPendingCommentRemovals(body: Body): Promise<void>;
 export type { CommentParts, Author } from './comments.mjs';

package/dist/model/content/Comment.mjs

@@ -8,7 +8,8 @@ import { Body } from './Body.mjs';
 import { Paragraph } from './Paragraph.mjs';
 import { Range } from './Range.mjs';
 import { runOf, paragraphOf, typeNameOf } from './tree.mjs';
-import { COMMENT_REFERENCE_STYLE, COMMENT_TEXT_STYLE, calendarToDate, commentExOf, commentIdsOf, commentPartsAccess, commentParaId, dateToCalendar, initialsOf, isDone, markersOf, markersOfParagraph, nextCommentId, paraIdTaken, randomHexId, removeMarkers, setCommentApi, } from './comments.mjs';
+import { revisionDateOf, wordCalendarOf, copyRPr } from './tracking.mjs';
+import { COMMENT_REFERENCE_STYLE, COMMENT_TEXT_STYLE, commentExOf, commentIdsOf, commentPartsAccess, commentParaId, initialsOf, isDone, markersOf, markersOfParagraph, nextCommentId, paraIdTaken, randomHexId, removeMarkers, setCommentApi, } from './comments.mjs';
 /**
  * A subset of Office JS `Word.Comment` over a `w:comment` and the markers that anchor it. A view:
  * the tree is the state, and a view may be created and discarded freely. Replies are `Comment`s
@@ -49,9 +50,21 @@ export class Comment {
         const ad = /^S::([^:]+)::/.exec(userId);
         return ad ? ad[1] : userId;
     }
-    /** `w:date`; undefined when the comment carries none. */
+    /**
+     * When the comment was made, as Word means it (CR-002 section 29, the revision dates' rule): its
+     * `w16cex:dateUtc` when the document has one for it, which is UTC; else `w:date`, which Word writes
+     * on the author's local wall clock whatever its `Z` says, read as local time. Undefined when the
+     * comment carries neither.
+     */
     get creationDate() {
-        return calendarToDate(this.element.date);
+        var _a;
+        for (const el of [...((_a = this.element.content) !== null && _a !== void 0 ? _a : [])].reverse()) {
+            const paraId = typeNameOf(el) === 'org_docx4j_wml.P' ? el.value.paraId : undefined;
+            const utc = paraId ? this.parts.datesUtc.get(paraId.toUpperCase()) : undefined;
+            if (utc)
+                return utc;
+        }
+        return revisionDateOf({ date: this.element.date });
     }
     /** The comment's paragraphs as a `Body` (extension: the same content API as the document's). */
     get commentBody() {
@@ -195,6 +208,7 @@ export class Comment {
                 ids.splice(i, 1);
                 if (durableId)
                     (_c = this.parts.extensible) === null || _c === void 0 ? void 0 : _c.remove(durableId);
+                this.parts.datesUtc.delete(paraId.toUpperCase());
             }
         }
     }
@@ -226,9 +240,48 @@ export class Comment {
 function annotationRefRun() {
     return runOf([el.annotationRef(wmlFactory.createRAnnotationRef())], applyRunOptions({}, { style: COMMENT_REFERENCE_STYLE }));
 }
-/** The run that anchors a comment in the body: `w:commentReference` in the `CommentReference` style. */
-function referenceRun(id) {
-    return runOf([el.commentReference(wmlFactory.createRCommentReference({ id }))], applyRunOptions({}, { style: COMMENT_REFERENCE_STYLE }));
+/**
+ * The run that anchors a comment in the body: `w:commentReference` in the `CommentReference` style,
+ * over the run properties of the text it stands by when given (Word's reference run for a comment at
+ * a caret carried the text's `w:sz`, CR-002 section 36).
+ */
+function referenceRun(id, textRPr) {
+    var _a;
+    const rPr = applyRunOptions((_a = copyRPr(textRPr)) !== null && _a !== void 0 ? _a : {}, { style: COMMENT_REFERENCE_STYLE });
+    return runOf([el.commentReference(wmlFactory.createRCommentReference({ id }))], rPr);
+}
+/** A comment marker that takes no room: a range start or end, or a run holding only a reference. */
+function isCommentMarker(item) {
+    var _a, _b;
+    if (!item)
+        return false;
+    const name = (_a = item.name) === null || _a === void 0 ? void 0 : _a.localPart;
+    if (name === 'commentRangeStart' || name === 'commentRangeEnd')
+        return true;
+    if (typeNameOf(item) !== 'org_docx4j_wml.R')
+        return false;
+    const content = ((_b = item.value.content) !== null && _b !== void 0 ? _b : []);
+    return content.length > 0 && content.every((c) => { var _a; return ((_a = c.name) === null || _a === void 0 ? void 0 : _a.localPart) === 'commentReference'; });
+}
+/**
+ * Where an empty range's markers go when other comments' empty ranges already stand at the caret:
+ * inside them, right after their starts, as Word nests a second comment made at the same place
+ * (start 0, start 1, end 1, reference 1, end 0, reference 0; CR-002 section 36). A start counts only
+ * when its comment's end is at the caret too, so a comment over text that begins there is not entered.
+ */
+function nestedIndex(owner, index) {
+    var _a;
+    let from = index;
+    while (isCommentMarker(owner[from - 1]))
+        from--;
+    let to = index;
+    while (isCommentMarker(owner[to]))
+        to++;
+    const endsHere = new Set(owner.slice(from, to).filter((e) => { var _a; return ((_a = e.name) === null || _a === void 0 ? void 0 : _a.localPart) === 'commentRangeEnd'; }).map((e) => String(e.value.id)));
+    let at = from;
+    while (at < to && ((_a = owner[at].name) === null || _a === void 0 ? void 0 : _a.localPart) === 'commentRangeStart' && endsHere.has(String(owner[at].value.id)))
+        at++;
+    return at > from ? at : index;
 }
 /** A paragraph of a comment: the `CommentText` style, opened by the annotation reference run. */
 function commentParagraph(text, first) {
@@ -248,11 +301,10 @@ function parentOf(element) {
     return element.value.PARENT;
 }
 /**
- * Where a marker for this segment's run goes: beside the run, but outside the `w:ins` or `w:del`
- * the run sits in, so that a comment made while change tracking is on is a comment and not an
- * insertion of its own (CR-002 section 13). Accepting or rejecting the revision then leaves the
- * comment where it is; the cost is that a comment on part of an insertion widens to the whole of
- * it, which is what Word shows anyway once the insertion is accepted.
+ * Where a marker for this segment's run goes when it is not put inside the revision the run sits
+ * in (`placeAround`): beside the run, but outside the `w:ins` or `w:del`, so that a comment made
+ * while change tracking is on is a comment and not an insertion of its own (CR-002 section 13).
+ * Accepting or rejecting the revision then leaves the comment where it is.
  */
 function markerSite(seg, fallback, after) {
     var _a;
@@ -271,23 +323,44 @@ function placeAround(range, id) {
     const covered = range.end > range.start ? paragraph.segments().filter((s) => s.end > range.start && s.start < range.end) : [];
     const start = el.commentRangeStart(wmlFactory.createCommentRangeStart({ id }));
     const end = el.commentRangeEnd(wmlFactory.createCommentRangeEnd({ id }));
-    const reference = referenceRun(id);
     if (covered.length === 0) {
-        // an empty range or an empty paragraph: the reference run only, which is all Word requires
+        // An empty range or an empty paragraph: both range markers with nothing between them, then the
+        // reference run in the text's run properties, and a later comment at the same place nested inside
+        // the earlier - what Word writes (measured by Jason 2026-09-29, CR-002 section 36).
         const segments = paragraph.segments();
         const after = segments.find((s) => s.start >= range.start);
         const before = [...segments].reverse().find((s) => s.end <= range.start);
+        const text = after !== null && after !== void 0 ? after : before;
         const site = after ? markerSite(after, paragraph.p, false) : before ? markerSite(before, paragraph.p, true) : undefined;
-        if (site)
-            insertAt(site.owner, site.index, [reference], site.parent);
-        else
-            insertAt(((_a = (_b = paragraph.p).content) !== null && _a !== void 0 ? _a : (_b.content = [])), paragraph.p.content.length, [reference], paragraph.p);
+        const owner = site ? site.owner : ((_a = (_b = paragraph.p).content) !== null && _a !== void 0 ? _a : (_b.content = []));
+        const index = nestedIndex(owner, site ? site.index : owner.length);
+        insertAt(owner, index, [start, end, referenceRun(id, text === null || text === void 0 ? void 0 : text.run.rPr)], site ? site.parent : paragraph.p);
         return;
     }
-    const after = markerSite(covered[covered.length - 1], paragraph.p, true);
-    insertAt(after.owner, after.index, [end, reference], after.parent);
-    const before = markerSite(covered[0], paragraph.p, false);
-    insertAt(before.owner, before.index, [start], before.parent);
+    const reference = referenceRun(id);
+    const first = covered[0];
+    const last = covered[covered.length - 1];
+    // A comment on part of an insertion, as Word writes it (the editor's measure-word2010.docx and
+    // measure-word15.docx, 2026-09-30; CR-002 section 38): the range start inside the w:ins before the
+    // first commented run, the w:ins closed at the range's end - the rest of it a second w:ins with a
+    // new id - and the end marker and the plain reference run after it. So the anchor stays narrow
+    // and the reference is no insertion. Before, both markers went outside the w:ins, which widened
+    // the anchor to the whole insertion. A deletion or a move keeps the markers outside (a deletion's
+    // form is not measured; a move's halves are not to be split).
+    const inInsertion = (seg) => { var _a; return ((_a = seg.revision) === null || _a === void 0 ? void 0 : _a.kind) === 'ins'; };
+    if (inInsertion(last)) {
+        paragraph.splitHolderAround(last.revision, last.runIndex + 1, [end, reference], () => paragraph.nextAnnotationId());
+    }
+    else {
+        const after = markerSite(last, paragraph.p, true);
+        insertAt(after.owner, after.index, [end, reference], after.parent);
+    }
+    if (inInsertion(first))
+        insertAt(first.runOwner, first.runIndex, [start], first.revision.value);
+    else {
+        const before = markerSite(first, paragraph.p, false);
+        insertAt(before.owner, before.index, [start], before.parent);
+    }
 }
 /** Writes the markers of a reply next to its parent's, as Word nests them. */
 function placeAfter(body, parentId, id) {
@@ -315,17 +388,19 @@ function placeAfter(body, parentId, id) {
  * paragraphs come checked, by `paragraphsOfContent` before the markers were placed.
  */
 function addComment(parts, body, id, paragraphs, parent, options) {
-    var _a, _b, _c, _d, _e, _f, _g;
-    var _h, _j;
+    var _a, _b, _c, _d, _e, _f;
+    var _g, _h;
     const author = (_a = options === null || options === void 0 ? void 0 : options.author) !== null && _a !== void 0 ? _a : parts.author;
+    // one instant for w:date (the local wall clock, as Word writes it) and w16cex:dateUtc (UTC)
+    const made = (_b = options === null || options === void 0 ? void 0 : options.date) !== null && _b !== void 0 ? _b : new Date();
     const paraId = randomHexId((candidate) => paraIdTaken(parts, body.container, candidate));
     paragraphs[0].value.paraId = paraId;
     const comment = wmlFactory.createCommentsComment({
-        id, author: author.name, initials: (_b = options === null || options === void 0 ? void 0 : options.initials) !== null && _b !== void 0 ? _b : initialsOf(author),
-        date: dateToCalendar((_c = options === null || options === void 0 ? void 0 : options.date) !== null && _c !== void 0 ? _c : new Date()),
+        id, author: author.name, initials: (_c = options === null || options === void 0 ? void 0 : options.initials) !== null && _c !== void 0 ? _c : initialsOf(author),
+        date: wordCalendarOf(made),
         content: paragraphs,
     });
-    const comments = ((_d = (_h = parts.comments).comment) !== null && _d !== void 0 ? _d : (_h.comment = []));
+    const comments = ((_d = (_g = parts.comments).comment) !== null && _d !== void 0 ? _d : (_g.comment = []));
     comments.push(comment);
     linkParents(comment, parts.comments);
     const extended = parts.ensureCommentsEx();
@@ -337,9 +412,12 @@ function addComment(parts, body, id, paragraphs, parent, options) {
     if (parts.commentsIds) {
         const durableId = randomHexId((candidate) => { var _a; return ((_a = parts.commentsIds.commentId) !== null && _a !== void 0 ? _a : []).some((e) => e.durableId === candidate); });
         const commentId = w16cidFactory.createCTCommentId({ paraId, durableId });
-        ((_f = (_j = parts.commentsIds).commentId) !== null && _f !== void 0 ? _f : (_j.commentId = [])).push(commentId);
+        ((_f = (_h = parts.commentsIds).commentId) !== null && _f !== void 0 ? _f : (_h.commentId = [])).push(commentId);
         linkParents(commentId, parts.commentsIds);
-        (_g = parts.extensible) === null || _g === void 0 ? void 0 : _g.set(durableId, new Date());
+        if (parts.extensible) {
+            parts.extensible.set(durableId, made);
+            parts.datesUtc.set(paraId.toUpperCase(), made);
+        }
     }
     addPerson(parts, author.name, author.email);
     return new Comment(comment, parts, body);
@@ -381,6 +459,31 @@ export async function insertComment(range, content, options) {
     placeAround(range, id);
     return addComment(parts, body, id, paragraphs, undefined, options);
 }
+/**
+ * A comment's entry for markers the caller placed (CR-002 section 36, asked by the editor for its
+ * E4.e, which places a new comment's markers itself: a selection may span paragraphs, where
+ * `Range.insertComment` anchors in one). Everything `insertComment` writes but the markers: the
+ * `w:comment` with the given id, author, initials, date and paragraphs (the first with a
+ * `w14:paraId`); its `w15:commentEx` (`w15:done="0"`, and `w15:paraIdParent` for a reply); its
+ * `w16cid:commentId` where that part exists, and its `w16cex:commentExtensible` where that one does;
+ * and the author's `w15:person`. The comment parts are created as `insertComment` creates them, and
+ * the date follows section 29's rule (`w:date` on the local wall clock, `w16cex:dateUtc` the date
+ * given). The id must be unused in the comments part - markers naming it are expected, being the
+ * caller's - and is not checked against them; a comment with no markers is still a comment, which
+ * Word shows unanchored.
+ */
+export async function addCommentEntry(body, entry) {
+    var _a;
+    const paragraphs = paragraphsOfContent(entry.content);
+    const parts = await commentPartsAccess().create(body);
+    const id = entry.id;
+    if (!Number.isInteger(id) || id < 0)
+        throw new Docx4JException(`A comment id must be a non-negative integer, not ${id}`);
+    if (((_a = parts.comments.comment) !== null && _a !== void 0 ? _a : []).some((c) => c.id === id)) {
+        throw new Docx4JException(`The comment id ${id} is already in use in this document's comments part`);
+    }
+    return addComment(parts, body, id, paragraphs, entry.parent, entry);
+}
 /**
  * The `w:id` for a new comment: the caller's when given, checked unused across the comments part and
  * the markers in the story, else the next free one. A clash throws rather than renumbering, as a
@@ -415,12 +518,59 @@ function paragraphsOfContent(content) {
  * order, replies nested under their parent (a reply is in the array only when its parent is not).
  */
 export async function commentsOf(scope) {
-    var _a, _b;
     const paragraph = scope instanceof Range ? scope.paragraph : scope instanceof Paragraph ? scope : undefined;
     const body = paragraph ? paragraph.parentBody : scope;
     const parts = await commentPartsAccess().load(body);
     if (!parts)
         return [];
+    await flushPendingRemovals(body, parts);
+    const views = viewsOf(parts, body);
+    const ids = scope instanceof Range ? idsInRange(scope) : paragraph ? unique(markersOfParagraph(paragraph.element, paragraph.container).map((m) => m.id)) : commentIdsOf(body.container);
+    const inScope = new Set(ids);
+    const out = [];
+    for (const id of ids) {
+        const view = views.get(id);
+        if (!view)
+            continue;
+        if (view.parent && inScope.has(view.parent.id))
+            continue;
+        out.push(view);
+    }
+    return out;
+}
+/**
+ * Comments whose anchored text went with a rejected insertion or an accepted deletion (check 32;
+ * `TrackedChange`'s `removeRevision`) had their markers removed then; their entries go here, with
+ * their replies, when the comments are next read or the package is saved (`WordprocessingMLPackage.saveTo`).
+ */
+export async function flushPendingCommentRemovals(body) {
+    var _a;
+    const pkg = body.package_;
+    if (!((_a = pkg === null || pkg === void 0 ? void 0 : pkg.pendingCommentRemovals) === null || _a === void 0 ? void 0 : _a.size))
+        return;
+    const parts = await commentPartsAccess().load(body);
+    if (!parts) {
+        pkg.pendingCommentRemovals.clear();
+        return;
+    }
+    await flushPendingRemovals(body, parts);
+}
+async function flushPendingRemovals(body, parts) {
+    const pkg = body.package_;
+    const pending = pkg === null || pkg === void 0 ? void 0 : pkg.pendingCommentRemovals;
+    if (!(pending === null || pending === void 0 ? void 0 : pending.size))
+        return;
+    const views = viewsOf(parts, body);
+    for (const id of [...pending]) {
+        const view = views.get(id);
+        if (view)
+            await view.delete();
+        pending.delete(id);
+    }
+}
+/** A `Comment` view per entry in the parts, replies linked to their parents. */
+function viewsOf(parts, body) {
+    var _a, _b;
     const views = new Map();
     for (const comment of (_a = parts.comments.comment) !== null && _a !== void 0 ? _a : []) {
         if (typeof comment.id === 'number' && !views.has(comment.id))
@@ -438,18 +588,7 @@ export async function commentsOf(scope) {
         if (parent && parent !== view)
             parent.addReply(view);
     }
-    const ids = scope instanceof Range ? idsInRange(scope) : paragraph ? unique(markersOfParagraph(paragraph.element, paragraph.container).map((m) => m.id)) : commentIdsOf(body.container);
-    const inScope = new Set(ids);
-    const out = [];
-    for (const id of ids) {
-        const view = views.get(id);
-        if (!view)
-            continue;
-        if (view.parent && inScope.has(view.parent.id))
-            continue;
-        out.push(view);
-    }
-    return out;
+    return views;
 }
 /** The comments a range touches: a comment whose markers overlap [start, end]. */
 function idsInRange(range) {

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

@@ -94,6 +94,12 @@ export declare class ContentControl {
     private parentParagraph;
     /** The offsets a run-level control covers in its paragraph. */
     private runSpan;
+    /**
+     * Text into a run control that holds no run: a new run in its content, in a `w:ins` under
+     * tracking (Word: check 30, new-control-typed), placed before the control's trailing insertion
+     * marker when it is itself an insertion.
+     */
+    private insertIntoEmpty;
     /** The control's data binding (Office JS `xmlMapping`), backed by `w:dataBinding`. */
     get xmlMapping(): XmlMapping;
     /**