@docx4j/core-ts 0.1.4 → 0.2.0

package/dist/model/content/binder.mjs

@@ -0,0 +1,95 @@
+// CR-006: XPath over the WordprocessingML tree, through a read-only binder recorded while marshalling.
+//
+// docx4j answers `getJAXBNodesViaXPath` with a JAXB `Binder<Node>`, which keeps the link between a
+// DOM node and the object it came from in both directions. This runtime has no binder, so CR-002
+// section 3.6 left XPath over the typed tree out; the demand appeared (the editor's Developer
+// perspective selects by XPath) and this is the cheap half - DOM node to object, which is what a
+// selection needs. Nothing is written back through the DOM (CR-006 section 7).
+//
+// The link is recorded by `@docx4j/jsonix` 3.4.0's `onElement` callback, reached through the objects
+// facade's `marshalNode(value, { onElement })` (objects CR-007): the runtime calls it once per
+// class-typed value with the element it was written into, and once per wildcard DOM child with the
+// **imported copy** of that child - `writeNode` does `importNode`, so the element in the snapshot is
+// not the node in the tree and a map keyed on it would miss exactly the content a caller most wants
+// (jsonix-CR-006 section 2, finding 3).
+import { marshalNode } from '@docx4j/generated-objects-ts';
+/**
+ * Marshals a root element and records what each DOM element came from. One marshal per call: the
+ * tree has no change log a cached snapshot could be checked against, and a stale answer is worse
+ * than a slow one (docx4j's `refreshXmlFirst`, always true here). The editor measured 349 to 411 ms
+ * for a 255-page main document part, against 975 ms for its first unmarshal, and runs a selection
+ * on Enter - so no cache is needed, which is what CR-006 section 2 was uncertain about.
+ */
+export async function bindSnapshot(element) {
+    const objects = new WeakMap();
+    const root = await marshalNode(element, {
+        onElement: (node, value) => {
+            if (isElement(node))
+                objects.set(node, value);
+        },
+    });
+    return { root, objects };
+}
+/** Turns selected nodes into `Bound`s against a snapshot. */
+export function boundsOf(nodes, snapshot) {
+    return nodes.map((node) => {
+        const owner = owningElement(node);
+        const bound = {
+            node,
+            object: owner === undefined ? undefined : snapshot.objects.get(owner),
+            path: pathOf(node),
+        };
+        if (node.nodeType === 2)
+            bound.attribute = node.name;
+        return bound;
+    });
+}
+/**
+ * The element an XPath result belongs to: itself for an element, its owner for an attribute, its
+ * parent for a text, comment or processing-instruction node. A document node has none.
+ */
+function owningElement(node) {
+    if (node.nodeType === 1)
+        return node;
+    if (node.nodeType === 2) {
+        const owner = node.ownerElement;
+        return owner === null ? undefined : owner;
+    }
+    const parent = node.parentNode;
+    return parent !== null && parent.nodeType === 1 ? parent : undefined;
+}
+/**
+ * The node's path from the document element, in the prefixed form the part itself uses, with a
+ * position on every step: `/w:document/w:body/w:p[3]/w:r[2]`, and `/@w:val` for an attribute. The
+ * position counts siblings of the same qualified name, as XPath does, and is written even when
+ * there is only one - a path that is stable whether or not a sibling is added later is worth more
+ * than a short one, and docx4j's harness records the same form.
+ */
+export function pathOf(node) {
+    if (node.nodeType === 2) {
+        const owner = node.ownerElement;
+        return `${owner === null ? '' : pathOf(owner)}/@${node.name}`;
+    }
+    if (node.nodeType === 3 || node.nodeType === 4) {
+        const parent = node.parentNode;
+        return `${parent === null ? '' : pathOf(parent)}/text()`;
+    }
+    if (node.nodeType !== 1)
+        return '';
+    const element = node;
+    const parent = element.parentNode;
+    if (parent === null || parent.nodeType !== 1)
+        return `/${element.nodeName}`;
+    let index = 0;
+    for (let sibling = parent.firstChild; sibling; sibling = sibling.nextSibling) {
+        if (sibling.nodeType === 1 && sibling.nodeName === element.nodeName) {
+            index++;
+            if (sibling === element)
+                break;
+        }
+    }
+    return `${pathOf(parent)}/${element.nodeName}[${index}]`;
+}
+function isElement(node) {
+    return typeof node === 'object' && node !== null && node.nodeType === 1;
+}

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

