@docx4j/core-ts 0.1.5 → 0.2.1

package/README.md

@@ -103,6 +103,25 @@ p?.insertParagraph('Inserted after the fourth block', 'After');
 (await pkg.paragraphAt({ contains: 'Chapter 2' }))?.delete();
 ```
 
+`search` and `replaceText` take Office JS's `matchCase`, `matchWholeWord` and `matchWildcards`
+(Word's `?`, `*`, `[a-z]`, `<`, `>`, `@` and `(...)` groups, with `\1` in the replacement), and
+`matchRegExp` for an ECMAScript regular expression, with `$1` in the replacement. A match never
+crosses a paragraph.
+
+```ts
+body.replaceText('(\\d+) pages', '$1 pp.', { matchRegExp: true });
+body.replaceText('(quick) (fox)', '\\2 \\1', { matchWildcards: true });
+```
+
+`range.hyperlink = 'https://example.com/'` (or `'#bookmark'` for a place in the document) makes the
+range a link, styled as Word styles one: its runs take the `Hyperlink` character style, over any
+character style they had, and lose their direct colour; `''` removes the links the range touches,
+style and all. A document that lacks the `Hyperlink` definition gets it when it is saved.
+
+A style the document lacks is spliced in from docx4j's defaults, with the styles it is based on and
+linked to: `await pkg.styles.ensure(['FootnoteText', 'FootnoteReference'])` returns the ids it
+added, and a document that already has them keeps its styles part byte for byte.
+
 Docx4j's names are there as aliases (`addParagraphOfText`, `addStyledParagraphOfText`,
 `addObject`, `getContent`), and the tree stays reachable: `paragraph.p` is the `P`,
 `body.content` the live array.
@@ -173,6 +192,12 @@ list.setLevelStartingNumber(0, 5);
 const again = p4.restartList();                 // the same list, numbering again from its start
 ```
 
