@docx4j/core-ts 0.5.0 → 0.6.0

package/dist/opc/mce/understood.mjs

@@ -137,13 +137,43 @@ export const UNDERSTOOD_NAMESPACES = new Set([
     'http://schemas.microsoft.com/office/drawing/2015/9/8/chartex',
     'http://schemas.microsoft.com/office/drawing/2015/10/21/chartex',
 ]);
+const prefixesOf = (namespaces) => [...namespaces].map((uri) => NAMESPACE_PREFIXES[uri]).filter((prefix) => prefix !== undefined && prefix !== '');
 /**
- * The conventional prefixes of `UNDERSTOOD_NAMESPACES` (`NAMESPACE_PREFIXES`), which is what a reader of a
- * kept mc:AlternateContent matches `mc:Choice/@Requires` against (CR-010 section 11.5): the unmarshalled
- * model does not keep the declarations in force at the element, so the objects package's `mcBranchOf`
- * compares prefixes, and its default set, every prefix `NAMESPACE_PREFIXES` knows, is wider than what
- * load understands. Through this set a reader takes the branch the preprocessor would have resolved to,
- * wherever the document writes the conventional prefixes. An understood namespace with no conventional
+ * The conventional prefixes of `UNDERSTOOD_NAMESPACES` (`NAMESPACE_PREFIXES`), the object model's namespaces
+ * expressed as prefixes (CR-010 section 11.5): the unmarshalled model does not keep the declarations in
+ * force at the element, so the objects package's `mcBranchOf` compares prefixes, and its default set,
+ * every prefix `NAMESPACE_PREFIXES` knows, is wider than what load understands. The readers match
+ * against `READ_UNDERSTOOD_PREFIXES`, this and four more. An understood namespace with no conventional
  * prefix has no entry.
  */
-export const UNDERSTOOD_PREFIXES = new Set([...UNDERSTOOD_NAMESPACES].map((uri) => NAMESPACE_PREFIXES[uri]).filter((prefix) => prefix !== undefined && prefix !== ''));
+export const UNDERSTOOD_PREFIXES = new Set(prefixesOf(UNDERSTOOD_NAMESPACES));
+/**
+ * The namespaces a reader of a kept mc:AlternateContent counts as understood beyond `UNDERSTOOD_NAMESPACES`
+ * (CR-010 section 15): Word 365 takes a Choice requiring any of them (measured 2026-10-20), and docx4j's
+ * published understood list (`understood-namespaces.txt`) has all four, among the 11 its JAXB contexts
+ * bind and no generated module here does. The name is CR-010's, when only the readers counted them;
+ * since CR-013 (D3) resolving does too (`READ_UNDERSTOOD_NAMESPACES`). Resolving turns the Choice it takes
+ * into typed content, which no module types here, but what Word writes in these namespaces survives a
+ * re-marshal: in every file seen it is attributes only (`w16du:dateUtc`, `w16sdtdh:storeItemChecksum`,
+ * `x14ac:dyDescent` and `x14ac:knownFonts`; `w16sdtfl` is only declared), measured 2026-10-21.
+ */
+export const READ_ONLY_UNDERSTOOD_NAMESPACES = new Set([
+    'http://schemas.microsoft.com/office/word/2020/wordml/sdtdatahash', // w16sdtdh
+    'http://schemas.microsoft.com/office/word/2024/wordml/sdtformatlock', // w16sdtfl
+    'http://schemas.microsoft.com/office/word/2023/wordml/word16du', // w16du
+    'http://schemas.microsoft.com/office/spreadsheetml/2009/9/ac', // x14ac
+]);
+/**
+ * What a reader of a kept mc:AlternateContent matches `mc:Choice/@Requires` against (`selectedBranchOf`,
+ * docx4j's `McMode.READ`): `UNDERSTOOD_PREFIXES` and the conventional prefixes of
+ * `READ_ONLY_UNDERSTOOD_NAMESPACES`. A Choice requiring only these is taken by the gate alone, as REQ-302
+ * of the text extraction specification reads, whatever its content (CR-010 section 15).
+ */
+export const READ_UNDERSTOOD_PREFIXES = new Set([...UNDERSTOOD_PREFIXES, ...prefixesOf(READ_ONLY_UNDERSTOOD_NAMESPACES)]);
+/**
+ * What load selects by, as namespaces: `UNDERSTOOD_NAMESPACES` and `READ_ONLY_UNDERSTOOD_NAMESPACES`, the
+ * readers' set (`READ_UNDERSTOOD_PREFIXES`) by URI. Resolving (`mcePreprocess: true`) takes the Choice it
+ * names, and the default load's `mce.branches_differ` reports it as the selected branch, so a resolved load
+ * takes the branch the readers of a kept load take, as Word 365 does (CR-013 D3).
+ */
+export const READ_UNDERSTOOD_NAMESPACES = new Set([...UNDERSTOOD_NAMESPACES, ...READ_ONLY_UNDERSTOOD_NAMESPACES]);