@@ -16,6 +16,24 @@ export declare const COMMENT_REFERENCE_STYLE = "CommentReference";
  * Who a comment (and, with phase F, a tracked change) is by. `WordprocessingMLPackage.author`;
  * there is no signed-in user here, so the package carries the identity.
  */
+/**
+ * What a comment is made of: the text, or the paragraphs of a comment that was edited rich
+ * (CR-002 section 28.3). A string splits on newlines, as it did before this option existed.
+ */
+export type CommentContent = string | Element<wml.P>[];
+/**
+ * Who made a comment and when, and its `w:id`, for a caller that knows better than the package does:
+ * in a co-editing room the author is the peer who made it and the date is when they made it
+ * (CR-002 section 28.3). Anything omitted falls back to what the package would have used.
+ */
+export interface CommentOptions {
+    author?: Author | undefined;
+    /** Overrides the initials derived from the author's name. */
+    initials?: string | undefined;
+    date?: Date | undefined;
+    /** Checked unused across the comments part and the story's markers; a clash throws. */
+    id?: number | undefined;
+}
 export interface Author {
     name: string;
     /** Word's `w:initials`; derived from the name when not given. */
@@ -69,7 +87,7 @@ export declare function commentPartsAccess(): CommentPartsAccess;
 /** How `Body`, `Paragraph` and `Range` reach the `Comment` views; registered by `Comment.mts`. */
 export interface CommentApi {
     commentsOf(scope: Body | Paragraph | Range): Promise<Comment[]>;
-    insertComment(range: Range, text: string): Promise<Comment>;
+    insertComment(range: Range, content: CommentContent, options?: CommentOptions): Promise<Comment>;
 }
 export declare function setCommentApi(implementation: CommentApi): void;
 export declare function commentApi(): CommentApi;

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

@@ -3,15 +3,17 @@ export { Paragraph, type Alignment } from './Paragraph.mjs';
 export { Range } from './Range.mjs';
 export { BUILT_IN_STYLES, builtInOf, idOfBuiltIn, displayNameOf, styleNameOf, styleIdOf, type BuiltInStyle } from './styles.mjs';
 export { Comment } from './Comment.mjs';
-export { List, ListItem, ListItemNotFoundError, listsOf, listLabelsOf, numberingEmulatorOf, levelOf, type ListLevelType, type ListNumbering, type ListBullet, type StartListOptions, type ListLabel, } from './List.mjs';
-export { type Author, type CommentParts, type CommentPartsAccess, type CommentsExtensible, type CommentMarker, COMMENT_TEXT_STYLE, COMMENT_REFERENCE_STYLE, markersOf, markersOfParagraph, commentIdsOf } from './comments.mjs';
+export { List, ListItem, ListItemNotFoundError, NumberingFacade, listsOf, listLabelsOf, numberingEmulatorOf, levelOf, type ListLevelType, type ListNumbering, type ListBullet, type StartListOptions, type ListLabel, } from './List.mjs';
+export { type Author, type CommentContent, type CommentOptions, type CommentParts, type CommentPartsAccess, type CommentsExtensible, type CommentMarker, COMMENT_TEXT_STYLE, COMMENT_REFERENCE_STYLE, markersOf, markersOfParagraph, commentIdsOf } from './comments.mjs';
 export { Font, type UnderlineType, type RPrHolder, type FontTracking } from './Font.mjs';
 export { Table, TableRow, TableCell, cellOf } from './Table.mjs';
 export { InlinePicture, imageInfoOf, naturalSizeEmu, addImage, writableWidthEmu, type ImageFormat, type ImageInfo, type InlinePictureOptions, type NewPicture } 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 } from './search.mjs';
+export { type SearchOptions, searchPattern, findAll, matchesOf, expandReplacement } from './search.mjs';
 export { segmentsOf, runsOf, runItemsOf, childrenOf, rowsOf, cellsOf, BLOCK_LEVEL_TYPES, SDT_TYPES, runOf, paragraphOf, textOfView, revisionKindOf, type TextSegment, type Located, type TextView, type TextViewOptions, type RevisionKind, type RevisionHolder } from './tree.mjs';
 export { TrackedChange, trackedChangesOfParagraph, trackedChangesOfRow, joinWithNext, type TrackedChangeType, type TrackedChangeTarget } from './TrackedChange.mjs';
