@docx4j/core-ts 0.5.0 → 0.6.0

package/dist/model/content/Body.mjs

@@ -1,19 +1,27 @@
 import { Docx4JException, PropertyResolverNotCreatedException } from '../../opc/exceptions.mjs';
-import { typeNameOf, childrenOf, linkParents, BLOCK_LEVEL_TYPES, textOf, textOfView, rowsOf, cellsOf, selectedBranchOf, ALTERNATE_CONTENT } from './tree.mjs';
-import { r as textRun, br as breakItem, tbl as tableOf } from '@docx4j/generated-objects-ts/builders/wml';
+import { hiddenRunsOf, typeNameOf, childrenOf, linkParents, BLOCK_LEVEL_TYPES, rowsOf, cellsOf, selectedBranchOf, branchesOf, branchListsOf, ALTERNATE_CONTENT, BRANCH_TYPES, inUnreadBranch, assertOutsideBranch, writingEveryBranch } from './tree.mjs';
+import { br as breakItem, tbl as tableOf } from '@docx4j/generated-objects-ts/builders/wml';
+import { oneParagraphRun } from './officeText.mjs';
 import { runOf, paragraphOf, runsOf } from './tree.mjs';
+import { textBoxesOf } from './textBoxes.mjs';
+import { outlineReader } from './outline.mjs';
 import { Paragraph } from './Paragraph.mjs';
+import { Range } from './Range.mjs';
 import { Table } from './Table.mjs';
-import { ContentControl, collectControls } from './ContentControl.mjs';
+import { ContentControl, collectControls, assertControlHolds, controlsOfTypes } from './ContentControl.mjs';
 import { sdt as sdtOf, nextSdtId } from '@docx4j/generated-objects-ts/builders/wml';
 import { controlIdScope, sdtKindFor, declareSdtExtensions } from '../customxml/insert.mjs';
 import { InlinePicture, addImage, writableWidthEmu } from './InlinePicture.mjs';
 import { contentOf } from './ooxml.mjs';
 import { relationshipIdsIn, queueRelationshipRemovals } from './relationships.mjs';
-import { expandReplacement } from './search.mjs';
+import { wrappingCellOf, paragraphEndOf, endsWithParagraph, endWithParagraph, endCellsWithParagraphs } from './tableRules.mjs';
+import { keepCellMarkLast } from './spanEdits.mjs';
+import { expandReplacement, paragraphMarkPieces, refuseMarkReplacement, refuseWildcardMarkReplacement } from './search.mjs';
 import { commentApi } from './comments.mjs';
+import { storyLayout } from './story.mjs';
 import { trackerOf, trackInsertedBlock, markHolderInserted } from './tracking.mjs';
-import { trackedChangesOfRow, trackedChangeTokensOfParagraph, groupTouching, BREAK, tablePropertiesChangeOf, cellChangeOf, bodySectionChangeOf, resolveUnlisted, holderInsertionAt, resolving } from './TrackedChange.mjs';
+import { trackedChangesOfRow, trackedChangeTokensOfParagraph, groupTouching, BREAK, tablePropertiesChangeOf, cellChangeOf, bodySectionChangeOf, resolveUnlisted, holderChangeAt, resolving, resolvePieces, alternateTokens, listedListing, pairTwins } from './TrackedChange.mjs';
+import { pieceMatcher } from './trackedChangeFilter.mjs';
 import { listsOf, listLabelsOf } from './List.mjs';
 /**
  * A subset of Office JS `Word.Body` over any container with block-level content: the main
@@ -47,14 +55,31 @@ export class Body {
             throw new PropertyResolverNotCreatedException();
         return resolver;
     }
+    /** Which of a paragraph's runs are hidden: a run's own `w:vanish`, else its styles' (`hiddenRunsOf`; CR-012 phase 4). */
+    hiddenRuns(p) {
+        const pkg = this.package_;
+        return hiddenRunsOf(pkg === null || pkg === void 0 ? void 0 : pkg.propertyResolverOrUndefined, p);
+    }
     /** The live content array (docx4j getContent()); block-level elements only, sectPr excluded. */
     get content() {
         var _a;
         var _b;
         return ((_a = (_b = this.container).content) !== null && _a !== void 0 ? _a : (_b.content = []));
     }