package/dist/packages/OpcPackage.d.mts

@@ -4,6 +4,7 @@ import { ContentTypeManager } from '../opc/ContentTypeManager.mjs';
 import { type PartStore, type PartSink } from '../opc/PartStore.mjs';
 import { type FlatOpcSinkOptions } from '../opc/FlatOpcPartStore.mjs';
 import { type LoadOptions } from '../opc/Load.mjs';
+import { type SaveReport } from '../opc/Save.mjs';
 import { Part, type RelationshipSource } from '../parts/Part.mjs';
 import { Parts } from '../parts/Parts.mjs';
 import { RelationshipsPart, type AddPartBehaviour } from '../parts/RelationshipsPart.mjs';
@@ -31,6 +32,18 @@ export declare class OpcPackage implements RelationshipSource {
     docPropsCorePart: DocPropsCorePart | undefined;
     docPropsExtendedPart: DocPropsExtendedPart | undefined;
     docPropsCustomPart: DocPropsCustomPart | undefined;
+    /**
+     * Whether a save writes run properties in their normal form (CR-015 D2; docx4j CR-061's
+     * `setNormaliseOnSave`): a colour Word accepts as upper-case `RRGGBB`, one it rejects left out (a text or
+     * underline colour) or `auto` (a fill's, a border's), a `w:highlight`, `w:vertAlign` or `w:em` Word repairs away
+     * left out; a revision's former properties too. Only what is written changes: the tree keeps what it read, and a
+     * part nobody unmarshalled is still copied byte for byte. Undefined defers to the objects package's process-wide
+     * `setNormaliseOnSave` (on unless set off); a package's own setting wins over it. False writes values as read.
+     * On/off values and `w:u`'s are settled when the part is read, so they are written the same either way.
+     */
+    normaliseOnSave: boolean | undefined;
+    /** What the last save did beyond writing the package: each value it normalised (CR-015 D8). Undefined until one. */
+    lastSave: SaveReport | undefined;
     constructor();
     get package(): OpcPackage;
     /**

package/dist/packages/OpcPackage.mjs

@@ -135,6 +135,7 @@ export class OpcPackage {
         if (copy.constructor !== this.constructor) {
             throw new Docx4JException(`Cloning ${this.constructor.name} produced ${copy.constructor.name}`);
         }
+        copy.normaliseOnSave = this.normaliseOnSave;
         this.copyPackageSettingsTo(copy);
         return copy;
     }

package/dist/packages/WordprocessingMLPackage.d.mts

@@ -4,6 +4,7 @@ import type { Part } from '../parts/Part.mjs';
 import { MainDocumentPart, StyleDefinitionsPart, type NumberingDefinitionsPart } from '../parts/wml/index.mjs';
 import { type FontSettings, type DefaultThemeValue } from '../model/fonts/defaultTheme.mjs';
 import { Body, type Address, type Outline, type OutlineParagraph, type OutlineTable } from '../model/content/Body.mjs';
+import { type TrackedChangeSelection } from '../model/content/trackedChangeFilter.mjs';
 import type { Paragraph } from '../model/content/Paragraph.mjs';
 import type { Author } from '../model/content/comments.mjs';
 import { CustomXmlPartCollection } from '../model/customxml/CustomXmlPartCollection.mjs';
@@ -11,6 +12,7 @@ import { type XPathEngine } from '../model/customxml/xpath.mjs';
 import { ChangeTracker, type ChangeTrackingMode, type TrackingHost, type TrackingScope } from '../model/content/tracking.mjs';
 import { NumberingFacade } from '../model/content/List.mjs';
 import { StylesFacade } from '../model/content/stylesFacade.mjs';
+import { GlossaryEntries } from '../model/content/placeholders.mjs';
 import type { Bound } from '../model/content/binder.mjs';
 import { PropertyResolver } from '../model/properties/PropertyResolver.mjs';
 import type { Emulator } from '../model/listnumbering/Emulator.mjs';
@@ -19,6 +21,9 @@ import { type RelationshipRemovals } from '../model/content/relationships.mjs';
 import { XmlPart } from '../parts/XmlPart.mjs';
 import type { PartSink } from '../opc/PartStore.mjs';
 import '../parts/wml/comments.mjs';
+import '../model/text/outline.mjs';
+import type { TextContext } from '../model/text/TextContext.mjs';
+import type { TextOptions, TextOptionsInit } from '../model/text/TextOptions.mjs';
 /** The outline of a document: the body's paragraphs and tables, then each header's and footer's (loaded ones only). */
 export interface DocumentOutline extends Outline {
     headers: {
@@ -102,6 +107,12 @@ export declare class WordprocessingMLPackage extends OpcPackage implements Track
      * 47). Settled on save, not at once, so a picture cut and pasted back keeps its image. An extension.
      */
     readonly pendingRelationshipRemovals: RelationshipRemovals;
+    /**
+     * The glossary's placeholder entries: read privately when a body is first read (`getBody`, `Word.run`), and those a
+     * placeholder written since names, which go into the glossary when the package is saved, the glossary made where the
+     * file has none (CR-002 section 63, D8 and D9). An extension.
+     */
+    readonly glossaryEntries: GlossaryEntries;
     /**
      * The parts `seedAnnotationIds()` has read, with what it read: `true` for a part still holding its
      * source, whose bytes cannot change, and otherwise the bytes that were set, which stay the same
@@ -212,10 +223,24 @@ export declare class WordprocessingMLPackage extends OpcPackage implements Track
     private settingsPart;
     /**
      * Office JS `document.getTrackedChanges()`: every tracked change in the main document part,
-     * in document order (headers and footers have their own `Body`). The part must be
-     * unmarshalled, as `body` needs it to be.
+     * in document order (headers and footers have their own `Body`; `getAllTrackedChanges` lists
+     * every story). The part must be unmarshalled, as `body` needs it to be.
      */
     getTrackedChanges(): TrackedChange[];
+    /**
+     * Every tracked change in every story, in docx4j's order (its CR-043 `TrackedChanges.in`, CR-011):
+     * the main document, each footnote, each endnote, each comment, then the headers and footers in the
+     * order the sections reference them; a text box's after the story it is in. Each story's are its
+     * `Body.getTrackedChanges()`, grouped as Office JS groups them, so changes never group across two
+     * stories. `TrackedChange.part` says which part each is in.
+     *
+     * With a filter, the changes with a piece it matches, each whole (docx4j's `in(pkg, filter)`).
+     *
+     * A story part whose source holds no revision markup is not read, so it keeps its bytes; one that
+     * does is unmarshalled, since the views returned must be resolvable, and so is re-marshalled on save.
+     * An extension: Office JS lists one body at a time.
+     */
+    getAllTrackedChanges(filter?: TrackedChangeSelection): Promise<TrackedChange[]>;
     /**
      * Accepts every tracked change in every story: the main document, the footnotes, the endnotes and
      * the comments, the headers and footers, and the text boxes in each. Word's
@@ -223,15 +248,19 @@ export declare class WordprocessingMLPackage extends OpcPackage implements Track
      * revision in any story; `Body.acceptAll` resolves its own story only, as Office JS's `body` does
      * (CR-002 section 49). A story part with no revision markup is not read, so it keeps its bytes.
      * Returns how many changes were listed, story by story. An extension, named after Word's verb.
+     *
+     * With a filter (CR-011), only the single changes it matches are accepted, as `Body.acceptAll`
+     * takes one, and the count is of the listed changes with a matching piece.
      */
-    acceptAllRevisions(): Promise<number>;
+    acceptAllRevisions(filter?: TrackedChangeSelection): Promise<number>;
     /** Rejects every tracked change in every story, as `acceptAllRevisions` accepts them (Word's `Document.RejectAllRevisions`). */
-    rejectAllRevisions(): Promise<number>;
+    rejectAllRevisions(filter?: TrackedChangeSelection): Promise<number>;
     private resolveEveryStory;
     /**
      * The body of every story whose part holds revision markup, in docx4j's order (its CR-043
      * `TrackedChanges.in`): the main document, each footnote, each endnote, each comment, then the
-     * headers and footers. A footnote, an endnote or a comment is a body of its own over its content.
+     * headers and footers in section order (`inSectionOrder`). A footnote, an endnote or a comment is a
+     * body of its own over its content.
      */
     private revisedStories;
     /** The tracker every content-API mutation asks for; undefined while the mode is `Off`. */
@@ -294,10 +323,18 @@ export declare class WordprocessingMLPackage extends OpcPackage implements Track
     /** A clone carries the identity, the tracking date, the theme setting, the XPath engine and the styles still to ensure. */
     protected copyPackageSettingsTo(target: OpcPackage): void;
     saveTo<R>(sink: PartSink<R>): Promise<R>;
-    /** The paragraph at an address anywhere in the document: 'body/3', 'header:rId5/0', a paraId, or a text match. */
+    /**
+     * The paragraph at an address anywhere in the document: 'body/3', 'header:rId5/0', 'footnote:2/0',
+     * 'endnote:1/0', 'comment:5/0', 'body/3/textbox:0/1' (a text box's paragraph, read-only: CR-012 D4 and
+     * D5), a paraId, or a text match. Undefined where the address names no paragraph.
+     */
     paragraphAt(address: Address): Promise<Paragraph | undefined>;
-    /** Every paragraph and table with its address, style and text (CR-002 section 3.3). Unmarshals the main part, headers and footers. */
-    outline(): Promise<DocumentOutline>;
+    /**
+     * Every paragraph and table with its address, style and text (CR-002 section 3.3), read by the text model
+     * under one context (CR-012 D3: `Body.outline`, whose options it takes): the main document, then each
+     * header and footer. Unmarshals the main part, headers and footers.
+     */
+    outline(options?: TextOptionsInit | TextOptions, context?: TextContext): Promise<DocumentOutline>;
     private bodies;
     /**
      * The XPath engine the custom XML views use (CR-002 section 3.6): `document.evaluate` in a

package/dist/packages/WordprocessingMLPackage.mjs

@@ -4,27 +4,33 @@ import { registerPackageClass } from './registry.mjs';
 import { ContentTypes } from '../opc/ContentTypes.mjs';
 import { Docx4JException } from '../opc/exceptions.mjs';
 import { Namespaces } from '../parts/Namespaces.mjs';
-import { MainDocumentPart, StyleDefinitionsPart, DocumentSettingsPart } from '../parts/wml/index.mjs';
+import { MainDocumentPart, StyleDefinitionsPart, DocumentSettingsPart, GlossaryDocumentPart } from '../parts/wml/index.mjs';
 import { DocPropsCorePart, DocPropsExtendedPart } from '../parts/docProps/index.mjs';
 import { DEFAULT_STYLES_XML } from '../parts/wml/defaultStyles.mjs';
 import { ThemePart } from '../parts/dml/index.mjs';
 import { newFontSettings, themeOfSettings, } from '../model/fonts/defaultTheme.mjs';
 import { HeaderPart, FooterPart } from '../parts/wml/index.mjs';
-import { Body, resolveStory } from '../model/content/Body.mjs';
+import { Body, resolveStory, trackedChangesOfStory } from '../model/content/Body.mjs';
+import { pieceMatcher } from '../model/content/trackedChangeFilter.mjs';
 import { CustomXmlPartCollection } from '../model/customxml/CustomXmlPartCollection.mjs';
 import { DefaultXPathEngine } from '../model/customxml/xpath.mjs';
 import { ChangeTracker, highestAnnotationId } from '../model/content/tracking.mjs';
 import { NumberingFacade } from '../model/content/List.mjs';
 import { StylesFacade } from '../model/content/stylesFacade.mjs';
 import { flushPendingCommentRemovals } from '../model/content/Comment.mjs';
+import { GlossaryEntries } from '../model/content/placeholders.mjs';
 import { PropertyResolver } from '../model/properties/PropertyResolver.mjs';
 import { PropertyResolverNotCreatedException } from '../opc/exceptions.mjs';
-import { flushPendingNoteRemovals } from '../model/content/TrackedChange.mjs';
+import { flushPendingNoteRemovals, notesGoing } from '../model/content/TrackedChange.mjs';
 import { flushPendingRelationshipRemovals } from '../model/content/relationships.mjs';
 import { XmlPart } from '../parts/XmlPart.mjs';
 // Registers the comment parts with the content API (CR-002 phase G); no cycle: the model half
 // never imports a part, as packages/registry.mts does for the package classes.
 import '../parts/wml/comments.mjs';
+// Registers the text model's outline reader with Body.outline (CR-012 D3), the same way: the content API
+// can't import the text model, which imports it.
+import '../model/text/outline.mjs';
+import { Texts } from '../model/text/Texts.mjs';
 const MAIN_CONTENT_TYPES = [
     ContentTypes.WORDPROCESSINGML_DOCUMENT,
     ContentTypes.WORDPROCESSINGML_DOCUMENT_MACROENABLED,
@@ -105,6 +111,12 @@ export class WordprocessingMLPackage extends OpcPackage {
          * 47). Settled on save, not at once, so a picture cut and pasted back keeps its image. An extension.
          */
         this.pendingRelationshipRemovals = new Map();
+        /**
+         * The glossary's placeholder entries: read privately when a body is first read (`getBody`, `Word.run`), and those a
+         * placeholder written since names, which go into the glossary when the package is saved, the glossary made where the
+         * file has none (CR-002 section 63, D8 and D9). An extension.
+         */
+        this.glossaryEntries = new GlossaryEntries();
         /**
          * The parts `seedAnnotationIds()` has read, with what it read: `true` for a part still holding its
          * source, whose bytes cannot change, and otherwise the bytes that were set, which stay the same
@@ -414,12 +426,32 @@ export class WordprocessingMLPackage extends OpcPackage {
     }
     /**
      * Office JS `document.getTrackedChanges()`: every tracked change in the main document part,
-     * in document order (headers and footers have their own `Body`). The part must be
-     * unmarshalled, as `body` needs it to be.
+     * in document order (headers and footers have their own `Body`; `getAllTrackedChanges` lists
+     * every story). The part must be unmarshalled, as `body` needs it to be.
      */
     getTrackedChanges() {
         return this.body.getTrackedChanges();
     }
+    /**
+     * Every tracked change in every story, in docx4j's order (its CR-043 `TrackedChanges.in`, CR-011):
+     * the main document, each footnote, each endnote, each comment, then the headers and footers in the
+     * order the sections reference them; a text box's after the story it is in. Each story's are its
+     * `Body.getTrackedChanges()`, grouped as Office JS groups them, so changes never group across two
+     * stories. `TrackedChange.part` says which part each is in.
+     *
+     * With a filter, the changes with a piece it matches, each whole (docx4j's `in(pkg, filter)`).
+     *
+     * A story part whose source holds no revision markup is not read, so it keeps its bytes; one that
+     * does is unmarshalled, since the views returned must be resolvable, and so is re-marshalled on save.
+     * An extension: Office JS lists one body at a time.
+     */
+    async getAllTrackedChanges(filter) {
+        const matches = filter === undefined ? undefined : pieceMatcher(filter);
+        const out = [];
+        for (const body of await this.revisedStories())
+            out.push(...trackedChangesOfStory(body));
+        return matches ? out.filter((change) => change.pieces.some(matches)) : out;
+    }
     /**
      * Accepts every tracked change in every story: the main document, the footnotes, the endnotes and
      * the comments, the headers and footers, and the text boxes in each. Word's
@@ -427,24 +459,30 @@ export class WordprocessingMLPackage extends OpcPackage {
      * revision in any story; `Body.acceptAll` resolves its own story only, as Office JS's `body` does
      * (CR-002 section 49). A story part with no revision markup is not read, so it keeps its bytes.
      * Returns how many changes were listed, story by story. An extension, named after Word's verb.
+     *
+     * With a filter (CR-011), only the single changes it matches are accepted, as `Body.acceptAll`
+     * takes one, and the count is of the listed changes with a matching piece.
      */
-    async acceptAllRevisions() {
-        return this.resolveEveryStory('accept');
+    async acceptAllRevisions(filter) {
+        return this.resolveEveryStory('accept', filter);
     }
     /** Rejects every tracked change in every story, as `acceptAllRevisions` accepts them (Word's `Document.RejectAllRevisions`). */
-    async rejectAllRevisions() {
-        return this.resolveEveryStory('reject');
+    async rejectAllRevisions(filter) {
+        return this.resolveEveryStory('reject', filter);
     }
-    async resolveEveryStory(what) {
+    async resolveEveryStory(what, filter) {
+        if (filter !== undefined)
+            pieceMatcher(filter); // a filter misread throws before anything is read or resolved
         let count = 0;
         for (const body of await this.revisedStories())
-            count += resolveStory(body, what);
+            count += resolveStory(body, what, filter);
         return count;
     }
     /**
      * The body of every story whose part holds revision markup, in docx4j's order (its CR-043
      * `TrackedChanges.in`): the main document, each footnote, each endnote, each comment, then the
-     * headers and footers. A footnote, an endnote or a comment is a body of its own over its content.
+     * headers and footers in section order (`inSectionOrder`). A footnote, an endnote or a comment is a
+     * body of its own over its content.
      */
     async revisedStories() {
         var _a, _b;
@@ -452,22 +490,33 @@ export class WordprocessingMLPackage extends OpcPackage {
         const out = [];
         if (await holdsRevisions(main))
             out.push(await main.getBody());
+        // a note or comment a resolution has taken the reference or anchor of goes on save; it is no story now
+        const pending = this.pendingNoteRemovals;
+        const going = pending.footnote.size + pending.endnote.size > 0 ? notesGoing(await main.readContents(), pending) : pending;
         for (const [part, kind] of [[main.footnotesPart, 'footnote'], [main.endnotesPart, 'endnote']]) {
             if (!part || !(await holdsRevisions(part)))
                 continue;
             const contents = await part.getContents();
             for (const note of (_a = (kind === 'footnote' ? contents.footnote : contents.endnote)) !== null && _a !== void 0 ? _a : []) {
+                if ((note.type === undefined || note.type === 'normal') && going[kind].has(Number(note.id)))
+                    continue;
                 out.push(new Body(part, note, `${kind}:${note.id}`, this));
             }
         }
         const comments = main.commentsPart;
         if (comments && (await holdsRevisions(comments))) {
-            for (const comment of (_b = (await comments.getContents()).comment) !== null && _b !== void 0 ? _b : [])
+            for (const comment of (_b = (await comments.getContents()).comment) !== null && _b !== void 0 ? _b : []) {
+                if (this.pendingCommentRemovals.has(comment.id))
+                    continue;
                 out.push(new Body(comments, comment, `comment:${comment.id}`, this));
+            }
         }
+        const revised = [];
         for (const part of [...main.headerParts, ...main.footerParts])
             if (await holdsRevisions(part))
-                out.push(await part.getBody());
+                revised.push(part);
+        for (const part of revised.length > 1 ? await inSectionOrder(main, revised) : revised)
+            out.push(await part.getBody());
         return out;
     }
     /** The tracker every content-API mutation asks for; undefined while the mode is `Off`. */
@@ -583,6 +632,7 @@ export class WordprocessingMLPackage extends OpcPackage {
             target.pendingNoteRemovals.endnote.add(id);
         for (const [name, ids] of this.pendingRelationshipRemovals)
             target.pendingRelationshipRemovals.set(name, new Set(ids));
+        this.glossaryEntries.copyTo(target.glossaryEntries);
         target.trackedChangeDate = this.trackedChangeDate;
         target.fonts.defaultTheme = this.fonts.defaultTheme;
         target.xpathEngine = this.xpathEngine;
@@ -603,13 +653,23 @@ export class WordprocessingMLPackage extends OpcPackage {
         }
         if (this.pendingRelationshipRemovals.size > 0)
             flushPendingRelationshipRemovals(this, this.pendingRelationshipRemovals);
+        if (this.glossaryEntries.waiting) {
+            await this.glossaryEntries.flush(this, {
+                glossary: () => new GlossaryDocumentPart(),
+                styles: () => new StyleDefinitionsPart('/word/glossary/styles.xml'),
+            });
+        }
         if (this.requiredStyles.size > 0) {
             await this.styles.ensure([...this.requiredStyles]);
             this.requiredStyles.clear();
         }
         return super.saveTo(sink);
     }
-    /** The paragraph at an address anywhere in the document: 'body/3', 'header:rId5/0', a paraId, or a text match. */
+    /**
+     * The paragraph at an address anywhere in the document: 'body/3', 'header:rId5/0', 'footnote:2/0',
+     * 'endnote:1/0', 'comment:5/0', 'body/3/textbox:0/1' (a text box's paragraph, read-only: CR-012 D4 and
+     * D5), a paraId, or a text match. Undefined where the address names no paragraph.
+     */
     async paragraphAt(address) {
         for (const body of await this.bodies(address)) {
             const p = body.paragraphAt(address);
@@ -618,28 +678,44 @@ export class WordprocessingMLPackage extends OpcPackage {
         }
         return undefined;
     }
-    /** Every paragraph and table with its address, style and text (CR-002 section 3.3). Unmarshals the main part, headers and footers. */
-    async outline() {
+    /**
+     * Every paragraph and table with its address, style and text (CR-002 section 3.3), read by the text model
+     * under one context (CR-012 D3: `Body.outline`, whose options it takes): the main document, then each
+     * header and footer. Unmarshals the main part, headers and footers.
+     */
+    async outline(options, context) {
         var _a, _b, _c, _d;
         const main = await this.getBody();
-        const out = { ...main.outline(), headers: [], footers: [] };
+        const ctx = context !== null && context !== void 0 ? context : await Texts.contextOf(this);
+        const out = { ...await main.outline(options, ctx), headers: [], footers: [] };
         for (const part of this.getMainDocumentPart().headerParts) {
             const body = await part.getBody();
-            out.headers.push({ relId: (_b = (_a = part.sourceRelationship) === null || _a === void 0 ? void 0 : _a.id) !== null && _b !== void 0 ? _b : '', partName: part.partName.name, ...body.outline() });
+            out.headers.push({ relId: (_b = (_a = part.sourceRelationship) === null || _a === void 0 ? void 0 : _a.id) !== null && _b !== void 0 ? _b : '', partName: part.partName.name, ...await body.outline(options, ctx) });
         }
         for (const part of this.getMainDocumentPart().footerParts) {
             const body = await part.getBody();
-            out.footers.push({ relId: (_d = (_c = part.sourceRelationship) === null || _c === void 0 ? void 0 : _c.id) !== null && _d !== void 0 ? _d : '', partName: part.partName.name, ...body.outline() });
+            out.footers.push({ relId: (_d = (_c = part.sourceRelationship) === null || _c === void 0 ? void 0 : _c.id) !== null && _d !== void 0 ? _d : '', partName: part.partName.name, ...await body.outline(options, ctx) });
         }
         return out;
     }
     async bodies(address) {
+        var _a;
         const main = this.getMainDocumentPart();
         if (typeof address === 'string' && !address.startsWith('w14:')) {
             const prefix = address.split('/')[0];
             if (prefix === 'body')
                 return [await main.getBody()];
             const [kind, relId] = prefix.split(':');
+            if (kind === 'footnote' || kind === 'endnote' || kind === 'comment') {
+                // a note's or a comment's body, by its w:id, as the text model and Comment address them (CR-012 D4)
+                const part = kind === 'footnote' ? main.footnotesPart : kind === 'endnote' ? main.endnotesPart : main.commentsPart;
+                if (!part)
+                    return [];
+                const contents = await part.getContents();
+                const entry = ((_a = contents[kind]) !== null && _a !== void 0 ? _a : []).find((e) => String(e.id) === relId);
+                await this.getPropertyResolver().catch(() => undefined);
+                return entry ? [new Body(part, entry, `${kind}:${relId}`, this)] : [];
+            }
             const parts = kind === 'header' ? main.headerParts : kind === 'footer' ? main.footerParts : [];
             const part = parts.find((p) => { var _a; return ((_a = p.sourceRelationship) === null || _a === void 0 ? void 0 : _a.id) === relId || p.partName.fileName === relId; });
             return part instanceof HeaderPart || part instanceof FooterPart ? [await part.getBody()] : [];
@@ -715,6 +791,65 @@ export class WordprocessingMLPackage extends OpcPackage {
         return 'Word.Document';
     }
 }
+/**
+ * Headers and footers in docx4j's order (its CR-043 `Lister.headersAndFooters`): as the sections
+ * reference them, in document order, a part once, then any other in the order of the main part's
+ * relationships. The main part's tree is read privately, so a main part nobody has otherwise read keeps
+ * its bytes.
+ */
+async function inSectionOrder(main, parts) {
+    var _a;
+    const rels = main.relationshipsPart;
+    if (!rels)
+        return parts;
+    const order = [];
+    const add = (part) => {
+        const known = parts.find((p) => p === part);
+        if (known && !order.includes(known))
+            order.push(known);
+    };
+    const body = (await main.readContents()).body;
+    for (const sectPr of sectionsOf(body))
+        for (const ref of (_a = sectPr.egHdrFtrReferences) !== null && _a !== void 0 ? _a : [])
+            add(rels.getPart(ref.id));
+    for (const rel of rels.list)
+        add(rels.getPart(rel));
+    for (const part of parts)
+        if (!order.includes(part))
+            order.push(part);
+    return order;
+}
+/**
+ * The body's `w:sectPr`s in document order, the paragraphs' first and the body's own last, as docx4j's
+ * walk finds them: not inside a run (where a text box's paragraphs are), DOM the model does not type
+ * left alone.
+ */
+function sectionsOf(body) {
+    const out = [];
+    const visit = (o) => {
+        if (typeof o !== 'object' || o === null || typeof o.nodeType === 'number')
+            return;
+        if (Array.isArray(o)) {
+            for (const item of o)
+                visit(item);
+            return;
+        }
+        const typeName = o.TYPE_NAME;
+        if (typeName === 'org_docx4j_wml.SectPr') {
+            out.push(o);
+            return;
+        }
+        if (typeName === 'org_docx4j_wml.R')
+            return;
+        for (const key in o)
+            if (key !== 'PARENT')
+                visit(o[key]);
+    };
+    visit(body === null || body === void 0 ? void 0 : body.content);
+    if (body === null || body === void 0 ? void 0 : body.sectPr)
+        out.push(body.sectPr);
+    return out;
+}
 /** Revision markup, by local name in any prefix: what a story part holds when it has a tracked change to resolve. */
 const REVISION_MARKUP = /<(?:[\w.-]+:)?(?:ins|del|moveFrom|moveTo|rPrChange|pPrChange|sectPrChange|tblPrChange|trPrChange|tcPrChange|tblGridChange|tblPrExChange|cellIns|cellDel|cellMerge|numberingChange|customXmlInsRangeStart|customXmlDelRangeStart)[\s/>]/;
 /**

package/dist/parts/DefaultXmlPart.mjs

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

package/dist/parts/Part.d.mts

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

package/dist/parts/XmlPart.d.mts

@@ -1,5 +1,5 @@
 import { type Jsonix } from '@docx4j/generated-objects-ts';
-import { Part } from './Part.mjs';
+import { Part, type PartBytesOptions } from './Part.mjs';
 import { PartName } from '../opc/PartName.mjs';
 import { type Bound } from '../model/content/binder.mjs';
 import type { PartWarning } from '../opc/mce/preprocessor.mjs';
@@ -36,12 +36,6 @@ export declare class XmlPart<T = unknown> extends Part {
     rootName: RootName | undefined;
     /** Runs over the DOM before unmarshalling; the package sets its MCE preprocessor here. */
     preprocessor: DomPreprocessor | undefined;
-    /**
-     * The namespace declarations the source root element carried, prefix to URI, recorded when the
-     * part was parsed. They are what `mc:Ignorable` prefixes the object model does not bind are
-     * re-declared from on marshal; see `declareIgnorablePrefixes`.
-     */
-    private sourceDeclarations;
     private parseWarnings;
     constructor(partName: PartName | string, contentType: string, relationshipType: string, rootName?: RootName);
     /** True once contents were unmarshalled or set; the part is then re-marshalled on save. */
@@ -54,9 +48,10 @@ export declare class XmlPart<T = unknown> extends Part {
      */
     get isUntouched(): boolean;
     /**
-     * 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), and each attribute value its type refuses that was read as
+     * Word 365 reads it (`value.kept.exact`, `value.kept.invalid`: CR-015 D8). Empty until the part is
+     * parsed, by `getContents()` or a private read, and again once its contents are set.
      */
     get warnings(): readonly PartWarning[];
     /** The unmarshalled contents (docx4j getJaxbElement()); throws when not yet unmarshalled. */
@@ -85,7 +80,7 @@ export declare class XmlPart<T = unknown> extends Part {
     /** The XML as it would be saved (docx4j XmlUtils.marshaltoString on the part). */
     getXml(): Promise<string>;
     /** Marshalled bytes when unmarshalled or set, else the source bytes untouched. */
-    getBytes(): Promise<Uint8Array>;
+    getBytes(options?: PartBytesOptions): Promise<Uint8Array>;
     /**
      * The objects an XPath selects in this part, through a DOM marshalled for the purpose
      * (CR-006; docx4j `JaxbXmlPart.getJAXBNodesViaXPath`, which does it with a JAXB `Binder`).
@@ -104,8 +99,12 @@ export declare class XmlPart<T = unknown> extends Part {
      * (CR-002 section 31).
      */
     selectObjects(xpath: string, options?: SelectOptions): Promise<Bound[]>;
-    /** The root element as a DOM element (docx4j XmlUtils.marshaltoW3CDomDocument). */
-    marshalToNode(): Promise<Element>;
+    /**
+     * The root element as a DOM element (docx4j XmlUtils.marshaltoW3CDomDocument). Run properties are written in
+     * their normal form unless the package's `normaliseOnSave` (else the objects package's `setNormaliseOnSave`) is
+     * false (CR-015 D2, the objects facade's CR-013 phase C): the tree keeps what it read.
+     */
+    marshalToNode(options?: PartBytesOptions): Promise<Element>;
     /**
      * Parses the part's bytes, and names the part when the XML is not well-formed. xmldom's error
      * (Node) carries the line and column of the fault; a browser's says them in its text, which
@@ -124,21 +123,4 @@ export declare class XmlPart<T = unknown> extends Part {
      * locator).
      */
     private unmarshal;
-    /** The source root element's namespace declarations, prefix to URI (`xmlns=` is the empty prefix). */
-    private recordDeclarations;
-    /**
-     * Every prefix the marshalled root's `mc:Ignorable` names must be declared on that root
-     * (ECMA-376 Part 3 10.1.2; Word and Excel treat an undeclared one as a corrupt part and offer
-     * to repair the file). The object model binds only the namespaces it has modules for, so an
-     * `mc:Ignorable` prefix whose content was dropped on unmarshal - `xr6`, `xr10` and `xr2` on
-     * Excel's `xl/workbook.xml`, for instance - loses its declaration: the runtime declares one
-     * prefix per entry of the objects package's table and the facade can only *remove* unused
-     * declarations, never add one it never made (CR-001 section 17).
-     *
-     * So the part re-declares them itself: from what the source root declared, else from the
-     * objects package's `NAMESPACE_PREFIXES`. A prefix neither knows is dropped from
-     * `mc:Ignorable` - an undeclared prefix is the one thing that must not be written - and warned
-     * about once.
-     */
-    private declareIgnorablePrefixes;
 }