@docx4j/core-ts 0.6.0 → 0.7.0

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

@@ -12,7 +12,9 @@ export { layoutModeOf, textWidthTwips, gridWidthsOf, widthTypeOf, insertGridColu
 export { InlinePicture, imageInfoOf, naturalSizeEmu, addImage, addImagePart, writableWidthEmu, type ImageFormat, type ImageInfo, type InlinePictureOptions, type NewPicture, type NewImagePart } from './InlinePicture.mjs';
 export { ContentControl, collectControls, collectRunControls, W14_NS, W15_NS, type ContentControlType, type ContentControlForm, type ContentControlAppearance } from './ContentControl.mjs';
 export { contentOf, isFlatOpc, rewriteRelationshipIds, type OoxmlOptions } from './ooxml.mjs';
-export { type SearchOptions, searchPattern, findAll, matchesOf, expandReplacement, officeMatches, type OfficeMatch, type SearchSegment } from './search.mjs';
+export { DEFAULT_ENTRIES, DEFAULT_PLACEHOLDER_ENTRY, DEFAULT_PLACEHOLDER_TEXT, defaultEntryFor, placeholderEntryOf, namePlaceholderEntry, type DefaultEntry, } from './placeholders.mjs';
+export { type SearchOptions, searchPattern, findAll, matchesOf, expandReplacement, officeMatches, type OfficeMatch, type SearchSegment, wildcardMatchesAcross, paragraphMarkPieces, type MarkedSegments, type MarkedMatch, } from './search.mjs';
+export { dropExcluded, officeItems } from './officeText.mjs';
 export { segmentsOf, runsOf, runItemsOf, selectedBranchOf, isAlternateContent, childrenOf, rowsOf, cellsOf, BLOCK_LEVEL_TYPES, SDT_TYPES, runOf, paragraphOf, textOfView, revisionKindOf, officeItemText, hiddenRunsOf, type TextSegment, type Located, type TextView, type TextViewOptions, type SegmentOptions, type HiddenRuns, type AlternateLocation, type RevisionKind, type RevisionHolder } from './tree.mjs';
 export { mathTextOf, mathLetter } from './mathText.mjs';
 export { textBoxesOf, type AnchoredBox } from './textBoxes.mjs';

package/dist/model/content/index.mjs

@@ -15,7 +15,10 @@ export { layoutModeOf, textWidthTwips, gridWidthsOf, widthTypeOf, insertGridColu
 export { InlinePicture, imageInfoOf, naturalSizeEmu, addImage, addImagePart, writableWidthEmu } from './InlinePicture.mjs';
 export { ContentControl, collectControls, collectRunControls, W14_NS, W15_NS } from './ContentControl.mjs';
 export { contentOf, isFlatOpc, rewriteRelationshipIds } from './ooxml.mjs';
-export { searchPattern, findAll, matchesOf, expandReplacement, officeMatches } from './search.mjs';
+export { DEFAULT_ENTRIES, DEFAULT_PLACEHOLDER_ENTRY, DEFAULT_PLACEHOLDER_TEXT, defaultEntryFor, placeholderEntryOf, namePlaceholderEntry, } from './placeholders.mjs';
+export { searchPattern, findAll, matchesOf, expandReplacement, officeMatches, wildcardMatchesAcross, paragraphMarkPieces, } from './search.mjs';
+// the writers' rule for Office JS's characters, for a caller's own text (CR-002 section 60.9; the editor's UPSTREAM-25)
+export { dropExcluded, officeItems } from './officeText.mjs';
 export { segmentsOf, runsOf, runItemsOf, selectedBranchOf, isAlternateContent, childrenOf, rowsOf, cellsOf, BLOCK_LEVEL_TYPES, SDT_TYPES, runOf, paragraphOf, textOfView, revisionKindOf, officeItemText, hiddenRunsOf } from './tree.mjs';
 export { mathTextOf, mathLetter } from './mathText.mjs';
 export { textBoxesOf } from './textBoxes.mjs';

package/dist/model/content/ooxml.mjs

@@ -7,6 +7,8 @@
 // `insertXml` takes; the two share this module.
 import { wml as parseFragment, walkAll } from '@docx4j/generated-objects-ts/builders/wml';
 import { Docx4JException } from '../../opc/exceptions.mjs';
+import { repairBreaksOutsideRuns } from '../../opc/repair/breaks.mjs';
+import { unknownElementsIn } from '../../opc/repair/unknownElements.mjs';
 import { PartName } from '../../opc/PartName.mjs';
 import { ContentTypes } from '../../opc/ContentTypes.mjs';
 import { BinaryPart, ImagePart } from '../../parts/BinaryPart.mjs';
@@ -25,6 +27,12 @@ export function isFlatOpc(ooxml) {
 const REL_ATTRIBUTES = ['embed', 'link', 'id', 'href', 'pict', 'dm', 'lo', 'qs', 'cs', 'topLeft', 'topRight', 'bottomLeft', 'bottomRight'];
 /** The relationships namespace, for the same attributes on DOM nodes kept as `any` content. */
 const R_NS = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships';
+/** CR-026 D12: a caller's own fragment holding an element Word doesn't know is refused, where a file arriving is read as Word reads it. */
+function refuseUnknown(names) {
+    if (names.length === 0)
+        return;
+    throw new Docx4JException(`insertOoxml refused: the content holds ${names.length === 1 ? 'an element' : 'elements'} Word doesn't know (${[...new Set(names)].join(', ')})`);
+}
 /**
  * The block-level content of `ooxml`, ready to insert: a flat OPC package's body content with
  * its parts copied and its references rewritten, or a fragment's elements.
@@ -32,7 +40,9 @@ const R_NS = 'http://schemas.openxmlformats.org/officeDocument/2006/relationship
 export async function contentOf(ooxml, options = {}) {
     var _a, _b;
     if (!isFlatOpc(ooxml)) {
-        return parseFragment(ooxml, { wrapper: 'body', preprocess: options.preprocess });
+        // a w:br outside a w:r read as Word reads it first, as on load (CR-021 D1): a created package has no hook
+        const preprocess = options.preprocess;
+        return parseFragment(ooxml, { wrapper: 'body', preprocess: (doc) => { refuseUnknown(unknownElementsIn(doc).map((e) => e.nodeName)); repairBreaksOutsideRuns(doc); preprocess === null || preprocess === void 0 ? void 0 : preprocess(doc); } });
     }
     const target = options.target;
     if (!target)
@@ -43,6 +53,7 @@ export async function contentOf(ooxml, options = {}) {
     const source = await WordprocessingMLPackage.load(ooxml, options.preprocess ? { preprocessor: options.preprocess } : {});
     const main = source.getMainDocumentPart();
     const document = await main.getContents();
+    refuseUnknown(main.warnings.flatMap((w) => (w.code === 'part.skipped' && w.kind === 'element' ? [w.name] : [])));
     const content = ((_b = (_a = document.body) === null || _a === void 0 ? void 0 : _a.content) !== null && _b !== void 0 ? _b : []);
     if (content.length === 0)
         return [];

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

@@ -0,0 +1,5 @@
+/**
+ * Gives every paragraph and row in `added`, at any depth, a w14:paraId, where the story `within` stands in uses them (CR-002
+ * section 66). A document that uses none stays so. `added` has to be in the tree already, or `within` be what it goes in.
+ */
+export declare function assignParaIds(within: object, added: Iterable<unknown>): void;

package/dist/model/content/paraIds.mjs

@@ -0,0 +1,54 @@
+// w14:paraId on what the content API adds. In some files, one paragraph or row without an id makes Word 365 renumber the whole
+// part at the next open (check 79: 79d-table, 79f-one-missing, 79f-row-ids; check 80), which breaks a `w14:` address held across
+// that open. In others it fills the gap, and what separates them isn't known (CR-002 section 66). With an id on everything nothing
+// is left to chance, so a new paragraph or row takes one wherever the story already uses them.
+import { walk } from '@docx4j/generated-objects-ts/builders/wml';
+const P = 'org_docx4j_wml.P';
+const TR = 'org_docx4j_wml.Tr';
+const holdsAnId = (value) => {
+    const type = value.TYPE_NAME;
+    return type === P || type === TR;
+};
+/** The top of the tree `within` stands in, up `PARENT`: the whole story, so a cell's own body sees the document's ids. */
+function storyOf(within) {
+    let top = within;
+    for (let guard = 0; top.PARENT !== undefined && guard < 4096; guard++)
+        top = top.PARENT;
+    return top;
+}
+/** The ids the story uses. A paragraph's own content isn't entered: what it holds matters only to a clash, one in two billion. */
+function idsIn(story) {
+    const used = new Set();
+    walk(story, (value) => {
+        if (!holdsAnId(value))
+            return undefined;
+        if (value.paraId)
+            used.add(value.paraId.toUpperCase());
+        return value.TYPE_NAME === P ? false : undefined;
+    });
+    return used;
+}
+function freeId(used) {
+    let id;
+    do {
+        id = Math.floor(Math.random() * 0x7fffffff).toString(16).toUpperCase().padStart(8, '0');
+    } while (used.has(id));
+    used.add(id);
+    return id;
+}
+/**
+ * Gives every paragraph and row in `added`, at any depth, a w14:paraId, where the story `within` stands in uses them (CR-002
+ * section 66). A document that uses none stays so. `added` has to be in the tree already, or `within` be what it goes in.
+ */
+export function assignParaIds(within, added) {
+    const used = idsIn(storyOf(within));
+    if (used.size === 0)
+        return;
+    for (const block of added) {
+        walk(block, (value) => {
+            if (holdsAnId(value) && !value.paraId)
+                value.paraId = freeId(used);
+            return undefined;
+        });
+    }
+}

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

@@ -34,6 +34,8 @@ export declare function findAll(text: string, pattern: RegExp): [number, number]
  * section 32 item 1, found by the editor's agreement suite). The clusters are `Intl.Segmenter`'s,
  * computed only for a text with a code unit at or above U+0300, below which every code unit is a
  * cluster of its own, so Latin text pays nothing; a runtime without `Intl.Segmenter` keeps every match.
+ * Only the stretches between control characters that a match's ends fall in are segmented, each once
+ * (`graphemeBoundaries`), so a search across a long body's paragraphs costs what each paragraph's does.
  */
 export declare function matchesOf(text: string, pattern: RegExp): RegExpExecArray[];
 /**

package/dist/model/content/search.mjs

@@ -110,6 +110,8 @@ export function findAll(text, pattern) {
  * section 32 item 1, found by the editor's agreement suite). The clusters are `Intl.Segmenter`'s,
  * computed only for a text with a code unit at or above U+0300, below which every code unit is a
  * cluster of its own, so Latin text pays nothing; a runtime without `Intl.Segmenter` keeps every match.
+ * Only the stretches between control characters that a match's ends fall in are segmented, each once
+ * (`graphemeBoundaries`), so a search across a long body's paragraphs costs what each paragraph's does.
  */
 export function matchesOf(text, pattern) {
     const out = [];
@@ -121,20 +123,62 @@ export function matchesOf(text, pattern) {
         }
         out.push(m);
     }
-    const boundaries = out.length > 0 ? graphemeBoundaries(text) : undefined;
-    return boundaries === undefined ? out : out.filter((m) => boundaries.has(m.index) && boundaries.has(m.index + m[0].length));
+    const isBoundary = out.length > 0 ? graphemeBoundaries(text) : undefined;
+    return isBoundary === undefined ? out : out.filter((m) => isBoundary(m.index) && isBoundary(m.index + m[0].length));
 }
-/** The code-unit offsets where a grapheme cluster starts, and the text's end; undefined where every unit is its own cluster. */
+/** A C0 or C1 control character: a grapheme cluster of its own, always a break before and after it but between CR and LF (UAX #29, GB3 to GB5). */
+const isControl = (code) => code < 0x20 || (code >= 0x7F && code < 0xA0);
+/**
+ * Whether a grapheme cluster starts at a code-unit offset (the text's end counts); undefined where every unit is its own
+ * cluster. A control character always has a break before and after it, and no rule looks back past one, so each stretch
+ * between controls (a paragraph's, in a search across marks) is segmented on its own, as it would be within the whole
+ * text, and only the stretches asked about, each once. V8's segmenter is quadratic in its input's length: the whole of a
+ * 510,000-character body didn't come back in 100 s (the editor's finding, 2026-10-26; CR-002 section 64).
+ */
 function graphemeBoundaries(text) {
     if (!/[\u0300-\uffff]/.test(text))
         return undefined;
     const Segmenter = Intl.Segmenter;
     if (Segmenter === undefined)
         return undefined;
-    const boundaries = new Set([text.length]);
-    for (const segment of new Segmenter(undefined, { granularity: 'grapheme' }).segment(text))
-        boundaries.add(segment.index);
-    return boundaries;
+    const segmenter = new Segmenter(undefined, { granularity: 'grapheme' });
+    const controls = [];
+    for (let i = 0; i < text.length; i++)
+        if (isControl(text.charCodeAt(i)))
+            controls.push(i);
+    // each stretch's cluster starts, by the stretch's start; undefined where every unit of it is its own cluster
+    const stretches = new Map();
+    return (at) => {
+        if (at <= 0 || at >= text.length)
+            return true;
+        const before = text.charCodeAt(at - 1);
+        const after = text.charCodeAt(at);
+        if (isControl(before) || isControl(after))
+            return before !== 0x0D || after !== 0x0A;
+        // the stretch holding `at`: from just after the last control before it to the first control after it
+        let lo = 0;
+        let hi = controls.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (controls[mid] < at)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        const start = lo > 0 ? controls[lo - 1] + 1 : 0;
+        if (!stretches.has(start)) {
+            const stretch = text.slice(start, lo < controls.length ? controls[lo] : text.length);
+            let starts;
+            if (/[\u0300-\uffff]/.test(stretch)) {
+                starts = new Set();
+                for (const segment of segmenter.segment(stretch))
+                    starts.add(start + segment.index);
+            }
+            stretches.set(start, starts);
+        }
+        const starts = stretches.get(start);
+        return starts === undefined || starts.has(at);
+    };
 }
 /**
  * A replacement with its group references expanded against one match: `$1` to `$9`, `$&` and `$$`

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

@@ -23,10 +23,13 @@ export interface StoryLayout {
 }
 /**
  * Whether a paragraph's mark is written in Word's default view: not where it is tracked as deleted, which reads as
- * nothing there, the paragraphs staying apart (check 58 cases 6 to 8, CR-012 section 19). A cell's last paragraph is
- * ended by the cell's `\t` whatever its mark (cases 9 and 10).
+ * nothing there, the paragraphs staying apart (check 58 cases 6 to 8, CR-012 section 19), nor where it is tracked as
+ * moved from, as the paragraph's runs are (CR-002 section 64). A cell's last paragraph is ended by the cell's `\t`
+ * whatever its mark (cases 9 and 10).
  */
 export declare const shownInDefaultView: (p: wml.P) => boolean;
+/** Whether a paragraph's mark is written in the original view, the marks Reject All keeps: not one tracked as inserted, nor as moved to. */
+export declare const shownInOriginalView: (p: wml.P) => boolean;
 /**
  * Lays out the blocks `items`, each paragraph's text read by `textOf` (its `Paragraph.text`, or another view's), its
  * mark written where `markShown` says (Word's default view's rule unless another view's is given).

package/dist/model/content/story.mjs

@@ -2,10 +2,13 @@ import { Docx4JException } from '../../opc/exceptions.mjs';
 import { typeNameOf, childrenOf, rowsOf, cellsOf, selectedBranchOf, BRANCH_TYPES } from './tree.mjs';
 /**
  * Whether a paragraph's mark is written in Word's default view: not where it is tracked as deleted, which reads as
- * nothing there, the paragraphs staying apart (check 58 cases 6 to 8, CR-012 section 19). A cell's last paragraph is
- * ended by the cell's `\t` whatever its mark (cases 9 and 10).
+ * nothing there, the paragraphs staying apart (check 58 cases 6 to 8, CR-012 section 19), nor where it is tracked as
+ * moved from, as the paragraph's runs are (CR-002 section 64). A cell's last paragraph is ended by the cell's `\t`
+ * whatever its mark (cases 9 and 10).
  */
-export const shownInDefaultView = (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; };
+export const shownInDefaultView = (p) => { var _a, _b, _c, _d; return ((_b = (_a = p.pPr) === null || _a === void 0 ? void 0 : _a.rPr) === null || _b === void 0 ? void 0 : _b.del) === undefined && ((_d = (_c = p.pPr) === null || _c === void 0 ? void 0 : _c.rPr) === null || _d === void 0 ? void 0 : _d.moveFrom) === undefined; };
+/** Whether a paragraph's mark is written in the original view, the marks Reject All keeps: not one tracked as inserted, nor as moved to. */
+export const shownInOriginalView = (p) => { var _a, _b, _c, _d; return ((_b = (_a = p.pPr) === null || _a === void 0 ? void 0 : _a.rPr) === null || _b === void 0 ? void 0 : _b.ins) === undefined && ((_d = (_c = p.pPr) === null || _c === void 0 ? void 0 : _c.rPr) === null || _d === void 0 ? void 0 : _d.moveTo) === undefined; };
 /**
  * Lays out the blocks `items`, each paragraph's text read by `textOf` (its `Paragraph.text`, or another view's), its
  * mark written where `markShown` says (Word's default view's rule unless another view's is given).

package/dist/model/content/tableRules.mjs

@@ -1,4 +1,5 @@
 import { typeNameOf, childrenOf, linkParents, selectedBranchOf, paragraphOf, rowsOf, cellsOf, ALTERNATE_CONTENT, BRANCH_TYPES } from './tree.mjs';
+import { assignParaIds } from './paraIds.mjs';
 const P = 'org_docx4j_wml.P';
 const TBL = 'org_docx4j_wml.Tbl';
 const TC = 'org_docx4j_wml.Tc';
@@ -51,6 +52,7 @@ export function endWithParagraph(tc) {
     const p = paragraphOf([]);
     content.push(p);
     linkParents(p, tc);
+    assignParaIds(tc, [p]);
     return p.value;
 }
 /** The cell whose content holds this container (a `w:tc`, a control's content, a branch, ...): up `PARENT` past the wrappers. */

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

@@ -26,6 +26,11 @@ export interface TrackingHost {
     readonly author: Author;
     /** A fixed date for new revisions; `undefined` means now, read once per revision. */
     readonly trackedChangeDate?: Date | undefined;
+    /**
+     * The zone a stamp's `w:date` wall-clock fields are written in, and a `w:date` without `dateUtc` read in: the
+     * package's `dateTimeZone`, an IANA id; undefined is the runtime's zone (CR-018, the portfolio's date rule).
+     */
+    readonly dateTimeZone?: string | undefined;
     /** The trees to scan for the highest annotation id in use: the parts already unmarshalled. */
     markupRoots(): object[];
     /**
@@ -73,19 +78,43 @@ export declare function dateOf(cal: wml.XmlCalendar | undefined): Date | undefin
 /**
  * A revision's `w:date` as Word writes it: the local wall-clock time, with a `Z` that does not mean
  * UTC (CR-002 section 29, check 23: Office JS read `01:00:00Z` as 15:00 UTC the day before, at
- * UTC+10; Word's own files carry the true UTC beside it in `w16du:dateUtc`). "Local" is this
- * process's time zone, as it is the add-in's for Office JS.
+ * UTC+10; Word's own files carry the true UTC beside it in `w16du:dateUtc`). "Local" is `zone`, the
+ * package's `dateTimeZone` (CR-018), else this process's time zone, which is the add-in's for Office JS.
  */
-export declare function wordCalendarOf(date: Date): wml.XmlCalendar;
+export declare function wordCalendarOf(date: Date, zone?: string): wml.XmlCalendar;
 /**
  * A revision's date as Word means it: `w16du:dateUtc` when there is one, which is UTC; else
- * `w:date` read as local wall-clock time, its `Z` notwithstanding, as Office JS reads it (check 23).
+ * `w:date` read as local wall-clock time, its `Z` notwithstanding, as Office JS reads it (check 23),
+ * in `zone` (the package's `dateTimeZone`, CR-018), else the runtime's zone.
  * A `w:date` with a non-zero offset, which Word does not write, is read as it says.
  */
 export declare function revisionDateOf(value: {
     date?: wml.XmlCalendar;
     dateUtc?: wml.XmlCalendar;
-}): Date | undefined;
+}, zone?: string): Date | undefined;
+/** A stamp's fields as written: an `XmlCalendar`, or its lexical form as a reader may hold it. */
+type Stamp = wml.XmlCalendar | string | null | undefined;
+/**
+ * The author's local time of a revision's or comment's `w:date`: its date and time as stored, in ISO 8601's extended form
+ * with no designator (`2026-10-31T11:00:00`), any designator not read, a missing time 00:00:00, fractions of a second
+ * dropped; undefined for no date. Word writes the author's wall clock labelled `Z` (CR-002 section 29), and shows it as it
+ * is. docx4j `RevisionDates.localTime`.
+ */
+export declare function authorLocalTime(date: Stamp): string | undefined;
+/**
+ * The author's UTC offset in minutes: `w:date` less `dateUtc` (`w16du:dateUtc`, or a comment's `w16cex:dateUtc`), where both
+ * are present and differ by a whole number of quarter hours from -12:00 to +14:00, as a clock's offset does; else
+ * undefined, so a pair a producer wrote inconsistently gives no offset rather than a wrong one. `dateUtc` without a zone is
+ * UTC, and one with an offset is moved by it. docx4j `RevisionDates.offset`.
+ */
+export declare function authorOffsetMinutes(date: Stamp, dateUtc: Stamp): number | undefined;
+/**
+ * A revision's or comment's stamp as WD REQ-702 writes it: the author's local time (`authorLocalTime`), with the author's
+ * offset after it where it is known (`2026-10-31T11:00:00+11:00`; `+00:00` for UTC, never `Z`); `dateUtc` with `Z` where
+ * there is no `w:date`; undefined where there is neither. The `Z` Word stores on `w:date` is never written, and nothing is
+ * converted to another zone. docx4j `RevisionDates.text`.
+ */
+export declare function revisionDateText(date: Stamp, dateUtc: Stamp): string | undefined;
 /** Properties compared as values: keys sorted, `PARENT`, `TYPE_NAME` and absent values left out. */
 export declare function canonical(value: unknown): string;
 /** The part a tracker writes into, as far as the tracker needs it: its tree, once unmarshalled. */
@@ -143,7 +172,7 @@ export declare class ChangeTracker {
     nextId(): number;
     /**
      * The `w:id`, `w:author` and `w:date` a new revision carries, `w:date` in Word's local wall-clock
-     * convention (`wordCalendarOf`), and `w16du:dateUtc`, the true UTC, as Word writes them both. The
+     * convention (`wordCalendarOf`, in the host's `dateTimeZone`), and `w16du:dateUtc`, the true UTC, as Word writes them both. The
      * part's root is made to list `w16du` in `mc:Ignorable` first (`declareDateUtc`): a consumer that
      * does not know `w16du` must reject it unless it is declared ignorable. A tracker bound to no part -
      * the package's own - writes `w:date` alone (CR-002 section 29).

package/dist/model/content/tracking.mjs

@@ -4,6 +4,7 @@ import { createCTTrackChange, createCTRPrChange, createCTRPrChangeRPr, createCTP
 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, isAlternateContent, selectedBranchOf, branchesOf, ALTERNATE_CONTENT } from './tree.mjs';
+import { wallClockIn, instantOf } from '../dateZone.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`,
@@ -69,21 +70,20 @@ export function dateOf(cal) {
 /**
  * A revision's `w:date` as Word writes it: the local wall-clock time, with a `Z` that does not mean
  * UTC (CR-002 section 29, check 23: Office JS read `01:00:00Z` as 15:00 UTC the day before, at
- * UTC+10; Word's own files carry the true UTC beside it in `w16du:dateUtc`). "Local" is this
- * process's time zone, as it is the add-in's for Office JS.
+ * UTC+10; Word's own files carry the true UTC beside it in `w16du:dateUtc`). "Local" is `zone`, the
+ * package's `dateTimeZone` (CR-018), else this process's time zone, which is the add-in's for Office JS.
  */
-export function wordCalendarOf(date) {
-    return {
-        year: date.getFullYear(), month: date.getMonth() + 1, day: date.getDate(),
-        hour: date.getHours(), minute: date.getMinutes(), second: date.getSeconds(), timezone: 0,
-    };
+export function wordCalendarOf(date, zone) {
+    const clock = wallClockIn(date, zone);
+    return { year: clock.year, month: clock.month, day: clock.day, hour: clock.hour, minute: clock.minute, second: clock.second, timezone: 0 };
 }
 /**
  * A revision's date as Word means it: `w16du:dateUtc` when there is one, which is UTC; else
- * `w:date` read as local wall-clock time, its `Z` notwithstanding, as Office JS reads it (check 23).
+ * `w:date` read as local wall-clock time, its `Z` notwithstanding, as Office JS reads it (check 23),
+ * in `zone` (the package's `dateTimeZone`, CR-018), else the runtime's zone.
  * A `w:date` with a non-zero offset, which Word does not write, is read as it says.
  */
-export function revisionDateOf(value) {
+export function revisionDateOf(value, zone) {
     var _a, _b, _c, _d, _e, _f;
     if (((_a = value.dateUtc) === null || _a === void 0 ? void 0 : _a.year) !== undefined)
         return dateOf(value.dateUtc);
@@ -92,7 +92,88 @@ export function revisionDateOf(value) {
         return undefined;
     if (cal.timezone !== undefined && cal.timezone !== 0)
         return dateOf(cal);
-    return new Date(cal.year, ((_b = cal.month) !== null && _b !== void 0 ? _b : 1) - 1, (_c = cal.day) !== null && _c !== void 0 ? _c : 1, (_d = cal.hour) !== null && _d !== void 0 ? _d : 0, (_e = cal.minute) !== null && _e !== void 0 ? _e : 0, (_f = cal.second) !== null && _f !== void 0 ? _f : 0);
+    return instantOf({ year: cal.year, month: (_b = cal.month) !== null && _b !== void 0 ? _b : 1, day: (_c = cal.day) !== null && _c !== void 0 ? _c : 1, hour: (_d = cal.hour) !== null && _d !== void 0 ? _d : 0, minute: (_e = cal.minute) !== null && _e !== void 0 ? _e : 0, second: (_f = cal.second) !== null && _f !== void 0 ? _f : 0 }, zone);
+}
+const STAMP = /^(-?\d{4,})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?)?(Z|[+-]\d{2}:\d{2})?$/;
+/** A stamp's date and time as written, its fields read as a UTC clock's (milliseconds), and its zone in minutes; undefined for no year. */
+function clockOf(stamp) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    if (stamp === undefined || stamp === null)
+        return undefined;
+    if (typeof stamp === 'string') {
+        const m = STAMP.exec(stamp.trim());
+        if (!m)
+            return undefined;
+        const zone = m[7];
+        const timezone = zone === undefined ? undefined : zone === 'Z' ? 0
+            : (zone.startsWith('-') ? -1 : 1) * (Number(zone.slice(1, 3)) * 60 + Number(zone.slice(4, 6)));
+        return { ms: utcClock(Number(m[1]), Number(m[2]), Number(m[3]), Number((_a = m[4]) !== null && _a !== void 0 ? _a : 0), Number((_b = m[5]) !== null && _b !== void 0 ? _b : 0), Number((_c = m[6]) !== null && _c !== void 0 ? _c : 0)), timezone };
+    }
+    if (stamp.year === undefined)
+        return undefined;
+    return { ms: utcClock(stamp.year, (_d = stamp.month) !== null && _d !== void 0 ? _d : 1, (_e = stamp.day) !== null && _e !== void 0 ? _e : 1, (_f = stamp.hour) !== null && _f !== void 0 ? _f : 0, (_g = stamp.minute) !== null && _g !== void 0 ? _g : 0, (_h = stamp.second) !== null && _h !== void 0 ? _h : 0), timezone: stamp.timezone };
+}
+function utcClock(year, month, day, hour, minute, second) {
+    const d = new Date(Date.UTC(2000, month - 1, day, hour, minute, second));
+    d.setUTCFullYear(year);
+    return d.getTime();
+}
+/** The offsets clocks keep, in seconds: UTC-12:00 to UTC+14:00. */
+const MIN_OFFSET = -12 * 3600;
+const MAX_OFFSET = 14 * 3600;
+/**
+ * The author's local time of a revision's or comment's `w:date`: its date and time as stored, in ISO 8601's extended form
+ * with no designator (`2026-10-31T11:00:00`), any designator not read, a missing time 00:00:00, fractions of a second
+ * dropped; undefined for no date. Word writes the author's wall clock labelled `Z` (CR-002 section 29), and shows it as it
+ * is. docx4j `RevisionDates.localTime`.
+ */
+export function authorLocalTime(date) {
+    const clock = clockOf(date);
+    return clock === undefined ? undefined : clockText(clock.ms);
+}
+/**
+ * The author's UTC offset in minutes: `w:date` less `dateUtc` (`w16du:dateUtc`, or a comment's `w16cex:dateUtc`), where both
+ * are present and differ by a whole number of quarter hours from -12:00 to +14:00, as a clock's offset does; else
+ * undefined, so a pair a producer wrote inconsistently gives no offset rather than a wrong one. `dateUtc` without a zone is
+ * UTC, and one with an offset is moved by it. docx4j `RevisionDates.offset`.
+ */
+export function authorOffsetMinutes(date, dateUtc) {
+    var _a;
+    const local = clockOf(date);
+    const utc = clockOf(dateUtc);
+    if (local === undefined || utc === undefined)
+        return undefined;
+    const seconds = Math.round((local.ms - (utc.ms - ((_a = utc.timezone) !== null && _a !== void 0 ? _a : 0) * 60000)) / 1000);
+    if (seconds % 900 !== 0 || seconds < MIN_OFFSET || seconds > MAX_OFFSET)
+        return undefined;
+    return seconds / 60;
+}
+/**
+ * A revision's or comment's stamp as WD REQ-702 writes it: the author's local time (`authorLocalTime`), with the author's
+ * offset after it where it is known (`2026-10-31T11:00:00+11:00`; `+00:00` for UTC, never `Z`); `dateUtc` with `Z` where
+ * there is no `w:date`; undefined where there is neither. The `Z` Word stores on `w:date` is never written, and nothing is
+ * converted to another zone. docx4j `RevisionDates.text`.
+ */
+export function revisionDateText(date, dateUtc) {
+    var _a;
+    const local = clockOf(date);
+    if (local === undefined) {
+        const utc = clockOf(dateUtc);
+        return utc === undefined ? undefined : `${clockText(utc.ms - ((_a = utc.timezone) !== null && _a !== void 0 ? _a : 0) * 60000)}Z`;
+    }
+    const offset = authorOffsetMinutes(date, dateUtc);
+    if (offset === undefined)
+        return clockText(local.ms);
+    const abs = Math.abs(offset);
+    return `${clockText(local.ms)}${offset < 0 ? '-' : '+'}${String(Math.floor(abs / 60)).padStart(2, '0')}:${String(abs % 60).padStart(2, '0')}`;
+}
+/** A UTC clock's milliseconds as `uuuu-MM-ddTHH:mm:ss`. */
+function clockText(ms) {
+    const d = new Date(ms);
+    const p2 = (n) => String(n).padStart(2, '0');
+    const year = d.getUTCFullYear();
+    const y = year < 0 ? `-${String(-year).padStart(4, '0')}` : String(year).padStart(4, '0');
+    return `${y}-${p2(d.getUTCMonth() + 1)}-${p2(d.getUTCDate())}T${p2(d.getUTCHours())}:${p2(d.getUTCMinutes())}:${p2(d.getUTCSeconds())}`;
 }
 /** Properties compared as values: keys sorted, `PARENT`, `TYPE_NAME` and absent values left out. */
 export function canonical(value) {
@@ -194,7 +275,7 @@ export class ChangeTracker {
     }
     /**
      * The `w:id`, `w:author` and `w:date` a new revision carries, `w:date` in Word's local wall-clock
-     * convention (`wordCalendarOf`), and `w16du:dateUtc`, the true UTC, as Word writes them both. The
+     * convention (`wordCalendarOf`, in the host's `dateTimeZone`), and `w16du:dateUtc`, the true UTC, as Word writes them both. The
      * part's root is made to list `w16du` in `mc:Ignorable` first (`declareDateUtc`): a consumer that
      * does not know `w16du` must reject it unless it is declared ignorable. A tracker bound to no part -
      * the package's own - writes `w:date` alone (CR-002 section 29).
@@ -202,7 +283,7 @@ export class ChangeTracker {
     markup() {
         var _a;
         const when = (_a = this.host.trackedChangeDate) !== null && _a !== void 0 ? _a : nowToTheMinute();
-        const markup = { id: this.nextId(), author: this.author, date: wordCalendarOf(when) };
+        const markup = { id: this.nextId(), author: this.author, date: wordCalendarOf(when, this.host.dateTimeZone) };
         if (declareDateUtc(this.part))
             markup.dateUtc = calendarOf(when);
         return markup;

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

@@ -1,6 +1,6 @@
 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';
+import { isElement, runItemsOf, type McOptions, 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';
@@ -56,14 +56,13 @@ export declare const OBJECT_ITEMS: ReadonlySet<string>;
 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.
+ * phase 3): the objects package's `mcBranchOf`, the first `mc:Choice` whose `Requires` names only namespaces in the
+ * understood set, by URI, else the `mc:Fallback`, else nothing (WD REQ-302 to REQ-305, CR-029). So a reader takes the
+ * branch the preprocessor resolves the element to. A mutator walks every branch instead (docx4j's `McMode.ALL`). Undefined
+ * where nothing is selected, as for an element with no branches. `options` are `mcBranchOf`'s: the text model passes
+ * `onNothingSelected` for `mce.nothing_selected`.
  */
-export declare function selectedBranchOf(value: mce.AlternateContent | undefined): Element[] | undefined;
+export declare function selectedBranchOf(value: mce.AlternateContent | undefined, options?: McOptions): Element[] | undefined;
 /** True for a kept `mc:AlternateContent`: its element pair, or its value. */
 export declare function isAlternateContent(value: unknown): boolean;
 /**

package/dist/model/content/tree.mjs

@@ -1,5 +1,4 @@
 import { isElement, typeNameOf, runItemsOf, mcBranchOf, sdtProperty } from '@docx4j/generated-objects-ts/builders/wml';
-import { READ_UNDERSTOOD_PREFIXES } from '../../opc/mce/understood.mjs';
 import { isMath, mathTextOf } from './mathText.mjs';
 import { NotSupportedError } from '../../office-js/errors.mjs';
 export { isElement, typeNameOf, walk, find, linkParents, textOf, W_NS } from '@docx4j/generated-objects-ts/builders/wml';
@@ -14,15 +13,14 @@ export const OBJECT_ITEMS = new Set(['drawing', 'pict', 'object']);
 export 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.
+ * phase 3): the objects package's `mcBranchOf`, the first `mc:Choice` whose `Requires` names only namespaces in the
+ * understood set, by URI, else the `mc:Fallback`, else nothing (WD REQ-302 to REQ-305, CR-029). So a reader takes the
+ * branch the preprocessor resolves the element to. A mutator walks every branch instead (docx4j's `McMode.ALL`). Undefined
+ * where nothing is selected, as for an element with no branches. `options` are `mcBranchOf`'s: the text model passes
+ * `onNothingSelected` for `mce.nothing_selected`.
  */
-export function selectedBranchOf(value) {
-    return mcBranchOf(value, { understood: READ_UNDERSTOOD_PREFIXES });
+export function selectedBranchOf(value, options) {
+    return mcBranchOf(value, options);
 }
 /** True for a kept `mc:AlternateContent`: its element pair, or its value. */
 export function isAlternateContent(value) {

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

@@ -0,0 +1,48 @@
+/** How Word 365 stores an attribute a setter writes, and the range the setter writes within, in the attribute's unit. */
+export interface WordStorage {
+    /** The attribute, as the part writes it. */
+    attribute: string;
+    /** The attribute's unit, and how many make a point. */
+    unit: 'twips' | 'half-points' | 'fiftieths of a percent';
+    min: number;
+    max: number;
+    /** What Word reads a value as, once it is stored: the wrap, as CR-066 measured it (the objects package's `wordIntegerReading`). */
+    reads(value: number): string;
+    /** Measured by CR-066's rounds 5 and 6: every row is, since round 6 (section 65.6). */
+    measured: boolean;
+    /** The range Word keeps as written, the objects table's (`keptRange`), before the setter's policy narrows it. */
+    stored: readonly [number, number];
+    /** Why a value Word would keep as written is refused all the same: the range narrowed below Word's storage. */
+    why?: string;
+    /** The objects table's entry the row reads: `TYPE_NAME`, property, and the rule beside the attribute where one applies. */
+    objects: {
+        typeName: string;
+        property: string;
+        rule?: 'auto' | 'exact' | 'atLeast';
+    };
+}
+/**
+ * The attributes the content API's setters write, by Word 365's storage (the objects table; CR-066 sections 3.1 and 3.4),
+ * narrowed where Word's own setter stops short of its storage (check 71b, CR-002 section 65.9, D2): there this package
+ * refuses where Word does, and no earlier.
+ */
+export declare const WORD_STORAGE: {
+    readonly indLeft: WordStorage;
+    readonly indRight: WordStorage;
+    readonly indFirstLine: WordStorage;
+    readonly indHanging: WordStorage;
+    readonly lvlIndLeft: WordStorage;
+    readonly spacingBefore: WordStorage;
+    readonly spacingAfter: WordStorage;
+    readonly spacingLineAuto: WordStorage;
+    readonly tcWDxa: WordStorage;
+    readonly tcWPct: WordStorage;
+    readonly sz: WordStorage;
+};
+/**
+ * `points` in the attribute's unit, rounded, where Word stores it as written and the setter's policy allows; else
+ * `InvalidArgument`, naming the range and what Word would read, or why the policy stops short of Word's storage (CR-002
+ * section 65; the policy section 65.9's). `where` is the setter (`Paragraph.leftIndent`). `units` is the value already
+ * in the attribute's unit, where the setter computes it otherwise (a percentage width's fiftieths).
+ */
+export declare function withinWord(where: string, points: number, storage: WordStorage, units?: number): number;