@docx4j/core-ts 0.1.0 → 0.1.2

package/dist/packages/WordprocessingMLPackage.d.mts

@@ -1,9 +1,19 @@
 import { OpcPackage, type PackageSource } from './OpcPackage.mjs';
 import type { LoadOptions } from '../opc/Load.mjs';
 import type { Part } from '../parts/Part.mjs';
-import { MainDocumentPart } from '../parts/wml/index.mjs';
+import { MainDocumentPart, type NumberingDefinitionsPart } from '../parts/wml/index.mjs';
+import { type FontSettings, type DefaultThemeValue } from '../model/fonts/defaultTheme.mjs';
 import type { Body, Address, Outline, OutlineParagraph, OutlineTable } from '../model/content/Body.mjs';
 import type { Paragraph } from '../model/content/Paragraph.mjs';
+import type { Author } from '../model/content/comments.mjs';
+import { CustomXmlPartCollection } from '../model/customxml/CustomXmlPartCollection.mjs';
+import { type XPathEngine } from '../model/customxml/xpath.mjs';
+import { ChangeTracker, type ChangeTrackingMode, type TrackingHost } from '../model/content/tracking.mjs';
+import { PropertyResolver } from '../model/properties/PropertyResolver.mjs';
+import type { Emulator } from '../model/listnumbering/Emulator.mjs';
+import type { TrackedChange } from '../model/content/TrackedChange.mjs';
+import type { PartSink } from '../opc/PartStore.mjs';
+import '../parts/wml/comments.mjs';
 /** The outline of a document: the body's paragraphs and tables, then each header's and footer's (loaded ones only). */
 export interface DocumentOutline extends Outline {
     headers: {
@@ -24,10 +34,41 @@ export type PageSizePaper = 'LETTER' | 'LEGAL' | 'A3' | 'A4' | 'A5' | 'B4JIS';
 export interface CreatePackageOptions {
     pageSize?: PageSizePaper;
     landscape?: boolean;
+    /** Which Office theme the new package's theme part carries, and which its font references
+     *  resolve against: `'2023'` (the default, Word 365's Aptos Display / Aptos), `'2013'`
+     *  (Calibri Light / Calibri) or `'2007'` (Cambria / Calibri). Sets `pkg.fonts.defaultTheme`. */
+    defaultTheme?: DefaultThemeValue;
+    /** The `w:compat/w:compatSetting` value for `compatibilityMode`: `'15'` (the default) is what
+     *  Word 2013 and later write, and is what keeps Word 365 out of compatibility mode. `''`
+     *  leaves the setting out, which is docx4j's own `createPackage` behaviour. */
+    compatibilityMode?: string;
 }
 /** A docx (docx4j WordprocessingMLPackage). */
-export declare class WordprocessingMLPackage extends OpcPackage {
+export declare class WordprocessingMLPackage extends OpcPackage implements TrackingHost {
     mainDocumentPart: MainDocumentPart | undefined;
+    /**
+     * Who this package's comments (CR-002 phase G) and its tracked changes (phase F) are by.
+     * There is no signed-in user here, so the package carries the identity; the initials default to
+     * the first letter of each word of the name and the email, when given, is written to `w:people`.
+     */
+    author: Author;
+    /** A fixed date for new revisions; undefined means the moment each one is written (CR-002 phase F). */
+    trackedChangeDate: Date | undefined;
+    private trackingMode;
+    private tracker;
+    /** Set when `changeTrackingMode` was written but the settings part was not unmarshalled yet. */
+    private trackingPending;
+    /**
+     * The package's font settings (CR-001 Phase B step 4), docx4j's `docx4j.fonts.*` properties
+     * scoped to one package: `defaultTheme` says which Office theme a font reference resolves
+     * against where the package has **no theme part**, and which theme part `createPackage()`
+     * gives a new one. `'2023'` (Word 365's Aptos Display / Aptos) by default; `'2013'` is
+     * Calibri Light / Calibri and `'2007'` Cambria / Calibri.
+     *
+     * Set it before the first `getRunFontSelector()` or `createPackage()`; afterwards call
+     * `mainDocumentPart.refreshFonts()`.
+     */
+    readonly fonts: FontSettings;
     static load(source: PackageSource, options?: LoadOptions): Promise<WordprocessingMLPackage>;
     /**
      * A new document with a main document part (one section, the page size and 2.54 cm margins),
@@ -40,10 +81,91 @@ export declare class WordprocessingMLPackage extends OpcPackage {
     /** Office JS `document.body`: the main document part's body; the part must be unmarshalled (`getBody()` does that). */
     get body(): Body;
     getBody(): Promise<Body>;
+    private resolver;
+    private resolverPending;
+    /**
+     * docx4j `MainDocumentPart.getPropertyResolver()`: the resolver of effective paragraph, run,
+     * paragraph-mark and table properties, built once and kept for the life of the package.
+     *
+     * Asynchronous because it unmarshals the styles and numbering parts; `propertyResolver` is
+     * the synchronous accessor afterwards. A style *added* to the styles part later is found; a
+     * style *modified* or *removed* needs `refresh()`.
+     */
+    getPropertyResolver(): Promise<PropertyResolver>;
+    /**
+     * The resolver, which must already have been created: building it unmarshals parts, which
+     * cannot be done synchronously. Throws `PropertyResolverNotCreatedException` naming
+     * `getPropertyResolver()` otherwise.
+     */
+    get propertyResolver(): PropertyResolver;
+    /** The resolver if it has been created, without throwing (what a read with a fallback wants). */
+    get propertyResolverOrUndefined(): PropertyResolver | undefined;
+    /** Tells the resolver, when there is one, that the styles part has changed. */
+    refreshPropertyResolver(): void;
+    /**
+     * Builds the resolver and the numbering definitions again, over the parts the package holds
+     * **now**: what docx4j's `getPropertyResolver(true)` does, and what a styles or numbering part
+     * *added* after the first resolver was built needs (`refreshPropertyResolver()` re-reads the
+     * parts the resolver already knows about, but cannot find new ones).
+     */
+    refresh(): Promise<PropertyResolver>;
+    /** `/word/numbering.xml`, or undefined. docx4j `MainDocumentPart.getNumberingDefinitionsPart()`. */
+    get numberingDefinitionsPart(): NumberingDefinitionsPart | undefined;
+    /**
+     * The numbering emulator over this package's numbering part, with its definitions read
+     * (docx4j `NumberingDefinitionsPart.getEmulator()`), or undefined where there is no numbering
+     * part. Asynchronous because reading the part is; `numberingDefinitionsPart.getEmulator()` is
+     * the synchronous accessor afterwards.
+     */
+    getNumberingEmulator(): Promise<Emulator | undefined>;
+    /**
+     * Office JS `document.changeTrackingMode`, backed by `w:trackRevisions` in the settings part.
+     * While it is not `Off`, every mutation of the content API writes Word's revision markup with
+     * `author` and `trackedChangeDate` instead of editing in place.
+     *
+     * Reading is synchronous, so it reports `Off` for a loaded package whose settings part has not
+     * been unmarshalled; `getChangeTrackingMode()` unmarshals it and is the one to await. Writing
+     * is synchronous too and is written through to the settings part on save when the part is not
+     * unmarshalled yet (`setChangeTrackingMode()` does it there and then).
+     */
+    get changeTrackingMode(): ChangeTrackingMode;
+    set changeTrackingMode(mode: ChangeTrackingMode);
+    /** The mode as the settings part has it, unmarshalling the part (docx4j's async counterpart of the getter). */
+    getChangeTrackingMode(): Promise<ChangeTrackingMode>;
+    /** Writes `w:trackRevisions`, unmarshalling the settings part, or creating it when there is none. */
+    setChangeTrackingMode(mode: ChangeTrackingMode): Promise<void>;
+    /** The settings part, created (with its relationship and content type) when the document has none. */
+    private settingsPart;
+    /**
+     * Office JS `document.getTrackedChanges()`: every tracked change in the main document part,
+     * in document order (headers and footers have their own `Body`). The part must be
+     * unmarshalled, as `body` needs it to be.
+     */
+    getTrackedChanges(): TrackedChange[];
+    /** The tracker every content-API mutation asks for; undefined while the mode is `Off`. */
+    get changeTracker(): ChangeTracker | undefined;
+    /** TrackingHost: the trees a new revision id must be above, which is every part already unmarshalled. */
+    markupRoots(): object[];
+    /** A clone carries the identity, the tracking date, the theme setting and the XPath engine. */
+    protected copyPackageSettingsTo(target: OpcPackage): void;
+    saveTo<R>(sink: PartSink<R>): Promise<R>;
     /** The paragraph at an address anywhere in the document: 'body/3', 'header:rId5/0', a paraId, or a text match. */
     paragraphAt(address: Address): Promise<Paragraph | undefined>;
     /** Every paragraph and table with its address, style and text (CR-002 section 3.3). Unmarshals the main part, headers and footers. */
     outline(): Promise<DocumentOutline>;
     private bodies;
+    /**
+     * The XPath engine the custom XML views use (CR-002 section 3.6): `document.evaluate` in a
+     * browser or an add-in, the optional `xpath` package in Node. Settable, so a consumer with
+     * another DOM (or one who wants no dynamic import) plugs in its own. Warmed once by
+     * `customXmlParts.load()`; every node call is synchronous afterwards.
+     */
+    xpathEngine: XPathEngine;
+    /**
+     * Office JS `document.customXmlParts`: the custom XML data storage parts as views, with
+     * `add`, and docx4j's `applyBindings()` / `updateFromContentControls()` (CR-002 section 3.5).
+     */
+    get customXmlParts(): CustomXmlPartCollection;
+    private customXmlPartCollection;
     protected get progId(): string;
 }

package/dist/packages/WordprocessingMLPackage.mjs

@@ -1,3 +1,4 @@
+import { createCTCompat, createCTCompatSetting } from '@docx4j/generated-objects-ts/factory/org_docx4j_wml';
 import { OpcPackage } from './OpcPackage.mjs';
 import { registerPackageClass } from './registry.mjs';
 import { ContentTypes } from '../opc/ContentTypes.mjs';
@@ -6,7 +7,18 @@ import { Namespaces } from '../parts/Namespaces.mjs';
 import { MainDocumentPart, StyleDefinitionsPart, DocumentSettingsPart } from '../parts/wml/index.mjs';
 import { DocPropsCorePart, DocPropsExtendedPart } from '../parts/docProps/index.mjs';
 import { DEFAULT_STYLES_XML } from '../parts/wml/defaultStyles.mjs';
+import { ThemePart } from '../parts/dml/index.mjs';
+import { newFontSettings, themeOfSettings, } from '../model/fonts/defaultTheme.mjs';
 import { HeaderPart, FooterPart } from '../parts/wml/index.mjs';
+import { CustomXmlPartCollection } from '../model/customxml/CustomXmlPartCollection.mjs';
+import { DefaultXPathEngine } from '../model/customxml/xpath.mjs';
+import { ChangeTracker } from '../model/content/tracking.mjs';
+import { PropertyResolver } from '../model/properties/PropertyResolver.mjs';
+import { PropertyResolverNotCreatedException } from '../opc/exceptions.mjs';
+import { XmlPart } from '../parts/XmlPart.mjs';
+// Registers the comment parts with the content API (CR-002 phase G); no cycle: the model half
+// never imports a part, as packages/registry.mts does for the package classes.
+import '../parts/wml/comments.mjs';
 const MAIN_CONTENT_TYPES = [
     ContentTypes.WORDPROCESSINGML_DOCUMENT,
     ContentTypes.WORDPROCESSINGML_DOCUMENT_MACROENABLED,
@@ -22,8 +34,59 @@ const PAGE_SIZES = {
     A5: [8391, 11907, 11],
     B4JIS: [14572, 20639, 12],
 };
+/** The URI of Word's own compatibility settings (docx4j `DocumentSettingsPart.setWordCompatSetting`). */
+const WORD_COMPAT_URI = 'http://schemas.microsoft.com/office/word';
+/**
+ * The `w:compat/w:compatSetting`s a created document carries, in the order Word writes them.
+ * `compatibilityMode` 15 is what Word 2013 and later write and is what keeps Word 365 out of
+ * compatibility mode; `overrideTableStyleFontSizeAndJustification` is docx4j's own
+ * (`DocumentSettingsPart.setOverrideTableStyleFontSizeAndJustification`). Word 365 writes four
+ * more - `enableOpenTypeFeatures`, `doNotFlipMirrorIndents`, `differentiateMultirowTableHeaders`
+ * and `useWord2013TrackBottomHyphenation`, all 1 - plus a locale-dependent `w:themeFontLang`,
+ * which are deliberately left out for now (CR-001 section 17); adding them is one edit here.
+ */
+const DEFAULT_COMPAT_SETTINGS = [
+    // The six settings Word 365 writes for a new document, in its order; docx4j's
+    // DocumentSettingsPart.setCompatSettingsAsWord365 (9de10aac9) writes the same six.
+    { name: 'compatibilityMode', val: '15' },
+    { name: 'overrideTableStyleFontSizeAndJustification', val: '1' },
+    { name: 'enableOpenTypeFeatures', val: '1' },
+    { name: 'doNotFlipMirrorIndents', val: '1' },
+    { name: 'differentiateMultirowTableHeaders', val: '1' },
+    { name: 'useWord2013TrackBottomHyphenation', val: '1' },
+];
 /** A docx (docx4j WordprocessingMLPackage). */
 export class WordprocessingMLPackage extends OpcPackage {
+    constructor() {
+        super(...arguments);
+        /**
+         * Who this package's comments (CR-002 phase G) and its tracked changes (phase F) are by.
+         * There is no signed-in user here, so the package carries the identity; the initials default to
+         * the first letter of each word of the name and the email, when given, is written to `w:people`.
+         */
+        this.author = { name: 'docx4j' };
+        /** Set when `changeTrackingMode` was written but the settings part was not unmarshalled yet. */
+        this.trackingPending = false;
+        /**
+         * The package's font settings (CR-001 Phase B step 4), docx4j's `docx4j.fonts.*` properties
+         * scoped to one package: `defaultTheme` says which Office theme a font reference resolves
+         * against where the package has **no theme part**, and which theme part `createPackage()`
+         * gives a new one. `'2023'` (Word 365's Aptos Display / Aptos) by default; `'2013'` is
+         * Calibri Light / Calibri and `'2007'` Cambria / Calibri.
+         *
+         * Set it before the first `getRunFontSelector()` or `createPackage()`; afterwards call
+         * `mainDocumentPart.refreshFonts()`.
+         */
+        this.fonts = newFontSettings();
+        // --- custom XML (CR-002 phase E) ---
+        /**
+         * The XPath engine the custom XML views use (CR-002 section 3.6): `document.evaluate` in a
+         * browser or an add-in, the optional `xpath` package in Node. Settable, so a consumer with
+         * another DOM (or one who wants no dynamic import) plugs in its own. Warmed once by
+         * `customXmlParts.load()`; every node call is synchronous afterwards.
+         */
+        this.xpathEngine = new DefaultXPathEngine();
+    }
     static async load(source, options) {
         var _a, _b;
         const pkg = await OpcPackage.load(source, options);
@@ -37,8 +100,10 @@ export class WordprocessingMLPackage extends OpcPackage {
      * docx4j's default styles, settings, and core and extended properties (docx4j createPackage).
      */
     static async createPackage(options = {}) {
-        var _a;
+        var _a, _b;
         const pkg = new WordprocessingMLPackage();
+        if (options.defaultTheme !== undefined)
+            pkg.fonts.defaultTheme = options.defaultTheme;
         const [pw, ph, code] = PAGE_SIZES[(_a = options.pageSize) !== null && _a !== void 0 ? _a : 'A4'];
         const landscape = options.landscape === true;
         const pgSz = { w: landscape ? ph : pw, h: landscape ? pw : ph, code };
@@ -52,8 +117,20 @@ export class WordprocessingMLPackage extends OpcPackage {
         const styles = new StyleDefinitionsPart();
         styles.setXml(DEFAULT_STYLES_XML);
         main.addTargetPart(styles);
+        /* The settings part carries `w:compat/w:compatSetting compatibilityMode` 15, which Word 2013
+         * and later write into every document they create: without it Word 365 opens the document in
+         * compatibility mode ("Compatibility Mode" in the title bar, the pre-2013 layout rules).
+         * docx4j writes no mode at all (its `getCompatibilityMode()` answers 12 when the setting is
+         * absent, and says so), so this is a deliberate departure from it (CR-001 section 17);
+         * `{ compatibilityMode: '' }` leaves the setting out and gets docx4j's behaviour back. */
         const settings = new DocumentSettingsPart();
-        settings.setContents({});
+        const compatibilityMode = (_b = options.compatibilityMode) !== null && _b !== void 0 ? _b : '15';
+        const compatSetting = DEFAULT_COMPAT_SETTINGS
+            .filter((s) => s.name !== 'compatibilityMode' || compatibilityMode !== '')
+            .map((s) => createCTCompatSetting({
+            name: s.name, uri: WORD_COMPAT_URI, val: s.name === 'compatibilityMode' ? compatibilityMode : s.val,
+        }));
+        settings.setContents({ compat: createCTCompat({ compatSetting }) });
         main.addTargetPart(settings);
         const core = new DocPropsCorePart();
         core.setContents({});
@@ -61,6 +138,18 @@ export class WordprocessingMLPackage extends OpcPackage {
         const app = new DocPropsExtendedPart();
         app.setContents({});
         pkg.addTargetPart(app);
+        /* The theme part (/word/theme/theme1.xml), as Word puts one in every document it creates
+         * and as docx4j's createPackage has done since 17.1.1 (CR-001 section 14.6): without it,
+         * the default styles' docDefaults - which reference the theme fonts
+         * (w:rFonts w:asciiTheme="minorHAnsi" ...) - had nothing to resolve against, and every
+         * consumer had to guess the Office theme's faces for itself. Which theme it is, is
+         * `pkg.fonts.defaultTheme`; the same setting answers a themeless package's references. */
+        const theme = new ThemePart();
+        theme.setXml(themeOfSettings(pkg.fonts).xml);
+        main.addTargetPart(theme);
+        // so that `pkg.body`'s effective reads work without a further await: the default styles are
+        // XML bytes, so this is the one place the resolver has to be built before the caller asks
+        await pkg.getPropertyResolver();
         return pkg;
     }
     setPartShortcut(part, relationshipType) {
@@ -83,6 +172,179 @@ export class WordprocessingMLPackage extends OpcPackage {
     async getBody() {
         return this.getMainDocumentPart().getBody();
     }
+    /**
+     * docx4j `MainDocumentPart.getPropertyResolver()`: the resolver of effective paragraph, run,
+     * paragraph-mark and table properties, built once and kept for the life of the package.
+     *
+     * Asynchronous because it unmarshals the styles and numbering parts; `propertyResolver` is
+     * the synchronous accessor afterwards. A style *added* to the styles part later is found; a
+     * style *modified* or *removed* needs `refresh()`.
+     */
+    async getPropertyResolver() {
+        var _a;
+        if (this.resolver)
+            return this.resolver;
+        (_a = this.resolverPending) !== null && _a !== void 0 ? _a : (this.resolverPending = PropertyResolver.create(this).then((resolver) => {
+            this.resolver = resolver;
+            this.resolverPending = undefined;
+            return resolver;
+        }));
+        return this.resolverPending;
+    }
+    /**
+     * The resolver, which must already have been created: building it unmarshals parts, which
+     * cannot be done synchronously. Throws `PropertyResolverNotCreatedException` naming
+     * `getPropertyResolver()` otherwise.
+     */
+    get propertyResolver() {
+        if (!this.resolver)
+            throw new PropertyResolverNotCreatedException();
+        return this.resolver;
+    }
+    /** The resolver if it has been created, without throwing (what a read with a fallback wants). */
+    get propertyResolverOrUndefined() {
+        return this.resolver;
+    }
+    /** Tells the resolver, when there is one, that the styles part has changed. */
+    refreshPropertyResolver() {
+        var _a, _b, _c;
+        (_a = this.resolver) === null || _a === void 0 ? void 0 : _a.refresh();
+        (_c = (_b = this.mainDocumentPart) === null || _b === void 0 ? void 0 : _b.numberingDefinitionsPart) === null || _c === void 0 ? void 0 : _c.refreshDefinitions();
+    }
+    /**
+     * Builds the resolver and the numbering definitions again, over the parts the package holds
+     * **now**: what docx4j's `getPropertyResolver(true)` does, and what a styles or numbering part
+     * *added* after the first resolver was built needs (`refreshPropertyResolver()` re-reads the
+     * parts the resolver already knows about, but cannot find new ones).
+     */
+    async refresh() {
+        var _a, _b;
+        this.resolver = undefined;
+        this.resolverPending = undefined;
+        (_b = (_a = this.mainDocumentPart) === null || _a === void 0 ? void 0 : _a.numberingDefinitionsPart) === null || _b === void 0 ? void 0 : _b.refreshDefinitions();
+        return this.getPropertyResolver();
+    }
+    // --- list numbering (CR-001 Phase B step 3) --------------------------------------------
+    /** `/word/numbering.xml`, or undefined. docx4j `MainDocumentPart.getNumberingDefinitionsPart()`. */
+    get numberingDefinitionsPart() {
+        var _a;
+        return (_a = this.mainDocumentPart) === null || _a === void 0 ? void 0 : _a.numberingDefinitionsPart;
+    }
+    /**
+     * The numbering emulator over this package's numbering part, with its definitions read
+     * (docx4j `NumberingDefinitionsPart.getEmulator()`), or undefined where there is no numbering
+     * part. Asynchronous because reading the part is; `numberingDefinitionsPart.getEmulator()` is
+     * the synchronous accessor afterwards.
+     */
+    async getNumberingEmulator() {
+        const part = this.numberingDefinitionsPart;
+        if (part === undefined)
+            return undefined;
+        await this.getPropertyResolver();
+        await part.getDefinitions();
+        return part.getEmulator();
+    }
+    // --- change tracking (CR-002 phase F, section 3.7) --------------------------------------
+    /**
+     * Office JS `document.changeTrackingMode`, backed by `w:trackRevisions` in the settings part.
+     * While it is not `Off`, every mutation of the content API writes Word's revision markup with
+     * `author` and `trackedChangeDate` instead of editing in place.
+     *
+     * Reading is synchronous, so it reports `Off` for a loaded package whose settings part has not
+     * been unmarshalled; `getChangeTrackingMode()` unmarshals it and is the one to await. Writing
+     * is synchronous too and is written through to the settings part on save when the part is not
+     * unmarshalled yet (`setChangeTrackingMode()` does it there and then).
+     */
+    get changeTrackingMode() {
+        var _a;
+        if (this.trackingMode !== undefined)
+            return this.trackingMode;
+        const settings = (_a = this.mainDocumentPart) === null || _a === void 0 ? void 0 : _a.documentSettingsPart;
+        if (settings === null || settings === void 0 ? void 0 : settings.isUnmarshalled)
+            return (this.trackingMode = modeOf(settings.contents));
+        return 'Off';
+    }
+    set changeTrackingMode(mode) {
+        this.trackingMode = mode;
+        this.tracker = undefined;
+        const settings = this.mainDocumentPart ? this.settingsPart() : undefined;
+        if (settings === null || settings === void 0 ? void 0 : settings.isUnmarshalled) {
+            writeTrackRevisions(settings.contents, mode);
+            this.trackingPending = false;
+        }
+        else
+            this.trackingPending = true;
+    }
+    /** The mode as the settings part has it, unmarshalling the part (docx4j's async counterpart of the getter). */
+    async getChangeTrackingMode() {
+        var _a, _b;
+        const settings = (_a = this.mainDocumentPart) === null || _a === void 0 ? void 0 : _a.documentSettingsPart;
+        if (!settings)
+            return (_b = this.trackingMode) !== null && _b !== void 0 ? _b : 'Off';
+        return (this.trackingMode = modeOf(await settings.getContents()));
+    }
+    /** Writes `w:trackRevisions`, unmarshalling the settings part, or creating it when there is none. */
+    async setChangeTrackingMode(mode) {
+        this.trackingMode = mode;
+        this.tracker = undefined;
+        this.trackingPending = false;
+        writeTrackRevisions(await this.settingsPart().getContents(), mode);
+    }
+    /** The settings part, created (with its relationship and content type) when the document has none. */
+    settingsPart() {
+        const main = this.getMainDocumentPart();
+        let settings = main.documentSettingsPart;
+        if (!settings) {
+            settings = new DocumentSettingsPart();
+            settings.setContents({});
+            main.addTargetPart(settings);
+        }
+        return settings;
+    }
+    /**
+     * Office JS `document.getTrackedChanges()`: every tracked change in the main document part,
+     * in document order (headers and footers have their own `Body`). The part must be
+     * unmarshalled, as `body` needs it to be.
+     */
+    getTrackedChanges() {
+        return this.body.getTrackedChanges();
+    }
+    /** The tracker every content-API mutation asks for; undefined while the mode is `Off`. */
+    get changeTracker() {
+        const mode = this.changeTrackingMode;
+        if (mode === 'Off')
+            return undefined;
+        if (!this.tracker || this.tracker.mode !== mode)
+            this.tracker = new ChangeTracker(this, mode);
+        return this.tracker;
+    }
+    /** TrackingHost: the trees a new revision id must be above, which is every part already unmarshalled. */
+    markupRoots() {
+        const out = [];
+        for (const part of this.parts) {
+            if (part instanceof XmlPart && part.isUnmarshalled) {
+                const contents = part.contents;
+                if (typeof contents === 'object' && contents !== null)
+                    out.push(contents);
+            }
+        }
+        return out;
+    }
+    /** A clone carries the identity, the tracking date, the theme setting and the XPath engine. */
+    copyPackageSettingsTo(target) {
+        if (!(target instanceof WordprocessingMLPackage))
+            return;
+        target.author = { ...this.author };
+        target.trackedChangeDate = this.trackedChangeDate;
+        target.fonts.defaultTheme = this.fonts.defaultTheme;
+        target.xpathEngine = this.xpathEngine;
+    }
+    async saveTo(sink) {
+        var _a;
+        if (this.trackingPending)
+            await this.setChangeTrackingMode((_a = this.trackingMode) !== null && _a !== void 0 ? _a : 'Off');
+        return super.saveTo(sink);
+    }
     /** The paragraph at an address anywhere in the document: 'body/3', 'header:rId5/0', a paraId, or a text match. */
     async paragraphAt(address) {
         for (const body of await this.bodies(address)) {
@@ -123,8 +385,53 @@ export class WordprocessingMLPackage extends OpcPackage {
             all.push(await part.getBody());
         return all;
     }
+    /**
+     * Office JS `document.customXmlParts`: the custom XML data storage parts as views, with
+     * `add`, and docx4j's `applyBindings()` / `updateFromContentControls()` (CR-002 section 3.5).
+     */
+    get customXmlParts() {
+        var _a;
+        const pkg = this;
+        return ((_a = this.customXmlPartCollection) !== null && _a !== void 0 ? _a : (this.customXmlPartCollection = new CustomXmlPartCollection({
+            // a getter, so that setting pkg.xpathEngine later is seen by the collection
+            get xpathEngine() { return pkg.xpathEngine; },
+            customXmlDataStorageParts: this.customXmlDataStorageParts,
+            getBoundBodies: async () => {
+                const main = this.getMainDocumentPart();
+                const bodies = [await main.getBody()];
+                for (const part of [...main.headerParts, ...main.footerParts])
+                    bodies.push(await part.getBody());
+                return bodies;
+            },
+            boundBodies: () => {
+                const main = this.mainDocumentPart;
+                if (!(main === null || main === void 0 ? void 0 : main.isUnmarshalled))
+                    return [];
+                const bodies = [main.body];
+                for (const part of [...main.headerParts, ...main.footerParts])
+                    if (part.isUnmarshalled)
+                        bodies.push(part.body);
+                return bodies;
+            },
+            customXmlRelationshipSource: () => this.getMainDocumentPart(),
+        })));
+    }
     get progId() {
         return 'Word.Document';
     }
 }
+/**
+ * `w:trackRevisions` is a flag, so a file cannot distinguish `TrackAll` from `TrackMineOnly`;
+ * a document that has it on reads as `TrackAll`, and either value writes it.
+ */
+function modeOf(settings) {
+    const flag = settings.trackRevisions;
+    return flag === undefined || flag.val === false ? 'Off' : 'TrackAll';
+}
+function writeTrackRevisions(settings, mode) {
+    if (mode === 'Off')
+        delete settings.trackRevisions;
+    else
+        settings.trackRevisions = {};
+}
 registerPackageClass(MAIN_CONTENT_TYPES, WordprocessingMLPackage);

package/dist/packages/index.d.mts

@@ -1,5 +1,5 @@
 export { OpcPackage, type PackageSource } from './OpcPackage.mjs';
 export { WordprocessingMLPackage, type PageSizePaper, type CreatePackageOptions } from './WordprocessingMLPackage.mjs';
-export { PresentationMLPackage } from './PresentationMLPackage.mjs';
+export { PresentationMLPackage, createSlideSize, type SlideSizesWellKnown, type CreatePresentationOptions, } from './PresentationMLPackage.mjs';
 export { SpreadsheetMLPackage } from './SpreadsheetMLPackage.mjs';
 export { registerPackageClass, createPackageForContentType, type PackageConstructor } from './registry.mjs';

package/dist/packages/index.mjs

@@ -1,6 +1,6 @@
 // Packages: OpcPackage and the three Office kinds. Importing this module registers all four.
 export { OpcPackage } from './OpcPackage.mjs';
 export { WordprocessingMLPackage } from './WordprocessingMLPackage.mjs';
-export { PresentationMLPackage } from './PresentationMLPackage.mjs';
+export { PresentationMLPackage, createSlideSize, } from './PresentationMLPackage.mjs';
 export { SpreadsheetMLPackage } from './SpreadsheetMLPackage.mjs';
 export { registerPackageClass, createPackageForContentType } from './registry.mjs';

package/dist/parts/DefaultXmlPart.d.mts

@@ -8,10 +8,28 @@ import { PartName } from '../opc/PartName.mjs';
 export declare class DefaultXmlPart extends Part {
     private document;
     private bytes;
+    /**
+     * A DOM parsed for reading only (CR-002 phase E): the part still writes its source bytes on
+     * save, so reading a custom XML part does not cost its byte-for-byte round trip. `markModified`
+     * adopts it.
+     */
+    private readDocument;
     constructor(partName: PartName | string, contentType?: string, relationshipType?: string);
     get isLoaded(): boolean;
+    /** Whether a DOM is parsed (for reading or as the part's content). */
     get isParsed(): boolean;
+    /** The DOM as the part's own content: from here on it is re-marshalled on save (docx4j getDocument). */
     getDocument(): Promise<Document>;
+    /**
+     * The DOM, parsed on first call, **without** adopting it: an untouched part still writes its
+     * source bytes (CR-001's rule). Call `markModified()` after editing the DOM in place. Extension
+     * of docx4j's DefaultXmlPart, for the custom XML views of CR-002 phase E.
+     */
+    parseDocument(): Promise<Document>;
+    /** The DOM if it is already parsed, else undefined: what a synchronous view reads (extension). */
+    get parsedDocument(): Document | undefined;
+    /** Adopts the parsed DOM as the part's content, so that save re-marshals it (extension). */
+    markModified(): void;
     setDocument(document: Document): void;
     setXml(xml: string): void;
     getXml(): Promise<string>;

package/dist/parts/DefaultXmlPart.mjs

@@ -15,27 +15,56 @@ export class DefaultXmlPart extends Part {
     get isLoaded() {
         return this.document !== undefined || this.bytes !== undefined;
     }
+    /** Whether a DOM is parsed (for reading or as the part's content). */
     get isParsed() {
-        return this.document !== undefined;
+        return this.parsedDocument !== undefined;
     }
+    /** The DOM as the part's own content: from here on it is re-marshalled on save (docx4j getDocument). */
     async getDocument() {
+        const document = await this.parseDocument();
+        this.markModified();
+        return document;
+    }
+    /**
+     * The DOM, parsed on first call, **without** adopting it: an untouched part still writes its
+     * source bytes (CR-001's rule). Call `markModified()` after editing the DOM in place. Extension
+     * of docx4j's DefaultXmlPart, for the custom XML views of CR-002 phase E.
+     */
+    async parseDocument() {
         var _a;
-        if (this.document === undefined) {
+        if (this.document !== undefined)
+            return this.document;
+        if (this.readDocument === undefined) {
             const bytes = (_a = this.bytes) !== null && _a !== void 0 ? _a : (await this.loadSourceBytes());
             if (bytes === undefined)
                 throw new Docx4JException(`Part ${this.partName} has no content: set a document or load it from a container`);
-            this.document = parseXml(decodeXmlText(bytes));
-            this.bytes = undefined;
+            this.readDocument = parseXml(decodeXmlText(bytes));
         }
-        return this.document;
+        return this.readDocument;
+    }
+    /** The DOM if it is already parsed, else undefined: what a synchronous view reads (extension). */
+    get parsedDocument() {
+        var _a;
+        return (_a = this.document) !== null && _a !== void 0 ? _a : this.readDocument;
+    }
+    /** Adopts the parsed DOM as the part's content, so that save re-marshals it (extension). */
+    markModified() {
+        if (this.document !== undefined)
+            return;
+        if (this.readDocument === undefined)
+            throw new Docx4JException(`Part ${this.partName} has no parsed document to mark as modified`);
+        this.document = this.readDocument;
+        this.bytes = undefined;
     }
     setDocument(document) {
         this.document = document;
+        this.readDocument = undefined;
         this.bytes = undefined;
     }
     setXml(xml) {
         this.bytes = encodeText(xml);
         this.document = undefined;
+        this.readDocument = undefined;
     }
     async getXml() {
         return decodeXmlText(await this.getBytes());

package/dist/parts/Namespaces.d.mts

@@ -91,6 +91,24 @@ export declare const Namespaces: {
     readonly SPREADSHEETML_PIVOT_CACHE_DEFINITION: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/pivotCacheDefinition";
     readonly SPREADSHEETML_PIVOT_CACHE_RECORDS: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/pivotCacheRecords";
     readonly SPREADSHEETML_EXTERNAL_LINK: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/externalLink";
+    /** `/xl/slicerCaches/slicerCache1.xml`, from the workbook. */
+    readonly SPREADSHEETML_SLICER_CACHE: "http://schemas.microsoft.com/office/2007/relationships/slicerCache";
+    /** `/xl/slicers/slicer1.xml`, from a worksheet. */
+    readonly SPREADSHEETML_SLICERS: "http://schemas.microsoft.com/office/2007/relationships/slicer";
+    /** `/xl/timelineCaches/timelineCache1.xml`, from the workbook. */
+    readonly SPREADSHEETML_TIMELINE_CACHE: "http://schemas.microsoft.com/office/2011/relationships/timelineCache";
+    /** `/xl/timelines/timeline1.xml`, from a worksheet. */
+    readonly SPREADSHEETML_TIMELINES: "http://schemas.microsoft.com/office/2011/relationships/timeline";
+    /** `/xl/ctrlProps/ctrlProp1.xml`, from a worksheet, for one of its form controls. */
+    readonly SPREADSHEETML_CONTROL_PROPERTIES: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/ctrlProp";
+    /** `/xl/customDataProps/customDataProps1.xml`, from the workbook. */
+    readonly SPREADSHEETML_CUSTOM_DATA_PROPERTIES: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/customDataProps";
+    /** `/xl/customData/customData1.dat`, from its properties part. */
+    readonly SPREADSHEETML_CUSTOM_DATA: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/customData";
+    /** `/xl/surveys/survey1.xml`, from the workbook. */
+    readonly SPREADSHEETML_SURVEY: "http://schemas.microsoft.com/office/2010/relationships/Survey";
+    /** `/xl/model/item.data` ([MS-XLDM]), from the workbook. */
+    readonly SPREADSHEETML_DATA_MODEL: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/powerPivotData";
     readonly WEB_EXTENSION_TASKPANES: "http://schemas.microsoft.com/office/webextensions/taskpanes/2010/11";
     readonly WEB_EXTENSION_WEBEXTENSION: "http://schemas.microsoft.com/office/webextensions/webextension/2010/11";
     readonly XML_EVENTS: "http://www.w3.org/2001/xml-events";