@docx4j/core-ts 0.4.0 → 0.6.0

package/dist/model/text/outline.mjs

@@ -0,0 +1,71 @@
+// CR-012 D3: Body.outline() and pkg.outline() read the text model. The paragraph text is the model's (hidden
+// text left out, a deleted mark joined, the view's), each text box's paragraphs follow their anchor at
+// `textbox:` addresses, flagged, and the options are the model's; the shape is the outline's own.
+import { setOutlineReader } from '../content/outline.mjs';
+import { Extractor } from './Extractor.mjs';
+import { PackageTrees, TextContext } from './TextContext.mjs';
+import { contextFor, optionsOf, isPackage } from './Texts.mjs';
+/** The story a body's blocks are in, from its address prefix. */
+function storyOf(prefix) {
+    const kind = prefix.split(':')[0];
+    switch (kind) {
+        case 'header': return 'HEADER';
+        case 'footer': return 'FOOTER';
+        case 'footnote': return 'FOOTNOTE';
+        case 'endnote': return 'ENDNOTE';
+        case 'comment': return 'COMMENT';
+        default: return 'MAIN';
+    }
+}
+/** The outline of blocks: each paragraph with its address, paraId, style and text, each table with its size; a cell's blocks after its table. */
+export function outlineOfBlocks(blocks) {
+    const paragraphs = [];
+    const tables = [];
+    const visit = (list) => {
+        var _a, _b, _c;
+        for (const block of list) {
+            if (block.kind === 'PARAGRAPH') {
+                const entry = { address: block.address, style: (_a = block.style) !== null && _a !== void 0 ? _a : 'Normal', text: block.text };
+                if (block.paraId)
+                    entry.paraId = block.paraId;
+                if (block.textbox)
+                    entry.textbox = true;
+                if (block.joined.length > 0)
+                    entry.joined = [...block.joined];
+                paragraphs.push(entry);
+            }
+            else if (block.kind === 'TABLE') {
+                tables.push({ address: block.address, rows: block.rows.length, cols: (_c = (_b = block.rows[0]) === null || _b === void 0 ? void 0 : _b.cells.length) !== null && _c !== void 0 ? _c : 0 });
+                for (const row of block.rows)
+                    for (const cell of row.cells)
+                        visit(cell.blocks);
+            }
+        }
+    };
+    visit(blocks);
+    return { paragraphs, tables };
+}
+setOutlineReader(async (body, options, context, blocks) => {
+    const o = optionsOf(options);
+    const pkg = body.package_;
+    const kind = storyOf(body.prefix);
+    if (!isPackage(pkg)) {
+        // content with no package: read as it stands, as Texts.of(content) does
+        const none = PackageTrees.none();
+        const x = new Extractor(none, o, 'planless', new TextContext(none));
+        if (blocks === undefined)
+            return outlineOfBlocks(x.extractContent(body.container, kind, body.prefix, undefined).blocks);
+        const starts = Extractor.fieldsAtBlocks(none, o, 'planless', new TextContext(none), body.container, kind, body.prefix, undefined);
+        return outlineOfBlocks(x.extractBlocks(body.container, kind, body.prefix, undefined, blocks, starts).blocks);
+    }
+    const ctx = await contextFor(pkg, context, o);
+    const part = body.part;
+    if (blocks === undefined)
+        return outlineOfBlocks(new Extractor(ctx.trees, o, 'view', ctx).extractContent(body.container, kind, body.prefix, part).blocks);
+    // some blocks (section 17.13): the plan made in the context itself, so that the siblings share it, and the
+    // reading under a sibling, so that it numbers no note and counts no list in the caller's context
+    if (o.view !== 'markup')
+        ctx.plan(o.view === 'accepted');
+    const starts = ctx.blockStarts(body.container, JSON.stringify(o.toMap()), () => Extractor.fieldsAtBlocks(ctx.trees, o, 'view', ctx, body.container, kind, body.prefix, part));
+    return outlineOfBlocks(new Extractor(ctx.trees, o, 'view', ctx.sibling()).extractBlocks(body.container, kind, body.prefix, part, blocks, starts).blocks);
+});

