@docx4j/core-ts 0.5.0 → 0.6.0

package/dist/model/content/Paragraph.mjs

@@ -1,26 +1,31 @@
 import { deepCopy, marshalString } from '@docx4j/generated-objects-ts';
 import { Docx4JException } from '../../opc/exceptions.mjs';
-import { r as textRun, t as textItem, br as breakItem } from '@docx4j/generated-objects-ts/builders/wml';
-import { segmentsOf, runsOf, runItemsOf, linkParents, textOf, textOfView, typeNameOf, W_NS, runOf, paragraphOf, revisionKindOf, objectInSpan, WHOLE } from './tree.mjs';
+import { NotSupportedError } from '../../office-js/errors.mjs';
+import { t as textItem, br as breakItem } from '@docx4j/generated-objects-ts/builders/wml';
+import { segmentsOf, runsOf, runItemsOf, inShowingPlaceholder, linkParents, typeNameOf, W_NS, runOf, paragraphOf, revisionKindOf, objectInSpan, WHOLE, isAlternateContent, selectedBranchOf, inBranch, assertOutsideBranch } from './tree.mjs';
 import { relationshipIdsIn, queueRelationshipRemovals } from './relationships.mjs';
 function withRPr(run, rPr) {
     if (rPr)
         run.value.rPr = rPr;
     return run;
 }
-import { Font } from './Font.mjs';
+import { Font, markHolderOf } from './Font.mjs';
 import { runFontSelectorOf } from '../fonts/lookup.mjs';
 import { Range } from './Range.mjs';
-import { searchPattern, matchesOf, expandReplacement } from './search.mjs';
+import { officeMatches, expandReplacement, paragraphMarkPieces, refuseMarkReplacement, refuseWildcardMarkReplacement } from './search.mjs';
 import { builtInOf, idOfBuiltIn, styleNameOf, styleIdOf } from './styles.mjs';
 import { cellOf } from './Table.mjs';
-import { ContentControl, collectRunControls } from './ContentControl.mjs';
-import { sdt as sdtOf, nextSdtId } from '@docx4j/generated-objects-ts/builders/wml';
+import { ContentControl, collectRunControls, controlViewOf, plainTextLinesOf, textForRunControl, assertControlHolds, controlsOfTypes, holdsOneParagraph, showsPlaceholderWhenMade, BLOCK_CONTROL } from './ContentControl.mjs';
+import { breakParagraphAt, BREAKABLE } from './spanEdits.mjs';
+import { endsCell, endsWithParagraph, wrappingCellOf } from './tableRules.mjs';
+import { dropExcluded, forWriter, linesOf, officeItems, oneParagraphRun, holdsElementCharacters } from './officeText.mjs';
+import { sdt as sdtOf, nextSdtId, sdtProperty } from '@docx4j/generated-objects-ts/builders/wml';
 import { controlIdScope, sdtKindFor, declareSdtExtensions } from '../customxml/insert.mjs';
 import { InlinePicture, picturesIn, addImage, writableWidthEmu } from './InlinePicture.mjs';
+import { showPicturePlaceholder } from '../customxml/picturePlaceholder.mjs';
 import { contentOf } from './ooxml.mjs';
 import { commentApi } from './comments.mjs';
