@docx4j/core-ts 0.1.0 → 0.1.1

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

@@ -0,0 +1,104 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import { type Element, type RevisionHolder } from './tree.mjs';
+import type { Author } from './comments.mjs';
+/** Office JS `Word.ChangeTrackingMode`. */
+export type ChangeTrackingMode = 'Off' | 'TrackAll' | 'TrackMineOnly';
+/** What a package offers so that its edits can be tracked; `WordprocessingMLPackage` implements it. */
+export interface TrackingHost {
+    /**
+     * The revision author (Office JS takes it from the signed-in user; here it is the package's).
+     * The same `author` phase G's comments use, so a revision and a comment made in one session
+     * carry one identity; only its `name` reaches `w:author`.
+     */
+    readonly author: Author;
+    /** A fixed date for new revisions; `undefined` means now, read once per revision. */
+    readonly trackedChangeDate?: Date | undefined;
+    /** The trees to scan for the highest annotation id in use: the parts already unmarshalled. */
+    markupRoots(): object[];
+}
+/** The tracker of a package whose mode is not `Off`; `undefined` when it is (duck typed, no import cycle). */
+export declare function trackerOf(pkg: unknown): ChangeTracker | undefined;
+/** An `XmlCalendar` in UTC, as Word writes `w:date` (an xsd:dateTime ending in `Z`). */
+export declare function calendarOf(date: Date): wml.XmlCalendar;
+/** The `Date` of a `w:date`, or undefined when there is none. */
+export declare function dateOf(cal: wml.XmlCalendar | undefined): Date | undefined;
+/**
+ * The per-package writer of revision markup. Created by the package while
+ * `changeTrackingMode` is not `Off`; every content-API mutation asks its `Body` for one and,
+ * when it gets one, writes revisions instead of editing in place.
+ *
+ * Departure from docx4j, which has no such class: docx4j leaves revision markup to the caller.
+ * The name follows Office JS's vocabulary (`Word.ChangeTrackingMode`).
+ */
+export declare class ChangeTracker {
+    readonly host: TrackingHost;
+    readonly mode: ChangeTrackingMode;
+    private counter;
+    constructor(host: TrackingHost, mode: ChangeTrackingMode);
+    /** The `w:author` a new revision carries: the package author's name. */
+    get author(): string;
+    /** The next annotation id: one above the highest in use in the parts already unmarshalled. */
+    nextId(): number;
+    /** The `w:id`, `w:author` and `w:date` a new revision carries. */
+    markup(): {
+        id: number;
+        author: string;
+        date: wml.XmlCalendar;
+    };
+    /** A `w:ins` / `w:del` attribute set: the id, this package's author and the date. */
+    trackChange(): wml.CTTrackChange;
+    /** `w:ins` around run-level items (they go under `customXmlOrSmartTagOrSdt`, not `content`). */
+    ins(items: Element[]): Element<wml.RunIns>;
+    /** `w:del` around run-level items; the caller has already turned their `w:t` into `w:delText`. */
+    del(items: Element[]): Element<wml.RunDel>;
+    /** True when this revision is an insertion this package's author may extend rather than nest in. */
+    ownInsertion(revision: RevisionHolder | undefined): boolean;
+    /** Refuses an edit that would change deleted text; rejecting the deletion first is the way. */
+    assertEditable(revision: RevisionHolder | undefined): void;
+    /** Records the run's properties as they are now in `w:rPrChange`, once (a later write keeps the first original). */
+    recordRPrChange(rPr: wml.RPr): void;
+    /** Records the paragraph's properties as they are now in `w:pPrChange`, once. */
+    recordPPrChange(pPr: wml.PPr): void;
+    /** `w:pPr/w:rPr/w:ins`: the paragraph mark is an insertion. */
+    markParagraphInserted(p: wml.P): void;
+    /** `w:pPr/w:rPr/w:del`: the paragraph mark is deleted (accepting joins the paragraph with the next). */
+    markParagraphDeleted(p: wml.P): void;
+    /** `w:trPr/w:ins`: the table row is an insertion (CR-002 phase C's `Table` calls this). */
+    markRowInserted(tr: wml.Tr): void;
+    /** `w:trPr/w:del`: the table row is deleted. */
+    markRowDeleted(tr: wml.Tr): void;
+}
+/**
+ * A whole paragraph inserted: the mark is marked inserted and every run of it goes into a
+ * `w:ins`. Word, splitting a paragraph, marks the *first* paragraph's mark instead and leaves
+ * the new one the original mark; marking the new paragraph's own mark is the same document once
+ * accepted or rejected and keeps the edit to the element that was added (CR-002 section 13).
+ */
+export declare function trackInsertedParagraph(tracker: ChangeTracker, p: wml.P): void;
+/** Every top-level run of the paragraph that is not already in a revision, wrapped in one `w:ins` per group. */
+export declare function wrapNewRuns(tracker: ChangeTracker, p: wml.P): void;
+/** A whole table inserted: every row is marked inserted and every paragraph in it is an insertion. */
+export declare function trackInsertedTable(tracker: ChangeTracker, tbl: wml.Tbl): void;
+/** The paragraph mark's run properties (`w:pPr/w:rPr`), created when absent. */
+export declare function paraRPrOf(p: wml.P): wml.ParaRPr;
+/** The row's properties (`w:trPr`), created when absent. */
+export declare function rowPrOf(tr: wml.Tr): wml.TrPr;
+/** Drops `w:pPr/w:rPr` and `w:pPr` once nothing is left in them, so that accepting or rejecting leaves no husk. */
+export declare function pruneParagraphProperties(p: wml.P): void;
+/** True when a paragraph's mark is marked deleted. */
+export declare function markDeleted(p: wml.P): boolean;
+/** True when a paragraph's mark is marked inserted. */
+export declare function markInserted(p: wml.P): boolean;
+/** Turns a run's `w:t` into `w:delText` and `w:instrText` into `w:delInstrText`, in place. */
+export declare function toDeletedText(run: wml.R): void;
+/** The inverse, for `reject()` of a deletion. */
+export declare function toRestoredText(run: wml.R): void;
+/** Replaces a run's direct formatting with `original`, keeping nothing of what is there. */
+export declare function restoreRPr(holder: {
+    rPr?: wml.RPr;
+}, original: wml.RPr): void;
+/** Replaces a paragraph's properties with `original` (a `w:pPrChange/w:pPr`), keeping the mark and the section. */
+export declare function restorePPr(p: wml.P, original: wml.PPrBase | undefined): void;
+/** A copy of a run's direct formatting for a new run: the recorded original (`w:rPrChange`) is not carried over. */
+export declare function copyRPr(rPr: wml.RPr | undefined): wml.RPr | undefined;
+export type { RevisionHolder, RevisionKind } from './tree.mjs';