package/dist/office-js/fragment.d.mts

@@ -1,10 +1,12 @@
-import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
 import type { Range } from '../model/content/Range.mjs';
 import type { Element } from '../model/content/tree.mjs';
 /**
- * A detached `w:p` holding exactly the range's text, with the runs and their formatting. The
- * paragraph is copied first, so the document is untouched.
+ * The blocks a range holds, as detached copies: within one paragraph, that paragraph trimmed to the range; across
+ * paragraphs, the first paragraph from the range's start, every block between whole (a table, a content control),
+ * and the last paragraph to the range's end, left out where the range ends at its start. The blocks are those
+ * `delete()` takes (`extentOf`), so a range starting or ending inside a table or a content control it doesn't hold
+ * whole is refused: a fragment of part of one isn't written.
  */
-export declare function paragraphElementOfRange(range: Range): Element<wml.P>;
-/** The range as a `w:p` fragment (extension; Office JS wraps a range in a pkg:package). */
+export declare function blocksOfRange(range: Range): Element[];
+/** The range as a fragment: its blocks' XML, one after another (extension; Office JS wraps a range in a pkg:package). */
 export declare function xmlOfRange(range: Range): Promise<string>;

package/dist/office-js/fragment.mjs

@@ -1,23 +1,72 @@
 // Marshalling a view back to a fragment: what `getOoxml()` and `toApiScript`'s fallback need.
-// A `w:p` copy holding only a range's text is the one piece the views do not offer (Range has no
-// element of its own: it is a span of the paragraph's text).
+// Copies of the blocks a range holds, its paragraphs trimmed to it, are the one piece the views do
+// not offer (Range has no element of its own: it is a span of its paragraphs' text).
 import { deepCopy, marshalString } from '@docx4j/generated-objects-ts';
+import { Body } from '../model/content/Body.mjs';
 import { Paragraph } from '../model/content/Paragraph.mjs';
+import { extentOf } from '../model/content/spanEdits.mjs';
+import { GeneralException } from '../model/content/generalException.mjs';
+import { NotSupportedError } from './errors.mjs';
 /**
- * A detached `w:p` holding exactly the range's text, with the runs and their formatting. The
- * paragraph is copied first, so the document is untouched.
+ * The body a detached copy is trimmed through. It reads as the paragraph's own body does (its package's styles
+ * decide which runs are hidden, and so the offsets), and writes untracked: trimming a copy is no edit of the
+ * document, and under tracking the trim would otherwise mark the rest of the copy deleted. What the trim queues on
+ * the package (a picture's relationship, a comment whose reference the copy lost) is settled at save against the
+ * document as it stands, which still holds them.
  */
