@docx4j/core-ts 0.5.0 → 0.7.0

package/dist/parts/XmlPart.mjs

@@ -1,24 +1,12 @@
 import { unmarshalNode, marshalNode, NAMESPACE_PREFIXES } from '@docx4j/generated-objects-ts';
 import { Part } from './Part.mjs';
-import { Namespaces } from './Namespaces.mjs';
 import { Docx4JException, PartUnmarshalException } from '../opc/exceptions.mjs';
-import { parseXml, serializeXml, encodeText, decodeXmlText, XML_DECLARATION } from '../xml/dom.mjs';
-import { log } from '../model/properties/log.mjs';
+import { parseXml, serializeXml, encodeText, decodeXmlText, XML_DECLARATION, assertXmlCharacters } from '../xml/dom.mjs';
 import { bindSnapshot, boundsOf } from '../model/content/binder.mjs';
-const XMLNS_NS = 'http://www.w3.org/2000/xmlns/';
-const MC_NS = Namespaces.MARKUP_COMPATIBILITY;
-/** The objects package's prefix table the other way round, prefix to URI, built once. */
-let prefixToUri;
-function knownUriOf(prefix) {
-    if (prefixToUri === undefined) {
-        prefixToUri = new Map();
-        for (const [uri, p] of Object.entries(NAMESPACE_PREFIXES))
-            if (p !== '' && !prefixToUri.has(p))
-                prefixToUri.set(p, uri);
-    }
-    return prefixToUri.get(prefix);
-}
-const warnedPrefixes = new Set();
+import { repairBreaksOutsideRuns } from '../opc/repair/breaks.mjs';
+import { readThroughUnknownElements } from '../opc/repair/unknownElements.mjs';
+import { skippedAttribute, skippedElement, skippedText } from '../opc/skipped.mjs';
+import { rangeOf, describeReading, UNMEASURED_RANGE } from '../model/wordIntegers.mjs';
 /**
  * The element or attribute a located runtime error names, out of its message: jsonix writes
  * `w:sz/@w:val (line 7): ...` when it could place the fault and `w:bogus (line 3): ...` for an
@@ -39,6 +27,96 @@ function positionOf(line, column) {
         return '';
     return column === undefined ? ` (line ${line})` : ` (line ${line}, column ${column})`;
 }
+/** A value the objects facade read by Word's rule, as a warning on the part (CR-015 D8). */
+function valueKept(reading, partName) {
+    var _a, _b, _c;
+    const node = reading.element;
+    const name = reading.attribute;
+    const attribute = (_c = (_b = (_a = node.getAttributeNodeNS) === null || _a === void 0 ? void 0 : _a.call(node, name.namespaceURI || null, name.localPart)) === null || _b === void 0 ? void 0 : _b.name) !== null && _c !== void 0 ? _c : name.localPart;
+    const value = reading.value;
+    const read = value === true ? 'on' : value === undefined ? 'absent' : JSON.stringify(value);
+    // a form Word refuses a document for is dropped (the objects package's CR-015; CR-017 P1)
+    const outcome = reading.kind === 'value.refused' ? 'dropped: Word 365 refuses a document with this value' : `read as ${read}, as Word 365 reads it`;
+    return {
+        code: reading.kind, partName,
+        ...(typeof node.lineNumber === 'number' ? { line: node.lineNumber } : {}),
+        ...(typeof node.columnNumber === 'number' ? { column: node.columnNumber } : {}),
+        element: node.nodeName, attribute, text: reading.text, value,
+        message: `${partName}: ${node.nodeName}/@${attribute}=${JSON.stringify(reading.text)}${positionOf(node.lineNumber, node.columnNumber)} is not a value its type allows; ${outcome}`,
+    };
+}
+/**
+ * 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 function valueOutOfRange(report, partName) {
+    var _a, _b, _c;
+    const node = report.element;
+    const name = report.attribute;
+    const attribute = (_c = (_b = (_a = node.getAttributeNodeNS) === null || _a === void 0 ? void 0 : _a.call(node, name.namespaceURI || null, name.localPart)) === null || _b === void 0 ? void 0 : _b.name) !== null && _c !== void 0 ? _c : `w:${name.localPart}`;
+    const reading = report.wordReads;
+    const unmeasured = !report.storage.measured;
+    // the rule beside a line or a height (`report.rule`, from the tree) decides what Word keeps there
+    const range = rangeOf(report.storage, report.property, report.rule);
+    const at = report.path !== undefined ? `${report.path}=${report.value}` : `${node.nodeName}/@${attribute}=${report.value}${positionOf(node.lineNumber, node.columnNumber)}`;
+    const where = unmeasured
+        ? `is outside ${UNMEASURED_RANGE[0]} to ${UNMEASURED_RANGE[1]}, where Word 365 changes every measured value of its kind (${node.nodeName}/@${attribute} is unmeasured); what Word reads is not known`
+        : `is past what Word 365 stores there (${reading.storage}${range ? `, ${range[0]} to ${range[1]}` : ''}); Word reads it as ${describeReading(reading, name.localPart)}`;
+    const prefix = partName === undefined ? '' : `${partName}: `;
+    return {
+        code: 'value.out_of_range', partName,
+        ...(report.path === undefined && typeof node.lineNumber === 'number' ? { line: node.lineNumber } : {}),
+        ...(report.path === undefined && typeof node.columnNumber === 'number' ? { column: node.columnNumber } : {}),
+        ...(report.path !== undefined ? { path: report.path } : {}),
+        element: node.nodeName, attribute, value: report.value, wordReads: reading.value,
+        ...(reading.attribute !== undefined && reading.attribute !== name.localPart ? { readAs: `w:${reading.attribute}` } : {}),
+        ...(reading.rule !== undefined ? { rule: reading.rule } : {}),
+        storage: reading.storage, range,
+        message: `${prefix}${at} ${where}`,
+    };
+}
+/** The last segment of an objects `TYPE_NAME`, docx4j's class name: `org_docx4j_wml.R` is `R`. */
+const className = (typeName) => typeName.slice(typeName.lastIndexOf('.') + 1);
+/**
+ * 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 function misplacedContent(report, partName) {
+    var _a;
+    const container = report.element;
+    const located = (_a = report.childElement) !== null && _a !== void 0 ? _a : container;
+    const isText = report.child === '#text';
+    const element = isText ? undefined : qualifiedName(report.child);
+    const onRead = report.path === undefined;
+    const line = onRead && typeof located.lineNumber === 'number' ? located.lineNumber : undefined;
+    const column = onRead && typeof located.columnNumber === 'number' ? located.columnNumber : undefined;
+    const shown = report.text === undefined ? '' : ` ${JSON.stringify(report.text.length > 80 ? `${report.text.slice(0, 80)}...` : report.text)}`;
+    const at = onRead
+        ? `${container.nodeName}${report.via === undefined ? '' : `/${report.via}`}, child ${report.index} (${element !== null && element !== void 0 ? element : 'a string'}${shown})${positionOf(line, column)}`
+        : report.path;
+    const prefix = partName === undefined ? '' : `${partName}: `;
+    return {
+        code: 'target.misplaced', partName,
+        ...(line !== undefined ? { line } : {}),
+        ...(column !== undefined ? { column } : {}),
+        ...(onRead ? {} : { path: report.path }),
+        holder: className(report.container), index: report.index,
+        ...(report.childType !== undefined ? { item: className(report.childType) } : {}),
+        ...(element !== undefined ? { element } : {}),
+        rule: report.rule,
+        ...(report.text !== undefined ? { text: report.text } : {}),
+        message: `${prefix}${at}: ${report.message}`,
+    };
+}
+/** `w:tbl` for a child's name: its prefix as the report has it, else the objects package's for the namespace. */
+function qualifiedName(name) {
+    var _a;
+    const prefix = (_a = name.prefix) !== null && _a !== void 0 ? _a : NAMESPACE_PREFIXES[name.namespaceURI];
+    return prefix ? `${prefix}:${name.localPart}` : name.localPart;
+}
 /** The objects package's prefix table as XPath wants it, prefix to URI; built once. */
 const NAMESPACE_PREFIXES_BY_PREFIX = (() => {
     const out = {};
@@ -75,9 +153,14 @@ export class XmlPart extends Part {
         return this.element === undefined && this.bytes === undefined;
     }
     /**
-     * What the preprocessor reported the last time this part was parsed (CR-010 phase 1): an
-     * mc:AlternateContent whose branches' text differs (`mce.branches_differ`). Empty until the part
-     * is parsed, by `getContents()` or a private read, and again once its contents are set.
+     * What the last parse of this part reported: an mc:AlternateContent whose branches' text differs
+     * (`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() {
         return this.parseWarnings;
@@ -97,10 +180,10 @@ export class XmlPart extends Part {
         var _a, _b;
         if (this.element === undefined) {
             const bytes = (_a = this.bytes) !== null && _a !== void 0 ? _a : (await this.loadSourceBytes());
+            this.parsedBytes = this.bytes;
             if (bytes === undefined)
                 throw new Docx4JException(`Part ${this.partName} has no content: set contents or load it from a container`);
             const doc = this.parse(bytes);
-            this.recordDeclarations(doc);
             this.preprocess(doc);
             this.element = await this.unmarshal(doc);
             (_b = this.rootName) !== null && _b !== void 0 ? _b : (this.rootName = { namespaceURI: this.element.name.namespaceURI, localPart: this.element.name.localPart });
@@ -118,21 +201,61 @@ export class XmlPart extends Part {
      * reads the styles and numbering parts of a document nobody has otherwise touched.
      */
     async readContents() {
+        return (await this.readElement()).value;
+    }
+    /** `readContents`'s typed element: the live one, else a private tree from the part's bytes. */
+    async readElement() {
         var _a;
         if (this.element !== undefined)
-            return this.element.value;
+            return this.element;
         const bytes = (_a = this.bytes) !== null && _a !== void 0 ? _a : (await this.loadSourceBytes());
         if (bytes === undefined)
             throw new Docx4JException(`Part ${this.partName} has no content: set contents or load it from a container`);
         const doc = this.parse(bytes);
-        this.recordDeclarations(doc);
         this.preprocess(doc);
-        return (await this.unmarshal(doc)).value;
+        return this.unmarshal(doc);
+    }
+    /**
+     * 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.
+     */
+    async checkContent() {
+        const element = await this.readElement();
+        const out = [];
+        try {
+            await marshalNode(element, { onMisplaced: (report) => out.push(misplacedContent(report, this.partName.name)) });
+        }
+        catch (cause) {
+            // the runtime refuses to write what the walk reported (a string in a run); with nothing reported, the fault is another
+            if (out.length === 0)
+                throw new Docx4JException(`Part ${this.partName}: its content cannot be written`, { cause });
+        }
+        return out;
     }
+    /**
+     * 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.
+     */
     preprocess(doc) {
+        this.parseWarnings = this.preprocessed(doc);
+    }
+    /**
+     * 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.
+     */
+    readRoot(_doc) {
+        return [];
+    }
+    preprocessed(doc) {
         var _a;
+        const rooted = this.readRoot(doc);
+        // ahead of CR-021's, which then gives a w:br the element held a run, as Word does (`76t42`)
+        const read = readThroughUnknownElements(doc, this.partName.name);
+        const repaired = repairBreaksOutsideRuns(doc, this.partName.name);
         const warnings = (_a = this.preprocessor) === null || _a === void 0 ? void 0 : _a.call(this, doc, this);
-        this.parseWarnings = warnings ? [...warnings] : [];
+        return [...rooted, ...read, ...repaired, ...(warnings !== null && warnings !== void 0 ? warnings : [])];
     }
     /** Replaces the contents (docx4j setJaxbElement / setContents). The root name defaults to the part's. */
     setContents(value, rootName) {
@@ -142,12 +265,58 @@ export class XmlPart extends Part {
             throw new Docx4JException(`Part ${this.partName}: no root element name; pass one`);
         this.element = { name: { namespaceURI: name.namespaceURI, localPart: name.localPart }, value };
         this.bytes = undefined;
+        this.parsedBytes = undefined;
         this.parseWarnings = [];
     }
     /** Replaces the contents with raw XML bytes; they are unmarshalled on the next getContents(). */
     setBytes(bytes) {
         this.bytes = bytes;
         this.element = undefined;
+        this.parsedBytes = undefined;
+    }
+    /** What the read of the tree held now dropped (CR-025): nothing for a part not unmarshalled, or given contents. */
+    get skippedByRead() {
+        if (this.element === undefined)
+            return [];
+        return this.parseWarnings.filter((w) => w.code === 'part.skipped');
+    }
+    /** The bytes the tree held now was read from. */
+    async bytesRead() {
+        var _a;
+        return (_a = this.parsedBytes) !== null && _a !== void 0 ? _a : this.loadSourceBytes();
+    }
+    /**
+     * 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.
+     */
+    async isUnchangedSinceRead() {
+        var _a;
+        if (this.element === undefined)
+            return true;
+        const bytes = await this.bytesRead();
+        if (bytes === undefined)
+            return false;
+        const marshal = {};
+        const normalise = (_a = this.package) === null || _a === void 0 ? void 0 : _a.normaliseOnSave;
+        if (normalise !== undefined)
+            marshal.normaliseOnSave = normalise;
+        try {
+            const doc = this.parse(bytes);
+            this.preprocessed(doc);
+            // read with the read's callbacks, their reports discarded: without onUnexpectedElement the runtime refuses an unknown
+            // element in the hosts route B skips it in (CR-026), and the part would count as changed
+            const ignore = () => { };
+            const source = await unmarshalNode(doc, {
+                onWordReading: ignore, onOutOfRange: ignore, onMisplaced: ignore,
+                onUnexpectedElement: ignore, onUnexpectedAttribute: ignore, onUnexpectedText: ignore,
+            });
+            return serializeXml(await marshalNode(source, marshal))
+                === serializeXml(await marshalNode(this.element, marshal));
+        }
+        catch {
+            return false;
+        }
     }
     /** Replaces the contents with XML text (docx4j setContents from a string). */
     setXml(xml) {
@@ -158,9 +327,9 @@ export class XmlPart extends Part {
         return decodeXmlText(await this.getBytes());
     }
     /** Marshalled bytes when unmarshalled or set, else the source bytes untouched. */
-    async getBytes() {
+    async getBytes(options) {
         if (this.element !== undefined)
-            return encodeText(XML_DECLARATION + serializeXml(await this.marshalToNode()));
+            return encodeText(assertXmlCharacters(XML_DECLARATION + serializeXml(await this.marshalToNode(options)), `Part ${this.partName}`));
         if (this.bytes !== undefined)
             return this.bytes;
         const loaded = await this.loadSourceBytes();
@@ -198,13 +367,26 @@ export class XmlPart extends Part {
         const namespaces = { ...NAMESPACE_PREFIXES_BY_PREFIX, ...options.namespaces };
         return boundsOf(engine.select(xpath, snapshot.root, namespaces), snapshot);
     }
-    /** The root element as a DOM element (docx4j XmlUtils.marshaltoW3CDomDocument). */
-    async marshalToNode() {
+    /**
+     * 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.
+     */
+    async marshalToNode(options) {
+        var _a;
         if (this.element === undefined)
             await this.getContents();
-        const root = await marshalNode(this.element);
-        this.declareIgnorablePrefixes(root);
-        return root;
+        const marshal = {};
+        const normalise = (_a = this.package) === null || _a === void 0 ? void 0 : _a.normaliseOnSave;
+        if (normalise !== undefined)
+            marshal.normaliseOnSave = normalise;
+        if ((options === null || options === void 0 ? void 0 : options.onNormalised) !== undefined)
+            marshal.onNormalised = options.onNormalised;
+        if ((options === null || options === void 0 ? void 0 : options.onOutOfRange) !== undefined)
+            marshal.onOutOfRange = options.onOutOfRange; // the report carries its rule (objects 0.7.0)
+        if ((options === null || options === void 0 ? void 0 : options.onMisplaced) !== undefined)
+            marshal.onMisplaced = options.onMisplaced;
+        return marshalNode(this.element, marshal);
     }
     /**
      * Parses the part's bytes, and names the part when the XML is not well-formed. xmldom's error
@@ -236,8 +418,33 @@ export class XmlPart extends Part {
      */
     async unmarshal(doc) {
         var _a, _b, _c, _d, _e, _f;
+        const kept = [];
+        const partName = this.partName.name;
+        // A string CR-016's walk reports as misplaced isn't reported twice: that walk runs after the text's own callback.
+        const textHolders = new Map();
+        const misplacedStrings = new Set();
         try {
-            return await unmarshalNode(doc);
+            const element = await unmarshalNode(doc, {
+                onWordReading: (reading) => kept.push(valueKept(reading, partName)),
+                onOutOfRange: (report) => kept.push(valueOutOfRange(report, partName)),
+                onMisplaced: (report) => {
+                    kept.push(misplacedContent(report, partName));
+                    if (report.child === '#text')
+                        misplacedStrings.add(report.element);
+                },
+                // What the read drops (CR-025). These stay at this one call: objects CR-007 keeps them per call.
+                onUnexpectedElement: (_name, node, classInfo) => kept.push(skippedElement(node, partName, classInfo.name)),
+                onUnexpectedAttribute: (name, node, classInfo) => kept.push(skippedAttribute(name, node, partName, classInfo.name)),
+                onUnexpectedText: (text, node, classInfo) => {
+                    const skipped = skippedText(text, node, partName, classInfo.name);
+                    textHolders.set(skipped, node.parentNode);
+                    kept.push(skipped);
+                },
+            });
+            const reported = kept.filter((w) => !(w.code === 'part.skipped' && misplacedStrings.has(textHolders.get(w))));
+            if (reported.length > 0)
+                this.parseWarnings = [...this.parseWarnings, ...reported];
+            return element;
         }
         catch (cause) {
             const located = cause;
@@ -256,67 +463,4 @@ export class XmlPart extends Part {
             throw new PartUnmarshalException(`${this.partName}: ${detail}`, this.partName.name, { cause, location, line, column });
         }
     }
-    /** The source root element's namespace declarations, prefix to URI (`xmlns=` is the empty prefix). */
-    recordDeclarations(doc) {
-        var _a;
-        const root = doc.documentElement;
-        if (!root)
-            return;
-        const map = new Map();
-        for (const attr of Array.from(root.attributes)) {
-            if (attr.name === 'xmlns')
-                map.set('', attr.value);
-            else if (attr.namespaceURI === XMLNS_NS || attr.name.startsWith('xmlns:'))
-                map.set((_a = attr.localName) !== null && _a !== void 0 ? _a : attr.name.slice(6), attr.value);
-        }
-        this.sourceDeclarations = map;
-    }
-    /**
-     * 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.
-     */
-    declareIgnorablePrefixes(root) {
-        var _a, _b;
-        const attr = Array.from(root.attributes).find((a) => { var _a; return a.namespaceURI === MC_NS && ((_a = a.localName) !== null && _a !== void 0 ? _a : a.name) === 'Ignorable'; });
-        if (!attr)
-            return;
-        const prefixes = attr.value.split(/\s+/).filter((p) => p !== '');
-        if (prefixes.length === 0)
-            return;
-        const kept = [];
-        let dropped = false;
-        for (const prefix of prefixes) {
-            if (root.getAttributeNS(XMLNS_NS, prefix) || root.getAttribute(`xmlns:${prefix}`)) {
-                kept.push(prefix);
-                continue;
-            }
-            const uri = (_b = (_a = this.sourceDeclarations) === null || _a === void 0 ? void 0 : _a.get(prefix)) !== null && _b !== void 0 ? _b : knownUriOf(prefix);
-            if (uri === undefined) {
-                dropped = true;
-                if (!warnedPrefixes.has(prefix)) {
-                    warnedPrefixes.add(prefix);
-                    log.warn(`${this.partName}: mc:Ignorable names the prefix "${prefix}", which nothing declares; dropping it (an undeclared prefix makes Word and Excel offer to repair the file)`);
-                }
-                continue;
-            }
-            root.setAttributeNS(XMLNS_NS, `xmlns:${prefix}`, uri);
-            kept.push(prefix);
-        }
-        if (!dropped)
-            return;
-        if (kept.length === 0)
-            root.removeAttributeNode(attr);
-        else
-            root.setAttributeNS(MC_NS, attr.name, kept.join(' '));
-    }
 }

package/dist/parts/wml/comments.mjs

@@ -47,6 +47,36 @@ class DocumentCommentParts {
         this.loadedAll = true;
         return this;
     }
+    async loadExisting() {
+        var _a, _b, _c;
+        const main = this.main;
+        if (main.commentsExtendedPart)
+            (_a = this.commentsEx) !== null && _a !== void 0 ? _a : (this.commentsEx = await main.commentsExtendedPart.getContents());
+        if (main.commentsIdsPart)
+            (_b = this.commentsIds) !== null && _b !== void 0 ? _b : (this.commentsIds = await main.commentsIdsPart.getContents());
+        (_c = this.extensible) !== null && _c !== void 0 ? _c : (this.extensible = await loadExtensible(main));
+        return this;
+    }
+    drop(people) {
+        var _a, _b;
+        const main = this.main;
+        const parts = [main.commentsPart, main.commentsExtendedPart, main.commentsIdsPart, main.commentsExtensiblePart, people ? main.peoplePart : undefined];
+        for (const part of parts) {
+            if (!part)
+                continue;
+            const rels = main.relationshipsPart;
+            const rel = rels === null || rels === void 0 ? void 0 : rels.getRel(part.partName);
+            if (rel)
+                rels.removeRelationship(rel);
+            if (part.sourceRelationships.length > 0)
+                continue;
+            (_a = part.relationshipsPart) === null || _a === void 0 ? void 0 : _a.removeParts();
+            (_b = part.package) === null || _b === void 0 ? void 0 : _b.parts.remove(part.partName);
+        }
+        main.commentsPart = main.commentsExtendedPart = main.commentsIdsPart = main.commentsExtensiblePart = undefined;
+        if (people)
+            main.peoplePart = undefined;
+    }
 }
 /** The document part a body's comments belong to: the body's own part, else the package's main part. */
 function mainPartOf(body) {

package/dist/parts/wml/index.d.mts

@@ -9,6 +9,7 @@ import { PartName } from '../../opc/PartName.mjs';
 import { DefaultXmlPart } from '../DefaultXmlPart.mjs';
 import { ThemePart } from '../dml/index.mjs';
 import { Body } from '../../model/content/Body.mjs';
+import type { PartWarning } from '../../opc/mce/preprocessor.mjs';
 import type { AbstractListDefinition, ListDefinition } from '../../model/listnumbering/definitions.mjs';
 import { NumberingDefinitions } from '../../model/listnumbering/definitions.mjs';
 import { Emulator } from '../../model/listnumbering/Emulator.mjs';
@@ -44,7 +45,17 @@ export declare class MainDocumentPart extends DocumentPart<wml.Document> {
     glossaryDocumentPart: GlossaryDocumentPart | undefined;
     constructor(partName?: PartName | string, contentType?: string);
     setPartShortcut(part: Part, relationshipType: string): boolean;
-    /** The Office JS-shaped view of `w:body`; the part must be unmarshalled (`getBody()` does that). */
+    /**
+     * The root's qualified name where it is one Word opens showing nothing of (WD REQ-320, CR-028 D11), read as an empty
+     * document; undefined for a `w:document`, a root read as one, or contents a caller set.
+     */
+    get unexpectedRoot(): string | undefined;
+    protected readRoot(doc: Document): readonly PartWarning[];
+    /**
+     * The Office JS-shaped view of `w:body`; the part must be unmarshalled (`getBody()` does that). Refused where the root is one
+     * Word shows nothing of, or `mc:AlternateContent` (CR-028 D10): either reads as no document here, and a write there would go
+     * nowhere a save keeps.
+     */
     get body(): Body;
     getBody(): Promise<Body>;
     private fontSelector;

package/dist/parts/wml/index.mjs

@@ -5,6 +5,7 @@ import { DefaultXmlPart } from '../DefaultXmlPart.mjs';
 import { ThemePart } from '../dml/index.mjs';
 import { Body } from '../../model/content/Body.mjs';
 import { Docx4JException } from '../../opc/exceptions.mjs';
+import { readMainPartRoot } from '../../opc/repair/mainRoot.mjs';
 import { NumberingDefinitions } from '../../model/listnumbering/definitions.mjs';
 import { Emulator } from '../../model/listnumbering/Emulator.mjs';
 import { DEFAULT_NUMBERING_XML } from './defaultNumbering.mjs';
@@ -23,6 +24,15 @@ async function ensurePropertyResolver(part) {
     const pkg = part.package;
     await ((_a = pkg === null || pkg === void 0 ? void 0 : pkg.getPropertyResolver) === null || _a === void 0 ? void 0 : _a.call(pkg));
 }
+/**
+ * The glossary's placeholder entries, read privately, which `ContentControl.placeholderText` reads synchronously
+ * (CR-002 section 63, D8).
+ */
+async function ensureGlossaryEntries(part) {
+    var _a, _b;
+    const pkg = part.package;
+    await ((_a = pkg === null || pkg === void 0 ? void 0 : pkg.glossaryEntries) === null || _a === void 0 ? void 0 : _a.load((_b = pkg.mainDocumentPart) === null || _b === void 0 ? void 0 : _b.glossaryDocumentPart));
+}
 /** The Body view of a part's block-level container, one per container object. */
 function bodyOf(part, container, prefix) {
     if (!container)
@@ -114,16 +124,40 @@ export class MainDocumentPart extends DocumentPart {
         }
         return super.setPartShortcut(part, relationshipType);
     }
-    /** The Office JS-shaped view of `w:body`; the part must be unmarshalled (`getBody()` does that). */
+    /**
+     * The root's qualified name where it is one Word opens showing nothing of (WD REQ-320, CR-028 D11), read as an empty
+     * document; undefined for a `w:document`, a root read as one, or contents a caller set.
+     */
+    get unexpectedRoot() {
+        var _a;
+        return (_a = this.warnings.find((w) => w.code === 'part.unexpected_root')) === null || _a === void 0 ? void 0 : _a.root;
+    }
+    readRoot(doc) {
+        return readMainPartRoot(doc, this.partName.name);
+    }
+    /**
+     * The Office JS-shaped view of `w:body`; the part must be unmarshalled (`getBody()` does that). Refused where the root is one
+     * Word shows nothing of, or `mc:AlternateContent` (CR-028 D10): either reads as no document here, and a write there would go
+     * nowhere a save keeps.
+     */
     get body() {
         var _a;
         const doc = this.contents;
+        const unexpected = this.unexpectedRoot;
+        if (unexpected !== undefined) {
+            throw new Docx4JException(`${this.partName}: its root is ${unexpected}, which Word opens showing nothing of (WD REQ-320), so it has no body to read or write`);
+        }
+        if (doc.TYPE_NAME === 'org_docx4j_mce.AlternateContent') {
+            // the branch isn't read as the document yet (WD REQ-317), so a body added here would go nowhere a save writes (CR-028 D10)
+            throw new Docx4JException(`${this.partName}: its root is mc:AlternateContent, whose branch this package doesn't yet read as the document (WD REQ-317), so it has no body to read or write`);
+        }
         (_a = doc.body) !== null && _a !== void 0 ? _a : (doc.body = { TYPE_NAME: 'org_docx4j_wml.Body' });
         return bodyOf(this, doc.body, 'body');
     }
     async getBody() {
         await this.getContents();
         await ensurePropertyResolver(this);
+        await ensureGlossaryEntries(this);
         return this.body;
     }
     /**
@@ -439,6 +473,7 @@ export class HeaderPart extends XmlPart {
     async getBody() {
         await this.getContents();
         await ensurePropertyResolver(this);
+        await ensureGlossaryEntries(this);
         return this.body;
     }
 }
@@ -454,6 +489,7 @@ export class FooterPart extends XmlPart {
     async getBody() {
         await this.getContents();
         await ensurePropertyResolver(this);
+        await ensureGlossaryEntries(this);
         return this.body;
     }
 }

package/dist/xml/dom.d.mts

@@ -14,6 +14,13 @@ export declare function parseXml(text: string): Document;
 /** Serialises a node (document or element) without an XML declaration. */
 export declare function serializeXml(node: Node): string;
 export declare function createDocument(): Document;
+/**
+ * The XML, refused where it holds a character XML 1.0 excludes, which no escape can write (CR-002 section 60 D3): the
+ * part would not be well-formed, and a conforming parser must refuse it. The content API's writers drop such characters
+ * or write them as their elements; this catches what reached the tree some other way (an attribute, a custom XML
+ * node's value, a caller's own edit of the tree).
+ */
+export declare function assertXmlCharacters(xml: string, where: string): string;
 /** XML declaration plus the serialised document element, as one string. */
 export declare function serializeXmlPart(node: Node): string;
 /** UTF-8 bytes of a string. */

package/dist/xml/dom.mjs

@@ -59,6 +59,24 @@ export function serializeXml(node) {
 export function createDocument() {
     return DOM.createDocument();
 }
+/** A character XML 1.0 excludes: a C0 control but tab, line feed and carriage return, U+FFFE, U+FFFF, an unpaired surrogate. */
+const NOT_XML = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\uFFFE\uFFFF]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+/**
+ * The XML, refused where it holds a character XML 1.0 excludes, which no escape can write (CR-002 section 60 D3): the
+ * part would not be well-formed, and a conforming parser must refuse it. The content API's writers drop such characters
+ * or write them as their elements; this catches what reached the tree some other way (an attribute, a custom XML
+ * node's value, a caller's own edit of the tree).
+ */
+export function assertXmlCharacters(xml, where) {
+    const m = NOT_XML.exec(xml);
+    if (m) {
+        const code = m[0].charCodeAt(0).toString(16).toUpperCase().padStart(4, '0');
+        const before = xml.slice(Math.max(0, m.index - 40), m.index).replace(/[^\x20-\x7e]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+        throw new Docx4JException(`${where} holds U+${code}, which XML 1.0 excludes, so it can't be written as well-formed XML `
+            + `(character ${m.index}, after "${before}"); remove it, or write it as the element it stands for (CR-002 section 60)`);
+    }
+    return xml;
+}
 /** XML declaration plus the serialised document element, as one string. */
 export function serializeXmlPart(node) {
     const el = node.nodeType === 9 ? node.documentElement : node;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docx4j/core-ts",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "docx4j-core for TypeScript: Open Packaging (docx/pptx/xlsx zip and flat OPC), typed parts and relationships, style, numbering and font resolution over @docx4j/generated-objects-ts. Node, browsers, Word add-ins.",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -83,7 +83,7 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
-    "@docx4j/generated-objects-ts": "^0.4.2",
+    "@docx4j/generated-objects-ts": "^0.8.0",
     "fflate": "^0.8.2"
   },
   "devDependencies": {