@docx4j/core-ts 0.6.0 → 0.7.0

package/dist/opc/Load.mjs

@@ -1,6 +1,6 @@
 import { PartName, CONTENT_TYPES_NAME } from './PartName.mjs';
 import { ContentTypeManager } from './ContentTypeManager.mjs';
-import { Docx4JException, InvalidFormatException } from './exceptions.mjs';
+import { Docx4JException, DuplicateEntryException, ExternalMainPartException, InvalidFormatException, MultipleMainPartsException } from './exceptions.mjs';
 import { Namespaces } from '../parts/Namespaces.mjs';
 import { RelationshipsPart, isExternal } from '../parts/RelationshipsPart.mjs';
 import { XmlPart } from '../parts/XmlPart.mjs';
@@ -8,6 +8,8 @@ import { CustomXmlDataStoragePart } from '../parts/DefaultXmlPart.mjs';
 import { CustomXmlDataStoragePropertiesPart, DS_NS } from '../parts/customXml/index.mjs';
 import { defaultPartRegistry } from '../parts/PartRegistry.mjs';
 import { decodeXmlText, parseXml } from '../xml/dom.mjs';
+/** The values of `LoadOptions.repair`, in the WD's order. */
+export const REPAIR_MODES = Object.freeze(['refuse', 'word', 'all']);
 /** Relationship types whose target is the main part (docx4j PackageRelsUtil.getNameOfMainPart). */
 const MAIN_PART_RELATIONSHIPS = [
     Namespaces.DOCUMENT,
@@ -15,23 +17,38 @@ const MAIN_PART_RELATIONSHIPS = [
     Namespaces.DRAWINGML_DIAGRAM_LAYOUT,
     Namespaces.DOCUMENT_STRICT,
 ];
+/**
+ * What REQ-206's statement counts (docx4j PackageRelsUtil.isMainPart): a transitional and a strict relationship are two. An
+ * External one isn't counted (CR-024 section 9.2): it names no part, so it can't be what the package reads.
+ */
+const OFFICE_DOCUMENT_RELATIONSHIPS = [Namespaces.DOCUMENT, Namespaces.DOCUMENT_STRICT];
 /**
  * Loads a package from a container (docx4j io3.Load3): content types, then the package
  * relationships, then every part reachable through relationships, recursively. Parts are not
  * unmarshalled. `createPackage` picks the package class from the main part's content type.
  */
 export async function loadPackage(store, createPackage, options = {}) {
-    var _a;
+    var _a, _b, _c;
     const registry = (_a = options.registry) !== null && _a !== void 0 ? _a : defaultPartRegistry;
+    const repair = repairOf(options.repair);
+    const followsWord = repair !== 'refuse';
+    const duplicateEntries = duplicateEntriesOf(store, followsWord);
     if (!store.has(CONTENT_TYPES_NAME))
         throw new InvalidFormatException(`${CONTENT_TYPES_NAME} is missing from this package`);
     const ctm = ContentTypeManager.parse(decodeXmlText(await store.load(CONTENT_TYPES_NAME)));
     const packageRels = RelationshipsPart.createPackageRels();
     if (!store.has('_rels/.rels'))
         throw new InvalidFormatException('_rels/.rels appears to be missing from this package');
+    packageRels.readsByLocalName = followsWord;
     packageRels.setBytes(await store.load('_rels/.rels'));
     await packageRels.getContents();
-    const mainRel = packageRels.list.find((r) => MAIN_PART_RELATIONSHIPS.includes(r.type));
+    // External first, as docx4j has it: refused at refuse and word whatever else the relationships hold, and dropped at all
+    // before Word's last-relationship repair
+    const external = externalMainPart(packageRels, repair);
+    const mainParts = oneMainPart(packageRels, followsWord);
+    // an External relationship names no part, so it gives way to one that does
+    const mainRels = packageRels.list.filter((r) => MAIN_PART_RELATIONSHIPS.includes(r.type));
+    const mainRel = (_b = mainRels.find((r) => !isExternal(r))) !== null && _b !== void 0 ? _b : mainRels[0];
     if (!mainRel)
         throw new InvalidFormatException('No relationship of type officeDocument');
     const mainPartName = PartName.resolve(PartName.ROOT, mainRel.target);
@@ -39,19 +56,111 @@ export async function loadPackage(store, createPackage, options = {}) {
     pkg.contentTypeManager = ctm;
     pkg.sourcePartStore = store;
     pkg.relationshipsPart = packageRels;
+    pkg.duplicateEntries = duplicateEntries;
+    pkg.multipleMainParts = mainParts === null || mainParts === void 0 ? void 0 : mainParts.warning;
+    pkg.externalMainPart = external;
     packageRels.sourceP = pkg;
     packageRels.package = pkg;
-    const loader = new Loader(pkg, store, registry, options.preprocessor);
+    const loader = new Loader(pkg, store, registry, options.preprocessor, followsWord);
     await loader.addPartsFromRelationships(pkg, packageRels);
     await loader.registerCustomXmlDataStorageParts();
+    // after the walk, so a target the kept part reaches by a relationship of its own, or a second relationship names, keeps its type
+    for (const name of (_c = mainParts === null || mainParts === void 0 ? void 0 : mainParts.dropped) !== null && _c !== void 0 ? _c : [])
+        if (!pkg.getPart(name))
+            ctm.removeOverrideContentType(name);
     return pkg;
 }
+/**
+ * More than one officeDocument relationship (WD REQ-206's statement; CR-024 section 9): refused under `repair: 'refuse'`, naming
+ * the targets. Under `'word'` and `'all'` the last stands and the others go here, before anything is read, so that the package's class, the
+ * walk, `getMainPart()` and `getMainDocumentPart()` all find one main part, and a save writes one. `dropped` is the part
+ * names they gave, whose Overrides `loadPackage` settles after the walk.
+ */
+function oneMainPart(rels, followsWord) {
+    const mains = rels.list.filter((r) => OFFICE_DOCUMENT_RELATIONSHIPS.includes(r.type) && !isExternal(r));
+    if (mains.length < 2)
+        return undefined;
+    const names = mains.map((r) => PartName.resolve(PartName.ROOT, r.target));
+    if (!followsWord)
+        throw new MultipleMainPartsException(names.map((name) => name.name));
+    for (const r of mains.slice(0, -1))
+        rels.removeRelationship(r);
+    const partName = names[names.length - 1].name;
+    return {
+        warning: {
+            code: 'package.multiple_main_parts',
+            partName,
+            count: mains.length,
+            message: `${mains.length} officeDocument relationships in this package (REQ-206); the last's target read, ${partName}`,
+        },
+        dropped: names.slice(0, -1),
+    };
+}
+/** `LoadOptions.repair`, `'refuse'` when not given; any other value refused (WD REQ-207). */
+function repairOf(repair) {
+    if (repair === undefined)
+        return 'refuse';
+    if (!REPAIR_MODES.includes(repair)) {
+        throw new Docx4JException(`repair: '${String(repair)}' is not ${REPAIR_MODES.map((m) => `'${m}'`).join(', ')} (WD REQ-207)`);
+    }
+    return repair;
+}
+/**
+ * An `External` officeDocument relationship (WD REQ-206's NOTE; CR-031 section 2.2). With no internal one beside it the package
+ * has no main document part, refused at every value (REQ-321), where the URL used to be taken for a part name. Beside an
+ * internal one it's refused at `'refuse'` and `'word'`, first or last alike, since Word refuses it even through its repair;
+ * at `'all'` every such relationship goes here, before anything is read, so a save writes none and the URL is never
+ * fetched, and the warning names the part read: the last internal relationship's target, as Word's repair of several reads.
+ */
+function externalMainPart(rels, repair) {
+    const mains = rels.list.filter((r) => OFFICE_DOCUMENT_RELATIONSHIPS.includes(r.type));
+    const externals = mains.filter(isExternal);
+    if (externals.length === 0)
+        return undefined;
+    const urls = externals.map((r) => r.target);
+    const internals = mains.filter((r) => !isExternal(r)).map((r) => PartName.resolve(PartName.ROOT, r.target).name);
+    if (internals.length === 0) {
+        throw new InvalidFormatException(`This package's only officeDocument relationship is External, to ${urls.join(', ')}, so it has no `
+            + 'main document part (REQ-321); refused at every value of repair. The URL is not fetched');
+    }
+    if (repair !== 'all')
+        throw new ExternalMainPartException(urls, internals);
+    for (const r of externals)
+        rels.removeRelationship(r);
+    const partName = internals[internals.length - 1];
+    return {
+        code: 'package.external_main_part',
+        partName,
+        urls,
+        message: `${urls.length === 1 ? 'An External officeDocument relationship' : `${urls.length} External officeDocument relationships`}, `
+            + `to ${urls.join(', ')}, beside the internal one dropped, ${partName} read, the URL not fetched: a repair of this package's own (REQ-207)`,
+    };
+}
+/**
+ * The store's duplicated names (CR-024, WD REQ-206), refused under `repair: 'refuse'` before anything is read, else one warning
+ * each. A store without `duplicates()` is not checked.
+ */
+function duplicateEntriesOf(store, followsWord) {
+    var _a;
+    const duplicates = (_a = store.duplicates) === null || _a === void 0 ? void 0 : _a.call(store);
+    if (!duplicates || duplicates.size === 0)
+        return [];
+    if (!followsWord)
+        throw new DuplicateEntryException(Object.fromEntries(duplicates));
+    return [...duplicates].map(([entry, count]) => ({
+        code: 'package.duplicate_entry',
+        entry,
+        count,
+        message: `${entry}: ${count} entries of one name in this package; the first read, the rest ignored (REQ-206)`,
+    }));
+}
 class Loader {
-    constructor(pkg, store, registry, preprocessor) {
+    constructor(pkg, store, registry, preprocessor, followsWord) {
         this.pkg = pkg;
         this.store = store;
         this.registry = registry;
         this.preprocessor = preprocessor;
+        this.followsWord = followsWord;
         this.handled = new Set();
     }
     async addPartsFromRelationships(source, rp) {
@@ -88,6 +197,7 @@ class Loader {
         const relsName = PartName.relsFor(partName).storeName;
         if (this.store.has(relsName)) {
             const rrp = new RelationshipsPart(part);
+            rrp.readsByLocalName = this.followsWord;
             rrp.setBytes(await this.store.load(relsName));
             await rrp.getContents();
             part.relationshipsPart = rrp;

package/dist/opc/PartStore.d.mts

@@ -10,6 +10,35 @@ export interface PartStore {
     load(partName: string): Promise<Uint8Array>;
     /** Size if known without loading, else undefined. */
     size?(partName: string): number | undefined;
+    /**
+     * The names the container holds more than one entry of, OPC part names compared without case (WD REQ-206; CR-024): each
+     * first entry's spelling, with the number of entries, in container order. The load refuses a package with any, unless
+     * `LoadOptions.duplicateEntries` is `'first'`. Every store here has it; a store without it is not checked.
+     */
+    duplicates?(): ReadonlyMap<string, number>;
+}
+/** An entry's key: its name without a leading '/', lower-cased, as `PartName`'s equality compares (CR-024 section 2.1). */
+export declare function entryKey(name: string): string;
+/**
+ * A container's entries by key (`entryKey`), the first entry of each key kept with its spelling and its value and the
+ * rest counted: what each store reads its container into, so that `has`, `load` and `size` agree and look up without
+ * case, and `duplicates()` reports a name held twice (CR-024, WD REQ-206).
+ */
+export declare class EntryIndex<T> {
+    private readonly byKey;
+    /** Adds an entry; a second entry of a key is counted, its value not kept. */
+    add(name: string, value: T): void;
+    /** Sets an entry's value, replacing the one its key holds (a sink's write), its first spelling kept. */
+    set(name: string, value: T): void;
+    get(name: string): T | undefined;
+    has(name: string): boolean;
+    delete(name: string): boolean;
+    /** Each key's first spelling, in the order the entries were added. */
+    names(): string[];
+    /** Each key's value (its first entry's), in the same order. */
+    values(): T[];
+    /** The keys added more than once: the first spelling and the count. */
+    duplicates(): Map<string, number>;
 }
 export interface PutOptions {
     /** Deflate in a zip (default true); ignored by containers that do not compress. */
@@ -23,7 +52,10 @@ export interface PartSink<R = unknown> {
     /** Completes the container. */
     finish(): Promise<R>;
 }
-/** An in-memory container: new packages, tests, and the result of `MemoryPartSink`. */
+/**
+ * An in-memory container: new packages, tests, and the result of `MemoryPartSink`. The constructor's entries are read as a
+ * container's (a second of one name counted, `duplicates()`); `put`, a sink's write, replaces.
+ */
 export declare class MemoryPartStore implements PartStore, PartSink<MemoryPartStore> {
     private readonly parts;
     /** Content types as put, for stores filled through the sink side. */
@@ -33,6 +65,7 @@ export declare class MemoryPartStore implements PartStore, PartSink<MemoryPartSt
     has(partName: string): boolean;
     load(partName: string): Promise<Uint8Array>;
     size(partName: string): number | undefined;
+    duplicates(): ReadonlyMap<string, number>;
     put(partName: string, bytes: Uint8Array, options?: PutOptions): void;
     delete(partName: string): boolean;
     finish(): Promise<MemoryPartStore>;

package/dist/opc/PartStore.mjs

@@ -1,28 +1,91 @@
-/** An in-memory container: new packages, tests, and the result of `MemoryPartSink`. */
+/** An entry's key: its name without a leading '/', lower-cased, as `PartName`'s equality compares (CR-024 section 2.1). */
+export function entryKey(name) {
+    return (name.startsWith('/') ? name.substring(1) : name).toLowerCase();
+}
+/**
+ * A container's entries by key (`entryKey`), the first entry of each key kept with its spelling and its value and the
+ * rest counted: what each store reads its container into, so that `has`, `load` and `size` agree and look up without
+ * case, and `duplicates()` reports a name held twice (CR-024, WD REQ-206).
+ */
+export class EntryIndex {
+    constructor() {
+        this.byKey = new Map();
+    }
+    /** Adds an entry; a second entry of a key is counted, its value not kept. */
+    add(name, value) {
+        const key = entryKey(name);
+        const entry = this.byKey.get(key);
+        if (entry)
+            entry.count++;
+        else
+            this.byKey.set(key, { name: name.startsWith('/') ? name.substring(1) : name, value, count: 1 });
+    }
+    /** Sets an entry's value, replacing the one its key holds (a sink's write), its first spelling kept. */
+    set(name, value) {
+        const entry = this.byKey.get(entryKey(name));
+        if (entry)
+            entry.value = value;
+        else
+            this.add(name, value);
+    }
+    get(name) {
+        var _a;
+        return (_a = this.byKey.get(entryKey(name))) === null || _a === void 0 ? void 0 : _a.value;
+    }
+    has(name) {
+        return this.byKey.has(entryKey(name));
+    }
+    delete(name) {
+        return this.byKey.delete(entryKey(name));
+    }
+    /** Each key's first spelling, in the order the entries were added. */
+    names() {
+        return [...this.byKey.values()].map((e) => e.name);
+    }
+    /** Each key's value (its first entry's), in the same order. */
+    values() {
+        return [...this.byKey.values()].map((e) => e.value);
+    }
+    /** The keys added more than once: the first spelling and the count. */
+    duplicates() {
+        const out = new Map();
+        for (const e of this.byKey.values())
+            if (e.count > 1)
+                out.set(e.name, e.count);
+        return out;
+    }
+}
+/**
+ * An in-memory container: new packages, tests, and the result of `MemoryPartSink`. The constructor's entries are read as a
+ * container's (a second of one name counted, `duplicates()`); `put`, a sink's write, replaces.
+ */
 export class MemoryPartStore {
     constructor(entries) {
-        this.parts = new Map();
+        this.parts = new EntryIndex();
         /** Content types as put, for stores filled through the sink side. */
         this.contentTypes = new Map();
         if (entries)
             for (const [name, bytes] of entries)
-                this.parts.set(normalize(name), bytes);
+                this.parts.add(normalize(name), bytes);
     }
     partNames() {
-        return this.parts.keys();
+        return this.parts.names();
     }
     has(partName) {
-        return this.parts.has(normalize(partName));
+        return this.parts.has(partName);
     }
     async load(partName) {
-        const bytes = this.parts.get(normalize(partName));
+        const bytes = this.parts.get(partName);
         if (bytes === undefined)
             throw new Error(`No part ${partName}`);
         return bytes;
     }
     size(partName) {
         var _a;
-        return (_a = this.parts.get(normalize(partName))) === null || _a === void 0 ? void 0 : _a.length;
+        return (_a = this.parts.get(partName)) === null || _a === void 0 ? void 0 : _a.length;
+    }
+    duplicates() {
+        return this.parts.duplicates();
     }
     put(partName, bytes, options) {
         const name = normalize(partName);
@@ -31,7 +94,7 @@ export class MemoryPartStore {
             this.contentTypes.set(name, options.contentType);
     }
     delete(partName) {
-        return this.parts.delete(normalize(partName));
+        return this.parts.delete(partName);
     }
     async finish() {
         return this;

package/dist/opc/Save.d.mts

@@ -1,9 +1,12 @@
 import type { PartSink } from './PartStore.mjs';
+import type { ValueOutOfRangeWarning, MisplacedContentWarning } from './mce/preprocessor.mjs';
+import type { ContentSkippedWarning } from './skipped.mjs';
 import type { OpcPackage } from '../packages/OpcPackage.mjs';
 /**
  * A value a save wrote in its normal form, or left out (CR-015 D2 and D8; the objects facade's normaliser, its
  * CR-013 phase C, docx4j CR-061's rule): `path` from the part's root, `before` as read, `after` as written, null
- * where the attribute or the element was left out. The code is docx4j-python CR-018's.
+ * where the attribute or the element was left out. The code is this package's (CR-015 D8); docx4j-python CR-018 reports
+ * the same as `package.last_save.normalised`.
  */
 export interface ValueNormalised {
     code: 'value.normalised';
@@ -13,9 +16,21 @@ export interface ValueNormalised {
     after: string | null;
     message: string;
 }
-/** What the last save of a package did beyond writing it: each value it normalised (CR-015 D8). */
+/**
+ * What the last save of a package did beyond writing it: each value it normalised (CR-015 D8), each integer
+ * attribute value it wrote that Word 365 reads differently, written as held (CR-017 P3, E3), with
+ * `checkContentOnSave` off, each child it wrote where its container never admits one (CR-016 D2), each with its path,
+ * each item the read dropped that a changed part was written without as Word's own save writes it (CR-025 section 10), and,
+ * with `checkLossOnSave` off, each it was written without that Word's save keeps or nobody has measured (CR-025 D8).
+ */
 export interface SaveReport {
     normalised: ValueNormalised[];
+    outOfRange: ValueOutOfRangeWarning[];
+    misplaced: MisplacedContentWarning[];
+    /** Items a changed part was written without, Word's own save dropping them too (`onSave: 'dropped'`, CR-025 D14): never refused. */
+    dropped: ContentSkippedWarning[];
+    /** Items a changed part was written without under `checkLossOnSave` off (`onSave: 'lost'`). */
+    lost: ContentSkippedWarning[];
 }
 /**
  * Writes a package to a sink (docx4j io3.Save): `[Content_Types].xml` first, then the package

package/dist/opc/Save.mjs

@@ -1,8 +1,9 @@
 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)}`;
@@ -11,6 +12,29 @@ function valueNormalised(partName, n) {
         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
@@ -18,11 +42,14 @@ function valueNormalised(partName, n) {
  * 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);
     const result = await sink.finish();
-    pkg.lastSave = { normalised: saver.normalised };
+    pkg.lastSave = { normalised: saver.normalised, outOfRange: saver.outOfRange, misplaced: saver.misplaced, dropped: saver.dropped, lost: saver.lost };
     return result;
 }
 class Saver {
@@ -31,6 +58,52 @@ class Saver {
         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 });
@@ -47,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({ onNormalised: (n) => this.normalised.push(valueNormalised(part.partName.name, n)) });
+            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 });
         }
     }
 }