@docx4j/core-ts 0.2.0 → 0.2.2

package/README.md

@@ -113,6 +113,11 @@ 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.
@@ -226,7 +231,9 @@ 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.
+view throughout, so an agent sees the document as it will read once the changes are taken. A moved
+paragraph is listed as its two halves, and accepting or rejecting either resolves the whole move,
+as Word's Review tab does.
 
 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

package/dist/model/content/Paragraph.mjs

@@ -527,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);
@@ -554,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
@@ -613,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);
@@ -807,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));
@@ -927,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

@@ -90,14 +90,43 @@ 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;
+    private touchesSpan;
+    /** The text a hyperlink holds, as [start, end) in the paragraph, or undefined when it holds none. */
+    private spanOf;
+    /**
+     * 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,9 +1,9 @@
 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';
@@ -247,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;
@@ -259,8 +269,24 @@ export class Range {
         return anchor === '' ? address : `${address}#${anchor}`;
     }
     set hyperlink(value) {
-        var _a;
+        var _a, _b, _c;
         const paragraph = this.paragraph;
+        // A range that crosses the edge of a link takes the whole of that link into the new one; a range
+        // inside a link replaces it with a link over the range alone. Measured in Word through Office JS
+        // (test/README.md check 16, cases F and G; CR-002 section 25): "alpha beta" linked and then
+        // "beta gamma" is one link over "alpha beta gamma", where "alpha beta gamma" linked and then
+        // "beta" leaves "alpha " and " gamma" unlinked.
+        let start = this.start;
+        let end = this.end;
+        for (const holder of hyperlinkHolders(paragraph)) {
+            const span = this.spanOf(holder);
+            if (span === undefined || !this.touchesSpan(span))
+                continue;
+            if (span[0] <= this.start && this.end <= span[1])
+                continue;
+            start = Math.min(start, span[0]);
+            end = Math.max(end, span[1]);
+        }
         this.removeHyperlinks();
         if (value === '')
             return;
@@ -277,13 +303,13 @@ export class Range {
             holder.value.anchor = location;
         if (address !== '')
             holder.value.id = this.addHyperlinkRelationship(address);
-        if (this.start === this.end) {
-            paragraph.insertItemsAt(this.start, [holder]);
+        if (start === end) {
+            paragraph.insertItemsAt(start, [holder]);
             return;
         }
-        paragraph.splitAt(this.start);
-        paragraph.splitAt(this.end);
-        const segments = paragraph.segments().filter((seg) => seg.start >= this.start && seg.end <= this.end);
+        paragraph.splitAt(start);
+        paragraph.splitAt(end);
+        const segments = paragraph.segments().filter((seg) => seg.start >= start && seg.end <= end);
         if (segments.length === 0)
             throw new Docx4JException('This range covers no run');
         const owner = segments[0].runOwner;
@@ -300,35 +326,79 @@ 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) {
+        const span = this.spanOf(holder);
+        return span !== undefined && this.touchesSpan(span);
+    }
+    touchesSpan([start, end]) {
+        return this.start === this.end ? start <= this.start && this.start < end : start < this.end && end > this.start;
+    }
+    /** The text a hyperlink holds, as [start, end) in the paragraph, or undefined when it holds none. */
+    spanOf(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;
+        }
+        return start === undefined ? undefined : [start, end];
+    }
+    /**
+     * 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;
@@ -343,6 +413,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/TrackedChange.d.mts

@@ -70,9 +70,15 @@ export declare class TrackedChange {
     get text(): string;
     /** The range the change covers; a deletion is a collapsed range where it sits in the accepted text. */
     getRange(): Range | undefined;
-    /** Keeps the change: a `w:ins` is unwrapped, a `w:del` removed, a deleted mark joins the paragraphs. */
+    /**
+     * Keeps the change: a `w:ins` is unwrapped, a `w:del` removed, a deleted mark joins the paragraphs.
+     * Either half of a move keeps the whole move, as Word's Review tab does (CR-002 section 29).
+     */
     accept(): void;