-    /** Every paragraph in document order, descending into tables and content controls. */
+    /**
+     * Every paragraph in document order, descending into tables and content controls, and into the
+     * selected branch of a kept `mc:AlternateContent` at block, row and cell level, as Word reads it
+     * (CR-013 phase 2). A paragraph in a branch is read-only (D4).
+     */
     get paragraphs() {
+        return this.paragraphsIn('read');
+    }
+    /**
+     * The paragraphs a walk in this mode takes: a reader's, `paragraphs`; a bulk edit's (`'every'`), every
+     * branch's too, the selected branch's where a reader sees them and each other branch's after them,
+     * where the element stands (CR-013 phase 3).
+     */
+    paragraphsIn(mode) {
         const out = [];
         const visit = (items) => {
             var _a;
@@ -67,10 +92,14 @@ export class Body {
                     if (typeof v !== 'object' || v === null)
                         continue;
                     if (tn === 'org_docx4j_wml.Tbl') {
-                        for (const row of rowsOf(v))
-                            for (const cell of cellsOf(row.element.value))
+                        for (const row of rowsOf(v, mode))
+                            for (const cell of cellsOf(row.element.value, mode))
                                 visit((_a = childrenOf(cell.element.value)) !== null && _a !== void 0 ? _a : []);
                     }
+                    else if (tn === ALTERNATE_CONTENT) {
+                        for (const branch of branchListsOf(v, mode))
+                            visit(branch);
+                    }
                     else {
                         const children = childrenOf(v);
                         if (children)
@@ -154,14 +183,45 @@ export class Body {
         }
         return out;
     }
-    /** The tables directly in this body, as Office JS reports them (nested tables are a cell's). */
+    /**
+     * The tables directly in this body, as Office JS reports them (nested tables are a cell's), a table in
+     * the selected branch of a kept block-level `mc:AlternateContent` among them (CR-013 phase 2).
+     */
     get tables() {
-        return this.content.filter((el) => typeNameOf(el) === 'org_docx4j_wml.Tbl').map((element) => new Table(element, this.content, this));
+        const out = [];
+        const visit = (items) => {
+            var _a;
+            for (const element of items) {
+                const tn = typeNameOf(element);
+                if (tn === 'org_docx4j_wml.Tbl')
+                    out.push(new Table(element, items, this));
+                else if (tn === ALTERNATE_CONTENT)
+                    visit((_a = selectedBranchOf(element.value)) !== null && _a !== void 0 ? _a : []);
+            }
+        };
+        visit(this.content);
+        return out;
     }
     /** Every content control in this body, in document order, nested ones included. */
     get contentControls() {
+        return this.contentControlsIn('read');
+    }
+    /**
+     * 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 content controls a walk in this mode takes: a reader's, `contentControls`; the binding passes'
+     * (`'every'`), every branch's of a kept `mc:AlternateContent` too, each other branch's where the element
+     * stands (CR-013 phase 3). An extension.
+     */
+    contentControlsIn(mode) {
         const out = [];
-        collectControls(this.content, this, out);
+        collectControls(this.content, this, out, mode);
         return out;
     }
     /** Every inline picture in this body, in document order (Office JS Body.inlinePictures). */
@@ -201,33 +261,72 @@ export class Body {
         const element = container === null || container === void 0 ? void 0 : container.find((e) => e.value === p);
         return element && container ? new Paragraph(element, container, this) : undefined;
     }
-    /** The text, a paragraph per line. */
+    /**
+     * The text as Office JS's `body.text` gives it in Word's default view (CR-012 phase 4; checks 30, 31, 48
+     * and 51): each paragraph's text (`Paragraph.text`) followed by its mark, `\r`, the last paragraph's left
+     * out; in a table a row's cells a `\t` apart, each cell's paragraphs a mark apart (its last mark not
+     * written), and the row ended by `\r\n`. Text boxes are not the body's (check 42).
+     */
     get text() {
-        return this.paragraphs.map((p) => p.text).join('\n');
+        return this.textIn('accepted');
     }
     /**
      * The text in one of the two views (extension; `text` is the accepted one).
      * `{ view: 'original' }` reads the document as it was before the tracked changes.
      */
     getText(options) {
-        if ((options === null || options === void 0 ? void 0 : options.view) !== 'original')
-            return this.text;
-        return this.paragraphs.map((p) => textOfView(p.p, options)).join('\n');
+        var _a;
+        return this.textIn((_a = options === null || options === void 0 ? void 0 : options.view) !== null && _a !== void 0 ? _a : 'accepted');
+    }
+    /**
+     * The body's range (Office JS `Body.getRange`; CR-014 phase 1): 'Whole' from its first paragraph's start to
+     * its last one's end, with that paragraph's mark (check 51: a cell's `CELLP1\rCELLP2\rCELLP3\t`, a note's
+     * `… NOTEP2\r`), 'Content' the same without the mark, 'Start' and 'End' collapsed at its ends.
+     */
+    getRange(location = 'Whole') {
+        const paragraphs = this.paragraphs;
+        const first = paragraphs[0];
+        if (!first)
+            throw new Docx4JException('This body holds no paragraph');
+        const last = paragraphs[paragraphs.length - 1];
+        if (location === 'Start')
+            return first.getRange('Start');
+        if (location === 'End')
+            return last.getRange('End');
+        if (paragraphs.length === 1)
+            return first.getRange(location);
+        return new Range(first, 0, last.text.length, true, location === 'Whole', last);
+    }
+    textIn(view) {
+        // the original view's marks are the ones Reject All keeps: a deleted mark written, an inserted one not
+        const { text } = storyLayout(this.content, (el, items) => {
+            const p = new Paragraph(el, items, this);
+            return view === 'original' ? p.getText({ view }) : p.text;
+        }, view === 'original' ? (p) => { var _a, _b; return ((_b = (_a = p.pPr) === null || _a === void 0 ? void 0 : _a.rPr) === null || _b === void 0 ? void 0 : _b.ins) === undefined; } : undefined);
+        // the last paragraph's mark is not written
+        return text.endsWith('\r') ? text.slice(0, -1) : text;
     }
     /** The package's change tracker while `changeTrackingMode` is on; undefined when it is off (CR-002 phase F). */
     get changeTracker() {
         var _a;
         return (_a = trackerOf(this.package_)) === null || _a === void 0 ? void 0 : _a.forPart(this.part);
     }
+    /** Refuses a write to a body in a branch of a kept `mc:AlternateContent`: a cell or a control a reader found there (CR-013 D4). */
+    assertWritable() {
+        assertOutsideBranch(this.container, 'Body');
+    }
     insertParagraph(text, location) {
-        const el = paragraphOf(text === '' ? [] : [textRun(text)]);
+        var _a;
+        const run = oneParagraphRun(text); // CR-002 section 60 E2: one paragraph, its line breaks w:br and w:cr
+        const el = paragraphOf(((_a = run.value.content) === null || _a === void 0 ? void 0 : _a.length) ? [run] : []);
         return this.insertElement(el, location);
     }
     /** Text at the start of the first paragraph, the end of the last, or replacing everything with one paragraph. */
     insertText(text, location) {
+        this.assertWritable();
         const paragraphs = this.paragraphs;
         if (location === 'Replace' || paragraphs.length === 0) {
-            this.clear();
+            this.clearContent(false); // its own paragraph ends a cell, so the cell's last one goes too
             const p = this.insertParagraph(text, 'End');
             return p.getRange('Content');
         }
@@ -252,7 +351,7 @@ export class Body {
         // cells the builder wrote, the table's width made automatic (CR-002 section 42.5 item 7).
         const tblPr = ((_a = (_b = element.value).tblPr) !== null && _a !== void 0 ? _a : (_b.tblPr = {}));
         tblPr.tblW = { w: 0, type: 'auto' };
-        this.insertElement(element, location);
+        this.insertElement(element, location, undefined, 'InvalidArgument');
         return new Table(element, this.content, this);
     }
     /**
@@ -261,6 +360,7 @@ export class Body {
      * than the text area is scaled down, as docx4j's CxCy.scale does.
      */
     insertInlinePictureFromBase64(base64, location, options) {
+        this.assertWritable();
         if (!this.part)
             throw new Docx4JException('This body has no part, so an image cannot be related to it');
         const { run, drawing } = addImage(this.part, base64, this.container, writableWidthEmu(this.container), options);
@@ -285,7 +385,8 @@ export class Body {
      * before or after a target paragraph, element or address. Links PARENT. Rejects anything the
      * body cannot hold, naming what was passed. Returns the view of the first inserted element.
      */
-    insertElement(element, location, target) {
+    insertElement(element, location, target, refusal, replacing) {
+        this.assertWritable();
         const elements = Array.isArray(element) ? element : [element];
         if (elements.length === 0)
             throw new Docx4JException('Nothing to insert');
@@ -303,11 +404,18 @@ export class Body {
             index = container.length;
         else {
             const t = this.resolveTarget(target);
+            assertOutsideBranch(t.element.value, 'Body', 'the block to insert beside'); // beside it is in the branch too
             container = t.container;
             index = container.indexOf(t.element) + (location === 'After' ? 1 : 0);
         }
-        container.splice(index, 0, ...elements);
+        // a bound block control holds one paragraph (CR-002 section 61): `replacing` is the block the write takes away after
+        assertControlHolds(this, this.ownerOf(container), replacing ? container.filter((e) => e !== replacing) : container, elements, refusal);
+        // a cell ends with a paragraph, as Word reads it: the cells of what goes in (D3), and the cell it goes in (CR-002 section 55)
+        endCellsWithParagraphs(elements);
         const owner = this.ownerOf(container);
+        const cell = wrappingCellOf(owner);
+        const end = cell ? paragraphEndOf(cell.content) : undefined;
+        container.splice(index, 0, ...elements);
         const tracker = this.changeTracker;
         for (const el of elements) {
             linkParents(el, owner);
@@ -319,12 +427,15 @@ export class Body {
             if (tracker)
                 trackInsertedBlock(tracker, el, container);
         }
+        if (cell)
+            this.keepCellEnd(cell, end, container);
         const first = elements[0];
         return typeNameOf(first) === 'org_docx4j_wml.P' ? new Paragraph(first, container, this) : { element: first, container };
     }
     /** Inserts a WML fragment (one or more w:p / w:tbl / ... as inside document.xml); the standard prefixes are declared for it. */
     async insertXml(xml, location, target) {
-        return this.insertContent(await contentOf(xml, { preprocess: this.preprocessor() }), location, target);
+        this.assertWritable();
+        return this.insertContent(await contentOf(xml, { preprocess: this.preprocessor() }), location, target, 'GeneralException');
     }
     /**
      * Word's `insertOoxml`: a flat OPC `pkg:package` string, whose body content is inserted with
@@ -334,12 +445,39 @@ export class Body {
      * what was inserted, as `insertXml` does, since a package may bring several blocks.
      */
     async insertOoxml(ooxml, location, target) {
+        this.assertWritable();
         const elements = await contentOf(ooxml, { preprocess: this.preprocessor(), target: this.part });
         if (location === 'Replace') {
-            this.clear();
-            return this.insertContent(elements, 'End');
+            assertControlHolds(this, this.container, [], elements, 'GeneralException'); // before the clear (CR-002 section 61)
+            // In a cell, what ends with a table goes in before the cell's last paragraph, which stays, emptied, as Word
+            // keeps it (check 52, case 94; CR-002 section 55.6); what ends with a paragraph replaces it, as before
+            const cell = endsWithParagraph(elements) ? undefined : wrappingCellOf(this.container);
+            this.clearContent(cell !== undefined);
+            const end = cell ? paragraphEndOf(cell.content) : undefined;
+            if (end && end.container === this.content)
+                return this.insertContent(elements, 'Before', { element: end.element, container: end.container }, 'GeneralException');
+            return this.insertContent(elements, 'End', undefined, 'GeneralException');
+        }
+        return this.insertContent(elements, location, target, 'GeneralException');
+    }
+    /**
+     * After an insertion into a cell: the cell still ends with a paragraph, as Word reads it (CR-002 section 55). Where
+     * a table went in after the paragraph the cell ended with, in the cell's own content, Word's form (check 52, cases 86
+     * and 87, `keepCellMarkLast`): that paragraph split at its end, the cell's mark staying last after the table, the
+     * first half's mark the inserted one under tracking. Anywhere else docx4j's repair, an empty paragraph after any wrapper.
+     */
+    keepCellEnd(cell, end, container) {
+        var _a;
+        const content = ((_a = cell.content) !== null && _a !== void 0 ? _a : (cell.content = []));
+        if (endsWithParagraph(content))
+            return;
+        if (end && end.container === content && container === content) {
+            keepCellMarkLast(new Paragraph(end.element, content, this), content);
+            return;
         }
-        return this.insertContent(elements, location, target);
+        const appended = endWithParagraph(cell);
+        if (appended)
+            this.assignParaId(appended);
     }
     /** The package's DOM preprocessor (the MCE one), for fragments and incoming packages. */
     preprocessor() {
@@ -347,16 +485,22 @@ export class Body {
         const preprocess = (_a = this.package_) === null || _a === void 0 ? void 0 : _a.loadOptions.preprocessor;
         return preprocess ? (doc) => preprocess(doc) : undefined;
     }
-    insertContent(elements, location, target) {
+    insertContent(elements, location, target, refusal) {
         if (elements.length === 0)
             return [];
-        this.insertElement(elements, location, target);
+        this.insertElement(elements, location, target, refusal);
         return elements.map((el) => typeNameOf(el) === 'org_docx4j_wml.P'
             ? new Paragraph(el, this.containerOf(el), this)
             : { element: el, container: this.containerOf(el) });
     }
     /** Matches over every paragraph, in document order. */
     search(text, options) {
+        // Word's paragraph mark, ^p, is searched across the body's whole range (CR-014 phase 3); a wildcard query across its
+        // content, which Word's wildcards read without the last paragraph's mark (check 59 case 5, a control's; K7)
+        if ((options === null || options === void 0 ? void 0 : options.matchWildcards) && this.paragraphs.length > 0)
+            return this.getRange('Content').search(text, options);
+        if (!(options === null || options === void 0 ? void 0 : options.matchWildcards) && !(options === null || options === void 0 ? void 0 : options.matchRegExp) && paragraphMarkPieces(text) && this.paragraphs.length > 0)
+            return this.getRange('Whole').search(text, options);
         return this.paragraphs.flatMap((p) => p.search(text, options));
     }
     /**
@@ -365,40 +509,101 @@ export class Body {
      * the package's `changeTrackingMode` is on.
      */
     replaceText(find, replace, options) {
-        const matches = this.paragraphs.flatMap((p) => p.searchMatches(find, options));
-        for (let i = matches.length - 1; i >= 0; i--) {
-            const { range, match } = matches[i];
-            range.insertText(expandReplacement(replace, match, options), 'Replace');
-        }
-        return matches.length;
+        refuseMarkReplacement('Body', find, options);
+        if (options === null || options === void 0 ? void 0 : options.matchWildcards)
+            refuseWildcardMarkReplacement('Body', this.search(find, options));
+        this.assertWritable();
+        // every branch of a kept mc:AlternateContent, each paragraph searched on its own; counted where a
+        // reader sees the match, as resolve-all counts the listed changes (CR-013 phase 3)
+        const matches = this.paragraphsIn('every').flatMap((p) => p.searchMatches(find, options).map((m) => ({ ...m, unread: inUnreadBranch(p.p) })));
+        writingEveryBranch(() => {
+            for (let i = matches.length - 1; i >= 0; i--) {
+                const { range, match } = matches[i];
+                range.insertText(expandReplacement(replace, match, options), 'Replace');
+            }
+        });
+        return matches.filter((m) => !m.unread).length;
     }
     /**
      * Removes everything (section properties stay). While the package tracks changes, every
      * paragraph is marked deleted and every row's `w:trPr` takes a `w:del` instead. Removed outright,
      * the relationships the content held (its pictures' images) are settled on save (CR-002 section 47).
+     * In a table cell the paragraph the cell ends with stays, emptied, its properties kept, and tracked
+     * only its text is deleted, as Word keeps a cell's last paragraph (check 52, cases 92 and 93; CR-002 section 55.6).
      */
     clear() {
+        this.clearContent(true);
+    }
+    /**
+     * `clear()`; with `keepCellEnd` false a cell's last paragraph goes as well, its mark marked deleted under
+     * tracking, for a caller that puts its own paragraph in next (`insertText(…, 'Replace')`, `TableCell.value`).
+     * @internal
+     */
+    clearContent(keepCellEnd) {
         var _a;
+        this.assertWritable();
         const tracker = this.changeTracker;
         if (!tracker) {
+            const cell = keepCellEnd ? wrappingCellOf(this.container) : undefined;
+            const end = cell ? paragraphEndOf(cell.content) : undefined;
             const ids = new Set();
             relationshipIdsIn(this.content, ids);
             queueRelationshipRemovals((_a = this.package_) === null || _a === void 0 ? void 0 : _a.pendingRelationshipRemovals, this.part, ids);
             this.content.length = 0;
+            if (cell && !endsWithParagraph(cell.content)) {
+                if (end) {
+                    end.element.value.content = [];
+                    this.content.push(end.element);
+                    linkParents(end.element, this.container);
+                }
+                else {
+                    const appended = endWithParagraph(cell);
+                    if (appended)
+                        this.assignParaId(appended);
+                }
+            }
             return;
         }
-        for (const row of this.rowElements())
-            tracker.markRowDeleted(row.value);
-        for (const p of this.paragraphs)
-            p.delete();
+        // every branch of a kept mc:AlternateContent (CR-013 phase 3)
+        writingEveryBranch(() => {
+            for (const row of this.rowElements())
+                tracker.markRowDeleted(row.value);
+            for (const p of this.paragraphsIn('every'))
+                p.remove(keepCellEnd);
+        });
+    }
+    /**
+     * Marks everything in this body deleted in place, in every branch of a kept `mc:AlternateContent`: each
+     * paragraph's text and mark, each row of its tables (a tracked row or table deletion's cells; CR-013
+     * phase 3). Internal: what `Table.delete` and `deleteRows` write while changes are tracked.
+     */
+    markContentDeleted(tracker) {
+        // the paragraphs, then the rows last first: the order, and so the ids, a row's deletion has always written;
+        // a row already deleted is left as it is, as a paragraph already deleted is (a range's deletion, CR-014 phase 2)
+        writingEveryBranch(() => {
+            var _a;
+            for (const p of this.paragraphsIn('every'))
+                p.markDeletedInPlace(tracker);
+            for (const row of this.rowElements().reverse())
+                if (!((_a = row.value.trPr) === null || _a === void 0 ? void 0 : _a.del))
+                    tracker.markRowDeleted(row.value);
+        });
     }
     // --- change tracking (CR-002 phase F) ---------------------------------------------------
     /**
      * Every tracked change in this body, in document order. Touching insertions or deletions by one
      * author - a deleted paragraph's text and mark, a deletion across a mark - are one change, as
      * Office JS lists them (CR-002 section 29, checks 22 and 23).
+     *
+     * In a kept `mc:AlternateContent` at block, paragraph, row or cell level the selected branch's changes
+     * are listed, as Word reads it (CR-013 phase 2); each other branch's are their twins, paired by kind and
+     * position, which resolving a listed change resolves too (phase 3, docx4j's twins).
      */
     getTrackedChanges() {
+        return this.trackedChanges(listedListing());
+    }
+    /** The listing in either mode (`Listing`): resolve-all's puts every other branch's changes after the story's. */
+    trackedChanges(listing) {
         const out = [];
         const visit = (items, into) => {
             var _a, _b;
@@ -406,12 +611,12 @@ export class Body {
                 const el = items[i];
                 const tn = typeNameOf(el);
                 if (tn === 'org_docx4j_wml.P') {
-                    into.push(...trackedChangeTokensOfParagraph(new Paragraph(el, items, this)));
+                    into.push(...trackedChangeTokensOfParagraph(new Paragraph(el, items, this), listing));
                     continue;
                 }
                 // a block control or custom XML element that is itself an insertion (check 30): one piece,
                 // grouping with the insertions around and inside it, as Word lists them
-                const inserted = holderInsertionAt(items, i, undefined);
+                const inserted = holderChangeAt(items, i, undefined, this);
                 if (inserted) {
                     into.push(inserted);
                     visit((_a = childrenOf(items[i + 1].value)) !== null && _a !== void 0 ? _a : [], into);
@@ -427,31 +632,16 @@ export class Body {
                     // inserted paragraphs is one change; rows added at a table's end with a paragraph typed after
                     // it, one; a paragraph whose mark is plain before rows added at the start, two). Its property
                     // records are one change of their own where the table stands (CR-002 section 35), kept apart.
-                    const tableChange = tablePropertiesChangeOf(el);
+                    const tableChange = tablePropertiesChangeOf(el, this);
                     if (tableChange)
                         into.push(BREAK, tableChange, BREAK);
-                    for (const row of rowsOf(v)) {
-                        // A row that is itself a revision reports as one change, as Office JS does: the
-                        // markup its cells carry (Word marks every run and mark of a deleted or inserted row)
-                        // belongs to that change, which accepts or rejects it along with the row.
-                        const tokens = [];
-                        for (const cell of cellsOf(row.element.value)) {
-                            const cellChange = cellChangeOf(cell.element, cell.container, row.element.value, this);
-                            if (cellChange)
-                                tokens.push(cellChange, BREAK);
-                            visit((_b = childrenOf(cell.element.value)) !== null && _b !== void 0 ? _b : [], tokens);
-                            tokens.push(BREAK);
-                        }
-                        const inner = groupTouching(tokens);
-                        const rowChanges = trackedChangesOfRow(row.element, row.container, inner, { element: el, container: items }, this);
-                        if (rowChanges.length > 0)
-                            into.push(...rowChanges);
-                        else {
-                            into.push(BREAK);
-                            for (const change of inner)
-                                into.push(change, BREAK);
-                        }
-                    }
+                    visitRows((_b = childrenOf(v)) !== null && _b !== void 0 ? _b : [], { element: el, container: items }, into);
+                    continue;
+                }
+                // a kept mc:AlternateContent is its selected branch, as Word reads it, and keeps nothing apart
+                // (CR-013 phase 2): Word's save has no element there. Its other branches' are twins (phase 3)
+                if (tn === ALTERNATE_CONTENT) {
+                    alternateTokens(v, visit, into, listing);
                     continue;
                 }
                 // a block-level content control or custom XML element keeps what is inside it apart; a
@@ -464,51 +654,137 @@ export class Body {
                 }
             }
         };
+        // a table's rows, through row-level controls and custom XML and a row-level mc:AlternateContent
+        const visitRows = (items, table, into) => {
+            var _a;
+            for (const el of items) {
+                const tn = typeNameOf(el);
+                const v = el.value;
+                if (typeof v !== 'object' || v === null)
+                    continue;
+                if (tn === 'org_docx4j_wml.Tr') {
+                    // A row that is itself a revision reports as one change, as Office JS does: the markup its
+                    // cells carry (Word marks every run and mark of a deleted or inserted row) belongs to that
+                    // change, which accepts or rejects it along with the row.
+                    const tokens = [];
+                    visitCells((_a = childrenOf(v)) !== null && _a !== void 0 ? _a : [], el, tokens);
+                    const inner = groupTouching(tokens);
+                    const rowChanges = trackedChangesOfRow(el, items, inner, table, this);
+                    if (rowChanges.length > 0)
+                        into.push(...rowChanges);
+                    else {
+                        into.push(BREAK);
+                        for (const change of inner)
+                            into.push(change, BREAK);
+                    }
+                }
+                else if (tn === ALTERNATE_CONTENT) {
+                    alternateTokens(v, (branch, tokens) => visitRows(branch, table, tokens), into, listing);
+                }
+                else if (tn !== 'org_docx4j_wml.Tc') {
+                    const children = childrenOf(v);
+                    if (children)
+                        visitRows(children, table, into);
+                }
+            }
+        };
+        // a row's cells, through cell-level controls and custom XML and a cell-level mc:AlternateContent
+        const visitCells = (items, row, tokens) => {
+            var _a;
+            for (const el of items) {
+                const tn = typeNameOf(el);
+                const v = el.value;
+                if (typeof v !== 'object' || v === null)
+                    continue;
+                if (tn === 'org_docx4j_wml.Tc') {
+                    const cellChange = cellChangeOf(el, items, row.value, this);
+                    if (cellChange)
+                        tokens.push(cellChange, BREAK);
+                    visit((_a = childrenOf(v)) !== null && _a !== void 0 ? _a : [], tokens);
+                    tokens.push(BREAK);
+                }
+                else if (tn === ALTERNATE_CONTENT) {
+                    alternateTokens(v, (branch, into) => visitCells(branch, row, into), tokens, listing);
+                }
+                else {
+                    const children = childrenOf(v);
+                    if (children)
+                        visitCells(children, row, tokens);
+                }
+            }
+        };
         visit(this.content, out);
         // the body's last section, after everything in it
-        const section = bodySectionChangeOf(this.container);
+        const section = bodySectionChangeOf(this.container, this);
         if (section)
             out.push(BREAK, section);
+        // resolve-all's: every other branch's changes, each kept apart, after the story's (resolved first, last first)
+        if (listing.extra.length > 0)
+            out.push(BREAK, ...listing.extra);
         return groupTouching(out);
     }
     /**
      * Accepts every tracked change, last first so that a paragraph join never disturbs one still
      * to do (docx4j `AcceptTrackedChanges` is the reference). Returns how many were listed.
+     *
+     * With a filter (an extension, CR-011), only the single changes it matches are accepted, so a group
+     * can be resolved in part, and what no change owns is left alone; the count is of the listed changes
+     * with a matching piece (docx4j's `TrackedChanges.acceptAll(pkg, filter)`).
      */
-    acceptAll() {
-        return this.resolveAll('accept');
+    acceptAll(filter) {
+        return this.resolveAll('accept', filter);
     }
-    /** Rejects every tracked change, last first. Returns how many were listed. */
-    rejectAll() {
-        return this.resolveAll('reject');
+    /** Rejects every tracked change, last first, as `acceptAll` accepts them. Returns how many were listed. */
+    rejectAll(filter) {
+        return this.resolveAll('reject', filter);
     }
     /**
      * Resolving one change can leave another to be listed afresh: accepting a move carries a deletion
      * nested in its moved text out of it, and resolving a broken move dissolves the rest of it into a
      * new `w:ins` or `w:del` (CR-002 section 29), so the list read first goes stale. The list is read
-     * again after each pass until nothing is left, as "all" promises (found by the editor's C5); a
-     * pass that resolves nothing ends it.
+     * again after each pass until nothing is left, as "all" promises (found by the editor's C5); as
+     * docx4j's `TrackedChanges.resolveAll` does it (CR-011): a change whose pieces all match is resolved
+     * whole, one with some matching its matching pieces alone, for up to 20 passes, and two passes in a
+     * row that leave as many matching changes as the one before end it. Then, with no filter, what is
+     * never listed is swept.
      */
-    resolveAll(what) {
+    resolveAll(what, filter) {
+        const matches = filter === undefined ? undefined : pieceMatcher(filter);
+        const matching = (change) => (matches ? change.pieces.filter(matches) : change.pieces);
         let count = 0;
         // one resolution for the lot, so the bookmarks are read before the first and after the last
         resolving(this.package_, this, () => {
-            let changes = this.getTrackedChanges();
-            count = changes.length;
-            while (changes.length > 0) {
-                for (let i = changes.length - 1; i >= 0; i--)
-                    changes[i][what]();
-                const left = this.getTrackedChanges();
-                if (left.length >= changes.length)
+            // counted as listed; resolved over every branch of a kept mc:AlternateContent, each other branch's
+            // changes on their own, as docx4j's resolveAll lists them (CR-013 phase 3)
+            count = this.getTrackedChanges().filter((change) => matching(change).length > 0).length;
+            let left = Infinity;
+            let stalled = 0;
+            for (let pass = 0; pass < 20 && stalled < 2; pass++) {
+                const changes = this.trackedChanges({ mode: 'every', extra: [] });
+                let matched = 0;
+                for (let i = changes.length - 1; i >= 0; i--) {
+                    const change = changes[i];
+                    const pieces = matching(change);
+                    if (pieces.length === 0)
+                        continue;
+                    matched++;
+                    if (pieces.length === change.pieces.length)
+                        change[what]();
+                    else
+                        resolvePieces(pieces, what);
+                }
+                if (matched === 0)
                     break;
-                changes = left;
+                stalled = matched >= left ? stalled + 1 : 0;
+                left = matched;
             }
             // and what is never listed: a cell merge, a numbering change, records that change nothing
-            resolveUnlisted(this.content, what);
+            if (!matches)
+                resolveUnlisted(this.content, what);
         });
         return count;
     }
-    /** Every `w:tr` in this body's tables, in document order (rows of nested tables included). */
+    /** Every `w:tr` in this body's tables, in document order (rows of nested tables included), in every branch (CR-013 phase 3). */
     rowElements() {
         const out = [];
         const visit = (items) => {
@@ -518,13 +794,18 @@ export class Body {
                 if (typeof v !== 'object' || v === null)
                     continue;
                 if (typeNameOf(el) === 'org_docx4j_wml.Tbl') {
-                    for (const row of rowsOf(v)) {
+                    for (const row of rowsOf(v, 'every')) {
                         out.push(row.element);
-                        for (const cell of cellsOf(row.element.value))
+                        for (const cell of cellsOf(row.element.value, 'every'))
                             visit((_a = childrenOf(cell.element.value)) !== null && _a !== void 0 ? _a : []);
                     }
                     continue;
                 }
+                if (typeNameOf(el) === ALTERNATE_CONTENT) {
+                    for (const branch of branchesOf(v))
+                        visit(branch);
+                    continue;
+                }
                 const children = childrenOf(v);
                 if (children)
                     visit(children);
@@ -540,7 +821,11 @@ export class Body {
         return this.part.getXml();
     }
     // --- addresses (CR-002 section 3.3) ---
-    /** The element at an address: 'body/3' (fourth block), 'body/3/1/0/2' (table row 1, cell 0, block 2), a paraId, or a text match. */
+    /**
+     * The element at an address: 'body/3' (fourth block), 'body/3/1/0/2' (table row 1, cell 0, block 2),
+     * 'body/3/textbox:0/1' (the second block of the first text box body/3 anchors, CR-012 D4), a paraId, or a
+     * text match. Undefined, never an error, where the address names nothing.
+     */
     elementAt(address) {
         if (typeof address === 'string' && address.startsWith('w14:'))
             address = { paraId: address.substring(4) };
@@ -560,9 +845,22 @@ export class Body {
         let container;
         let element;
         for (const seg of tail === '' ? [] : tail.substring(1).split('/')) {
-            container = childrenOf(current);
+            if (seg.startsWith('textbox:')) {
+                // the n-th text box the paragraph here anchors, as the text model numbers them (CR-012 D4)
+                if (typeNameOf(element !== null && element !== void 0 ? element : {}) !== 'org_docx4j_wml.P')
+                    return undefined;
+                const n = Number(seg.substring('textbox:'.length));
+                const box = Number.isInteger(n) && n >= 0 ? textBoxesOf(current, this.hiddenRuns(current))[n] : undefined;
+                if (!(box === null || box === void 0 ? void 0 : box.content))
+                    return undefined; // none, or legacy WordArt: no paragraphs
+                current = box.content;
+                element = undefined;
+                container = undefined;
+                continue;
+            }
+            container = childrenOf(current, 'read');
             const i = Number(seg);
-            if (!container || !Number.isInteger(i) || i < 0 || i >= container.length)
+            if (!container || seg === '' || !Number.isInteger(i) || i < 0 || i >= container.length)
                 return undefined;
             element = container[i];
             current = element.value;
@@ -580,38 +878,38 @@ export class Body {
         const path = this.pathOf(target.element.value);
         return path ? [this.prefix, ...path].join('/') : undefined;
     }
-    /** What an agent asks for first: every paragraph and table with its address, style and text. */
-    outline() {
-        const paragraphs = [];
-        const tables = [];
-        const visit = (items, path) => {
-            items.forEach((el, i) => {
-                var _a, _b, _c, _d, _e;
-                const tn = typeNameOf(el);
-                const here = [...path, i];
-                const address = [this.prefix, ...here].join('/');
-                if (tn === 'org_docx4j_wml.P') {
-                    const p = el.value;
-                    const entry = { address, style: (_c = (_b = (_a = p.pPr) === null || _a === void 0 ? void 0 : _a.pStyle) === null || _b === void 0 ? void 0 : _b.val) !== null && _c !== void 0 ? _c : 'Normal', text: textOf(p) };
-                    if (p.paraId)
-                        entry.paraId = p.paraId;
-                    paragraphs.push(entry);
-                }
-                else if (tn === 'org_docx4j_wml.Tbl') {
-                    const rows = (_d = childrenOf(el.value)) !== null && _d !== void 0 ? _d : [];
-                    const cols = rows.length ? ((_e = childrenOf(rows[0].value)) !== null && _e !== void 0 ? _e : []).filter((c) => typeNameOf(c) === 'org_docx4j_wml.Tc').length : 0;
-                    tables.push({ address, rows: rows.filter((r) => typeNameOf(r) === 'org_docx4j_wml.Tr').length, cols });
-                    rows.forEach((row, ri) => { var _a; return ((_a = childrenOf(row.value)) !== null && _a !== void 0 ? _a : []).forEach((cell, ci) => { var _a; return visit((_a = childrenOf(cell.value)) !== null && _a !== void 0 ? _a : [], [...here, ri, ci]); }); });
-                }
-                else if (typeof el.value === 'object' && el.value !== null) {
-                    const children = childrenOf(el.value);
-                    if (children)
-                        visit(children, here);
-                }
-            });
-        };
-        visit(this.content, []);
-        return { paragraphs, tables };
+    /**
+     * What an agent asks for first: every paragraph and table with its address, style and text, read by the
+     * text model (CR-012 D3; `Texts.of`'s options, `TextOptionsInit`): each paragraph's text is the model's
+     * (hidden text left out, a paragraph whose mark the view deletes joined to the next, in the view asked
+     * for), and each text box's paragraphs follow their anchoring paragraph, or the table it is in (REQ-518),
+     * at `textbox:` addresses (`body/3/textbox:0/1`), flagged `textbox`. A cell's paragraphs and tables follow
+     * their table's entry.
+     * Async since phase 4, as the model's reading is; calls under one `TextContext` (`Texts.contextOf`) read
+     * the package's stories once. The package is not changed (REQ-204).
+     *
+     * With `select`, only some of this body's top-level blocks are read (CR-012 section 17.13): their entries
+     * are those the whole outline gives them under the same context and options, in document order. A
+     * paragraph whose text a paragraph before it holds (`joined`) gives none; a block that starts inside a
+     * field open before it (a table of contents left out, D12) is read inside it. Under a context, the first
+     * such call over a body walks its blocks' field characters once; each block after that costs its own
+     * reading. A context is a snapshot: after an edit, make another.
+     */
+    async outline(options, context, select) {
+        return outlineReader()(this, options, context, select === null || select === void 0 ? void 0 : select.blocks.map((b) => this.blockIndexOf(b)));
+    }
+    /** The index in `content` of one of this body's top-level blocks. */
+    blockIndexOf(block) {
+        const content = this.content;
+        if (typeof block === 'number') {
+            if (!Number.isInteger(block) || block < 0 || block >= content.length)
+                throw new Docx4JException(`${this.prefix} has no block ${block}`);
+            return block;
+        }
+        const i = block.container === content ? content.indexOf(block.element) : -1;
+        if (i < 0)
+            throw new Docx4JException(`Not one of ${this.prefix}'s top-level blocks: ${describe(block.element)}`);
+        return i;
     }
     // --- docx4j names ---
     /** docx4j MainDocumentPart.addParagraphOfText. */
@@ -707,7 +1005,7 @@ export class Body {
         return found;
     }
     pathOf(value) {
-        var _a;
+        var _a, _b;
         const path = [];
         let child = value;
         for (let guard = 0; guard < 64; guard++) {
@@ -728,25 +1026,46 @@ export class Body {
             path.unshift(i);
             if (parent === this.container)
                 return path;
+            if (BRANCH_TYPES.has((_b = parent.TYPE_NAME) !== null && _b !== void 0 ? _b : '')) {
+                // a kept mc:AlternateContent's branch is no level of its own (D2): what is in the selected one is
+                // addressed from the element, body/2/0; another branch's is not addressed, readers not seeing it
+                const ac = parent.PARENT;
+                if (!ac || selectedBranchOf(ac) !== children)
+                    return undefined;
+                child = ac;
+                continue;
+            }
+            if (parent.TYPE_NAME === 'org_docx4j_wml.CTTxbxContent') {
+                // a text box's block: addressed from the paragraph that anchors it, `textbox:n` its place among
+                // that paragraph's boxes; none for a box the text model doesn't number (another branch's, a hidden run's)
+                const anchor = anchorOf(parent);
+                const n = anchor ? textBoxesOf(anchor, this.hiddenRuns(anchor)).findIndex((box) => box.content === parent) : -1;
+                if (!anchor || n < 0)
+                    return undefined;
+                path.unshift(`textbox:${n}`);
+                child = anchor;
+                continue;
+            }
             child = parent;
         }
         return undefined;
     }
-    /** Gives a new paragraph a w14:paraId when the document already uses them. */
+    /**
+     * Gives a new paragraph a w14:paraId when the document already uses them, free in every branch (CR-013 phase 3).
+     * @internal a paragraph split (CR-014 phase 2) gives its new first half one.
+     */
     assignParaId(p) {
         if (p.paraId)
             return;
-        if (!this.usesParaIds())
+        const paragraphs = this.paragraphsIn('every');
+        if (!paragraphs.some((q) => q.paraId !== undefined))
             return;
         let id;
         do {
             id = Math.floor(Math.random() * 0x7fffffff).toString(16).toUpperCase().padStart(8, '0');
-        } while (this.paragraphs.some((q) => q.paraId === id));
+        } while (paragraphs.some((q) => q.paraId === id));
         p.paraId = id;
     }
-    usesParaIds() {
-        return this.paragraphs.some((q) => q.paraId !== undefined);
-    }
     // --- comments (CR-002 phase G) ---
     /**
      * The comments anchored in this body, in document order, with replies nested under their
@@ -763,6 +1082,7 @@ export class Body {
      * body. Returns the control.
      */
     insertContentControl(kind) {
+        this.assertWritable();
         const content = [...this.content];
         const sdt = sdtOf(content, { kind: sdtKindFor(kind), id: nextSdtId(controlIdScope(this)), form: 'block' });
         this.content.length = 0;
@@ -791,33 +1111,60 @@ function describe(el) {
     return `${(_b = (_a = el.name) === null || _a === void 0 ? void 0 : _a.localPart) !== null && _b !== void 0 ? _b : '?'} (${tn !== null && tn !== void 0 ? tn : 'no TYPE_NAME'})`;
 }
 /**
- * A story's tracked changes resolved (`Body.acceptAll` or `rejectAll`), then those of each text box in
- * it - a `w:txbxContent`, in a DrawingML shape or a VML one - which Word counts as a story of its own
- * (CR-002 section 49). A text box inside a text box is reached through its own story. Returns how many
- * changes were listed.
+ * A story's tracked changes resolved (`Body.acceptAll` or `rejectAll`, with the filter if one is given),
+ * then those of each text box in it - a `w:txbxContent`, in a DrawingML shape or a VML one - which Word
+ * counts as a story of its own (CR-002 section 49). A text box inside a text box is reached through its
+ * own story. Returns how many changes were listed (with a filter, how many had a matching piece).
  *
  * In a kept `mc:AlternateContent` the text box of every branch is resolved, so that each says the same
  * afterwards (docx4j's `McMode.ALL`), and the changes are counted in the selected branch alone, so a
  * text box held in both counts once, as a resolved load's does (CR-010 phase 3).
  */
-export function resolveStory(body, what) {
-    let count = what === 'accept' ? body.acceptAll() : body.rejectAll();
+export function resolveStory(body, what, filter) {
+    let count = what === 'accept' ? body.acceptAll(filter) : body.rejectAll(filter);
     for (const { box, selected } of textBoxesIn(body.container)) {
-        const resolved = resolveStory(body.sub(box), what);
+        const resolved = resolveStory(body.sub(box), what, filter);
         if (selected)
             count += resolved;
     }
     return count;
 }
+/**
+ * A story's tracked changes (`Body.getTrackedChanges`), then each text box's in it, as `resolveStory`
+ * resolves them: docx4j's order (its CR-043 `Lister`, CR-011). In a kept `mc:AlternateContent` the
+ * selected branch's text boxes alone are listed, so a text box held in both branches is listed once;
+ * each other branch's box at the same place is its twin, whose changes are paired with the listed ones
+ * by kind and position and resolved with them, as docx4j resolves a text box's `mc:Fallback` twin
+ * (`pairTwins`; CR-013 phase 3).
+ */
+export function trackedChangesOfStory(body) {
+    const out = body.getTrackedChanges();
+    for (const { box, selected, twins } of textBoxesIn(body.container)) {
+        if (!selected)
+            continue;
+        const changes = trackedChangesOfStory(body.sub(box));
+        for (const twin of twins !== null && twins !== void 0 ? twins : [])
+            pairTwins(changes, trackedChangesOfStory(body.sub(twin)));
+        out.push(...changes);
+    }
+    return out;
+}
+/**
+ * The members `textBoxesIn` does not descend into: an element's name, and properties, which hold no text box.
+ * Over every fixture the walk finds the same text boxes without them and visits 38% fewer objects (CR-012
+ * section 17.13: it was most of a plan's cost).
+ */
+const NO_TEXT_BOXES = new Set(['PARENT', 'name', 'pPr', 'rPr', 'tblPr', 'tblGrid', 'trPr', 'tcPr', 'sectPr', 'sdtPr', 'sdtEndPr']);
 /**
  * The `w:txbxContent` of every text box in a story's content, not descending into one found, each with
  * whether it is in a branch a reader takes: false inside a branch of a kept `mc:AlternateContent` other
- * than its selected one (`selectedBranchOf`).
+ * than its selected one (`selectedBranchOf`). A selected box in a branch has as twins the boxes at its
+ * place, by position, in the element's other branches (docx4j's `Lister.twins`).
  */
 function textBoxesIn(container) {
     const out = [];
     const seen = new Set();
-    const visit = (o, selected) => {
+    const visit = (o, selected, into) => {
         var _a;
         if (typeof o !== 'object' || o === null || seen.has(o))
             return;
@@ -826,25 +1173,46 @@ function textBoxesIn(container) {
         seen.add(o);
         if (Array.isArray(o)) {
             for (const item of o)
-                visit(item, selected);
+                visit(item, selected, into);
             return;
         }
         const typeName = o.TYPE_NAME;
         if (typeName === 'org_docx4j_wml.CTTxbxContent') {
-            out.push({ box: o, selected });
+            into.push({ box: o, selected });
             return;
         }
         if (typeName === ALTERNATE_CONTENT) {
             const ac = o;
             const read = selectedBranchOf(ac);
-            for (const branch of [...((_a = ac.choice) !== null && _a !== void 0 ? _a : []), ...(ac.fallback ? [ac.fallback] : [])])
-                visit(branch.any, selected && branch.any === read);
+            let primary = [];
+            const others = [];
+            for (const branch of [...((_a = ac.choice) !== null && _a !== void 0 ? _a : []), ...(ac.fallback ? [ac.fallback] : [])]) {
+                const found = [];
+                visit(branch.any, selected && branch.any === read, found);
+                into.push(...found);
+                if (branch.any === read)
+                    primary = found;
+                else
+                    others.push(found);
+            }
+            for (const found of others)
+                found.forEach(({ box }, i) => { var _a; const twin = primary[i]; if (twin)
+                    ((_a = twin.twins) !== null && _a !== void 0 ? _a : (twin.twins = [])).push(box); });
             return;
         }
         for (const key in o)
-            if (key !== 'PARENT')
-                visit(o[key], selected);
+            if (!NO_TEXT_BOXES.has(key))
+                visit(o[key], selected, into);
     };
-    visit(container.content, true);
+    visit(container.content, true, out);
     return out;
 }
+/** The paragraph a text box's content is anchored in: its nearest `w:p` ancestor. */
+function anchorOf(box) {
+    let o = box.PARENT;
+    for (let guard = 0; o && guard < 64; guard++, o = o.PARENT) {
+        if (o.TYPE_NAME === 'org_docx4j_wml.P')
+            return o;
+    }
+    return undefined;
+}