-export { ChangeTracker, trackerOf, calendarOf, dateOf, copyRPr, markDeleted, markInserted, toDeletedText, toRestoredText, restoreRPr, restorePPr, trackInsertedParagraph, trackInsertedTable, wrapNewRuns, paraRPrOf, rowPrOf, pruneParagraphProperties, type ChangeTrackingMode, type TrackingHost, } from './tracking.mjs';
+export { ChangeTracker, trackerOf, calendarOf, dateOf, copyRPr, markDeleted, markInserted, toDeletedText, toRestoredText, restoreRPr, restorePPr, trackInsertedParagraph, trackInsertedTable, wrapNewRuns, paraRPrOf, rowPrOf, pruneParagraphProperties, type ChangeTrackingMode, type TrackingHost, type TrackingScope, } from './tracking.mjs';
 export { wml, wmlOne, p, r, t, br, tab, tbl, tr, tc, sdt, sdtPr, nextSdtId, sdtProperty, sdtKindOf, inlinePicture, rPrToElements, rPrFromElements, textOf, walk, walkAll, find, linkParents, applyRunOptions, readRunOptions, UNDERLINE_TO_WML, isElement, typeNameOf, W_NS, type Element, type Wrapper, type WmlOptions, type Raw, type Interpolated, type RunOptions, type RunFormatting, type ParagraphOptions, type TableOptions, type CellOptions, type SdtKind, type SdtForm, type SdtOptions } from '@docx4j/generated-objects-ts/builders/wml';
+export { StylesFacade, type StylePackageLike } from './stylesFacade.mjs';
+export { bindSnapshot, boundsOf, pathOf, type Bound, type BoundSnapshot } from './binder.mjs';

package/dist/model/content/index.mjs

@@ -5,17 +5,19 @@ export { Range } from './Range.mjs';
 export { BUILT_IN_STYLES, builtInOf, idOfBuiltIn, displayNameOf, styleNameOf, styleIdOf } from './styles.mjs';
 export { Comment } from './Comment.mjs';
 // lists (CR-002 phase H)
-export { List, ListItem, ListItemNotFoundError, listsOf, listLabelsOf, numberingEmulatorOf, levelOf, } from './List.mjs';
+export { List, ListItem, ListItemNotFoundError, NumberingFacade, listsOf, listLabelsOf, numberingEmulatorOf, levelOf, } from './List.mjs';
 export { COMMENT_TEXT_STYLE, COMMENT_REFERENCE_STYLE, markersOf, markersOfParagraph, commentIdsOf } from './comments.mjs';
 export { Font } from './Font.mjs';
 export { Table, TableRow, TableCell, cellOf } from './Table.mjs';
 export { InlinePicture, imageInfoOf, naturalSizeEmu, addImage, writableWidthEmu } from './InlinePicture.mjs';
 export { ContentControl, collectControls, collectRunControls, W14_NS, W15_NS } from './ContentControl.mjs';
 export { contentOf, isFlatOpc, rewriteRelationshipIds } from './ooxml.mjs';
-export { searchPattern } from './search.mjs';
+export { searchPattern, findAll, matchesOf, expandReplacement } from './search.mjs';
 export { segmentsOf, runsOf, runItemsOf, childrenOf, rowsOf, cellsOf, BLOCK_LEVEL_TYPES, SDT_TYPES, runOf, paragraphOf, textOfView, revisionKindOf } from './tree.mjs';
 // change tracking (CR-002 phase F)
 export { TrackedChange, trackedChangesOfParagraph, trackedChangesOfRow, joinWithNext } from './TrackedChange.mjs';
 export { ChangeTracker, trackerOf, calendarOf, dateOf, copyRPr, markDeleted, markInserted, toDeletedText, toRestoredText, restoreRPr, restorePPr, trackInsertedParagraph, trackInsertedTable, wrapNewRuns, paraRPrOf, rowPrOf, pruneParagraphProperties, } from './tracking.mjs';
 // The objects package's builders, re-exported so that one import serves the content API and the tree it works on.
 export { wml, wmlOne, p, r, t, br, tab, tbl, tr, tc, sdt, sdtPr, nextSdtId, sdtProperty, sdtKindOf, inlinePicture, rPrToElements, rPrFromElements, textOf, walk, walkAll, find, linkParents, applyRunOptions, readRunOptions, UNDERLINE_TO_WML, isElement, typeNameOf, W_NS } from '@docx4j/generated-objects-ts/builders/wml';
+export { StylesFacade } from './stylesFacade.mjs';
+export { bindSnapshot, boundsOf, pathOf } from './binder.mjs';

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

