@docx4j/core-ts 0.4.0 → 0.6.0

package/dist/model/content/tracking.mjs

@@ -1,9 +1,9 @@
 import { deepCopy, deepCopyAsSync } from '@docx4j/generated-objects-ts';
 import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
-import { createCTTrackChange, createCTRPrChange, createCTRPrChangeRPr, createCTPPrChange, createCTMarkup, createDelText, createPPr, createParaRPr, createTrPr, } from '@docx4j/generated-objects-ts/factory/org_docx4j_wml';
+import { createCTTrackChange, createCTRPrChange, createCTRPrChangeRPr, createCTPPrChange, createCTMarkup, createDelText, createPPr, createParaRPr, createTrPr, createParaRPrChange, createCTParaRPrOriginal, } from '@docx4j/generated-objects-ts/factory/org_docx4j_wml';
 import { rPrToElements, rPrFromElements } from '@docx4j/generated-objects-ts/builders/wml';
 import { Docx4JException } from '../../opc/exceptions.mjs';
-import { W_NS, linkParents, walk, typeNameOf, revisionKindOf, childrenOf, rowsOf, cellsOf } from './tree.mjs';
+import { W_NS, linkParents, walk, typeNameOf, revisionKindOf, childrenOf, rowsOf, cellsOf, isAlternateContent, selectedBranchOf, branchesOf, ALTERNATE_CONTENT } from './tree.mjs';
 /**
  * `w:id` on these is the one annotation id space (ECMA-376 17.13.5.4): revisions, bookmarks,
  * comment range marks and permissions share it. `w:comment/@w:id` (docx4j `Comments.Comment`,
@@ -263,6 +263,31 @@ export class ChangeTracker {
         if (Object.keys(rPr).every((key) => key === 'TYPE_NAME'))
             delete run.rPr;
     }
+    /**
+     * Records a paragraph mark's formatting as it is now in its `w:rPrChange`, once: what a tracked `font`
+     * write over a range holding the mark writes (check 52 case 56: `<w:rPrChange><w:rPr/></w:rPrChange>`
+     * for a mark that had no formatting). The mark's own revisions (inserted, deleted) are not its formatting.
+     */
+    recordMarkRPrChange(rPr) {
+        if (rPr.rPrChange)
+            return;
+        const original = createCTParaRPrOriginal({ egrPrBase: rPrToElements(rPr) });
+        rPr.rPrChange = createParaRPrChange({ ...this.markup(), rPr: original });
+        linkParents(rPr.rPrChange, rPr);
+    }
+    /** `settleRPrChange` for a paragraph mark: its `w:rPrChange` goes where its formatting is back to what it recorded. */
+    settleMarkRPrChange(p) {
+        var _a, _b, _c;
+        const rPr = (_a = p.pPr) === null || _a === void 0 ? void 0 : _a.rPr;
+        const change = rPr === null || rPr === void 0 ? void 0 : rPr.rPrChange;
+        if (!rPr || !change)
+            return;
+        const { rPrChange: _recorded, ins: _ins, del: _del, moveFrom: _from, moveTo: _to, ...current } = rPr;
+        if (canonical(current) !== canonical(rPrFromElements((_c = (_b = change.rPr) === null || _b === void 0 ? void 0 : _b.egrPrBase) !== null && _c !== void 0 ? _c : [])))
+            return;
+        delete rPr.rPrChange;
+        pruneParagraphProperties(p);
+    }
     /** Records the paragraph's properties as they are now in `w:pPrChange`, once. */
     recordPPrChange(pPr) {
         if (pPr.pPrChange)
@@ -373,11 +398,12 @@ export function wrapInsertedRuns(tracker, items, parent) {
 /** A whole table inserted: every row is marked inserted and everything in its cells is an insertion (`trackInsertedBlocks`). */
 export function trackInsertedTable(tracker, tbl) {
     var _a;
-    for (const row of rowsOf(tbl)) {
+    // every branch of a kept row- or cell-level mc:AlternateContent (CR-013 phase 3)
+    for (const row of rowsOf(tbl, 'every')) {
         const tr = row.element.value;
         if (!((_a = tr.trPr) === null || _a === void 0 ? void 0 : _a.ins))
             tracker.markRowInserted(tr);
-        for (const cell of cellsOf(tr))
+        for (const cell of cellsOf(tr, 'every'))
             trackInsertedBlocks(tracker, childrenOf(cell.element.value));
     }
 }
@@ -398,6 +424,10 @@ export function trackInsertedBlock(tracker, block, owner) {
         return;
     else if (HOLDER_TYPES.has(tn !== null && tn !== void 0 ? tn : ''))
         markHolderInserted(tracker, block, owner, () => trackInsertedBlocks(tracker, childrenOf(block.value)));
+    // a kept block-level mc:AlternateContent: every branch's content (CR-013 phase 3)
+    else if (tn === ALTERNATE_CONTENT)
+        for (const branch of branchesOf(block.value))
+            trackInsertedBlocks(tracker, branch);
     else
         trackInsertedBlocks(tracker, childrenOf(block.value));
 }
@@ -443,6 +473,18 @@ export function holderItemsOf(value) {
  * pairs, so that the ids run in document order as Word's do.
  */
 export function markHolderInserted(tracker, holder, owner, inside) {
+    markHolder(tracker, holder, owner, inside, 'ins');
+}
+/**
+ * A content control or custom XML element deleted under tracking, as Word writes it (check 54 cases 15 and 17, a
+ * range across paragraphs holding a whole control): `markHolderInserted`'s form with `w:customXmlDelRangeStart` and
+ * `w:customXmlDelRangeEnd`, its content marked deleted between the two pairs (`inside`). Accepting takes the element
+ * away; rejecting, the markers (`TrackedChange`'s `holder` target).
+ */
+export function markHolderDeleted(tracker, holder, owner, inside) {
+    markHolder(tracker, holder, owner, inside, 'del');
+}
+function markHolder(tracker, holder, owner, inside, revision) {
     var _a;
     const at = owner.indexOf(holder);
     const items = holderItemsOf(holder.value);
@@ -450,16 +492,17 @@ export function markHolderInserted(tracker, holder, owner, inside) {
         inside();
         return;
     }
+    const [start, end] = revision === 'ins' ? [el.customXmlInsRangeStart, el.customXmlInsRangeEnd] : [el.customXmlDelRangeStart, el.customXmlDelRangeEnd];
     const value = holder.value;
     const first = tracker.markup();
-    const outerStart = el.customXmlInsRangeStart(createCTTrackChange(first));
-    const innerEnd = el.customXmlInsRangeEnd(createCTMarkup({ id: first.id }));
+    const outerStart = start(createCTTrackChange(first));
+    const innerEnd = end(createCTMarkup({ id: first.id }));
     owner.splice(at, 0, outerStart);
     items.unshift(innerEnd);
     inside();
     const second = tracker.markup();
-    const innerStart = el.customXmlInsRangeStart(createCTTrackChange(second));
-    const outerEnd = el.customXmlInsRangeEnd(createCTMarkup({ id: second.id }));
+    const innerStart = start(createCTTrackChange(second));
+    const outerEnd = end(createCTMarkup({ id: second.id }));
     items.push(innerStart);
     owner.splice(owner.indexOf(holder) + 1, 0, outerEnd);
     linkParents([outerStart, outerEnd], value.PARENT);
@@ -505,6 +548,87 @@ export function markInserted(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;
 }
+// --- an equation deleted (CR-002 section 62.2, D2) ----------------------------------------
+/** Each equation structure's properties, whose `m:ctrlPr` marks the structure inserted or deleted (CR-002 section 51). */
+const MATH_STRUCTURES = Object.fromEntries(['Acc', 'Bar', 'BorderBox', 'Box', 'D', 'EqArr', 'F', 'Func', 'GroupChr', 'LimLow', 'LimUpp', 'M', 'Nary', 'Phant', 'Rad', 'SPre', 'SSub', 'SSubSup', 'SSup']
+    .map((n) => [`org_docx4j_math.CT${n}`, `${n[0].toLowerCase()}${n.slice(1)}Pr`]));
+/**
+ * An equation (`m:oMath`, `m:oMathPara`) marked deleted where it stands, in Word's form (check 57 cases 7 to 10): each
+ * math run's content inside a `w:del` in its `m:r`, and each structure's `m:ctrlPr` holding a `w:del` around its run
+ * properties, as Word's tracked `delete()` writes them. An argument's own `m:ctrlPr` marks no structure, and is left as
+ * it is. An equation holding a revision of its own (`equationRevisionIn`) is the caller's to put in a `w:del` whole.
+ */
+export function markEquationDeleted(tracker, equation) {
+    const visit = (value, depth) => {
+        var _a;
+        if (typeof value !== 'object' || value === null || depth > 64)
+            return;
+        if (Array.isArray(value)) {
+            for (const v of value)
+                visit(v, depth + 1);
+            return;
+        }
+        const named = value;
+        if (named.name !== undefined && 'value' in named) {
+            visit(named.value, depth + 1);
+            return;
+        }
+        const tn = (_a = value.TYPE_NAME) !== null && _a !== void 0 ? _a : '';
+        if (!tn.startsWith('org_docx4j_math.') || tn.endsWith('Pr'))
+            return;
+        if (tn === 'org_docx4j_math.CTR') {
+            deleteMathRun(tracker, value);
+            return;
+        }
+        const key = MATH_STRUCTURES[tn];
+        if (key !== undefined)
+            deleteMathStructure(tracker, value, tn, key);
+        for (const k of Object.keys(value))
+            if (k !== 'PARENT' && k !== 'TYPE_NAME' && k !== key)
+                visit(value[k], depth + 1);
+    };
+    visit(equation, 0);
+}
+/** A math run's content moved into a `w:del` in it (`CT_MathRunTrackChange`), its `m:t` kept as `m:t`, as Word writes it. */
+function deleteMathRun(tracker, run) {
+    var _a;
+    const content = ((_a = run.content) !== null && _a !== void 0 ? _a : (run.content = []));
+    const value = { TYPE_NAME: 'org_docx4j_wml.CTMathRunTrackChange', ...tracker.markup(), rest: content.splice(0) };
+    const del = element('del', value);
+    linkParents(value.rest, value);
+    content.push(del);
+    linkParents(del, run);
+}
+/** A structure's `m:ctrlPr` holding a `w:del` with the run properties it had, its properties made where it had none. */
+function deleteMathStructure(tracker, structure, tn, key) {
+    var _a, _b;
+    const properties = ((_a = structure[key]) !== null && _a !== void 0 ? _a : (structure[key] = { TYPE_NAME: `${tn}Pr` }));
+    const ctrlPr = ((_b = properties.ctrlPr) !== null && _b !== void 0 ? _b : (properties.ctrlPr = { TYPE_NAME: 'org_docx4j_math.CTCtrlPr' }));
+    const rPr = createCTRPrChangeRPr({ egrPrBase: ctrlPr.rPr ? rPrToElements(ctrlPr.rPr) : [] });
+    ctrlPr.del = createCTRPrChange({ ...tracker.markup(), rPr });
+    delete ctrlPr.rPr;
+    linkParents(properties, structure);
+}
+/**
+ * A revision an equation holds of its own, or undefined: a math run's, a structure's or an argument's, or a `w:ins` or
+ * `w:del` among its runs. How Word deletes such an equation isn't measured, so a tracked deletion puts it whole in a
+ * `w:del`, the form this package wrote for every equation before (CR-002 section 62.2, D2).
+ */
+export function equationRevisionIn(equation) {
+    let found;
+    walk(equation, (value) => {
+        if (found)
+            return;
+        const tn = value.TYPE_NAME;
+        if (tn === 'org_docx4j_wml.CTMathRunTrackChange')
+            found = 'a math run\'s revision';
+        else if (tn === 'org_docx4j_wml.RunIns' || tn === 'org_docx4j_wml.RunDel' || tn === 'org_docx4j_wml.RunTrackChange')
+            found = 'a revision among its runs';
+        else if (tn === 'org_docx4j_math.CTCtrlPr' && (value.ins || value.del))
+            found = 'a structure\'s revision';
+    });
+    return found;
+}
 // --- w:t <-> w:delText -------------------------------------------------------------------
 const DELETED_NAME = { t: 'delText', instrText: 'delInstrText' };
 const RESTORED_NAME = { delText: 't', delInstrText: 'instrText' };
@@ -517,11 +641,26 @@ export function toRestoredText(run) {
     rename(run, RESTORED_NAME, false);
 }
 function rename(run, table, deleting) {
-    const content = run.content;
+    renameIn(run.content, run, table, deleting);
+}
+/**
+ * `rename` over a run's items, and over a kept `mc:AlternateContent`'s selected branch among them: a
+ * deletion of a branch's text writes the selected branch's `w:delText` and keeps the other branches as
+ * they were (CR-012 section 12.2, the editor's ED-009 section 3.6).
+ */
+function renameIn(content, parent, table, deleting) {
+    var _a, _b, _c;
     if (!content)
         return;
     for (let i = 0; i < content.length; i++) {
         const item = content[i];
+        if (isAlternateContent(item)) {
+            const branch = selectedBranchOf(item.value);
+            const holder = branch === undefined ? undefined : ((_c = (_b = (_a = branch[0]) === null || _a === void 0 ? void 0 : _a.value) === null || _b === void 0 ? void 0 : _b.PARENT) !== null && _c !== void 0 ? _c : parent);
+            if (branch && holder)
+                renameIn(branch, holder, table, deleting);
+            continue;
+        }
         const to = table[item.name.localPart];
         if (to === undefined)
             continue;
@@ -530,7 +669,7 @@ function rename(run, table, deleting) {
             ? createDelText({ value: v.value, ...(v.space === undefined ? {} : { space: v.space }) })
             : { TYPE_NAME: 'org_docx4j_wml.Text', value: v.value, ...(v.space === undefined ? {} : { space: v.space }) };
         content[i] = element(to, value);
-        linkParents(content[i], run);
+        linkParents(content[i], parent);
     }
 }
 // --- w:rPr <-> w:rPrChange/w:rPr ---------------------------------------------------------

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

@@ -1,4 +1,5 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import type * as mce from '@docx4j/generated-objects-ts/modules/org_docx4j_mce';
 import { isElement, runItemsOf, type Element } from '@docx4j/generated-objects-ts/builders/wml';
 export { isElement, typeNameOf, walk, find, linkParents, textOf, W_NS, type Element } from '@docx4j/generated-objects-ts/builders/wml';
 /** The two views of a tracked document: as it will read once accepted, or as it read before the changes. */
@@ -7,6 +8,78 @@ export interface TextViewOptions {
     /** 'accepted' (the default: w:ins included, w:del excluded) or 'original' (the other way). */
     view?: TextView;
 }
+/** Whether a run is hidden: its effective `w:vanish` (`hiddenRunsOf` makes one for a paragraph). */
+export type HiddenRuns = (run: wml.R) => boolean;
+/** `segmentsOf`'s options: a view, whether drawn objects get a segment of their own, which runs are hidden. */
+export interface SegmentOptions extends TextViewOptions {
+    /**
+     * True to list each picture or other drawn object (`OBJECT_ITEMS`) as a segment of no text at its
+     * place in the text (`object` set), so that a deletion of a span can find it (CR-002 section 48).
+     * Hidden runs' items are listed with them.
+     */
+    objects?: boolean;
+    /**
+     * Which runs are hidden. Office JS's text leaves hidden text out, a run's own `w:vanish` or its
+     * styles' (check 48b), so `Paragraph.text` does too (CR-012 phase 4): a hidden run's items take no
+     * offset, and are listed only with the objects, each `object` and `hidden`, so that a span's deletion
+     * takes the hidden text strictly inside it as it takes a picture. Undefined: no run is hidden.
+     */
+    hidden?: HiddenRuns;
+    /**
+     * Called for every element the walk passes that adds no text: each element of a run holder's list
+     * (runs, revision holders, markers, before it is entered) and each item of a run that adds none (a
+     * comment reference, a field character, a drawing, a hidden run's text), with the offset it stands at,
+     * the list holding it and its run. What gives a comment marker or a revision its offset in the same text.
+     */
+    visit?: (item: Element, at: number, owner: Element[], run: {
+        element: Element<wml.R>;
+        owner: Element[];
+    } | undefined) => void;
+    /**
+     * `office` (the default): Office JS's characters (`officeItemText`), a kept `mc:AlternateContent`'s
+     * selected branch read, an equation's drawn text. `textOf`: the characters of the objects package's
+     * `textOf` and docx4j's `TextUtils`, as this function read before CR-012 phase 4 (a break `\n`, the
+     * hyphens U+2011 and U+00AD, a symbol its code point, a note reference nothing), a run-level element
+     * one object, a paragraph-level one and an equation nothing: what a tracked change's `text` is, which
+     * the revisions goldens hold to docx4j's.
+     */
+    characters?: 'office' | 'textOf';
+}
+/**
+ * Run content that stands in the text and has no text of its own: a `w:drawing` (a picture, a chart, a
+ * text box), a VML `w:pict` and an embedded `w:object`. Office JS counts an inline picture as in a
+ * range, so a span's deletion takes the objects in it (CR-002 section 48). A kept `mc:AlternateContent`
+ * in a run is one such object too, whatever its branches hold (`ALTERNATE_CONTENT`, CR-010 phase 3).
+ */
+export declare const OBJECT_ITEMS: ReadonlySet<string>;
+/** The TYPE_NAME of a kept `mc:AlternateContent` (the default load since CR-010 phase 4; under `KEPT_HOSTS` with `mcePreprocess: true`). */
+export declare const ALTERNATE_CONTENT = "org_docx4j_mce.AlternateContent";
+/**
+ * The branch of a kept `mc:AlternateContent` the content API reads (docx4j's `McMode.READ`, CR-010
+ * phase 3): the objects package's `mcBranchOf` over `READ_UNDERSTOOD_PREFIXES`, the prefixes load
+ * understands and the four Word 365 understands that load leaves alone (CR-010 section 15). So a reader
+ * takes the branch the preprocessor would have resolved the element to, unless a Choice requires one of
+ * those four: then it takes that Choice, as Word does, where a resolved load takes the next one or the
+ * Fallback. A mutator walks every branch instead (docx4j's `McMode.ALL`). Undefined for an element with
+ * no branches.
+ */
+export declare function selectedBranchOf(value: mce.AlternateContent | undefined): Element[] | undefined;
+/** True for a kept `mc:AlternateContent`: its element pair, or its value. */
+export declare function isAlternateContent(value: unknown): boolean;
+/**
+ * Which objects at a span's edges are in the span. An object stands between two characters, so one at
+ * a span's start or end offset may be inside it or outside it, and offsets alone cannot say which. A
+ * paragraph's whole range holds the objects at both of its edges (`WHOLE`); a span of text, such as a
+ * search found, holds only the objects strictly inside it (CR-002 section 48).
+ */
+export interface SpanEdges {
+    start: boolean;
+    end: boolean;
+}
+/** Both edges: the objects at a span's start and at its end are in it. */
+export declare const WHOLE: SpanEdges;
+/** True when an object at offset `at` is in the span [start, end) with these edges. */
+export declare function objectInSpan(at: number, start: number, end: number, edges?: SpanEdges): boolean;
 /** The four run-level revision holders (CR-002 phase F); their runs live under `customXmlOrSmartTagOrSdt`. */
 export type RevisionKind = 'ins' | 'del' | 'moveFrom' | 'moveTo';
 /** The run-level revision a run sits in. */
@@ -37,44 +110,170 @@ export interface TextSegment {
     end: number;
     /** True for w:t: text that can be edited in place. */
     editable: boolean;
+    /** True for a drawn object (`OBJECT_ITEMS`, or a kept `mc:AlternateContent`), whose segment has no text: listed only when asked for. */
+    object?: boolean;
     /**
      * The nearest enclosing w:ins / w:del / w:moveFrom / w:moveTo, when the run is in one.
      * A deletion of this run goes inside it (`runOwner` is already its item list); an insertion
      * next to it goes beside it (`revision.owner`) unless the same author may extend it.
      */
     revision?: RevisionHolder;
+    /**
+     * An item of a hidden run (`SegmentOptions.hidden`): no text, listed with the objects, `object` set too;
+     * a drawing in a hidden run is one (Word's default view doesn't show it: `search`'s `^g` passes it by).
+     */
+    hidden?: boolean;
+    /**
+     * An equation (`m:oMath`, `m:oMathPara`): one segment holding its text as Word draws it
+     * (`mathTextOf`). `item` is the equation and `owner` the list holding it, as `runOwner` is; `run`
+     * is a frozen stand-in, since an equation is in no run. An edit may take it whole, not in part.
+     */
+    math?: boolean;
+    /**
+     * The kept `mc:AlternateContent` whose selected branch holds this item (a run-level element) or its
+     * run (a paragraph-level one), the innermost: an edit lands in that branch, the others kept as they
+     * were read (CR-012 section 12.2).
+     */
+    alternate?: AlternateLocation;
+}
+/** Where a kept `mc:AlternateContent` whose selected branch holds text stands (CR-012 section 12.2). */
+export interface AlternateLocation {
+    /** The element pair. */
+    element: Element;
+    /** The array holding it: a run's content (`run` level) or a run holder's list (`paragraph` level). */
+    owner: Element[];
+    /** Its selected branch's items (`selectedBranchOf`). */
+    branch: Element[];
+    /** `run`: the element is run content and its branch holds run items; `paragraph`: it stands among runs and its branch holds runs. */
+    level: 'run' | 'paragraph';
 }
 /** Types whose value holds runs (directly or through sdtContent); the revision holders are separate. */
 declare const RUN_HOLDERS: Set<string>;
 /** The kind of a run-level revision element, by its name; undefined when it is not one. */
 export declare function revisionKindOf(el: Element): RevisionKind | undefined;
 export { runItemsOf };
+/**
+ * An item's text in Office JS's text, Word's own character stream (CR-012 phase 4; check 48, Word 365):
+ * a `w:br` U+000B, of type page U+000C and column U+000E; a `w:cr` U+000D; a `w:ptab` `0`; the
+ * non-breaking and optional hyphens U+001E and U+001F; any `w:sym` `(`, whatever its font or code
+ * (check 48b); a footnote or endnote reference U+0002, and so the note's own mark (`w:footnoteRef`,
+ * `w:endnoteRef`, not measured). Undefined for an item that adds no text: a comment reference, a
+ * field's characters and code, a drawing.
+ */
+export declare function officeItemText(item: Element): string | undefined;
+/**
+ * The item text the revision listings and the text model's plan count (`itemTextOf`): whether a run
+ * holds text, in the characters `textOf` gives. Not Office JS's (`officeItemText`).
+ */
 declare function itemText(item: Element): string | undefined;
 /**
- * The text segments of a paragraph (or any run holder) in order. The default view is the
- * accepted one: the runs of a `w:ins` or `w:moveTo` count, those of a `w:del` or `w:moveFrom`
- * do not. `{ view: 'original' }` is the other way round (CR-002 phase F).
+ * The text segments of a paragraph (or any run holder) in order, in Office JS's characters
+ * (`officeItemText`). The default view is the accepted one: the runs of a `w:ins` or `w:moveTo`
+ * count, those of a `w:del` or `w:moveFrom` do not. `{ view: 'original' }` is the other way round
+ * (CR-002 phase F). `{ objects: true }` lists the drawn objects too, each a segment of no text where
+ * it stands (CR-002 section 48), and the items of hidden runs (`hidden`).
+ *
+ * A kept `mc:AlternateContent` reads as its selected branch (CR-012 section 12.2, ED-009): in a run,
+ * a branch holding run items reads as those items, at the run's offsets, and one holding a drawing,
+ * a picture or an object is one object segment, as a drawing is (CR-010 phase 3); among a paragraph's
+ * runs, it reads as the runs its branch holds. Either way the segments carry `alternate`, so that an
+ * edit lands in that branch. An equation is one segment of its drawn text (`math`).
+ */
+export declare function segmentsOf(container: object, options?: SegmentOptions): TextSegment[];
+/** What `hiddenRunsOf` asks of a `PropertyResolver`. */
+export interface VanishResolver {
+    isVanishedByStyles(paragraphStyleId: string | undefined, runStyleId: string | undefined): boolean;
+}
+/**
+ * Which of a paragraph's runs are hidden, as the text model's rule has it (REQ-507) and Office JS's text
+ * leaves them out (check 48b): a run's own `w:vanish`, else its paragraph style's and character style's.
+ * Without a resolver only a run's own counts.
+ */
+export declare function hiddenRunsOf(resolver: VanishResolver | undefined, p: wml.P): HiddenRuns;
+/**
+ * Whether a run is in a content control showing its placeholder (`w:showingPlcHdr`), run-level or block-level, up its
+ * `PARENT`s. Office JS reads a placeholder as no text, and finds no text there to keep (check 53 cases 34 and 35, check 58
+ * cases 11 and 12; CR-012 section 18), so the readers take its runs as they take hidden ones.
+ */
+export declare function inShowingPlaceholder(run: object): boolean;
+/** The text of a paragraph or container in one of the two views, in Office JS's characters (`segmentsOf`). */
+export declare function textOfView(container: object, options?: SegmentOptions): string;
+/**
+ * The runs of a paragraph, direct and nested in hyperlinks, content controls and insertions, in order,
+ * and in the selected branch of a kept `mc:AlternateContent` among them (CR-012 section 12.2).
  */
-export declare function segmentsOf(container: object, options?: TextViewOptions): TextSegment[];
-/** The text of a paragraph or container in one of the two views (`textOf` is the accepted one). */
-export declare function textOfView(container: object, options?: TextViewOptions): string;
-/** The runs of a paragraph, direct and nested in hyperlinks, content controls and insertions, in order. */
 export declare function runsOf(container: object, options?: TextViewOptions): Element<wml.R>[];
+/** The TYPE_NAMEs of a kept `mc:AlternateContent`'s branches, whose items are their `any`. */
+export declare const BRANCH_TYPES: ReadonlySet<string>;
+/**
+ * How a walk takes a kept `mc:AlternateContent` among blocks, rows or cells (CR-013): `'read'`, a reader's,
+ * its selected branch (`selectedBranchOf`), as Word reads it; `'every'`, a mutator's, every branch, Choices
+ * first (phase 3). With no mode the element is stepped over, as every walk did before CR-013 phase 2.
+ */
+export type BranchMode = 'read' | 'every';
 /**
  * The block-level children of a container: body, header, footer, cell, sdt content, table (rows),
  * row (cells). A content control of any kind (block, row, cell, run) answers with its
- * `sdtContent`'s content, so that a traversal does not have to know the four types.
+ * `sdtContent`'s content, so that a traversal does not have to know the four types. A branch of a kept
+ * `mc:AlternateContent` (a Choice or the Fallback) answers with its items, so that a locator climbing
+ * `PARENT` from a branch's paragraph, row or cell finds the list it is in; the element itself answers
+ * in a reader's walk (`'read'`) with its selected branch (CR-013 phase 2), and otherwise not at all.
+ */
+export declare function childrenOf(value: object, mode?: 'read'): Element[] | undefined;
+/** Every branch of a kept `mc:AlternateContent`, the Choices in order, then the Fallback. */
+export declare function branchesOf(value: mce.AlternateContent): Element[][];
+/**
+ * Runs a bulk edit that reaches every branch of a kept `mc:AlternateContent` (CR-013 phase 3): a
+ * `replaceText`, a tracked clear or row deletion, the binding passes. Inside it the views it makes of
+ * what is in a branch write, where a caller's view refuses (D4): the edit itself reaches every branch,
+ * the selected one and the others alike, as CR-010's rule has mutators do.
+ */
+export declare function writingEveryBranch<T>(edit: () => T): T;
+/**
+ * Refuses a write through a view in a branch of a kept `mc:AlternateContent` at block, row or cell level
+ * (CR-013 D4): the view reads the selected branch, and a write would have to reach the element's other
+ * branches too, which nothing maps. A bulk edit reaching every branch writes there (`writingEveryBranch`).
+ * `className` is Office JS's ('Paragraph', 'Body').
+ */
+export declare function assertOutsideBranch(value: object | undefined, className: string, what?: string): void;
+/**
+ * True for a value inside a branch of a kept `mc:AlternateContent` at block, row or cell level: a
+ * paragraph, table, row, cell or content control a reader sees in the selected branch (CR-013 phase 2).
+ * A view of one is read-only (D4). From `PARENT` links; a run-level element's content is not reached
+ * from a paragraph, which is outside it.
+ */
+export declare function inBranch(value: object | undefined): boolean;
+/**
+ * True for a value no reader sees: inside a branch of a kept `mc:AlternateContent` other than the one
+ * `selectedBranchOf` takes, at any depth (CR-013 phase 3). What a bulk edit writes there it does not
+ * count, as resolve-all counts the listed changes: the count is of what a reader sees.
  */
-export declare function childrenOf(value: object): Element[] | undefined;
+export declare function inUnreadBranch(value: object | undefined): boolean;
+/**
+ * The lists a walk takes for a kept `mc:AlternateContent` among blocks, rows or cells: a reader's
+ * (`'read'`) its selected branch, a mutator's (`'every'`) every branch, the Choices first.
+ */
+export declare function branchListsOf(value: mce.AlternateContent, mode: BranchMode): Element[][];
 /** An element with the array that holds it: what a view needs to edit it in place. */
 export interface Located<T = unknown> {
     element: Element<T>;
     container: Element[];
 }
-/** The rows of a table, in order, descending into row-level content controls (an OpenDoPE repeat). */
-export declare function rowsOf(tbl: object): Located<wml.Tr>[];
-/** The cells of a row, in order, descending into cell-level content controls. */
-export declare function cellsOf(tr: object): Located<wml.Tc>[];
+/**
+ * The rows of a table, in order, descending into row-level content controls (an OpenDoPE repeat), and,
+ * with a mode, into a row-level `mc:AlternateContent` (`BranchMode`; CR-013 phase 2).
+ */
+export declare function rowsOf(tbl: object, mode?: BranchMode): Located<wml.Tr>[];
+/** The cells of a row, in order, descending into cell-level content controls, and with a mode into a cell-level `mc:AlternateContent`. */
+export declare function cellsOf(tr: object, mode?: BranchMode): Located<wml.Tc>[];
+/**
+ * A row's cells as laid along the grid, one list per reading of the row (docx4j's `Lister.cellLayoutsOf`,
+ * its CR-051 phase 2): the selected branches' first (`cellsOf(tr, 'read')`), then, for each cell-level
+ * `mc:AlternateContent` and each of its other branches, the row read with that branch in the element's
+ * place. Every branch spans the same grid columns, so every cell is in some list at its grid position:
+ * what a pass over the grid's columns walks (`collapseGrid`, the column passes; CR-013 phase 3).
+ */
+export declare function cellLayoutsOf(tr: object): Located<wml.Tc>[][];
 /** Content controls: `w:sdt` at block, row, cell and run level, by TYPE_NAME. */
 export declare const SDT_TYPES: Set<string>;
 /** True for what a body or cell may hold directly (the Body content union), by TYPE_NAME. */