@docx4j/core-ts 0.4.0 → 0.6.0

package/dist/packages/WordprocessingMLPackage.mjs

@@ -4,24 +4,33 @@ import { registerPackageClass } from './registry.mjs';
 import { ContentTypes } from '../opc/ContentTypes.mjs';
 import { Docx4JException } from '../opc/exceptions.mjs';
 import { Namespaces } from '../parts/Namespaces.mjs';
-import { MainDocumentPart, StyleDefinitionsPart, DocumentSettingsPart } from '../parts/wml/index.mjs';
+import { MainDocumentPart, StyleDefinitionsPart, DocumentSettingsPart, GlossaryDocumentPart } 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 { Body, resolveStory, trackedChangesOfStory } from '../model/content/Body.mjs';
+import { pieceMatcher } from '../model/content/trackedChangeFilter.mjs';
 import { CustomXmlPartCollection } from '../model/customxml/CustomXmlPartCollection.mjs';
 import { DefaultXPathEngine } from '../model/customxml/xpath.mjs';
 import { ChangeTracker, highestAnnotationId } from '../model/content/tracking.mjs';
 import { NumberingFacade } from '../model/content/List.mjs';
 import { StylesFacade } from '../model/content/stylesFacade.mjs';
 import { flushPendingCommentRemovals } from '../model/content/Comment.mjs';
+import { GlossaryEntries } from '../model/content/placeholders.mjs';
 import { PropertyResolver } from '../model/properties/PropertyResolver.mjs';
 import { PropertyResolverNotCreatedException } from '../opc/exceptions.mjs';
