@docx4j/core-ts 0.6.0 → 0.7.0

package/dist/packages/OpcPackage.mjs

@@ -9,8 +9,9 @@ import { Docx4JException } from '../opc/exceptions.mjs';
 import { Namespaces } from '../parts/Namespaces.mjs';
 import { Parts } from '../parts/Parts.mjs';
 import { XmlPart } from '../parts/XmlPart.mjs';
-import { RelationshipsPart } from '../parts/RelationshipsPart.mjs';
+import { RelationshipsPart, isExternal } from '../parts/RelationshipsPart.mjs';
 import { DocPropsCorePart, DocPropsExtendedPart } from '../parts/docProps/index.mjs';
+import { assertTimeZone, runtimeTimeZone } from '../model/dateZone.mjs';
 import { mceKeep, mcePreprocess } from '../opc/mce/preprocessor.mjs';
 import { createPackageForContentType, registerGenericPackageClass } from './registry.mjs';
 /**
@@ -18,6 +19,27 @@ import { createPackageForContentType, registerGenericPackageClass } from './regi
  * the content types, the package relationships and the parts reachable from them.
  */
 export class OpcPackage {
+    /**
+     * The client's time zone for this package, an IANA id (`Australia/Sydney`), or undefined for the runtime's (CR-018; the
+     * portfolio's date rule of 2026-10-28, docx4j's `OpcPackage.setDateTimeZone`). Every instant the package holds is shown
+     * in it, and a `w:date` without `dateUtc` read in it: a new revision's or comment's stamp (Word's local wall-clock
+     * `w:date`), `TrackedChange.date` and `Comment.creationDate`, and date fields when they are evaluated (CR-012 phase 5).
+     * It is the client's for this package, not the document's, and reaches no saved file as such: a server reusing a
+     * loaded package sets it per request. Under Office JS the runtime's zone is already the client's. A bound date has no
+     * zone (CR-002 section 56) unless `boundDatesConvertedAsWord` asks for Word's conversion in this one. A zone the
+     * runtime does not know is refused with a `RangeError` at the set.
+     */
+    get dateTimeZone() {
+        return this.dateTimeZone_;
+    }
+    set dateTimeZone(id) {
+        this.dateTimeZone_ = id === undefined ? undefined : assertTimeZone(id);
+    }
+    /** The zone in force: `dateTimeZone`, else the runtime's. */
+    effectiveDateTimeZone() {
+        var _a;
+        return (_a = this.dateTimeZone_) !== null && _a !== void 0 ? _a : runtimeTimeZone();
+    }
     constructor() {
         /** The pseudo part name of the package itself: the source of the package relationships. */
         this.partName = PartName.ROOT;
@@ -26,7 +48,46 @@ export class OpcPackage {
         /** Custom XML parts by the (lower-cased) itemID of their properties part. */
         this.customXmlDataStorageParts = new Map();
         /** The options this package was loaded with. */
+        /**
+         * The names the container held more than one entry of, each read from its first entry under
+         * `LoadOptions.repair: 'word'` (WD REQ-206, CR-024); empty for a package loaded without one, or made here.
+         */
+        this.duplicateEntries = [];
         this.loadOptions = {};
+        /**
+         * Whether a save refuses a part holding a child its container never admits (CR-016 D2, docx4j CR-064's rules in the
+         * objects facade, its CR-017): a run straight in the body, a table in a paragraph, a cell beside a table's rows, a
+         * string in a run, a name and value that disagree. On by default: the save throws `MisplacedContentException` with
+         * every such child in the part, its path and docx4j's message naming the fix, and writes nothing, since Word 365
+         * refuses such a file or repairs it by dropping content (check 72). Off, the part is written as held and each is on
+         * `lastSave.misplaced`. Only a part being marshalled is checked (one unmarshalled, or given contents); a part copied
+         * from the source is never refused, so a document read and saved untouched never is. `checkContent()` is the same
+         * check on request. A misplaced child read from a file is a `target.misplaced` warning on its part (D7).
+         */
+        this.checkContentOnSave = true;
+        /**
+         * Whether a save refuses to lose what a read dropped (CR-025 sections 2.3 and 2.4, D8): a part holding `part.skipped` content
+         * that was changed throws `SaveLossException` and nothing is written. Off, the part is written without those items, each on
+         * `lastSave.lost`. A part read and not changed is copied either way, so nothing is lost there. Word's own save drops such
+         * content with no message (check 76), so off is Word's behaviour.
+         */
+        this.checkLossOnSave = true;
+        /**
+         * Show bound dates as Word displays them in the package's zone (CR-018, the date rule's point 3; docx4j's
+         * `setBoundDatesConvertedAsWord`): off by default, a bound date being the day its fields say wherever it is read
+         * (CR-002 section 56). On, a bound value carrying a `Z` or an offset is read as an instant and shown in
+         * `effectiveDateTimeZone()`, as Word reads the `Z` as UTC and shows the machine's local time (a day early west of
+         * UTC); a value with no marker, or a date alone, stays nominal. Setting `dateTimeZone` does not turn this on.
+         */
+        this.boundDatesConvertedAsWord = false;
+        /**
+         * Write the save's time into the core properties (CR-018, the date rule's point 6; docx4j's `docx4j.dcterms.write`):
+         * off by default, a save leaving `dcterms:created` and `dcterms:modified` as they are. On, each save sets
+         * `dcterms:modified` to now, UTC to the second (`2026-10-28T03:04:05Z`, the W3CDTF form Office writes), and
+         * `dcterms:created` too for a package created here that has none; a loaded package with no core properties part is
+         * left without one, as docx4j leaves it.
+         */
+        this.writeTimesOnSave = false;
         this.relationshipsPart = RelationshipsPart.createPackageRels();
         this.relationshipsPart.sourceP = this;
         this.relationshipsPart.package = this;
@@ -73,22 +134,71 @@ export class OpcPackage {
             default: return false;
         }
     }
-    /** The main part: the target of the officeDocument relationship. */
+    /** The main part: the target of the officeDocument relationship, an External one naming none. */
     getMainPart() {
-        var _a;
-        const rel = (_a = this.relationshipsPart.getRelationshipByType(Namespaces.DOCUMENT)) !== null && _a !== void 0 ? _a : this.relationshipsPart.getRelationshipByType(Namespaces.DOCUMENT_STRICT);
-        return rel ? this.relationshipsPart.getPart(rel) : undefined;
+        const rels = this.relationshipsPart;
+        const rel = [...rels.getRelationshipsByType(Namespaces.DOCUMENT), ...rels.getRelationshipsByType(Namespaces.DOCUMENT_STRICT)].find((r) => !isExternal(r));
+        return rel ? rels.getPart(rel) : undefined;
     }
     /**
-     * The warnings of every part parsed so far (each XML part's `warnings`, CR-010 phase 1). A part
+     * The warnings of every part parsed so far (each XML part's `warnings`, CR-010 phase 1), after the
+     * load's own: a name the container holds twice, and more than one officeDocument relationship, read under
+     * `repair: 'word'` (CR-024), and an `External` main relationship dropped under `repair: 'all'` (CR-031). A part
      * is parsed when something reads it, so a reader that wants a whole package's warnings reads its
      * parts first; `unmarshalAll()` does, at the cost of re-marshalling every part on save.
      */
     get warnings() {
-        const out = [];
+        const out = [...this.duplicateEntries];
+        if (this.multipleMainParts)
+            out.push(this.multipleMainParts);
+        if (this.externalMainPart)
+            out.push(this.externalMainPart);
         for (const part of this.parts)
             if (part instanceof XmlPart)
                 out.push(...part.warnings);
+        // a relationships part's own, what its read dropped: a child of another local name, an attribute the model doesn't map
+        // (CR-025 section 8, D12); after the parts', and outside the save's gate, since none names a part
+        for (const rels of [this.relationshipsPart, ...[...this.parts].map((p) => p.relationshipsPart)])
+            if (rels)
+                out.push(...rels.warnings);
+        return out;
+    }
+    /**
+     * Each relationships part a load under `repair: 'word'` read by local name, being in a wrong namespace (CR-031 section
+     * 2.3): the package's and its parts', in that order.
+     */
+    get relationshipsNamespaces() {
+        var _a;
+        const out = [];
+        for (const rels of [this.relationshipsPart, ...[...this.parts].map((p) => p.relationshipsPart)]) {
+            for (const w of (_a = rels === null || rels === void 0 ? void 0 : rels.warnings) !== null && _a !== void 0 ? _a : [])
+                if (w.code === 'package.relationships_namespace')
+                    out.push(w);
+        }
+        return out;
+    }
+    /**
+     * What the load repaired (WD REQ-207's `repaired`, CR-031 section 2.4), read from what it recorded, so it reports what the
+     * load did whatever the option: `'own'` for a repair of this package's own (an `External` main relationship dropped),
+     * `'word'` where only Word's were followed (a duplicated entry, several main relationships, a relationships part read by
+     * local name), else `'none'`.
+     */
+    get repaired() {
+        if (this.externalMainPart)
+            return 'own';
+        return this.duplicateEntries.length > 0 || this.multipleMainParts || this.relationshipsNamespaces.length > 0 ? 'word' : 'none';
+    }
+    /**
+     * Every child a part holds that its container never admits (CR-016 D6, the check on request): what a save would
+     * refuse for, over every typed XML part, each finding with its part, its path, the rule and docx4j's message naming
+     * the fix. Nothing is changed, and an untouched part stays untouched (read privately). `[]` for a package whose
+     * content is all in its place.
+     */
+    async checkContent() {
+        const out = [];
+        for (const part of this.parts)
+            if (part instanceof XmlPart)
+                out.push(...(await part.checkContent()));
         return out;
     }
     /** Unmarshals every XML part, so that `contents` is available synchronously everywhere. */
@@ -136,6 +246,11 @@ export class OpcPackage {
             throw new Docx4JException(`Cloning ${this.constructor.name} produced ${copy.constructor.name}`);
         }
         copy.normaliseOnSave = this.normaliseOnSave;
+        copy.checkContentOnSave = this.checkContentOnSave;
+        copy.checkLossOnSave = this.checkLossOnSave;
+        copy.dateTimeZone = this.dateTimeZone;
+        copy.boundDatesConvertedAsWord = this.boundDatesConvertedAsWord;
+        copy.writeTimesOnSave = this.writeTimesOnSave;
         this.copyPackageSettingsTo(copy);
         return copy;
     }

package/dist/packages/WordprocessingMLPackage.mjs

@@ -171,7 +171,8 @@ export class WordprocessingMLPackage extends OpcPackage {
         if (landscape)
             pgSz.orient = 'landscape';
         const pgMar = { top: 1440, right: 1440, bottom: 1440, left: 1440, header: 708, footer: 708, gutter: 0 };
-        const document = { body: { content: [], sectPr: { pgSz, pgMar } } };
+        // typed, as a loaded document is, so the objects facade's walks (its onMisplaced, CR-016) see the body as a container
+        const document = { TYPE_NAME: 'org_docx4j_wml.Document', body: { TYPE_NAME: 'org_docx4j_wml.Body', content: [], sectPr: { TYPE_NAME: 'org_docx4j_wml.SectPr', pgSz, pgMar } } };
         const main = new MainDocumentPart();
         main.setContents(document);
         pkg.addTargetPart(main);
@@ -785,6 +786,7 @@ export class WordprocessingMLPackage extends OpcPackage {
             },
             customXmlRelationshipSource: () => this.getMainDocumentPart(),
             xhtmlHost: this,
+            getPropertyResolver: () => this.getPropertyResolver(),
         })));
     }
     get progId() {

package/dist/packages/index.d.mts

@@ -1,4 +1,4 @@
-export { OpcPackage, type PackageSource } from './OpcPackage.mjs';
+export { OpcPackage, type PackageSource, type PackageWarning, type Repaired } from './OpcPackage.mjs';
 export { WordprocessingMLPackage, type PageSizePaper, type CreatePackageOptions } from './WordprocessingMLPackage.mjs';
 export { PresentationMLPackage, createSlideSize, type SlideSizesWellKnown, type CreatePresentationOptions, } from './PresentationMLPackage.mjs';
 export { SpreadsheetMLPackage } from './SpreadsheetMLPackage.mjs';

package/dist/parts/Part.d.mts

@@ -1,11 +1,15 @@
 import type { Relationship } from '@docx4j/generated-objects-ts/modules/org_docx4j_relationships';
-import type { Normalisation } from '@docx4j/generated-objects-ts';
+import type { Normalisation, OutOfRange, MisplacedChild } 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;
+    /** Called for each integer attribute value written that Word 365 reads differently (CR-017 P3); the value is written as held. */
+    onOutOfRange?(report: OutOfRange): void;
+    /** Called for each child its container never admits, as the container is written (CR-016 D2); written as held unless the callback throws. */
+    onMisplaced?(report: MisplacedChild): void;
 }
 /** Something that owns a relationships part: a part or the package (docx4j Base). */
 export interface RelationshipSource {

package/dist/parts/RelationshipsPart.d.mts

@@ -2,6 +2,7 @@ import type { Relationships, Relationship } from '@docx4j/generated-objects-ts/m
 import { XmlPart } from './XmlPart.mjs';
 import { Part, type RelationshipSource } from './Part.mjs';
 import { PartName } from '../opc/PartName.mjs';
+import type { PartWarning } from '../opc/mce/preprocessor.mjs';
 /** What `addPart` does when a part of the same name is already in the package (docx4j AddPartBehaviour). */
 export type AddPartBehaviour = 'OVERWRITE_IF_NAME_EXISTS' | 'REUSE_EXISTING' | 'RENAME_IF_NAME_EXISTS';
 export declare const RELATIONSHIPS_ROOT: {
@@ -22,6 +23,20 @@ export declare class RelationshipsPart extends XmlPart<Relationships> {
     static createPackageRels(): RelationshipsPart;
     /** A part's own, empty, relationships part. */
     static createRelationshipsPartForPart(source: RelationshipSource): RelationshipsPart;
+    /**
+     * Set by the load under `LoadOptions.repair` `'word'` or `'all'` (CR-031 section 2.3): a part in a wrong namespace is read
+     * as Word's repair reads it, not refused.
+     */
+    readsByLocalName: boolean;
+    /**
+     * Refuses a part in another namespace, or in none, on its root or on any `Relationship` (CR-025 section 8, D10), before the
+     * runtime drops what it can't bind. Under `readsByLocalName` (`repair: 'word'`, CR-031 section 2.3) the root and every
+     * `Relationship` are read by their local names instead, as Word's repair reads them, so the runtime binds them all and a
+     * save writes the right namespace, with one `package.relationships_namespace` warning. A root or a child with another
+     * local name is left to the runtime, as before: Word is unmeasured on both, and a child is then a `part.skipped` on this
+     * part, which `pkg.warnings` gathers (D12).
+     */
+    protected readRoot(doc: Document): readonly PartWarning[];
     /** The name of the part these relationships belong to; '/' for the package. */
     get sourceName(): PartName;
     get isPackageRelationshipPart(): boolean;

package/dist/parts/RelationshipsPart.mjs

@@ -3,7 +3,7 @@ import { setRelationshipsPartFactory } from './Part.mjs';
 import { PartName } from '../opc/PartName.mjs';
 import { ContentTypes } from '../opc/ContentTypes.mjs';
 import { Namespaces } from './Namespaces.mjs';
-import { InvalidFormatException } from '../opc/exceptions.mjs';
+import { InvalidFormatException, RelationshipsNamespaceException } from '../opc/exceptions.mjs';
 export const RELATIONSHIPS_ROOT = { namespaceURI: Namespaces.RELATIONSHIPS, localPart: 'Relationships' };
 const RELATIONSHIP_TYPE_NAME = 'org_docx4j_relationships.Relationship';
 /**
@@ -15,6 +15,11 @@ export class RelationshipsPart extends XmlPart {
     constructor(source, partName) {
         super(partName !== null && partName !== void 0 ? partName : (source ? PartName.relsFor(source.partName) : '/_rels/.rels'), ContentTypes.RELATIONSHIPS_PART, '', RELATIONSHIPS_ROOT);
         this.nextId = 1;
+        /**
+         * Set by the load under `LoadOptions.repair` `'word'` or `'all'` (CR-031 section 2.3): a part in a wrong namespace is read
+         * as Word's repair reads it, not refused.
+         */
+        this.readsByLocalName = false;
         this.sourceP = source;
         if (source)
             this.package = source.package;
@@ -31,6 +36,48 @@ export class RelationshipsPart extends XmlPart {
         rp.setContents({ relationship: [] });
         return rp;
     }
+    /**
+     * Refuses a part in another namespace, or in none, on its root or on any `Relationship` (CR-025 section 8, D10), before the
+     * runtime drops what it can't bind. Under `readsByLocalName` (`repair: 'word'`, CR-031 section 2.3) the root and every
+     * `Relationship` are read by their local names instead, as Word's repair reads them, so the runtime binds them all and a
+     * save writes the right namespace, with one `package.relationships_namespace` warning. A root or a child with another
+     * local name is left to the runtime, as before: Word is unmeasured on both, and a child is then a `part.skipped` on this
+     * part, which `pkg.warnings` gathers (D12).
+     */
+    readRoot(doc) {
+        var _a, _b;
+        const root = doc.documentElement;
+        if (!root || root.localName !== 'Relationships')
+            return [];
+        const isRelationship = (c) => c.nodeType === 1 && c.localName === 'Relationship';
+        let wrong = root.namespaceURI !== Namespaces.RELATIONSHIPS ? (_a = root.namespaceURI) !== null && _a !== void 0 ? _a : null : undefined;
+        for (let c = root.firstChild; c && wrong === undefined; c = c.nextSibling) {
+            if (isRelationship(c) && c.namespaceURI !== Namespaces.RELATIONSHIPS)
+                wrong = (_b = c.namespaceURI) !== null && _b !== void 0 ? _b : null;
+        }
+        if (wrong === undefined)
+            return [];
+        if (!this.readsByLocalName)
+            throw new RelationshipsNamespaceException(this.partName.name, wrong);
+        const fixed = inRelationshipsNamespace(doc, root);
+        let count = 0;
+        while (root.firstChild) {
+            const c = root.firstChild;
+            root.removeChild(c);
+            if (isRelationship(c))
+                count++;
+            fixed.appendChild(isRelationship(c) && c.namespaceURI !== Namespaces.RELATIONSHIPS ? inRelationshipsNamespace(doc, c) : c);
+        }
+        doc.replaceChild(fixed, root);
+        return [{
+                code: 'package.relationships_namespace',
+                partName: this.partName.name,
+                namespace: wrong,
+                count,
+                message: `${this.partName.name}: a relationships part in ${wrong === null ? 'no namespace' : `another namespace, ${wrong}`}, `
+                    + `read as Word's repair reads it, its ${count} relationship${count === 1 ? '' : 's'} by local name (REQ-207)`,
+            }];
+    }
     /** The name of the part these relationships belong to; '/' for the package. */
     get sourceName() {
         var _a, _b;
@@ -218,6 +265,24 @@ export class RelationshipsPart extends XmlPart {
         }
     }
 }
+/**
+ * `el` again, in the relationships namespace under its local name, with its attributes but not its namespace declarations,
+ * and with what it holds moved across (CR-031 section 2.3).
+ */
+function inRelationshipsNamespace(doc, el) {
+    var _a;
+    const out = doc.createElementNS(Namespaces.RELATIONSHIPS, (_a = el.localName) !== null && _a !== void 0 ? _a : el.nodeName);
+    for (let i = 0; i < el.attributes.length; i++) {
+        const a = el.attributes.item(i);
+        if (a.name === 'xmlns' || a.name.startsWith('xmlns:'))
+            continue;
+        out.setAttributeNS(a.namespaceURI, a.name, a.value);
+    }
+    if (el.localName === 'Relationship')
+        while (el.firstChild)
+            out.appendChild(el.firstChild);
+    return out;
+}
 export function isExternal(rel) {
     return rel.targetMode === 'External';
 }

package/dist/parts/XmlPart.d.mts

@@ -1,8 +1,15 @@
-import { type Jsonix } from '@docx4j/generated-objects-ts';
+import { type Jsonix, type OutOfRange, type MisplacedChild } from '@docx4j/generated-objects-ts';
 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';
+import type { PartWarning, ValueOutOfRangeWarning, MisplacedContentWarning } from '../opc/mce/preprocessor.mjs';
+import { type ContentSkippedWarning } from '../opc/skipped.mjs';
+/**
+ * An integer attribute value Word 365 reads differently, as the objects facade reports it on read or on save, as a
+ * warning (CR-017 P2 and P3). The value stays as written; the message says what Word would read, the storage and the
+ * range Word keeps as written, from the table entry the report names (`storage`, `property` and `rule`, objects 0.7.0).
+ */
+export declare function valueOutOfRange(report: OutOfRange, partName: string | undefined): ValueOutOfRangeWarning;
 /** 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. */
@@ -13,6 +20,13 @@ export interface SelectOptions {
     /** Prefixes added to (or overriding) the objects package's own table. */
     namespaces?: Record<string, string> | undefined;
 }
+/**
+ * A child its container never admits, as the objects facade reports it on read or on save (its CR-017's
+ * `onMisplaced`), as a warning (CR-016 D7, D2): docx4j-python's code and fields (`target.misplaced`; `holder` and `item`
+ * docx4j's class names), docx4j's message after the part and the place (the path on save; the container, the child's
+ * place in its list and the line on read).
+ */
+export declare function misplacedContent(report: MisplacedChild, partName: string | undefined): MisplacedContentWarning;
 /** A qualified name for a part's root element. */
 export interface RootName {
     namespaceURI: string;
@@ -37,6 +51,8 @@ export declare class XmlPart<T = unknown> extends Part {
     /** Runs over the DOM before unmarshalling; the package sets its MCE preprocessor here. */
     preprocessor: DomPreprocessor | undefined;
     private parseWarnings;
+    /** The bytes given to `setBytes` that the tree was read from; undefined where it came from the source container. */
+    private parsedBytes;
     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;
@@ -49,9 +65,13 @@ export declare class XmlPart<T = unknown> extends Part {
     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.
+     * (`mce.branches_differ`, CR-010 phase 1), each attribute value its type refuses that was read as
+     * Word 365 reads it (`value.kept.exact`, `value.kept.invalid`, `value.truncated`, `value.refused`: CR-015 D8,
+     * CR-017 P1), each integer attribute value past what Word stores, kept as written (`value.out_of_range`,
+     * CR-017 P2), and each child its container never admits, kept as read but a string the runtime drops
+     * (`target.misplaced`, CR-016 D7), and a w:br outside a w:r read as Word reads it (`br.outside_run`, CR-021).
+     * 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. */
@@ -70,11 +90,40 @@ export declare class XmlPart<T = unknown> extends Part {
      * reads the styles and numbering parts of a document nobody has otherwise touched.
      */
     readContents(): Promise<T>;
+    /** `readContents`'s typed element: the live one, else a private tree from the part's bytes. */
+    private readElement;
+    /**
+     * Every child the part holds that its container never admits (CR-016 D6, the check on request): what a save would
+     * refuse the part for, each with its path, the rule and docx4j's message naming the fix, found by the objects
+     * facade's walk over the tree (a marshal to nothing); the part is not changed, and one never unmarshalled stays
+     * untouched, read privately. `[]` for a part whose content is all in its place.
+     */
+    checkContent(): Promise<MisplacedContentWarning[]>;
+    /**
+     * The DOM before unmarshalling: a w:br outside a w:r put in a run, as Word reads it (CR-021: a reading of the file,
+     * not an option, so ahead of the package's hook, which sees the repaired DOM), then the hook.
+     */
     private preprocess;
+    /**
+     * Reads the part's root before anything else meets the DOM; nothing by default. A main document part reads a root other than
+     * `w:document` here (WD REQ-318 to REQ-320, CR-028), throwing for one Word refuses.
+     */
+    protected readRoot(_doc: Document): readonly PartWarning[];
+    private preprocessed;
     /** 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(). */
     setBytes(bytes: Uint8Array): void;
+    /** What the read of the tree held now dropped (CR-025): nothing for a part not unmarshalled, or given contents. */
+    get skippedByRead(): readonly ContentSkippedWarning[];
+    /** The bytes the tree held now was read from. */
+    bytesRead(): Promise<Uint8Array | undefined>;
+    /**
+     * Whether the tree is still what its source reads as (CR-025 section 2.2): the source read again and the two marshalled
+     * alike. The save has no change log to ask, so this is for a part that holds skipped content, and only that: such a part,
+     * read and not changed, is copied, where a marshal would lose what the read dropped. What can't be compared counts as changed.
+     */
+    isUnchangedSinceRead(): Promise<boolean>;
     /** Replaces the contents with XML text (docx4j setContents from a string). */
     setXml(xml: string): void;
     /** The XML as it would be saved (docx4j XmlUtils.marshaltoString on the part). */