@docx4j/core-ts 0.1.5 → 0.2.1

package/dist/model/content/Paragraph.mjs

@@ -10,7 +10,7 @@ function withRPr(run, rPr) {
 import { Font } from './Font.mjs';
 import { runFontSelectorOf } from '../fonts/lookup.mjs';
 import { Range } from './Range.mjs';
-import { searchPattern, findAll } from './search.mjs';
+import { searchPattern, matchesOf, expandReplacement } from './search.mjs';
 import { builtInOf, idOfBuiltIn, styleNameOf, styleIdOf } from './styles.mjs';
 import { cellOf } from './Table.mjs';
 import { ContentControl, collectRunControls } from './ContentControl.mjs';
@@ -336,7 +336,16 @@ export class Paragraph {
     }
     /** Matches within this paragraph. */
     search(text, options) {
-        return findAll(this.text, searchPattern(text, options)).map(([s, e]) => new Range(this, s, e));
+        return this.searchMatches(text, options).map((m) => m.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, options) {
+        return matchesOf(this.text, searchPattern(text, options))
+            .map((match) => ({ range: new Range(this, match.index, match.index + match[0].length), match }));
     }
     /**
      * Replaces every match of `find` with `replace`, last match first so that the offsets of the
@@ -344,9 +353,11 @@ export class Paragraph {
      * 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.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;
     }
     /** The tracked changes in this paragraph, in document order (CR-002 phase F). */
@@ -516,11 +527,8 @@ export class Paragraph {
                     const value = seg.text.substring(0, from) + middle + seg.text.substring(to);
                     if (value === '')
                         toRemove.push(seg);
-                    else {
-                        t.value = value;
-                        if (/^\s|\s$|\s\s/.test(value))
-                            t.space = 'preserve';
-                    }
+                    else
+                        setText(t, value);
                 }
                 else
                     toRemove.push(seg);
@@ -543,9 +551,7 @@ export class Paragraph {
             if (target) {
                 const t = target.item.value;
                 const at = start - target.start;
-                t.value = target.text.substring(0, at) + text + target.text.substring(at);
-                if (/^\s|\s$|\s\s/.test(t.value))
-                    t.space = 'preserve';
+                setText(t, target.text.substring(0, at) + text + target.text.substring(at));
             }
             else {
                 // no w:t to extend: a new run next to the segment at `start`, with that run's formatting
@@ -602,9 +608,7 @@ export class Paragraph {
         const t = seg.item.value;
         const head = seg.text.substring(0, at);
         const tail = seg.text.substring(at);
-        t.value = head;
-        if (/^\s|\s$|\s\s/.test(head))
-            t.space = 'preserve';
+        setText(t, head);
         const rest = seg.owner.splice(seg.index + 1);
         const second = runOf([textItem(tail), ...rest], seg.run.rPr ? deepCopy(seg.run.rPr) : undefined);
         seg.runOwner.splice(seg.runIndex + 1, 0, second);
@@ -672,8 +676,8 @@ export class Paragraph {
         return commentApi().commentsOf(this);
     }
     /** Comments the whole paragraph (sugar over `getRange().insertComment`). */
-    async insertComment(text) {
-        return commentApi().insertComment(this.getRange(), text);
+    async insertComment(content, options) {
+        return commentApi().insertComment(this.getRange(), content, options);
     }
     // --- content controls (CR-002 phase E) ---
     /**
@@ -796,9 +800,7 @@ export class Paragraph {
                 continue;
             if (seg.editable) {
                 const t = seg.item.value;
-                t.value = side === 'after' ? seg.text + text : text + seg.text;
-                if (/^\s|\s$|\s\s/.test(t.value))
-                    t.space = 'preserve';
+                setText(t, side === 'after' ? seg.text + text : text + seg.text);
             }
             else {
                 const run = runOf([textItem(text)], copyRPr(seg.run.rPr));
@@ -916,3 +918,17 @@ function outlineLevelOf(pPr) {
     const level = (_a = pPr === null || pPr === void 0 ? void 0 : pPr.outlineLvl) === null || _a === void 0 ? void 0 : _a.val;
     return level === undefined ? 10 : level + 1;
 }
+/**
+ * Sets a `w:t`'s text with `xml:space="preserve"` exactly when the text needs it - whitespace at
+ * either end, or two whitespace characters together - which is how the builders' `t()` and Word
+ * write it. Setting the attribute and never taking it off left a text shortened from "Font styles "
+ * to "Font X" still preserving, the same text but not the same bytes as a `w:t` made afresh
+ * (CR-002 section 32 item 2).
+ */
+function setText(t, value) {
+    t.value = value;
+    if (/^\s|\s$|\s\s/.test(value))
+        t.space = 'preserve';
+    else
+        delete t.space;
+}

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

@@ -5,6 +5,7 @@ import type { BlockElement } from './Body.mjs';
 import { type Element, type TextViewOptions } from './tree.mjs';
 import { ContentControl, type ContentControlType } from './ContentControl.mjs';
 import { type SearchOptions } from './search.mjs';
+import { type CommentContent, type CommentOptions } from './comments.mjs';
 import type { Comment } from './Comment.mjs';
 import type { TrackedChange } from './TrackedChange.mjs';
 /**
@@ -54,7 +55,11 @@ export declare class Range {
     /** Removes the span's text. */
     delete(): void;
     search(text: string, options?: SearchOptions): Range[];
-    /** Replaces every match in this span, last first so the offsets stay valid; returns the count (CR-002 section 3.7). */
+    /**
+     * Replaces every match in this span, last first so the offsets stay valid; returns the count
+     * (CR-002 section 3.7). The replacement's `$1` or Word's `\1` expands as it does on a paragraph
+     * (section 26; this one was missed there, section 31).
+     */
     replaceText(find: string, replace: string, options?: SearchOptions): number;
     /** The tracked changes this span covers, in document order (CR-002 phase F). */
     getTrackedChanges(): TrackedChange[];
@@ -68,7 +73,7 @@ export declare class Range {
      * boundaries, as `font` does), the comment itself and the side-part entries, creating any of
      * the comment parts the document lacks. Asynchronous because it unmarshals those parts.
      */
-    insertComment(text: string): Promise<Comment>;
+    insertComment(content: CommentContent, options?: CommentOptions): Promise<Comment>;
     /**
      * Wraps the runs this span covers in a run-level content control (Office JS
      * `Range.insertContentControl`), splitting the runs at the boundaries as `font` does. An empty
@@ -85,14 +90,40 @@ export declare class Range {
      * Setting removes the hyperlinks the range already carries and wraps its runs in one
      * `w:hyperlink`, splitting runs at the boundaries as `font` and `insertContentControl` do;
      * setting `""` removes them and wraps nothing. An external address becomes a relationship of
-     * this range's part, which is why the part must exist (CR-002 section 20).
+     * this range's part, which is why the part must exist (CR-002 section 20). Only the hyperlinks
+     * the range touches are removed; before 0.2.1 every one in the paragraph was (section 25).
+     *
+     * The runs are styled as Word styles them, measured through Office JS (`test/README.md` check
+     * 15, CR-002 section 25): each run a link wraps takes the `Hyperlink` character style, over any
+     * character style it had, and loses its direct colour, keeping the rest of its direct formatting;
+     * a link removed takes the style off its runs again. The `Hyperlink` definition is added to the
+     * styles part when the document lacks it, at the latest when the package is saved - a setter
+     * cannot await it - so `await pkg.styles.ensure('Hyperlink')` first where an effective read
+     * before the save must see it. Under change tracking the restyle is a formatting revision, as a
+     * `font` write is.
      */
     get hyperlink(): string;
     set hyperlink(value: string);
-    /** The `w:hyperlink` this range's first run sits in, if any. */
+    /** The first `w:hyperlink` this range touches, if any. */
     private hyperlinkHolder;
-    /** Unwraps every `w:hyperlink` the range touches, keeping its runs where they are. */
+    /**
+     * Unwraps every `w:hyperlink` the range touches, keeping its runs where they are and taking the
+     * `Hyperlink` style off them. Until 0.2.1 this unwrapped every hyperlink of the paragraph, so
+     * linking one word unlinked the others (CR-002 section 25).
+     */
     private removeHyperlinks;
+    /**
+     * Whether this range touches a hyperlink's text: overlaps it, or for an empty range lies in it
+     * (from its first character up to, not including, its end). A hyperlink holding no text touches
+     * nothing.
+     */
+    private touches;
+    /**
+     * The `Hyperlink` character style on every run of a hyperlink, in place of any character style
+     * and with the direct colour removed, or off again when the link goes: what Word does (CR-002
+     * section 25). A run whose properties are then empty loses its `w:rPr`, as in Word's output.
+     */
+    private restyle;
     /** The target of a relationship of this range's part, for the getter. */
     private relationshipTarget;
     /** An external relationship of this range's part for the address, and its id. */

package/dist/model/content/Range.mjs

@@ -1,14 +1,14 @@
 import { Font } from './Font.mjs';
 import { runFontSelectorOf } from '../fonts/lookup.mjs';
-import { typeNameOf, linkParents, runItemsOf } from './tree.mjs';
+import { typeNameOf, linkParents, runItemsOf, runsOf } from './tree.mjs';
 import { Docx4JException } from '../../opc/exceptions.mjs';
 import { ContentControl } from './ContentControl.mjs';
-import { sdt as sdtOf, nextSdtId } from '@docx4j/generated-objects-ts/builders/wml';
+import { sdt as sdtOf, nextSdtId, applyRunOptions } from '@docx4j/generated-objects-ts/builders/wml';
 import { hyperlink as hyperlinkOf } from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
 import { Namespaces } from '../../parts/Namespaces.mjs';
 import { controlIdScope, sdtKindFor } from '../customxml/insert.mjs';
 import { contentOf } from './ooxml.mjs';
-import { searchPattern, findAll } from './search.mjs';
+import { searchPattern, findAll, matchesOf, expandReplacement } from './search.mjs';
 import { commentApi } from './comments.mjs';
 /**
  * A subset of Office JS `Word.Range`: a span of text within one paragraph, [start, end) in the
@@ -151,11 +151,19 @@ export class Range {
         const base = this.start;
         return findAll(this.text, searchPattern(text, options)).map(([s, e]) => new Range(this.paragraph, base + s, base + e));
     }
-    /** Replaces every match in this span, last first so the offsets stay valid; returns the count (CR-002 section 3.7). */
+    /**
+     * Replaces every match in this span, last first so the offsets stay valid; returns the count
+     * (CR-002 section 3.7). The replacement's `$1` or Word's `\1` expands as it does on a paragraph
+     * (section 26; this one was missed there, section 31).
+     */
     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 base = this.start;
+        const matches = matchesOf(this.text, searchPattern(find, options));
+        for (let i = matches.length - 1; i >= 0; i--) {
+            const match = matches[i];
+            new Range(this.paragraph, base + match.index, base + match.index + match[0].length)
+                .insertText(expandReplacement(replace, match, options), 'Replace');
+        }
         return matches.length;
     }
     /** The tracked changes this span covers, in document order (CR-002 phase F). */
@@ -188,8 +196,8 @@ export class Range {
      * boundaries, as `font` does), the comment itself and the side-part entries, creating any of
      * the comment parts the document lacks. Asynchronous because it unmarshals those parts.
      */
-    async insertComment(text) {
-        return commentApi().insertComment(this, text);
+    async insertComment(content, options) {
+        return commentApi().insertComment(this, content, options);
     }
     // --- content controls (CR-002 phase E) ---
     /**
@@ -239,7 +247,17 @@ export class Range {
      * Setting removes the hyperlinks the range already carries and wraps its runs in one
      * `w:hyperlink`, splitting runs at the boundaries as `font` and `insertContentControl` do;
      * setting `""` removes them and wraps nothing. An external address becomes a relationship of
-     * this range's part, which is why the part must exist (CR-002 section 20).
+     * this range's part, which is why the part must exist (CR-002 section 20). Only the hyperlinks
+     * the range touches are removed; before 0.2.1 every one in the paragraph was (section 25).
+     *
+     * The runs are styled as Word styles them, measured through Office JS (`test/README.md` check
+     * 15, CR-002 section 25): each run a link wraps takes the `Hyperlink` character style, over any
+     * character style it had, and loses its direct colour, keeping the rest of its direct formatting;
+     * a link removed takes the style off its runs again. The `Hyperlink` definition is added to the
+     * styles part when the document lacks it, at the latest when the package is saved - a setter
+     * cannot await it - so `await pkg.styles.ensure('Hyperlink')` first where an effective read
+     * before the save must see it. Under change tracking the restyle is a formatting revision, as a
+     * `font` write is.
      */
     get hyperlink() {
         var _a;
@@ -251,7 +269,7 @@ export class Range {
         return anchor === '' ? address : `${address}#${anchor}`;
     }
     set hyperlink(value) {
-        var _a;
+        var _a, _b, _c;
         const paragraph = this.paragraph;
         this.removeHyperlinks();
         if (value === '')
@@ -259,7 +277,12 @@ export class Range {
         const hash = value.indexOf('#');
         const address = hash === -1 ? value : value.slice(0, hash);
         const location = hash === -1 ? '' : value.slice(hash + 1);
-        const holder = hyperlinkOf({ content: [] });
+        // w:history="1" is what Word writes on every hyperlink it makes, and what docx4j writes when
+        // it builds one (MainDocumentPart.addHyperlink): "add the target to the viewed hyperlinks"
+        // (ECMA-376 17.16.22). Readers do not depend on it, but a document holding one holder from
+        // each source should not differ over it. Found by the docx4j-ts-editor session, ED-003
+        // section 11.8.
+        const holder = hyperlinkOf({ content: [], history: true });
         if (location !== '')
             holder.value.anchor = location;
         if (address !== '')
@@ -287,35 +310,73 @@ export class Range {
         holder.value.content = items;
         owner.splice(at, items.length, holder);
         linkParents(holder, (_a = segments[0].run.PARENT) !== null && _a !== void 0 ? _a : paragraph.p);
+        this.restyle(holder.value, true);
+        (_c = (_b = paragraph.parentBody.package_) === null || _b === void 0 ? void 0 : _b.requireStyles) === null || _c === void 0 ? void 0 : _c.call(_b, [HYPERLINK_STYLE]);
     }
-    /** The `w:hyperlink` this range's first run sits in, if any. */
+    /** The first `w:hyperlink` this range touches, if any. */
     hyperlinkHolder() {
-        for (const segment of this.paragraph.segments()) {
-            if (segment.end <= this.start && this.start !== this.end)
-                continue;
-            if (segment.start >= this.end && this.start !== this.end)
-                break;
-            const parent = segment.run.PARENT;
-            const found = hyperlinkHolders(this.paragraph).find((h) => h.value === parent);
-            if (found)
-                return found;
-        }
-        return undefined;
+        return hyperlinkHolders(this.paragraph).find((holder) => this.touches(holder));
     }
-    /** Unwraps every `w:hyperlink` the range touches, keeping its runs where they are. */
+    /**
+     * Unwraps every `w:hyperlink` the range touches, keeping its runs where they are and taking the
+     * `Hyperlink` style off them. Until 0.2.1 this unwrapped every hyperlink of the paragraph, so
+     * linking one word unlinked the others (CR-002 section 25).
+     */
     removeHyperlinks() {
         var _a, _b, _c;
-        for (const holder of hyperlinkHolders(this.paragraph)) {
+        for (const holder of hyperlinkHolders(this.paragraph).filter((h) => this.touches(h))) {
             const owner = containerOf(holder, this.paragraph);
             const at = owner.indexOf(holder);
             if (at === -1)
                 continue;
+            this.restyle(holder.value, false);
             owner.splice(at, 1, ...((_a = holder.value.content) !== null && _a !== void 0 ? _a : []));
             for (const item of ((_b = holder.value.content) !== null && _b !== void 0 ? _b : [])) {
                 linkParents(item, (_c = holder.PARENT) !== null && _c !== void 0 ? _c : this.paragraph.p);
             }
         }
     }
+    /**
+     * Whether this range touches a hyperlink's text: overlaps it, or for an empty range lies in it
+     * (from its first character up to, not including, its end). A hyperlink holding no text touches
+     * nothing.
+     */
+    touches(holder) {
+        let start;
+        let end = 0;
+        for (const segment of this.paragraph.segments()) {
+            if (!within(segment.run, holder.value, this.paragraph.p))
+                continue;
+            start !== null && start !== void 0 ? start : (start = segment.start);
+            end = segment.end;
+        }
+        if (start === undefined)
+            return false;
+        return this.start === this.end ? start <= this.start && this.start < end : start < this.end && end > this.start;
+    }
+    /**
+     * The `Hyperlink` character style on every run of a hyperlink, in place of any character style
+     * and with the direct colour removed, or off again when the link goes: what Word does (CR-002
+     * section 25). A run whose properties are then empty loses its `w:rPr`, as in Word's output.
+     */
+    restyle(holder, linked) {
+        var _a, _b, _c;
+        const tracking = this.paragraph.fontTracking();
+        const runs = new Set([...runsOf(holder), ...runsOf(holder, { view: 'original' })].map((r) => r.value));
+        for (const run of runs) {
+            if (!linked && ((_b = (_a = run.rPr) === null || _a === void 0 ? void 0 : _a.rStyle) === null || _b === void 0 ? void 0 : _b.val) !== HYPERLINK_STYLE)
+                continue;
+            (_c = run.rPr) !== null && _c !== void 0 ? _c : (run.rPr = { TYPE_NAME: 'org_docx4j_wml.RPr' });
+            // the properties as they are now become w:rPrChange, unless this run is our own insertion
+            if (tracking && !tracking.ownInsertions.has(run))
+                tracking.tracker.recordRPrChange(run.rPr);
+            applyRunOptions(run.rPr, linked ? { style: HYPERLINK_STYLE, color: '' } : { style: '' });
+            if (Object.keys(run.rPr).every((key) => key === 'TYPE_NAME'))
+                delete run.rPr;
+            else
+                linkParents(run.rPr, run);
+        }
+    }
     /** The target of a relationship of this range's part, for the getter. */
     relationshipTarget(id) {
         var _a, _b, _c;
@@ -330,6 +391,16 @@ export class Range {
         return part.getRelationshipsPart(true).addExternalRelationship(Namespaces.HYPERLINK, address).id;
     }
 }
+/** The character style Word gives the runs of a hyperlink it makes. */
+const HYPERLINK_STYLE = 'Hyperlink';
+/** Whether `object` is `ancestor` or below it, following `PARENT` no further than `stop`. */
+function within(object, ancestor, stop) {
+    for (let o = object; o !== undefined && o !== stop; o = o.PARENT) {
+        if (o === ancestor)
+            return true;
+    }
+    return false;
+}
 /** Every `w:hyperlink` of a paragraph, outermost first (they do not nest in practice). */
 function hyperlinkHolders(paragraph) {
     const out = [];

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

@@ -0,0 +1,44 @@
+import { type Jsonix } from '@docx4j/generated-objects-ts';
+/** What an XPath selected, and the tree object behind it (CR-006 section 2). */
+export interface Bound {
+    /**
+     * The DOM node the expression selected. It is in a snapshot marshalled for this call, so changing
+     * it changes nothing: edits go through the content API or `setContents`, never here.
+     */
+    node: Node;
+    /**
+     * The tree object: for an element, what a walk of the typed tree would hand you at that path,
+     * never a `{ name, value }` wrapper; for an attribute or a text node, the object of the element
+     * that owns it. Undefined for an element the model does not build - a wildcard child is its own
+     * object, so this is undefined only above the root or for a node the marshal did not report.
+     */
+    object: unknown;
+    /** Set when an attribute was selected: its qualified name on `object`'s element. */
+    attribute?: string;
+    /** The node's path from the part's root, `/w:document/w:body/w:p[3]/w:r[2]`. */
+    path: string;
+}
+/** A marshalled snapshot and the element-to-object map recorded while it was written. */
+export interface BoundSnapshot {
+    root: Element;
+    /** The object each element was marshalled from; a wildcard child maps to the original tree node. */
+    objects: WeakMap<Element, unknown>;
+}
+/**
+ * Marshals a root element and records what each DOM element came from. One marshal per call: the
+ * tree has no change log a cached snapshot could be checked against, and a stale answer is worse
+ * than a slow one (docx4j's `refreshXmlFirst`, always true here). The editor measured 349 to 411 ms
+ * for a 255-page main document part, against 975 ms for its first unmarshal, and runs a selection
+ * on Enter - so no cache is needed, which is what CR-006 section 2 was uncertain about.
+ */
+export declare function bindSnapshot<T>(element: Jsonix.TypedNamedValue<T>): Promise<BoundSnapshot>;
+/** Turns selected nodes into `Bound`s against a snapshot, with one path cache for them all. */
+export declare function boundsOf(nodes: readonly Node[], snapshot: BoundSnapshot): Bound[];
+/**
+ * The node's path from the document element, in the prefixed form the part itself uses, with a
+ * position on every step: `/w:document/w:body/w:p[3]/w:r[2]`, and `/@w:val` for an attribute. The
+ * position counts siblings of the same qualified name, as XPath does, and is written even when
+ * there is only one - a path that is stable whether or not a sibling is added later is worth more
+ * than a short one, and docx4j's harness records the same form.
+ */
+export declare function pathOf(node: Node): string;

package/dist/model/content/binder.mjs

@@ -0,0 +1,128 @@
+// CR-006: XPath over the WordprocessingML tree, through a read-only binder recorded while marshalling.
+//
+// docx4j answers `getJAXBNodesViaXPath` with a JAXB `Binder<Node>`, which keeps the link between a
+// DOM node and the object it came from in both directions. This runtime has no binder, so CR-002
+// section 3.6 left XPath over the typed tree out; the demand appeared (the editor's Developer
+// perspective selects by XPath) and this is the cheap half - DOM node to object, which is what a
+// selection needs. Nothing is written back through the DOM (CR-006 section 7).
+//
+// The link is recorded by `@docx4j/jsonix` 3.4.0's `onElement` callback, reached through the objects
+// facade's `marshalNode(value, { onElement })` (objects CR-007): the runtime calls it once per
+// class-typed value with the element it was written into, and once per wildcard DOM child with the
+// **imported copy** of that child - `writeNode` does `importNode`, so the element in the snapshot is
+// not the node in the tree and a map keyed on it would miss exactly the content a caller most wants
+// (jsonix-CR-006 section 2, finding 3).
+import { marshalNode } from '@docx4j/generated-objects-ts';
+/**
+ * Marshals a root element and records what each DOM element came from. One marshal per call: the
+ * tree has no change log a cached snapshot could be checked against, and a stale answer is worse
+ * than a slow one (docx4j's `refreshXmlFirst`, always true here). The editor measured 349 to 411 ms
+ * for a 255-page main document part, against 975 ms for its first unmarshal, and runs a selection
+ * on Enter - so no cache is needed, which is what CR-006 section 2 was uncertain about.
+ */
+export async function bindSnapshot(element) {
+    const objects = new WeakMap();
+    const root = await marshalNode(element, {
+        onElement: (node, value) => {
+            if (isElement(node))
+                objects.set(node, value);
+        },
+    });
+    return { root, objects };
+}
+/** Turns selected nodes into `Bound`s against a snapshot, with one path cache for them all. */
+export function boundsOf(nodes, snapshot) {
+    const paths = new Paths();
+    return nodes.map((node) => {
+        const owner = owningElement(node);
+        const bound = {
+            node,
+            object: owner === undefined ? undefined : snapshot.objects.get(owner),
+            path: paths.of(node),
+        };
+        if (node.nodeType === 2)
+            bound.attribute = node.name;
+        return bound;
+    });
+}
+/**
+ * The element an XPath result belongs to: itself for an element, its owner for an attribute, its
+ * parent for a text, comment or processing-instruction node. A document node has none.
+ */
+function owningElement(node) {
+    if (node.nodeType === 1)
+        return node;
+    if (node.nodeType === 2) {
+        const owner = node.ownerElement;
+        return owner === null ? undefined : owner;
+    }
+    const parent = node.parentNode;
+    return parent !== null && parent.nodeType === 1 ? parent : undefined;
+}
+/**
+ * The node's path from the document element, in the prefixed form the part itself uses, with a
+ * position on every step: `/w:document/w:body/w:p[3]/w:r[2]`, and `/@w:val` for an attribute. The
+ * position counts siblings of the same qualified name, as XPath does, and is written even when
+ * there is only one - a path that is stable whether or not a sibling is added later is worth more
+ * than a short one, and docx4j's harness records the same form.
+ */
+export function pathOf(node) {
+    return new Paths().of(node);
+}
+/**
+ * Paths for the nodes of one snapshot. Each parent's children are counted once, on first need,
+ * and each element's path is kept for its descendants, so a hit list costs one pass over the
+ * parents it touches. Counting a node's preceding siblings afresh for every node and every
+ * ancestor was quadratic in a parent's children: the 6,972 hits of `//w:p[w:pPr/w:pStyle]` over a
+ * 7,088-paragraph body took 21 s in Chromium, where the marshal took 0.5 s (CR-006 section 10).
+ */
+class Paths {
+    constructor() {
+        /** For a parent, the position of each element child among its siblings of the same name. */
+        this.positions = new Map();
+        this.elementPaths = new Map();
+    }
+    of(node) {
+        if (node.nodeType === 2) {
+            const owner = node.ownerElement;
+            return `${owner === null ? '' : this.of(owner)}/@${node.name}`;
+        }
+        if (node.nodeType === 3 || node.nodeType === 4) {
+            const parent = node.parentNode;
+            return `${parent === null ? '' : this.of(parent)}/text()`;
+        }
+        if (node.nodeType !== 1)
+            return '';
+        const known = this.elementPaths.get(node);
+        if (known !== undefined)
+            return known;
+        const element = node;
+        const parent = element.parentNode;
+        const path = parent === null || parent.nodeType !== 1
+            ? `/${element.nodeName}`
+            : `${this.of(parent)}/${element.nodeName}[${this.position(parent, element)}]`;
+        this.elementPaths.set(node, path);
+        return path;
+    }
+    position(parent, element) {
+        var _a, _b;
+        let positions = this.positions.get(parent);
+        if (positions === undefined) {
+            positions = new Map();
+            const counts = new Map();
+            for (let sibling = parent.firstChild; sibling; sibling = sibling.nextSibling) {
+                if (sibling.nodeType !== 1)
+                    continue;
+                const name = sibling.nodeName;
+                const n = ((_a = counts.get(name)) !== null && _a !== void 0 ? _a : 0) + 1;
+                counts.set(name, n);
+                positions.set(sibling, n);
+            }
+            this.positions.set(parent, positions);
+        }
+        return (_b = positions.get(element)) !== null && _b !== void 0 ? _b : 0;
+    }
+}
+function isElement(node) {
+    return typeof node === 'object' && node !== null && node.nodeType === 1;
+}

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

@@ -16,6 +16,24 @@ export declare const COMMENT_REFERENCE_STYLE = "CommentReference";
  * Who a comment (and, with phase F, a tracked change) is by. `WordprocessingMLPackage.author`;
  * there is no signed-in user here, so the package carries the identity.
  */
+/**
+ * What a comment is made of: the text, or the paragraphs of a comment that was edited rich
+ * (CR-002 section 28.3). A string splits on newlines, as it did before this option existed.
+ */
+export type CommentContent = string | Element<wml.P>[];
+/**
+ * Who made a comment and when, and its `w:id`, for a caller that knows better than the package does:
+ * in a co-editing room the author is the peer who made it and the date is when they made it
+ * (CR-002 section 28.3). Anything omitted falls back to what the package would have used.
+ */
+export interface CommentOptions {
+    author?: Author | undefined;
+    /** Overrides the initials derived from the author's name. */
+    initials?: string | undefined;
+    date?: Date | undefined;
+    /** Checked unused across the comments part and the story's markers; a clash throws. */
+    id?: number | undefined;
+}
 export interface Author {
     name: string;
     /** Word's `w:initials`; derived from the name when not given. */
@@ -69,7 +87,7 @@ export declare function commentPartsAccess(): CommentPartsAccess;
 /** How `Body`, `Paragraph` and `Range` reach the `Comment` views; registered by `Comment.mts`. */
 export interface CommentApi {
     commentsOf(scope: Body | Paragraph | Range): Promise<Comment[]>;
-    insertComment(range: Range, text: string): Promise<Comment>;
+    insertComment(range: Range, content: CommentContent, options?: CommentOptions): Promise<Comment>;
 }
 export declare function setCommentApi(implementation: CommentApi): void;
 export declare function commentApi(): CommentApi;

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

@@ -4,14 +4,16 @@ export { Range } from './Range.mjs';
 export { BUILT_IN_STYLES, builtInOf, idOfBuiltIn, displayNameOf, styleNameOf, styleIdOf, type BuiltInStyle } from './styles.mjs';
 export { Comment } from './Comment.mjs';
 export { List, ListItem, ListItemNotFoundError, NumberingFacade, listsOf, listLabelsOf, numberingEmulatorOf, levelOf, type ListLevelType, type ListNumbering, type ListBullet, type StartListOptions, type ListLabel, } from './List.mjs';
-export { type Author, type CommentParts, type CommentPartsAccess, type CommentsExtensible, type CommentMarker, COMMENT_TEXT_STYLE, COMMENT_REFERENCE_STYLE, markersOf, markersOfParagraph, commentIdsOf } from './comments.mjs';
+export { type Author, type CommentContent, type CommentOptions, type CommentParts, type CommentPartsAccess, type CommentsExtensible, type CommentMarker, COMMENT_TEXT_STYLE, COMMENT_REFERENCE_STYLE, markersOf, markersOfParagraph, commentIdsOf } from './comments.mjs';
 export { Font, type UnderlineType, type RPrHolder, type FontTracking } from './Font.mjs';
 export { Table, TableRow, TableCell, cellOf } from './Table.mjs';
 export { InlinePicture, imageInfoOf, naturalSizeEmu, addImage, writableWidthEmu, type ImageFormat, type ImageInfo, type InlinePictureOptions, type NewPicture } from './InlinePicture.mjs';
 export { ContentControl, collectControls, collectRunControls, W14_NS, W15_NS, type ContentControlType, type ContentControlForm, type ContentControlAppearance } from './ContentControl.mjs';
 export { contentOf, isFlatOpc, rewriteRelationshipIds, type OoxmlOptions } from './ooxml.mjs';
-export { type SearchOptions, searchPattern } from './search.mjs';
+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, copyRPr, markDeleted, markInserted, toDeletedText, toRestoredText, restoreRPr, restorePPr, trackInsertedParagraph, trackInsertedTable, wrapNewRuns, paraRPrOf, rowPrOf, pruneParagraphProperties, type ChangeTrackingMode, type TrackingHost, } from './tracking.mjs';
+export { ChangeTracker, trackerOf, calendarOf, dateOf, copyRPr, markDeleted, markInserted, toDeletedText, toRestoredText, restoreRPr, restorePPr, trackInsertedParagraph, trackInsertedTable, wrapNewRuns, paraRPrOf, rowPrOf, pruneParagraphProperties, type ChangeTrackingMode, type TrackingHost, type TrackingScope, } 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

@@ -12,10 +12,12 @@ export { Table, TableRow, TableCell, cellOf } from './Table.mjs';
 export { InlinePicture, imageInfoOf, naturalSizeEmu, addImage, writableWidthEmu } from './InlinePicture.mjs';
 export { ContentControl, collectControls, collectRunControls, W14_NS, W15_NS } from './ContentControl.mjs';
 export { contentOf, isFlatOpc, rewriteRelationshipIds } from './ooxml.mjs';
-export { searchPattern } from './search.mjs';
+export { searchPattern, findAll, matchesOf, expandReplacement } from './search.mjs';
 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, copyRPr, markDeleted, markInserted, toDeletedText, toRestoredText, restoreRPr, restorePPr, trackInsertedParagraph, trackInsertedTable, wrapNewRuns, 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';
+export { bindSnapshot, boundsOf, pathOf } from './binder.mjs';