@@ -1,12 +1,37 @@
-/** Office JS Word.SearchOptions, the subset honoured here. */
+/** Office JS Word.SearchOptions, the subset honoured here, plus `matchRegExp` (CR-002 section 26). */
 export interface SearchOptions {
     matchCase?: boolean;
     matchWholeWord?: boolean;
     /** Word wildcards: `?` one character, `*` any run, `[a-z]`, `[!x]`, `<` / `>` word start and end, `@` one or more of the previous. */
     matchWildcards?: boolean;
+    /**
+     * The search text is an ECMAScript regular expression, compiled with `u` (extension beyond
+     * Office JS, as `replaceText` is; `Word.SearchOptions` has no such member, so it stays out of
+     * `Word.supported`). Never `m` or `s`: a match stays inside one paragraph, as every search here
+     * does (CR-002 sections 26 and 29). `matchWildcards` as well is an error - they are two
+     * languages for the same argument.
+     */
+    matchRegExp?: boolean;
 }
 /** A regular expression for a search text under the options; global so it can iterate matches. */
 export declare function searchPattern(text: string, options?: SearchOptions): RegExp;
 export declare function escapeRegExp(s: string): string;
-/** All [start, end) matches of a pattern in a text. */
+/**
+ * All [start, end) matches of a pattern in a text. Kept as it is - it is a public export, and every
+ * caller that only wants spans would have to change - so the groups a replacement needs come from
+ * `matchesOf` instead (CR-002 section 26's review note, trap 1).
+ */
 export declare function findAll(text: string, pattern: RegExp): [number, number][];
+/**
+ * Every match of a pattern in a text, with its capture groups: what `replaceText` needs to expand
+ * `$1` and Word's `\1`. An empty match advances by one rather than looping forever, as `findAll`
+ * has always done.
+ */
+export declare function matchesOf(text: string, pattern: RegExp): RegExpExecArray[];
+/**
+ * A replacement with its group references expanded against one match: `$1` to `$9`, `$&` and `$$`
+ * for a regular expression (JavaScript's `String.prototype.replace` rules), and Word's `\1` to
+ * `\9` for wildcards (CR-002 section 26). A reference to a group the pattern does not have expands
+ * to nothing, as both languages do.
+ */
+export declare function expandReplacement(replacement: string, match: RegExpExecArray, options?: SearchOptions): string;

package/dist/model/content/search.mjs