-import { ChangeTracker, copyRPr, markDeleted, toDeletedText, highestAnnotationId, canonical, restorePPr, wrapInsertedRuns, markHolderInserted, pruneParagraphProperties } from './tracking.mjs';
+import { ChangeTracker, copyRPr, markDeleted, toDeletedText, highestAnnotationId, canonical, restorePPr, wrapInsertedRuns, markHolderInserted, pruneParagraphProperties, markEquationDeleted, equationRevisionIn } 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;
@@ -62,23 +67,57 @@ export class Paragraph {
     get p() {
         return this.element.value;
     }
+    /** @internal A view of another paragraph of this one's body, for a `Range` across paragraphs (CR-014). */
+    viewOf(element, container) {
+        return new Paragraph(element, container, this.parentBody);
+    }
+    /**
+     * @internal A range from this paragraph's start to the end of `last`, a later paragraph of the same story, with
+     * `last`'s mark where `mark` is set, or `endMark` in its place (CR-014 phase 1).
+     */
+    rangeTo(last, mark, endMark) {
+        return new Range(this, 0, last.text.length, true, mark, last.element === this.element ? undefined : last, endMark);
+    }
+    /** How many tables deep the paragraph is: 0 outside a table, 1 in a cell, 2 in a nested table's (Office JS `tableNestingLevel`). */
+    get tableNestingLevel() {
+        let level = 0;
+        for (let cell = this.parentTableCell; cell; cell = cell.parentTable.parentTableCell)
+            level++;
+        return level;
+    }
     get index() {
         return this.container.indexOf(this.element);
     }
-    /** The paragraph's text: runs joined, tabs as \t, breaks as \n; deleted text excluded. */
+    /**
+     * The paragraph's text as Office JS gives it in Word's default view (CR-012 phase 4, section 6.2):
+     * the accepted text, hidden text left out, in Word's characters (check 48: a note reference U+0002,
+     * a line break U+000B, a page break U+000C, a column break U+000E, a `w:cr` U+000D, the hyphens
+     * U+001E and U+001F, a symbol `(`, an equation as Word draws it). A kept `mc:AlternateContent`
+     * reads as its selected branch (check 49). Every offset a `Range` or `search` takes counts in it.
+     */
     get text() {
-        return textOf(this.p);
+        return this.segments().map((s) => s.text).join('');
     }
     /** Replaces the content with one run of the text, keeping the first run's formatting. */
     set text(value) {
         var _a;
+        this.assertWritable();
+        // one paragraph, its line breaks w:br and w:cr (CR-002 section 60 E2), or as a plain-text control takes them (F3)
+        const lines = this.blockControl ? plainTextLinesOf(this.blockControl) : undefined;
+        const mode = lines === 'multi' ? 'multi-line' : lines === 'single' ? 'single-line' : 'one-paragraph';
+        // in a block control showing its placeholder, the text in the placeholder's place (CR-002 section 63)
+        const placeholder = this.placeholderControl;
+        if (placeholder) {
+            placeholder.writePlaceholder(value, { lineBreaks: mode });
+            return;
+        }
         if (this.changeTracker) {
-            this.splice(0, this.text.length, value, 'before', WHOLE);
+            this.splice(0, this.text.length, value, 'before', WHOLE, mode);
             return;
         }
         const rPr = (_a = runsOf(this.p)[0]) === null || _a === void 0 ? void 0 : _a.value.rPr;
         this.releaseRelationships(this.p.content);
-        this.p.content = [withRPr(textRun(value), rPr ? deepCopy(rPr) : undefined)];
+        this.p.content = [oneParagraphRun(value, rPr ? deepCopy(rPr) : undefined, mode)];
         linkParents(this.p.content, this.p);
     }
     /**
@@ -86,7 +125,7 @@ export class Paragraph {
      * reads the document as it was before the tracked changes: `w:del` included, `w:ins` excluded.
      */
     getText(options) {
-        return (options === null || options === void 0 ? void 0 : options.view) === 'original' ? textOfView(this.p, options) : this.text;
+        return (options === null || options === void 0 ? void 0 : options.view) === 'original' ? this.segments({ view: 'original' }).map((s) => s.text).join('') : this.text;
     }
     /** The style id (w:pStyle; docx4j's name for it); 'Normal' when none is set. Extension: Office JS has `style` and `styleBuiltIn` only. */
     get styleId() {
@@ -227,24 +266,36 @@ export class Paragraph {
     else
         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).
+     * The runs' formatting: reads the *effective* properties of the runs holding the paragraph's text, `null` (or `''`,
+     * `Mixed`) where they differ, and the mark's where it has no text, as Office JS reads them (CR-002 section 59); writes
+     * direct formatting to every run (extension: `Font` is over runs, not the paragraph mark).
      */
     get font() {
         return this.getFont();
     }
-    /** `font`, with `{ direct: true }` for the direct formatting of the first run (extension). */
+    /** `font`, with `{ direct: true }` for the runs' direct formatting (extension). */
     getFont(options) {
-        const holders = () => runsOf(this.p).map((r) => r.value);
+        const holders = (write) => {
+            if (write) {
+                this.assertWritable();
+                return runsOf(this.p).map((r) => r.value);
+            }
+            // a read takes the runs of Paragraph.text, Word's default view, as a range over it does; with none, a placeholder's
+            // runs, which Word's font reads though its text doesn't (check 52 case 13, after Accept All: Word's bold filler)
+            const runs = this.getRange('Content').runs.map((r) => r.value);
+            return runs.length > 0 ? runs : runsOf(this.p).map((r) => r.value).filter((r) => inShowingPlaceholder(r));
+        };
+        const mark = () => markHolderOf(this.p);
         if ((options === null || options === void 0 ? void 0 : options.direct) === true)
-            return new Font(holders, () => this.fontTracking());
-        return new Font(holders, () => this.fontTracking(), (rPr) => this.parentBody.propertyResolver.getEffectiveRPr(rPr, this.p.pPr, this.cellContext), (rPr) => { var _a; return (_a = runFontSelectorOf(this.parentBody.package_)) === null || _a === void 0 ? void 0 : _a.asciiFontName(rPr); });
+            return new Font(holders, () => this.fontTracking(), undefined, undefined, mark);
+        return new Font(holders, () => this.fontTracking(), (rPr) => this.parentBody.propertyResolver.getEffectiveRPr(rPr, this.p.pPr, this.cellContext), (rPr) => { var _a; return (_a = runFontSelectorOf(this.parentBody.package_)) === null || _a === void 0 ? void 0 : _a.asciiFontName(rPr); }, mark, () => this.parentBody.propertyResolver.getThemeColors());
     }
     /** w14:paraId, the stable address Word gives paragraphs. */
     get paraId() {
         return this.p.paraId;
     }
     set paraId(id) {
+        this.assertWritable();
         if (id === undefined)
             delete this.p.paraId;
         else
@@ -264,6 +315,14 @@ export class Paragraph {
         collectRunControls(this.p, this.parentBody, out);
         return out;
     }
+    /**
+     * Office JS `getContentControls` (WordApi 1.5): the content controls `contentControls` lists, those of `options.types`
+     * where given. Word's `contentControls` lists rich-text controls only; this package's lists every kind, a recorded
+     * departure (CR-002 section 60 G1, check 55b), so this is how add-in code that asks for plain-text controls finds them.
+     */
+    getContentControls(options) {
+        return controlsOfTypes(this.contentControls, options);
+    }
     /**
      * The inline pictures in this paragraph, in order (Office JS Paragraph.inlinePictures): each
      * `w:drawing` whose `wp:inline` holds a `pic:pic`, in a run or in the selected branch of a kept
@@ -283,27 +342,55 @@ export class Paragraph {
     }
     /** Text inserted at the start, the end, or replacing the whole paragraph's text. */
     insertText(text, location) {
+        // in a block control showing its placeholder the text takes the placeholder's place wherever it is put (CR-002
+        // section 63; check 63's run 2, cases 7 to 9 and 33 to 35)
+        const placeholder = this.placeholderControl;
+        if (placeholder)
+            return placeholder.writePlaceholder(text);
         const length = this.text.length;
         if (location === 'Start')
             return this.splice(0, 0, text);
         if (location === 'End')
-            return this.splice(length, length, text);
+            return this.writeAtEnd(text);
+        // tracked, the insertion goes first, before the deletion, as a range's Replace writes it and Word wrote this one
+        // (check 63 cases 45 and 52; CR-002 section 63 D3)
+        if (this.changeTracker && length > 0)
+            return this.getRange('Content').insertText(text, 'Replace');
         return this.splice(0, length, text, 'before', WHOLE);
     }
-    /** A new paragraph of the text before or after this one, with this paragraph's properties (as Word). */
+    /**
+     * A new paragraph of the text before or after this one, with this paragraph's properties (as Word). Beside the only
+     * paragraph of a block control showing its placeholder it goes outside the control, as Word's went, and the control
+     * stays at block level (CR-002 section 63, D6 (b); check 63 cases 10, 11, 36 and 37).
+     */
     insertParagraph(text, location) {
+        var _a, _b;
+        this.assertWritable();
         const pPr = this.p.pPr ? deepCopy(this.p.pPr) : undefined;
         if (pPr) {
             delete pPr.rPr;
             delete pPr.sectPr;
             delete pPr.pPrChange;
         }
-        const el = paragraphOf(text === '' ? [] : [textRun(text)], pPr);
+        const run = oneParagraphRun(text); // E2
+        const el = paragraphOf(((_a = run.value.content) === null || _a === void 0 ? void 0 : _a.length) ? [run] : [], pPr);
+        const control = this.blockControl;
+        if ((control === null || control === void 0 ? void 0 : control.isShowingPlaceholder) && holdsOneParagraph(control)) {
+            // the body holding the control: this paragraph's is the control's content
+            const owner = (_b = control.element.value.PARENT) !== null && _b !== void 0 ? _b : this.parentBody.container;
+            return this.parentBody.sub(owner).insertElement(el, location, { element: control.element, container: control.container });
+        }
         return this.parentBody.insertElement(el, location, this);
     }
+    /** The block-level control holding this paragraph directly while it shows its placeholder (CR-002 section 63). */
+    get placeholderControl() {
+        const control = this.blockControl;
+        return (control === null || control === void 0 ? void 0 : control.showsPlaceholderContent) ? control : undefined;
+    }
     insertBreak(type, location) {
         var _a;
         var _b;
+        this.assertWritable();
         const brk = breakItem(type === 'Page' ? 'page' : undefined);
         if (location === 'Before' || location === 'After') {
             const p = this.insertParagraph('', location);
@@ -331,11 +418,15 @@ export class Paragraph {
     insertInlinePictureFromBase64(base64, location, options) {
         var _a;
         var _b;
+        this.assertWritable();
         const part = this.parentBody.part;
         if (!part)
             throw new Docx4JException('This body has no part, so an image cannot be related to it');
-        const { run, drawing } = addImage(part, base64, this.parentBody.container, writableWidthEmu(this.parentBody.container), options);
         const tracker = this.changeTracker;
+        // refused before the image part is added, not after (CR-012 section 12.4)
+        if (location === 'Replace' && tracker)
+            this.assertPlaceable(0, this.text.length, 'replace');
+        const { run, drawing } = addImage(part, base64, this.parentBody.container, writableWidthEmu(this.parentBody.container), options);
         // under tracking the picture is an insertion, and what it replaces is deleted as insertText's is
         if (location === 'Replace' && tracker)
             this.splice(0, this.text.length, '', 'before', WHOLE);
@@ -360,6 +451,7 @@ export class Paragraph {
      */
     async insertOoxml(ooxml, location) {
         var _a, _b;
+        this.assertWritable();
         const preprocess = (_a = this.parentBody.package_) === null || _a === void 0 ? void 0 : _a.loadOptions.preprocessor;
         const elements = await contentOf(ooxml, { preprocess: preprocess ? (doc) => preprocess(doc) : undefined, target: this.parentBody.part });
         if (elements.length === 0)
@@ -370,12 +462,12 @@ export class Paragraph {
             return [this];
         }
         if (location === 'Replace') {
-            const inserted = this.parentBody.insertElement(elements, 'Before', this);
+            const inserted = this.parentBody.insertElement(elements, 'Before', this, 'GeneralException', this.element);
             void inserted;
             this.delete();
         }
         else {
-            this.parentBody.insertElement(elements, location === 'Start' ? 'Before' : location === 'End' ? 'After' : location, this);
+            this.parentBody.insertElement(elements, location === 'Start' ? 'Before' : location === 'End' ? 'After' : location, this, 'GeneralException');
         }
         return elements.map((el) => typeNameOf(el) === 'org_docx4j_wml.P'
             ? new Paragraph(el, this.container, this.parentBody)
@@ -383,6 +475,10 @@ export class Paragraph {
     }
     /** Matches within this paragraph. */
     search(text, options) {
+        // Word's paragraph mark, ^p, is searched in the paragraph's whole range, which holds its mark (CR-014 phase 3), and so
+        // is a wildcard query, whose ? or class matches the mark too (check 59; CR-002 section 32, K7)
+        if ((options === null || options === void 0 ? void 0 : options.matchWildcards) || (!(options === null || options === void 0 ? void 0 : options.matchRegExp) && paragraphMarkPieces(text)))
+            return this.getRange('Whole').search(text, options);
         return this.searchMatches(text, options).map((m) => m.range);
     }
     /**
@@ -391,8 +487,8 @@ export class Paragraph {
      * 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 }));
+        return officeMatches(this.segments({ objects: true }), text, options)
+            .map(({ start, end, match }) => ({ range: new Range(this, start, end), match }));
     }
     /**
      * Replaces every match of `find` with `replace`, last match first so that the offsets of the
@@ -400,6 +496,9 @@ export class Paragraph {
      * the package's `changeTrackingMode` is on.
      */
     replaceText(find, replace, options) {
+        refuseMarkReplacement('Paragraph', find, options);
+        if (options === null || options === void 0 ? void 0 : options.matchWildcards)
+            refuseWildcardMarkReplacement('Paragraph', this.search(find, options));
         const matches = this.searchMatches(find, options);
         for (let i = matches.length - 1; i >= 0; i--) {
             const { range, match } = matches[i];
@@ -414,24 +513,51 @@ export class Paragraph {
     /**
      * The paragraph's range: 'Whole' and 'Content' hold its whole content, the pictures at its start and
      * end among them, so deleting it deletes them (CR-002 section 48); 'Start' and 'End' are collapsed.
+     * 'Whole' holds the paragraph's mark too, so its `text` ends with `markText`, as Office JS's does
+     * (check 48); 'Content' ends with the paragraph's text.
      */
     getRange(location = 'Whole') {
         const length = this.text.length;
         if (location === 'Start')
             return new Range(this, 0, 0);
         if (location === 'End')
-            return new Range(this, length, length);
-        return new Range(this, 0, length, true);
+            return new Range(this, length, length).atEndOf('End');
+        const range = new Range(this, 0, length, true, location === 'Whole');
+        return location === 'Content' ? range.atEndOf('Content') : range;
+    }
+    /**
+     * The character Office JS gives for this paragraph's mark at the end of its 'Whole' range (check 48):
+     * `\t` for the last paragraph of a table cell, the cell's end; nothing for a mark tracked as deleted, which
+     * Word's default view doesn't show (CR-012 section 19, check 58); and `\r` for any other.
+     */
+    get markText() {
+        var _a, _b;
+        if (lastInCell(this.p))
+            return '\t';
+        return ((_b = (_a = this.p.pPr) === null || _a === void 0 ? void 0 : _a.rPr) === null || _b === void 0 ? void 0 : _b.del) !== undefined ? '' : '\r';
     }
     /**
      * Removes the paragraph from its container. While the package tracks changes, the content
      * becomes a `w:del` and the mark is marked deleted (`w:pPr/w:rPr/w:del`) instead, unless the
      * whole paragraph was this author's own insertion, which Word simply takes back.
+     * The paragraph a table cell ends with, as Word reads it, stays where removing it would leave the
+     * cell without one, emptied, its properties kept; tracked, its mark is never marked deleted, as Word
+     * keeps a cell's last paragraph (check 52, cases 88 to 91; CR-002 section 55.6).
      */
     delete() {
+        this.remove(true);
+    }
+    /**
+     * `delete()`; with `keepCellEnd` false a cell's last paragraph goes as any other, for `Body.clearContent`'s
+     * callers, which put their own paragraph in next.
+     * @internal
+     */
+    remove(keepCellEnd) {
+        this.assertWritable();
+        const cellEnd = keepCellEnd && endsCell(this.p);
         const tracker = this.changeTracker;
         if (tracker) {
-            this.trackedDelete(tracker);
+            this.trackedDelete(tracker, cellEnd);
             return;
         }
         const i = this.index;
@@ -439,8 +565,17 @@ export class Paragraph {
             return;
         this.container.splice(i, 1);
         this.releaseRelationships(this.element);
+        if (cellEnd && !this.cellStillEnds()) {
+            this.p.content = [];
+            this.container.splice(i, 0, this.element);
+        }
+    }
+    /** Whether the cell this paragraph was in ends with a paragraph without it, as Word reads it (CR-002 section 55). */
+    cellStillEnds() {
+        var _a;
+        return endsWithParagraph((_a = wrappingCellOf(this.p.PARENT)) === null || _a === void 0 ? void 0 : _a.content);
     }
-    trackedDelete(tracker) {
+    trackedDelete(tracker, cellEnd) {
         var _a, _b;
         if (markDeleted(this.p))
             throw new Docx4JException('This paragraph is already marked deleted');
@@ -451,10 +586,17 @@ export class Paragraph {
         const ownMark = (rPr === null || rPr === void 0 ? void 0 : rPr.ins) !== undefined && rPr.ins.author === tracker.author;
         if (ownMark && ((_b = this.p.content) !== null && _b !== void 0 ? _b : []).length === 0) {
             const i = this.index;
-            if (i >= 0)
+            if (i >= 0) {
                 this.container.splice(i, 1);
+                if (!cellEnd || this.cellStillEnds())
+                    return;
+                this.container.splice(i, 0, this.element);
+            }
             return;
         }
+        // a cell's last mark: Word deletes the paragraph's text and never marks the mark (check 52, cases 90 and 91)
+        if (cellEnd)
+            return;
         tracker.markParagraphDeleted(this.p);
         // Word, deleting a paragraph mark ALONE under tracking, gives the next paragraph this one's
         // properties as a w:pPrChange (CR-002 section 38 item 2, the editor's measure-word15.docx), so
@@ -469,13 +611,14 @@ export class Paragraph {
      * what the cells of a deleted table row need (a `w:tc` must keep a block-level child, and Word
      * writes `w:del` around every run and `w:pPr/w:rPr/w:del` on every mark inside a deleted row).
      * The same primitives `delete()` uses, without its "take back my own insertion" step.
-     * Does nothing when the mark is already deleted.
+     * A mark already deleted is left as it is, and the text is deleted still: a paragraph another author's
+     * deletion ended keeps text a range's deletion across it must take (CR-014 phase 2).
      */
     markDeletedInPlace(tracker) {
-        if (markDeleted(this.p))
-            return;
+        this.assertWritable();
         this.deleteText(tracker, 0, this.text.length, WHOLE);
-        tracker.markParagraphDeleted(this.p);
+        if (!markDeleted(this.p))
+            tracker.markParagraphDeleted(this.p);
     }
     /**
      * Queues the relationships that content removed outright referenced (a picture's image, a link's
@@ -512,6 +655,7 @@ export class Paragraph {
     pPr() {
         var _a, _b;
         var _c;
+        this.assertWritable();
         const pPr = ((_a = (_c = this.p).pPr) !== null && _a !== void 0 ? _a : (_c.pPr = { TYPE_NAME: 'org_docx4j_wml.PPr' }));
         linkParents(pPr, this.p);
         (_b = this.changeTracker) === null || _b === void 0 ? void 0 : _b.recordPPrChange(pPr);
@@ -590,9 +734,49 @@ export class Paragraph {
                 ownInsertions.add(seg.run);
         return { tracker, ownInsertions };
     }
-    /** The text segments (w:t, w:tab, ...) with their offsets; `{ objects: true }` adds the pictures. */
+    /**
+     * The text segments (w:t, w:tab, ...) with their offsets in `text`; `{ objects: true }` adds the
+     * pictures and the hidden runs' items.
+     */
     segments(options) {
-        return segmentsOf(this.p, options);
+        return segmentsOf(this.p, { hidden: this.hiddenRuns(), ...options });
+    }
+    /**
+     * True for a paragraph in a text box (`w:txbxContent`), at a `textbox:` address (CR-012 D4). Such a view
+     * reads as any paragraph does and is read-only (D5): every write throws `NotSupportedError`.
+     */
+    get inTextBox() {
+        let o = this.p.PARENT;
+        for (let guard = 0; o && guard < 256; guard++, o = o.PARENT) {
+            if (o.TYPE_NAME === 'org_docx4j_wml.CTTxbxContent')
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Refuses a write to a paragraph in a text box (CR-012 D5): a box is in each branch of its
+     * `mc:AlternateContent`, `wps:txbx` in the Choice and `v:textbox` in the Fallback, and nothing maps the
+     * one's paragraphs to the other's, so an edit could not reach every branch as CR-010's D2 has mutators do.
+     * And a write to a paragraph in a branch of a kept `mc:AlternateContent` at block, row or cell level
+     * (CR-013 D4), for the same reason. Internal: the content API's mutators call it first.
+     */
+    assertWritable() {
+        if (this.inTextBox) {
+            throw new NotSupportedError('Paragraph', 'edit', 'this paragraph is in a text box, whose paragraphs are read-only (CR-012 D5): '
+                + "writes into a text box would have to reach its other branch's box too, which nothing maps yet");
+        }
+        assertOutsideBranch(this.p, 'Paragraph');
+    }
+    /**
+     * True for a paragraph in the selected branch of a kept `mc:AlternateContent` at block, row or cell
+     * level, which readers see as Word does (CR-013 phase 2). Such a view is read-only (D4).
+     */
+    get inBranch() {
+        return inBranch(this.p);
+    }
+    /** Which of this paragraph's runs are hidden: a run's own `w:vanish`, else its styles' (CR-012 phase 4). */
+    hiddenRuns() {
+        return this.parentBody.hiddenRuns(this.p);
     }
     /**
      * Replaces the text in [start, end) with `text` and returns the range of the inserted text.
@@ -604,13 +788,313 @@ export class Paragraph {
      * says the span holds (`WHOLE` for a paragraph's whole content), so a span of no text can still
      * delete a picture (CR-002 section 48).
      */
-    splice(start, end, text, prefer = 'before', edges) {
-        var _a, _b, _c, _d, _e, _f;
-        var _g;
+    splice(start, end, text, prefer = 'before', edges, lineBreaks) {
+        this.assertWritable();
+        // text into a block control showing its placeholder takes the placeholder's place (CR-002 section 63)
+        const placeholder = text === '' ? undefined : this.placeholderControl;
+        if (placeholder)
+            return placeholder.writePlaceholder(text, lineBreaks ? { lineBreaks } : {});
+        // every text write into a bound control writes its node (CR-002 section 63, D7), as ContentControl.insertText did
+        const bound = this.boundControlsAt(start, end);
+        const range = this.spliceWrite(start, end, text, prefer, edges, lineBreaks);
+        for (const control of bound)
+            control.syncBoundNode();
+        return range;
+    }
+    /**
+     * The controls bound by `w:dataBinding` that [start, end) is in: those holding the paragraph, and the run-level ones
+     * holding text there.
+     */
+    boundControlsAt(start, end, ancestorsOnly = false) {
+        const out = [];
+        const seen = new Set();
+        const add = (o) => {
+            const tn = o.TYPE_NAME;
+            if (tn === undefined || !SDT_VALUE_TYPES.has(tn) || seen.has(o))
+                return;
+            seen.add(o);
+            if (sdtProperty(o.sdtPr, 'dataBinding') === undefined)
+                return;
+            try {
+                out.push(controlViewOf(o, this.parentBody));
+            }
+            catch {
+                // not where its PARENT says: nothing to write
+            }
+        };
+        for (let o = this.p.PARENT; o; o = o.PARENT)
+            add(o);
+        if (ancestorsOnly || !holdsBoundRunControl(this.p))
+            return out;
+        for (const seg of this.segments({ objects: true })) {
+            if (seg.end < start || seg.start > end)
+                continue;
+            for (let o = seg.run.PARENT; o && o !== this.p; o = o.PARENT)
+                add(o);
+        }
+        return out;
+    }
+    /**
+     * @internal Text written at the paragraph's End by Office JS's routes to it: `insertText('End')`, its End range at any
+     * location, its Content range's End and After, and so a body's or a cell's `insertText('End')` (CR-002 sections 63.24
+     * to 63.27; checks 69 and 70). As Word writes it (D12): after everything the paragraph holds, into none of it - a
+     * run-level control, a link, a revision, a field, a bookmark's or a comment's markers, a text box - in a run of its
+     * own, or the last run extended. The text takes the last item's run properties where that item is a run holding text,
+     * so after a hidden run it is hidden and its range reads nothing (D13); otherwise it has none, and with `plain` (the End
+     * range's After, D14) none either. Word's proofing marks, `w:proofErr`, are no item (a choice: Word redoes them).
+     * Tracked, the run is a `w:ins`, or joins this author's own `w:ins` where one ends the paragraph. A line break makes
+     * paragraphs, as `splice` does (CR-002 section 60 E1); text so broken after a hidden run is written visible (a choice,
+     * unmeasured).
+     */
+    writeAtEnd(text, plain = false) {
+        var _a, _b;
+        var _c;
+        this.assertWritable();
+        const placeholder = this.placeholderControl;
+        if (placeholder)
+            return placeholder.writePlaceholder(text);
+        const length = this.text.length;
+        text = dropExcluded(text);
+        if (text === '')
+            return new Range(this, length, length);
+        let mode = 'paragraphs';
+        const lines = this.blockControl ? plainTextLinesOf(this.blockControl) : undefined;
+        if (lines)
+            mode = lines === 'multi' ? 'multi-line' : 'single-line'; // section 61 item 3, F3
+        text = forWriter(text, mode);
+        const broken = mode === 'paragraphs' && /[\r\n]/.test(text) ? linesOf(text) : undefined;
+        const joined = broken ? broken.join('') : text;
+        if (joined === '' && !broken)
+            return new Range(this, length, length);
+        const bound = this.boundControlsAt(length, length, true);
+        const content = ((_a = (_c = this.p).content) !== null && _a !== void 0 ? _a : (_c.content = []));
+        let at = content.length;
+        while (at > 0 && typeNameOf(content[at - 1]) === 'org_docx4j_wml.ProofErr')
+            at--;
+        const last = at > 0 ? content[at - 1] : undefined;
+        const textRun = (item) => {
+            var _a;
+            if (!item || typeNameOf(item) !== 'org_docx4j_wml.R')
+                return undefined;
+            const run = item.value;
+            return ((_a = run.content) !== null && _a !== void 0 ? _a : []).some((c) => { var _a; return ((_a = c.name) === null || _a === void 0 ? void 0 : _a.localPart) === 't'; }) ? run : undefined;
+        };
+        const hidden = this.hiddenRuns();
+        // the run whose properties the text takes, and which it may extend: a run holding text, unless `plain`
+        let source = plain ? undefined : textRun(last);
+        if (source && broken && hidden(source))
+            source = undefined;
+        const items = officeItems(joined);
+        const tracker = this.changeTracker;
+        let written;
+        const own = tracker && last && typeNameOf(last) === 'org_docx4j_wml.RunIns' && tracker.ownInsertion({ kind: 'ins', value: last.value });
+        if (items.length === 0) {
+            // nothing but line breaks: only the paragraphs they make
+        }
+        else if (own) {
+            // this author's own insertion ends the paragraph: the text joins it, after its last run, in that run's look
+            const value = last.value;
+            const holder = (_b = runItemsOf(value)) !== null && _b !== void 0 ? _b : (value.customXmlOrSmartTagOrSdt = []);
+            const inner = plain ? undefined : textRun(holder[holder.length - 1]);
+            written = this.appendTo(holder, inner, items, value);
+        }
+        else if (tracker) {
+            const ins = tracker.ins([runOf(items, copyRPr(source === null || source === void 0 ? void 0 : source.rPr))]);
+            content.splice(at, 0, ins);
+            linkParents(ins, this.p);
+            written = runsOf(ins.value)[0].value;
+        }
+        else {
+            written = this.appendTo(content, source, items, this.p, at);
+        }
+        for (const control of bound)
+            control.syncBoundNode();
+        if (broken) {
+            const offsets = [];
+            let end = length;
+            for (const line of broken.slice(0, -1))
+                offsets.push(end += line.length);
+            const { first, last: tail } = breakParagraphAt(this, offsets);
+            return new Range(first, length, broken[broken.length - 1].length, false, false, tail);
+        }
+        return written && hidden(written) ? new Range(this, length, length) : new Range(this, length, length + joined.length);
+    }
+    /**
+     * `items` put at `at` in `list` (its end by default): onto the end of `run`, which is in `list` right before `at`,
+     * merging into its last `w:t`, or as a new run in its properties where `run` is undefined. Returns the run written.
+     */
+    appendTo(list, run, items, parent, at = list.length) {
+        var _a, _b, _c, _d, _e;
+        if (run) {
+            const own = ((_a = run.content) !== null && _a !== void 0 ? _a : (run.content = []));
+            const tail = own[own.length - 1];
+            const head = items[0];
+            if (((_b = tail === null || tail === void 0 ? void 0 : tail.name) === null || _b === void 0 ? void 0 : _b.localPart) === 't' && ((_c = head === null || head === void 0 ? void 0 : head.name) === null || _c === void 0 ? void 0 : _c.localPart) === 't') {
+                setText(tail.value, ((_d = tail.value.value) !== null && _d !== void 0 ? _d : '') + ((_e = head.value.value) !== null && _e !== void 0 ? _e : ''));
+                items = items.slice(1);
+            }
+            own.push(...items);
+            linkParents(items, run);
+            return run;
+        }
+        const added = runOf(items);
+        list.splice(at, 0, added);
+        linkParents(added, parent);
+        return added.value;
+    }
+    /** `splice`'s write. */
+    spliceWrite(start, end, text, prefer, edges, lineBreaks) {
+        // Office JS's characters written back (CR-002 section 60): the characters XML 1.0 excludes go (E3), a line feed or
+        // carriage return is a paragraph break (E1) unless the writer or the control takes it otherwise, and every
+        // character that is an element is written as it (D1)
+        text = dropExcluded(text);
+        if (text === '')
+            return this.spliceText(start, end, text, prefer, edges);
+        const from = Math.max(0, Math.min(start, this.text.length));
+        const landing = this.landingSegment(from, prefer, end > from);
+        const runControl = this.runControlOf(landing);
+        let mode = lineBreaks !== null && lineBreaks !== void 0 ? lineBreaks : 'paragraphs';
+        if (runControl) {
+            text = textForRunControl(runControl, text); // F4 and F3
+        }
+        else if (lineBreaks === undefined) {
+            const lines = this.blockControl ? plainTextLinesOf(this.blockControl) : undefined;
+            if (lines)
+                mode = lines === 'multi' ? 'multi-line' : 'single-line'; // section 61 item 3, F3
+        }
+        text = forWriter(text, mode);
+        if (mode === 'paragraphs' && /[\r\n]/.test(text))
+            return this.spliceLines(start, end, linesOf(text), prefer, edges, landing);
+        const range = this.spliceText(start, end, text, prefer, edges);
+        this.writeElements(range.start, range.start + text.length);
+        return range;
+    }
+    /**
+     * Text of several lines put in place of [start, end) as Word's insertText puts it (CR-002 section 60 E1): the lines'
+     * text, then a paragraph break after each line but the last, the paragraphs keeping this one's properties; tracked,
+     * each new mark inserted. Refused before anything changes where a paragraph can't be split there.
+     */
+    spliceLines(start, end, lines, prefer, edges, landing) {
+        this.assertBreakable(landing);
+        const joined = lines.join('');
+        const range = this.spliceText(start, end, joined, prefer, edges);
+        const from = range.start;
+        this.writeElements(from, from + joined.length);
+        const offsets = [];
+        let at = from;
+        for (const line of lines.slice(0, -1))
+            offsets.push(at += line.length);
+        const { first, last } = breakParagraphAt(this, offsets);
+        return new Range(first, from, lines[lines.length - 1].length, false, false, last);
+    }
+    /** @internal Refuses, before anything changes, a paragraph break at `at` where none can be made (E1; `Range`'s Replace across paragraphs). */
+    assertBreakableAt(at, prefer) {
+        this.assertBreakable(this.landingSegment(at, prefer));
+    }
+    /**
+     * The segment text put at `at` goes into, as `spliceText` chooses it: a replacement's, the one holding the first
+     * replaced character; else the one containing `at`, else the nearer neighbour.
+     */
+    landingSegment(at, prefer, replacing = false) {
+        const segs = this.segments();
+        if (replacing) {
+            const first = segs.find((s) => s.start <= at && at < s.end);
+            if (first)
+                return first;
+        }
+        const containing = segs.find((s) => s.editable && s.start < at && at < s.end);
+        const ending = segs.find((s) => s.editable && s.end === at);
+        const starting = segs.find((s) => s.editable && s.start === at);
+        return containing !== null && containing !== void 0 ? containing : (prefer === 'after' ? starting !== null && starting !== void 0 ? starting : ending : ending !== null && ending !== void 0 ? ending : starting);
+    }
+    /** The run-level content control a segment's run is in, the innermost, as a view; undefined for none. */
+    runControlOf(seg) {
+        var _a;
+        for (let o = (_a = seg === null || seg === void 0 ? void 0 : seg.run) === null || _a === void 0 ? void 0 : _a.PARENT; o && o !== this.p; o = o.PARENT) {
+            if (o.TYPE_NAME === 'org_docx4j_wml.SdtRun')
+                return controlViewOf(o, this.parentBody);
+        }
+        return undefined;
+    }
+    /** The block-level content control holding this paragraph directly, as a view; undefined for none. */
+    get blockControl() {
+        const content = this.p.PARENT;
+        const sdt = (content === null || content === void 0 ? void 0 : content.TYPE_NAME) === 'org_docx4j_wml.SdtContentBlock' ? content.PARENT : undefined;
+        return (sdt === null || sdt === void 0 ? void 0 : sdt.TYPE_NAME) === 'org_docx4j_wml.SdtBlock' ? controlViewOf(sdt, this.parentBody) : undefined;
+    }
+    /**
+     * Refuses, before anything changes, a paragraph break where the text lands inside something a paragraph can't be
+     * split in: a content control, an equation, a kept mc:AlternateContent (CR-002 section 60 E1, as `splitParagraph`
+     * refuses one). A field's result is split: a complex field's runs across the paragraphs, a `w:fldSimple` made a
+     * complex field first (section 62.2 D1).
+     */
+    assertBreakable(seg) {
+        var _a;
+        if (!seg)
+            return;
+        const refuse = (what) => {
+            throw new NotSupportedError('Paragraph', 'insertText', `a line feed or carriage return is a paragraph break (CR-002 section 60, E1), `
+                + `and this text goes inside ${what}, which can't be cut in two`);
+        };
+        if (seg.alternate || seg.math)
+            refuse('an equation or an mc:AlternateContent');
+        for (let o = seg.run.PARENT; o && o !== this.p; o = o.PARENT) {
+            const tn = (_a = o.TYPE_NAME) !== null && _a !== void 0 ? _a : '';
+            if (!BREAKABLE.has(tn))
+                refuse(`a ${tn.replace('org_docx4j_wml.', '')}`);
+        }
+    }
+    /**
+     * The characters of [from, to) that are elements written as the elements they read as (CR-002 section 60 D1), each
+     * in its run where it stood: a w:t holding one is cut around it. Characters outside the span are left as they are.
+     */
+    writeElements(from, to) {
+        var _a;
+        if (to <= from)
+            return;
+        for (const seg of this.segments().reverse()) {
+            if (!seg.editable || seg.end <= from || seg.start >= to)
+                continue;
+            const value = seg.text;
+            const a = Math.max(0, from - seg.start);
+            const b = Math.min(value.length, to - seg.start);
+            const inside = value.substring(a, b);
+            if (!holdsElementCharacters(inside))
+                continue;
+            const items = [
+                ...(a > 0 ? [textItem(value.substring(0, a))] : []),
+                ...officeItems(inside),
+                ...(b < value.length ? [textItem(value.substring(b))] : []),
+            ];
+            const parent = (_a = seg.item.value.PARENT) !== null && _a !== void 0 ? _a : seg.run;
+            seg.owner.splice(seg.index, 1, ...items);
+            linkParents(items, parent);
+        }
+    }
+    /**
+     * The first run's properties, for text with no run beside it to take its look from; none where that run is hidden,
+     * so that text put into a paragraph whose every run is hidden can be seen (CR-002 section 60: the text was hidden
+     * with it, so read as nothing, and its characters escaped the map).
+     */
+    visibleFirstRunRPr() {
+        var _a;
+        const first = (_a = runsOf(this.p)[0]) === null || _a === void 0 ? void 0 : _a.value;
+        return first && !this.hiddenRuns()(first) ? first.rPr : undefined;
+    }
+    /** `splice` before section 60: the text put in as it is, as one stretch of a w:t's text. */
+    spliceText(start, end, text, prefer = 'before', edges) {
+        var _a, _b, _c, _d, _e;
+        var _f;
         const length = this.text.length;
         start = Math.max(0, Math.min(start, length));
         end = Math.max(start, Math.min(end, length));
         const tracker = this.changeTracker;
+        this.assertPlaceable(start, end, tracker === undefined ? false : text.length > 0 ? 'replace' : 'delete');
+        // a run-level control showing its placeholder that the span holds whole goes with it, as Word takes one; tracked,
+        // `deleteText` marks it deleted (CR-002 section 63, D3; check 63 cases 19, 20 and 26)
+        if (!tracker && (end > start || edges))
+            for (const control of this.placeholderControlsIn(start, end, edges))
+                control.takeWhole();
         if (tracker) {
             // a replacement is the w:del first and the w:ins after it, as Word writes one
             const deletions = end > start || edges ? this.deleteText(tracker, start, end, edges) : [];
@@ -621,14 +1105,16 @@ export class Paragraph {
         let segs = this.segments();
         let inserted = false;
         const objects = this.segments({ objects: true }).filter((s) => s.object && objectInSpan(s.start, start, end, edges));
+        // a comment's reference in the span goes with the text, and its comment with it (CR-014 section 12.6)
+        const references = end > start || edges ? this.commentReferencesIn(start, end, edges) : [];
         // 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, '', prefer, edges);
-            return this.splice(start, start, text);
+            this.spliceText(start, end, '', prefer, edges);
+            return this.spliceText(start, start, text);
         }
-        if (end > start || objects.length > 0) {
+        if (end > start || objects.length > 0 || references.length > 0) {
             // 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);
             const toRemove = [];
@@ -656,6 +1142,13 @@ export class Paragraph {
                 if (i >= 0)
                     seg.owner.splice(i, 1);
             }
+            removeEmptiedAlternates([...toRemove, ...objects]);
+            for (const { run, owner, id } of references) {
+                const i = owner.indexOf(run);
+                if (i >= 0)
+                    owner.splice(i, 1);
+                this.queueCommentRemoval(id);
+            }
             this.releaseRelationships(objects.map((seg) => seg.item));
             if (inserted && text.length > 0) {
                 this.removeEmptyRuns();
@@ -696,7 +1189,7 @@ export class Paragraph {
                 const before = [...segs].reverse().find((s) => s.end <= start);
                 const after = segs.find((s) => s.start >= start);
                 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 firstRun = this.visibleFirstRunRPr();
                 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 (neighbour === before && before)
@@ -704,7 +1197,7 @@ export class Paragraph {
                 else if (after)
                     after.runOwner.splice(after.runIndex, 0, run);
                 else {
-                    const content = ((_f = (_g = this.p).content) !== null && _f !== void 0 ? _f : (_g.content = []));
+                    const content = ((_e = (_f = this.p).content) !== null && _e !== void 0 ? _e : (_f.content = []));
                     if (start === 0)
                         content.unshift(run);
                     else
@@ -722,8 +1215,10 @@ export class Paragraph {
     insertItemsAt(offset, items) {
         var _a, _b, _c, _d;
         var _e;
+        this.assertWritable();
         if (items.length === 0)
             return;
+        this.assertPlaceable(offset, offset, false);
         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
@@ -753,18 +1248,46 @@ export class Paragraph {
     /** Splits the run at a text offset so that [offset, ...) begins a run; returns nothing when the offset is already a boundary. */
     splitAt(offset) {
         var _a;
+        this.assertWritable();
+        this.assertPlaceable(offset, offset, false);
         const seg = this.segments().find((s) => s.editable && s.start < offset && offset < s.end);
         if (!seg)
             return;
         const at = offset - seg.start;
         const t = seg.item.value;
         const head = seg.text.substring(0, at);
-        const tail = seg.text.substring(at);
+        const tail = textItem(seg.text.substring(at));
         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.owner.splice(seg.index + 1, 0, tail);
+        linkParents(tail, (_a = t.PARENT) !== null && _a !== void 0 ? _a : seg.run);
+        this.splitRunAtItem(seg, seg.owner, seg.index + 1);
+    }
+    /**
+     * Splits `seg`'s run so that the items of `owner` from `index` on begin a run of their own, behind it.
+     * `owner` is the run's content, or the selected branch of a run-level `mc:AlternateContent` in it
+     * (CR-012 section 12.2): a run holds the element whole, so the branch splits with it, as the editor's
+     * ED-009 section 3.4 has it. The first piece keeps the element, its other branches as they were; the
+     * second gets an element of its own, the same branches in the same order with the same `Requires`, the
+     * selected one holding the rest of its items and the others empty, so that a reader taking any branch
+     * takes the same one in both. The run's items after the element go with the second piece.
+     */
+    splitRunAtItem(seg, owner, index) {
+        var _a, _b;
+        const alternate = ((_a = seg.alternate) === null || _a === void 0 ? void 0 : _a.level) === 'run' && owner === seg.alternate.branch ? seg.alternate : undefined;
+        let moved;
+        if (alternate) {
+            const piece = alternatePiece(alternate, owner.splice(index));
+            const at = alternate.owner.indexOf(alternate.element);
+            moved = [piece, ...alternate.owner.splice(at + 1)];
+        }
+        else {
+            moved = owner.splice(index);
+        }
+        if (moved.length === 0)
+            return;
+        const second = runOf(moved, seg.run.rPr ? deepCopy(seg.run.rPr) : undefined);
         seg.runOwner.splice(seg.runIndex + 1, 0, second);
-        linkParents(second, (_a = seg.run.PARENT) !== null && _a !== void 0 ? _a : this.p);
+        linkParents(second, (_b = seg.run.PARENT) !== null && _b !== void 0 ? _b : this.p);
     }
     // --- lists (CR-002 phase H) ---
     /**
@@ -801,14 +1324,17 @@ export class Paragraph {
      * unmarshalled (CR-002 section 17).
      */
     startNewList(options) {
+        this.assertWritable();
         return startNewList(this, options);
     }
     /** Office JS `paragraph.attachToList(listId, level)`: this paragraph joins that list. */
     attachToList(listId, level = 0) {
+        this.assertWritable();
         return attachToList(this, listId, level);
     }
     /** Office JS `paragraph.detachFromList()`: this paragraph leaves its list. */
     detachFromList() {
+        this.assertWritable();
         detachFromList(this);
     }
     /**
@@ -816,6 +1342,7 @@ export class Paragraph {
      * `w:abstractNum` with a `w:startOverride` (extension; `List.restart()` is the verb).
      */
     restartList() {
+        this.assertWritable();
         const list = this.list;
         const level = this.listItem.level;
         const restarted = list.restart();
@@ -829,6 +1356,7 @@ export class Paragraph {
     }
     /** Comments the whole paragraph (sugar over `getRange().insertComment`). */
     async insertComment(content, options) {
+        this.assertWritable();
         return commentApi().insertComment(this.getRange(), content, options);
     }
     // --- content controls (CR-002 phase E) ---
@@ -839,18 +1367,32 @@ export class Paragraph {
      */
     insertContentControl(kind) {
         var _a;
+        this.assertWritable();
         const at = this.index;
         if (at < 0)
             throw new Docx4JException('This paragraph is not in its container any more');
+        // the paragraph's parent read before the builder makes the control its parent: read after, it was the
+        // control's own content, and the control's PARENT pointed into itself (found in CR-012 phase 4)
+        const parent = (_a = this.p.PARENT) !== null && _a !== void 0 ? _a : this.parentBody.container;
+        // a bound block control holds one paragraph (CR-002 section 61): checked before sdtOf, which takes the paragraph
+        assertControlHolds(this.parentBody, parent, this.container.filter((e) => e !== this.element), [BLOCK_CONTROL], undefined, ['Paragraph', 'insertContentControl']);
+        const empty = this.segments({ objects: true }).length === 0;
         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);
+        linkParents(sdt, parent);
         declareSdtExtensions(this.parentBody, sdt);
         // 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);
+        const control = new ContentControl(sdt, this.container, this.parentBody);
+        // around an empty paragraph, a control showing Word's default placeholder, as Word's (CR-002 section 63, D8; check 64);
+        // a picture control Word's form, the flag and the placeholder picture (CR-005 section 10, D2; docx4j's check 71 case 8)
+        if (empty && showsPlaceholderWhenMade(kind))
+            control.showPlaceholder();
+        else if (empty && kind === 'Picture')
+            showPicturePlaceholder(control);
+        return control;
     }
     removeEmptyRuns() {
         var _a;
@@ -862,6 +1404,16 @@ export class Paragraph {
                     if (!v.content || v.content.length === 0)
                         items.splice(i, 1);
                 }
+                else if (isAlternateContent(el)) {
+                    // among the runs: a selected branch an edit has emptied takes the element, every branch with
+                    // it, as a deletion of all of a run-level element's text does (CR-012 section 12.2 item 4)
+                    const branch = selectedBranchOf(el.value);
+                    if (!branch || branch.length === 0)
+                        continue;
+                    prune(branch);
+                    if (branch.length === 0)
+                        items.splice(i, 1);
+                }
                 else if (v.TYPE_NAME !== 'org_docx4j_wml.P') {
                     const nested = runItemsOf(v);
                     if (nested) {
@@ -881,16 +1433,28 @@ export class Paragraph {
      * turned into `w:delText`, and each run of consecutive ones moved into one `w:del`. Text this
      * author had inserted is simply removed, as Word does, rather than nested in a `w:del`.
      * The pictures in the span (`splice`'s `edges`) are deleted with the text, each in a run of its own
-     * where its run held more, as `InlinePicture.delete` gives it one (CR-002 section 48).
+     * where its run held more, as `InlinePicture.delete` gives it one (CR-002 section 48). An equation is deleted where
+     * it stands, in Word's form, a `w:del` in each math run and each structure's `m:ctrlPr` (`markEquationDeleted`;
+     * section 62.2 D2), the runs either side in `w:del`s of their own; one holding a revision of its own goes into the
+     * `w:del` whole, as every equation did before.
      * Returns the `w:del` elements it made, in document order.
      */
     deleteText(tracker, start, end, edges) {
-        var _a, _b, _c, _d, _e;
+        var _a, _b, _c, _d, _e, _f, _g;
+        // a run-level control showing its placeholder that the span holds whole is marked deleted whole, in Word's markers,
+        // its placeholder gone unmarked (CR-002 section 63, D3; check 63's run 2, cases 45, 46 and 52)
+        for (const control of this.placeholderControlsIn(start, end, edges))
+            control.takeWhole();
         const targets = this.isolate(start, end, edges);
         for (const seg of targets)
             tracker.assertEditable(seg.revision);
         const list = [];
+        const equations = [];
         for (const seg of targets) {
+            if (seg.math && !tracker.ownInsertion(seg.revision) && equationRevisionIn(seg.item.value) === undefined) {
+                equations.push(seg.item.value);
+                continue;
+            }
             const run = seg.runOwner[seg.runIndex];
             if (list.length > 0 && list[list.length - 1].run === run)
                 continue;
@@ -899,6 +1463,22 @@ export class Paragraph {
                 target.revision = seg.revision;
             list.push(target);
         }
+        // a comment's reference in the span goes into the w:del with the text, where it stands among the runs, as Word
+        // puts it (check 54 case 28; CR-014 section 12.6); accepting the deletion then takes the comment
+        const references = this.commentReferencesIn(start, end, edges);
+        if (references.length > 0) {
+            const order = runOrderOf(this.p);
+            const revisions = new Map(targets.filter((seg) => seg.revision).map((seg) => [seg.runOwner, seg.revision]));
+            for (const { run, owner } of references) {
+                const revision = (_a = revisions.get(owner)) !== null && _a !== void 0 ? _a : revisionHolding(run);
+                const target = { run, owner, own: tracker.ownInsertion(revision) };
+                if (revision)
+                    target.revision = revision;
+                const key = (_b = order.get(run)) !== null && _b !== void 0 ? _b : Number.NaN;
+                const at = list.findIndex((t) => { var _a; return ((_a = order.get(t.run)) !== null && _a !== void 0 ? _a : Number.NaN) > key; });
+                list.splice(at < 0 ? list.length : at, 0, target);
+            }
+        }
         // groups of consecutive runs in the same array, so that one w:del holds them all
         const groups = [];
         for (const t of list) {
@@ -910,6 +1490,8 @@ export class Paragraph {
             else
                 groups.push([t]);
         }
+        for (const equation of equations)
+            markEquationDeleted(tracker, equation);
         const made = [];
         for (let g = groups.length - 1; g >= 0; g--) {
             const group = groups[g];
@@ -918,8 +1500,11 @@ export class Paragraph {
             const runs = owner.splice(at, group.length);
             if (group[0].own) {
                 // taking back our own insertion: the runs go, and an emptied w:ins with them; a picture's
-                // image waits for the save, as `InlinePicture.delete` leaves it (section 47)
+                // image waits for the save, as `InlinePicture.delete` leaves it (section 47); a comment whose
+                // reference goes with them goes too
                 this.releaseRelationships(runs);
+                for (const id of commentReferenceIds(runs))
+                    this.queueCommentRemoval(id);
                 const revision = group[0].revision;
                 if (revision && revision.items.length === 0) {
                     const i = revision.owner.indexOf(revision.element);
@@ -932,15 +1517,60 @@ export class Paragraph {
                 toDeletedText(run.value);
             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));
+            linkParents(del, ((_e = (_d = (_c = group[0].revision) === null || _c === void 0 ? void 0 : _c.value) !== null && _d !== void 0 ? _d : group[0].run.value.PARENT) !== null && _e !== void 0 ? _e : 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) };
+            const anchor = { owner, element: del, parent: ((_g = (_f = revision === null || revision === void 0 ? void 0 : revision.value) !== null && _f !== void 0 ? _f : del.value.PARENT) !== null && _g !== void 0 ? _g : this.p) };
             if (revision && revision.items === owner)
                 anchor.revision = revision;
             made.unshift(anchor);
         }
         return made;
     }
+    /**
+     * The run-level controls showing their placeholder that [start, end) holds whole: where the walk passes one strictly
+     * inside the span, or at an edge `edges` says it holds. A placeholder is no text, so such a control has no width
+     * (CR-002 section 63, D3).
+     */
+    placeholderControlsIn(start, end, edges) {
+        const found = [];
+        this.segments({ visit: (item, at) => {
+                var _a;
+                if (typeNameOf(item) !== 'org_docx4j_wml.SdtRun' || !objectInSpan(at, start, end, edges))
+                    return;
+                const sdtPr = item.value.sdtPr;
+                const flag = sdtProperty(sdtPr, 'showingPlcHdr');
+                if (flag !== undefined && ((_a = flag.value) === null || _a === void 0 ? void 0 : _a.val) !== false)
+                    found.push(item.value);
+            } });
+        return found.map((sdt) => controlViewOf(sdt, this.parentBody));
+    }
+    /**
+     * The runs of comments' references in [start, end): each a run holding nothing but a reference, where the walk
+     * passes it, strictly inside the span or at an edge `edges` says it holds. A reference has no text, so a
+     * deletion's segments never held it, and a comment whose reference a deletion took stayed. Word's deletion takes
+     * it with the text (check 54 cases 27 and 28; CR-014 section 12.6).
+     */
+    commentReferencesIn(start, end, edges) {
+        const out = [];
+        this.segments({ visit: (item, at, _owner, run) => {
+                var _a, _b;
+                if (((_a = item.name) === null || _a === void 0 ? void 0 : _a.localPart) !== 'commentReference' || !run || !objectInSpan(at, start, end, edges))
+                    return;
+                if (out.some((r) => r.run === run.element))
+                    return;
+                if (!((_b = run.element.value.content) !== null && _b !== void 0 ? _b : []).every((c) => { var _a; return ((_a = c.name) === null || _a === void 0 ? void 0 : _a.localPart) === 'commentReference'; }))
+                    return;
+                out.push({ run: run.element, owner: run.owner, id: Number(item.value.id) });
+            } });
+        return out;
+    }
+    /** A comment queued to go when the package is saved, its markers, replies and entries with it, as a resolution queues one. */
+    queueCommentRemoval(id) {
+        var _a, _b;
+        if (!Number.isInteger(id))
+            return;
+        (_b = (_a = this.parentBody.package_) === null || _a === void 0 ? void 0 : _a.pendingCommentRemovals) === null || _b === void 0 ? void 0 : _b.add(id);
+    }
     /**
      * 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
@@ -1030,7 +1660,7 @@ export class Paragraph {
      * of a replacement, which the insertion must follow.
      */
     insertTracked(tracker, at, text, anchor, prefer = 'before') {
-        var _a, _b, _c;
+        var _a, _b;
         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)]);
@@ -1066,7 +1696,7 @@ export class Paragraph {
         }
         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 rPr = copyRPr((_b = neighbour === null || neighbour === void 0 ? void 0 : neighbour.run.rPr) !== null && _b !== void 0 ? _b : this.visibleFirstRunRPr());
         const ins = tracker.ins([runOf([textItem(text)], rPr)]);
         this.placeInsertion(at, [ins], before, after, () => tracker.nextId(), prefer);
     }
@@ -1106,6 +1736,13 @@ export class Paragraph {
             linkParents(items, this.p);
         }
     }
+    /**
+     * Splits runs so that every run holding text in [start, end) holds nothing else (internal: what a
+     * `Range.font` write formats). A kept `mc:AlternateContent`'s branch splits with its run (section 12.2).
+     */
+    splitRunsAround(start, end) {
+        this.isolate(start, end);
+    }
     /**
      * Splits runs so that every run holding text in [start, end) holds nothing else, and returns
      * the segments inside the span. `splitAt` does the `w:t` boundaries; this also moves the items
@@ -1125,16 +1762,16 @@ export class Paragraph {
                 if (seen.has(seg.run))
                     continue;
                 seen.add(seg.run);
+                if (seg.math)
+                    continue; // in no run: taken whole or refused
                 const ofRun = inside.filter((s) => s.run === seg.run);
                 const first = ofRun[0];
                 const last = ofRun[ofRun.length - 1];
-                if (first.index > 0) {
-                    this.splitRunBefore(first);
+                if (this.splitRunBefore(first)) {
                     split = true;
                     break;
                 }
-                if (last.index < last.owner.length - 1) {
-                    this.splitRunAfter(last);
+                if (this.splitRunAfter(last)) {
                     split = true;
                     break;
                 }
@@ -1144,23 +1781,58 @@ export class Paragraph {
         }
         return this.segments({ objects: true }).filter(inSpan);
     }
-    /** Moves the items before `seg` into a run of their own, in front of `seg`'s run. */
+    /**
+     * Refuses an edit that would cut an equation (CR-012 phase 4). Its text is one segment, Word's drawing of
+     * its math runs (`mathTextOf`), so an edit may take it whole but not part of it, nor insert into it. Under change
+     * tracking a deletion takes it whole in Word's form (`deleteText`, CR-002 section 62.2 D2, check 57), and a
+     * replacement doesn't take it at all: where Word puts the new text beside a deleted equation isn't measured. Since
+     * phase 4 every other offset is a place in the runs: `text` is the segments' text, where before it was the objects
+     * package's `textOf` and section 12.4 refused an offset past a kept `mc:AlternateContent` among the runs.
+     */
+    assertPlaceable(start, end, tracked) {
+        for (const seg of this.segments()) {
+            if (!seg.math)
+                continue;
+            const cuts = (seg.start < start && start < seg.end) || (seg.start < end && end < seg.end);
+            const takes = start < seg.end && seg.start < end;
+            if (!cuts && !(tracked === 'replace' && takes))
+                continue;
+            throw new NotSupportedError('Paragraph', 'edit', `[${start}, ${end}) ${cuts ? 'cuts' : 'takes'} the equation at [${seg.start}, ${seg.end})`
+                + (cuts ? ': an edit takes an equation whole or not at all (CR-012 phase 4)'
+                    : ' under change tracking, with text in its place: a tracked replacement of an equation is not measured (CR-002 section 62.2)'));
+        }
+    }
+    /** Moves the items before `seg` into a run of their own, in front of the rest; false where there are none. */
     splitRunBefore(seg) {
         var _a;
-        const head = seg.owner.splice(0, seg.index);
-        const first = runOf(head, copyRPr(seg.run.rPr));
-        seg.runOwner.splice(seg.runIndex, 0, first);
-        linkParents(first, (_a = seg.run.PARENT) !== null && _a !== void 0 ? _a : this.p);
+        if (seg.index > 0) {
+            this.splitRunAtItem(seg, seg.owner, seg.index);
+            return true;
+        }
+        const alternate = ((_a = seg.alternate) === null || _a === void 0 ? void 0 : _a.level) === 'run' && seg.owner === seg.alternate.branch ? seg.alternate : undefined;
+        if (!alternate)
+            return false;
+        const at = alternate.owner.indexOf(alternate.element);
+        if (at <= 0)
+            return false;
+        this.splitRunAtItem(seg, alternate.owner, at);
+        return true;
     }
-    /** Moves the items after `seg` into a run of their own, behind `seg`'s run. */
+    /** Moves the items after `seg` into a run of their own, behind it; false where there are none. */
     splitRunAfter(seg) {
         var _a;
-        const tail = seg.owner.splice(seg.index + 1);
-        if (tail.length === 0)
-            return;
-        const rest = runOf(tail, copyRPr(seg.run.rPr));
-        seg.runOwner.splice(seg.runIndex + 1, 0, rest);
-        linkParents(rest, (_a = seg.run.PARENT) !== null && _a !== void 0 ? _a : this.p);
+        if (seg.index < seg.owner.length - 1) {
+            this.splitRunAtItem(seg, seg.owner, seg.index + 1);
+            return true;
+        }
+        const alternate = ((_a = seg.alternate) === null || _a === void 0 ? void 0 : _a.level) === 'run' && seg.owner === seg.alternate.branch ? seg.alternate : undefined;
+        if (!alternate)
+            return false;
+        const at = alternate.owner.indexOf(alternate.element);
+        if (at < 0 || at >= alternate.owner.length - 1)
+            return false;
+        this.splitRunAtItem(seg, alternate.owner, at + 1);
+        return true;
     }
 }
 export { W_NS };
@@ -1212,3 +1884,127 @@ function setText(t, value) {
     else
         delete t.space;
 }
+/**
+ * The element a run-level `mc:AlternateContent`'s later piece is written as (CR-012 section 12.2; the
+ * editor's ED-009 section 3.4, P2): its branches in order with their `Requires`, the selected one holding
+ * `items` and every other one empty.
+ */
+function alternatePiece(alternate, items) {
+    const ac = alternate.element.value;
+    const emptied = (branch) => {
+        if (branch === undefined)
+            return undefined;
+        const copy = {};
+        for (const [key, value] of Object.entries(branch))
+            if (key !== 'any' && key !== 'PARENT')
+                copy[key] = value;
+        copy.any = branch.any === alternate.branch ? items : [];
+        return copy;
+    };
+    const value = {};
+    for (const [key, v] of Object.entries(ac)) {
+        if (key === 'PARENT')
+            continue;
+        if (key === 'choice')
+            value.choice = v.map(emptied);
+        else if (key === 'fallback')
+            value.fallback = emptied(v);
+        else
+            value[key] = v;
+    }
+    return { name: alternate.element.name, value };
+}
+/**
+ * After an untracked deletion: a run-level `mc:AlternateContent` whose selected branch the deletion
+ * emptied goes, every branch with it (CR-012 section 12.2 item 4; ED-009 section 3.5). A branch that
+ * was empty before is left as it is.
+ */
+function removeEmptiedAlternates(removed) {
+    const seen = new Set();
+    for (const seg of removed) {
+        const alternate = seg.alternate;
+        if ((alternate === null || alternate === void 0 ? void 0 : alternate.level) !== 'run' || seen.has(alternate.element))
+            continue;
+        seen.add(alternate.element);
+        if (alternate.branch.length > 0)
+            continue;
+        const i = alternate.owner.indexOf(alternate.element);
+        if (i >= 0)
+            alternate.owner.splice(i, 1);
+    }
+}
+/** Block holders a cell's paragraph may stand in: a block content control, its content, custom XML. */
+const BLOCK_HOLDERS = new Set(['org_docx4j_wml.SdtBlock', 'org_docx4j_wml.SdtContentBlock', 'org_docx4j_wml.CTSdtContentBlock', 'org_docx4j_wml.CTCustomXmlBlock']);
+/** True for the last paragraph of a table cell, through the block holders between them. */
+function lastInCell(p) {
+    var _a;
+    let holder = p.PARENT;
+    for (let guard = 0; holder && guard < 16 && BLOCK_HOLDERS.has((_a = holder.TYPE_NAME) !== null && _a !== void 0 ? _a : ''); guard++) {
+        holder = holder.PARENT;
+    }
+    if ((holder === null || holder === void 0 ? void 0 : holder.TYPE_NAME) !== 'org_docx4j_wml.Tc')
+        return false;
+    let last;
+    const visit = (items) => {
+        for (const el of items !== null && items !== void 0 ? items : []) {
+            const tn = typeNameOf(el);
+            if (tn === 'org_docx4j_wml.P')
+                last = el.value;
+            else if (tn !== 'org_docx4j_wml.Tbl' && typeof el.value === 'object' && el.value !== null) {
+                const v = el.value;
+                visit(v.sdtContent ? v.sdtContent.content : v.content);
+            }
+        }
+    };
+    visit(holder.content);
+    return last === p;
+}
+/** Every element among a paragraph's runs, in document order: where a deletion places a comment's reference among its runs. */
+function runOrderOf(p) {
+    const order = new Map();
+    const visit = (items) => {
+        for (const el of items !== null && items !== void 0 ? items : []) {
+            order.set(el, order.size);
+            const v = el.value;
+            if (typeof v === 'object' && v !== null && typeNameOf(el) !== 'org_docx4j_wml.R')
+                visit(runItemsOf(v));
+        }
+    };
+    visit(runItemsOf(p));
+    return order;
+}
+/** The `w:ins` (or other revision) a run stands directly in, read from its `PARENT`, if any. */
+function revisionHolding(run) {
+    const holder = run.value.PARENT;
+    const items = holder === null || holder === void 0 ? void 0 : holder.customXmlOrSmartTagOrSdt;
+    const outer = (holder === null || holder === void 0 ? void 0 : holder.PARENT) ? runItemsOf(holder.PARENT) : undefined;
+    const element = outer === null || outer === void 0 ? void 0 : outer.find((e) => e.value === holder);
+    const kind = element ? revisionKindOf(element) : undefined;
+    if (!holder || !items || !outer || !element || !kind)
+        return undefined;
+    return { kind, element, value: holder, items, owner: outer };
+}
+/** The ids of the comment references among runs. */
+function commentReferenceIds(runs) {
+    return runs.flatMap((run) => {
+        var _a;
+        return ((_a = run.value.content) !== null && _a !== void 0 ? _a : [])
+            .filter((c) => { var _a; return ((_a = c.name) === null || _a === void 0 ? void 0 : _a.localPart) === 'commentReference'; }).map((c) => Number(c.value.id));
+    });
+}
+/** The `w:sdt` value types, block, run, row and cell. */
+const SDT_VALUE_TYPES = new Set(['org_docx4j_wml.SdtBlock', 'org_docx4j_wml.SdtRun', 'org_docx4j_wml.CTSdtRow', 'org_docx4j_wml.CTSdtCell']);
+/** Whether a paragraph holds a run-level control bound by `w:dataBinding`, at any depth among its runs. */
+function holdsBoundRunControl(holder) {
+    var _a;
+    for (const item of (_a = runItemsOf(holder)) !== null && _a !== void 0 ? _a : []) {
+        const value = item.value;
+        if (!value || typeof value !== 'object')
+            continue;
+        if (value.TYPE_NAME === 'org_docx4j_wml.SdtRun' && sdtProperty(value.sdtPr, 'dataBinding') !== undefined)
+            return true;
+        if (value.TYPE_NAME !== 'org_docx4j_wml.R' && holdsBoundRunControl(value))
+            return true;
+    }
+    return false;
+}