@docx4j/core-ts 0.3.1 → 0.3.2

package/dist/model/content/Body.mjs

@@ -6,7 +6,7 @@ import { Paragraph } from './Paragraph.mjs';
 import { Table } from './Table.mjs';
 import { ContentControl, collectControls } from './ContentControl.mjs';
 import { sdt as sdtOf, nextSdtId } from '@docx4j/generated-objects-ts/builders/wml';
-import { controlIdScope, sdtKindFor } from '../customxml/insert.mjs';
+import { controlIdScope, sdtKindFor, declareSdtExtensions } from '../customxml/insert.mjs';
 import { InlinePicture, addImage, writableWidthEmu } from './InlinePicture.mjs';
 import { contentOf } from './ooxml.mjs';
 import { expandReplacement } from './search.mjs';
@@ -748,6 +748,7 @@ export class Body {
         this.content.length = 0;
         this.content.push(sdt);
         linkParents(sdt, this.container);
+        declareSdtExtensions(this, sdt);
         // under tracking the control itself is the insertion, its content what it was (check 30)
         const tracker = this.changeTracker;
         if (tracker)

package/dist/model/content/ContentControl.d.mts

@@ -140,7 +140,11 @@ export declare class ContentControl {
     get repeatingSectionContentControl(): RepeatingSectionContentControl | undefined;
     /** The group view, for a `w:group` control (Office JS: an object with no members of its own). */
     get groupContentControl(): GroupContentControl | undefined;
-    /** Adds or replaces a `w:sdtPr` child (extension). */
+    /**
+     * Adds or replaces a `w:sdtPr` child (extension). A `w15` element (`w15:appearance`, `w15:color`,
+     * `w15:dataBinding`, the repeating section) puts `w15` in the part's `mc:Ignorable`, as Word's own
+     * files have it: Word 2010 opens a part holding one only then (CR-002 section 40).
+     */
     putProperty(element: Element): void;
     /** Removes a `w:sdtPr` child (extension). */
     removeProperty(localPart: string, namespaceURI?: string): void;

package/dist/model/content/ContentControl.mjs

@@ -6,7 +6,8 @@ import { marshalString, deepCopy } from '@docx4j/generated-objects-ts';
 // nothing from here at run time (types only), so this direction is the only one.
 import { XmlMapping } from '../customxml/XmlMapping.mjs';
 import { CheckboxContentControl, DatePickerContentControl, ListContentControl, PictureContentControl, RepeatingSectionContentControl, GroupContentControl, checkboxRun, CHECKBOX_FONT, } from '../customxml/kinds.mjs';
-import { runsForValue, updateFromControl, PLACEHOLDER_TEXT } from '../customxml/bindings.mjs';
+import { runsForValue, updateFromControl, PLACEHOLDER_TEXT, PLACEHOLDER_STYLE } from '../customxml/bindings.mjs';
+import { declareIgnorable } from './tracking.mjs';
 import { sdtProperty, sdtKindOf, t as textItem } from '@docx4j/generated-objects-ts/builders/wml';
 import { typeNameOf, childrenOf, textOf, runItemsOf, segmentsOf, linkParents, runOf, SDT_TYPES } from './tree.mjs';
 import { Range } from './Range.mjs';
@@ -429,7 +430,11 @@ export class ContentControl {
     get groupContentControl() {
         return sdtProperty(this.sdt.sdtPr, 'group') ? new GroupContentControl() : undefined;
     }
-    /** Adds or replaces a `w:sdtPr` child (extension). */
+    /**
+     * Adds or replaces a `w:sdtPr` child (extension). A `w15` element (`w15:appearance`, `w15:color`,
+     * `w15:dataBinding`, the repeating section) puts `w15` in the part's `mc:Ignorable`, as Word's own
+     * files have it: Word 2010 opens a part holding one only then (CR-002 section 40).
+     */
     putProperty(element) {
         var _a, _b;
         var _c;
@@ -441,6 +446,8 @@ export class ContentControl {
             items[at] = element;
         else
             items.push(element);
+        if (element.name.namespaceURI === W15_NS)
+            declareIgnorable(this.parentBody.part, 'w15');
     }
     /** Removes a `w:sdtPr` child (extension). */
     removeProperty(localPart, namespaceURI) {
@@ -481,11 +488,11 @@ export class ContentControl {
      * the runs of a run-level one.
      */
     setBoundContent(runs, showingPlaceholder = false) {
-        var _a, _b;
-        var _c;
+        var _a, _b, _c, _d;
+        var _e;
         const sdt = this.sdt;
         (_a = sdt.sdtContent) !== null && _a !== void 0 ? _a : (sdt.sdtContent = {});
-        const content = ((_b = (_c = sdt.sdtContent).content) !== null && _b !== void 0 ? _b : (_c.content = []));
+        const content = ((_b = (_e = sdt.sdtContent).content) !== null && _b !== void 0 ? _b : (_e.content = []));
         const first = content.find((e) => typeNameOf(e) !== undefined);
         if (this.form === 'Run' || (first && typeNameOf(first) === 'org_docx4j_wml.R')) {
             content.length = 0;
@@ -505,6 +512,12 @@ export class ContentControl {
             }
         }
         this.isShowingPlaceholder = showingPlaceholder;
+        // The placeholder run names the PlaceholderText style, which a document made here lacks: the
+        // package splices the definition in when it is saved, as it does a new hyperlink's style. Word
+        // 2010 drops a w:rStyle naming a style the part does not define (CR-002 section 40).
+        if (showingPlaceholder) {
+            (_d = (_c = this.parentBody.package_) === null || _c === void 0 ? void 0 : _c.requireStyles) === null || _d === void 0 ? void 0 : _d.call(_c, [PLACEHOLDER_STYLE]);
+        }
     }
     /** Shows a checkbox's glyph, as Word writes it: one run in the checkbox font (docx4j checkboxRun). */
     setCheckboxGlyph(symbol) {

package/dist/model/content/Paragraph.d.mts

@@ -1,4 +1,5 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import type { CellContext } from '../properties/table.mjs';
 import { type Element, W_NS, type TextSegment, type TextViewOptions } from './tree.mjs';
 import { Font, type FontTracking } from './Font.mjs';
 import { Range } from './Range.mjs';
@@ -95,6 +96,16 @@ export declare class Paragraph {
     get effectivePPr(): wml.PPr;
     /** The paragraph mark's effective run properties (docx4j `getEffectiveParagraphMarkRPr`). */
     get effectiveParagraphMarkRPr(): wml.RPr;
+    /**
+     * Where this paragraph sits in a table, as far as its formatting goes (docx4j
+     * `PropertyResolver.cellContextOf`; CR-007): the table style its table resolves to and the
+     * conditional formats it is under. Undefined outside a table, and in a text box, note or comment
+     * reached from a cell. Every effective read of the paragraph and of its runs passes it, so a run
+     * in a header row the table style makes bold reads bold. Each read walks the table's rows; code
+     * resolving every paragraph of a large table should walk with a `TableContextTracker` instead.
+     * Needs the package's resolver, as the effective reads do.
+     */
+    get cellContext(): CellContext | undefined;
     /** The `w:pPr` a formatting read works from: the resolved one, or this paragraph's own. */
     private readPPr;
     /**
@@ -195,17 +206,6 @@ export declare class Paragraph {
      */
     delete(): void;
     private trackedDelete;
-    /**
-     * A paragraph mark deleted under tracking gives the next paragraph this paragraph's properties,
-     * as a `w:pPrChange` on it recording its own: Word, at Delete at the end of a Heading 2 with a
-     * Normal paragraph after it, wrote the next paragraph `w:pStyle Heading2` with
-     * `<w:pPrChange><w:pPr/></w:pPrChange>`, and No Markup reads the joined line as a heading
-     * throughout (the editor's `measure-word15.docx`, 2026-09-30; CR-002 section 38). The Delete
-     * counterpart of check 29's Enter. Nothing where the two paragraphs' properties are the same
-     * (check 22's deleted marks). Accepting the mark then joins into a paragraph with these
-     * properties, and rejecting puts the next paragraph's back.
-     */
-    private giveMarkPropertiesToNext;
     /**
      * The paragraph's content and its mark marked deleted, the paragraph element itself kept:
      * what the cells of a deleted table row need (a `w:tc` must keep a block-level child, and Word

package/dist/model/content/Paragraph.mjs

@@ -15,11 +15,11 @@ import { builtInOf, idOfBuiltIn, styleNameOf, styleIdOf } from './styles.mjs';
 import { cellOf } from './Table.mjs';
 import { ContentControl, collectRunControls } from './ContentControl.mjs';
 import { sdt as sdtOf, nextSdtId } from '@docx4j/generated-objects-ts/builders/wml';
-import { controlIdScope, sdtKindFor } from '../customxml/insert.mjs';
+import { controlIdScope, sdtKindFor, declareSdtExtensions } from '../customxml/insert.mjs';
 import { InlinePicture, addImage, writableWidthEmu } from './InlinePicture.mjs';
 import { contentOf } from './ooxml.mjs';
 import { commentApi } from './comments.mjs';
-import { ChangeTracker, copyRPr, markDeleted, toDeletedText, highestAnnotationId, canonical, restorePPr, wrapInsertedRuns, markHolderInserted } from './tracking.mjs';
+import { ChangeTracker, copyRPr, markDeleted, toDeletedText, highestAnnotationId, canonical, restorePPr, wrapInsertedRuns, markHolderInserted, pruneParagraphProperties } from './tracking.mjs';
 import { trackedChangesOfParagraph } from './TrackedChange.mjs';
 import { isListItem, listOf, listOrNullObjectOf, listItemOf, listItemOrNullObjectOf, startNewList, attachToList, detachFromList, } from './List.mjs';
 const TWIPS_PER_POINT = 20;
@@ -125,11 +125,23 @@ export class Paragraph {
      * changing it. Needs the package's resolver; see `Body.propertyResolver`.
      */
     get effectivePPr() {
-        return this.parentBody.propertyResolver.getEffectivePPr(this.p.pPr);
+        return this.parentBody.propertyResolver.getEffectivePPr(this.p.pPr, this.cellContext);
     }
     /** The paragraph mark's effective run properties (docx4j `getEffectiveParagraphMarkRPr`). */
     get effectiveParagraphMarkRPr() {
-        return this.parentBody.propertyResolver.getEffectiveParagraphMarkRPr(this.p.pPr);
+        return this.parentBody.propertyResolver.getEffectiveParagraphMarkRPr(this.p.pPr, this.cellContext);
+    }
+    /**
+     * Where this paragraph sits in a table, as far as its formatting goes (docx4j
+     * `PropertyResolver.cellContextOf`; CR-007): the table style its table resolves to and the
+     * conditional formats it is under. Undefined outside a table, and in a text box, note or comment
+     * reached from a cell. Every effective read of the paragraph and of its runs passes it, so a run
+     * in a header row the table style makes bold reads bold. Each read walks the table's rows; code
+     * resolving every paragraph of a large table should walk with a `TableContextTracker` instead.
+     * Needs the package's resolver, as the effective reads do.
+     */
+    get cellContext() {
+        return this.parentBody.propertyResolver.cellContextOf(this.p);
     }
     /** The `w:pPr` a formatting read works from: the resolved one, or this paragraph's own. */
     readPPr(options) {
@@ -157,6 +169,7 @@ export class Paragraph {
         else
             pPr.jc = { val };
         this.settleFormatting();
+        pruneParagraphProperties(this.p); // no empty w:pPr left (the editor's finding on 0.3.1)
     }
     /**
      * The alignment the paragraph resolves to with no `w:jc` of its own: its style's, else the
@@ -172,7 +185,8 @@ export class Paragraph {
         if (!resolver)
             return undefined;
         const { jc: _jc, pPrChange: _change, PARENT: _parent, ...rest } = this.p.pPr;
-        return alignmentOf(resolver.getEffectivePPr(rest), true);
+        // in a table cell what is inherited includes the table style's (CR-007)
+        return alignmentOf(resolver.getEffectivePPr(rest, resolver.cellContextOf(this.p)), true);
     }
     /** Indents and spacing in points, as Office JS; the effective values (CR-001 Phase B step 2). */
     get leftIndent() { var _a, _b; return ((_b = (_a = this.effectivePPr.ind) === null || _a === void 0 ? void 0 : _a.left) !== null && _b !== void 0 ? _b : 0) / TWIPS_PER_POINT; }
@@ -222,7 +236,7 @@ export class Paragraph {
         const holders = () => runsOf(this.p).map((r) => r.value);
         if ((options === null || options === void 0 ? void 0 : options.direct) === true)
             return new Font(holders, () => this.fontTracking());
-        return new Font(holders, () => this.fontTracking(), (rPr) => this.parentBody.propertyResolver.getEffectiveRPr(rPr, this.p.pPr), (rPr) => { var _a; return (_a = runFontSelectorOf(this.parentBody.package_)) === null || _a === void 0 ? void 0 : _a.asciiFontName(rPr); });
+        return new Font(holders, () => this.fontTracking(), (rPr) => this.parentBody.propertyResolver.getEffectiveRPr(rPr, this.p.pPr, this.cellContext), (rPr) => { var _a; return (_a = runFontSelectorOf(this.parentBody.package_)) === null || _a === void 0 ? void 0 : _a.asciiFontName(rPr); });
     }
     /** w14:paraId, the stable address Word gives paragraphs. */
     get paraId() {
@@ -426,42 +440,13 @@ export class Paragraph {
             return;
         }
         tracker.markParagraphDeleted(this.p);
-        this.giveMarkPropertiesToNext(tracker);
-    }
-    /**
-     * A paragraph mark deleted under tracking gives the next paragraph this paragraph's properties,
-     * as a `w:pPrChange` on it recording its own: Word, at Delete at the end of a Heading 2 with a
-     * Normal paragraph after it, wrote the next paragraph `w:pStyle Heading2` with
-     * `<w:pPrChange><w:pPr/></w:pPrChange>`, and No Markup reads the joined line as a heading
-     * throughout (the editor's `measure-word15.docx`, 2026-09-30; CR-002 section 38). The Delete
-     * counterpart of check 29's Enter. Nothing where the two paragraphs' properties are the same
-     * (check 22's deleted marks). Accepting the mark then joins into a paragraph with these
-     * properties, and rejecting puts the next paragraph's back.
-     */
-    giveMarkPropertiesToNext(tracker) {
-        const i = this.index;
-        const next = i >= 0 ? this.container[i + 1] : undefined;
-        if (!next || typeNameOf(next) !== 'org_docx4j_wml.P')
-            return;
-        const base = (pPr) => {
-            const out = {};
-            for (const [key, value] of Object.entries(pPr !== null && pPr !== void 0 ? pPr : {})) {
-                if (key !== 'TYPE_NAME' && key !== 'PARENT' && key !== 'rPr' && key !== 'sectPr' && key !== 'pPrChange' && value !== undefined)
-                    out[key] = value;
-            }
-            return out;
-        };
-        const source = base(this.p.pPr);
-        const nextP = next.value;
-        if (canonical(source) === canonical(base(nextP.pPr)))
-            return;
-        const target = new Paragraph(next, this.container, this.parentBody).pPr();
-        tracker.recordPPrChange(target);
-        for (const key of Object.keys(base(target)))
-            delete target[key];
-        for (const [key, value] of Object.entries(source))
-            target[key] = deepCopy(value);
-        linkParents(target, nextP);
+        // Word, deleting a paragraph mark ALONE under tracking, gives the next paragraph this one's
+        // properties as a w:pPrChange (CR-002 section 38 item 2, the editor's measure-word15.docx), so
+        // that the joined line reads in them. This method deletes the whole paragraph, text and mark - the
+        // engine's only mark deletion, a Range being within one paragraph - and what Word writes for that
+        // is not measured (test/README.md check 33). 0.3.1 carried the properties here too, which turned
+        // an agent's new heading, put in after a paragraph it then deleted, into body text once accepted
+        // (the editor's finding on 0.3.1); until the check, nothing is carried.
     }
     /**
      * The paragraph's content and its mark marked deleted, the paragraph element itself kept:
@@ -533,8 +518,9 @@ export class Paragraph {
         if (!same) {
             const rest = (props) => canonical(Object.fromEntries(Object.entries(props).filter(([key]) => !FORMATTING_MEMBERS.has(key))));
             const resolver = (_b = this.parentBody.package_) === null || _b === void 0 ? void 0 : _b.propertyResolverOrUndefined;
+            const cell = resolver === null || resolver === void 0 ? void 0 : resolver.cellContextOf(this.p);
             same = resolver !== undefined && rest(current) === rest(before)
-                && canonical(formattingOf(resolver.getEffectivePPr(current), true)) === canonical(formattingOf(resolver.getEffectivePPr(before), true));
+                && canonical(formattingOf(resolver.getEffectivePPr(current, cell), true)) === canonical(formattingOf(resolver.getEffectivePPr(before, cell), true));
         }
         if (same)
             restorePPr(this.p, recorded);
@@ -826,6 +812,7 @@ export class Paragraph {
         const sdt = sdtOf([this.element], { kind: sdtKindFor(kind), id: nextSdtId(controlIdScope(this.parentBody)), form: 'block' });
         this.container.splice(at, 1, sdt);
         linkParents(sdt, (_a = this.p.PARENT) !== null && _a !== void 0 ? _a : this.parentBody.container);
+        declareSdtExtensions(this.parentBody, sdt);
         // under tracking the control itself is the insertion, the paragraph what it was (check 30)
         const tracker = this.changeTracker;
         if (tracker)

package/dist/model/content/Range.mjs

@@ -6,7 +6,7 @@ import { ContentControl } from './ContentControl.mjs';
 import { sdt as sdtOf, nextSdtId, applyRunOptions, t as textElement } from '@docx4j/generated-objects-ts/builders/wml';
 import { hyperlink as hyperlinkOf } from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
 import { Namespaces } from '../../parts/Namespaces.mjs';
-import { controlIdScope, sdtKindFor } from '../customxml/insert.mjs';
+import { controlIdScope, sdtKindFor, declareSdtExtensions } from '../customxml/insert.mjs';
 import { contentOf } from './ooxml.mjs';
 import { markHolderInserted } from './tracking.mjs';
 import { searchPattern, findAll, matchesOf, expandReplacement } from './search.mjs';
@@ -74,7 +74,7 @@ export class Range {
         };
         if ((options === null || options === void 0 ? void 0 : options.direct) === true)
             return new Font(holders, () => this.paragraph.fontTracking());
-        return new Font(holders, () => this.paragraph.fontTracking(), (rPr) => this.paragraph.parentBody.propertyResolver.getEffectiveRPr(rPr, this.paragraph.p.pPr), (rPr) => { var _a; return (_a = runFontSelectorOf(this.paragraph.parentBody.package_)) === null || _a === void 0 ? void 0 : _a.asciiFontName(rPr); });
+        return new Font(holders, () => this.paragraph.fontTracking(), (rPr) => this.paragraph.parentBody.propertyResolver.getEffectiveRPr(rPr, this.paragraph.p.pPr, this.paragraph.cellContext), (rPr) => { var _a; return (_a = runFontSelectorOf(this.paragraph.parentBody.package_)) === null || _a === void 0 ? void 0 : _a.asciiFontName(rPr); });
     }
     /** The runs the span covers (a run partly inside counts). */
     get runs() {
@@ -215,6 +215,7 @@ export class Range {
         // The control is built empty first: `sdt` refuses a kind that cannot be run-level (a repeating
         // section), and that refusal must come before any run is split.
         const sdt = sdtOf([], { kind: sdtKindFor(kind), id: nextSdtId(controlIdScope(body)), form: 'run' });
+        declareSdtExtensions(body, sdt);
         if (this.start === this.end) {
             paragraph.insertItemsAt(this.start, [sdt]);
             return new ContentControl(sdt, containerOf(sdt, paragraph), body);

package/dist/model/content/stylesFacade.mjs

@@ -4,12 +4,14 @@ import { parseXml } from '../../xml/dom.mjs';
 import { DEFAULT_STYLES_XML } from '../../parts/wml/defaultStyles.mjs';
 import { SPLICEABLE_STYLES_XML } from '../../parts/wml/spliceableStyles.mjs';
 import { commentStyles } from '../../parts/wml/commentStyles.mjs';
+import { placeholderStyle } from '../../parts/wml/placeholderStyle.mjs';
 import { Docx4JException } from '../../opc/exceptions.mjs';
 /**
  * Where a definition is looked up, unmarshalled once and never handed out (a copy is spliced in):
  * the defaults `createPackage()` writes, and then the nine styles docx4j's own `styles.xml` carries
  * **commented out** - which is why a created document has no `FootnoteText` although the file
- * appears to contain one, and why this facade exists (CR-002 section 22.2).
+ * appears to contain one, and why this facade exists (CR-002 section 22.2) - with Word's two comment
+ * styles and its `PlaceholderText` after them.
  */
 let sources;
 function styleSources() {
@@ -17,8 +19,9 @@ function styleSources() {
         const read = async (xml) => { var _a; return (_a = (await unmarshalNode(parseXml(xml))).value.style) !== null && _a !== void 0 ? _a : []; };
         const defaults = await read(DEFAULT_STYLES_XML);
         // and Word's two comment styles, which the comment parts add when they are made, for a caller
-        // that makes the comment itself (CR-002 section 37)
-        return { defaults, all: [...defaults, ...(await read(SPLICEABLE_STYLES_XML)), ...commentStyles()] };
+        // that makes the comment itself (CR-002 section 37), and Word's PlaceholderText, which a
+        // placeholder run names (CR-002 section 40)
+        return { defaults, all: [...defaults, ...(await read(SPLICEABLE_STYLES_XML)), ...commentStyles(), placeholderStyle()] };
     })()));
 }
 /**
@@ -102,7 +105,7 @@ function closureOf(wanted, present, source) {
         seen.add(id);
         const template = source.find((s) => s.styleId === id);
         if (template === undefined) {
-            throw new Docx4JException(`No definition to splice for the style ${id}: neither docx4j's default styles, the nine it comments out nor the two comment styles carry one. Define it yourself on the styles part.`);
+            throw new Docx4JException(`No definition to splice for the style ${id}: neither docx4j's default styles, the nine it comments out, the two comment styles nor PlaceholderText carry one. Define it yourself on the styles part.`);
         }
         // what it is based on and linked to must be there too, and before it reads better in the part
         for (const dependency of [(_a = template.basedOn) === null || _a === void 0 ? void 0 : _a.val, (_b = template.link) === null || _b === void 0 ? void 0 : _b.val]) {

package/dist/model/content/tracking.d.mts

@@ -92,6 +92,20 @@ export declare function canonical(value: unknown): string;
 export interface TrackedPart {
     readonly contents?: unknown;
 }
+/**
+ * Makes sure the part's root lists a prefix in `mc:Ignorable`, appending it when absent, so that
+ * content in that prefix's namespace may be written in it; the facade then declares the prefix.
+ * This is docx4j's pattern - the writer of the content adds its prefix
+ * (`Paginate.declareW14Ignorable`) - and Jason's decision (CR-002 section 29). Since objects 0.3.1
+ * (its CR-008) the marshaller does it for every writer as well; these calls stay as the writer's
+ * own statement. False when there is no unmarshalled root to put it on. Every part a
+ * `Body` is over (document, header, footer, notes, comments) has a root that binds `mc:Ignorable`.
+ *
+ * The prefix must be the facade's conventional one for its namespace (`w15`, `w16du`): an
+ * application that does not know the namespace (Word 2010 and `w15`) opens the part only when the
+ * prefix is ignorable, as Word's own files declare it (CR-002 section 40).
+ */
+export declare function declareIgnorable(part: TrackedPart | undefined, prefix: string): boolean;
 /**
  * The per-package writer of revision markup. Created by the package while
  * `changeTrackingMode` is not `Off`; every content-API mutation asks its `Body` for one and,

package/dist/model/content/tracking.mjs

@@ -105,24 +105,33 @@ export function canonical(value) {
     });
 }
 /**
- * Makes sure the part's root lists `w16du` in `mc:Ignorable`, appending it when absent, so that
- * `w16du:dateUtc` may be written in it; the facade then declares the prefix. This is docx4j's
- * pattern - the writer of the content adds its prefix (`Paginate.declareW14Ignorable`) - and Jason's
- * decision (CR-002 section 29); objects CR-008 would do it for every writer. False when there is no
- * unmarshalled root to put it on. Every part a `Body` is over (document, header, footer, notes,
- * comments) has a root that binds `mc:Ignorable`.
+ * Makes sure the part's root lists a prefix in `mc:Ignorable`, appending it when absent, so that
+ * content in that prefix's namespace may be written in it; the facade then declares the prefix.
+ * This is docx4j's pattern - the writer of the content adds its prefix
+ * (`Paginate.declareW14Ignorable`) - and Jason's decision (CR-002 section 29). Since objects 0.3.1
+ * (its CR-008) the marshaller does it for every writer as well; these calls stay as the writer's
+ * own statement. False when there is no unmarshalled root to put it on. Every part a
+ * `Body` is over (document, header, footer, notes, comments) has a root that binds `mc:Ignorable`.
+ *
+ * The prefix must be the facade's conventional one for its namespace (`w15`, `w16du`): an
+ * application that does not know the namespace (Word 2010 and `w15`) opens the part only when the
+ * prefix is ignorable, as Word's own files declare it (CR-002 section 40).
  */
-function declareDateUtc(part) {
+export function declareIgnorable(part, prefix) {
     var _a;
     const contents = part === null || part === void 0 ? void 0 : part.contents;
     if (!contents || typeof contents !== 'object')
         return false;
     const root = (contents.value && typeof contents.value === 'object' ? contents.value : contents);
-    const prefixes = ((_a = root.ignorable) !== null && _a !== void 0 ? _a : '').split(/\s+/).filter((prefix) => prefix.length > 0);
-    if (!prefixes.includes('w16du'))
-        root.ignorable = [...prefixes, 'w16du'].join(' ');
+    const prefixes = ((_a = root.ignorable) !== null && _a !== void 0 ? _a : '').split(/\s+/).filter((p) => p.length > 0);
+    if (!prefixes.includes(prefix))
+        root.ignorable = [...prefixes, prefix].join(' ');
     return true;
 }
+/** `w16du` in the part's `mc:Ignorable`, so that `w16du:dateUtc` may be written in it. */
+function declareDateUtc(part) {
+    return declareIgnorable(part, 'w16du');
+}
 function element(localPart, value) {
     return { name: { namespaceURI: W_NS, localPart }, value };
 }

package/dist/model/customxml/XmlMapping.d.mts

@@ -8,7 +8,9 @@ export interface CustomXmlPartLookup {
 }
 /**
  * A subset of Office JS `Word.XmlMapping`: the content control's data binding. `isMapped` is
- * whether the control has a `w:dataBinding`; `customXmlNode` evaluates the XPath now, so it needs
+ * whether the control has a `w:dataBinding` (or, on a rich text control or a repeating section,
+ * the `w15:dataBinding` Word writes there, which is what `setMapping` writes on one: CR-002
+ * section 40); `customXmlNode` evaluates the XPath now, so it needs
  * the XPath engine to be warm (`await pkg.customXmlParts.load()` once, CR-002 section 3.6).
  */
 export declare class XmlMapping {
@@ -33,13 +35,27 @@ export declare class XmlMapping {
      * Binds the control to what the XPath selects, as Word's own mapping does: the part is the one
      * given, else the one the control is already bound to, else the first custom XML part (the
      * built-in property stores last) in which the XPath selects a node. Returns false and changes
-     * nothing when nothing is selected, which is what Word reports.
+     * nothing when nothing is selected, which is what Word reports. **The node's value then goes into
+     * the control**, whatever text it held: Office JS's `setMapping` on a plain text control holding
+     * "quick brown", on an empty one and on one already holding the value, and Word's XML Mapping
+     * Pane mapping an existing control, each showed the node's "Ann" and left the part unchanged
+     * (`test/README.md` check 34, 2026-10-03; CR-002 section 39). Before, only the binding was
+     * written and the values stayed apart until `applyBindings`.
      */
     setMapping(xpath: string, prefixMappings?: string, part?: CustomXmlPart): boolean;
-    /** Binds to a node: its canonical XPath and the prefixes that path needs, as Word writes them. */
+    /** Binds to a node: its canonical XPath and the prefixes that path needs, as Word writes them; the node's value goes into the control (check 34). */
     setMappingByNode(node: CustomXmlNode): boolean;
-    /** Removes the binding (`w:dataBinding`); the control keeps the content it shows. */
+    /** Removes the binding (`w:dataBinding` and `w15:dataBinding`); the control keeps the content it shows. */
     delete(): void;
+    /**
+     * Whether the control's binding is `w15:dataBinding`, as Word 2013 and later write it: on a rich
+     * text control (one with `w:richText`, or with no kind element at all) and on a repeating
+     * section. `w:dataBinding` on a rich text control makes it a plain text control to Word 15 and
+     * Word 2010 alike - shown from its node on open, given `<w:text/>` on saving, an edit written
+     * back as text (`test/README.md` check 35, 1f; CR-002 section 40).
+     */
+    get usesW15(): boolean;
+    /** Writes the binding in the element the control's kind takes, replacing one in the other namespace where it stood. */
     private write;
     /** The parts to try, the customer's data before Word's property stores. */
     private candidates;

package/dist/model/customxml/XmlMapping.mjs

@@ -1,11 +1,16 @@
 import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
+import * as w15el from '@docx4j/generated-objects-ts/el/org_docx4j_w15';
 import { sdtProperty } from '@docx4j/generated-objects-ts/builders/wml';
 import { canonicalXPathOf } from './xpath.mjs';
+import { applyBindingTo } from './bindings.mjs';
 /** The Word 2012 (w15) namespace; not imported from `ContentControl`, which imports this module. */
 const W15_NS = 'http://schemas.microsoft.com/office/word/2012/wordml';
+const W_NS = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
 /**
  * A subset of Office JS `Word.XmlMapping`: the content control's data binding. `isMapped` is
- * whether the control has a `w:dataBinding`; `customXmlNode` evaluates the XPath now, so it needs
+ * whether the control has a `w:dataBinding` (or, on a rich text control or a repeating section,
+ * the `w15:dataBinding` Word writes there, which is what `setMapping` writes on one: CR-002
+ * section 40); `customXmlNode` evaluates the XPath now, so it needs
  * the XPath engine to be warm (`await pkg.customXmlParts.load()` once, CR-002 section 3.6).
  */
 export class XmlMapping {
@@ -58,7 +63,12 @@ export class XmlMapping {
      * Binds the control to what the XPath selects, as Word's own mapping does: the part is the one
      * given, else the one the control is already bound to, else the first custom XML part (the
      * built-in property stores last) in which the XPath selects a node. Returns false and changes
-     * nothing when nothing is selected, which is what Word reports.
+     * nothing when nothing is selected, which is what Word reports. **The node's value then goes into
+     * the control**, whatever text it held: Office JS's `setMapping` on a plain text control holding
+     * "quick brown", on an empty one and on one already holding the value, and Word's XML Mapping
+     * Pane mapping an existing control, each showed the node's "Ann" and left the part unchanged
+     * (`test/README.md` check 34, 2026-10-03; CR-002 section 39). Before, only the binding was
+     * written and the values stayed apart until `applyBindings`.
      */
     setMapping(xpath, prefixMappings, part) {
         const candidates = part ? [part] : this.candidates();
@@ -67,25 +77,53 @@ export class XmlMapping {
             if (!node)
                 continue;
             this.write(xpath, prefixMappings !== null && prefixMappings !== void 0 ? prefixMappings : '', candidate.id);
+            applyBindingTo(this.contentControl);
             return true;
         }
         return false;
     }
-    /** Binds to a node: its canonical XPath and the prefixes that path needs, as Word writes them. */
+    /** Binds to a node: its canonical XPath and the prefixes that path needs, as Word writes them; the node's value goes into the control (check 34). */
     setMappingByNode(node) {
         const { xpath, prefixMappings } = canonicalXPathOf(node.node);
         this.write(xpath, prefixMappings, node.ownerPart.id);
+        applyBindingTo(this.contentControl);
         return true;
     }
-    /** Removes the binding (`w:dataBinding`); the control keeps the content it shows. */
+    /** Removes the binding (`w:dataBinding` and `w15:dataBinding`); the control keeps the content it shows. */
     delete() {
-        this.contentControl.removeProperty('dataBinding');
+        this.contentControl.removeProperty('dataBinding', W_NS);
+        this.contentControl.removeProperty('dataBinding', W15_NS);
     }
+    /**
+     * Whether the control's binding is `w15:dataBinding`, as Word 2013 and later write it: on a rich
+     * text control (one with `w:richText`, or with no kind element at all) and on a repeating
+     * section. `w:dataBinding` on a rich text control makes it a plain text control to Word 15 and
+     * Word 2010 alike - shown from its node on open, given `<w:text/>` on saving, an edit written
+     * back as text (`test/README.md` check 35, 1f; CR-002 section 40).
+     */
+    get usesW15() {
+        const type = this.contentControl.type;
+        return type === 'RichText' || type === 'RepeatingSection';
+    }
+    /** Writes the binding in the element the control's kind takes, replacing one in the other namespace where it stood. */
     write(xpath, prefixMappings, storeItemID) {
+        var _a, _b;
         const binding = { TYPE_NAME: 'org_docx4j_wml.CTDataBinding', xpath, storeItemID };
         if (prefixMappings !== '')
             binding.prefixMappings = prefixMappings;
-        this.contentControl.putProperty(el.dataBinding(binding));
+        const w15 = this.usesW15;
+        const element = (w15 ? w15el.dataBinding(binding) : el.dataBinding(binding));
+        const items = (_a = this.contentControl.sdt.sdtPr) === null || _a === void 0 ? void 0 : _a.rPrOrAliasOrLock;
+        const other = w15 ? W_NS : W15_NS;
+        const at = (_b = items === null || items === void 0 ? void 0 : items.findIndex((i) => i.name.localPart === 'dataBinding' && i.name.namespaceURI === other)) !== null && _b !== void 0 ? _b : -1;
+        if (items && at >= 0) {
+            if (items.some((i) => i.name.localPart === 'dataBinding' && i.name.namespaceURI === element.name.namespaceURI))
+                items.splice(at, 1);
+            else
+                items[at] = element;
+        }
+        // putProperty also lists w15 in the part's mc:Ignorable when the element is a w15 one
+        this.contentControl.putProperty(element);
     }
     /** The parts to try, the customer's data before Word's property stores. */
     candidates() {

package/dist/model/customxml/bindings.d.mts

@@ -13,6 +13,13 @@ export interface BindingResult {
     /** Controls left alone: the part is missing, the XPath selects nothing, or the kind is not handled. */
     skipped: number;
 }
+/**
+ * Whether a node's value is a Flat OPC package: what Word writes into the node of a mapped rich
+ * text control when its content is edited, a whole `pkg:package` as escaped text (`test/README.md`
+ * check 35). It is content, never a control's text - Word 2010 shows it as raw XML in a plain text
+ * control bound to the same node - so neither direction moves it as text (CR-002 section 40).
+ */
+export declare function holdsFlatOpc(value: string): boolean;
 /** docx4j ValueInserterPlainTextImpl: the runs for a value, with the w:sdtPr run properties. */
 export declare function runsForValue(value: string, rPr: wml.RPr | undefined, multiLine: boolean): Element[];
 /**
@@ -24,8 +31,8 @@ export declare function runsForValue(value: string, rPr: wml.RPr | undefined, mu
 export declare function formatDate(pattern: string, date: Date, locale?: string): string;
 /**
  * Pushes the custom XML value into one control (docx4j BindingHandler's per-sdt work). Returns
- * false when nothing was written: no binding, no part, an XPath that selects nothing, or a kind
- * this phase does not handle (pictures, explicit rich text).
+ * false when nothing was written: no binding, no part, an XPath that selects nothing, a kind
+ * this phase does not handle (pictures, explicit rich text), or a node holding a Flat OPC package.
  */
 export declare function applyBindingTo(control: ContentControl): boolean;
 /** `applyBindings` over a list of controls. */

package/dist/model/customxml/bindings.mjs

@@ -4,6 +4,16 @@ import { sdtProperty } from '@docx4j/generated-objects-ts/builders/wml';
 /** The style Word gives placeholder text, and the text docx4j's placeholder.xml carries. */
 export const PLACEHOLDER_STYLE = 'PlaceholderText';
 export const PLACEHOLDER_TEXT = 'Click here to enter text.';
+/**
+ * Whether a node's value is a Flat OPC package: what Word writes into the node of a mapped rich
+ * text control when its content is edited, a whole `pkg:package` as escaped text (`test/README.md`
+ * check 35). It is content, never a control's text - Word 2010 shows it as raw XML in a plain text
+ * control bound to the same node - so neither direction moves it as text (CR-002 section 40).
+ */
+export function holdsFlatOpc(value) {
+    return /^\s*(<\?[^>]*\?>\s*)*<([\w.-]+:)?package[\s>]/.test(value)
+        && value.includes('http://schemas.microsoft.com/office/2006/xmlPackage');
+}
 function isTrue(value) {
     const v = value.trim().toLowerCase();
     return v === 'true' || v === '1' || v === 'on' || v === 'yes';
@@ -103,8 +113,8 @@ function dateOf(value) {
 }
 /**
  * Pushes the custom XML value into one control (docx4j BindingHandler's per-sdt work). Returns
- * false when nothing was written: no binding, no part, an XPath that selects nothing, or a kind
- * this phase does not handle (pictures, explicit rich text).
+ * false when nothing was written: no binding, no part, an XPath that selects nothing, a kind
+ * this phase does not handle (pictures, explicit rich text), or a node holding a Flat OPC package.
  */
 export function applyBindingTo(control) {
     var _a;
@@ -123,6 +133,9 @@ export function applyBindingTo(control) {
         return false;
     if (isContainer(control))
         return false;
+    // A Flat OPC package is a rich text control's content, not text: no control is filled with it.
+    if (holdsFlatOpc(value))
+        return false;
     if (control.type === 'CheckBox') {
         const checkbox = control.checkboxContentControl;
         if (!checkbox)
@@ -190,6 +203,9 @@ export function updateFromControl(control) {
     // A control showing its placeholder holds no value.
     if (control.isShowingPlaceholder)
         return false;
+    // The node holds a rich text control's content as Flat OPC: text is not written over it.
+    if (holdsFlatOpc(node.text))
+        return false;
     let value = control.text;
     if (control.type === 'CheckBox') {
         const checkbox = control.checkboxContentControl;

package/dist/model/customxml/index.d.mts

@@ -3,5 +3,5 @@ export { CustomXmlPart, CustomXmlNode, CustomXmlPrefixMappingCollection, type Cu
 export { CustomXmlPartCollection, type CustomXmlHost } from './CustomXmlPartCollection.mjs';
 export { XmlMapping, type CustomXmlPartLookup } from './XmlMapping.mjs';
 export { CheckboxContentControl, DatePickerContentControl, ListContentControl, ContentControlListItem, PictureContentControl, RepeatingSectionContentControl, GroupContentControl, checkboxRun, CHECKED_SYMBOL, UNCHECKED_SYMBOL, CHECKBOX_FONT, } from './kinds.mjs';
-export { applyBindingsTo, applyBindingTo, updateFromControls, updateFromControl, runsForValue, formatDate, PLACEHOLDER_STYLE, PLACEHOLDER_TEXT, type BindingResult } from './bindings.mjs';
+export { applyBindingsTo, applyBindingTo, updateFromControls, updateFromControl, runsForValue, formatDate, holdsFlatOpc, PLACEHOLDER_STYLE, PLACEHOLDER_TEXT, type BindingResult } from './bindings.mjs';
 export { controlIdScope, sdtKindFor, isRunLevel } from './insert.mjs';

package/dist/model/customxml/index.mjs

@@ -5,5 +5,5 @@ export { CustomXmlPart, CustomXmlNode, CustomXmlPrefixMappingCollection } from '
 export { CustomXmlPartCollection } from './CustomXmlPartCollection.mjs';
 export { XmlMapping } from './XmlMapping.mjs';
 export { CheckboxContentControl, DatePickerContentControl, ListContentControl, ContentControlListItem, PictureContentControl, RepeatingSectionContentControl, GroupContentControl, checkboxRun, CHECKED_SYMBOL, UNCHECKED_SYMBOL, CHECKBOX_FONT, } from './kinds.mjs';
-export { applyBindingsTo, applyBindingTo, updateFromControls, updateFromControl, runsForValue, formatDate, PLACEHOLDER_STYLE, PLACEHOLDER_TEXT } from './bindings.mjs';
+export { applyBindingsTo, applyBindingTo, updateFromControls, updateFromControl, runsForValue, formatDate, holdsFlatOpc, PLACEHOLDER_STYLE, PLACEHOLDER_TEXT } from './bindings.mjs';
 export { controlIdScope, sdtKindFor, isRunLevel } from './insert.mjs';