@docx4j/core-ts 0.1.5 → 0.2.0

package/dist/packages/WordprocessingMLPackage.d.mts

@@ -1,18 +1,21 @@
 import { OpcPackage, type PackageSource } from './OpcPackage.mjs';
 import type { LoadOptions } from '../opc/Load.mjs';
 import type { Part } from '../parts/Part.mjs';
-import { MainDocumentPart, type NumberingDefinitionsPart } from '../parts/wml/index.mjs';
+import { MainDocumentPart, StyleDefinitionsPart, 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 { ChangeTracker, type ChangeTrackingMode, type TrackingHost, type TrackingScope } from '../model/content/tracking.mjs';
 import { NumberingFacade } from '../model/content/List.mjs';
+import { StylesFacade } from '../model/content/stylesFacade.mjs';
+import type { Bound } from '../model/content/binder.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 { XmlPart } from '../parts/XmlPart.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). */
@@ -59,6 +62,25 @@ export declare class WordprocessingMLPackage extends OpcPackage implements Track
     private tracker;
     /** Set when `changeTrackingMode` was written but the settings part was not unmarshalled yet. */
     private trackingPending;
+    /**
+     * `withTracking`'s mode for the duration of one call: read by the getter before everything else
+     * and **never** written by the setter, so it touches neither the settings part, `trackingPending`
+     * nor the cached `trackingMode` (CR-002 section 28.1).
+     */
+    private trackingOverride;
+    /**
+     * 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).
+     */
+    private trackingScopes;
+    private beforeScopes;
+    /**
+     * 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.
+     */
+    private seededParts;
     /**
      * 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
@@ -131,6 +153,30 @@ export declare class WordprocessingMLPackage extends OpcPackage implements Track
      */
     get changeTrackingMode(): ChangeTrackingMode;
     set changeTrackingMode(mode: ChangeTrackingMode);
+    /**
+     * 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).
+     */
+    withTracking<T>(markup: TrackingScope, fn: () => T | Promise<T>): Promise<T>;
+    /**
+     * 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).
+     */
+    private applyTrackingScope;
     /** 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. */
@@ -145,6 +191,41 @@ export declare class WordprocessingMLPackage extends OpcPackage implements Track
     getTrackedChanges(): TrackedChange[];
     /** The tracker every content-API mutation asks for; undefined while the mode is `Off`. */
     get changeTracker(): ChangeTracker | undefined;
+    /**
+     * 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.
+     */
+    selectObjects(xpath: string, options?: {
+        part?: XmlPart<unknown>;
+        namespaces?: Record<string, string>;
+    }): Promise<Bound[]>;
+    /**
+     * 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).
+     */
+    annotationIdFloor: number;
+    /**
+     * TrackingHost: the last annotation id issued, shared by every tracker this package makes (CR-002
+     * section 31). Forgotten when the mode is set, as the tracker used to be, so that the next id is
+     * found by a fresh scan of whatever has arrived since by other routes (`insertOoxml`, `setContents`).
+     */
+    annotationIdCounter: number | undefined;
+    /**
+     * 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.
+     */
+    seedAnnotationIds(): Promise<number>;
     /** 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. */
@@ -162,6 +243,15 @@ export declare class WordprocessingMLPackage extends OpcPackage implements Track
      * `customXmlParts.load()`; every node call is synchronous afterwards.
      */
     xpathEngine: XPathEngine;
+    /**
+     * 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(): StylesFacade;
+    private stylesFacade;
+    /** The styles part, created with the defaults when the document has none (CR-002 section 22.2). */
+    ensureStyleDefinitionsPart(): StyleDefinitionsPart;
     /**
      * 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

package/dist/packages/WordprocessingMLPackage.mjs

@@ -12,8 +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';
@@ -68,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
@@ -79,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
@@ -258,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;
@@ -268,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);
@@ -276,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;
@@ -288,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() {
@@ -319,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 = [];
@@ -386,6 +509,26 @@ 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

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);
 }
 /**