package/dist/model/content/tracking.mjs

@@ -0,0 +1,313 @@
+import { deepCopy, deepCopyAsSync } from '@docx4j/generated-objects-ts';
+import { createCTTrackChange, createCTRPrChange, createCTRPrChangeRPr, createCTPPrChange, createDelText, createPPr, createParaRPr, createTrPr, } from '@docx4j/generated-objects-ts/factory/org_docx4j_wml';
+import { rPrToElements } from '@docx4j/generated-objects-ts/builders/wml';
+import { Docx4JException } from '../../opc/exceptions.mjs';
+import { W_NS, linkParents, walk, typeNameOf, revisionKindOf } 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`,
+ * which also extends `CTMarkup`) is a different space and is excluded, so that phase G's
+ * comment ids and phase F's revision ids never have to agree.
+ */
+const MARKUP_TYPES = new Set([
+    'org_docx4j_wml.CTMarkup', 'org_docx4j_wml.CTBookmark', 'org_docx4j_wml.CTBookmarkRange',
+    'org_docx4j_wml.CTCellMergeTrackChange', 'org_docx4j_wml.CTMarkupRange', 'org_docx4j_wml.CTMathRunTrackChange',
+    'org_docx4j_wml.CTMoveBookmark', 'org_docx4j_wml.CTMoveFromRangeEnd', 'org_docx4j_wml.CTMoveToRangeEnd',
+    'org_docx4j_wml.CTPPrChange', 'org_docx4j_wml.CTRPrChange', 'org_docx4j_wml.CTSectPrChange',
+    'org_docx4j_wml.CTTblGridChange', 'org_docx4j_wml.CTTblPrChange', 'org_docx4j_wml.CTTblPrExChange',
+    'org_docx4j_wml.CTTcPrChange', 'org_docx4j_wml.CTTrPrChange', 'org_docx4j_wml.CTTrackChange',
+    'org_docx4j_wml.CTTrackChangeNumbering', 'org_docx4j_wml.CTTrackChangeRange',
+    'org_docx4j_wml.ParaRPrChange', 'org_docx4j_wml.RunDel', 'org_docx4j_wml.RunIns', 'org_docx4j_wml.RunTrackChange',
+]);
+/** The tracker of a package whose mode is not `Off`; `undefined` when it is (duck typed, no import cycle). */
+export function trackerOf(pkg) {
+    return pkg === null || pkg === void 0 ? void 0 : pkg.changeTracker;
+}
+/** An `XmlCalendar` in UTC, as Word writes `w:date` (an xsd:dateTime ending in `Z`). */
+export function calendarOf(date) {
+    return {
+        year: date.getUTCFullYear(), month: date.getUTCMonth() + 1, day: date.getUTCDate(),
+        hour: date.getUTCHours(), minute: date.getUTCMinutes(), second: date.getUTCSeconds(), timezone: 0,
+    };
+}
+/** The `Date` of a `w:date`, or undefined when there is none. */
+export function dateOf(cal) {
+    var _a, _b, _c, _d, _e, _f;
+    if (!cal || cal.year === undefined)
+        return undefined;
+    const ms = Date.UTC(cal.year, ((_a = cal.month) !== null && _a !== void 0 ? _a : 1) - 1, (_b = cal.day) !== null && _b !== void 0 ? _b : 1, (_c = cal.hour) !== null && _c !== void 0 ? _c : 0, (_d = cal.minute) !== null && _d !== void 0 ? _d : 0, (_e = cal.second) !== null && _e !== void 0 ? _e : 0);
+    return new Date(ms - ((_f = cal.timezone) !== null && _f !== void 0 ? _f : 0) * 60000);
+}
+function element(localPart, value) {
+    return { name: { namespaceURI: W_NS, localPart }, value };
+}
+/**
+ * The per-package writer of revision markup. Created by the package while
+ * `changeTrackingMode` is not `Off`; every content-API mutation asks its `Body` for one and,
+ * when it gets one, writes revisions instead of editing in place.
+ *
+ * Departure from docx4j, which has no such class: docx4j leaves revision markup to the caller.
+ * The name follows Office JS's vocabulary (`Word.ChangeTrackingMode`).
+ */
+export class ChangeTracker {
+    constructor(host, mode) {
+        this.host = host;
+        this.mode = mode;
+    }
+    /** The `w:author` a new revision carries: the package author's name. */
+    get author() {
+        return this.host.author.name;
+    }
+    /** The next annotation id: one above the highest in use in the parts already unmarshalled. */
+    nextId() {
+        if (this.counter === undefined) {
+            let highest = 0;
+            for (const root of this.host.markupRoots()) {
+                walk(root, (value) => {
+                    const tn = value.TYPE_NAME;
+                    const id = value.id;
+                    if (tn !== undefined && MARKUP_TYPES.has(tn) && typeof id === 'number' && id > highest)
+                        highest = id;
+                });
+            }
+            this.counter = highest;
+        }
+        return ++this.counter;
+    }
+    /** The `w:id`, `w:author` and `w:date` a new revision carries. */
+    markup() {
+        var _a;
+        return { id: this.nextId(), author: this.author, date: calendarOf((_a = this.host.trackedChangeDate) !== null && _a !== void 0 ? _a : new Date()) };
+    }
+    /** A `w:ins` / `w:del` attribute set: the id, this package's author and the date. */
+    trackChange() {
+        return createCTTrackChange(this.markup());
+    }
+    /** `w:ins` around run-level items (they go under `customXmlOrSmartTagOrSdt`, not `content`). */
+    ins(items) {
+        const value = { TYPE_NAME: 'org_docx4j_wml.RunIns', ...this.markup(), customXmlOrSmartTagOrSdt: items };
+        const wrapper = element('ins', value);
+        linkParents(items, value);
+        return wrapper;
+    }
+    /** `w:del` around run-level items; the caller has already turned their `w:t` into `w:delText`. */
+    del(items) {
+        const value = { TYPE_NAME: 'org_docx4j_wml.RunDel', ...this.markup(), customXmlOrSmartTagOrSdt: items };
+        const wrapper = element('del', value);
+        linkParents(items, value);
+        return wrapper;
+    }
+    /** True when this revision is an insertion this package's author may extend rather than nest in. */
+    ownInsertion(revision) {
+        return (revision === null || revision === void 0 ? void 0 : revision.kind) === 'ins' && revision.value.author === this.author;
+    }
+    /** Refuses an edit that would change deleted text; rejecting the deletion first is the way. */
+    assertEditable(revision) {
+        if ((revision === null || revision === void 0 ? void 0 : revision.kind) === 'del' || (revision === null || revision === void 0 ? void 0 : revision.kind) === 'moveFrom') {
+            throw new Docx4JException(`Cannot edit text inside a w:${revision.kind} (deleted by ${revision.value.author}); reject the deletion first`);
+        }
+    }
+    /** Records the run's properties as they are now in `w:rPrChange`, once (a later write keeps the first original). */
+    recordRPrChange(rPr) {
+        if (rPr.rPrChange)
+            return;
+        const original = createCTRPrChangeRPr({ egrPrBase: rPrToElements(rPr) });
+        rPr.rPrChange = createCTRPrChange({ ...this.markup(), rPr: original });
+        linkParents(rPr.rPrChange, rPr);
+    }
+    /** Records the paragraph's properties as they are now in `w:pPrChange`, once. */
+    recordPPrChange(pPr) {
+        if (pPr.pPrChange)
+            return;
+        // w:pPrChange's child is a CT_PPrBase: `deepCopyAsSync` types the copy as the base and drops
+        // what CT_PPrBase does not declare (w:rPr, w:sectPr, w:pPrChange), so no xsi:type is marshalled.
+        // Synchronous: the part this runs on is unmarshalled, so the Jsonix context is built.
+        const original = deepCopyAsSync(pPr, 'org_docx4j_wml.PPrBase');
+        pPr.pPrChange = createCTPPrChange({ ...this.markup(), pPr: original });
+        linkParents(pPr.pPrChange, pPr);
+    }
+    /** `w:pPr/w:rPr/w:ins`: the paragraph mark is an insertion. */
+    markParagraphInserted(p) {
+        const rPr = paraRPrOf(p);
+        rPr.ins = this.trackChange();
+        linkParents(rPr.ins, rPr);
+    }
+    /** `w:pPr/w:rPr/w:del`: the paragraph mark is deleted (accepting joins the paragraph with the next). */
+    markParagraphDeleted(p) {
+        const rPr = paraRPrOf(p);
+        if (rPr.del)
+            throw new Docx4JException('This paragraph mark is already marked deleted');
+        rPr.del = this.trackChange();
+        linkParents(rPr.del, rPr);
+    }
+    /** `w:trPr/w:ins`: the table row is an insertion (CR-002 phase C's `Table` calls this). */
+    markRowInserted(tr) {
+        const trPr = rowPrOf(tr);
+        trPr.ins = this.trackChange();
+        linkParents(trPr.ins, trPr);
+    }
+    /** `w:trPr/w:del`: the table row is deleted. */
+    markRowDeleted(tr) {
+        const trPr = rowPrOf(tr);
+        if (trPr.del)
+            throw new Docx4JException('This row is already marked deleted');
+        trPr.del = this.trackChange();
+        linkParents(trPr.del, trPr);
+    }
+}
+/**
+ * A whole paragraph inserted: the mark is marked inserted and every run of it goes into a
+ * `w:ins`. Word, splitting a paragraph, marks the *first* paragraph's mark instead and leaves
+ * the new one the original mark; marking the new paragraph's own mark is the same document once
+ * accepted or rejected and keeps the edit to the element that was added (CR-002 section 13).
+ */
+export function trackInsertedParagraph(tracker, p) {
+    tracker.markParagraphInserted(p);
+    wrapNewRuns(tracker, p);
+}
+/** Every top-level run of the paragraph that is not already in a revision, wrapped in one `w:ins` per group. */
+export function wrapNewRuns(tracker, p) {
+    const content = p.content;
+    if (!content)
+        return;
+    for (let i = 0; i < content.length; i++) {
+        if (typeNameOf(content[i]) !== 'org_docx4j_wml.R' || revisionKindOf(content[i]) !== undefined)
+            continue;
+        let j = i;
+        while (j < content.length && typeNameOf(content[j]) === 'org_docx4j_wml.R' && revisionKindOf(content[j]) === undefined)
+            j++;
+        const runs = content.splice(i, j - i);
+        const ins = tracker.ins(runs);
+        content.splice(i, 0, ins);
+        linkParents(ins, p);
+    }
+}
+/** A whole table inserted: every row is marked inserted and every paragraph in it is an insertion. */
+export function trackInsertedTable(tracker, tbl) {
+    var _a, _b, _c;
+    for (const row of ((_a = tbl.content) !== null && _a !== void 0 ? _a : [])) {
+        if (typeNameOf(row) !== 'org_docx4j_wml.Tr')
+            continue;
+        const tr = row.value;
+        tracker.markRowInserted(tr);
+        for (const cell of ((_b = tr.content) !== null && _b !== void 0 ? _b : [])) {
+            if (typeNameOf(cell) !== 'org_docx4j_wml.Tc')
+                continue;
+            for (const block of ((_c = cell.value.content) !== null && _c !== void 0 ? _c : [])) {
+                if (typeNameOf(block) === 'org_docx4j_wml.P')
+                    trackInsertedParagraph(tracker, block.value);
+            }
+        }
+    }
+}
+/** The paragraph mark's run properties (`w:pPr/w:rPr`), created when absent. */
+export function paraRPrOf(p) {
+    var _a, _b;
+    const pPr = ((_a = p.pPr) !== null && _a !== void 0 ? _a : (p.pPr = createPPr()));
+    linkParents(pPr, p);
+    const rPr = ((_b = pPr.rPr) !== null && _b !== void 0 ? _b : (pPr.rPr = createParaRPr()));
+    linkParents(rPr, pPr);
+    return rPr;
+}
+/** The row's properties (`w:trPr`), created when absent. */
+export function rowPrOf(tr) {
+    var _a;
+    const trPr = ((_a = tr.trPr) !== null && _a !== void 0 ? _a : (tr.trPr = createTrPr()));
+    linkParents(trPr, tr);
+    return trPr;
+}
+/** Drops `w:pPr/w:rPr` and `w:pPr` once nothing is left in them, so that accepting or rejecting leaves no husk. */
+export function pruneParagraphProperties(p) {
+    const pPr = p.pPr;
+    if (!pPr)
+        return;
+    const rPr = pPr.rPr;
+    if (rPr && isEmpty(rPr))
+        delete pPr.rPr;
+    if (isEmpty(pPr))
+        delete p.pPr;
+}
+function isEmpty(value) {
+    return Object.keys(value).every((key) => key === 'TYPE_NAME' || value[key] === undefined);
+}
+/** True when a paragraph's mark is marked deleted. */
+export function markDeleted(p) {
+    var _a, _b;
+    return ((_b = (_a = p.pPr) === null || _a === void 0 ? void 0 : _a.rPr) === null || _b === void 0 ? void 0 : _b.del) !== undefined;
+}
+/** True when a paragraph's mark is marked inserted. */
+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;
+}
+// --- w:t <-> w:delText -------------------------------------------------------------------
+const DELETED_NAME = { t: 'delText', instrText: 'delInstrText' };
+const RESTORED_NAME = { delText: 't', delInstrText: 'instrText' };
+/** Turns a run's `w:t` into `w:delText` and `w:instrText` into `w:delInstrText`, in place. */
+export function toDeletedText(run) {
+    rename(run, DELETED_NAME, true);
+}
+/** The inverse, for `reject()` of a deletion. */
+export function toRestoredText(run) {
+    rename(run, RESTORED_NAME, false);
+}
+function rename(run, table, deleting) {
+    const content = run.content;
+    if (!content)
+        return;
+    for (let i = 0; i < content.length; i++) {
+        const item = content[i];
+        const to = table[item.name.localPart];
+        if (to === undefined)
+            continue;
+        const v = item.value;
+        const value = deleting && to === 'delText'
+            ? 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);
+    }
+}
+// --- w:rPr <-> w:rPrChange/w:rPr ---------------------------------------------------------
+// The conversion itself is the builders' `rPrToElements` / `rPrFromElements` (objects CR-003
+// section 3.5, in 0.1.4): every EG_RPrBase member in schema order, the w14 effects included.
+/** Replaces a run's direct formatting with `original`, keeping nothing of what is there. */
+export function restoreRPr(holder, original) {
+    if (Object.keys(original).filter((k) => k !== 'TYPE_NAME').length === 0)
+        delete holder.rPr;
+    else {
+        holder.rPr = original;
+        linkParents(original, holder);
+    }
+}
+/** Replaces a paragraph's properties with `original` (a `w:pPrChange/w:pPr`), keeping the mark and the section. */
+export function restorePPr(p, original) {
+    const pPr = p.pPr;
+    if (!pPr)
+        return;
+    const keep = { rPr: pPr.rPr, sectPr: pPr.sectPr };
+    for (const key of Object.keys(pPr))
+        if (key !== 'TYPE_NAME' && key !== 'PARENT')
+            delete pPr[key];
+    if (original) {
+        for (const [key, value] of Object.entries(original)) {
+            if (key === 'TYPE_NAME' || key === 'PARENT')
+                continue;
+            pPr[key] = deepCopy(value);
+        }
+    }
+    if (keep.rPr)
+        pPr.rPr = keep.rPr;
+    if (keep.sectPr)
+        pPr.sectPr = keep.sectPr;
+    linkParents(pPr, p);
+    pruneParagraphProperties(p);
+}
+/** A copy of a run's direct formatting for a new run: the recorded original (`w:rPrChange`) is not carried over. */
+export function copyRPr(rPr) {
+    if (!rPr)
+        return undefined;
+    const copy = deepCopy(rPr);
+    delete copy.rPrChange;
+    return copy;
+}

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

@@ -1,6 +1,25 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
-import { isElement, type Element } from '@docx4j/generated-objects-ts/builders/wml';
+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. */
+export type TextView = 'accepted' | 'original';
+export interface TextViewOptions {
+    /** 'accepted' (the default: w:ins included, w:del excluded) or 'original' (the other way). */
+    view?: TextView;
+}
+/** 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. */
+export interface RevisionHolder {
+    kind: RevisionKind;
+    /** The `w:ins` / `w:del` / `w:moveFrom` / `w:moveTo` element pair. */
+    element: Element;
+    value: wml.CTTrackChange;
+    /** Its run items (the model's `customXmlOrSmartTagOrSdt`). */
+    items: Element[];
+    /** The array holding `element`. */
+    owner: Element[];
+}
 /** One text-bearing item of a run, with its position in the paragraph's text. */
 export interface TextSegment {
     /** The item: w:t, w:tab, w:br, ... */
@@ -18,19 +37,46 @@ export interface TextSegment {
     end: number;
     /** True for w:t: text that can be edited in place. */
     editable: 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;
 }
+/** 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 };
+declare function itemText(item: Element): string | undefined;
 /**
- * The run-level items a holder keeps, by the model's own property names: `content` for most,
- * `customXmlOrSmartTagOrSdt` for w:ins, w:del, w:moveFrom and w:moveTo (docx4j's names for
- * the choice groups), `sdtContent.content` for a run-level content control.
+ * 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).
  */
-export declare function runItemsOf(value: object): Element[] | undefined;
-/** The text segments of a paragraph (or any run holder) in order. Deleted text (w:del) is skipped. */
-export declare function segmentsOf(container: object): TextSegment[];
+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): Element<wml.R>[];
-/** The block-level children of a container: body, header, footer, cell, sdt content, table (rows), row (cells). */
+export declare function runsOf(container: object, options?: TextViewOptions): Element<wml.R>[];
+/**
+ * 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.
+ */
 export declare function childrenOf(value: object): Element[] | undefined;
+/** 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>[];
+/** 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. */
 export declare const BLOCK_LEVEL_TYPES: Set<string>;
 /** A run element with the given items and, optionally, run properties (the builders' r() takes text; this takes items). */
@@ -38,3 +84,4 @@ export declare function runOf(items: Element[], rPr?: wml.RPr): Element<wml.R>;
 /** A paragraph element with the given runs and, optionally, paragraph properties. */
 export declare function paragraphOf(runs: Element[], pPr?: wml.PPr): Element<wml.P>;
 export { isElement as isTypedElement };
+export { RUN_HOLDERS, itemText as itemTextOf };