+Without a paragraph, `pkg.numbering.newList()` makes a definition and returns its `w:numId`, and
+`pkg.numbering.restart(numId)` one that numbers again from the start. Both take the identifiers to
+use when the next free one is the wrong answer - two sessions allocating in one co-edited
+document - checked unused, a clash throwing rather than renumbering:
+`await pkg.numbering.newList({ numId: 4242, abstractNumId: 77 })`.
+
 A level writer changes the `w:abstractNum`, so it copies that definition first when another
 `w:num` shares it — the change stays local to this list. `startNewList()` is asynchronous here
 (Office JS's is not): it copies its definition from docx4j's default `numbering.xml` and adds
@@ -208,6 +233,21 @@ body.acceptAll();     // or rejectAll(), or accept()/reject() one at a time
 `getTrackedChanges()` is also on `Paragraph` and `Range`. Text and searches read the accepted
 view throughout, so an agent sees the document as it will read once the changes are taken.
 
+To record one caller's edits without touching the document's own setting - an agent working in a
+document whose `w:trackRevisions` belongs to its owner - use `withTracking`. Nothing is written
+to the settings part, and the author, date and mode are put back when `fn` returns or throws:
+
+```ts
+await pkg.withTracking({ author: { name: 'Agent' } }, () => {
+  body.replaceText('colour', 'color');
+});
+```
+
+Calls nest. While two overlap, the later one's author and mode apply to every edit, since nothing
+can tell which asynchronous call an edit came from: await one before starting another when they
+must be recorded as different authors. A revision is dated to the minute, as Word dates them, and
+its id is above every annotation id in the document, including those in parts nobody has read.
+
 ### Comments
 
 `getComments()` on the body, a paragraph or a range, and `insertComment` on a range or a
@@ -230,6 +270,15 @@ for (const c of await body.getComments()) {    // document order, replies nested
 }
 ```
 
+`insertComment` and `reply` take the author, initials, date and `w:id` when they are not the
+package's - a comment made by another person in a co-edited document - and paragraphs as well as
+a string. A chosen id is checked unused, and a clash throws:
+
+```ts
+await hit.insertComment('Checked', { author: { name: 'Grace Hopper' }, date: new Date('2026-09-27T10:15:00Z'), id: 42 });
+await hit.insertComment([p1, p2]);             // w:p elements, for rich content
+```
+
 ### XML in
 
 A whole `word/document.xml` becomes the main document part's contents with `setXml`, and a
@@ -253,6 +302,33 @@ import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
 body.addObject(el.p({ content: [el.r({ content: [el.t({ value: 'Hello World' })] })] }));
 ```
 
+A part that cannot be unmarshalled throws `PartUnmarshalException`, whose message names the part
+and, where the parser supplies a position (xmldom in Node; not a browser), the element or attribute
+and its line: `/word/styles.xml: w:sz/@w:val (line 7): Argument [NaN] must be an integer, but it is not a number.`
+`partName`, `location`, `line` and `column` are fields of their own.
+
+### XPath over the document
+
+`pkg.selectObjects(xpath)` evaluates an XPath over a part - the main document part unless you pass
+another - and answers as docx4j's `getJAXBNodesViaXPath` does: for each hit, the node, the tree
+object behind it and its path. `body.select(xpath)` gives the content-API view instead, where the
+element has one (`Paragraph`, `Table`, `TableRow`, `TableCell`, `ContentControl`, a `Range` for a
+run):
+
+```ts
+const hits = await pkg.selectObjects("//w:p[w:pPr/w:pStyle/@w:val='Heading1']");
+hits[0].object;         // the P itself, not a copy: change it and the document changes
+hits[0].path;           // '/w:document/w:body[1]/w:p[3]'
+
+for (const heading of await body.select("//w:p[w:pPr/w:pStyle/@w:val='Heading1']")) {
+  if (heading instanceof Paragraph) heading.styleBuiltIn = 'Heading2';
+}
+```
+
+The prefixes are the objects package's (`w`, `r`, `wp`, `a`, ...), and `namespaces` adds others.
+Each call evaluates a fresh snapshot of the part, so what it selects is never stale and changing the
+snapshot's DOM changes nothing. The answers are held to docx4j's own by the XPath goldens (CR-006).
+
 ### Tables, pictures and content controls
 
 `Table`, `TableRow` and `TableCell` are Office JS shapes too; a cell is a `Body` of its own, so
@@ -350,6 +426,7 @@ document part (Word drops a custom XML part the main part does not relate to):
 
 ```ts
 const part = pkg.customXmlParts.add('<greeting xmlns="http://example.com/g"><to>World</to></greeting>');
+// or with the itemID and part name to use, checked unused: { itemID: '{4B0E8F1A-...}', partName: '/customXml/item7.xml' }
 control.xmlMapping.setMapping('/ns0:greeting[1]/ns0:to[1]', "xmlns:ns0='http://example.com/g'", part);
 control.xmlMapping.setMappingByNode(part.selectSingleNode('/ns0:greeting/ns0:to', "xmlns:ns0='http://example.com/g'"));
 ```
@@ -475,6 +552,10 @@ await Word.run(pkg, async (context) => {
 await writeFile('edited.docx', await pkg.save());
 ```
 
+The callback's `context.document` is typed `ShimmedDocument`, so add-in code that uses
+`paragraphs.items`, `load('items/text')`, `getFirst()` or `getCount().value` type-checks here as it
+does against Office JS.
+
 `Word.supported` is the set of `Class.member` strings this package implements
 (`Word.supported.has('Body.insertParagraph')`), generated from the compile-time subset, so a
 tool can check a script before running it. The selection an add-in edits is passed in:

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

@@ -5,10 +5,16 @@ import type { OpcPackage } from '../../packages/OpcPackage.mjs';
 import { type Element, type TextViewOptions } from './tree.mjs';
 import { Paragraph } from './Paragraph.mjs';
 import { Range } from './Range.mjs';
-import { Table } from './Table.mjs';
+import { Table, type TableRow, type TableCell } from './Table.mjs';
 import { ContentControl, type ContentControlType } from './ContentControl.mjs';
 import { InlinePicture, type InlinePictureOptions } from './InlinePicture.mjs';
-import type { SearchOptions } from './search.mjs';
+import { type SearchOptions } from './search.mjs';
+import type { Bound } from './binder.mjs';
+/**
+ * What `Body.select` returns for one hit: the content-API view of the selected element where there
+ * is one, and the `Bound` itself otherwise (CR-006 section 2).
+ */
+export type SelectResult = Paragraph | Table | TableRow | TableCell | ContentControl | Range | Bound;
 import type { Comment } from './Comment.mjs';
 import { type ChangeTracker } from './tracking.mjs';
 import { type TrackedChange } from './TrackedChange.mjs';
@@ -75,6 +81,34 @@ export declare class Body {
     get content(): Element[];
     /** Every paragraph in document order, descending into tables and content controls. */
     get paragraphs(): Paragraph[];
+    /**
+     * The content-API views an XPath selects (CR-006): a `ContentControl`, `Table`, `TableRow`,
+     * `TableCell` or `Paragraph` where the selected element has one, at any depth - an inline content
+     * control is a `ContentControl`, a nested table a `Table`; a `Range` over the whole paragraph for a
+     * `w:r` or anything in one (`w:t`, `w:tab`), wherever the run sits (a hyperlink, an insertion, an
+     * inline control); and the `Bound` itself for anything else - an attribute, a text node, a `w:pPr`,
+     * a `w:hyperlink`, a wildcard child. An attribute or a text node is always the `Bound`, never its
+     * element's view, so that what matched is not lost. A caller that wants the tree objects rather
+     * than views uses `pkg.selectObjects`.
+     *
+     * The expression is evaluated over a snapshot of the part this body belongs to, so it sees the
+     * whole part - `//w:p` from a header's body selects that header's paragraphs. Every call marshals
+     * the part afresh (CR-006 section 2).
+     */
+    select(xpath: string, options?: {
+        namespaces?: Record<string, string>;
+    }): Promise<SelectResult[]>;
+    /**
+     * Every view this body can make, keyed by the tree object behind it, so that a selected object
+     * becomes the view a caller can act on. Built per select: the views are cheap wrappers and nothing
+     * is cached but the `Body` itself (CR-002's "views, not a model"). The first view put for an object
+     * is the one it keeps, so the most specific kinds go first: a content control before the
+     * paragraph that holds an inline one, a table at any depth before the paragraphs in its cells, and
+     * a paragraph before the runs in it. A `w:r` and what is in it map to a `Range` over the paragraph,
+     * which is the nearest thing the content API has - a run is not addressable on its own in Office
+     * JS. A run in a text box is not one of the paragraph's, and stays a `Bound`.
+     */
+    private viewsByObject;
     /** The tables directly in this body, as Office JS reports them (nested tables are a cell's). */
     get tables(): Table[];
     /** Every content control in this body, in document order, nested ones included. */

package/dist/model/content/Body.mjs

@@ -1,7 +1,7 @@
 import { Docx4JException, PropertyResolverNotCreatedException } from '../../opc/exceptions.mjs';
 import { typeNameOf, childrenOf, linkParents, BLOCK_LEVEL_TYPES, textOf, textOfView, rowsOf, cellsOf } from './tree.mjs';
 import { r as textRun, br as breakItem, tbl as tableOf } from '@docx4j/generated-objects-ts/builders/wml';
-import { runOf, paragraphOf } from './tree.mjs';
+import { runOf, paragraphOf, runsOf } from './tree.mjs';
 import { Paragraph } from './Paragraph.mjs';
 import { Table } from './Table.mjs';
 import { ContentControl, collectControls } from './ContentControl.mjs';
@@ -9,6 +9,7 @@ import { sdt as sdtOf, nextSdtId } from '@docx4j/generated-objects-ts/builders/w
 import { controlIdScope, sdtKindFor } from '../customxml/insert.mjs';
 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';
@@ -80,6 +81,78 @@ export class Body {
         visit(this.content);
         return out;
     }
+    /**
+     * The content-API views an XPath selects (CR-006): a `ContentControl`, `Table`, `TableRow`,
+     * `TableCell` or `Paragraph` where the selected element has one, at any depth - an inline content
+     * control is a `ContentControl`, a nested table a `Table`; a `Range` over the whole paragraph for a
+     * `w:r` or anything in one (`w:t`, `w:tab`), wherever the run sits (a hyperlink, an insertion, an
+     * inline control); and the `Bound` itself for anything else - an attribute, a text node, a `w:pPr`,
+     * a `w:hyperlink`, a wildcard child. An attribute or a text node is always the `Bound`, never its
+     * element's view, so that what matched is not lost. A caller that wants the tree objects rather
+     * than views uses `pkg.selectObjects`.
+     *
+     * The expression is evaluated over a snapshot of the part this body belongs to, so it sees the
+     * whole part - `//w:p` from a header's body selects that header's paragraphs. Every call marshals
+     * the part afresh (CR-006 section 2).
+     */
+    async select(xpath, options = {}) {
+        const pkg = this.package_;
+        if ((pkg === null || pkg === void 0 ? void 0 : pkg.selectObjects) === undefined)
+            throw new Docx4JException('select needs the package that owns this body');
+        const bounds = await pkg.selectObjects(xpath, { part: this.part, namespaces: options.namespaces });
+        const views = this.viewsByObject();
+        return bounds.map((bound) => { var _a; return (_a = (bound.node.nodeType === 1 ? views.get(bound.object) : undefined)) !== null && _a !== void 0 ? _a : bound; });
+    }
+    /**
+     * Every view this body can make, keyed by the tree object behind it, so that a selected object
+     * becomes the view a caller can act on. Built per select: the views are cheap wrappers and nothing
+     * is cached but the `Body` itself (CR-002's "views, not a model"). The first view put for an object
+     * is the one it keeps, so the most specific kinds go first: a content control before the
+     * paragraph that holds an inline one, a table at any depth before the paragraphs in its cells, and
+     * a paragraph before the runs in it. A `w:r` and what is in it map to a `Range` over the paragraph,
+     * which is the nearest thing the content API has - a run is not addressable on its own in Office
+     * JS. A run in a text box is not one of the paragraph's, and stays a `Bound`.
+     */
+    viewsByObject() {
+        var _a;
+        const out = new Map();
+        const put = (value, view) => {
+            if (typeof value === 'object' && value !== null && !out.has(value))
+                out.set(value, view);
+        };
+        const controls = this.contentControls;
+        for (const control of controls)
+            put(control.element.value, control);
+        const putTables = (tables) => {
+            for (const table of tables) {
+                put(table.element.value, table);
+                for (const row of table.rows) {
+                    put(row.element.value, row);
+                    for (const cell of row.cells) {
+                        put(cell.element.value, cell);
+                        putTables(cell.tables);
+                    }
+                }
+            }
+        };
+        putTables(this.tables);
+        for (const control of controls)
+            if (control.form === 'Block')
+                putTables(control.tables);
+        for (const paragraph of this.paragraphs) {
+            put(paragraph.element.value, paragraph);
+            const range = paragraph.getRange();
+            // both views, so that a run in a w:del is found as well as one in a w:ins
+            for (const view of ['accepted', 'original']) {
+                for (const run of runsOf(paragraph.element.value, { view })) {
+                    put(run.value, range);
+                    for (const item of (_a = run.value.content) !== null && _a !== void 0 ? _a : [])
+                        put(item.value, range);
+                }
+            }
+        }
+        return out;
+    }
     /** The tables directly in this body, as Office JS reports them (nested tables are a cell's). */
     get tables() {
         return this.content.filter((el) => typeNameOf(el) === 'org_docx4j_wml.Tbl').map((element) => new Table(element, this.content, this));
@@ -282,9 +355,11 @@ export class Body {
      * the package's `changeTrackingMode` is on.
      */
     replaceText(find, replace, options) {
-        const matches = this.search(find, options);
-        for (let i = matches.length - 1; i >= 0; i--)
-            matches[i].insertText(replace, 'Replace');
+        const matches = this.paragraphs.flatMap((p) => p.searchMatches(find, options));
+        for (let i = matches.length - 1; i >= 0; i--) {
+            const { range, match } = matches[i];
+            range.insertText(expandReplacement(replace, match, options), 'Replace');
+        }
         return matches.length;
     }
     /**

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 CommentParts } from './comments.mjs';
+import { type CommentContent, type CommentOptions, 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
@@ -51,8 +51,11 @@ export declare class Comment {
     get replies(): Comment[];
     /** The comment this one replies to (extension). */
     get parent(): Comment | undefined;
-    /** A reply in the same thread, anchored to the same range, as Word writes them. */
-    reply(text: string): Promise<Comment>;
+    /**
+     * A reply in the same thread, anchored to the same range, as Word writes them. `options` are
+     * `insertComment`'s (CR-002 section 28.3).
+     */
+    reply(content: CommentContent, options?: CommentOptions): Promise<Comment>;
     /** Removes the comment and its replies: the markers, the reference runs and every side-part entry. */
     delete(): Promise<void>;
     /**
@@ -68,8 +71,15 @@ export declare class Comment {
     /** Used by `commentsOf` while threading. */
     addReply(reply: Comment): void;
 }
-/** `Range.insertComment` (CR-002 section 3.8): the markers, the comment and the side-part entries. */
-export declare function insertComment(range: Range, text: string): Promise<Comment>;
+/**
+ * `Range.insertComment` (CR-002 section 3.8): the markers, the comment and the side-part entries.
+ *
+ * `options` (CR-002 section 28.3) name the author, the initials, the date and the `w:id`: in a
+ * co-editing room the author is the peer who made the comment and the date is when they made it,
+ * neither of which is a property of whoever is saving. A given `id` is checked unused and a clash
+ * throws.
+ */
+export declare function insertComment(range: Range, content: CommentContent, options?: CommentOptions): 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).

package/dist/model/content/Comment.mjs

@@ -105,12 +105,16 @@ export class Comment {
     get parent() {
         return this.parentComment;
     }
-    /** A reply in the same thread, anchored to the same range, as Word writes them. */
-    async reply(text) {
+    /**
+     * A reply in the same thread, anchored to the same range, as Word writes them. `options` are
+     * `insertComment`'s (CR-002 section 28.3).
+     */
+    async reply(content, options) {
+        const paragraphs = paragraphsOfContent(content);
         const parts = await this.parts.ensureAll();
-        const id = nextCommentId(parts.comments, this.body.container);
+        const id = commentId(parts, this.body, options);
         placeAfter(this.body, this.id, id);
-        const reply = addComment(parts, this.body, id, text, this);
+        const reply = addComment(parts, this.body, id, paragraphs, this, options);
         this.replyList.push(reply);
         reply.parentComment = this;
         return reply;
@@ -291,6 +295,10 @@ function placeAfter(body, parentId, id) {
     const start = markers.find((m) => m.kind === 'start');
     const end = [...markers].reverse().find((m) => m.kind === 'end');
     const reference = [...markers].reverse().find((m) => m.kind === 'reference');
+    if (!((reference === null || reference === void 0 ? void 0 : reference.run) && reference.runOwner) && !end) {
+        // refused before anything is written, so that no marker is left naming a comment never made
+        throw new Docx4JException(`Comment ${parentId} has no markers in this body; cannot anchor a reply`);
+    }
     if (start)
         insertAt(start.owner, start.owner.indexOf(start.item) + 1, [el.commentRangeStart(wmlFactory.createCommentRangeStart({ id }))], parentOf(start.item));
     if (end)
@@ -301,37 +309,37 @@ function placeAfter(body, parentId, id) {
     else if (end) {
         insertAt(end.owner, end.owner.indexOf(end.item) + 1, [referenceRun(id)], parentOf(end.item));
     }
-    else {
-        throw new Docx4JException(`Comment ${parentId} has no markers in this body; cannot anchor a reply`);
-    }
 }
-/** The `w:comment` and the side-part entries of a new comment; the markers are already written. */
-function addComment(parts, body, id, text, parent) {
-    var _a, _b, _c, _d;
-    var _e, _f;
-    const author = parts.author;
-    const paragraphs = text.split('\n').map((line, i) => commentParagraph(line, i === 0));
+/**
+ * The `w:comment` and the side-part entries of a new comment; the markers are already written. The
+ * 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;
+    const author = (_a = options === null || options === void 0 ? void 0 : options.author) !== null && _a !== void 0 ? _a : parts.author;
     const paraId = randomHexId((candidate) => paraIdTaken(parts, body.container, candidate));
     paragraphs[0].value.paraId = paraId;
     const comment = wmlFactory.createCommentsComment({
-        id, author: author.name, initials: initialsOf(author), date: dateToCalendar(new Date()),
+        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()),
         content: paragraphs,
     });
-    const comments = ((_a = (_e = parts.comments).comment) !== null && _a !== void 0 ? _a : (_e.comment = []));
+    const comments = ((_d = (_h = parts.comments).comment) !== null && _d !== void 0 ? _d : (_h.comment = []));
     comments.push(comment);
     linkParents(comment, parts.comments);
     const extended = parts.ensureCommentsEx();
     const entry = w15Factory.createCTCommentEx({ paraId, done: '0' });
     if (parent)
         entry.paraIdParent = parent.ensureParaId();
-    ((_b = extended.commentEx) !== null && _b !== void 0 ? _b : (extended.commentEx = [])).push(entry);
+    ((_e = extended.commentEx) !== null && _e !== void 0 ? _e : (extended.commentEx = [])).push(entry);
     linkParents(entry, extended);
     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 });
-        ((_c = (_f = parts.commentsIds).commentId) !== null && _c !== void 0 ? _c : (_f.commentId = [])).push(commentId);
+        ((_f = (_j = parts.commentsIds).commentId) !== null && _f !== void 0 ? _f : (_j.commentId = [])).push(commentId);
         linkParents(commentId, parts.commentsIds);
-        (_d = parts.extensible) === null || _d === void 0 ? void 0 : _d.set(durableId, new Date());
+        (_g = parts.extensible) === null || _g === void 0 ? void 0 : _g.set(durableId, new Date());
     }
     addPerson(parts, author.name, author.email);
     return new Comment(comment, parts, body);
@@ -354,13 +362,53 @@ function addPerson(parts, name, email) {
     list.push(person);
     linkParents(person, people);
 }
-/** `Range.insertComment` (CR-002 section 3.8): the markers, the comment and the side-part entries. */
-export async function insertComment(range, text) {
+/**
+ * `Range.insertComment` (CR-002 section 3.8): the markers, the comment and the side-part entries.
+ *
+ * `options` (CR-002 section 28.3) name the author, the initials, the date and the `w:id`: in a
+ * co-editing room the author is the peer who made the comment and the date is when they made it,
+ * neither of which is a property of whoever is saving. A given `id` is checked unused and a clash
+ * throws.
+ */
+export async function insertComment(range, content, options) {
+    // Everything that can refuse the call runs before anything is written: the content, then the id
+    // once the parts can say which are taken. A refusal after the markers were placed left them naming
+    // a comment that does not exist (CR-002 section 31).
+    const paragraphs = paragraphsOfContent(content);
     const body = range.paragraph.parentBody;
     const parts = await commentPartsAccess().create(body);
-    const id = nextCommentId(parts.comments, body.container);
+    const id = commentId(parts, body, options);
     placeAround(range, id);
-    return addComment(parts, body, id, text, undefined);
+    return addComment(parts, body, id, paragraphs, undefined, options);
+}
+/**
+ * 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
+ * chosen list `numId` does: the caller is asserting something about a room's state (section 28.3).
+ */
+function commentId(parts, body, options) {
+    var _a;
+    if ((options === null || options === void 0 ? void 0 : options.id) === undefined)
+        return nextCommentId(parts.comments, body.container);
+    const id = options.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`);
+    }
+    if (markersOf(body.container).some((m) => m.id === id)) {
+        throw new Docx4JException(`The comment id ${id} is already named by a marker in this story`);
+    }
+    return id;
+}
+/** The paragraphs of a comment's content: a string splits on newlines, elements are taken as they are. */
+function paragraphsOfContent(content) {
+    if (typeof content === 'string')
+        return content.split('\n').map((line, i) => commentParagraph(line, i === 0));
+    const paragraphs = [...content];
+    if (paragraphs.length === 0)
+        throw new Docx4JException('A comment needs at least one paragraph');
+    return paragraphs;
 }
 /**
  * `getComments()` on a body, a paragraph or a range: the comments anchored there in document

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

@@ -307,7 +307,7 @@ export declare class NumberingFacade {
      */
     newList(options?: {
         bullet?: boolean;
-    }): Promise<string>;
+    } & ChosenListIds): Promise<string>;
     /**
      * A `w:num` that numbers as `numId` does but starts again, and its own `w:numId`:
      * `List.restart()` without needing a `Body`. The counters are shared by abstract definition,
@@ -317,5 +317,16 @@ export declare class NumberingFacade {
      * Synchronous, so the numbering part must have been read: `await pkg.getPropertyResolver()`,
      * `newList()` or any list read does it.
      */
-    restart(numId: string | number): string;
+    restart(numId: string | number, options?: {
+        newNumId?: string | number;
+    }): string;
+}
+/**
+ * The identifiers a caller may choose for a new list definition, when the next integer is the wrong
+ * answer: in a co-editing room two sessions allocate at once, so the editor picks random ids and
+ * needs them honoured rather than renumbered (CR-002 section 24).
+ */
+export interface ChosenListIds {
+    numId?: string | number | undefined;
+    abstractNumId?: string | number | undefined;
 }

package/dist/model/content/List.mjs

@@ -669,23 +669,29 @@ export async function startNewList(paragraph, options) {
  * `w:numId`. The paragraph half of `startNewList` is separate because it is separable: nothing
  * about building a list definition needs one.
  */
-async function addListDefinition(part, bullet) {
+async function addListDefinition(part, bullet, ids) {
     var _a, _b, _c;
     const numbering = await part.getContents();
     const defaults = await defaultNumbering();
     const template = ((_a = defaults.abstractNum) !== null && _a !== void 0 ? _a : [])[bullet ? 0 : 1];
     if (template === undefined)
         throw new Docx4JException('The default numbering definitions are missing an abstractNum');
+    // both identifiers are settled before anything is written, so a clash leaves the part as it was
+    // (CR-002 section 31: an orphan w:abstractNum was saved for every refused numId)
+    const abstractNumId = (ids === null || ids === void 0 ? void 0 : ids.abstractNumId) === undefined
+        ? nextAbstractNumId(numbering)
+        : requireFreeId(numbering, 'abstractNumId', ids.abstractNumId);
+    const numId = (ids === null || ids === void 0 ? void 0 : ids.numId) === undefined ? nextNumId(numbering) : requireFreeId(numbering, 'numId', ids.numId);
     const abstract = deepCopy(template);
-    abstract.abstractNumId = nextAbstractNumId(numbering);
+    abstract.abstractNumId = abstractNumId;
     abstract.nsid = f.createCTLongHexNumber({ val: hexId() });
     delete abstract.styleLink;
     delete abstract.numStyleLink;
     ((_b = numbering.abstractNum) !== null && _b !== void 0 ? _b : (numbering.abstractNum = [])).push(abstract);
     linkParents(abstract, numbering);
     const num = f.createNumberingNum({
-        numId: nextNumId(numbering),
-        abstractNumId: f.createNumberingNumAbstractNumId({ val: abstract.abstractNumId }),
+        numId,
+        abstractNumId: f.createNumberingNumAbstractNumId({ val: abstractNumId }),
     });
     ((_c = numbering.num) !== null && _c !== void 0 ? _c : (numbering.num = [])).push(num);
     linkParents(num, numbering);
@@ -697,10 +703,10 @@ async function addListDefinition(part, bullet) {
  * list (CR-001 section 15.2), and it is what {@link List.restart} and
  * {@link NumberingFacade.restart} both do.
  */
-function addRestartedNum(numbering, abstractNumId, start) {
+function addRestartedNum(numbering, abstractNumId, start, newNumId) {
     var _a;
     const created = f.createNumberingNum({
-        numId: nextNumId(numbering),
+        numId: newNumId === undefined ? nextNumId(numbering) : requireFreeId(numbering, 'numId', newNumId),
         abstractNumId: f.createNumberingNumAbstractNumId({ val: abstractNumId }),
         lvlOverride: [f.createNumberingNumLvlOverride({
                 ilvl: 0,
@@ -776,9 +782,14 @@ export class NumberingFacade {
      * caller writes `w:numPr` itself.
      */
     async newList(options) {
+        // the form is checked before a numbering part can be created for a call that is then refused
+        if ((options === null || options === void 0 ? void 0 : options.numId) !== undefined)
+            requireIdForm('numId', options.numId);
+        if ((options === null || options === void 0 ? void 0 : options.abstractNumId) !== undefined)
+            requireIdForm('abstractNumId', options.abstractNumId);
         const main = this.pkg.getMainDocumentPart();
         const part = await ensureNumberingPartOf(this.pkg, main);
-        const numId = await addListDefinition(part, (options === null || options === void 0 ? void 0 : options.bullet) === true);
+        const numId = await addListDefinition(part, (options === null || options === void 0 ? void 0 : options.bullet) === true, options);
         this.pkg.refreshPropertyResolver();
         return String(numId);
     }
@@ -791,7 +802,7 @@ export class NumberingFacade {
      * Synchronous, so the numbering part must have been read: `await pkg.getPropertyResolver()`,
      * `newList()` or any list read does it.
      */
-    restart(numId) {
+    restart(numId, options) {
         var _a, _b;
         const part = this.pkg.getMainDocumentPart().numberingDefinitionsPart;
         if (part === undefined)
@@ -799,7 +810,7 @@ export class NumberingFacade {
         const definition = part.definitions.list(numId);
         if (definition === undefined)
             throw new ItemNotFound(`No w:num for numId ${numId}`);
-        const created = addRestartedNum(part.makeLive(), definition.num.abstractNumId.val, (_b = (_a = definition.level('0')) === null || _a === void 0 ? void 0 : _a.start) !== null && _b !== void 0 ? _b : 1);
+        const created = addRestartedNum(part.makeLive(), definition.num.abstractNumId.val, (_b = (_a = definition.level('0')) === null || _a === void 0 ? void 0 : _a.start) !== null && _b !== void 0 ? _b : 1, options === null || options === void 0 ? void 0 : options.newNumId);
         this.pkg.refreshPropertyResolver();
         return String(created);
     }
@@ -840,6 +851,34 @@ function nextNumId(numbering) {
     var _a;
     return ((_a = numbering.num) !== null && _a !== void 0 ? _a : []).reduce((max, num) => Math.max(max, Number(num.numId)), 0) + 1;
 }
+/**
+ * A chosen identifier in range: a `w:numId` from 1, since 0 is what a `w:numPr` says to mean "not
+ * numbered" (`detachFromList` writes it, and Word and the Emulator read it so), and a
+ * `w:abstractNumId` from 0 (CR-002 section 31).
+ */
+function requireIdForm(kind, chosen) {
+    const id = Number(chosen);
+    const least = kind === 'numId' ? 1 : 0;
+    if (!Number.isInteger(id) || id < least) {
+        throw new Docx4JException(`A ${kind} must be an integer from ${least}, not ${String(chosen)}`);
+    }
+    return id;
+}
+/**
+ * A chosen identifier, checked unused, as `addExternalRelationship`'s proposed id is. A clash throws
+ * rather than renumbering: a caller who names an id is asserting something about a room's state, and
+ * quietly moving it would break the peer that named it (CR-002 section 24).
+ */
+function requireFreeId(numbering, kind, chosen) {
+    var _a, _b;
+    const id = requireIdForm(kind, chosen);
+    const taken = kind === 'numId'
+        ? ((_a = numbering.num) !== null && _a !== void 0 ? _a : []).some((num) => Number(num.numId) === id)
+        : ((_b = numbering.abstractNum) !== null && _b !== void 0 ? _b : []).some((a) => Number(a.abstractNumId) === id);
+    if (taken)
+        throw new Docx4JException(`The ${kind} ${id} is already in use in this document's numbering part`);
+    return id;
+}
 /** A free `w:abstractNumId`. */
 function nextAbstractNumId(numbering) {
     var _a;

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

@@ -7,6 +7,7 @@ import type { Body, BlockElement } from './Body.mjs';
 import { type TableCell } from './Table.mjs';
 import { ContentControl, type ContentControlType } from './ContentControl.mjs';
 import { InlinePicture, type InlinePictureOptions } from './InlinePicture.mjs';
+import { type CommentContent, type CommentOptions } from './comments.mjs';
 import type { Comment } from './Comment.mjs';
 import { type ChangeTracker } from './tracking.mjs';
 import { TrackedChange } from './TrackedChange.mjs';
@@ -160,6 +161,15 @@ export declare class Paragraph {
     insertOoxml(ooxml: string, location: 'Before' | 'After' | 'Start' | 'End' | 'Replace'): Promise<(Paragraph | BlockElement)[]>;
     /** Matches within this paragraph. */
     search(text: string, options?: SearchOptions): Range[];
+    /**
+     * `search`, keeping each match's capture groups, which is what a replacement's `$1` or Word's `\1`
+     * expands from (CR-002 section 26). Not an Office JS member; `replaceText` is its only caller here
+     * and `Body.replaceText` the other.
+     */
+    searchMatches(text: string, options?: SearchOptions): {
+        range: Range;
+        match: RegExpExecArray;
+    }[];
     /**
      * Replaces every match of `find` with `replace`, last match first so that the offsets of the
      * ones still to do stay valid (CR-002 section 3.7). Returns the number replaced; tracked when
@@ -261,7 +271,7 @@ export declare class Paragraph {
     /** The comments anchored in this paragraph, replies nested under their parent. */
     getComments(): Promise<Comment[]>;
     /** Comments the whole paragraph (sugar over `getRange().insertComment`). */
-    insertComment(text: string): Promise<Comment>;
+    insertComment(content: CommentContent, options?: CommentOptions): Promise<Comment>;
     /**
      * Wraps this paragraph in a new block-level content control (Office JS
      * `Paragraph.insertContentControl`), typed for the kind when one is given. The `w:id` is free in