@docx4j/core-ts 0.1.4 → 0.2.0

package/dist/packages/WordprocessingMLPackage.mjs

@@ -12,7 +12,9 @@ import { newFontSettings, themeOfSettings, } from '../model/fonts/defaultTheme.m
 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 { ChangeTracker, highestAnnotationId } from '../model/content/tracking.mjs';
+import { NumberingFacade } from '../model/content/List.mjs';
+import { StylesFacade } from '../model/content/stylesFacade.mjs';
 import { PropertyResolver } from '../model/properties/PropertyResolver.mjs';
 import { PropertyResolverNotCreatedException } from '../opc/exceptions.mjs';
 import { XmlPart } from '../parts/XmlPart.mjs';
@@ -67,6 +69,18 @@ export class WordprocessingMLPackage extends OpcPackage {
         this.author = { name: 'docx4j' };
         /** Set when `changeTrackingMode` was written but the settings part was not unmarshalled yet. */
         this.trackingPending = false;
+        /**
+         * The `withTracking` calls still running, oldest first, and what the package said before the
+         * first of them. The latest call's markup applies; when it ends, the latest one still running
+         * applies again, and when none is left the package is as it was (CR-002 section 31).
+         */
+        this.trackingScopes = [];
+        /**
+         * The parts `seedAnnotationIds()` has read, with what it read: `true` for a part still holding its
+         * source, whose bytes cannot change, and otherwise the bytes that were set, which stay the same
+         * array until they are set again.
+         */
+        this.seededParts = new WeakMap();
         /**
          * 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
@@ -78,6 +92,11 @@ export class WordprocessingMLPackage extends OpcPackage {
          * `mainDocumentPart.refreshFonts()`.
          */
         this.fonts = newFontSettings();
+        /**
+         * TrackingHost: a floor for the annotation id, from the WordprocessingML parts that were **not**
+         * unmarshalled; `seedAnnotationIds()` fills it. 0 until then (CR-002 section 28.2).
+         */
+        this.annotationIdFloor = 0;
         // --- custom XML (CR-002 phase E) ---
         /**
          * The XPath engine the custom XML views use (CR-002 section 3.6): `document.evaluate` in a
@@ -257,6 +276,8 @@ export class WordprocessingMLPackage extends OpcPackage {
      */
     get changeTrackingMode() {
         var _a;
+        if (this.trackingOverride !== undefined)
+            return this.trackingOverride;
         if (this.trackingMode !== undefined)
             return this.trackingMode;
         const settings = (_a = this.mainDocumentPart) === null || _a === void 0 ? void 0 : _a.documentSettingsPart;
@@ -267,6 +288,7 @@ export class WordprocessingMLPackage extends OpcPackage {
     set changeTrackingMode(mode) {
         this.trackingMode = mode;
         this.tracker = undefined;
+        this.annotationIdCounter = undefined;
         const settings = this.mainDocumentPart ? this.settingsPart() : undefined;
         if (settings === null || settings === void 0 ? void 0 : settings.isUnmarshalled) {
             writeTrackRevisions(settings.contents, mode);
@@ -275,6 +297,58 @@ export class WordprocessingMLPackage extends OpcPackage {
         else
             this.trackingPending = true;
     }
+    /**
+     * Runs `fn` with revisions recorded as `markup` says, and the document's own setting untouched:
+     * nothing is written to `w:trackRevisions`, no settings part is created, and the mode a later read
+     * reports is the one that was there before (CR-002 section 28.1, for an editor whose agent must
+     * record its edits as a named author in a room whose tracking setting belongs to the document).
+     *
+     * The author, the date and the mode are restored in a `finally`, so a throw from `fn` cannot leave
+     * the package tracking. It is asynchronous for one reason: it awaits `seedAnnotationIds()` before
+     * running `fn`, so a revision written inside it cannot reuse an id from a part nobody has read
+     * (section 28.2). `fn` itself may be synchronous.
+     *
+     * Calls nest, and calls that overlap in time end in whatever order they end without leaving the
+     * package tracking. But the markup is the package's for as long as a call runs, not the call's:
+     * while two are running, **the later one's author and mode apply to every edit**, the earlier
+     * one's included, because nothing here can tell which asynchronous call an edit came from. Await
+     * one before starting another when they must be recorded as different authors (section 31).
+     */
+    async withTracking(markup, fn) {
+        await this.seedAnnotationIds();
+        const scope = { ...markup };
+        if (this.trackingScopes.length === 0) {
+            this.beforeScopes = { author: this.author, date: this.trackedChangeDate, override: this.trackingOverride };
+        }
+        this.trackingScopes.push(scope);
+        this.applyTrackingScope(scope);
+        try {
+            return await fn();
+        }
+        finally {
+            this.trackingScopes.splice(this.trackingScopes.indexOf(scope), 1);
+            const latest = this.trackingScopes[this.trackingScopes.length - 1];
+            if (latest !== undefined)
+                this.applyTrackingScope(latest);
+            else if (this.beforeScopes !== undefined) {
+                this.author = this.beforeScopes.author;
+                this.trackedChangeDate = this.beforeScopes.date;
+                this.trackingOverride = this.beforeScopes.override;
+                this.beforeScopes = undefined;
+            }
+        }
+    }
+    /**
+     * One `withTracking` call's markup made the package's. The tracker is left alone: the getter makes
+     * another when the mode differs, and the id counter it reads is the package's, so a tracker kept
+     * across the call cannot reissue an id given out inside it (section 31).
+     */
+    applyTrackingScope(scope) {
+        var _a;
+        this.author = scope.author;
+        this.trackedChangeDate = scope.date;
+        this.trackingOverride = (_a = scope.mode) !== null && _a !== void 0 ? _a : 'TrackAll';
+    }
     /** The mode as the settings part has it, unmarshalling the part (docx4j's async counterpart of the getter). */
     async getChangeTrackingMode() {
         var _a, _b;
@@ -287,8 +361,11 @@ export class WordprocessingMLPackage extends OpcPackage {
     async setChangeTrackingMode(mode) {
         this.trackingMode = mode;
         this.tracker = undefined;
+        this.annotationIdCounter = undefined;
         this.trackingPending = false;
         writeTrackRevisions(await this.settingsPart().getContents(), mode);
+        if (mode !== 'Off')
+            await this.seedAnnotationIds();
     }
     /** The settings part, created (with its relationship and content type) when the document has none. */
     settingsPart() {
@@ -318,6 +395,53 @@ export class WordprocessingMLPackage extends OpcPackage {
             this.tracker = new ChangeTracker(this, mode);
         return this.tracker;
     }
+    /**
+     * The objects an XPath selects in a part of this document, through the package's engine
+     * (CR-006; docx4j `MainDocumentPart.getJAXBNodesViaXPath`). The part defaults to the main
+     * document part, which is what a `//w:p[...]` expression means.
+     */
+    async selectObjects(xpath, options = {}) {
+        var _a;
+        const part = (_a = options.part) !== null && _a !== void 0 ? _a : this.getMainDocumentPart();
+        return part.selectObjects(xpath, { engine: this.xpathEngine, namespaces: options.namespaces });
+    }
+    /**
+     * Raises `annotationIdFloor` above every annotation id in the WordprocessingML parts that are not
+     * unmarshalled, reading each **privately** (`readContents`, CR-001 Phase D's device), so that a
+     * part nobody has touched keeps its byte-for-byte round trip and still cannot have its ids reused.
+     *
+     * Awaited by `setChangeTrackingMode()` and by `withTracking()`, which is where tracking is turned
+     * on; a caller that uses the synchronous `changeTrackingMode` setter on a document with unread
+     * parts should await this itself, since `nextId()` cannot (the content API's setters are
+     * synchronous, which is why the floor exists at all rather than the scan being made async).
+     *
+     * A part is read once for the bytes it holds: an agent that wraps every edit in `withTracking`
+     * would otherwise re-read every header, footer and note part each time (section 31). Its source
+     * bytes cannot change; bytes that were set are read again when they are set again.
+     */
+    async seedAnnotationIds() {
+        for (const part of this.parts) {
+            if (!(part instanceof XmlPart) || part.isUnmarshalled)
+                continue;
+            if (!part.partName.name.startsWith('/word/'))
+                continue;
+            const read = part.isUntouched ? true : await part.getBytes();
+            if (this.seededParts.get(part) === read)
+                continue;
+            let tree;
+            try {
+                tree = await part.readContents();
+            }
+            catch {
+                tree = undefined;
+            } // an unreadable part cannot hold ids we must avoid
+            if (typeof tree === 'object' && tree !== null) {
+                this.annotationIdFloor = highestAnnotationId(tree, this.annotationIdFloor);
+            }
+            this.seededParts.set(part, read);
+        }
+        return this.annotationIdFloor;
+    }
     /** TrackingHost: the trees a new revision id must be above, which is every part already unmarshalled. */
     markupRoots() {
         const out = [];
@@ -385,6 +509,36 @@ export class WordprocessingMLPackage extends OpcPackage {
             all.push(await part.getBody());
         return all;
     }
+    /**
+     * The document's style definitions as a verb that needs no `Body`: `ensure(ids)` splices in a
+     * style the document lacks, out of the same defaults `createPackage()` writes, with what it is
+     * based on and linked to (CR-002 section 22.2).
+     */
+    get styles() {
+        var _a;
+        return ((_a = this.stylesFacade) !== null && _a !== void 0 ? _a : (this.stylesFacade = new StylesFacade(this)));
+    }
+    /** The styles part, created with the defaults when the document has none (CR-002 section 22.2). */
+    ensureStyleDefinitionsPart() {
+        const main = this.getMainDocumentPart();
+        let part = main.styleDefinitionsPart;
+        if (!part) {
+            part = new StyleDefinitionsPart();
+            part.setXml(DEFAULT_STYLES_XML);
+            main.addTargetPart(part);
+        }
+        return part;
+    }
+    /**
+     * The document's list definitions as verbs that need no paragraph: `newList()` and
+     * `restart(numId)` (CR-002 section 19). `Paragraph.startNewList()` and `List.restart()` are
+     * Office JS's shapes and remain; this is for a caller that holds a `w:numId` rather than a
+     * paragraph - an editor with its own document model, writing `w:numPr` itself.
+     */
+    get numbering() {
+        var _a;
+        return ((_a = this.numberingFacade) !== null && _a !== void 0 ? _a : (this.numberingFacade = new NumberingFacade(this)));
+    }
     /**
      * Office JS `document.customXmlParts`: the custom XML data storage parts as views, with
      * `add`, and docx4j's `applyBindings()` / `updateFromContentControls()` (CR-002 section 3.5).

package/dist/parts/XmlPart.d.mts

@@ -1,6 +1,17 @@
 import { type Jsonix } from '@docx4j/generated-objects-ts';
 import { Part } from './Part.mjs';
 import { PartName } from '../opc/PartName.mjs';
+import { type Bound } from '../model/content/binder.mjs';
+/** What `selectObjects` needs: the engine to evaluate with, and any prefixes beyond the defaults. */
+export interface SelectOptions {
+    /** The engine; `pkg.selectObjects` and `Body.select` pass the package's. It is readied on the snapshot. */
+    engine?: {
+        ready(context?: Node): Promise<void>;
+        select(expression: string, context: Node, namespaces?: Record<string, string>): Node[];
+    } | undefined;
+    /** Prefixes added to (or overriding) the objects package's own table. */
+    namespaces?: Record<string, string> | undefined;
+}
 /** A qualified name for a part's root element. */
 export interface RootName {
     namespaceURI: string;
@@ -31,6 +42,12 @@ export declare class XmlPart<T = unknown> extends Part {
     /** True once contents were unmarshalled or set; the part is then re-marshalled on save. */
     get isUnmarshalled(): boolean;
     get isLoaded(): boolean;
+    /**
+     * True while the part holds nothing but its source: never unmarshalled, no contents or bytes set.
+     * Such a part is written back byte for byte, and what a private read finds in it cannot change,
+     * which is what lets a reader remember it (CR-002 section 31).
+     */
+    get isUntouched(): boolean;
     /** The unmarshalled contents (docx4j getJaxbElement()); throws when not yet unmarshalled. */
     get contents(): T;
     /** The root element as [name, value]; undefined until unmarshalled. */
@@ -57,8 +74,35 @@ export declare class XmlPart<T = unknown> extends Part {
     getXml(): Promise<string>;
     /** Marshalled bytes when unmarshalled or set, else the source bytes untouched. */
     getBytes(): Promise<Uint8Array>;
+    /**
+     * The objects an XPath selects in this part, through a DOM marshalled for the purpose
+     * (CR-006; docx4j `JaxbXmlPart.getJAXBNodesViaXPath`, which does it with a JAXB `Binder`).
+     *
+     * Each result carries the node the expression selected, the tree object behind it, the attribute
+     * name when an attribute was selected, and the node's path from the root. The DOM is a **snapshot**:
+     * changing it changes nothing, and a select leaves the part's own bytes alone - the marshal is
+     * thrown away. Every call marshals afresh, since the tree has no change log a cached snapshot could
+     * be checked against (CR-006 section 2).
+     *
+     * The prefixes default to the ones the objects package writes, so `//w:p[w:pPr/w:pStyle/@w:val='Heading1']`
+     * needs no mapping; `options.namespaces` adds to or overrides them. The engine is the caller's
+     * (`pkg.xpathEngine`: XPath 1.0 by default, 3.1 with `FontoXPathEngine`), and is readied here on
+     * the snapshot itself: whether an engine can evaluate a tree is a property of the document that
+     * tree is in (CR-002 section 21), and readying it on a marshal of its own would cost a second one
+     * (CR-002 section 31).
+     */
+    selectObjects(xpath: string, options?: SelectOptions): Promise<Bound[]>;
     /** The root element as a DOM element (docx4j XmlUtils.marshaltoW3CDomDocument). */
     marshalToNode(): Promise<Element>;
+    /**
+     * Unmarshals, and names the part when the runtime refuses. The runtime's own message says what is
+     * wrong and, since `@docx4j/jsonix` 3.4.0, where - `w:sz/@w:val (line 12): Argument [NaN] must be
+     * an integer` - but not which part it was reading, which is the first thing a person editing a
+     * part's XML needs (CR-002 section 27). The location it found is lifted onto the exception so a
+     * caller does not parse the message; `line` is undefined where the parser supplies no position,
+     * which is every browser (only xmldom carries a locator).
+     */
+    private unmarshal;
     /** The source root element's namespace declarations, prefix to URI (`xmlns=` is the empty prefix). */
     private recordDeclarations;
     /**

package/dist/parts/XmlPart.mjs

@@ -1,9 +1,10 @@
 import { unmarshalNode, marshalNode, NAMESPACE_PREFIXES } from '@docx4j/generated-objects-ts';
 import { Part } from './Part.mjs';
 import { Namespaces } from './Namespaces.mjs';
-import { Docx4JException } from '../opc/exceptions.mjs';
+import { Docx4JException, PartUnmarshalException } from '../opc/exceptions.mjs';
 import { parseXml, serializeXml, encodeText, decodeXmlText, XML_DECLARATION } from '../xml/dom.mjs';
 import { log } from '../model/properties/log.mjs';
+import { bindSnapshot, boundsOf } from '../model/content/binder.mjs';
 const XMLNS_NS = 'http://www.w3.org/2000/xmlns/';
 const MC_NS = Namespaces.MARKUP_COMPATIBILITY;
 /** The objects package's prefix table the other way round, prefix to URI, built once. */
@@ -18,6 +19,26 @@ function knownUriOf(prefix) {
     return prefixToUri.get(prefix);
 }
 const warnedPrefixes = new Set();
+/**
+ * The element or attribute a located runtime error names, out of its message: jsonix writes
+ * `w:sz/@w:val (line 7): ...` when it could place the fault and `w:bogus (line 3): ...` for an
+ * element, so the location is everything before the position or the colon - and `w:sz` must not be
+ * cut at its own prefix separator, which a naive split on `:` does.
+ */
+function locationOf(message, located) {
+    var _a;
+    if (!located)
+        return undefined;
+    return (_a = /^(.+?)(?: \(line \d+(?:, column \d+)?\))?: /.exec(message)) === null || _a === void 0 ? void 0 : _a[1];
+}
+/** The objects package's prefix table as XPath wants it, prefix to URI; built once. */
+const NAMESPACE_PREFIXES_BY_PREFIX = (() => {
+    const out = {};
+    for (const [uri, prefix] of Object.entries(NAMESPACE_PREFIXES))
+        if (prefix !== '' && !(prefix in out))
+            out[prefix] = uri;
+    return out;
+})();
 /**
  * A part whose content is a typed element of the object model (docx4j JaxbXmlPart<E>). `T` is the
  * root element's value type (`Document`, `Styles`, ...). Contents are unmarshalled on first
@@ -36,6 +57,14 @@ export class XmlPart extends Part {
     get isLoaded() {
         return this.element !== undefined || this.bytes !== undefined;
     }
+    /**
+     * True while the part holds nothing but its source: never unmarshalled, no contents or bytes set.
+     * Such a part is written back byte for byte, and what a private read finds in it cannot change,
+     * which is what lets a reader remember it (CR-002 section 31).
+     */
+    get isUntouched() {
+        return this.element === undefined && this.bytes === undefined;
+    }
     /** The unmarshalled contents (docx4j getJaxbElement()); throws when not yet unmarshalled. */
     get contents() {
         if (this.element === undefined)
@@ -56,7 +85,7 @@ export class XmlPart extends Part {
             const doc = parseXml(decodeXmlText(bytes));
             this.recordDeclarations(doc);
             (_b = this.preprocessor) === null || _b === void 0 ? void 0 : _b.call(this, doc, this);
-            this.element = await unmarshalNode(doc);
+            this.element = await this.unmarshal(doc);
             (_c = this.rootName) !== null && _c !== void 0 ? _c : (this.rootName = { namespaceURI: this.element.name.namespaceURI, localPart: this.element.name.localPart });
             this.bytes = undefined;
         }
@@ -81,7 +110,7 @@ export class XmlPart extends Part {
         const doc = parseXml(decodeXmlText(bytes));
         this.recordDeclarations(doc);
         (_b = this.preprocessor) === null || _b === void 0 ? void 0 : _b.call(this, doc, this);
-        return (await unmarshalNode(doc)).value;
+        return (await this.unmarshal(doc)).value;
     }
     /** Replaces the contents (docx4j setJaxbElement / setContents). The root name defaults to the part's. */
     setContents(value, rootName) {
@@ -116,6 +145,36 @@ export class XmlPart extends Part {
             throw new Docx4JException(`Part ${this.partName} has no content and no source container`);
         return loaded;
     }
+    /**
+     * The objects an XPath selects in this part, through a DOM marshalled for the purpose
+     * (CR-006; docx4j `JaxbXmlPart.getJAXBNodesViaXPath`, which does it with a JAXB `Binder`).
+     *
+     * Each result carries the node the expression selected, the tree object behind it, the attribute
+     * name when an attribute was selected, and the node's path from the root. The DOM is a **snapshot**:
+     * changing it changes nothing, and a select leaves the part's own bytes alone - the marshal is
+     * thrown away. Every call marshals afresh, since the tree has no change log a cached snapshot could
+     * be checked against (CR-006 section 2).
+     *
+     * The prefixes default to the ones the objects package writes, so `//w:p[w:pPr/w:pStyle/@w:val='Heading1']`
+     * needs no mapping; `options.namespaces` adds to or overrides them. The engine is the caller's
+     * (`pkg.xpathEngine`: XPath 1.0 by default, 3.1 with `FontoXPathEngine`), and is readied here on
+     * the snapshot itself: whether an engine can evaluate a tree is a property of the document that
+     * tree is in (CR-002 section 21), and readying it on a marshal of its own would cost a second one
+     * (CR-002 section 31).
+     */
+    async selectObjects(xpath, options = {}) {
+        var _a;
+        const element = (_a = this.element) !== null && _a !== void 0 ? _a : (await this.getContents(), this.element);
+        if (element === undefined)
+            throw new Docx4JException(`Part ${this.partName} has no contents to select over`);
+        const engine = options.engine;
+        if (engine === undefined)
+            throw new Docx4JException(`selectObjects on ${this.partName} needs an XPath engine; pkg.selectObjects passes the package's`);
+        const snapshot = await bindSnapshot(element);
+        await engine.ready(snapshot.root);
+        const namespaces = { ...NAMESPACE_PREFIXES_BY_PREFIX, ...options.namespaces };
+        return boundsOf(engine.select(xpath, snapshot.root, namespaces), snapshot);
+    }
     /** The root element as a DOM element (docx4j XmlUtils.marshaltoW3CDomDocument). */
     async marshalToNode() {
         if (this.element === undefined)
@@ -124,6 +183,30 @@ export class XmlPart extends Part {
         this.declareIgnorablePrefixes(root);
         return root;
     }
+    /**
+     * Unmarshals, and names the part when the runtime refuses. The runtime's own message says what is
+     * wrong and, since `@docx4j/jsonix` 3.4.0, where - `w:sz/@w:val (line 12): Argument [NaN] must be
+     * an integer` - but not which part it was reading, which is the first thing a person editing a
+     * part's XML needs (CR-002 section 27). The location it found is lifted onto the exception so a
+     * caller does not parse the message; `line` is undefined where the parser supplies no position,
+     * which is every browser (only xmldom carries a locator).
+     */
+    async unmarshal(doc) {
+        var _a, _b;
+        try {
+            return await unmarshalNode(doc);
+        }
+        catch (cause) {
+            const located = cause;
+            const message = typeof (located === null || located === void 0 ? void 0 : located.message) === 'string' ? located.message : String(cause);
+            throw new PartUnmarshalException(`${this.partName}: ${message}`, this.partName.name, {
+                cause,
+                location: locationOf(message, (located === null || located === void 0 ? void 0 : located.jsonixLocated) === true),
+                line: typeof ((_a = located === null || located === void 0 ? void 0 : located.node) === null || _a === void 0 ? void 0 : _a.lineNumber) === 'number' ? located.node.lineNumber : undefined,
+                column: typeof ((_b = located === null || located === void 0 ? void 0 : located.node) === null || _b === void 0 ? void 0 : _b.columnNumber) === 'number' ? located.node.columnNumber : undefined,
+            });
+        }
+    }
     /** The source root element's namespace declarations, prefix to URI (`xmlns=` is the empty prefix). */
     recordDeclarations(doc) {
         var _a;

package/dist/parts/sml/index.d.mts

@@ -1,6 +1,7 @@
 import type * as sml from '@docx4j/generated-objects-ts/modules/org_xlsx4j_sml';
+import type * as x14 from '@docx4j/generated-objects-ts/modules/org_xlsx4j_com_microsoft_schemas_office_spreadsheetml_x2009_x9_main';
+import type * as x15 from '@docx4j/generated-objects-ts/modules/org_xlsx4j_com_microsoft_schemas_office_spreadsheetml_x2010_x11_main';
 import { XmlPart } from '../XmlPart.mjs';
-import { DefaultXmlPart } from '../DefaultXmlPart.mjs';
 import { BinaryPart } from '../BinaryPart.mjs';
 import { Part } from '../Part.mjs';
 import { PartName } from '../../opc/PartName.mjs';
@@ -99,31 +100,31 @@ export declare class PrinterSettingsPart extends BinaryPart {
     constructor(partName: PartName | string);
 }
 /** A slicer cache (`x14:slicerCacheDefinition`), from the workbook. docx4j `SlicerCachePart`. */
-export declare class SlicerCachePart extends DefaultXmlPart {
+export declare class SlicerCachePart extends XmlPart<x14.CTSlicerCacheDefinition> {
     constructor(partName?: PartName | string);
 }
 /** A sheet's slicers (`x14:slicers`). docx4j `SlicersPart`. */
-export declare class SlicersPart extends DefaultXmlPart {
+export declare class SlicersPart extends XmlPart<x14.CTSlicers> {
     constructor(partName?: PartName | string);
 }
 /** A timeline cache (`x15:timelineCacheDefinition`), from the workbook. docx4j `TimelineCachePart`. */
-export declare class TimelineCachePart extends DefaultXmlPart {
+export declare class TimelineCachePart extends XmlPart<x15.CTTimelineCacheDefinition> {
     constructor(partName?: PartName | string);
 }
 /** A sheet's timelines (`x15:timelines`). docx4j `TimelinesPart`. */
-export declare class TimelinesPart extends DefaultXmlPart {
+export declare class TimelinesPart extends XmlPart<x15.CTTimelines> {
     constructor(partName?: PartName | string);
 }
 /** A form control's properties (`x14:formControlPr`), from a worksheet. docx4j `ControlPropertiesPart`. */
-export declare class ControlPropertiesPart extends DefaultXmlPart {
+export declare class ControlPropertiesPart extends XmlPart<x14.CTFormControlPr> {
     constructor(partName?: PartName | string);
 }
 /** The properties of a custom data part (`x14:datastoreItem`). docx4j `CustomDataPropertiesPart`. */
-export declare class CustomDataPropertiesPart extends DefaultXmlPart {
+export declare class CustomDataPropertiesPart extends XmlPart<x14.CTDatastoreItem> {
     constructor(partName?: PartName | string);
 }
 /** A survey (`x15:survey`), from the workbook. docx4j `SurveyPart`. */
-export declare class SurveyPart extends DefaultXmlPart {
+export declare class SurveyPart extends XmlPart<x15.CTSurvey> {
     constructor(partName?: PartName | string);
 }
 /**

package/dist/parts/sml/index.mjs

@@ -1,10 +1,13 @@
 import { XmlPart } from '../XmlPart.mjs';
-import { DefaultXmlPart } from '../DefaultXmlPart.mjs';
 import { BinaryPart } from '../BinaryPart.mjs';
 import { ContentTypes } from '../../opc/ContentTypes.mjs';
 import { Namespaces } from '../Namespaces.mjs';
 import { Xlsx4jException } from '../../opc/exceptions.mjs';
 const S = 'http://schemas.openxmlformats.org/spreadsheetml/2006/main';
+/** The Excel 2010 extension namespace (x14; docx4j's org.xlsx4j...x2009.x9.main). */
+const X14 = 'http://schemas.microsoft.com/office/spreadsheetml/2009/9/main';
+/** The Excel 2013 extension namespace (x15; docx4j's org.xlsx4j...x2010.x11.main). */
+const X15 = 'http://schemas.microsoft.com/office/spreadsheetml/2010/11/main';
 export class WorkbookPart extends XmlPart {
     constructor(partName = '/xl/workbook.xml', contentType = ContentTypes.SPREADSHEETML_WORKBOOK) {
         super(partName, contentType, Namespaces.SPREADSHEETML_WORKBOOK, { namespaceURI: S, localPart: 'workbook' });
@@ -196,50 +199,51 @@ export class PrinterSettingsPart extends BinaryPart {
         super(partName, ContentTypes.SPREADSHEETML_PRINTER_SETTINGS, Namespaces.SPREADSHEETML_PRINTER_SETTINGS);
     }
 }
-// The Excel 2010 and 2013 extension parts (CR-004 phase A; docx4j
-// org.docx4j.openpackaging.parts.SpreadsheetML).  The seven XML ones are `DefaultXmlPart`s for
-// now: their DOM round-trips byte for byte, and nothing re-marshals them, so an `mc:Ignorable`
-// they carry is untouched.  Phase B makes them `XmlPart`s over the `x14` and `x15` roots.
+// The Excel 2010 and 2013 extension parts (CR-004; docx4j
+// org.docx4j.openpackaging.parts.SpreadsheetML).  Phase A held the seven XML ones as DOM; phase B
+// types them over the x14 and x15 roots the objects package's CR-022 regeneration bound, so their
+// contents read like any other part's and a re-marshalled root is Excel's own shape (the
+// mc:Ignorable Excel writes on them is a property of each root, re-declared by `XmlPart`).
 /** A slicer cache (`x14:slicerCacheDefinition`), from the workbook. docx4j `SlicerCachePart`. */
-export class SlicerCachePart extends DefaultXmlPart {
+export class SlicerCachePart extends XmlPart {
     constructor(partName = '/xl/slicerCaches/slicerCache1.xml') {
-        super(partName, ContentTypes.SPREADSHEETML_SLICER_CACHE, Namespaces.SPREADSHEETML_SLICER_CACHE);
+        super(partName, ContentTypes.SPREADSHEETML_SLICER_CACHE, Namespaces.SPREADSHEETML_SLICER_CACHE, { namespaceURI: X14, localPart: 'slicerCacheDefinition' });
     }
 }
 /** A sheet's slicers (`x14:slicers`). docx4j `SlicersPart`. */
-export class SlicersPart extends DefaultXmlPart {
+export class SlicersPart extends XmlPart {
     constructor(partName = '/xl/slicers/slicer1.xml') {
-        super(partName, ContentTypes.SPREADSHEETML_SLICERS, Namespaces.SPREADSHEETML_SLICERS);
+        super(partName, ContentTypes.SPREADSHEETML_SLICERS, Namespaces.SPREADSHEETML_SLICERS, { namespaceURI: X14, localPart: 'slicers' });
     }
 }
 /** A timeline cache (`x15:timelineCacheDefinition`), from the workbook. docx4j `TimelineCachePart`. */
-export class TimelineCachePart extends DefaultXmlPart {
+export class TimelineCachePart extends XmlPart {
     constructor(partName = '/xl/timelineCaches/timelineCache1.xml') {
-        super(partName, ContentTypes.SPREADSHEETML_TIMELINE_CACHE, Namespaces.SPREADSHEETML_TIMELINE_CACHE);
+        super(partName, ContentTypes.SPREADSHEETML_TIMELINE_CACHE, Namespaces.SPREADSHEETML_TIMELINE_CACHE, { namespaceURI: X15, localPart: 'timelineCacheDefinition' });
     }
 }
 /** A sheet's timelines (`x15:timelines`). docx4j `TimelinesPart`. */
-export class TimelinesPart extends DefaultXmlPart {
+export class TimelinesPart extends XmlPart {
     constructor(partName = '/xl/timelines/timeline1.xml') {
-        super(partName, ContentTypes.SPREADSHEETML_TIMELINES, Namespaces.SPREADSHEETML_TIMELINES);
+        super(partName, ContentTypes.SPREADSHEETML_TIMELINES, Namespaces.SPREADSHEETML_TIMELINES, { namespaceURI: X15, localPart: 'timelines' });
     }
 }
 /** A form control's properties (`x14:formControlPr`), from a worksheet. docx4j `ControlPropertiesPart`. */
-export class ControlPropertiesPart extends DefaultXmlPart {
+export class ControlPropertiesPart extends XmlPart {
     constructor(partName = '/xl/ctrlProps/ctrlProp1.xml') {
-        super(partName, ContentTypes.SPREADSHEETML_CONTROL_PROPERTIES, Namespaces.SPREADSHEETML_CONTROL_PROPERTIES);
+        super(partName, ContentTypes.SPREADSHEETML_CONTROL_PROPERTIES, Namespaces.SPREADSHEETML_CONTROL_PROPERTIES, { namespaceURI: X14, localPart: 'formControlPr' });
     }
 }
 /** The properties of a custom data part (`x14:datastoreItem`). docx4j `CustomDataPropertiesPart`. */
-export class CustomDataPropertiesPart extends DefaultXmlPart {
+export class CustomDataPropertiesPart extends XmlPart {
     constructor(partName = '/xl/customDataProps/customDataProps1.xml') {
-        super(partName, ContentTypes.SPREADSHEETML_CUSTOM_DATA_PROPERTIES, Namespaces.SPREADSHEETML_CUSTOM_DATA_PROPERTIES);
+        super(partName, ContentTypes.SPREADSHEETML_CUSTOM_DATA_PROPERTIES, Namespaces.SPREADSHEETML_CUSTOM_DATA_PROPERTIES, { namespaceURI: X14, localPart: 'datastoreItem' });
     }
 }
 /** A survey (`x15:survey`), from the workbook. docx4j `SurveyPart`. */
-export class SurveyPart extends DefaultXmlPart {
+export class SurveyPart extends XmlPart {
     constructor(partName = '/xl/surveys/survey1.xml') {
-        super(partName, ContentTypes.SPREADSHEETML_SURVEY, Namespaces.SPREADSHEETML_SURVEY);
+        super(partName, ContentTypes.SPREADSHEETML_SURVEY, Namespaces.SPREADSHEETML_SURVEY, { namespaceURI: X15, localPart: 'survey' });
     }
 }
 /**

package/dist/parts/wml/index.d.mts

@@ -85,8 +85,16 @@ export declare class MainDocumentPart extends DocumentPart<wml.Document> {
     /** The style ids used directly in the document (docx4j `getStylesInUse()`); not those that
      *  others are merely based on. */
     getStylesInUse(): Promise<Set<string>>;
-    /** The block-level content of each story, in docx4j's order: the body, then the headers and
-     *  footers, the endnotes, the footnotes and the comments. */
+    /**
+     * The block-level content of each story, in docx4j's order: the body, then the headers and
+     * footers, the endnotes, the footnotes and the comments.
+     *
+     * Every story is read **privately** (`readContents`, which answers the unmarshalled tree when
+     * there is one and parses without keeping it when there is not), so asking a document which
+     * fonts it uses does not cost any part its byte-for-byte round trip. The body used to come from
+     * `getContents()`, which unmarshalled the main part and so re-marshalled it on the next save
+     * (CR-001 section 18).
+     */
     private stories;
     /** The styles part and its `w:default="1"` style ids, read without costing it its round trip. */
     private styleSource;

package/dist/parts/wml/index.mjs

@@ -207,11 +207,19 @@ export class MainDocumentPart extends DocumentPart {
     async getStylesInUse() {
         return walkStories(await this.stories(), await this.styleSource(), undefined, false).styles;
     }
-    /** The block-level content of each story, in docx4j's order: the body, then the headers and
-     *  footers, the endnotes, the footnotes and the comments. */
+    /**
+     * The block-level content of each story, in docx4j's order: the body, then the headers and
+     * footers, the endnotes, the footnotes and the comments.
+     *
+     * Every story is read **privately** (`readContents`, which answers the unmarshalled tree when
+     * there is one and parses without keeping it when there is not), so asking a document which
+     * fonts it uses does not cost any part its byte-for-byte round trip. The body used to come from
+     * `getContents()`, which unmarshalled the main part and so re-marshalled it on the next save
+     * (CR-001 section 18).
+     */
     async stories() {
         var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
-        const out = [(_b = (_a = (await this.getContents()).body) === null || _a === void 0 ? void 0 : _a.content) !== null && _b !== void 0 ? _b : []];
+        const out = [(_b = (_a = (await this.readContents()).body) === null || _a === void 0 ? void 0 : _a.content) !== null && _b !== void 0 ? _b : []];
         const rp = this.relationshipsPart;
         for (const r of (_c = rp === null || rp === void 0 ? void 0 : rp.relationships.relationship) !== null && _c !== void 0 ? _c : []) {
             const part = rp === null || rp === void 0 ? void 0 : rp.getPart(r);

package/dist/parts/wml/spliceableStyles.d.mts

@@ -0,0 +1 @@
+export declare const SPLICEABLE_STYLES_XML = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<w:styles xmlns:r=\"http://schemas.openxmlformats.org/officeDocument/2006/relationships\" xmlns:w=\"http://schemas.openxmlformats.org/wordprocessingml/2006/main\">\n<w:style w:type=\"paragraph\" w:styleId=\"BlockText\">\n    <w:name w:val=\"Block Text\" />\n    <w:basedOn w:val=\"Normal\" />\n    <w:uiPriority w:val=\"99\" />\n    <w:unhideWhenUsed />\n    <w:rsid w:val=\"00841CD9\" />\n    <w:pPr>\n      <w:pBdr>\n        <w:top w:val=\"single\" w:sz=\"2\" w:space=\"10\" w:color=\"4F81BD\" w:themeColor=\"accent1\" w:shadow=\"1\" />\n        <w:left w:val=\"single\" w:sz=\"2\" w:space=\"10\" w:color=\"4F81BD\" w:themeColor=\"accent1\" w:shadow=\"1\" />\n        <w:bottom w:val=\"single\" w:sz=\"2\" w:space=\"10\" w:color=\"4F81BD\" w:themeColor=\"accent1\" w:shadow=\"1\" />\n        <w:right w:val=\"single\" w:sz=\"2\" w:space=\"10\" w:color=\"4F81BD\" w:themeColor=\"accent1\" w:shadow=\"1\" />\n      </w:pBdr>\n      <w:ind w:left=\"1152\" w:right=\"1152\" />\n    </w:pPr>\n    <w:rPr>\n      <w:rFonts w:eastAsiaTheme=\"minorEastAsia\" />\n      <w:i />\n      <w:iCs />\n      <w:color w:val=\"4F81BD\" w:themeColor=\"accent1\" />\n    </w:rPr>\n  </w:style>\n  <w:style w:type=\"paragraph\" w:styleId=\"EndnoteText\">\n    <w:name w:val=\"endnote text\" />\n    <w:basedOn w:val=\"Normal\" />\n    <w:link w:val=\"EndnoteTextChar\" />\n    <w:uiPriority w:val=\"99\" />\n    <w:unhideWhenUsed />\n    <w:rsid w:val=\"00841CD9\" />\n    <w:rPr>\n      <w:sz w:val=\"20\" />\n      <w:szCs w:val=\"20\" />\n    </w:rPr>\n  </w:style>\n  <w:style w:type=\"character\" w:customStyle=\"1\" w:styleId=\"EndnoteTextChar\">\n    <w:name w:val=\"Endnote Text Char\" />\n    <w:basedOn w:val=\"DefaultParagraphFont\" />\n    <w:link w:val=\"EndnoteText\" />\n    <w:uiPriority w:val=\"99\" />\n    <w:rsid w:val=\"00841CD9\" />\n    <w:rPr>\n      <w:sz w:val=\"20\" />\n      <w:szCs w:val=\"20\" />\n    </w:rPr>\n  </w:style>\n  <w:style w:type=\"paragraph\" w:styleId=\"Footer\">\n    <w:name w:val=\"footer\" />\n    <w:basedOn w:val=\"Normal\" />\n    <w:link w:val=\"FooterChar\" />\n    <w:uiPriority w:val=\"99\" />\n    <w:unhideWhenUsed />\n    <w:rsid w:val=\"00841CD9\" />\n    <w:pPr>\n      <w:tabs>\n        <w:tab w:val=\"center\" w:pos=\"4680\" />\n        <w:tab w:val=\"right\" w:pos=\"9360\" />\n      </w:tabs>\n    </w:pPr>\n  </w:style>\n  <w:style w:type=\"character\" w:customStyle=\"1\" w:styleId=\"FooterChar\">\n    <w:name w:val=\"Footer Char\" />\n    <w:basedOn w:val=\"DefaultParagraphFont\" />\n    <w:link w:val=\"Footer\" />\n    <w:uiPriority w:val=\"99\" />\n    <w:rsid w:val=\"00841CD9\" />\n  </w:style>\n  <w:style w:type=\"paragraph\" w:styleId=\"FootnoteText\">\n    <w:name w:val=\"footnote text\" />\n    <w:basedOn w:val=\"Normal\" />\n    <w:link w:val=\"FootnoteTextChar\" />\n    <w:uiPriority w:val=\"99\" />\n    <w:unhideWhenUsed />\n    <w:rsid w:val=\"00841CD9\" />\n    <w:rPr>\n      <w:sz w:val=\"20\" />\n      <w:szCs w:val=\"20\" />\n    </w:rPr>\n  </w:style>\n  <w:style w:type=\"character\" w:customStyle=\"1\" w:styleId=\"FootnoteTextChar\">\n    <w:name w:val=\"Footnote Text Char\" />\n    <w:basedOn w:val=\"DefaultParagraphFont\" />\n    <w:link w:val=\"FootnoteText\" />\n    <w:uiPriority w:val=\"99\" />\n    <w:rsid w:val=\"00841CD9\" />\n    <w:rPr>\n      <w:sz w:val=\"20\" />\n      <w:szCs w:val=\"20\" />\n    </w:rPr>\n  </w:style>\n<w:style w:type=\"character\" w:styleId=\"FootnoteReference\">\n    <w:name w:val=\"footnote reference\" />\n    <w:basedOn w:val=\"DefaultParagraphFont\" />\n    <w:uiPriority w:val=\"99\" />\n    <w:unhideWhenUsed />\n    <w:rsid w:val=\"00D1197D\" />\n    <w:rPr>\n      <w:vertAlign w:val=\"superscript\" />\n    </w:rPr>\n  </w:style>\n  <w:style w:type=\"character\" w:styleId=\"EndnoteReference\">\n    <w:name w:val=\"endnote reference\" />\n    <w:basedOn w:val=\"DefaultParagraphFont\" />\n    <w:uiPriority w:val=\"99\" />\n    <w:unhideWhenUsed />\n    <w:rsid w:val=\"00D1197D\" />\n    <w:rPr>\n      <w:vertAlign w:val=\"superscript\" />\n    </w:rPr>\n  </w:style>\n</w:styles>";