+import { flushPendingNoteRemovals, notesGoing } from '../model/content/TrackedChange.mjs';
+import { flushPendingRelationshipRemovals } from '../model/content/relationships.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';
+// Registers the text model's outline reader with Body.outline (CR-012 D3), the same way: the content API
+// can't import the text model, which imports it.
+import '../model/text/outline.mjs';
+import { Texts } from '../model/text/Texts.mjs';
 const MAIN_CONTENT_TYPES = [
     ContentTypes.WORDPROCESSINGML_DOCUMENT,
     ContentTypes.WORDPROCESSINGML_DOCUMENT_MACROENABLED,
@@ -88,6 +97,26 @@ export class WordprocessingMLPackage extends OpcPackage {
          * the package is saved (check 32; `TrackedChange`). An extension.
          */
         this.pendingCommentRemovals = new Set();
+        /**
+         * Footnotes and endnotes whose references went with content a tracked change took away (a rejected
+         * insertion, an accepted deletion, a row or cell, a move's other half): their entries go from the
+         * notes parts when the package is saved, each unless a reference to it still stands, as Word took
+         * them (CR-002 section 44; `TrackedChange`). An extension.
+         */
+        this.pendingNoteRemovals = { footnote: new Set(), endnote: new Set() };
+        /**
+         * Relationships, by the name of their part, that a picture removed outright referenced (tracking off,
+         * or a picture taken back from its author's own insertion): each goes when the package is saved if
+         * nothing then references it, and its part with it when nothing else targets that (CR-002 section
+         * 47). Settled on save, not at once, so a picture cut and pasted back keeps its image. An extension.
+         */
+        this.pendingRelationshipRemovals = new Map();
+        /**
+         * The glossary's placeholder entries: read privately when a body is first read (`getBody`, `Word.run`), and those a
+         * placeholder written since names, which go into the glossary when the package is saved, the glossary made where the
+         * file has none (CR-002 section 63, D8 and D9). An extension.
+         */
+        this.glossaryEntries = new GlossaryEntries();
         /**
          * 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
@@ -220,6 +249,10 @@ export class WordprocessingMLPackage extends OpcPackage {
             this.resolver = resolver;
             this.resolverPending = undefined;
             return resolver;
+        }, (e) => {
+            // not kept: a styles part put right (setXml) is read again on the next call
+            this.resolverPending = undefined;
+            throw e;
         }));
         return this.resolverPending;
     }
@@ -393,12 +426,99 @@ export class WordprocessingMLPackage extends OpcPackage {
     }
     /**
      * 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.
+     * in document order (headers and footers have their own `Body`; `getAllTrackedChanges` lists
+     * every story). The part must be unmarshalled, as `body` needs it to be.
      */
     getTrackedChanges() {
         return this.body.getTrackedChanges();
     }
+    /**
+     * Every tracked change in every story, in docx4j's order (its CR-043 `TrackedChanges.in`, CR-011):
+     * the main document, each footnote, each endnote, each comment, then the headers and footers in the
+     * order the sections reference them; a text box's after the story it is in. Each story's are its
+     * `Body.getTrackedChanges()`, grouped as Office JS groups them, so changes never group across two
+     * stories. `TrackedChange.part` says which part each is in.
+     *
+     * With a filter, the changes with a piece it matches, each whole (docx4j's `in(pkg, filter)`).
+     *
+     * A story part whose source holds no revision markup is not read, so it keeps its bytes; one that
+     * does is unmarshalled, since the views returned must be resolvable, and so is re-marshalled on save.
+     * An extension: Office JS lists one body at a time.
+     */
+    async getAllTrackedChanges(filter) {
+        const matches = filter === undefined ? undefined : pieceMatcher(filter);
+        const out = [];
+        for (const body of await this.revisedStories())
+            out.push(...trackedChangesOfStory(body));
+        return matches ? out.filter((change) => change.pieces.some(matches)) : out;
+    }
+    /**
+     * Accepts every tracked change in every story: the main document, the footnotes, the endnotes and
+     * the comments, the headers and footers, and the text boxes in each. Word's
+     * `Document.AcceptAllRevisions` did that on docx4j's CR-043 probe (Word 16.0.20326), and left no
+     * revision in any story; `Body.acceptAll` resolves its own story only, as Office JS's `body` does
+     * (CR-002 section 49). A story part with no revision markup is not read, so it keeps its bytes.
+     * Returns how many changes were listed, story by story. An extension, named after Word's verb.
+     *
+     * With a filter (CR-011), only the single changes it matches are accepted, as `Body.acceptAll`
+     * takes one, and the count is of the listed changes with a matching piece.
+     */
+    async acceptAllRevisions(filter) {
+        return this.resolveEveryStory('accept', filter);
+    }
+    /** Rejects every tracked change in every story, as `acceptAllRevisions` accepts them (Word's `Document.RejectAllRevisions`). */
+    async rejectAllRevisions(filter) {
+        return this.resolveEveryStory('reject', filter);
+    }
+    async resolveEveryStory(what, filter) {
+        if (filter !== undefined)
+            pieceMatcher(filter); // a filter misread throws before anything is read or resolved
+        let count = 0;
+        for (const body of await this.revisedStories())
+            count += resolveStory(body, what, filter);
+        return count;
+    }
+    /**
+     * The body of every story whose part holds revision markup, in docx4j's order (its CR-043
+     * `TrackedChanges.in`): the main document, each footnote, each endnote, each comment, then the
+     * headers and footers in section order (`inSectionOrder`). A footnote, an endnote or a comment is a
+     * body of its own over its content.
+     */
+    async revisedStories() {
+        var _a, _b;
+        const main = this.getMainDocumentPart();
+        const out = [];
+        if (await holdsRevisions(main))
+            out.push(await main.getBody());
+        // a note or comment a resolution has taken the reference or anchor of goes on save; it is no story now
+        const pending = this.pendingNoteRemovals;
+        const going = pending.footnote.size + pending.endnote.size > 0 ? notesGoing(await main.readContents(), pending) : pending;
+        for (const [part, kind] of [[main.footnotesPart, 'footnote'], [main.endnotesPart, 'endnote']]) {
+            if (!part || !(await holdsRevisions(part)))
+                continue;
+            const contents = await part.getContents();
+            for (const note of (_a = (kind === 'footnote' ? contents.footnote : contents.endnote)) !== null && _a !== void 0 ? _a : []) {
+                if ((note.type === undefined || note.type === 'normal') && going[kind].has(Number(note.id)))
+                    continue;
+                out.push(new Body(part, note, `${kind}:${note.id}`, this));
+            }
+        }
+        const comments = main.commentsPart;
+        if (comments && (await holdsRevisions(comments))) {
+            for (const comment of (_b = (await comments.getContents()).comment) !== null && _b !== void 0 ? _b : []) {
+                if (this.pendingCommentRemovals.has(comment.id))
+                    continue;
+                out.push(new Body(comments, comment, `comment:${comment.id}`, this));
+            }
+        }
+        const revised = [];
+        for (const part of [...main.headerParts, ...main.footerParts])
+            if (await holdsRevisions(part))
+                revised.push(part);
+        for (const part of revised.length > 1 ? await inSectionOrder(main, revised) : revised)
+            out.push(await part.getBody());
+        return out;
+    }
     /** The tracker every content-API mutation asks for; undefined while the mode is `Off`. */
     get changeTracker() {
         const mode = this.changeTrackingMode;
@@ -506,6 +626,13 @@ export class WordprocessingMLPackage extends OpcPackage {
         target.author = { ...this.author };
         for (const id of this.pendingCommentRemovals)
             target.pendingCommentRemovals.add(id);
+        for (const id of this.pendingNoteRemovals.footnote)
+            target.pendingNoteRemovals.footnote.add(id);
+        for (const id of this.pendingNoteRemovals.endnote)
+            target.pendingNoteRemovals.endnote.add(id);
+        for (const [name, ids] of this.pendingRelationshipRemovals)
+            target.pendingRelationshipRemovals.set(name, new Set(ids));
+        this.glossaryEntries.copyTo(target.glossaryEntries);
         target.trackedChangeDate = this.trackedChangeDate;
         target.fonts.defaultTheme = this.fonts.defaultTheme;
         target.xpathEngine = this.xpathEngine;
@@ -514,15 +641,35 @@ export class WordprocessingMLPackage extends OpcPackage {
         var _a;
         if (this.trackingPending)
             await this.setChangeTrackingMode((_a = this.trackingMode) !== null && _a !== void 0 ? _a : 'Off');
-        if (this.pendingCommentRemovals.size > 0)
-            await flushPendingCommentRemovals(await this.getBody());
+        // what removed content took with it, until nothing more goes: a removed note takes the comments
+        // anchored in it, and a removed note or comment the relationships its content held, which the last
+        // step settles (CR-002 section 50; docx4j's Removals.flush repeats the same way)
+        const notes = this.pendingNoteRemovals;
+        for (let round = 0; round < 10 && this.pendingCommentRemovals.size + notes.footnote.size + notes.endnote.size > 0; round++) {
+            if (this.pendingCommentRemovals.size > 0)
+                await flushPendingCommentRemovals(await this.getBody());
+            if (notes.footnote.size + notes.endnote.size > 0)
+                await flushPendingNoteRemovals(this.getMainDocumentPart(), notes, this);
+        }
+        if (this.pendingRelationshipRemovals.size > 0)
+            flushPendingRelationshipRemovals(this, this.pendingRelationshipRemovals);
+        if (this.glossaryEntries.waiting) {
+            await this.glossaryEntries.flush(this, {
+                glossary: () => new GlossaryDocumentPart(),
+                styles: () => new StyleDefinitionsPart('/word/glossary/styles.xml'),
+            });
+        }
         if (this.requiredStyles.size > 0) {
             await this.styles.ensure([...this.requiredStyles]);
             this.requiredStyles.clear();
         }
         return super.saveTo(sink);
     }
-    /** The paragraph at an address anywhere in the document: 'body/3', 'header:rId5/0', a paraId, or a text match. */
+    /**
+     * The paragraph at an address anywhere in the document: 'body/3', 'header:rId5/0', 'footnote:2/0',
+     * 'endnote:1/0', 'comment:5/0', 'body/3/textbox:0/1' (a text box's paragraph, read-only: CR-012 D4 and
+     * D5), a paraId, or a text match. Undefined where the address names no paragraph.
+     */
     async paragraphAt(address) {
         for (const body of await this.bodies(address)) {
             const p = body.paragraphAt(address);
@@ -531,28 +678,44 @@ export class WordprocessingMLPackage extends OpcPackage {
         }
         return undefined;
     }
-    /** Every paragraph and table with its address, style and text (CR-002 section 3.3). Unmarshals the main part, headers and footers. */
-    async outline() {
+    /**
+     * Every paragraph and table with its address, style and text (CR-002 section 3.3), read by the text model
+     * under one context (CR-012 D3: `Body.outline`, whose options it takes): the main document, then each
+     * header and footer. Unmarshals the main part, headers and footers.
+     */
+    async outline(options, context) {
         var _a, _b, _c, _d;
         const main = await this.getBody();
-        const out = { ...main.outline(), headers: [], footers: [] };
+        const ctx = context !== null && context !== void 0 ? context : await Texts.contextOf(this);
+        const out = { ...await main.outline(options, ctx), headers: [], footers: [] };
         for (const part of this.getMainDocumentPart().headerParts) {
             const body = await part.getBody();
-            out.headers.push({ relId: (_b = (_a = part.sourceRelationship) === null || _a === void 0 ? void 0 : _a.id) !== null && _b !== void 0 ? _b : '', partName: part.partName.name, ...body.outline() });
+            out.headers.push({ relId: (_b = (_a = part.sourceRelationship) === null || _a === void 0 ? void 0 : _a.id) !== null && _b !== void 0 ? _b : '', partName: part.partName.name, ...await body.outline(options, ctx) });
         }
         for (const part of this.getMainDocumentPart().footerParts) {
             const body = await part.getBody();
-            out.footers.push({ relId: (_d = (_c = part.sourceRelationship) === null || _c === void 0 ? void 0 : _c.id) !== null && _d !== void 0 ? _d : '', partName: part.partName.name, ...body.outline() });
+            out.footers.push({ relId: (_d = (_c = part.sourceRelationship) === null || _c === void 0 ? void 0 : _c.id) !== null && _d !== void 0 ? _d : '', partName: part.partName.name, ...await body.outline(options, ctx) });
         }
         return out;
     }
     async bodies(address) {
+        var _a;
         const main = this.getMainDocumentPart();
         if (typeof address === 'string' && !address.startsWith('w14:')) {
             const prefix = address.split('/')[0];
             if (prefix === 'body')
                 return [await main.getBody()];
             const [kind, relId] = prefix.split(':');
+            if (kind === 'footnote' || kind === 'endnote' || kind === 'comment') {
+                // a note's or a comment's body, by its w:id, as the text model and Comment address them (CR-012 D4)
+                const part = kind === 'footnote' ? main.footnotesPart : kind === 'endnote' ? main.endnotesPart : main.commentsPart;
+                if (!part)
+                    return [];
+                const contents = await part.getContents();
+                const entry = ((_a = contents[kind]) !== null && _a !== void 0 ? _a : []).find((e) => String(e.id) === relId);
+                await this.getPropertyResolver().catch(() => undefined);
+                return entry ? [new Body(part, entry, `${kind}:${relId}`, this)] : [];
+            }
             const parts = kind === 'header' ? main.headerParts : kind === 'footer' ? main.footerParts : [];
             const part = parts.find((p) => { var _a; return ((_a = p.sourceRelationship) === null || _a === void 0 ? void 0 : _a.id) === relId || p.partName.fileName === relId; });
             return part instanceof HeaderPart || part instanceof FooterPart ? [await part.getBody()] : [];
@@ -628,6 +791,74 @@ export class WordprocessingMLPackage extends OpcPackage {
         return 'Word.Document';
     }
 }
+/**
+ * Headers and footers in docx4j's order (its CR-043 `Lister.headersAndFooters`): as the sections
+ * reference them, in document order, a part once, then any other in the order of the main part's
+ * relationships. The main part's tree is read privately, so a main part nobody has otherwise read keeps
+ * its bytes.
+ */
+async function inSectionOrder(main, parts) {
+    var _a;
+    const rels = main.relationshipsPart;
+    if (!rels)
+        return parts;
+    const order = [];
+    const add = (part) => {
+        const known = parts.find((p) => p === part);
+        if (known && !order.includes(known))
+            order.push(known);
+    };
+    const body = (await main.readContents()).body;
+    for (const sectPr of sectionsOf(body))
+        for (const ref of (_a = sectPr.egHdrFtrReferences) !== null && _a !== void 0 ? _a : [])
+            add(rels.getPart(ref.id));
+    for (const rel of rels.list)
+        add(rels.getPart(rel));
+    for (const part of parts)
+        if (!order.includes(part))
+            order.push(part);
+    return order;
+}
+/**
+ * The body's `w:sectPr`s in document order, the paragraphs' first and the body's own last, as docx4j's
+ * walk finds them: not inside a run (where a text box's paragraphs are), DOM the model does not type
+ * left alone.
+ */
+function sectionsOf(body) {
+    const out = [];
+    const visit = (o) => {
+        if (typeof o !== 'object' || o === null || typeof o.nodeType === 'number')
+            return;
+        if (Array.isArray(o)) {
+            for (const item of o)
+                visit(item);
+            return;
+        }
+        const typeName = o.TYPE_NAME;
+        if (typeName === 'org_docx4j_wml.SectPr') {
+            out.push(o);
+            return;
+        }
+        if (typeName === 'org_docx4j_wml.R')
+            return;
+        for (const key in o)
+            if (key !== 'PARENT')
+                visit(o[key]);
+    };
+    visit(body === null || body === void 0 ? void 0 : body.content);
+    if (body === null || body === void 0 ? void 0 : body.sectPr)
+        out.push(body.sectPr);
+    return out;
+}
+/** Revision markup, by local name in any prefix: what a story part holds when it has a tracked change to resolve. */
+const REVISION_MARKUP = /<(?:[\w.-]+:)?(?:ins|del|moveFrom|moveTo|rPrChange|pPrChange|sectPrChange|tblPrChange|trPrChange|tcPrChange|tblGridChange|tblPrExChange|cellIns|cellDel|cellMerge|numberingChange|customXmlInsRangeStart|customXmlDelRangeStart)[\s/>]/;
+/**
+ * True when a story part may hold a tracked change: always once it is unmarshalled, else when its
+ * source has revision markup, read without unmarshalling it, so a part with none keeps its bytes.
+ */
+async function holdsRevisions(part) {
+    return part.isUnmarshalled || REVISION_MARKUP.test(await part.getXml());
+}
 /**
  * `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.

package/dist/parts/DefaultXmlPart.mjs

@@ -2,7 +2,7 @@ import { Part } from './Part.mjs';
 import { ContentTypes } from '../opc/ContentTypes.mjs';
 import { Namespaces } from './Namespaces.mjs';
 import { Docx4JException } from '../opc/exceptions.mjs';
-import { parseXml, serializeXmlPart, encodeText, decodeXmlText } from '../xml/dom.mjs';
+import { parseXml, serializeXmlPart, encodeText, decodeXmlText, assertXmlCharacters } from '../xml/dom.mjs';
 /**
  * An XML part the object model does not type, held as a DOM (docx4j DefaultXmlPart / XmlPart).
  * The document is parsed on first `getDocument()`; a part whose document was never requested is
@@ -71,7 +71,7 @@ export class DefaultXmlPart extends Part {
     }
     async getBytes() {
         if (this.document !== undefined)
-            return encodeText(serializeXmlPart(this.document));
+            return encodeText(assertXmlCharacters(serializeXmlPart(this.document), `Part ${this.partName}`));
         if (this.bytes !== undefined)
             return this.bytes;
         const loaded = await this.loadSourceBytes();

package/dist/parts/Part.d.mts

@@ -1,7 +1,12 @@
 import type { Relationship } from '@docx4j/generated-objects-ts/modules/org_docx4j_relationships';
+import type { Normalisation } from '@docx4j/generated-objects-ts';
 import { PartName } from '../opc/PartName.mjs';
 import type { RelationshipsPart, AddPartBehaviour } from './RelationshipsPart.mjs';
 import type { OpcPackage } from '../packages/OpcPackage.mjs';
+/** What a save asks of a part's bytes (CR-015 D8): to be told of each value the objects facade's normaliser rewrote. */
+export interface PartBytesOptions {
+    onNormalised?(normalisation: Normalisation): void;
+}
 /** Something that owns a relationships part: a part or the package (docx4j Base). */
 export interface RelationshipSource {
     readonly partName: PartName;
@@ -49,8 +54,11 @@ export declare abstract class Part implements RelationshipSource {
     setPartShortcut(_part: Part, _relationshipType: string): boolean;
     /** The bytes this part was loaded from, if it came from a container. Undefined for new parts. */
     protected loadSourceBytes(): Promise<Uint8Array | undefined>;
-    /** The bytes to write on save. Untouched parts come back from the source container unchanged. */
-    abstract getBytes(): Promise<Uint8Array>;
+    /**
+     * The bytes to write on save. Untouched parts come back from the source container unchanged. A part
+     * marshalled through the objects facade tells `options.onNormalised` of each value written in its normal form.
+     */
+    abstract getBytes(options?: PartBytesOptions): Promise<Uint8Array>;
     /** Whether the part carries content of its own (set or unmarshalled) rather than relying on the source container. */
     abstract get isLoaded(): boolean;
 }

package/dist/parts/XmlPart.d.mts

@@ -1,7 +1,8 @@
 import { type Jsonix } from '@docx4j/generated-objects-ts';
-import { Part } from './Part.mjs';
+import { Part, type PartBytesOptions } from './Part.mjs';
 import { PartName } from '../opc/PartName.mjs';
 import { type Bound } from '../model/content/binder.mjs';
+import type { PartWarning } from '../opc/mce/preprocessor.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. */
@@ -17,8 +18,11 @@ export interface RootName {
     namespaceURI: string;
     localPart: string;
 }
-/** A hook run over the DOM before unmarshalling (the MCE preprocessor); set by the package on load. */
-export type DomPreprocessor = (doc: Document, part?: XmlPart<unknown>) => void;
+/**
+ * A hook run over the DOM before unmarshalling (the MCE preprocessor); set by the package on load.
+ * What it returns becomes the part's `warnings`.
+ */
+export type DomPreprocessor = (doc: Document, part?: XmlPart<unknown>) => void | readonly PartWarning[];
 /**
  * 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
@@ -32,12 +36,7 @@ export declare class XmlPart<T = unknown> extends Part {
     rootName: RootName | undefined;
     /** Runs over the DOM before unmarshalling; the package sets its MCE preprocessor here. */
     preprocessor: DomPreprocessor | undefined;
-    /**
-     * The namespace declarations the source root element carried, prefix to URI, recorded when the
-     * part was parsed. They are what `mc:Ignorable` prefixes the object model does not bind are
-     * re-declared from on marshal; see `declareIgnorablePrefixes`.
-     */
-    private sourceDeclarations;
+    private parseWarnings;
     constructor(partName: PartName | string, contentType: string, relationshipType: string, rootName?: RootName);
     /** True once contents were unmarshalled or set; the part is then re-marshalled on save. */
     get isUnmarshalled(): boolean;
@@ -48,6 +47,13 @@ export declare class XmlPart<T = unknown> extends Part {
      * which is what lets a reader remember it (CR-002 section 31).
      */
     get isUntouched(): boolean;
+    /**
+     * What the last parse of this part reported: an mc:AlternateContent whose branches' text differs
+     * (`mce.branches_differ`, CR-010 phase 1), and each attribute value its type refuses that was read as
+     * Word 365 reads it (`value.kept.exact`, `value.kept.invalid`: CR-015 D8). Empty until the part is
+     * parsed, by `getContents()` or a private read, and again once its contents are set.
+     */
+    get warnings(): readonly PartWarning[];
     /** The unmarshalled contents (docx4j getJaxbElement()); throws when not yet unmarshalled. */
     get contents(): T;
     /** The root element as [name, value]; undefined until unmarshalled. */
@@ -64,6 +70,7 @@ export declare class XmlPart<T = unknown> extends Part {
      * reads the styles and numbering parts of a document nobody has otherwise touched.
      */
     readContents(): Promise<T>;
+    private preprocess;
     /** Replaces the contents (docx4j setJaxbElement / setContents). The root name defaults to the part's. */
     setContents(value: T, rootName?: RootName): void;
     /** Replaces the contents with raw XML bytes; they are unmarshalled on the next getContents(). */
@@ -73,7 +80,7 @@ export declare class XmlPart<T = unknown> extends Part {
     /** The XML as it would be saved (docx4j XmlUtils.marshaltoString on the part). */
     getXml(): Promise<string>;
     /** Marshalled bytes when unmarshalled or set, else the source bytes untouched. */
-    getBytes(): Promise<Uint8Array>;
+    getBytes(options?: PartBytesOptions): 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`).
@@ -92,32 +99,28 @@ export declare class XmlPart<T = unknown> extends Part {
      * (CR-002 section 31).
      */
     selectObjects(xpath: string, options?: SelectOptions): Promise<Bound[]>;
-    /** The root element as a DOM element (docx4j XmlUtils.marshaltoW3CDomDocument). */
-    marshalToNode(): Promise<Element>;
+    /**
+     * The root element as a DOM element (docx4j XmlUtils.marshaltoW3CDomDocument). Run properties are written in
+     * their normal form unless the package's `normaliseOnSave` (else the objects package's `setNormaliseOnSave`) is
+     * false (CR-015 D2, the objects facade's CR-013 phase C): the tree keeps what it read.
+     */
+    marshalToNode(options?: PartBytesOptions): Promise<Element>;
+    /**
+     * Parses the part's bytes, and names the part when the XML is not well-formed. xmldom's error
+     * (Node) carries the line and column of the fault; a browser's says them in its text, which
+     * `parseXml` passes on.
+     */
+    private parse;
     /**
      * 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).
+     * part's XML needs (CR-002 section 27), nor the value it refused. The message names the part, and
+     * for an attribute gives the value as written and the column too:
+     * `/word/styles.xml: w:sz/@w:val="big" (line 12, column 9): Argument [NaN] must be an integer, ...`.
+     * 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;
-    /**
-     * Every prefix the marshalled root's `mc:Ignorable` names must be declared on that root
-     * (ECMA-376 Part 3 10.1.2; Word and Excel treat an undeclared one as a corrupt part and offer
-     * to repair the file). The object model binds only the namespaces it has modules for, so an
-     * `mc:Ignorable` prefix whose content was dropped on unmarshal - `xr6`, `xr10` and `xr2` on
-     * Excel's `xl/workbook.xml`, for instance - loses its declaration: the runtime declares one
-     * prefix per entry of the objects package's table and the facade can only *remove* unused
-     * declarations, never add one it never made (CR-001 section 17).
-     *
-     * So the part re-declares them itself: from what the source root declared, else from the
-     * objects package's `NAMESPACE_PREFIXES`. A prefix neither knows is dropped from
-     * `mc:Ignorable` - an undeclared prefix is the one thing that must not be written - and warned
-     * about once.
-     */
-    private declareIgnorablePrefixes;
 }