@docx4j/core-ts 0.2.2 → 0.3.1

package/dist/model/content/Paragraph.mjs

@@ -19,10 +19,26 @@ import { controlIdScope, sdtKindFor } from '../customxml/insert.mjs';
 import { InlinePicture, addImage, writableWidthEmu } from './InlinePicture.mjs';
 import { contentOf } from './ooxml.mjs';
 import { commentApi } from './comments.mjs';
-import { copyRPr, markDeleted, toDeletedText } from './tracking.mjs';
+import { ChangeTracker, copyRPr, markDeleted, toDeletedText, highestAnnotationId, canonical, restorePPr, wrapInsertedRuns, markHolderInserted } from './tracking.mjs';
 import { trackedChangesOfParagraph } from './TrackedChange.mjs';
 import { isListItem, listOf, listOrNullObjectOf, listItemOf, listItemOrNullObjectOf, startNewList, attachToList, detachFromList, } from './List.mjs';
 const TWIPS_PER_POINT = 20;
+/** Office JS's paragraph formatting read from a `w:pPr`, resolved (`effective`) or direct. */
+function formattingOf(pPr, effective) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    return {
+        alignment: alignmentOf(pPr, effective),
+        leftIndent: ((_b = (_a = pPr === null || pPr === void 0 ? void 0 : pPr.ind) === null || _a === void 0 ? void 0 : _a.left) !== null && _b !== void 0 ? _b : 0) / TWIPS_PER_POINT,
+        rightIndent: ((_d = (_c = pPr === null || pPr === void 0 ? void 0 : pPr.ind) === null || _c === void 0 ? void 0 : _c.right) !== null && _d !== void 0 ? _d : 0) / TWIPS_PER_POINT,
+        firstLineIndent: firstLineIndentOf(pPr),
+        spaceBefore: ((_f = (_e = pPr === null || pPr === void 0 ? void 0 : pPr.spacing) === null || _e === void 0 ? void 0 : _e.before) !== null && _f !== void 0 ? _f : 0) / TWIPS_PER_POINT,
+        spaceAfter: ((_h = (_g = pPr === null || pPr === void 0 ? void 0 : pPr.spacing) === null || _g === void 0 ? void 0 : _g.after) !== null && _h !== void 0 ? _h : 0) / TWIPS_PER_POINT,
+        lineSpacing: lineSpacingOf(pPr),
+        outlineLevel: outlineLevelOf(pPr),
+    };
+}
+/** The `w:pPr` members `formattingOf` reads; everything else is compared as it is written. */
+const FORMATTING_MEMBERS = new Set(['jc', 'ind', 'spacing', 'outlineLvl']);
 /**
  * A subset of Office JS `Word.Paragraph` over a `w:p` in a body, cell, header, footer or
  * content control. A light view: it holds the element and the array that contains it; nothing
@@ -78,11 +94,11 @@ export class Paragraph {
     set styleId(id) {
         // through pPr(), so that a tracked write records w:pPrChange first (CR-002 phase F)
         const pPr = this.pPr();
-        if (id === '' || id === 'Normal') {
+        if (id === '' || id === 'Normal')
             delete pPr.pStyle;
-            return;
-        }
-        pPr.pStyle = { val: id };
+        else
+            pPr.pStyle = { val: id };
+        this.settleFormatting();
     }
     /**
      * The style's display name ('Heading 1', 'My Style'), as Office JS: from the styles part's
@@ -125,19 +141,7 @@ export class Paragraph {
      * Phase B step 2 (an absent property reads 0, 10 or `'Unknown'`).
      */
     formatting(options) {
-        var _a, _b, _c, _d, _e, _f, _g, _h;
-        const pPr = this.readPPr(options);
-        const effective = (options === null || options === void 0 ? void 0 : options.direct) !== true;
-        return {
-            alignment: alignmentOf(pPr, effective),
-            leftIndent: ((_b = (_a = pPr === null || pPr === void 0 ? void 0 : pPr.ind) === null || _a === void 0 ? void 0 : _a.left) !== null && _b !== void 0 ? _b : 0) / TWIPS_PER_POINT,
-            rightIndent: ((_d = (_c = pPr === null || pPr === void 0 ? void 0 : pPr.ind) === null || _c === void 0 ? void 0 : _c.right) !== null && _d !== void 0 ? _d : 0) / TWIPS_PER_POINT,
-            firstLineIndent: firstLineIndentOf(pPr),
-            spaceBefore: ((_f = (_e = pPr === null || pPr === void 0 ? void 0 : pPr.spacing) === null || _e === void 0 ? void 0 : _e.before) !== null && _f !== void 0 ? _f : 0) / TWIPS_PER_POINT,
-            spaceAfter: ((_h = (_g = pPr === null || pPr === void 0 ? void 0 : pPr.spacing) === null || _g === void 0 ? void 0 : _g.after) !== null && _h !== void 0 ? _h : 0) / TWIPS_PER_POINT,
-            lineSpacing: lineSpacingOf(pPr),
-            outlineLevel: outlineLevelOf(pPr),
-        };
+        return formattingOf(this.readPPr(options), (options === null || options === void 0 ? void 0 : options.direct) !== true);
     }
     /** The effective alignment; an absent `w:jc` after resolution is `'Left'`, as Office JS. */
     get alignment() {
@@ -146,17 +150,35 @@ export class Paragraph {
     set alignment(v) {
         const pPr = this.pPr();
         const val = v === 'Left' ? 'left' : v === 'Centered' ? 'center' : v === 'Right' ? 'right' : v === 'Justified' ? 'both' : undefined;
-        if (val === undefined) {
+        if (val === undefined)
             delete pPr.jc;
-            return;
-        }
-        pPr.jc = { val };
+        else if (this.inheritedAlignment() === v)
+            delete pPr.jc;
+        else
+            pPr.jc = { val };
+        this.settleFormatting();
+    }
+    /**
+     * The alignment the paragraph resolves to with no `w:jc` of its own: its style's, else the
+     * defaults'. Word's Ctrl+L on a centred paragraph whose style is left-aligned removes the `w:jc`
+     * rather than writing `w:jc="left"`, with tracking on (check 26) and off (the editor's
+     * `measure-word2010.docx` and `measure-word15.docx`, 2026-09-30; CR-002 section 38), so a value the
+     * paragraph already inherits is not written. Measured for left over a left-aligned style; taken to
+     * hold for any value. Undefined without a resolver, where the value is written as asked.
+     */
+    inheritedAlignment() {
+        var _a;
+        const resolver = (_a = this.parentBody.package_) === null || _a === void 0 ? void 0 : _a.propertyResolverOrUndefined;
+        if (!resolver)
+            return undefined;
+        const { jc: _jc, pPrChange: _change, PARENT: _parent, ...rest } = this.p.pPr;
+        return alignmentOf(resolver.getEffectivePPr(rest), true);
     }
     /** Indents and spacing in points, as Office JS; the effective values (CR-001 Phase B step 2). */
     get leftIndent() { var _a, _b; return ((_b = (_a = this.effectivePPr.ind) === null || _a === void 0 ? void 0 : _a.left) !== null && _b !== void 0 ? _b : 0) / TWIPS_PER_POINT; }
-    set leftIndent(pt) { this.ind().left = Math.round(pt * TWIPS_PER_POINT); }
+    set leftIndent(pt) { this.ind().left = Math.round(pt * TWIPS_PER_POINT); this.settleFormatting(); }
     get rightIndent() { var _a, _b; return ((_b = (_a = this.effectivePPr.ind) === null || _a === void 0 ? void 0 : _a.right) !== null && _b !== void 0 ? _b : 0) / TWIPS_PER_POINT; }
-    set rightIndent(pt) { this.ind().right = Math.round(pt * TWIPS_PER_POINT); }
+    set rightIndent(pt) { this.ind().right = Math.round(pt * TWIPS_PER_POINT); this.settleFormatting(); }
     /** First-line indent; negative for a hanging indent, as Office JS. */
     get firstLineIndent() {
         return firstLineIndentOf(this.effectivePPr);
@@ -171,22 +193,23 @@ export class Paragraph {
             ind.firstLine = Math.round(pt * TWIPS_PER_POINT);
             delete ind.hanging;
         }
+        this.settleFormatting();
     }
     get spaceBefore() { var _a, _b; return ((_b = (_a = this.effectivePPr.spacing) === null || _a === void 0 ? void 0 : _a.before) !== null && _b !== void 0 ? _b : 0) / TWIPS_PER_POINT; }
-    set spaceBefore(pt) { this.spacing().before = Math.round(pt * TWIPS_PER_POINT); }
+    set spaceBefore(pt) { this.spacing().before = Math.round(pt * TWIPS_PER_POINT); this.settleFormatting(); }
     get spaceAfter() { var _a, _b; return ((_b = (_a = this.effectivePPr.spacing) === null || _a === void 0 ? void 0 : _a.after) !== null && _b !== void 0 ? _b : 0) / TWIPS_PER_POINT; }
-    set spaceAfter(pt) { this.spacing().after = Math.round(pt * TWIPS_PER_POINT); }
+    set spaceAfter(pt) { this.spacing().after = Math.round(pt * TWIPS_PER_POINT); this.settleFormatting(); }
     /** Line spacing in points: w:line/240 lines of 12pt when the rule is auto, else w:line twips; 0 when not set. */
     get lineSpacing() {
         return lineSpacingOf(this.effectivePPr);
     }
-    set lineSpacing(pt) { const s = this.spacing(); s.line = Math.round(pt * TWIPS_PER_POINT); s.lineRule = 'exact'; }
+    set lineSpacing(pt) { const s = this.spacing(); s.line = Math.round(pt * TWIPS_PER_POINT); s.lineRule = 'exact'; this.settleFormatting(); }
     /** w:outlineLvl + 1 (1 to 9); 10 for body text, as Office JS. A heading style supplies it. */
     get outlineLevel() { return outlineLevelOf(this.effectivePPr); }
     set outlineLevel(level) { const pPr = this.pPr(); if (level >= 10 || level < 1)
         delete pPr.outlineLvl;
     else
-        pPr.outlineLvl = { val: level - 1 }; }
+        pPr.outlineLvl = { val: level - 1 }; this.settleFormatting(); }
     /**
      * The runs' formatting: reads the first run's *effective* properties, writes direct
      * formatting to all (extension: `Font` is over runs, not the paragraph mark).
@@ -403,6 +426,42 @@ export class Paragraph {
             return;
         }
         tracker.markParagraphDeleted(this.p);
+        this.giveMarkPropertiesToNext(tracker);
+    }
+    /**
+     * A paragraph mark deleted under tracking gives the next paragraph this paragraph's properties,
+     * as a `w:pPrChange` on it recording its own: Word, at Delete at the end of a Heading 2 with a
+     * Normal paragraph after it, wrote the next paragraph `w:pStyle Heading2` with
+     * `<w:pPrChange><w:pPr/></w:pPrChange>`, and No Markup reads the joined line as a heading
+     * throughout (the editor's `measure-word15.docx`, 2026-09-30; CR-002 section 38). The Delete
+     * counterpart of check 29's Enter. Nothing where the two paragraphs' properties are the same
+     * (check 22's deleted marks). Accepting the mark then joins into a paragraph with these
+     * properties, and rejecting puts the next paragraph's back.
+     */
+    giveMarkPropertiesToNext(tracker) {
+        const i = this.index;
+        const next = i >= 0 ? this.container[i + 1] : undefined;
+        if (!next || typeNameOf(next) !== 'org_docx4j_wml.P')
+            return;
+        const base = (pPr) => {
+            const out = {};
+            for (const [key, value] of Object.entries(pPr !== null && pPr !== void 0 ? pPr : {})) {
+                if (key !== 'TYPE_NAME' && key !== 'PARENT' && key !== 'rPr' && key !== 'sectPr' && key !== 'pPrChange' && value !== undefined)
+                    out[key] = value;
+            }
+            return out;
+        };
+        const source = base(this.p.pPr);
+        const nextP = next.value;
+        if (canonical(source) === canonical(base(nextP.pPr)))
+            return;
+        const target = new Paragraph(next, this.container, this.parentBody).pPr();
+        tracker.recordPPrChange(target);
+        for (const key of Object.keys(base(target)))
+            delete target[key];
+        for (const [key, value] of Object.entries(source))
+            target[key] = deepCopy(value);
+        linkParents(target, nextP);
     }
     /**
      * The paragraph's content and its mark marked deleted, the paragraph element itself kept:
@@ -446,6 +505,40 @@ export class Paragraph {
         (_b = this.changeTracker) === null || _b === void 0 ? void 0 : _b.recordPPrChange(pPr);
         return pPr;
     }
+    /**
+     * After a tracked write of the paragraph's properties: when the paragraph is as it was, its
+     * recorded properties go back as they were and the `w:pPrChange` goes, since Word keeps no
+     * formatting change that changes nothing, whoever changed it back (`test/README.md` check 26:
+     * centred then left again, by the same author and by another; Increase Indent then Decrease
+     * Indent; each left no `w:pPr`; CR-002 section 29). "As it was" is Office JS's paragraph
+     * formatting (alignment, indents, spacing, outline level) read resolved from both, the rest of the
+     * properties - the style, the list - written the same: Word's Ctrl+L and Decrease Indent removed
+     * the direct values where this package's setters write `w:jc="left"` and `w:ind w:left="0"`.
+     * Without the package's `PropertyResolver` only properties written the same count.
+     *
+     * @internal public so that the list views (CR-002 phase H) settle their `w:numPr` writes.
+     */
+    settleFormatting() {
+        var _a, _b;
+        const pPr = this.p.pPr;
+        const recorded = (_a = pPr === null || pPr === void 0 ? void 0 : pPr.pPrChange) === null || _a === void 0 ? void 0 : _a.pPr;
+        if (!pPr || !pPr.pPrChange || !this.changeTracker)
+            return;
+        const current = {};
+        for (const [key, value] of Object.entries(pPr))
+            if (key !== 'pPrChange' && key !== 'rPr' && key !== 'sectPr')
+                current[key] = value;
+        const before = { ...(recorded !== null && recorded !== void 0 ? recorded : {}) };
+        let same = canonical(current) === canonical(before);
+        if (!same) {
+            const rest = (props) => canonical(Object.fromEntries(Object.entries(props).filter(([key]) => !FORMATTING_MEMBERS.has(key))));
+            const resolver = (_b = this.parentBody.package_) === null || _b === void 0 ? void 0 : _b.propertyResolverOrUndefined;
+            same = resolver !== undefined && rest(current) === rest(before)
+                && canonical(formattingOf(resolver.getEffectivePPr(current), true)) === canonical(formattingOf(resolver.getEffectivePPr(before), true));
+        }
+        if (same)
+            restorePPr(this.p, recorded);
+    }
     /**
      * The paragraph's `w:numPr`, created when absent, through {@link pPr} so that a tracked
      * write records `w:pPrChange` first.
@@ -494,9 +587,9 @@ export class Paragraph {
      * is removed, a run left empty is removed. Text is inserted into the w:t at `start`,
      * else into a new run with the formatting of the nearest run.
      */
-    splice(start, end, text) {
-        var _a, _b, _c, _d;
-        var _e;
+    splice(start, end, text, prefer = 'before') {
+        var _a, _b, _c, _d, _e, _f;
+        var _g;
         const length = this.text.length;
         start = Math.max(0, Math.min(start, length));
         end = Math.max(start, Math.min(end, length));
@@ -505,11 +598,18 @@ export class Paragraph {
             // a replacement is the w:del first and the w:ins after it, as Word writes one
             const deletions = end > start ? this.deleteText(tracker, start, end) : [];
             if (text.length > 0)
-                this.insertTracked(tracker, start, text, deletions[deletions.length - 1]);
+                this.insertTracked(tracker, start, text, deletions[deletions.length - 1], prefer);
             return new Range(this, start, start + text.length);
         }
         let segs = this.segments();
         let inserted = false;
+        // A replacement that begins inside a revision is a deletion and then the new text typed there, so
+        // the new text is plain and splits the revision, as typed text is (test/README.md check 21), rather
+        // than joining the revision it replaced part of.
+        if (end > start && text.length > 0 && ((_a = segs.find((s) => s.start <= start && start < s.end)) === null || _a === void 0 ? void 0 : _a.revision)) {
+            this.splice(start, end, '');
+            return this.splice(start, start, text);
+        }
         if (end > start) {
             // Replace: the new text takes the place (and formatting) of the first replaced character, as Word does.
             const first = segs.find((s) => s.start <= start && start < s.end);
@@ -546,8 +646,27 @@ export class Paragraph {
             segs = this.segments();
         }
         if (text.length > 0) {
-            // Insert: extend the w:t at `start` (the one containing it, else the one ending there, else the one starting there)
-            const target = (_b = (_a = segs.find((s) => s.editable && s.start < start && start < s.end)) !== null && _a !== void 0 ? _a : segs.find((s) => s.editable && s.end === start)) !== null && _b !== void 0 ? _b : segs.find((s) => s.editable && s.start === start);
+            // Text typed with tracking off is plain wherever it lands, as Word writes it (test/README.md
+            // check 21): inside a revision it splits the revision, and next to one it goes beside it, not
+            // in it. Otherwise it extends the w:t at `start` (the one containing it, else the one ending
+            // there, else the one starting there).
+            const containing = segs.find((s) => s.editable && s.start < start && start < s.end);
+            if ((containing === null || containing === void 0 ? void 0 : containing.revision) && this.insertBetweenHalves(start, runOf([textItem(text)], copyRPr(containing.run.rPr)), () => this.nextAnnotationId())) {
+                return new Range(this, start, start + text.length);
+            }
+            const ending = segs.find((s) => s.editable && s.end === start);
+            const starting = segs.find((s) => s.editable && s.start === start);
+            // `prefer` says which run takes text put exactly between two: the one ending there (typed text,
+            // `Paragraph.insertText`) or the one starting there (`Range.insertText('Before')`, which Office
+            // JS puts inside the link the range is on: check 32)
+            const [near, far] = prefer === 'after' ? [starting, ending] : [ending, starting];
+            const target = (_d = (_c = (_b = (containing && !containing.revision ? containing : undefined)) !== null && _b !== void 0 ? _b : (near && !near.revision ? near : undefined)) !== null && _c !== void 0 ? _c : (far && !far.revision ? far : undefined)) !== null && _d !== void 0 ? _d : containing; // a revision that could not be split: extended, as before
+            const edge = target ? undefined : near !== null && near !== void 0 ? near : far;
+            if (edge === null || edge === void 0 ? void 0 : edge.revision) {
+                const run = runOf([textItem(text)], copyRPr(edge.run.rPr));
+                this.insertBesideRevision(edge.revision, run, edge === ending ? 'after' : 'before');
+                return new Range(this, start, start + text.length);
+            }
             if (target) {
                 const t = target.item.value;
                 const at = start - target.start;
@@ -557,16 +676,16 @@ export class Paragraph {
                 // no w:t to extend: a new run next to the segment at `start`, with that run's formatting
                 const before = [...segs].reverse().find((s) => s.end <= start);
                 const after = segs.find((s) => s.start >= start);
-                const neighbour = before !== null && before !== void 0 ? before : after;
-                const firstRun = (_c = runsOf(this.p)[0]) === null || _c === void 0 ? void 0 : _c.value.rPr;
+                const neighbour = prefer === 'after' ? after !== null && after !== void 0 ? after : before : before !== null && before !== void 0 ? before : after;
+                const firstRun = (_e = runsOf(this.p)[0]) === null || _e === void 0 ? void 0 : _e.value.rPr;
                 const rPr = (neighbour === null || neighbour === void 0 ? void 0 : neighbour.run.rPr) ? deepCopy(neighbour.run.rPr) : firstRun ? deepCopy(firstRun) : undefined;
                 const run = runOf([textItem(text)], rPr);
-                if (before)
+                if (neighbour === before && before)
                     before.runOwner.splice(before.runIndex + 1, 0, run);
                 else if (after)
                     after.runOwner.splice(after.runIndex, 0, run);
                 else {
-                    const content = ((_d = (_e = this.p).content) !== null && _d !== void 0 ? _d : (_e.content = []));
+                    const content = ((_f = (_g = this.p).content) !== null && _f !== void 0 ? _f : (_g.content = []));
                     if (start === 0)
                         content.unshift(run);
                     else
@@ -582,19 +701,33 @@ export class Paragraph {
      * run there when the offset falls inside one. PARENT is linked on what is inserted.
      */
     insertItemsAt(offset, items) {
-        var _a, _b, _c;
-        var _d;
+        var _a, _b, _c, _d;
+        var _e;
         if (items.length === 0)
             return;
+        const tracker = this.changeTracker;
+        if (tracker) {
+            // With tracking on, what goes in is an insertion: its runs in w:ins, in a link, a control or a
+            // field too, placed as typed text is - beside another's revision, or between its halves, never
+            // in it. Before, `insertOoxml` into a paragraph went in untracked (CR-002 section 37).
+            wrapInsertedRuns(tracker, items, this.p);
+            this.splitAt(offset);
+            const segs = this.segments();
+            const before = [...segs].reverse().find((s) => s.end <= offset);
+            const after = segs.find((s) => s.start >= offset);
+            tracker.assertEditable((_a = (before !== null && before !== void 0 ? before : after)) === null || _a === void 0 ? void 0 : _a.revision);
+            this.placeInsertion(offset, items, before, after, () => tracker.nextId());
+            return;
+        }
         this.splitAt(offset);
         const segs = this.segments();
         const after = segs.find((s) => s.start >= offset);
         const before = [...segs].reverse().find((s) => s.end <= offset);
         const neighbour = after !== null && after !== void 0 ? after : before;
-        const list = neighbour ? neighbour.runOwner : ((_a = (_d = this.p).content) !== null && _a !== void 0 ? _a : (_d.content = []));
+        const list = neighbour ? neighbour.runOwner : ((_b = (_e = this.p).content) !== null && _b !== void 0 ? _b : (_e.content = []));
         const at = neighbour ? (after ? neighbour.runIndex : neighbour.runIndex + 1) : (offset === 0 ? 0 : list.length);
         list.splice(at, 0, ...items);
-        const owner = (_c = (_b = neighbour === null || neighbour === void 0 ? void 0 : neighbour.run) === null || _b === void 0 ? void 0 : _b.PARENT) !== null && _c !== void 0 ? _c : this.p;
+        const owner = (_d = (_c = neighbour === null || neighbour === void 0 ? void 0 : neighbour.run) === null || _c === void 0 ? void 0 : _c.PARENT) !== null && _d !== void 0 ? _d : this.p;
         for (const item of items)
             linkParents(item, owner);
     }
@@ -693,6 +826,10 @@ export class Paragraph {
         const sdt = sdtOf([this.element], { kind: sdtKindFor(kind), id: nextSdtId(controlIdScope(this.parentBody)), form: 'block' });
         this.container.splice(at, 1, sdt);
         linkParents(sdt, (_a = this.p.PARENT) !== null && _a !== void 0 ? _a : this.parentBody.container);
+        // under tracking the control itself is the insertion, the paragraph what it was (check 30)
+        const tracker = this.changeTracker;
+        if (tracker)
+            markHolderInserted(tracker, sdt, this.container, () => { });
         return new ContentControl(sdt, this.container, this.parentBody);
     }
     removeEmptyRuns() {
@@ -726,7 +863,7 @@ export class Paragraph {
      * Returns the `w:del` elements it made, in document order.
      */
     deleteText(tracker, start, end) {
-        var _a, _b, _c, _d, _e, _f;
+        var _a, _b, _c, _d, _e;
         const targets = this.isolate(start, end);
         for (const seg of targets)
             tracker.assertEditable(seg.revision);
@@ -772,21 +909,114 @@ export class Paragraph {
             const del = tracker.del(runs);
             owner.splice(at, 0, del);
             linkParents(del, ((_c = (_b = (_a = group[0].revision) === null || _a === void 0 ? void 0 : _a.value) !== null && _b !== void 0 ? _b : group[0].run.value.PARENT) !== null && _c !== void 0 ? _c : this.p));
-            made.unshift({ owner, element: del, parent: ((_f = (_e = (_d = group[0].revision) === null || _d === void 0 ? void 0 : _d.value) !== null && _e !== void 0 ? _e : del.value.PARENT) !== null && _f !== void 0 ? _f : this.p) });
+            const revision = group[0].revision;
+            const anchor = { owner, element: del, parent: ((_e = (_d = revision === null || revision === void 0 ? void 0 : revision.value) !== null && _d !== void 0 ? _d : del.value.PARENT) !== null && _e !== void 0 ? _e : this.p) };
+            if (revision && revision.items === owner)
+                anchor.revision = revision;
+            made.unshift(anchor);
         }
         return made;
     }
+    /**
+     * Splits the revision that holds the text at `at` into two - the second half a copy of its
+     * attributes under a new `w:id` - and puts `item` between them. Word splits a revision so when
+     * text is typed inside it: around the typist's `w:ins` with tracking on, around plain text with it
+     * off (`test/README.md` checks 20 and 21). False, with nothing changed but a run split at `at`,
+     * where the text there is not directly in the revision (in a hyperlink inside it, say): the caller
+     * then does what it did before.
+     */
+    insertBetweenHalves(at, item, nextId) {
+        this.splitAt(at);
+        const after = this.segments().find((s) => s.start >= at && s.revision);
+        const holder = after === null || after === void 0 ? void 0 : after.revision;
+        const index = holder && after ? holder.items.indexOf(after.runOwner[after.runIndex]) : -1;
+        if (!holder || index <= 0)
+            return false;
+        return this.splitHolderAround(holder, index, item, nextId);
+    }
+    /**
+     * Moves a revision's items from `index` on into a copy of it - its attributes, a new `w:id` - and
+     * puts `item` between the two; with nothing from `index` on, `item` just goes after the revision.
+     * False, with nothing changed, where the revision's items cannot be told apart from its attributes.
+     * Internal: `Range.insertContentControl` uses it to put a new control between the halves of the
+     * insertion it wraps part of (check 30).
+     */
+    splitHolderAround(holder, index, item, nextId) {
+        var _a;
+        const value = holder.value;
+        const itemsKey = Object.keys(value).find((key) => value[key] === holder.items);
+        if (!itemsKey)
+            return false;
+        const parent = (_a = holder.value.PARENT) !== null && _a !== void 0 ? _a : this.p;
+        const at = holder.owner.indexOf(holder.element) + 1;
+        const items = Array.isArray(item) ? item : [item];
+        if (index >= holder.items.length) {
+            holder.owner.splice(at, 0, ...items);
+            linkParents(items, parent);
+            return true;
+        }
+        const copy = {};
+        for (const [key, v] of Object.entries(value))
+            if (key !== itemsKey)
+                copy[key] = v;
+        copy.id = nextId();
+        copy[itemsKey] = holder.items.splice(index);
+        const second = { name: holder.element.name, value: copy };
+        holder.owner.splice(at, 0, ...items, second);
+        linkParents(copy[itemsKey], copy);
+        linkParents([...items, second], parent);
+        return true;
+    }
+    /**
+     * Puts `item` beside a revision rather than in it: after it, or before it - and then before the
+     * range start of a move whose range opens just there, so that text typed at the start of moved
+     * text is not inside the move (`test/README.md` check 20 case 03).
+     */
+    insertBesideRevision(holder, item, side) {
+        var _a, _b, _c;
+        let index = holder.owner.indexOf(holder.element) + (side === 'after' ? 1 : 0);
+        if (side === 'before' && (holder.kind === 'moveTo' || holder.kind === 'moveFrom')) {
+            const marker = holder.kind === 'moveTo' ? 'moveToRangeStart' : 'moveFromRangeStart';
+            while (index > 0 && ((_b = (_a = holder.owner[index - 1]) === null || _a === void 0 ? void 0 : _a.name) === null || _b === void 0 ? void 0 : _b.localPart) === marker)
+                index--;
+        }
+        const items = Array.isArray(item) ? item : [item];
+        holder.owner.splice(index, 0, ...items);
+        linkParents(items, (_c = holder.value.PARENT) !== null && _c !== void 0 ? _c : this.p);
+    }
+    /**
+     * A fresh annotation id for markup this paragraph writes itself: the package's counter when there
+     * is a package that keeps one, since a document has one id space; else one above every id in the
+     * story.
+     */
+    /** @internal `Comment` uses it to split an insertion at a comment's end. */
+    nextAnnotationId() {
+        const pkg = this.parentBody.package_;
+        if (pkg && typeof pkg.markupRoots === 'function' && 'annotationIdFloor' in pkg) {
+            return new ChangeTracker(pkg, 'TrackAll').nextId();
+        }
+        let root = this.p;
+        for (let o = this.p; o !== undefined; o = o.PARENT)
+            root = o;
+        return highestAnnotationId(root) + 1;
+    }
     /**
      * Text inserted at `at` as a `w:ins`. A run of this author's own that is already inside a
      * `w:ins` is extended rather than nested in another one, as Word does. `anchor` is the `w:del`
      * of a replacement, which the insertion must follow.
      */
-    insertTracked(tracker, at, text, anchor) {
-        var _a, _b, _c, _d, _e;
-        var _f;
+    insertTracked(tracker, at, text, anchor, prefer = 'before') {
+        var _a, _b, _c;
         if (anchor) {
             const rPr = copyRPr((_a = runsOf(anchor.element.value, { view: 'original' })[0]) === null || _a === void 0 ? void 0 : _a.value.rPr);
             const ins = tracker.ins([runOf([textItem(text)], rPr)]);
+            // A replacement inside another's revision - an insertion, moved text - leaves its w:del in
+            // that revision; the new text is not put in it too, but the revision split after the deletion
+            // and the text between the halves, as for anything typed in it (check 21; the editor's finding
+            // on 0.3.0, CR-002 section 37).
+            const holder = anchor.revision;
+            if (holder && this.splitHolderAround(holder, holder.items.indexOf(anchor.element) + 1, ins, () => tracker.nextId()))
+                return;
             anchor.owner.splice(anchor.owner.indexOf(anchor.element) + 1, 0, ins);
             linkParents(ins, anchor.parent);
             return;
@@ -795,7 +1025,8 @@ export class Paragraph {
         const segs = this.segments();
         const before = [...segs].reverse().find((s) => s.end <= at);
         const after = segs.find((s) => s.start >= at);
-        for (const [seg, side] of [[before, 'after'], [after, 'before']]) {
+        const sides = [[before, 'after'], [after, 'before']];
+        for (const [seg, side] of prefer === 'after' ? [...sides].reverse() : sides) {
             if (!seg || !tracker.ownInsertion(seg.revision))
                 continue;
             if (seg.editable) {
@@ -809,24 +1040,46 @@ export class Paragraph {
             }
             return;
         }
-        const neighbour = before !== null && before !== void 0 ? before : after;
+        const neighbour = prefer === 'after' ? after !== null && after !== void 0 ? after : before : before !== null && before !== void 0 ? before : after;
         tracker.assertEditable(neighbour === null || neighbour === void 0 ? void 0 : neighbour.revision);
         const rPr = copyRPr((_b = neighbour === null || neighbour === void 0 ? void 0 : neighbour.run.rPr) !== null && _b !== void 0 ? _b : (_c = runsOf(this.p)[0]) === null || _c === void 0 ? void 0 : _c.value.rPr);
         const ins = tracker.ins([runOf([textItem(text)], rPr)]);
+        this.placeInsertion(at, [ins], before, after, () => tracker.nextId(), prefer);
+    }
+    /**
+     * An insertion put at `at`, `before` and `after` being the segments either side of it once the runs
+     * are split there: never inside another's revision.
+     */
+    placeInsertion(at, items, before, after, nextId, prefer = 'before') {
+        var _a, _b;
+        var _c;
+        // Typed inside another's revision - a w:ins, a w:moveTo - the revision is split and the typist's
+        // w:ins goes between its halves, as Word writes it (test/README.md check 20 case 01, check 21's
+        // first run); before, it went to the revision's edge, putting the text in the wrong place.
+        if ((before === null || before === void 0 ? void 0 : before.revision) && (after === null || after === void 0 ? void 0 : after.revision) && before.revision.element === after.revision.element
+            && this.insertBetweenHalves(at, items, nextId)) {
+            return;
+        }
+        // at the start of a revision, beside it - and outside a move's range that opens there (case 03)
+        if (!before && (after === null || after === void 0 ? void 0 : after.revision)) {
+            this.insertBesideRevision(after.revision, items, 'before');
+            return;
+        }
+        const neighbour = prefer === 'after' ? after !== null && after !== void 0 ? after : before : before !== null && before !== void 0 ? before : after;
         if (neighbour) {
             const owner = neighbour.revision ? neighbour.revision.owner : neighbour.runOwner;
             const item = neighbour.revision ? neighbour.revision.element : neighbour.runOwner[neighbour.runIndex];
             const parent = (neighbour.revision ? neighbour.revision.value : neighbour.run);
-            owner.splice(owner.indexOf(item) + (neighbour === before ? 1 : 0), 0, ins);
-            linkParents(ins, (_d = parent.PARENT) !== null && _d !== void 0 ? _d : this.p);
+            owner.splice(owner.indexOf(item) + (neighbour === before ? 1 : 0), 0, ...items);
+            linkParents(items, (_a = parent.PARENT) !== null && _a !== void 0 ? _a : this.p);
         }
         else {
-            const content = ((_e = (_f = this.p).content) !== null && _e !== void 0 ? _e : (_f.content = []));
+            const content = ((_b = (_c = this.p).content) !== null && _b !== void 0 ? _b : (_c.content = []));
             if (at === 0)
-                content.unshift(ins);
+                content.unshift(...items);
             else
-                content.push(ins);
-            linkParents(ins, this.p);
+                content.push(...items);
+            linkParents(items, this.p);
         }
     }
     /**

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

@@ -91,7 +91,9 @@ export declare class Range {
      * `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). Only the hyperlinks
-     * the range touches are removed; before 0.2.1 every one in the paragraph was (section 25).
+     * the range touches are removed; before 0.2.1 every one in the paragraph was (section 25). An
+     * empty range is refused with a `GeneralException`, as Office JS refuses it (section 25, check 19):
+     * to change a link under a caret, set it on the link's whole range.
      *
      * 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
@@ -113,9 +115,9 @@ export declare class Range {
      */
     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.
+     * Whether this range touches a hyperlink's text: overlaps it, or for an empty range lies in it or
+     * at either end of it - Office JS reads a caret just after a link as in that link (check 19, case
+     * K; the start edge was not measured). A hyperlink holding no text touches nothing.
      */
     private touches;
     private touchesSpan;