-export function paragraphElementOfRange(range) {
-    const copy = deepCopy(range.paragraph.element);
-    const view = new Paragraph(copy, [copy], range.paragraph.parentBody);
+class CopyBody extends Body {
+    get changeTracker() {
+        return undefined;
+    }
+}
+/** A detached copy of `paragraph` holding only its text from `start` to `end`, with the runs and their formatting. */
+function trimmed(paragraph, start, end) {
+    const copy = deepCopy(paragraph.element);
+    const own = paragraph.parentBody;
+    const view = new Paragraph(copy, [copy], new CopyBody(own.part, { content: [copy] }, own.prefix, own.package_));
     const length = view.text.length;
-    if (range.end < length)
-        view.splice(range.end, length, '');
-    if (range.start > 0)
-        view.splice(0, range.start, '');
+    if (end < length)
+        view.splice(end, length, '');
+    if (start > 0)
+        view.splice(0, start, '');
     return copy;
 }
-/** The range as a `w:p` fragment (extension; Office JS wraps a range in a pkg:package). */
-export function xmlOfRange(range) {
-    return marshalString(paragraphElementOfRange(range));
+/**
+ * The blocks a range holds, as detached copies: within one paragraph, that paragraph trimmed to the range; across
+ * paragraphs, the first paragraph from the range's start, every block between whole (a table, a content control),
+ * and the last paragraph to the range's end, left out where the range ends at its start. The blocks are those
+ * `delete()` takes (`extentOf`), so a range starting or ending inside a table or a content control it doesn't hold
+ * whole is refused: a fragment of part of one isn't written.
+ */
+export function blocksOfRange(range) {
+    if (!range.spansParagraphs)
+        return [trimmed(range.paragraph, range.start, range.end)];
+    let extent;
+    try {
+        extent = extentOf(range, 'getOoxml');
+    }
+    catch (error) {
+        if (!(error instanceof GeneralException) && !(error instanceof NotSupportedError))
+            throw error;
+        throw new NotSupportedError('Range', 'getOoxml', "this range starts or ends inside a table or a content control it doesn't hold whole, "
+            + "and a fragment of part of one isn't written; take the whole table or control, or a range inside one cell");
+    }
+    const out = [];
+    for (let k = extent.first; k <= extent.last; k++) {
+        const block = extent.list[k];
+        if (k === extent.first && extent.head)
+            out.push(trimmed(extent.head, range.start, extent.head.text.length));
+        else if (k === extent.last && extent.tail) {
+            if (range.end > 0)
+                out.push(trimmed(extent.tail, 0, range.end));
+        }
+        else
+            out.push(deepCopy(block));
+    }
+    return out;
+}
+/** The range as a fragment: its blocks' XML, one after another (extension; Office JS wraps a range in a pkg:package). */
+export async function xmlOfRange(range) {
+    const xml = await Promise.all(blocksOfRange(range).map((block) => marshalString(block)));
+    return xml.join('');
 }

package/dist/office-js/proxy.d.mts

@@ -23,6 +23,14 @@ export declare class ClientResult<T = unknown> {
     resolveWith(value: T): void;
     /** True once `context.sync()` has filled it. */
     get isLoaded(): boolean;
+    /**
+     * Office JS's `load` on what an asynchronous member returned: nothing to load here, so the result itself.
+     * With `items`, a collection a member returns asynchronously (`range.getComments()`, the comment parts
+     * being read first) reads as Office JS code expects: `load`, `context.sync()`, then `items` (CR-014 phase 1).
+     */
+    load(): this;
+    /** The collection's items, once `context.sync()` has filled the result: an asynchronous collection's. */
+    get items(): T extends readonly (infer I)[] ? I[] : never;
     toJSON(): {
         value: T | undefined;
     };

package/dist/office-js/proxy.mjs

@@ -47,6 +47,21 @@ export class ClientResult {
     get isLoaded() {
         return this.loaded;
     }
+    /**
+     * Office JS's `load` on what an asynchronous member returned: nothing to load here, so the result itself.
+     * With `items`, a collection a member returns asynchronously (`range.getComments()`, the comment parts
+     * being read first) reads as Office JS code expects: `load`, `context.sync()`, then `items` (CR-014 phase 1).
+     */
+    load() {
+        return this;
+    }
+    /** The collection's items, once `context.sync()` has filled the result: an asynchronous collection's. */
+    get items() {
+        const value = this.value;
+        if (!Array.isArray(value))
+            throw new NotSupportedError('ClientResult', 'items', `the result of ${this.member}() is not a collection`);
+        return value;
+    }
     toJSON() {
         return { value: this.loaded ? this.result : undefined };
     }
@@ -219,6 +234,9 @@ export class Wrapper {
             return wrapped;
         });
         result.attach(settled);
+        // the next sync() reports a failure; code that throws before it (a member of the result called at once, as
+        // Office JS code chains `insertComment(...).getRange()`) leaves it unawaited, which must not end the process
+        settled.catch(() => { });
         this.context.enqueue(settled);
         return result;
     }
@@ -253,6 +271,12 @@ export class Wrapper {
             result.resolveWith(wrapped.length);
             return result;
         });
+        if (itemClass === 'ContentControl') {
+            // Office JS's ContentControlCollection lookups: the controls with the tag or title, as a collection
+            const matching = (key, value) => this.collection(items.filter((i) => unwrap(i)[key] === value), 'contentControls');
+            define('getByTag', (tag) => matching('tag', tag));
+            define('getByTitle', (title) => matching('title', title));
+        }
         define('load', () => collectionProxy);
         define('track', () => collectionProxy);
         define('untrack', () => collectionProxy);
@@ -268,6 +292,11 @@ export class Wrapper {
                 if (!(prop in obj))
                     throw new NotSupportedError(className, prop);
                 const member2 = Reflect.get(obj, prop, obj);
+                // the array's own methods (map, filter, forEach) give what they give: an Office JS collection has
+                // none, and a map's empty result made into a collection wouldn't serialize (CR-014 phase 1)
+                if (typeof member2 === 'function' && Object.prototype.hasOwnProperty.call(Array.prototype, prop)) {
+                    return member2.bind(obj);
+                }
                 if (typeof member2 === 'function' && !/^\d+$/.test(prop)) {
                     return (...args) => wrapperSelf.result(member2.apply(obj, args.map(unwrap)), prop);
                 }

package/dist/office-js/run.mjs

@@ -43,6 +43,8 @@ export class RequestContext {
 async function prepare(pkg, options) {
     const main = pkg.getMainDocumentPart();
     await main.getContents();
+    // a control's placeholderText reads the glossary's entries, read privately (CR-002 section 63)
+    await pkg.glossaryEntries.load(main.glossaryDocumentPart);
     if (options.unmarshalSideParts === false)
         return;
     const sideParts = [pkg.docPropsCorePart, pkg.docPropsExtendedPart, main.documentSettingsPart];

package/dist/office-js/supported.generated.mjs

@@ -5,6 +5,8 @@ export const SUBSET_MEMBERS = [
     'Body.clear',
     'Body.contentControls',
     'Body.getComments',
+    'Body.getContentControls',
+    'Body.getRange',
     'Body.getTrackedChanges',
     'Body.inlinePictures',
     'Body.insertBreak',
@@ -23,6 +25,7 @@ export const SUBSET_MEMBERS = [
     'Comment.content',
     'Comment.creationDate',
     'Comment.delete',
+    'Comment.getRange',
     'Comment.replies',
     'Comment.reply',
     'Comment.resolved',
@@ -36,6 +39,7 @@ export const SUBSET_MEMBERS = [
     'ContentControl.datePickerContentControl',
     'ContentControl.delete',
     'ContentControl.dropDownListContentControl',
+    'ContentControl.getContentControls',
     'ContentControl.getRange',
     'ContentControl.groupContentControl',
     'ContentControl.id',
@@ -47,6 +51,7 @@ export const SUBSET_MEMBERS = [
     'ContentControl.removeWhenEdited',
     'ContentControl.repeatingSectionContentControl',
     'ContentControl.search',
+    'ContentControl.showingPlaceholderText',
     'ContentControl.tables',
     'ContentControl.tag',
     'ContentControl.text',
@@ -57,6 +62,7 @@ export const SUBSET_MEMBERS = [
     'ContentControlListItem.displayText',
     'ContentControlListItem.index',
     'ContentControlListItem.value',
+    'ContentControlOptions.types',
     'CustomXmlNode.attributes',
     'CustomXmlNode.baseName',
     'CustomXmlNode.childNodes',
@@ -151,6 +157,7 @@ export const SUBSET_MEMBERS = [
     'Paragraph.firstLineIndent',
     'Paragraph.font',
     'Paragraph.getComments',
+    'Paragraph.getContentControls',
     'Paragraph.getRange',
     'Paragraph.getTrackedChanges',
     'Paragraph.insertBreak',
@@ -172,19 +179,27 @@ export const SUBSET_MEMBERS = [
     'Paragraph.startNewList',
     'Paragraph.style',
     'Paragraph.styleBuiltIn',
+    'Paragraph.tableNestingLevel',
     'Paragraph.text',
     'PictureContentControl.inlinePicture',
+    'Range.contentControls',
     'Range.delete',
+    'Range.expandTo',
     'Range.font',
     'Range.getComments',
+    'Range.getContentControls',
     'Range.getRange',
     'Range.getTrackedChanges',
     'Range.hyperlink',
     'Range.insertComment',
     'Range.insertParagraph',
     'Range.insertText',
+    'Range.isEmpty',
+    'Range.paragraphs',
     'Range.search',
     'Range.style',
+    'Range.styleBuiltIn',
+    'Range.tables',
     'Range.text',
     'RepeatingSectionContentControl.allowInsertDeleteSection',
     'RepeatingSectionContentControl.items',
@@ -196,6 +211,7 @@ export const SUBSET_MEMBERS = [
     'Table.delete',
     'Table.deleteRows',
     'Table.getCell',
+    'Table.getRange',
     'Table.headerRowCount',
     'Table.rowCount',
     'Table.rows',

package/dist/office-js/toApiScript.mjs

@@ -9,8 +9,8 @@ import { Docx4JException } from '../opc/exceptions.mjs';
 import { Body } from '../model/content/Body.mjs';
 import { Paragraph } from '../model/content/Paragraph.mjs';
 import { Range } from '../model/content/Range.mjs';
-import { isElement, typeNameOf, textOf } from '../model/content/tree.mjs';
-import { paragraphElementOfRange } from './fragment.mjs';
+import { isElement, typeNameOf, textOf, selectedBranchOf, ALTERNATE_CONTENT } from '../model/content/tree.mjs';
+import { blocksOfRange } from './fragment.mjs';
 import { builtInOf, displayNameOf } from '../model/content/styles.mjs';
 const TWIPS_PER_POINT = 20;
 /** Paragraph properties the verbs express; anything else sends the paragraph to `insertXml`. */
@@ -97,13 +97,23 @@ class Emitter {
     line(text) {
         this.lines.push(this.indent + text);
     }
-    /** A block-level element: a paragraph, a table, or anything else through `insertXml`. */
+    /**
+     * A block-level element: a paragraph, a table, or anything else through `insertXml`. A kept
+     * `mc:AlternateContent` is its selected branch's content, as Word reads it and as its save writes it:
+     * `insertXml` refuses the element itself (CR-013 phase 3).
+     */
     async element(element) {
+        var _a;
         const typeName = typeNameOf(element);
         if (typeName === 'org_docx4j_wml.P')
             await this.paragraph(element);
         else if (typeName === 'org_docx4j_wml.Tbl')
             await this.table(element);
+        else if (typeName === ALTERNATE_CONTENT) {
+            this.line('// an mc:AlternateContent: its selected branch, as Word reads it');
+            for (const child of (_a = selectedBranchOf(element.value)) !== null && _a !== void 0 ? _a : [])
+                await this.element(child);
+        }
         else
             await this.fallback(element);
     }
@@ -117,9 +127,10 @@ class Emitter {
             await this.fallback(element, error.message);
         }
     }
-    /** A range: its text and run formatting, as one paragraph. */
+    /** A range: its text and run formatting, as one paragraph; across paragraphs, each block it holds. */
     async range(range) {
-        await this.paragraph(paragraphElementOfRange(range));
+        for (const block of blocksOfRange(range))
+            await this.element(block);
     }
     emitParagraph(p) {
         const properties = this.paragraphProperties(p);
@@ -326,10 +337,15 @@ function tableGrid(tbl) {
         const typeName = typeNameOf(item);
         if (typeName === 'org_docx4j_wml.CTTblGridCol' || typeName === 'org_docx4j_wml.TblGrid')
             continue;
+        // a row- or cell-level mc:AlternateContent is no plain grid: the table goes whole through insertXml (CR-013 phase 3)
+        if (typeName === ALTERNATE_CONTENT)
+            return undefined;
         if (typeName !== 'org_docx4j_wml.Tr')
             continue;
         const row = [];
         for (const cell of ((_b = item.value.content) !== null && _b !== void 0 ? _b : [])) {
+            if (typeNameOf(cell) === ALTERNATE_CONTENT)
+                return undefined;
             if (typeNameOf(cell) !== 'org_docx4j_wml.Tc')
                 continue;
             const tc = cell.value;

package/dist/opc/Load.d.mts

@@ -5,9 +5,16 @@ import type { OpcPackage } from '../packages/OpcPackage.mjs';
 export interface LoadOptions {
     /** Part classes by content type; defaults to docx4j's table. */
     registry?: PartRegistry;
-    /** Resolve `mc:AlternateContent` before unmarshalling (default true, as docx4j and Word). */
+    /**
+     * Resolve `mc:AlternateContent` before unmarshalling, as Word does on open. Default false since
+     * CR-010 phase 4: every element is kept with all its branches, as docx4j keeps it since its CR-021;
+     * readers take the branch resolving would (`selectedBranchOf`), mutators every branch, and a save
+     * writes them all. Either way a part's `warnings` report where the branches' text differs. True
+     * resolves, but keeps the element under a `KEPT_HOSTS` host and one nothing can be selected from
+     * (CR-010 phase 1).
+     */
     mcePreprocess?: boolean;
-    /** Runs over every XML part's DOM before it is unmarshalled; set by the package from `mcePreprocess`. */
+    /** Runs over every XML part's DOM before it is unmarshalled; set by the package from `mcePreprocess` (`mceKeep` or `mcePreprocess`). */
     preprocessor?: DomPreprocessor;
 }
 /**

package/dist/opc/Save.d.mts

@@ -1,5 +1,22 @@
 import type { PartSink } from './PartStore.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.
+ */
+export interface ValueNormalised {
+    code: 'value.normalised';
+    partName: string;
+    path: string;
+    before: string | undefined;
+    after: string | null;
+    message: string;
+}
+/** What the last save of a package did beyond writing it: each value it normalised (CR-015 D8). */
+export interface SaveReport {
+    normalised: ValueNormalised[];
+}
 /**
  * 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

package/dist/opc/Save.mjs

@@ -4,6 +4,13 @@ import { Docx4JException } from './exceptions.mjs';
 import { Namespaces } from '../parts/Namespaces.mjs';
 import { isExternal } from '../parts/RelationshipsPart.mjs';
 import { encodeText } from '../xml/dom.mjs';
+function valueNormalised(partName, n) {
+    const after = n.after === null ? 'left out' : `written ${JSON.stringify(n.after)}`;
+    return {
+        code: 'value.normalised', partName, path: n.path, before: n.before, after: n.after,
+        message: `${partName}: ${n.path} ${n.before === undefined ? '(no value)' : JSON.stringify(n.before)} ${after}, as Word reads it`,
+    };
+}
 /**
  * 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
@@ -14,13 +21,16 @@ export async function savePackage(pkg, sink) {
     const saver = new Saver(pkg, sink);
     sink.put(CONTENT_TYPES_NAME, encodeText(pkg.contentTypeManager.toXml()), { contentType: ContentTypes.CONTENT_TYPES_PART });
     await saver.saveRels(pkg.relationshipsPart);
-    return sink.finish();
+    const result = await sink.finish();
+    pkg.lastSave = { normalised: saver.normalised };
+    return result;
 }
 class Saver {
     constructor(pkg, sink) {
         this.pkg = pkg;
         this.sink = sink;
         this.handled = new Set();
+        this.normalised = [];
     }
     async saveRels(rp) {
         this.sink.put(rp.partName.storeName, await rp.getBytes(), { contentType: ContentTypes.RELATIONSHIPS_PART });
@@ -39,7 +49,7 @@ class Saver {
         this.handled.add(part.partName.key);
         let bytes;
         try {
-            bytes = await part.getBytes();
+            bytes = await part.getBytes({ onNormalised: (n) => this.normalised.push(valueNormalised(part.partName.name, n)) });
         }
         catch (e) {
             throw new Docx4JException(`Problem saving part ${part.partName}`, { cause: e });

package/dist/opc/index.d.mts

@@ -5,8 +5,8 @@ export { type PartStore, type PartSink, type PutOptions, MemoryPartStore, Memory
 export { ZipPartStore, ZipPartSink } from './ZipPartStore.mjs';
 export { FlatOpcPartStore, FlatOpcPartSink, type FlatOpcSinkOptions, PKG_NS } from './FlatOpcPartStore.mjs';
 export { loadPackage, type LoadOptions } from './Load.mjs';
-export { savePackage } from './Save.mjs';
-export { mcePreprocess, createMcePreprocessor, resolveAlternateContent, MCE_NS, type McePreprocessOptions } from './mce/preprocessor.mjs';
-export { UNDERSTOOD_NAMESPACES } from './mce/understood.mjs';
+export { savePackage, type ValueNormalised, type SaveReport } from './Save.mjs';
+export { mceKeep, mcePreprocess, createMcePreprocessor, resolveAlternateContent, preprocessAlternateContent, MCE_NS, KEPT_HOSTS, type McePreprocessOptions, type McBranchesDifferWarning, type ValueKeptWarning, type PartWarning, type MceResult } from './mce/preprocessor.mjs';
+export { UNDERSTOOD_NAMESPACES, UNDERSTOOD_PREFIXES, READ_ONLY_UNDERSTOOD_NAMESPACES, READ_UNDERSTOOD_NAMESPACES, READ_UNDERSTOOD_PREFIXES } from './mce/understood.mjs';
 export { Docx4JException, InvalidFormatException, PartUnrecognisedException, PartUnmarshalException, CyclicStylesException, PropertyResolverNotCreatedException } from './exceptions.mjs';
 export { parseXml, serializeXml, serializeXmlPart, createDocument, encodeText, decodeXmlText, stripXmlDeclaration, base64Encode, base64Decode, childElements, XML_DECLARATION } from '../xml/dom.mjs';

package/dist/opc/index.mjs

@@ -7,7 +7,7 @@ export { ZipPartStore, ZipPartSink } from './ZipPartStore.mjs';
 export { FlatOpcPartStore, FlatOpcPartSink, PKG_NS } from './FlatOpcPartStore.mjs';
 export { loadPackage } from './Load.mjs';
 export { savePackage } from './Save.mjs';
-export { mcePreprocess, createMcePreprocessor, resolveAlternateContent, MCE_NS } from './mce/preprocessor.mjs';
-export { UNDERSTOOD_NAMESPACES } from './mce/understood.mjs';
+export { mceKeep, mcePreprocess, createMcePreprocessor, resolveAlternateContent, preprocessAlternateContent, MCE_NS, KEPT_HOSTS } from './mce/preprocessor.mjs';
+export { UNDERSTOOD_NAMESPACES, UNDERSTOOD_PREFIXES, READ_ONLY_UNDERSTOOD_NAMESPACES, READ_UNDERSTOOD_NAMESPACES, READ_UNDERSTOOD_PREFIXES } from './mce/understood.mjs';
 export { Docx4JException, InvalidFormatException, PartUnrecognisedException, PartUnmarshalException, CyclicStylesException, PropertyResolverNotCreatedException } from './exceptions.mjs';
 export { parseXml, serializeXml, serializeXmlPart, createDocument, encodeText, decodeXmlText, stripXmlDeclaration, base64Encode, base64Decode, childElements, XML_DECLARATION } from '../xml/dom.mjs';

package/dist/opc/mce/preprocessor.d.mts

@@ -1,15 +1,96 @@
 import type { XmlPart } from '../../parts/XmlPart.mjs';
 export declare const MCE_NS = "http://schemas.openxmlformats.org/markup-compatibility/2006";
+/**
+ * The hosts whose mc:AlternateContent is kept whole on load, as `{namespace}localName`
+ * (CR-010 phase 1): a chart's `c:chartSpace` and SpreadsheetML's `workbook`.
+ */
+export declare const KEPT_HOSTS: ReadonlySet<string>;
 export interface McePreprocessOptions {
-    /** Namespaces counted as understood; defaults to the object model's modules. */
+    /** Namespaces counted as understood; defaults to `READ_UNDERSTOOD_NAMESPACES` (CR-013 D3). */
     understood?: ReadonlySet<string>;
+    /** Hosts, as `{namespace}localName`, whose mc:AlternateContent is left whole; defaults to `KEPT_HOSTS`. */
+    keptHosts?: ReadonlySet<string>;
+    /**
+     * False leaves every element whole and reports what resolving would (CR-010 phase 4): the same
+     * warnings, from the same elements, and no change to the DOM. Defaults to true.
+     */
+    resolve?: boolean;
+}
+/**
+ * What load reports about a part (CR-010 phase 1; the text extraction paper's warning channel).
+ * `mce.branches_differ`: an mc:AlternateContent whose branches' text differs, so a reader that
+ * takes another branch than this package's reads something else. `selected` is the branch this
+ * package took (`Choice(wps)`, `Fallback`); `branches` gives every branch's text, in document
+ * order, as the w:t, a:t and m:t text it holds, with whitespace collapsed.
+ */
+export interface McBranchesDifferWarning {
+    code: 'mce.branches_differ';
+    partName: string | undefined;
+    /** Where the element starts in the part, where the DOM records it (xmldom does; a browser's DOMParser does not). */
+    line?: number;
+    column?: number;
+    selected: string;
+    branches: {
+        branch: string;
+        text: string;
+    }[];
+    message: string;
+}
+/**
+ * An attribute value of Word's own WordprocessingML that its type refuses, read as Word 365 reads it
+ * rather than failing the part (CR-015 D8; the objects facade's `wordInvalidValue`, its CR-013):
+ * `value.kept.exact` where the text, trimmed of XML whitespace, is a form its type reads (`" false"`),
+ * else `value.kept.invalid` (`"yes"`, `"Single"`). The names are docx4j-python CR-018's.
+ */
+export interface ValueKeptWarning {
+    code: 'value.kept.exact' | 'value.kept.invalid';
+    partName: string | undefined;
+    /** Where the element starts in the part, where the DOM records it (xmldom does; a browser's DOMParser does not). */
+    line?: number;
+    column?: number;
+    /** The element and the attribute, as the part writes them: `w:b`, `w:val`. */
+    element: string;
+    attribute: string;
+    /** The attribute's text, as written. */
+    text: string;
+    /**
+     * What the tree holds instead: `true` for an on/off value (Word reads only exactly `false`, `off` and
+     * `0` as off), `'none'` for `w:u`'s on/off words, and undefined where the value was dropped, so the
+     * attribute reads as absent (a style's value beneath shows).
+     */
+    value: boolean | string | undefined;
+    message: string;
 }
-/** The default preprocessor, over the object model's namespaces. */
-export declare function mcePreprocess(doc: Document, _part?: XmlPart<unknown>): void;
-/** A preprocessor over a namespace set of your own. */
-export declare function createMcePreprocessor(options: McePreprocessOptions): (doc: Document, part?: XmlPart<unknown>) => void;
+/** A warning load records on a part. */
+export type PartWarning = McBranchesDifferWarning | ValueKeptWarning;
 /**
- * Resolves every mc:AlternateContent under a node, innermost first (a chosen branch may contain
- * another). Returns the number resolved.
+ * What one pass over a DOM did. `kept` counts the elements it met and left whole; it doesn't enter a
+ * branch the rule doesn't select, so an element nested there is not counted.
+ */
+export interface MceResult {
+    resolved: number;
+    kept: number;
+    warnings: PartWarning[];
+}
+/**
+ * Load's preprocessor since CR-010 phase 4: every mc:AlternateContent is kept, and the part's
+ * warnings are what resolving would report. Returns them.
+ */
+export declare function mceKeep(doc: Document, part?: XmlPart<unknown>): PartWarning[];
+/** The resolving preprocessor (`mcePreprocess: true`), over `READ_UNDERSTOOD_NAMESPACES`. Returns the part's warnings. */
+export declare function mcePreprocess(doc: Document, part?: XmlPart<unknown>): PartWarning[];
+/** A preprocessor over a namespace set (or kept hosts) of your own. */
+export declare function createMcePreprocessor(options: McePreprocessOptions): (doc: Document, part?: XmlPart<unknown>) => PartWarning[];
+/**
+ * Resolves every mc:AlternateContent under a node, outermost first, but those `KEPT_HOSTS` and the
+ * nothing-selectable rule keep (see the file comment). Returns the number resolved.
  */
 export declare function resolveAlternateContent(root: Node, understood?: ReadonlySet<string>): number;
+/**
+ * The pass itself: what it resolved, kept and reported. With `resolve: false` it visits the elements
+ * resolving would, outermost first and into the branch the rule selects, reports the same warnings,
+ * and leaves the DOM as it was.
+ */
+export declare function preprocessAlternateContent(root: Node, options?: McePreprocessOptions & {
+    partName?: string;
+}): MceResult;