@docx4j/core-ts 0.5.0 → 0.7.0

package/dist/opc/Save.mjs

@@ -1,9 +1,40 @@
 import { CONTENT_TYPES_NAME } from './PartName.mjs';
 import { ContentTypes } from './ContentTypes.mjs';
-import { Docx4JException } from './exceptions.mjs';
+import { Docx4JException, MisplacedContentException, SaveLossException } from './exceptions.mjs';
 import { Namespaces } from '../parts/Namespaces.mjs';
 import { isExternal } from '../parts/RelationshipsPart.mjs';
+import { XmlPart, valueOutOfRange, misplacedContent } from '../parts/XmlPart.mjs';
 import { encodeText } from '../xml/dom.mjs';
+function valueNormalised(partName, n) {
+    const after = n.after === null ? 'left out' : `written ${JSON.stringify(n.after)}`;
+    return {
+        code: 'value.normalised', partName, path: n.path, before: n.before, after: n.after,
+        message: `${partName}: ${n.path} ${n.before === undefined ? '(no value)' : JSON.stringify(n.before)} ${after}, as Word reads it`,
+    };
+}
+/**
+ * `pkg.writeTimesOnSave` (CR-018; docx4j `DocPropsCorePart.writeTimes` under `docx4j.dcterms.write`): `dcterms:modified`
+ * now, UTC to the second in the W3CDTF form Office writes, and `dcterms:created` too for a package created here (one with
+ * no source container) that has none, its core properties part made for it. A loaded package without the part is left
+ * without one, as docx4j leaves it. The part is unmarshalled for the write, so it is marshalled by this save.
+ */
+async function writeTimes(pkg) {
+    const isNew = pkg.sourcePartStore === undefined;
+    let part = pkg.docPropsCorePart;
+    if (!part) {
+        if (!isNew)
+            return;
+        part = pkg.addDocPropsCorePart();
+    }
+    await part.getContents();
+    const props = part.contents;
+    const now = () => ({
+        TYPE_NAME: 'org_docx4j_docProps_core_dc_terms.W3CDTF', content: [new Date().toISOString().replace(/\.\d{3}Z$/, 'Z')],
+    });
+    if (props.created === undefined && isNew)
+        props.created = now();
+    props.modified = now();
+}
 /**
  * Writes a package to a sink (docx4j io3.Save): `[Content_Types].xml` first, then the package
  * relationships, then every part reachable through relationships, each once. Relationship parts
@@ -11,16 +42,68 @@ import { encodeText } from '../xml/dom.mjs';
  * container unchanged.
  */
 export async function savePackage(pkg, sink) {
+    if (pkg.writeTimesOnSave)
+        await writeTimes(pkg);
     const saver = new Saver(pkg, sink);
+    await saver.settleLosses(); // before anything is written, whatever the sink
     sink.put(CONTENT_TYPES_NAME, encodeText(pkg.contentTypeManager.toXml()), { contentType: ContentTypes.CONTENT_TYPES_PART });
     await saver.saveRels(pkg.relationshipsPart);
-    return sink.finish();
+    const result = await sink.finish();
+    pkg.lastSave = { normalised: saver.normalised, outOfRange: saver.outOfRange, misplaced: saver.misplaced, dropped: saver.dropped, lost: saver.lost };
+    return result;
 }
 class Saver {
     constructor(pkg, sink) {
         this.pkg = pkg;
         this.sink = sink;
         this.handled = new Set();
+        this.normalised = [];
+        this.outOfRange = [];
+        this.misplaced = [];
+        this.dropped = [];
+        this.lost = [];
+        /** Parts holding skipped content, read and not changed: written from their source (CR-025 section 2.2). */
+        this.copied = new Set();
+    }
+    /**
+     * CR-025 sections 2.2, 2.3 and 10, over the parts this save reaches: one holding what its read dropped is copied if it hasn't
+     * changed. If it has, what Word's own save drops too is written without and listed (`dropped`), and for the rest the save is
+     * refused for all such parts at once, or, with `checkLossOnSave` off, says what went (`lost`).
+     */
+    async settleLosses() {
+        const losses = [];
+        const seen = new Set();
+        const visit = async (rp) => {
+            for (const r of rp.list) {
+                if (r.type === Namespaces.HYPERLINK || isExternal(r))
+                    continue;
+                const part = this.pkg.getPart(rp.resolveTarget(r));
+                if (!part || seen.has(part.partName.key))
+                    continue;
+                seen.add(part.partName.key);
+                if (part instanceof XmlPart) {
+                    const skipped = part.skippedByRead;
+                    if (skipped.length > 0) {
+                        if (await part.isUnchangedSinceRead())
+                            this.copied.add(part.partName.key);
+                        else {
+                            this.dropped.push(...skipped.filter((w) => w.onSave === 'dropped'));
+                            const lost = skipped.filter((w) => w.onSave === 'lost');
+                            if (lost.length > 0 && this.pkg.checkLossOnSave)
+                                losses.push({ partName: part.partName.name, kind: 'skipped', count: lost.length });
+                            else
+                                this.lost.push(...lost);
+                        }
+                    }
+                }
+                const rrp = part.relationshipsPart;
+                if (rrp && rrp.size > 0)
+                    await visit(rrp);
+            }
+        };
+        await visit(this.pkg.relationshipsPart);
+        if (losses.length > 0)
+            throw new SaveLossException(losses);
     }
     async saveRels(rp) {
         this.sink.put(rp.partName.storeName, await rp.getBytes(), { contentType: ContentTypes.RELATIONSHIPS_PART });
@@ -37,12 +120,35 @@ class Saver {
         if (this.handled.has(part.partName.key))
             return;
         this.handled.add(part.partName.key);
+        if (this.copied.has(part.partName.key)) {
+            this.sink.put(part.partName.storeName, (await part.bytesRead()), { compress: part.compress, contentType: part.contentType });
+            const held = part.relationshipsPart;
+            if (held && held.size > 0)
+                await this.saveRels(held);
+            return;
+        }
         let bytes;
+        // CR-016 D2: a child its container never admits refuses the save, every one in the part listed, unless
+        // pkg.checkContentOnSave is off, when each is written as held and reported; the runtime's own refusal (a string in a
+        // run) names what the walk reported either way, where before it said nothing of the cause
+        const misplaced = [];
         try {
-            bytes = await part.getBytes();
+            bytes = await part.getBytes({
+                onNormalised: (n) => this.normalised.push(valueNormalised(part.partName.name, n)),
+                onOutOfRange: (r) => this.outOfRange.push(valueOutOfRange(r, part.partName.name)),
+                onMisplaced: (r) => misplaced.push(misplacedContent(r, part.partName.name)),
+            });
         }
         catch (e) {
-            throw new Docx4JException(`Problem saving part ${part.partName}`, { cause: e });
+            if (misplaced.length > 0 && this.pkg.checkContentOnSave)
+                throw new MisplacedContentException(part.partName.name, misplaced, { cause: e });
+            const because = misplaced.length > 0 ? `: ${misplaced.map((f) => f.message).join('; ')}` : '';
+            throw new Docx4JException(`Problem saving part ${part.partName}${because}`, { cause: e });
+        }
+        if (misplaced.length > 0) {
+            if (this.pkg.checkContentOnSave)
+                throw new MisplacedContentException(part.partName.name, misplaced);
+            this.misplaced.push(...misplaced);
         }
         this.sink.put(part.partName.storeName, bytes, { compress: part.compress, contentType: part.contentType });
         const rrp = part.relationshipsPart;

package/dist/opc/ZipPartStore.d.mts

@@ -1,17 +1,19 @@
-import type { PartStore, PartSink, PutOptions } from './PartStore.mjs';
+import { type PartStore, type PartSink, type PutOptions } from './PartStore.mjs';
 /**
  * A zip container read from bytes (docx4j io3.stores.ZipPartStore). The central directory is
  * read once; an entry is inflated on first `load` and then cached. ZIP64 archives are rejected.
+ * Entries are looked up as OPC part names, without case, and of two entries of one name the first
+ * in the central directory is the one read, the rest counted in `duplicates()` (CR-024).
  */
 export declare class ZipPartStore implements PartStore {
     private readonly data;
     private readonly entries;
-    private readonly order;
     private readonly cache;
     constructor(source: Uint8Array | ArrayBuffer);
     partNames(): Iterable<string>;
     has(partName: string): boolean;
     size(partName: string): number | undefined;
+    duplicates(): ReadonlyMap<string, number>;
     load(partName: string): Promise<Uint8Array>;
     loadSync(partName: string): Uint8Array;
     private readCentralDirectory;

package/dist/opc/ZipPartStore.mjs

@@ -1,19 +1,21 @@
 import { inflateSync, zipSync } from 'fflate';
+import { EntryIndex, entryKey } from './PartStore.mjs';
 import { InvalidFormatException } from './exceptions.mjs';
 /**
  * A zip container read from bytes (docx4j io3.stores.ZipPartStore). The central directory is
  * read once; an entry is inflated on first `load` and then cached. ZIP64 archives are rejected.
+ * Entries are looked up as OPC part names, without case, and of two entries of one name the first
+ * in the central directory is the one read, the rest counted in `duplicates()` (CR-024).
  */
 export class ZipPartStore {
     constructor(source) {
-        this.entries = new Map();
-        this.order = [];
+        this.entries = new EntryIndex();
         this.cache = new Map();
         this.data = source instanceof Uint8Array ? source : new Uint8Array(source);
         this.readCentralDirectory();
     }
     partNames() {
-        return this.order;
+        return this.entries.names();
     }
     has(partName) {
         return this.entries.has(partName);
@@ -22,11 +24,15 @@ export class ZipPartStore {
         var _a;
         return (_a = this.entries.get(partName)) === null || _a === void 0 ? void 0 : _a.size;
     }
+    duplicates() {
+        return this.entries.duplicates();
+    }
     async load(partName) {
         return this.loadSync(partName);
     }
     loadSync(partName) {
-        const cached = this.cache.get(partName);
+        const key = entryKey(partName);
+        const cached = this.cache.get(key);
         if (cached)
             return cached;
         const e = this.entries.get(partName);
@@ -47,7 +53,7 @@ export class ZipPartStore {
             bytes = inflateSync(raw);
         else
             throw new InvalidFormatException(`Unsupported compression method ${e.method} for ${partName}`);
-        this.cache.set(partName, bytes);
+        this.cache.set(key, bytes);
         return bytes;
     }
     readCentralDirectory() {
@@ -85,8 +91,7 @@ export class ZipPartStore {
             p += 46 + nameLen + extraLen + commentLen;
             if (name.endsWith('/'))
                 continue; // directory entry
-            this.entries.set(name, { name, method, compressedSize, size, localHeaderOffset });
-            this.order.push(name);
+            this.entries.add(name, { name, method, compressedSize, size, localHeaderOffset });
         }
     }
 }

package/dist/opc/exceptions.d.mts

@@ -1,3 +1,4 @@
+import type { MisplacedContentWarning } from './mce/preprocessor.mjs';
 /** docx4j Docx4JException: anything the packaging layer cannot recover from. */
 export declare class Docx4JException extends Error {
     readonly cause: unknown;
@@ -11,6 +12,113 @@ export declare class InvalidFormatException extends Docx4JException {
         cause?: unknown;
     });
 }
+/**
+ * A relationships part in another namespace, or in none, on its root or on any `Relationship` (CR-025 section 8, D10): refused when
+ * it is read, which is at the load, since the walk reads every relationships part it meets. Word reads such a part only through a
+ * repair, which reads every `Relationship` by its local name (the `rels-namespace` round), where the runtime here drops each one
+ * in a wrong namespace and with it the part it names, so a save would lose those parts with nothing said. `namespace` is the
+ * namespace found, `null` for none. The code is docx4j's and the WD's. `LoadOptions.repair: 'word'` reads such a part as Word's
+ * repair does, every `Relationship` by its local name (CR-031 section 2.3).
+ */
+export declare class RelationshipsNamespaceException extends InvalidFormatException {
+    readonly partName: string;
+    readonly namespace: string | null;
+    /** The finding's code, the WD's, shared with docx4j and docx4j-python. */
+    readonly code = "package.relationships_namespace";
+    constructor(partName: string, namespace: string | null);
+}
+/**
+ * A package whose container holds two entries of one name, OPC part names compared without case (WD REQ-206; CR-024),
+ * refused when it is loaded, before anything is read. Word reads such a file only after a repair, and the readers that
+ * don't refuse read different copies. `entries` gives each duplicated name, as its first entry spells it, with the
+ * number of entries; `LoadOptions.repair: 'word'` reads the first copy of each instead (CR-031).
+ */
+export declare class DuplicateEntryException extends InvalidFormatException {
+    readonly entries: Readonly<Record<string, number>>;
+    /** The finding's code, shared with docx4j-python (its CR-032). */
+    readonly code = "package.duplicate_entry";
+    constructor(entries: Readonly<Record<string, number>>);
+}
+/**
+ * Under `LoadOptions.repair: 'word'` or `'all'`, a name the container holds more than one entry of (WD REQ-206; CR-024):
+ * the first entry in the container's order is read, the rest ignored, and a save writes only the copy read, as Word's
+ * repaired save does. On `pkg.warnings`, ahead of the parts' warnings. The code and the fields are docx4j-python's (its
+ * CR-032): `entry`, the name as the first entry spells it (no leading '/'), and `count`, the entries of that name.
+ */
+export interface DuplicateEntryWarning {
+    code: 'package.duplicate_entry';
+    entry: string;
+    count: number;
+    message: string;
+}
+/**
+ * A package whose package relationships hold more than one officeDocument relationship (WD REQ-206's statement, WD 0.100;
+ * CR-024 section 9), refused when it is loaded, as a duplicated entry is and for the same reason: Word reads such a file
+ * only through a repair, and which target it reads then alternates with each repaired open in a Word session. A
+ * transitional and a strict relationship are two, and so are two naming one target. An External one names no part and
+ * isn't counted. `targets` gives each as a part name (`/word/document.xml`), in the relationships' order.
+ * `LoadOptions.repair: 'word'` reads the last relationship's target instead, as a fresh Word does (CR-031).
+ */
+export declare class MultipleMainPartsException extends InvalidFormatException {
+    readonly targets: readonly string[];
+    /** The finding's code, the WD's, shared with docx4j and docx4j-python. */
+    readonly code = "package.multiple_main_parts";
+    constructor(targets: readonly string[]);
+}
+/**
+ * Under `LoadOptions.repair: 'word'` or `'all'`, a package with more than one officeDocument relationship (WD REQ-206's
+ * statement; CR-024 section 9): the last relationship's target is read, as a fresh Word reads it, the other relationships
+ * go at the load, and a save writes the one main part. On `pkg.warnings`, after any `DuplicateEntryWarning` and ahead of
+ * the parts' warnings. The fields are docx4j-python's: `partName`, the part read (`/word/document.xml`), and `count`, the
+ * relationships there were.
+ */
+export interface MultipleMainPartsWarning {
+    code: 'package.multiple_main_parts';
+    partName: string;
+    count: number;
+    message: string;
+}
+/**
+ * An `External` officeDocument relationship beside an internal one (WD REQ-206's NOTE, WD 0.102; CR-031 D3), refused at the load
+ * under `LoadOptions.repair` `'refuse'`, the default, and `'word'`, first or last alike: Word offers a repair and then fails
+ * (the `x-ext-*` rounds), so there is no reading of Word's to follow. `urls` gives each `External` relationship's target as
+ * written and `targets` each internal one's as a part name, in the relationships' order (docx4j-python's fields). The URL is
+ * never fetched. `repair: 'all'` reads the internal target instead, a repair of this package's own.
+ */
+export declare class ExternalMainPartException extends InvalidFormatException {
+    readonly urls: readonly string[];
+    readonly targets: readonly string[];
+    /** The finding's code, the WD's, shared with docx4j and docx4j-python. */
+    readonly code = "package.external_main_part";
+    constructor(urls: readonly string[], targets: readonly string[]);
+}
+/**
+ * Under `LoadOptions.repair: 'all'`, an `External` officeDocument relationship beside an internal one (WD REQ-206's NOTE;
+ * CR-031 section 2.2): the internal target is read, every `External` officeDocument relationship goes at the load, so a save
+ * writes none, and the URL is never fetched. A repair of this package's own, so a reading's `repaired` is `own`. On
+ * `pkg.externalMainPart` and on `pkg.warnings`, after the other load warnings. `partName` is the part read, `urls` each URL
+ * as written, in the relationships' order (the text model's `detail` the first).
+ */
+export interface ExternalMainPartWarning {
+    code: 'package.external_main_part';
+    partName: string;
+    urls: readonly string[];
+    message: string;
+}
+/**
+ * Under `LoadOptions.repair: 'word'` or `'all'`, a relationships part in another namespace, or in none, on its root or on any
+ * `Relationship` (CR-031 section 2.3; CR-025 section 8 refuses it otherwise): every `Relationship` is read by its local name,
+ * as Word's repair reads it, and a save writes the right namespace, so nothing is lost. On the relationships part's `warnings`
+ * and so on `pkg.warnings`. `partName` is the relationships part, `namespace` the first wrong one found (`null` for none),
+ * `count` the relationships read (the WD's `detail`, docx4j's).
+ */
+export interface RelationshipsNamespaceWarning {
+    code: 'package.relationships_namespace';
+    partName: string;
+    namespace: string | null;
+    count: number;
+    message: string;
+}
 /**
  * docx4j CyclicStylesException: a style's `w:basedOn` chain comes back to a style it already
  * holds, or goes deeper than docx4j's limit of 32. Thrown only when
@@ -70,3 +178,35 @@ export declare class PartUnmarshalException extends Docx4JException {
     readonly line: number | undefined;
     readonly column: number | undefined;
 }
+/**
+ * A save refused for a child its container never admits (CR-016 D2): the part being marshalled holds a run straight in
+ * the body, a table in a paragraph, a string in a run, ..., which Word 365 refuses the file for or repairs by dropping
+ * content (check 72). Nothing was written. `findings` are the part's, each with its path and docx4j's message naming
+ * the fix; `pkg.checkContentOnSave = false` writes the file as held and reports them on `pkg.lastSave.misplaced` instead.
+ */
+export declare class MisplacedContentException extends Docx4JException {
+    /** The part refused: `/word/document.xml`. */
+    readonly partName: string;
+    readonly findings: readonly MisplacedContentWarning[];
+    constructor(
+    /** The part refused: `/word/document.xml`. */
+    partName: string, findings: readonly MisplacedContentWarning[], options?: {
+        cause?: unknown;
+    });
+}
+/** One part a save would lose content from (CR-025 section 2.3). */
+export interface ContentLoss {
+    partName: string;
+    kind: 'skipped';
+    /** The items its read dropped that Word's own save doesn't drop too: `part.skipped` with `onSave: 'lost'`, one each (CR-025 section 10). */
+    count: number;
+}
+/**
+ * A save refused because a part holding what its read dropped was changed, so a marshal would lose that (CR-025 section 2.3, the
+ * repair policy's P7). Nothing is written. The code and the wording are docx4j-python's, with this package's way past it.
+ */
+export declare class SaveLossException extends Docx4JException {
+    readonly losses: readonly ContentLoss[];
+    readonly code = "save.content_lost";
+    constructor(losses: readonly ContentLoss[]);
+}

package/dist/opc/exceptions.mjs

@@ -13,6 +13,83 @@ export class InvalidFormatException extends Docx4JException {
         this.name = 'InvalidFormatException';
     }
 }
+/**
+ * A relationships part in another namespace, or in none, on its root or on any `Relationship` (CR-025 section 8, D10): refused when
+ * it is read, which is at the load, since the walk reads every relationships part it meets. Word reads such a part only through a
+ * repair, which reads every `Relationship` by its local name (the `rels-namespace` round), where the runtime here drops each one
+ * in a wrong namespace and with it the part it names, so a save would lose those parts with nothing said. `namespace` is the
+ * namespace found, `null` for none. The code is docx4j's and the WD's. `LoadOptions.repair: 'word'` reads such a part as Word's
+ * repair does, every `Relationship` by its local name (CR-031 section 2.3).
+ */
+export class RelationshipsNamespaceException extends InvalidFormatException {
+    constructor(partName, namespace) {
+        super(`${partName}: a relationships part in ${namespace === null ? 'no namespace' : `another namespace, ${namespace}`}, which Word reads `
+            + "only through a repair; refused, since its relationships would be lost with the parts they name. Load with { repair: 'word' } "
+            + 'to read every Relationship by its local name, as Word does (REQ-207)');
+        this.partName = partName;
+        this.namespace = namespace;
+        /** The finding's code, the WD's, shared with docx4j and docx4j-python. */
+        this.code = 'package.relationships_namespace';
+        this.name = 'RelationshipsNamespaceException';
+    }
+}
+/**
+ * A package whose container holds two entries of one name, OPC part names compared without case (WD REQ-206; CR-024),
+ * refused when it is loaded, before anything is read. Word reads such a file only after a repair, and the readers that
+ * don't refuse read different copies. `entries` gives each duplicated name, as its first entry spells it, with the
+ * number of entries; `LoadOptions.repair: 'word'` reads the first copy of each instead (CR-031).
+ */
+export class DuplicateEntryException extends InvalidFormatException {
+    constructor(entries) {
+        const list = Object.entries(entries);
+        super(list.length === 1
+            ? `Duplicate entry ${list[0][0]} in this package: ${list[0][1]} entries (REQ-206). Load with { repair: 'word' } to read the first, as Word does (REQ-207)`
+            : `Duplicate entries in this package: ${list.map(([name, n]) => `${name}, ${n} entries`).join('; ')} (REQ-206). `
+                + "Load with { repair: 'word' } to read the first of each, as Word does (REQ-207)");
+        this.entries = entries;
+        /** The finding's code, shared with docx4j-python (its CR-032). */
+        this.code = 'package.duplicate_entry';
+        this.name = 'DuplicateEntryException';
+    }
+}
+/**
+ * A package whose package relationships hold more than one officeDocument relationship (WD REQ-206's statement, WD 0.100;
+ * CR-024 section 9), refused when it is loaded, as a duplicated entry is and for the same reason: Word reads such a file
+ * only through a repair, and which target it reads then alternates with each repaired open in a Word session. A
+ * transitional and a strict relationship are two, and so are two naming one target. An External one names no part and
+ * isn't counted. `targets` gives each as a part name (`/word/document.xml`), in the relationships' order.
+ * `LoadOptions.repair: 'word'` reads the last relationship's target instead, as a fresh Word does (CR-031).
+ */
+export class MultipleMainPartsException extends InvalidFormatException {
+    constructor(targets) {
+        super(`${targets.length} officeDocument relationships in this package: ${targets.join(', ')} (REQ-206). `
+            + "Load with { repair: 'word' } to read the last, as a fresh Word does (REQ-207)");
+        this.targets = targets;
+        /** The finding's code, the WD's, shared with docx4j and docx4j-python. */
+        this.code = 'package.multiple_main_parts';
+        this.name = 'MultipleMainPartsException';
+    }
+}
+/**
+ * An `External` officeDocument relationship beside an internal one (WD REQ-206's NOTE, WD 0.102; CR-031 D3), refused at the load
+ * under `LoadOptions.repair` `'refuse'`, the default, and `'word'`, first or last alike: Word offers a repair and then fails
+ * (the `x-ext-*` rounds), so there is no reading of Word's to follow. `urls` gives each `External` relationship's target as
+ * written and `targets` each internal one's as a part name, in the relationships' order (docx4j-python's fields). The URL is
+ * never fetched. `repair: 'all'` reads the internal target instead, a repair of this package's own.
+ */
+export class ExternalMainPartException extends InvalidFormatException {
+    constructor(urls, targets) {
+        super(`${urls.length === 1 ? 'An External officeDocument relationship' : `${urls.length} External officeDocument relationships`} in this package, `
+            + `to ${urls.join(', ')}, beside ${targets.length === 1 ? 'an internal one' : `${targets.length} internal ones`}, to ${targets.join(', ')} `
+            + "(REQ-206). Word refuses such a package, even through its repair. Load with { repair: 'all' } to read "
+            + `${targets[targets.length - 1]} and drop the External relationship, a repair of this package's own (REQ-207)`);
+        this.urls = urls;
+        this.targets = targets;
+        /** The finding's code, the WD's, shared with docx4j and docx4j-python. */
+        this.code = 'package.external_main_part';
+        this.name = 'ExternalMainPartException';
+    }
+}
 /**
  * docx4j CyclicStylesException: a style's `w:basedOn` chain comes back to a style it already
  * holds, or goes deeper than docx4j's limit of 32. Thrown only when
@@ -78,3 +155,34 @@ export class PartUnmarshalException extends Docx4JException {
         this.column = options === null || options === void 0 ? void 0 : options.column;
     }
 }
+/**
+ * A save refused for a child its container never admits (CR-016 D2): the part being marshalled holds a run straight in
+ * the body, a table in a paragraph, a string in a run, ..., which Word 365 refuses the file for or repairs by dropping
+ * content (check 72). Nothing was written. `findings` are the part's, each with its path and docx4j's message naming
+ * the fix; `pkg.checkContentOnSave = false` writes the file as held and reports them on `pkg.lastSave.misplaced` instead.
+ */
+export class MisplacedContentException extends Docx4JException {
+    constructor(
+    /** The part refused: `/word/document.xml`. */
+    partName, findings, options) {
+        super(`Save refused: ${partName} holds ${findings.length === 1 ? 'a child its container never admits' : `${findings.length} children their containers never admit`}, `
+            + 'which Word 365 refuses the file for or repairs by dropping content (set pkg.checkContentOnSave = false to write it as held):\n'
+            + findings.map((f) => `  ${f.message}`).join('\n'), options);
+        this.partName = partName;
+        this.findings = findings;
+        this.name = 'MisplacedContentException';
+    }
+}
+/**
+ * A save refused because a part holding what its read dropped was changed, so a marshal would lose that (CR-025 section 2.3, the
+ * repair policy's P7). Nothing is written. The code and the wording are docx4j-python's, with this package's way past it.
+ */
+export class SaveLossException extends Docx4JException {
+    constructor(losses) {
+        super(`Saving would lose content Word's own save keeps or isn't measured on: ${losses.map((l) => `${l.partName} holds ${l.count} item${l.count === 1 ? '' : 's'} the load skipped (part.skipped, onSave lost)`).join(', ')}. `
+            + `Set pkg.checkLossOnSave = false to write ${losses.length === 1 ? 'the part without it' : 'the parts without them'}.`);
+        this.losses = losses;
+        this.code = 'save.content_lost';
+        this.name = 'SaveLossException';
+    }
+}

package/dist/opc/index.d.mts

@@ -4,9 +4,12 @@ export { ContentTypeManager, CONTENT_TYPES_NS } from './ContentTypeManager.mjs';
 export { type PartStore, type PartSink, type PutOptions, MemoryPartStore, MemoryPartSink } from './PartStore.mjs';
 export { ZipPartStore, ZipPartSink } from './ZipPartStore.mjs';
 export { FlatOpcPartStore, FlatOpcPartSink, type FlatOpcSinkOptions, PKG_NS } from './FlatOpcPartStore.mjs';
-export { loadPackage, type LoadOptions } from './Load.mjs';
-export { savePackage } from './Save.mjs';
-export { mceKeep, mcePreprocess, createMcePreprocessor, resolveAlternateContent, preprocessAlternateContent, MCE_NS, KEPT_HOSTS, type McePreprocessOptions, type McBranchesDifferWarning, type PartWarning, type MceResult } from './mce/preprocessor.mjs';
-export { UNDERSTOOD_NAMESPACES, UNDERSTOOD_PREFIXES } from './mce/understood.mjs';
-export { Docx4JException, InvalidFormatException, PartUnrecognisedException, PartUnmarshalException, CyclicStylesException, PropertyResolverNotCreatedException } from './exceptions.mjs';
+export { loadPackage, type LoadOptions, type RepairMode, REPAIR_MODES } from './Load.mjs';
+export { savePackage, type ValueNormalised, type SaveReport } from './Save.mjs';
+export { mceKeep, mcePreprocess, createMcePreprocessor, resolveAlternateContent, preprocessAlternateContent, MCE_NS, KEPT_HOSTS, type McePreprocessOptions, type McBranchesDifferWarning, type McNothingSelectedWarning, type McUndeclaredPrefixWarning, type ValueKeptWarning, type ValueOutOfRangeWarning, type MisplacedContentWarning, type PartWarning, type MceResult } from './mce/preprocessor.mjs';
+export { repairBreaksOutsideRuns, type BrOutsideRunWarning } from './repair/breaks.mjs';
+export { readMainPartRoot, type UnexpectedRootWarning } from './repair/mainRoot.mjs';
+export type { ContentSkippedWarning } from './skipped.mjs';
+export { UNDERSTOOD_NAMESPACES, TRAVERSAL_NAMESPACES } from './mce/understood.mjs';
+export { Docx4JException, InvalidFormatException, PartUnrecognisedException, PartUnmarshalException, MisplacedContentException, SaveLossException, type ContentLoss, DuplicateEntryException, type DuplicateEntryWarning, MultipleMainPartsException, type MultipleMainPartsWarning, RelationshipsNamespaceException, type RelationshipsNamespaceWarning, ExternalMainPartException, type ExternalMainPartWarning, CyclicStylesException, PropertyResolverNotCreatedException } from './exceptions.mjs';
 export { parseXml, serializeXml, serializeXmlPart, createDocument, encodeText, decodeXmlText, stripXmlDeclaration, base64Encode, base64Decode, childElements, XML_DECLARATION } from '../xml/dom.mjs';

package/dist/opc/index.mjs

@@ -5,9 +5,11 @@ export { ContentTypeManager, CONTENT_TYPES_NS } from './ContentTypeManager.mjs';
 export { MemoryPartStore, MemoryPartSink } from './PartStore.mjs';
 export { ZipPartStore, ZipPartSink } from './ZipPartStore.mjs';
 export { FlatOpcPartStore, FlatOpcPartSink, PKG_NS } from './FlatOpcPartStore.mjs';
-export { loadPackage } from './Load.mjs';
+export { loadPackage, REPAIR_MODES } from './Load.mjs';
 export { savePackage } from './Save.mjs';
 export { mceKeep, mcePreprocess, createMcePreprocessor, resolveAlternateContent, preprocessAlternateContent, MCE_NS, KEPT_HOSTS } from './mce/preprocessor.mjs';
-export { UNDERSTOOD_NAMESPACES, UNDERSTOOD_PREFIXES } from './mce/understood.mjs';
-export { Docx4JException, InvalidFormatException, PartUnrecognisedException, PartUnmarshalException, CyclicStylesException, PropertyResolverNotCreatedException } from './exceptions.mjs';
+export { repairBreaksOutsideRuns } from './repair/breaks.mjs';
+export { readMainPartRoot } from './repair/mainRoot.mjs';
+export { UNDERSTOOD_NAMESPACES, TRAVERSAL_NAMESPACES } from './mce/understood.mjs';
+export { Docx4JException, InvalidFormatException, PartUnrecognisedException, PartUnmarshalException, MisplacedContentException, SaveLossException, DuplicateEntryException, MultipleMainPartsException, RelationshipsNamespaceException, ExternalMainPartException, CyclicStylesException, PropertyResolverNotCreatedException } from './exceptions.mjs';
 export { parseXml, serializeXml, serializeXmlPart, createDocument, encodeText, decodeXmlText, stripXmlDeclaration, base64Encode, base64Decode, childElements, XML_DECLARATION } from '../xml/dom.mjs';