@docx4j/core-ts 0.1.5 → 0.2.0

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() {

package/dist/model/customxml/CustomXmlPartCollection.d.mts

@@ -40,9 +40,16 @@ export declare class CustomXmlPartCollection implements CustomXmlPartOwner, Cust
      * A new custom XML part holding this XML, with its properties part and a fresh itemID, related
      * from the main document part (docx4j's `AbstractMigrator.addPropertiesPart` recipe: Word
      * silently drops a custom XML part that only the package relates to).
+     *
+     * `itemID` and `partName` may be given, both checked unused, for a co-editing room where two
+     * sessions allocate at once and the next free name is not the right answer (CR-002 section 24).
+     * A clash throws rather than renaming, as a chosen list `numId` does: the caller is asserting
+     * something about the room's state, and renaming would break the peer that chose it.
      */
     add(xml: string, options?: {
         schemaRefs?: string[];
+        itemID?: string;
+        partName?: string;
     }): CustomXmlPart;
     /**
      * Removes a part, its properties part and the relationships (Office JS CustomXmlPart.delete).

package/dist/model/customxml/CustomXmlPartCollection.mjs

@@ -33,7 +33,10 @@ export class CustomXmlPartCollection {
             if (!this.views.has(part))
                 this.views.set(part, await this.viewFor(part));
         }
-        await this.host.xpathEngine.ready();
+        // A parsed document, not the global one: whether a native `document.evaluate` can read these
+        // trees is a property of the parser that built them (CR-002 section 21).
+        const parsed = this.views.size > 0 ? [...this.views.values()][0].document : undefined;
+        await this.host.xpathEngine.ready(parsed);
         return this.items;
     }
     /** The parts, in the order they were registered. Call `load()` once first: a DOM has to be parsed. */
@@ -61,20 +64,40 @@ export class CustomXmlPartCollection {
      * A new custom XML part holding this XML, with its properties part and a fresh itemID, related
      * from the main document part (docx4j's `AbstractMigrator.addPropertiesPart` recipe: Word
      * silently drops a custom XML part that only the package relates to).
+     *
+     * `itemID` and `partName` may be given, both checked unused, for a co-editing room where two
+     * sessions allocate at once and the next free name is not the right answer (CR-002 section 24).
+     * A clash throws rather than renaming, as a chosen list `numId` does: the caller is asserting
+     * something about the room's state, and renaming would break the peer that chose it.
      */
     add(xml, options = {}) {
-        var _a;
+        var _a, _b;
         const document = parseXml(xml);
         const root = document.documentElement;
         if (!root)
             throw new Docx4JException('A custom XML part needs a document element');
-        const dataPart = new CustomXmlDataStoragePart('/customXml/item1.xml');
+        // Everything that can refuse the call runs before a part is made, so a refusal leaves the package
+        // as it was (CR-002 section 31: a malformed itemID used to be refused after the data part was
+        // related, which left it in the package without a properties part). The itemID is checked
+        // against the keys the package indexes its custom XML parts by, which needs no parse; the views
+        // do, and `load()` is not a precondition of `add()`.
+        const chosenName = options.partName === undefined ? undefined : PartName.of(options.partName);
+        if (chosenName && ((_a = this.host.customXmlRelationshipSource().package) === null || _a === void 0 ? void 0 : _a.parts.get(chosenName.name))) {
+            throw new Docx4JException(`The part name ${chosenName.name} is already in this package`);
+        }
+        const itemID = options.itemID === undefined ? `{${uuid().toUpperCase()}}` : normaliseChosenItemID(options.itemID);
+        if (options.itemID !== undefined) {
+            const key = normaliseId(itemID);
+            if ([...this.host.customXmlDataStorageParts.keys()].some((existing) => normaliseId(existing) === key)) {
+                throw new Docx4JException(`The itemID ${options.itemID} is already in use by a custom XML part`);
+            }
+        }
+        const dataPart = new CustomXmlDataStoragePart(chosenName !== null && chosenName !== void 0 ? chosenName : '/customXml/item1.xml');
         dataPart.setDocument(document);
-        this.host.customXmlRelationshipSource().addTargetPart(dataPart, 'RENAME_IF_NAME_EXISTS');
-        const itemID = `{${uuid().toUpperCase()}}`;
+        this.host.customXmlRelationshipSource().addTargetPart(dataPart, chosenName ? 'OVERWRITE_IF_NAME_EXISTS' : 'RENAME_IF_NAME_EXISTS');
         const propsName = PartName.of(`/customXml/itemProps${suffixOf(dataPart.partName)}.xml`);
         const props = new CustomXmlDataStoragePropertiesPart(propsName);
-        const refs = (_a = options.schemaRefs) !== null && _a !== void 0 ? _a : (root.namespaceURI ? [root.namespaceURI] : []);
+        const refs = (_b = options.schemaRefs) !== null && _b !== void 0 ? _b : (root.namespaceURI ? [root.namespaceURI] : []);
         props.setContents(createDatastoreItem({
             itemID,
             ...(refs.length > 0 ? { schemaRefs: { schemaRef: refs.map((uri) => ({ uri })) } } : {}),
@@ -152,6 +175,17 @@ export class CustomXmlPartCollection {
     }
 }
 /** An itemID without braces, lower-cased: how docx4j keys the map and how Office JS compares ids. */
+/**
+ * A chosen itemID in the form the properties part carries: braced and upper case, as Word and
+ * `uuid()` write it. A caller may pass it either way round (CR-002 section 24).
+ */
+function normaliseChosenItemID(id) {
+    const bare = id.trim().replace(/^\{|\}$/g, '');
+    if (!/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/.test(bare)) {
+        throw new Docx4JException(`An itemID must be a GUID, with or without braces, not ${id}`);
+    }
+    return `{${bare.toUpperCase()}}`;
+}
 function normaliseId(id) {
     return id.replace(/[{}]/g, '').toLowerCase();
 }

package/dist/model/customxml/xpath.d.mts

@@ -19,8 +19,15 @@ export type BooleanConversionMode = 'java' | 'xpath1' | 'xpath2';
  * string, number or boolean result. `namespaces` maps prefixes used in the expression to URIs.
  */
 export interface XPathEngine {
-    /** Prepares the engine (loads the `xpath` package in Node); idempotent, and cheap once done. */
-    ready(): Promise<void>;
+    /**
+     * Prepares the engine (loads the `xpath` package in Node); idempotent, and cheap once done.
+     *
+     * `context` is a node from a document the engine will be asked about, when the caller has one:
+     * whether a native `document.evaluate` can be used is a property of **that document**, not of
+     * the global one, and the two differ in a mixed environment - a jsdom test whose XML is parsed
+     * by xmldom has a global `document.evaluate` that cannot evaluate over the parsed tree.
+     */
+    ready(context?: Node): Promise<void>;
     /** True when `select` and `selectValue` can be called synchronously. */
     readonly isReady: boolean;
     select(expression: string, context: Node, namespaces?: Record<string, string>): Node[];
@@ -55,7 +62,15 @@ export declare class DefaultXPathEngine implements XPathEngine {
     /** True when the runtime has a native `document.evaluate` (a browser, a Word add-in). */
     private native;
     get isReady(): boolean;
-    ready(): Promise<void>;
+    /**
+     * @param context a node from a document this engine will be asked about. Given one, readiness is
+     *   decided from **that document** rather than from the global: a global `document.evaluate` says
+     *   nothing about a tree some other parser built, and in a mixed environment - jsdom's global
+     *   with xmldom's parser, which is what a Node test runner gives when the runtime resolves its
+     *   `node` export condition - the global would claim readiness the parsed tree cannot honour.
+     *   `pkg.customXmlParts.load()` passes a parsed document for exactly this reason.
+     */
+    ready(context?: Node): Promise<void>;
     select(expression: string, context: Node, namespaces?: Record<string, string>): Node[];
     selectValue(expression: string, context: Node, namespaces?: Record<string, string>): XPathValue;
     private call;

package/dist/model/customxml/xpath.mjs

@@ -67,9 +67,19 @@ export class DefaultXPathEngine {
     get isReady() {
         return this.native || this.module !== undefined;
     }
-    async ready() {
+    /**
+     * @param context a node from a document this engine will be asked about. Given one, readiness is
+     *   decided from **that document** rather than from the global: a global `document.evaluate` says
+     *   nothing about a tree some other parser built, and in a mixed environment - jsdom's global
+     *   with xmldom's parser, which is what a Node test runner gives when the runtime resolves its
+     *   `node` export condition - the global would claim readiness the parsed tree cannot honour.
+     *   `pkg.customXmlParts.load()` passes a parsed document for exactly this reason.
+     */
+    async ready(context) {
         var _a;
-        if (this.isReady)
+        if (this.module !== undefined)
+            return;
+        if (context === undefined ? this.native : nativeEvaluatorFor(context) !== undefined)
             return;
         (_a = this.loading) !== null && _a !== void 0 ? _a : (this.loading = (async () => {
             const specifier = 'xpath';
@@ -124,7 +134,12 @@ export class DefaultXPathEngine {
     }
     call(expression, context, namespaces) {
         if (!this.module) {
-            throw new Docx4JException('The XPath engine is not ready yet: await pkg.customXmlParts.load() (or pkg.xpathEngine.ready()) once before selecting nodes');
+            throw new Docx4JException(this.native
+                ? 'This document cannot be evaluated by the host DOM: it was parsed by another one (jsdom\'s '
+                    + 'document.evaluate over an xmldom tree, say). Install the optional peer dependency '
+                    + "'xpath' and await pkg.xpathEngine.ready(node) with a node of this document, or set "
+                    + 'pkg.xpathEngine to an engine that can read it'
+                : 'The XPath engine is not ready yet: await pkg.customXmlParts.load() (or pkg.xpathEngine.ready()) once before selecting nodes');
         }
         const select = Object.keys(namespaces).length > 0 ? this.module.useNamespaces(namespaces) : this.module.select;
         return select(expression, context);

package/dist/office-js/index.d.mts

@@ -1,4 +1,4 @@
-import { run, RequestContext, type RunOptions, type TrackedObjects } from './run.mjs';
+import { run, RequestContext, type RunOptions, type TrackedObjects, type ShimmedDocument } from './run.mjs';
 import { Document, DocumentProperties } from './document.mjs';
 import { supported, SUBSET_MEMBERS } from './supported.mjs';
 import { ClientResult, unwrap, nullObject, Wrapper, type Collection, type PendingSink } from './proxy.mjs';
@@ -6,6 +6,8 @@ import { NotSupportedError, ItemNotFoundError, ValueNotLoadedError } from './err
 import { toApiScript, type ApiScriptOptions, type ApiScriptTarget } from './toApiScript.mjs';
 import { InsertLocation, Alignment, UnderlineType, ChangeTrackingMode, BreakType, ContentControlType, Style, ErrorCodes, SearchOptions, ListLevelType, ListNumbering, ListBullet, type InsertLocationValue, type ChangeTrackingModeValue, type BreakTypeValue, type ContentControlTypeValue, type StyleValue, type AlignmentValue, type UnderlineTypeValue, type ListLevelTypeValue, type ListNumberingValue, type ListBulletValue } from './enums.mjs';
 export { run, RequestContext, Document, DocumentProperties, ClientResult, unwrap, nullObject, Wrapper, toApiScript, supported, SUBSET_MEMBERS };
+export type { Shimmed, ShimmedObject, ShimmedCollection, Loadable } from './shimmed.mjs';
+export type { ShimmedDocument };
 export { NotSupportedError, ItemNotFoundError, ValueNotLoadedError };
 export { InsertLocation, Alignment, UnderlineType, ChangeTrackingMode, BreakType, ContentControlType, Style, ErrorCodes, SearchOptions };
 export { ListLevelType, ListNumbering, ListBullet };

package/dist/office-js/run.d.mts

@@ -1,17 +1,27 @@
 import type { WordprocessingMLPackage } from '../packages/WordprocessingMLPackage.mjs';
 import { Document, type RunOptions } from './document.mjs';
 import { type PendingSink } from './proxy.mjs';
+import type { Shimmed } from './shimmed.mjs';
 export type { RunOptions };
+/** The `Document` as the shim presents it (CR-002 section 22.1): `context.document`'s type. */
+export type ShimmedDocument = Shimmed<Document>;
 /** Office JS's `context.trackedObjects`: object lifetime is the garbage collector's business here. */
 export interface TrackedObjects {
     add<T>(object: T): T;
     remove<T>(object: T): T;
 }
-/** A subset of Office JS `Word.RequestContext` over a package. */
+/**
+ * A subset of Office JS `Word.RequestContext` over a package.
+ *
+ * `document` is typed `ShimmedDocument`, which is what the proxies actually present: every array a
+ * `Collection` with `items` and `getFirst`, every object `load`able (CR-002 section 22.1). The
+ * runtime object is the same either way; the type is what lets an add-in script type-check against
+ * this package exactly as it does against Office JS.
+ */
 export declare class RequestContext implements PendingSink {
     /** The package this context is over (extension: Office JS has a host document). */
     readonly package_: WordprocessingMLPackage;
-    readonly document: Document;
+    readonly document: ShimmedDocument;
     /** Tracking is a no-op: nothing here is a remote proxy. */
     readonly trackedObjects: TrackedObjects;
     private pending;

package/dist/office-js/run.mjs

@@ -7,7 +7,14 @@
 import { Document } from './document.mjs';
 import { EXTRA_MEMBERS } from './extras.mjs';
 import { Wrapper, unwrap } from './proxy.mjs';
-/** A subset of Office JS `Word.RequestContext` over a package. */
+/**
+ * A subset of Office JS `Word.RequestContext` over a package.
+ *
+ * `document` is typed `ShimmedDocument`, which is what the proxies actually present: every array a
+ * `Collection` with `items` and `getFirst`, every object `load`able (CR-002 section 22.1). The
+ * runtime object is the same either way; the type is what lets an add-in script type-check against
+ * this package exactly as it does against Office JS.
+ */
 export class RequestContext {
     constructor(
     /** The package this context is over (extension: Office JS has a host document). */

package/dist/office-js/shimmed.d.mts

@@ -0,0 +1,46 @@
+import type { ClientResult, Collection } from './proxy.mjs';
+/** Office JS's `load` / `track` / `untrack`, which every proxy answers and which return the object. */
+export interface Loadable<T> {
+    /**
+     * Office JS's `load`: a no-op here, since the tree is in memory and nothing is a remote proxy
+     * (CR-002 section 3.10). Returns the object, so `body.load('text')` chains as it does in Word.
+     */
+    load(option?: string | string[] | Record<string, unknown>): T;
+    track(): T;
+    untrack(): T;
+}
+/**
+ * What the shim presents for a value of type `T`:
+ *
+ * - a function becomes a function whose result is shimmed in turn (a method call on a proxy hands
+ *   back another proxy), except that a promise stays a promise and a `ClientResult` stays one;
+ * - an array becomes a `Collection` of shimmed items - Office JS's `items`, `getFirst`,
+ *   `getFirstOrNullObject`, `getLast`, `getLastOrNullObject` and `getCount`;
+ * - any other object becomes itself with its members shimmed, plus `load`, `track` and `untrack`;
+ * - a primitive is itself.
+ *
+ * Deliberately **not** distributive over unions of objects beyond the array case: a `Range | undefined`
+ * shims to `Shimmed<Range> | undefined`, which is what a caller wants, and the conditional's natural
+ * distribution gives that.
+ */
+export type Shimmed<T> = T extends ClientResult<unknown> ? T : T extends Promise<unknown> ? T : T extends (...args: infer A) => infer R ? ((...args: A) => Shimmed<R>) & Loadable<T> : T extends readonly (infer I)[] ? ShimmedCollection<I> : T extends object ? ShimmedObject<T> : T;
+/** A collection of shimmed items, as the proxies wrap an array. */
+export type ShimmedCollection<I> = Collection<Shimmed<I>> & Loadable<Collection<Shimmed<I>>>;
+/**
+ * An object with every member shimmed, and Office JS's `load` / `track` / `untrack` beside them.
+ *
+ * `T &` matters and is not redundant: a mapped type keeps only the public members, so without it a
+ * shimmed `Body` is not assignable to `Body` and a consumer cannot pass `context.document.body` to
+ * its own function typed on the plain view - which is exactly what an add-in that shares one `edit`
+ * between Word and the shim does (`examples/office-addin/taskpane.ts`). Intersecting keeps that
+ * assignable while the mapped half still narrows an array member to a `Collection`.
+ *
+ * The **order** matters too, and is the subtler half: an intersection of two call signatures is an
+ * overload set, and TypeScript picks the first that matches. With `T` first, `getRange()` resolves
+ * to `T`'s own signature and hands back a plain `Range`, so `paragraph.getRange().font.load(...)`
+ * is rejected although the shim allows it. The mapped half therefore comes first, so the shimmed
+ * return type wins, and `T` follows to keep assignability.
+ */
+export type ShimmedObject<T> = {
+    [K in keyof T]: Shimmed<T[K]>;
+} & T & Loadable<T>;

package/dist/office-js/shimmed.mjs

@@ -0,0 +1 @@
+export {};

package/dist/opc/exceptions.d.mts

@@ -45,3 +45,28 @@ export declare class Xlsx4jException extends Docx4JException {
 export declare class PartUnrecognisedException extends Docx4JException {
     constructor(message: string);
 }
+/**
+ * An XML part that could not be unmarshalled, naming the part (CR-002 section 27, item 9 of the
+ * E4 release). The runtime's own message is specific about *what* is wrong and, since
+ * `@docx4j/jsonix` 3.4.0, *where* - `w:sz/@w:val (line 12): Argument [NaN] must be an integer` -
+ * but it cannot know which part it was reading, and a person editing a part's XML in an editor needs
+ * that first. The location fields are lifted off the runtime's error so a caller does not have to
+ * parse the message.
+ */
+export declare class PartUnmarshalException extends Docx4JException {
+    /** The part being unmarshalled: `/word/styles.xml`. */
+    readonly partName: string;
+    constructor(message: string, 
+    /** The part being unmarshalled: `/word/styles.xml`. */
+    partName: string, options?: {
+        cause?: unknown;
+        /** The element or attribute the runtime was on, when it said. */
+        location?: string | undefined;
+        /** Its line in the source, when the parser supplied one (Node only: xmldom's locator). */
+        line?: number | undefined;
+        column?: number | undefined;
+    });
+    readonly location: string | undefined;
+    readonly line: number | undefined;
+    readonly column: number | undefined;
+}

package/dist/opc/exceptions.mjs

@@ -58,3 +58,23 @@ export class PartUnrecognisedException extends Docx4JException {
         this.name = 'PartUnrecognisedException';
     }
 }
+/**
+ * An XML part that could not be unmarshalled, naming the part (CR-002 section 27, item 9 of the
+ * E4 release). The runtime's own message is specific about *what* is wrong and, since
+ * `@docx4j/jsonix` 3.4.0, *where* - `w:sz/@w:val (line 12): Argument [NaN] must be an integer` -
+ * but it cannot know which part it was reading, and a person editing a part's XML in an editor needs
+ * that first. The location fields are lifted off the runtime's error so a caller does not have to
+ * parse the message.
+ */
+export class PartUnmarshalException extends Docx4JException {
+    constructor(message, 
+    /** The part being unmarshalled: `/word/styles.xml`. */
+    partName, options) {
+        super(message, { cause: options === null || options === void 0 ? void 0 : options.cause });
+        this.partName = partName;
+        this.name = 'PartUnmarshalException';
+        this.location = options === null || options === void 0 ? void 0 : options.location;
+        this.line = options === null || options === void 0 ? void 0 : options.line;
+        this.column = options === null || options === void 0 ? void 0 : options.column;
+    }
+}

package/dist/opc/index.d.mts

@@ -8,5 +8,5 @@ export { loadPackage, type LoadOptions } from './Load.mjs';
 export { savePackage } from './Save.mjs';
 export { mcePreprocess, createMcePreprocessor, resolveAlternateContent, MCE_NS, type McePreprocessOptions } from './mce/preprocessor.mjs';
 export { UNDERSTOOD_NAMESPACES } from './mce/understood.mjs';
-export { Docx4JException, InvalidFormatException, PartUnrecognisedException, CyclicStylesException, PropertyResolverNotCreatedException } from './exceptions.mjs';
+export { Docx4JException, InvalidFormatException, PartUnrecognisedException, PartUnmarshalException, CyclicStylesException, PropertyResolverNotCreatedException } from './exceptions.mjs';
 export { parseXml, serializeXml, serializeXmlPart, createDocument, encodeText, decodeXmlText, stripXmlDeclaration, base64Encode, base64Decode, childElements, XML_DECLARATION } from '../xml/dom.mjs';

package/dist/opc/index.mjs

@@ -9,5 +9,5 @@ export { loadPackage } from './Load.mjs';
 export { savePackage } from './Save.mjs';
 export { mcePreprocess, createMcePreprocessor, resolveAlternateContent, MCE_NS } from './mce/preprocessor.mjs';
 export { UNDERSTOOD_NAMESPACES } from './mce/understood.mjs';
-export { Docx4JException, InvalidFormatException, PartUnrecognisedException, CyclicStylesException, PropertyResolverNotCreatedException } from './exceptions.mjs';
+export { Docx4JException, InvalidFormatException, PartUnrecognisedException, PartUnmarshalException, CyclicStylesException, PropertyResolverNotCreatedException } from './exceptions.mjs';
 export { parseXml, serializeXml, serializeXmlPart, createDocument, encodeText, decodeXmlText, stripXmlDeclaration, base64Encode, base64Decode, childElements, XML_DECLARATION } from '../xml/dom.mjs';

package/dist/opc/mce/understood.mjs

@@ -1,17 +1,21 @@
-// The namespaces the object model has modules for: what "understanding" an mc:Choice means here.
-// Mirrors the defaultElementNamespaceURI of every generated module of @docx4j/generated-objects-ts
-// (0.1.0); regenerate when modules are added. Word takes the first mc:Choice whose Requires
-// prefixes it all understands (ECMA-376 Part 3, 10.2.1), and so does this preprocessor.
+// What "understanding" an mc:Choice means here: the namespaces whose content survives a load and
+// a save. Word takes the first mc:Choice whose Requires prefixes it all understands (ECMA-376
+// Part 3, 10.2.1), and so does this preprocessor.
+//
+// It is the defaultElementNamespaceURI of every generated module of @docx4j/generated-objects-ts
+// (0.3.0), which `mce.test.mjs` asserts so that the next regeneration announces an addition, plus
+// two groups of hand-kept entries, each marked below: namespaces no module *defaults* to but which
+// the model binds anyway (attributes, or elements a module of another namespace declares), and the
+// slicer namespaces of CR-004 phase B, whose content the model does not bind at all but carries
+// through as DOM.
 export const UNDERSTOOD_NAMESPACES = new Set([
     'http://schemas.openxmlformats.org/wordprocessingml/2006/main',
-    'http://schemas.openxmlformats.org/officeDocument/2006/relationships',
     'http://schemas.openxmlformats.org/package/2006/relationships',
     'http://schemas.openxmlformats.org/markup-compatibility/2006',
     'http://schemas.openxmlformats.org/officeDocument/2006/math',
     'http://schemas.openxmlformats.org/officeDocument/2006/bibliography',
     'http://schemas.openxmlformats.org/officeDocument/2006/customXml',
     'http://schemas.openxmlformats.org/schemaLibrary/2006/main',
-    'http://schemas.openxmlformats.org/officeDocument/2006/custom-properties',
     'http://schemas.openxmlformats.org/officeDocument/2006/extended-properties',
     'http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes',
     'http://schemas.openxmlformats.org/package/2006/metadata/core-properties',
@@ -36,7 +40,6 @@ export const UNDERSTOOD_NAMESPACES = new Set([
     'http://schemas.microsoft.com/office/drawing/2010/diagram',
     'http://schemas.microsoft.com/office/drawing/2012/main',
     'http://schemas.microsoft.com/office/drawing/2012/chart',
-    'http://schemas.microsoft.com/office/drawing/2012/chartStyle',
     'http://schemas.microsoft.com/office/drawing/2013/main/command',
     'http://schemas.microsoft.com/office/drawing/2014/main',
     'http://schemas.microsoft.com/office/drawing/2014/chart',
@@ -44,7 +47,6 @@ export const UNDERSTOOD_NAMESPACES = new Set([
     'http://schemas.microsoft.com/office/drawing/2014/chartex',
     'http://schemas.microsoft.com/office/drawing/2016/11/main',
     'http://schemas.microsoft.com/office/drawing/2016/12/diagram',
-    'http://schemas.microsoft.com/office/drawing/2016/ink',
     'http://schemas.microsoft.com/office/drawing/2016/SVG/main',
     'http://schemas.microsoft.com/office/drawing/2017/03/chart',
     'http://schemas.microsoft.com/office/drawing/2017/decorative',
@@ -68,6 +70,9 @@ export const UNDERSTOOD_NAMESPACES = new Set([
     'http://schemas.microsoft.com/office/word/2012/wordprocessingDrawing',
     'http://schemas.microsoft.com/office/word/2015/wordml/symex',
     'http://schemas.microsoft.com/office/word/2016/wordml/cid',
+    'http://schemas.microsoft.com/office/word/2018/wordml',
+    'http://schemas.microsoft.com/office/word/2018/wordml/cex',
+    'http://schemas.microsoft.com/office/word/2026/wordml/cei',
     'http://schemas.microsoft.com/office/webextensions/taskpanes/2010/11',
     'http://schemas.microsoft.com/office/webextensions/webextension/2010/11',
     'http://schemas.microsoft.com/office/powerpoint/2010/main',
@@ -89,10 +94,34 @@ export const UNDERSTOOD_NAMESPACES = new Set([
     'http://schemas.microsoft.com/office/excel/2006/main',
     'http://schemas.microsoft.com/office/excel/2008/2/main',
     'http://schemas.microsoft.com/office/excel/2010/spreadsheetDrawing',
+    'http://schemas.microsoft.com/office/spreadsheetml/2009/9/main',
+    'http://schemas.microsoft.com/office/spreadsheetml/2010/11/main',
+    'http://schemas.microsoft.com/office/spreadsheetml/2010/11/ac',
+    'http://schemas.microsoft.com/office/spreadsheetml/2011/1/ac',
+    'http://schemas.microsoft.com/office/spreadsheetml/2014/11/main',
+    'http://schemas.microsoft.com/office/spreadsheetml/2014/revision',
+    'http://schemas.microsoft.com/office/spreadsheetml/2018/calcfeatures',
     'http://schemas.microsoft.com/ink/2010/main',
     'http://www.w3.org/1998/Math/MathML',
     'http://www.w3.org/2003/InkML',
     'http://schemas.microsoft.com/office/2006/encryption',
     'http://schemas.microsoft.com/office/2006/keyEncryptor/certificate',
     'http://schemas.microsoft.com/office/2006/keyEncryptor/password',
+    // Bound by the model without being any module's default element namespace (so the check in
+    // mce.test.mjs does not reach them): relationship ids and the custom document properties are
+    // attributes and elements other modules' types carry, chartStyle has a module that defaults to
+    // the DrawingML main namespace, and the 2016 ink one a module with no default at all.
+    'http://schemas.openxmlformats.org/officeDocument/2006/relationships',
+    'http://schemas.openxmlformats.org/officeDocument/2006/custom-properties',
+    'http://schemas.microsoft.com/office/drawing/2012/chartStyle',
+    'http://schemas.microsoft.com/office/drawing/2016/ink',
+    // Excel's slicer and timeline drawings (CR-004 phase B). Nothing binds these - docx4j has not
+    // bound the schemas either - but the Choice they gate is an xdr:graphicFrame whose a:graphicData
+    // holds the one unbound element, and that wildcard is lax (docx4j 8e8f6ea83), so it loads as DOM
+    // and re-marshals unchanged. Taking the Choice therefore keeps the slicer or timeline; leaving
+    // it would take the Fallback, an "Excel 2010 or higher" placeholder box, and lose the slicer for
+    // good. A Choice is only worth taking when everything in it round-trips (docx4j CR-021 8.9).
+    'http://schemas.microsoft.com/office/drawing/2010/slicer',
+    'http://schemas.microsoft.com/office/drawing/2012/slicer',
+    'http://schemas.microsoft.com/office/drawing/2012/timeslicer',
 ]);