@@ -1,5 +1,19 @@
+import { Docx4JException } from '../../opc/exceptions.mjs';
 /** A regular expression for a search text under the options; global so it can iterate matches. */
 export function searchPattern(text, options = {}) {
+    if (options.matchRegExp && options.matchWildcards) {
+        throw new RangeError('matchRegExp and matchWildcards are two languages for the same argument; choose one');
+    }
+    // The `u` flag goes on this branch ONLY. Under it several escapes that are merely redundant become
+    // syntax errors, and the other two branches write some: the wildcard `[...]` doubles backslashes
+    // and `escapeRegExp` escapes `-`. So it must not be moved to the one `new RegExp` below.
+    if (options.matchRegExp) {
+        // A user expression may have a top-level alternation, so `matchWholeWord` has to wrap it in a
+        // group: `(?<!\w)cat|dog(?!\w)` is two alternatives with one guard each and matches `dog` in
+        // `dogma`. A non-capturing group keeps the group numbers `$1` refers to.
+        const source = options.matchWholeWord ? `(?<![\\w])(?:${text})(?![\\w])` : text;
+        return new RegExp(source, options.matchCase ? 'gu' : 'giu');
+    }
     let source;
     if (options.matchWildcards) {
         source = '';
@@ -39,6 +53,14 @@ export function searchPattern(text, options = {}) {
             else if (c === '\\' && i + 1 < text.length) {
                 source += '\\' + text[++i];
             }
+            else if (c === '(' || c === ')') {
+                // Word's wildcard grouping, which `\1` to `\9` in a replacement refer to (CR-002 section 26);
+                // a literal parenthesis is `\(`, taken by the escape case above. Before section 26 both were
+                // escaped to literals, so this changes what a pattern with them finds: `f(x)` matched the
+                // text "f(x)" and now matches "fx", as Word's wildcards do. An unbalanced one is refused
+                // below (CR-002 section 31).
+                source += c;
+            }
             else
                 source += escapeRegExp(c);
         }
@@ -48,13 +70,32 @@ export function searchPattern(text, options = {}) {
     }
     if (options.matchWholeWord)
         source = `(?<![\\w])${source}(?![\\w])`;
-    return new RegExp(source, options.matchCase ? 'g' : 'gi');
+    try {
+        return new RegExp(source, options.matchCase ? 'g' : 'gi');
+    }
+    catch (cause) {
+        // Only a wildcard pattern can fail here - a plain text is escaped whole - and the RegExp's own
+        // message quotes the translation, a pattern the caller never wrote.
+        throw new Docx4JException(`Not a valid wildcard pattern: ${text}`, { cause });
+    }
 }
 export function escapeRegExp(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-/** All [start, end) matches of a pattern in a text. */
+/**
+ * All [start, end) matches of a pattern in a text. Kept as it is - it is a public export, and every
+ * caller that only wants spans would have to change - so the groups a replacement needs come from
+ * `matchesOf` instead (CR-002 section 26's review note, trap 1).
+ */
 export function findAll(text, pattern) {
+    return matchesOf(text, pattern).map((m) => [m.index, m.index + m[0].length]);
+}
+/**
+ * Every match of a pattern in a text, with its capture groups: what `replaceText` needs to expand
+ * `$1` and Word's `\1`. An empty match advances by one rather than looping forever, as `findAll`
+ * has always done.
+ */
+export function matchesOf(text, pattern) {
     const out = [];
     pattern.lastIndex = 0;
     for (let m = pattern.exec(text); m !== null; m = pattern.exec(text)) {
@@ -62,7 +103,22 @@ export function findAll(text, pattern) {
             pattern.lastIndex++;
             continue;
         }
-        out.push([m.index, m.index + m[0].length]);
+        out.push(m);
     }
     return out;
 }
+/**
+ * A replacement with its group references expanded against one match: `$1` to `$9`, `$&` and `$$`
+ * for a regular expression (JavaScript's `String.prototype.replace` rules), and Word's `\1` to
+ * `\9` for wildcards (CR-002 section 26). A reference to a group the pattern does not have expands
+ * to nothing, as both languages do.
+ */
+export function expandReplacement(replacement, match, options = {}) {
+    if (options.matchRegExp) {
+        return replacement.replace(/\$(\$|&|[1-9])/g, (_, token) => { var _a; return token === '$' ? '$' : token === '&' ? match[0] : (_a = match[Number(token)]) !== null && _a !== void 0 ? _a : ''; });
+    }
+    if (options.matchWildcards) {
+        return replacement.replace(/\\([1-9])/g, (_, digit) => { var _a; return (_a = match[Number(digit)]) !== null && _a !== void 0 ? _a : ''; });
+    }
+    return replacement;
+}

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

@@ -0,0 +1,37 @@
+import type { StyleDefinitionsPart, MainDocumentPart } from '../../parts/wml/index.mjs';
+/** What the facade needs of its package; `WordprocessingMLPackage` satisfies it. */
+export interface StylePackageLike {
+    getMainDocumentPart(): MainDocumentPart;
+    refreshPropertyResolver(): void;
+    /** Creates the styles part, with the defaults, when the document has none. */
+    ensureStyleDefinitionsPart(): StyleDefinitionsPart;
+}
+/**
+ * The document's style definitions as verbs that need no `Body`: `pkg.styles`.
+ *
+ * `ensure` is the one verb, and the point of it is the closure: a style is useless without what it
+ * is `w:basedOn` and `w:link`ed to, and a caller asking for `FootnoteText` means the four styles
+ * that make a footnote look like a footnote, not one.
+ */
+export declare class StylesFacade {
+    private readonly pkg;
+    constructor(pkg: StylePackageLike);
+    /**
+     * Adds each style the document lacks, from the same defaults `createPackage()` writes, together
+     * with the styles it is `w:basedOn` and `w:link`ed to, recursively. Returns the ids actually
+     * added, in the order they were written, so a caller can tell whether it changed anything.
+     *
+     * A style already in the document is left exactly as it is - the document's own definition wins
+     * over the default, always, since a consumer must not silently restyle a document it was asked to
+     * add a footnote to. An id the defaults do not carry throws a `Docx4JException` naming it: the
+     * caller asked for a definition nothing here has, and inventing one would be worse than saying so.
+     * The whole closure is worked out before anything is written, so a call that throws has changed
+     * nothing (CR-002 section 31).
+     *
+     * A document that already has every id keeps its styles part **byte for byte**: the part is not
+     * unmarshalled at all when its XML names them, the check `ensureCommentStyles` uses, and when that
+     * text check misses (another prefix, single quotes) it is read privately rather than unmarshalled,
+     * so the part is still written back from its source unless something is added.
+     */
+    ensure(ids: string | readonly string[]): Promise<string[]>;
+}

package/dist/model/content/stylesFacade.mjs

@@ -0,0 +1,114 @@
+import { deepCopy, unmarshalNode } from '@docx4j/generated-objects-ts';
+import { linkParents } from './tree.mjs';
+import { parseXml } from '../../xml/dom.mjs';
+import { DEFAULT_STYLES_XML } from '../../parts/wml/defaultStyles.mjs';
+import { SPLICEABLE_STYLES_XML } from '../../parts/wml/spliceableStyles.mjs';
+import { Docx4JException } from '../../opc/exceptions.mjs';
+/**
+ * Where a definition is looked up, unmarshalled once and never handed out (a copy is spliced in):
+ * the defaults `createPackage()` writes, and then the nine styles docx4j's own `styles.xml` carries
+ * **commented out** - which is why a created document has no `FootnoteText` although the file
+ * appears to contain one, and why this facade exists (CR-002 section 22.2).
+ */
+let sources;
+function styleSources() {
+    return (sources !== null && sources !== void 0 ? sources : (sources = (async () => {
+        const read = async (xml) => { var _a; return (_a = (await unmarshalNode(parseXml(xml))).value.style) !== null && _a !== void 0 ? _a : []; };
+        const defaults = await read(DEFAULT_STYLES_XML);
+        return { defaults, all: [...defaults, ...(await read(SPLICEABLE_STYLES_XML))] };
+    })()));
+}
+/**
+ * The document's style definitions as verbs that need no `Body`: `pkg.styles`.
+ *
+ * `ensure` is the one verb, and the point of it is the closure: a style is useless without what it
+ * is `w:basedOn` and `w:link`ed to, and a caller asking for `FootnoteText` means the four styles
+ * that make a footnote look like a footnote, not one.
+ */
+export class StylesFacade {
+    constructor(pkg) {
+        this.pkg = pkg;
+    }
+    /**
+     * Adds each style the document lacks, from the same defaults `createPackage()` writes, together
+     * with the styles it is `w:basedOn` and `w:link`ed to, recursively. Returns the ids actually
+     * added, in the order they were written, so a caller can tell whether it changed anything.
+     *
+     * A style already in the document is left exactly as it is - the document's own definition wins
+     * over the default, always, since a consumer must not silently restyle a document it was asked to
+     * add a footnote to. An id the defaults do not carry throws a `Docx4JException` naming it: the
+     * caller asked for a definition nothing here has, and inventing one would be worse than saying so.
+     * The whole closure is worked out before anything is written, so a call that throws has changed
+     * nothing (CR-002 section 31).
+     *
+     * A document that already has every id keeps its styles part **byte for byte**: the part is not
+     * unmarshalled at all when its XML names them, the check `ensureCommentStyles` uses, and when that
+     * text check misses (another prefix, single quotes) it is read privately rather than unmarshalled,
+     * so the part is still written back from its source unless something is added.
+     */
+    async ensure(ids) {
+        var _a, _b;
+        const wanted = typeof ids === 'string' ? [ids] : [...ids];
+        for (const id of wanted) {
+            if (typeof id !== 'string' || id === '')
+                throw new Docx4JException(`Not a styleId: ${String(id)}`);
+        }
+        if (wanted.length === 0)
+            return [];
+        const existing = this.pkg.getMainDocumentPart().styleDefinitionsPart;
+        // The cheap path: an untouched part whose XML names them all is left alone, so a document that
+        // has them keeps its styles part byte for byte. The comments must go first - docx4j's own
+        // default styles carry nine definitions COMMENTED OUT, so a plain `includes` finds
+        // `w:styleId="FootnoteText"` in a document that does not have the style and this would answer
+        // "nothing to do" for exactly the documents the facade exists for.
+        if (existing !== undefined && !existing.isUnmarshalled) {
+            const xml = (await existing.getXml()).replace(/<!--[\s\S]*?-->/g, '');
+            if (wanted.every((id) => xml.includes(`w:styleId="${id}"`)))
+                return [];
+        }
+        // What the document holds now, read without unmarshalling; a part created below holds the defaults.
+        const source = await styleSources();
+        const present = existing === undefined ? source.defaults : ((_a = (await existing.readContents()).style) !== null && _a !== void 0 ? _a : []);
+        const plan = closureOf(wanted, present, source.all);
+        // a document with no styles part gets the defaults, whether or not anything else is needed
+        const part = existing !== null && existing !== void 0 ? existing : this.pkg.ensureStyleDefinitionsPart();
+        if (plan.length === 0)
+            return [];
+        const styles = await part.getContents();
+        const list = ((_b = styles.style) !== null && _b !== void 0 ? _b : (styles.style = []));
+        for (const template of plan) {
+            const style = deepCopy(template);
+            list.push(style);
+            linkParents(style, styles);
+        }
+        this.pkg.refreshPropertyResolver();
+        return plan.map((style) => style.styleId);
+    }
+}
+/**
+ * The definitions to splice, in the order they are written: each wanted id the document lacks,
+ * after what it is `w:basedOn` and `w:link`ed to, recursively. Throws for an id nothing carries.
+ */
+function closureOf(wanted, present, source) {
+    const plan = [];
+    const has = (id) => present.some((s) => s.styleId === id) || plan.some((s) => s.styleId === id);
+    const add = (id, seen) => {
+        var _a, _b;
+        if (has(id) || seen.has(id))
+            return;
+        seen.add(id);
+        const template = source.find((s) => s.styleId === id);
+        if (template === undefined) {
+            throw new Docx4JException(`No definition to splice for the style ${id}: neither docx4j's default styles nor the nine it comments out carry one. Define it yourself on the styles part.`);
+        }
+        // what it is based on and linked to must be there too, and before it reads better in the part
+        for (const dependency of [(_a = template.basedOn) === null || _a === void 0 ? void 0 : _a.val, (_b = template.link) === null || _b === void 0 ? void 0 : _b.val]) {
+            if (typeof dependency === 'string')
+                add(dependency, seen);
+        }
+        plan.push(template);
+    };
+    for (const id of wanted)
+        add(id, new Set());
+    return plan;
+}

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

@@ -3,6 +3,19 @@ import { type Element, type RevisionHolder } from './tree.mjs';
 import type { Author } from './comments.mjs';
 /** Office JS `Word.ChangeTrackingMode`. */
 export type ChangeTrackingMode = 'Off' | 'TrackAll' | 'TrackMineOnly';
+/**
+ * `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.
+ */
+export declare const MARKUP_TYPES: ReadonlySet<string>;
+/**
+ * The highest annotation id in a tree (`MARKUP_TYPES` only, the one `w:id` space of ECMA-376
+ * 17.13.5.4). Shared so that the tracker's scan of the unmarshalled parts and the package's
+ * private read of the rest cannot drift apart (CR-002 section 28.2).
+ */
+export declare function highestAnnotationId(root: object, from?: number): number;
 /** What a package offers so that its edits can be tracked; `WordprocessingMLPackage` implements it. */
 export interface TrackingHost {
     /**
@@ -15,9 +28,43 @@ export interface TrackingHost {
     readonly trackedChangeDate?: Date | undefined;
     /** The trees to scan for the highest annotation id in use: the parts already unmarshalled. */
     markupRoots(): object[];
+    /**
+     * A floor for the annotation id, above every id in the parts that were **not** unmarshalled
+     * (`seedAnnotationIds()` reads them privately). 0 until it is seeded; `markupRoots()` covers the
+     * rest, so the next id is one above the greater of the two (CR-002 section 28.2).
+     */
+    readonly annotationIdFloor: number;
+    /**
+     * The last annotation id issued in the document, or `undefined` until the first, when the tracker
+     * scans for the highest in use. The host holds it rather than the tracker because a document has
+     * one id space and may have several trackers over its life - `withTracking` can make one with
+     * another mode - and a tracker with a counter of its own reissues the ids another one gave out
+     * (CR-002 section 31).
+     */
+    annotationIdCounter: number | undefined;
+}
+/**
+ * What `WordprocessingMLPackage.withTracking` records for the duration of one call: who, when, and
+ * which mode (`TrackAll` unless said otherwise). The document's own `w:trackRevisions` is not
+ * touched - an editor's agent records its edits as itself in a room whose setting belongs to the
+ * document, not to the caller (CR-002 section 28.1).
+ */
+export interface TrackingScope {
+    author: Author;
+    /** The `w:date` for every revision in the call; `undefined` means now, to the minute. */
+    date?: Date | undefined;
+    /** `TrackAll` unless given; `Off` runs `fn` with tracking suppressed for the call. */
+    mode?: ChangeTrackingMode | undefined;
 }
 /** 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;
+/**
+ * Now, with the seconds and milliseconds dropped, which is what Word stamps a revision with.
+ * Not cosmetic: Word groups adjacent revisions by author **and** timestamp, so a per-second stamp
+ * makes one change of every keystroke run and an editor's typing unreviewable (CR-002 section 28.2).
+ * A caller that sets `trackedChangeDate` gets exactly the date it asked for, truncated or not.
+ */
+export declare function nowToTheMinute(): Date;
 /** 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. */
@@ -33,11 +80,19 @@ export declare function dateOf(cal: wml.XmlCalendar | undefined): Date | undefin
 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. */
+    /**
+     * The next annotation id: one above the highest in use anywhere in the document - the parts
+     * already unmarshalled, scanned here, and the rest through the host's `annotationIdFloor`,
+     * which `seedAnnotationIds()` fills from their bytes without unmarshalling them (CR-002
+     * section 28.2; before that this saw only the unmarshalled parts, so a revision in an unread
+     * footnote or comment part did not raise the counter).
+     *
+     * The scan runs once per document, not per tracker: the counter is the host's. The floor is
+     * consulted on every call, so a `seedAnnotationIds()` awaited after the first id still counts.
+     */
     nextId(): number;
     /** The `w:id`, `w:author` and `w:date` a new revision carries. */
     markup(): {

package/dist/model/content/tracking.mjs

@@ -9,7 +9,7 @@ import { W_NS, linkParents, walk, typeNameOf, revisionKindOf } from './tree.mjs'
  * 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([
+export 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',
@@ -19,10 +19,36 @@ const MARKUP_TYPES = new Set([
     '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 highest annotation id in a tree (`MARKUP_TYPES` only, the one `w:id` space of ECMA-376
+ * 17.13.5.4). Shared so that the tracker's scan of the unmarshalled parts and the package's
+ * private read of the rest cannot drift apart (CR-002 section 28.2).
+ */
+export function highestAnnotationId(root, from = 0) {
+    let highest = from;
+    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;
+    });
+    return highest;
+}
 /** 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;
 }
+/**
+ * Now, with the seconds and milliseconds dropped, which is what Word stamps a revision with.
+ * Not cosmetic: Word groups adjacent revisions by author **and** timestamp, so a per-second stamp
+ * makes one change of every keystroke run and an editor's typing unreviewable (CR-002 section 28.2).
+ * A caller that sets `trackedChangeDate` gets exactly the date it asked for, truncated or not.
+ */
+export function nowToTheMinute() {
+    const now = new Date();
+    now.setUTCSeconds(0, 0);
+    return now;
+}
 /** An `XmlCalendar` in UTC, as Word writes `w:date` (an xsd:dateTime ending in `Z`). */
 export function calendarOf(date) {
     return {
@@ -58,26 +84,32 @@ export class ChangeTracker {
     get author() {
         return this.host.author.name;
     }
-    /** The next annotation id: one above the highest in use in the parts already unmarshalled. */
+    /**
+     * The next annotation id: one above the highest in use anywhere in the document - the parts
+     * already unmarshalled, scanned here, and the rest through the host's `annotationIdFloor`,
+     * which `seedAnnotationIds()` fills from their bytes without unmarshalling them (CR-002
+     * section 28.2; before that this saw only the unmarshalled parts, so a revision in an unread
+     * footnote or comment part did not raise the counter).
+     *
+     * The scan runs once per document, not per tracker: the counter is the host's. The floor is
+     * consulted on every call, so a `seedAnnotationIds()` awaited after the first id still counts.
+     */
     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;
+        const host = this.host;
+        let counter = host.annotationIdCounter;
+        if (counter === undefined) {
+            counter = 0;
+            for (const root of host.markupRoots())
+                counter = highestAnnotationId(root, counter);
         }
-        return ++this.counter;
+        counter = Math.max(counter, host.annotationIdFloor) + 1;
+        host.annotationIdCounter = counter;
+        return 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()) };
+        return { id: this.nextId(), author: this.author, date: calendarOf((_a = this.host.trackedChangeDate) !== null && _a !== void 0 ? _a : nowToTheMinute()) };
     }
     /** A `w:ins` / `w:del` attribute set: the id, this package's author and the date. */
     trackChange() {