-    /** Puts back what was there: a `w:ins` is removed, a `w:del` restored, a `w:rPrChange` re-applied. */
+    /**
+     * Puts back what was there: a `w:ins` is removed, a `w:del` restored, a `w:rPrChange` re-applied.
+     * Either half of a move rejects the whole move, as Word's Review tab does (CR-002 section 29).
+     */
     reject(): void;
     private requireParagraph;
 }
@@ -86,7 +92,7 @@ export declare class TrackedChange {
  * with: the paragraph then goes, its content joining the one before. With neither neighbour the
  * mark is simply dropped.
  */
-export declare function joinWithNext(paragraph: Paragraph, fallbackToPrevious?: boolean): void;
+export declare function joinWithNext(paragraph: Pick<Paragraph, 'container' | 'element' | 'p'>, fallbackToPrevious?: boolean): void;
 /** The tracked changes of one paragraph, in document order. */
 export declare function trackedChangesOfParagraph(paragraph: Paragraph): TrackedChange[];
 /**

package/dist/model/content/TrackedChange.mjs

@@ -73,12 +73,17 @@ export class TrackedChange {
         }
         return p.getRange('Whole');
     }
-    /** Keeps the change: a `w:ins` is unwrapped, a `w:del` removed, a deleted mark joins the paragraphs. */
+    /**
+     * Keeps the change: a `w:ins` is unwrapped, a `w:del` removed, a deleted mark joins the paragraphs.
+     * Either half of a move keeps the whole move, as Word's Review tab does (CR-002 section 29).
+     */
     accept() {
         var _a, _b, _c;
         const t = this.target;
         switch (t.kind) {
             case 'run':
+                if ((t.revision === 'moveFrom' || t.revision === 'moveTo') && resolveMove(this, 'accept'))
+                    return;
                 if (t.revision === 'ins' || t.revision === 'moveTo')
                     unwrap(t);
                 else
@@ -111,12 +116,17 @@ export class TrackedChange {
                 return;
         }
     }
-    /** Puts back what was there: a `w:ins` is removed, a `w:del` restored, a `w:rPrChange` re-applied. */
+    /**
+     * Puts back what was there: a `w:ins` is removed, a `w:del` restored, a `w:rPrChange` re-applied.
+     * Either half of a move rejects the whole move, as Word's Review tab does (CR-002 section 29).
+     */
     reject() {
         var _a;
         const t = this.target;
         switch (t.kind) {
             case 'run':
+                if ((t.revision === 'moveFrom' || t.revision === 'moveTo') && resolveMove(this, 'reject'))
+                    return;
                 if (t.revision === 'ins' || t.revision === 'moveTo')
                     remove(t.owner, t.element);
                 else
@@ -298,6 +308,129 @@ function acceptedOffsetOf(p, target) {
     visit(runItemsOf(p));
     return found >= 0 ? found : pos;
 }
+const RANGE_MARKERS = {
+    moveFromRangeStart: { kind: 'start', side: 'from' }, moveFromRangeEnd: { kind: 'end', side: 'from' },
+    moveToRangeStart: { kind: 'start', side: 'to' }, moveToRangeEnd: { kind: 'end', side: 'to' },
+};
+/**
+ * Accepts or rejects the whole move a run-level half belongs to, as Word's Review tab does from
+ * either half (`test/README.md` check 18, Word 16.0.20326.20158; Office JS cannot list a move at
+ * all there, check 17). Word pairs the halves by the `w:name` on their range starts
+ * (`w:moveFromRangeStart`, `w:moveToRangeStart`); `w:moveFrom` and `w:moveTo` carry none, so a half
+ * belongs to the move whose range of its side is open where it stands. Accepting keeps the
+ * destination and removes the source, paragraph mark and all; rejecting the other way round; the
+ * four range markers go either way. Returns false for a half in no named range - markup without
+ * range markers, or a half already resolved - which the caller then treats on its own, as before.
+ */
+function resolveMove(change, action) {
+    var _a, _b, _c;
+    const t = change.target;
+    if (t.kind !== 'run' || !change.paragraph)
+        return false;
+    const pieces = movePiecesOf(storyOf(change.paragraph.p));
+    const half = pieces.find((piece) => piece.kind === 'half' && piece.element === t.element);
+    if (!half || half.kind !== 'half' || half.names.length === 0)
+        return false;
+    const name = half.names[0];
+    const ids = new Set(pieces.filter((piece) => piece.kind === 'start' && piece.name === name).map((piece) => piece.id));
+    const mine = pieces.filter((piece) => (piece.kind === 'start' && piece.name === name) || (piece.kind === 'end' && ids.has(piece.id))
+        || ((piece.kind === 'half' || piece.kind === 'mark') && piece.names.includes(name)));
+    const kept = action === 'accept' ? 'to' : 'from';
+    // the markers first: a range end between two paragraphs would stop the paragraph join below
+    for (const piece of mine)
+        if (piece.kind === 'start' || piece.kind === 'end')
+            remove(piece.owner, piece.element);
+    for (const piece of mine) {
+        if (piece.kind !== 'half')
+            continue;
+        const target = { kind: 'run', revision: piece.side === 'from' ? 'moveFrom' : 'moveTo', element: piece.element, owner: piece.owner, value: piece.element.value };
+        if (piece.side === kept) {
+            if (piece.side === 'from')
+                restoreDeleted(target);
+            else
+                unwrap(target);
+        }
+        else
+            remove(piece.owner, piece.element);
+    }
+    // the paragraph marks last, last first, so that a join never disturbs one still to do
+    const marks = mine.filter((piece) => piece.kind === 'mark');
+    for (let i = marks.length - 1; i >= 0; i--) {
+        const mark = marks[i];
+        const p = mark.paragraph.value;
+        if (mark.side === kept) {
+            const rPr = (_a = p.pPr) === null || _a === void 0 ? void 0 : _a.rPr;
+            if (rPr)
+                delete rPr[mark.side === 'from' ? 'moveFrom' : 'moveTo'];
+            pruneParagraphProperties(p);
+        }
+        else if (((_b = p.content) !== null && _b !== void 0 ? _b : []).length === 0) {
+            remove(mark.container, mark.paragraph); // the moved paragraph, emptied: gone, as in Word
+        }
+        else {
+            const rPr = (_c = p.pPr) === null || _c === void 0 ? void 0 : _c.rPr;
+            if (rPr)
+                delete rPr[mark.side === 'from' ? 'moveFrom' : 'moveTo'];
+            joinWithNext({ container: mark.container, element: mark.paragraph, p }, mark.side === 'to');
+        }
+    }
+    return true;
+}
+/** The story a paragraph is in: the outermost array of block content above it (a body, a header, a note). */
+function storyOf(p) {
+    let story;
+    for (let o = p; o !== undefined; o = o.PARENT) {
+        const content = o.content;
+        if (Array.isArray(content) && o.TYPE_NAME !== 'org_docx4j_wml.P')
+            story = content;
+    }
+    return story !== null && story !== void 0 ? story : [];
+}
+/** Every piece of move markup in a story, in document order, each half and mark with the names of the ranges open over it. */
+function movePiecesOf(story) {
+    const out = [];
+    const open = { from: new Map(), to: new Map() };
+    const visit = (items) => {
+        var _a, _b, _c, _d, _e, _f;
+        for (const el of items) {
+            const marker = RANGE_MARKERS[(_b = (_a = el.name) === null || _a === void 0 ? void 0 : _a.localPart) !== null && _b !== void 0 ? _b : ''];
+            const value = el.value;
+            if (marker && value) {
+                const id = Number(value.id);
+                if (marker.kind === 'start') {
+                    open[marker.side].set(id, (_c = value.name) !== null && _c !== void 0 ? _c : '');
+                    out.push({ kind: 'start', side: marker.side, id, name: (_d = value.name) !== null && _d !== void 0 ? _d : '', element: el, owner: items });
+                }
+                else {
+                    open[marker.side].delete(id);
+                    out.push({ kind: 'end', side: marker.side, id, element: el, owner: items });
+                }
+                continue;
+            }
+            const revision = revisionKindOf(el);
+            if (revision === 'moveFrom' || revision === 'moveTo') {
+                const side = revision === 'moveFrom' ? 'from' : 'to';
+                out.push({ kind: 'half', side, element: el, owner: items, names: [...open[side].values()] });
+            }
+            const v = el.value;
+            if (typeof v !== 'object' || v === null)
+                continue;
+            const children = (_e = childrenOf(v)) !== null && _e !== void 0 ? _e : runItemsOf(v);
+            if (children)
+                visit(children);
+            if (typeNameOf(el) === 'org_docx4j_wml.P') {
+                const rPr = (_f = v.pPr) === null || _f === void 0 ? void 0 : _f.rPr;
+                for (const side of ['from', 'to']) {
+                    if (rPr === null || rPr === void 0 ? void 0 : rPr[side === 'from' ? 'moveFrom' : 'moveTo']) {
+                        out.push({ kind: 'mark', side, paragraph: el, container: items, names: [...open[side].values()] });
+                    }
+                }
+            }
+        }
+    };
+    visit(story);
+    return out;
+}
 // --- collecting ----------------------------------------------------------------------------
 /** The tracked changes of one paragraph, in document order. */
 export function trackedChangesOfParagraph(paragraph) {

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

@@ -32,7 +32,7 @@ export interface BoundSnapshot {
  * 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. */
+/** 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

package/dist/model/content/binder.mjs

@@ -30,14 +30,15 @@ export async function bindSnapshot(element) {
     });
     return { root, objects };
 }
-/** Turns selected nodes into `Bound`s against a snapshot. */
+/** 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: pathOf(node),
+            path: paths.of(node),
         };
         if (node.nodeType === 2)
             bound.attribute = node.name;
@@ -66,29 +67,61 @@ function owningElement(node) {
  * than a short one, and docx4j's harness records the same form.
  */
 export function pathOf(node) {
-    if (node.nodeType === 2) {
-        const owner = node.ownerElement;
-        return `${owner === null ? '' : pathOf(owner)}/@${node.name}`;
+    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();
     }
-    if (node.nodeType === 3 || node.nodeType === 4) {
-        const parent = node.parentNode;
-        return `${parent === null ? '' : pathOf(parent)}/text()`;
+    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;
     }
-    if (node.nodeType !== 1)
-        return '';
-    const element = node;
-    const parent = element.parentNode;
-    if (parent === null || parent.nodeType !== 1)
-        return `/${element.nodeName}`;
-    let index = 0;
-    for (let sibling = parent.firstChild; sibling; sibling = sibling.nextSibling) {
-        if (sibling.nodeType === 1 && sibling.nodeName === element.nodeName) {
-            index++;
-            if (sibling === element)
-                break;
+    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;
     }
-    return `${pathOf(parent)}/${element.nodeName}[${index}]`;
 }
 function isElement(node) {
     return typeof node === 'object' && node !== null && node.nodeType === 1;

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

@@ -13,7 +13,7 @@ export { contentOf, isFlatOpc, rewriteRelationshipIds, type OoxmlOptions } from
 export { type SearchOptions, searchPattern, findAll, matchesOf, expandReplacement } from './search.mjs';
 export { segmentsOf, runsOf, runItemsOf, childrenOf, rowsOf, cellsOf, BLOCK_LEVEL_TYPES, SDT_TYPES, runOf, paragraphOf, textOfView, revisionKindOf, type TextSegment, type Located, type TextView, type TextViewOptions, type RevisionKind, type RevisionHolder } from './tree.mjs';
 export { TrackedChange, trackedChangesOfParagraph, trackedChangesOfRow, joinWithNext, type TrackedChangeType, type TrackedChangeTarget } from './TrackedChange.mjs';
-export { ChangeTracker, trackerOf, calendarOf, dateOf, copyRPr, markDeleted, markInserted, toDeletedText, toRestoredText, restoreRPr, restorePPr, trackInsertedParagraph, trackInsertedTable, wrapNewRuns, paraRPrOf, rowPrOf, pruneParagraphProperties, type ChangeTrackingMode, type TrackingHost, type TrackingScope, } from './tracking.mjs';
+export { ChangeTracker, trackerOf, calendarOf, dateOf, copyRPr, markDeleted, markInserted, highestAnnotationId, MARKUP_TYPES, 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

@@ -16,7 +16,7 @@ export { searchPattern, findAll, matchesOf, expandReplacement } from './search.m
 export { segmentsOf, runsOf, runItemsOf, childrenOf, rowsOf, cellsOf, BLOCK_LEVEL_TYPES, SDT_TYPES, runOf, paragraphOf, textOfView, revisionKindOf } from './tree.mjs';
 // change tracking (CR-002 phase F)
 export { TrackedChange, trackedChangesOfParagraph, trackedChangesOfRow, joinWithNext } from './TrackedChange.mjs';
-export { ChangeTracker, trackerOf, calendarOf, dateOf, copyRPr, markDeleted, markInserted, toDeletedText, toRestoredText, restoreRPr, restorePPr, trackInsertedParagraph, trackInsertedTable, wrapNewRuns, paraRPrOf, rowPrOf, pruneParagraphProperties, } from './tracking.mjs';
+export { ChangeTracker, trackerOf, calendarOf, dateOf, copyRPr, markDeleted, markInserted, highestAnnotationId, MARKUP_TYPES, 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';

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

@@ -26,6 +26,14 @@ export declare function findAll(text: string, pattern: RegExp): [number, number]
  * Every match of a pattern in a text, with its capture groups: what `replaceText` needs to expand
  * `$1` and Word's `\1`. An empty match advances by one rather than looping forever, as `findAll`
  * has always done.
+ *
+ * A match that starts or ends inside a grapheme cluster is dropped: half of an emoji's surrogate
+ * pair (a wildcard `?` or class matches one UTF-16 unit), or an Arabic letter without the
+ * combining mark after it (`\p{L}+` stops before the mark). Such a range is not text a person can
+ * see, and replacing it splits a character - half a surrogate pair is saved as U+FFFD (CR-002
+ * section 32 item 1, found by the editor's agreement suite). The clusters are `Intl.Segmenter`'s,
+ * computed only for a text with a code unit at or above U+0300, below which every code unit is a
+ * cluster of its own, so Latin text pays nothing; a runtime without `Intl.Segmenter` keeps every match.
  */
 export declare function matchesOf(text: string, pattern: RegExp): RegExpExecArray[];
 /**

package/dist/model/content/search.mjs

@@ -94,6 +94,14 @@ export function findAll(text, pattern) {
  * Every match of a pattern in a text, with its capture groups: what `replaceText` needs to expand
  * `$1` and Word's `\1`. An empty match advances by one rather than looping forever, as `findAll`
  * has always done.
+ *
+ * A match that starts or ends inside a grapheme cluster is dropped: half of an emoji's surrogate
+ * pair (a wildcard `?` or class matches one UTF-16 unit), or an Arabic letter without the
+ * combining mark after it (`\p{L}+` stops before the mark). Such a range is not text a person can
+ * see, and replacing it splits a character - half a surrogate pair is saved as U+FFFD (CR-002
+ * section 32 item 1, found by the editor's agreement suite). The clusters are `Intl.Segmenter`'s,
+ * computed only for a text with a code unit at or above U+0300, below which every code unit is a
+ * cluster of its own, so Latin text pays nothing; a runtime without `Intl.Segmenter` keeps every match.
  */
 export function matchesOf(text, pattern) {
     const out = [];
@@ -105,7 +113,20 @@ export function matchesOf(text, pattern) {
         }
         out.push(m);
     }
-    return out;
+    const boundaries = out.length > 0 ? graphemeBoundaries(text) : undefined;
+    return boundaries === undefined ? out : out.filter((m) => boundaries.has(m.index) && boundaries.has(m.index + m[0].length));
+}
+/** The code-unit offsets where a grapheme cluster starts, and the text's end; undefined where every unit is its own cluster. */
+function graphemeBoundaries(text) {
+    if (!/[\u0300-\uffff]/.test(text))
+        return undefined;
+    const Segmenter = Intl.Segmenter;
+    if (Segmenter === undefined)
+        return undefined;
+    const boundaries = new Set([text.length]);
+    for (const segment of new Segmenter(undefined, { granularity: 'grapheme' }).segment(text))
+        boundaries.add(segment.index);
+    return boundaries;
 }
 /**
  * A replacement with its group references expanded against one match: `$1` to `$9`, `$&` and `$$`

package/dist/packages/WordprocessingMLPackage.d.mts

@@ -75,6 +75,12 @@ export declare class WordprocessingMLPackage extends OpcPackage implements Track
      */
     private trackingScopes;
     private beforeScopes;
+    /**
+     * Style ids a synchronous setter has given runs, to be defined in the styles part by the time the
+     * package is saved: `Range.hyperlink` writes `w:rStyle w:val="Hyperlink"` and cannot await
+     * `styles.ensure` (CR-002 section 25). `saveTo` ensures them; nothing is read before then.
+     */
+    private requiredStyles;
     /**
      * The parts `seedAnnotationIds()` has read, with what it read: `true` for a part still holding its
      * source, whose bytes cannot change, and otherwise the bytes that were set, which stay the same
@@ -226,9 +232,27 @@ export declare class WordprocessingMLPackage extends OpcPackage implements Track
      * bytes cannot change; bytes that were set are read again when they are set again.
      */
     seedAnnotationIds(): Promise<number>;
+    /**
+     * Records the highest annotation id of a part the caller has read itself, so that
+     * `seedAnnotationIds()` does not read it again. An editor that imports the main document part into
+     * a model of its own knows that part's ids already, and seeding would parse it a second time -
+     * 1.06 s for a 255-page document (CR-002 section 34). The floor rises to `highest` at once, and
+     * the part counts as read for the bytes it holds now: set its bytes again and the next seed reads
+     * it afresh; unmarshal it and the counter's own scan of it covers it.
+     *
+     * The caller vouches for the number: one lower than the part's highest id lets a new revision
+     * reuse an id. Asynchronous only because a part whose bytes were set is keyed on those bytes.
+     */
+    noteAnnotationIds(part: XmlPart<unknown>, highest: number): Promise<void>;
     /** TrackingHost: the trees a new revision id must be above, which is every part already unmarshalled. */
     markupRoots(): object[];
-    /** A clone carries the identity, the tracking date, the theme setting and the XPath engine. */
+    /**
+     * Asks for style definitions a synchronous setter has referenced; they are ensured on save, as
+     * `pkg.styles.ensure(ids)` would, and a document that already has them keeps its styles part
+     * byte for byte (CR-002 section 25). Await `styles.ensure` instead to have them at once.
+     */
+    requireStyles(ids: Iterable<string>): void;
+    /** A clone carries the identity, the tracking date, the theme setting, the XPath engine and the styles still to ensure. */
     protected copyPackageSettingsTo(target: OpcPackage): void;
     saveTo<R>(sink: PartSink<R>): Promise<R>;
     /** The paragraph at an address anywhere in the document: 'body/3', 'header:rId5/0', a paraId, or a text match. */

package/dist/packages/WordprocessingMLPackage.mjs

@@ -75,6 +75,12 @@ export class WordprocessingMLPackage extends OpcPackage {
          * applies again, and when none is left the package is as it was (CR-002 section 31).
          */
         this.trackingScopes = [];
+        /**
+         * Style ids a synchronous setter has given runs, to be defined in the styles part by the time the
+         * package is saved: `Range.hyperlink` writes `w:rStyle w:val="Hyperlink"` and cannot await
+         * `styles.ensure` (CR-002 section 25). `saveTo` ensures them; nothing is read before then.
+         */
+        this.requiredStyles = new Set();
         /**
          * The parts `seedAnnotationIds()` has read, with what it read: `true` for a part still holding its
          * source, whose bytes cannot change, and otherwise the bytes that were set, which stay the same
@@ -442,6 +448,28 @@ export class WordprocessingMLPackage extends OpcPackage {
         }
         return this.annotationIdFloor;
     }
+    /**
+     * Records the highest annotation id of a part the caller has read itself, so that
+     * `seedAnnotationIds()` does not read it again. An editor that imports the main document part into
+     * a model of its own knows that part's ids already, and seeding would parse it a second time -
+     * 1.06 s for a 255-page document (CR-002 section 34). The floor rises to `highest` at once, and
+     * the part counts as read for the bytes it holds now: set its bytes again and the next seed reads
+     * it afresh; unmarshal it and the counter's own scan of it covers it.
+     *
+     * The caller vouches for the number: one lower than the part's highest id lets a new revision
+     * reuse an id. Asynchronous only because a part whose bytes were set is keyed on those bytes.
+     */
+    async noteAnnotationIds(part, highest) {
+        if (!Number.isInteger(highest) || highest < 0) {
+            throw new Docx4JException(`The highest annotation id must be a non-negative integer, not ${String(highest)}`);
+        }
+        if (this.parts.get(part.partName.name) !== part) {
+            throw new Docx4JException(`${part.partName.name} is not a part of this package`);
+        }
+        this.annotationIdFloor = Math.max(this.annotationIdFloor, highest);
+        if (!part.isUnmarshalled)
+            this.seededParts.set(part, part.isUntouched ? true : await part.getBytes());
+    }
     /** TrackingHost: the trees a new revision id must be above, which is every part already unmarshalled. */
     markupRoots() {
         const out = [];
@@ -454,10 +482,20 @@ export class WordprocessingMLPackage extends OpcPackage {
         }
         return out;
     }
-    /** A clone carries the identity, the tracking date, the theme setting and the XPath engine. */
+    /**
+     * Asks for style definitions a synchronous setter has referenced; they are ensured on save, as
+     * `pkg.styles.ensure(ids)` would, and a document that already has them keeps its styles part
+     * byte for byte (CR-002 section 25). Await `styles.ensure` instead to have them at once.
+     */
+    requireStyles(ids) {
+        for (const id of ids)
+            this.requiredStyles.add(id);
+    }
+    /** A clone carries the identity, the tracking date, the theme setting, the XPath engine and the styles still to ensure. */
     copyPackageSettingsTo(target) {
         if (!(target instanceof WordprocessingMLPackage))
             return;
+        target.requireStyles(this.requiredStyles);
         target.author = { ...this.author };
         target.trackedChangeDate = this.trackedChangeDate;
         target.fonts.defaultTheme = this.fonts.defaultTheme;
@@ -467,6 +505,10 @@ export class WordprocessingMLPackage extends OpcPackage {
         var _a;
         if (this.trackingPending)
             await this.setChangeTrackingMode((_a = this.trackingMode) !== null && _a !== void 0 ? _a : 'Off');
+        if (this.requiredStyles.size > 0) {
+            await this.styles.ensure([...this.requiredStyles]);
+            this.requiredStyles.clear();
+        }
         return super.saveTo(sink);
     }
     /** The paragraph at an address anywhere in the document: 'body/3', 'header:rId5/0', a paraId, or a text match. */

package/dist/xml/dom.d.mts

@@ -1,6 +1,15 @@
 /** The declaration docx4j writes on every XML part. */
 export declare const XML_DECLARATION = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>";
-/** Parses XML text to a DOM document; throws on malformed input. */
+/**
+ * Parses XML text to a DOM document; throws on malformed input, in a browser as in Node.
+ *
+ * xmldom throws. A browser's `DOMParser` does not: Chromium returns the document up to the error
+ * with an XHTML `parsererror` element first in the root, and Firefox a `parsererror` root in its
+ * own namespace, and handing that on unmarshalled a truncated part without complaint - a settings
+ * part with a stray `<` kept its first child and lost the rest, which a save would have written
+ * (CR-002 section 33). Such a document is refused here, with the parser's own message, which
+ * carries the line and column in both browsers.
+ */
 export declare function parseXml(text: string): Document;
 /** Serialises a node (document or element) without an XML declaration. */
 export declare function serializeXml(node: Node): string;

package/dist/xml/dom.mjs

@@ -1,12 +1,56 @@
 // DOM, text and base64 helpers over the runtime's DOM implementation. In Node the runtime brings
 // @xmldom/xmldom; in browsers it uses the native DOM. Jsonix.DOM is typed since @docx4j/jsonix 3.2.1.
 import { Jsonix } from '@docx4j/generated-objects-ts';
+import { Docx4JException } from '../opc/exceptions.mjs';
 const DOM = Jsonix.DOM;
 /** The declaration docx4j writes on every XML part. */
 export const XML_DECLARATION = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>';
-/** Parses XML text to a DOM document; throws on malformed input. */
+/**
+ * Parses XML text to a DOM document; throws on malformed input, in a browser as in Node.
+ *
+ * xmldom throws. A browser's `DOMParser` does not: Chromium returns the document up to the error
+ * with an XHTML `parsererror` element first in the root, and Firefox a `parsererror` root in its
+ * own namespace, and handing that on unmarshalled a truncated part without complaint - a settings
+ * part with a stray `<` kept its first child and lost the rest, which a save would have written
+ * (CR-002 section 33). Such a document is refused here, with the parser's own message, which
+ * carries the line and column in both browsers.
+ */
 export function parseXml(text) {
-    return DOM.parse(text);
+    const doc = DOM.parse(text);
+    const error = parserErrorOf(doc);
+    if (error !== undefined)
+        throw new Docx4JException(`Malformed XML: ${error}`);
+    return doc;
+}
+/** The namespaces a browser puts its `parsererror` element in: Chromium and WebKit's, Firefox's. */
+const PARSER_ERROR_NAMESPACES = new Set([
+    'http://www.w3.org/1999/xhtml',
+    'http://www.mozilla.org/newlayout/xml/parsererror.xml',
+]);
+/**
+ * The message of a browser's `parsererror` document - the root, or the root's first element child,
+ * named `parsererror` in one of the parser-error namespaces - or undefined for a document that
+ * parsed. Chromium's message is the `div` in its element; its `h3`s are boilerplate.
+ */
+function parserErrorOf(doc) {
+    var _a, _b;
+    const root = doc.documentElement;
+    if (!root)
+        return undefined;
+    let first = null;
+    for (let child = root.firstChild; child; child = child.nextSibling) {
+        if (child.nodeType === 1) {
+            first = child;
+            break;
+        }
+    }
+    for (const element of [root, first]) {
+        if (element === null || element.localName !== 'parsererror' || !PARSER_ERROR_NAMESPACES.has((_a = element.namespaceURI) !== null && _a !== void 0 ? _a : ''))
+            continue;
+        const div = element.getElementsByTagNameNS('http://www.w3.org/1999/xhtml', 'div')[0];
+        return ((_b = (div !== null && div !== void 0 ? div : element).textContent) !== null && _b !== void 0 ? _b : '').replace(/\s+/g, ' ').trim() || 'the parser reported an error';
+    }
+    return undefined;
 }
 /** Serialises a node (document or element) without an XML declaration. */
 export function serializeXml(node) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docx4j/core-ts",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "docx4j-core for TypeScript: Open Packaging (docx/pptx/xlsx zip and flat OPC), typed parts and relationships, style, numbering and font resolution over @docx4j/generated-objects-ts. Node, browsers, Word add-ins.",
   "type": "module",
   "main": "./dist/index.mjs",