@docx4j/core-ts 0.3.1 → 0.4.0

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

@@ -12,7 +12,16 @@ export interface BindingResult {
     updated: number;
     /** Controls left alone: the part is missing, the XPath selects nothing, or the kind is not handled. */
     skipped: number;
+    /** What the XHTML and picture passes left or dropped, one line each (CR-005 sections 8.2 and 9; REQ-076). */
+    notes?: string[];
 }
+/**
+ * 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,10 +33,11 @@ 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 (explicit rich text), a node holding a Flat OPC package, or a
+ * picture control whose node holds no image (`notes` says which; CR-005 section 9).
  */
-export declare function applyBindingTo(control: ContentControl): boolean;
+export declare function applyBindingTo(control: ContentControl, notes?: string[]): boolean;
 /** `applyBindings` over a list of controls. */
 export declare function applyBindingsTo(controls: ContentControl[]): BindingResult;
 /**

package/dist/model/customxml/bindings.mjs

@@ -1,9 +1,20 @@
 import { deepCopy } from '@docx4j/generated-objects-ts';
 import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
 import { sdtProperty } from '@docx4j/generated-objects-ts/builders/wml';
+import { bindPicture } from './pictures.mjs';
 /** 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,10 +114,11 @@ 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 (explicit rich text), a node holding a Flat OPC package, or a
+ * picture control whose node holds no image (`notes` says which; CR-005 section 9).
  */
-export function applyBindingTo(control) {
+export function applyBindingTo(control, notes) {
     var _a;
     const mapping = control.xmlMapping;
     if (!mapping.isMapped)
@@ -115,14 +127,22 @@ export function applyBindingTo(control) {
     if (!node)
         return false;
     const value = node.text.trim();
-    // A picture binding carries base64 image data; docx4j replaces the a:blip embed. Deferred (section 12).
-    if (control.type === 'Picture')
-        return false;
+    // A picture control's node holds base64 image data: the picture's a:blip is pointed at a new
+    // image part and the drawing kept, as docx4j's bind.xslt mode picture3 does (CR-005 section 9).
+    if (control.type === 'Picture') {
+        const outcome = bindPicture(control, value, { kind: 'keep' }, control.title || control.tag || `picture control ${control.id}`);
+        if (outcome.note)
+            notes === null || notes === void 0 ? void 0 : notes.push(outcome.note);
+        return outcome.done;
+    }
     // Explicit rich text is bound from flat OPC or XHTML in docx4j; deferred, as it is there for this route.
     if (sdtProperty(control.sdt.sdtPr, 'richText') !== undefined)
         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)
@@ -156,15 +176,18 @@ export function applyBindingTo(control) {
 /** `applyBindings` over a list of controls. */
 export function applyBindingsTo(controls) {
     const result = { bound: 0, updated: 0, skipped: 0 };
+    const notes = [];
     for (const control of controls) {
         if (!control.xmlMapping.isMapped)
             continue;
         result.bound++;
-        if (applyBindingTo(control))
+        if (applyBindingTo(control, notes))
             result.updated++;
         else
             result.skipped++;
     }
+    if (notes.length > 0)
+        result.notes = notes;
     return result;
 }
 /**
@@ -181,6 +204,8 @@ export function updateFromControl(control) {
     const node = mapping.customXmlNode;
     if (!node)
         return false;
+    // A picture control is the asynchronous pass's (updateFromPictureControl, CR-005 section 9): its
+    // image's bytes go back to the node as base64, as Word 15 writes them (check 38).
     if (control.type === 'Picture')
         return false;
     if (sdtProperty(control.sdt.sdtPr, 'richText') !== undefined)
@@ -190,6 +215,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;
@@ -220,6 +248,9 @@ export function updateFromControls(controls) {
     for (const control of controls) {
         if (!control.xmlMapping.isMapped)
             continue;
+        // counted by the picture pass, which reads the image part (CR-005 section 9)
+        if (control.type === 'Picture')
+            continue;
         result.bound++;
         if (updateFromControl(control))
             result.updated++;

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

@@ -3,5 +3,8 @@ 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';
+export { tagParamsOf, xpathsEntriesOf, selectEntryNode, OPENDOPE_XPATHS_NS, XHTML_CONTENT_TYPE, PICTURE_HANDLER, type XPathsEntry } from './opendope.mjs';
+export { applyXhtmlBindingTo, applyXhtmlBindingsTo, isXhtmlBound, type XhtmlHost, type XhtmlBindingOptions } from './xhtml.mjs';
+export { applyPictureHandlerTo, applyPictureHandlersTo, isPictureHandlerBound, bindPicture, pictureWidthOf, updateFromPictureControl, updateFromPictureControls, type PictureWidth, type PictureOutcome } from './pictures.mjs';

package/dist/model/customxml/index.mjs

@@ -5,5 +5,8 @@ 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';
+export { tagParamsOf, xpathsEntriesOf, selectEntryNode, OPENDOPE_XPATHS_NS, XHTML_CONTENT_TYPE, PICTURE_HANDLER } from './opendope.mjs';
+export { applyXhtmlBindingTo, applyXhtmlBindingsTo, isXhtmlBound } from './xhtml.mjs';
+export { applyPictureHandlerTo, applyPictureHandlersTo, isPictureHandlerBound, bindPicture, pictureWidthOf, updateFromPictureControl, updateFromPictureControls } from './pictures.mjs';

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

@@ -16,5 +16,15 @@ export declare function controlIdScope(body: {
     part?: XmlPart<unknown> | undefined;
     container: object;
 }): object;
+/**
+ * Lists `w15` in the `mc:Ignorable` of the body's part when the new control's `w:sdtPr` holds a
+ * `w15` element (a repeating section or its item): Word 2010 knows no `w15` and opens a part with
+ * one only when the prefix is ignorable (CR-002 section 40, `test/README.md` check 35).
+ */
+export declare function declareSdtExtensions(body: {
+    part?: XmlPart<unknown> | undefined;
+}, sdt: {
+    value?: unknown;
+}): void;
 /** True for a run-level item (what a Range wraps). */
 export declare function isRunLevel(element: Element): boolean;

package/dist/model/customxml/insert.mjs

@@ -1,4 +1,6 @@
 import { typeNameOf } from '../content/tree.mjs';
+import { declareIgnorable } from '../content/tracking.mjs';
+const W15_NS = 'http://schemas.microsoft.com/office/word/2012/wordml';
 /**
  * The kind the builders' `sdt` takes: Office JS's `Unknown` has no kind element, as `RichText`
  * has none (Word reports an untyped control as rich text).
@@ -15,6 +17,17 @@ export function controlIdScope(body) {
     const part = body.part;
     return (part === null || part === void 0 ? void 0 : part.isUnmarshalled) ? part.contents : body.container;
 }
+/**
+ * Lists `w15` in the `mc:Ignorable` of the body's part when the new control's `w:sdtPr` holds a
+ * `w15` element (a repeating section or its item): Word 2010 knows no `w15` and opens a part with
+ * one only when the prefix is ignorable (CR-002 section 40, `test/README.md` check 35).
+ */
+export function declareSdtExtensions(body, sdt) {
+    var _a, _b;
+    const items = (_b = (_a = sdt.value) === null || _a === void 0 ? void 0 : _a.sdtPr) === null || _b === void 0 ? void 0 : _b.rPrOrAliasOrLock;
+    if (items === null || items === void 0 ? void 0 : items.some((item) => { var _a; return ((_a = item.name) === null || _a === void 0 ? void 0 : _a.namespaceURI) === W15_NS; }))
+        declareIgnorable(body.part, 'w15');
+}
 /** True for a run-level item (what a Range wraps). */
 export function isRunLevel(element) {
     const tn = typeNameOf(element);

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

@@ -0,0 +1,32 @@
+import type { CustomXmlPartLookup } from './XmlMapping.mjs';
+import type { CustomXmlNode } from './CustomXmlPart.mjs';
+export declare const OPENDOPE_XPATHS_NS = "http://opendope.org/xpaths";
+export declare const XHTML_CONTENT_TYPE = "application/xhtml+xml";
+/** The tag's `od:Handler` value for a picture (the specification's section 9.3; CR-005 section 9). */
+export declare const PICTURE_HANDLER = "picture";
+/** The tag's parameters, `key=value` pairs separated by `&`, in order; a value is as written (the content type keeps its `/` and `+`). */
+export declare function tagParamsOf(tag: string): Map<string, string>;
+/**
+ * An XPaths part entry: `<xpath id="x1"><dataBinding storeItemID xpath prefixMappings/></xpath>`.
+ * The attributes are unqualified (`xpaths.xsd`: `attributeFormDefault="unqualified"`; docx4j's
+ * `org.opendope.xpaths.Xpaths` and its invoice.docx write them so); a `w:`-qualified form, which
+ * this package's own check 37 and 38 files were made with, is read as well.
+ */
+export interface XPathsEntry {
+    id: string;
+    storeItemID: string;
+    xpath: string;
+    prefixMappings: string;
+}
+/** The XPaths part's entries by id, from the first custom XML part in the OpenDoPE XPaths namespace; empty without one. */
+export declare function xpathsEntriesOf(parts: CustomXmlPartLookup): Map<string, XPathsEntry>;
+/**
+ * The node an `od:xpath` entry selects: the entry's XPath over the part its `storeItemID` names
+ * (the id compared without braces or case, as `getItem` does). What a tag-bound control's pass
+ * starts from; the note says why there is no node.
+ */
+export declare function selectEntryNode(entryId: string, parts: CustomXmlPartLookup): {
+    node: CustomXmlNode;
+} | {
+    note: string;
+};

package/dist/model/customxml/opendope.mjs

@@ -0,0 +1,56 @@
+export const OPENDOPE_XPATHS_NS = 'http://opendope.org/xpaths';
+export const XHTML_CONTENT_TYPE = 'application/xhtml+xml';
+/** The tag's `od:Handler` value for a picture (the specification's section 9.3; CR-005 section 9). */
+export const PICTURE_HANDLER = 'picture';
+/** The tag's parameters, `key=value` pairs separated by `&`, in order; a value is as written (the content type keeps its `/` and `+`). */
+export function tagParamsOf(tag) {
+    const out = new Map();
+    for (const pair of tag.split('&')) {
+        const eq = pair.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const key = pair.slice(0, eq).trim();
+        if (!out.has(key))
+            out.set(key, pair.slice(eq + 1).trim());
+    }
+    return out;
+}
+/** The XPaths part's entries by id, from the first custom XML part in the OpenDoPE XPaths namespace; empty without one. */
+export function xpathsEntriesOf(parts) {
+    const out = new Map();
+    const part = parts.items.find((p) => p.namespaceUri === OPENDOPE_XPATHS_NS);
+    if (!part)
+        return out;
+    const root = part.document.documentElement;
+    if (!root)
+        return out;
+    const entries = root.getElementsByTagNameNS(OPENDOPE_XPATHS_NS, 'xpath');
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        const id = entry.getAttribute('id');
+        const binding = entry.getElementsByTagNameNS(OPENDOPE_XPATHS_NS, 'dataBinding')[0];
+        if (!id || !binding)
+            continue;
+        const read = (name) => binding.getAttribute(name) || binding.getAttributeNS('http://schemas.openxmlformats.org/wordprocessingml/2006/main', name) || binding.getAttribute(`w:${name}`) || '';
+        out.set(id, { id, storeItemID: read('storeItemID'), xpath: read('xpath'), prefixMappings: read('prefixMappings') });
+    }
+    return out;
+}
+/**
+ * The node an `od:xpath` entry selects: the entry's XPath over the part its `storeItemID` names
+ * (the id compared without braces or case, as `getItem` does). What a tag-bound control's pass
+ * starts from; the note says why there is no node.
+ */
+export function selectEntryNode(entryId, parts) {
+    var _a;
+    const entry = xpathsEntriesOf(parts).get(entryId);
+    if (!entry)
+        return { note: `od:xpath=${entryId}: no such entry in the XPaths part` };
+    const part = (_a = parts.getItem(entry.storeItemID)) !== null && _a !== void 0 ? _a : parts.items.find((p) => p.id.replace(/[{}]/g, '').toLowerCase() === entry.storeItemID.replace(/[{}]/g, '').toLowerCase());
+    if (!part)
+        return { note: `od:xpath=${entryId}: no custom XML part ${entry.storeItemID}` };
+    const node = part.selectSingleNode(entry.xpath, entry.prefixMappings);
+    if (!node)
+        return { note: `od:xpath=${entryId}: ${entry.xpath} selects nothing` };
+    return { node };
+}

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

@@ -0,0 +1,54 @@
+import type { ContentControl } from '../content/ContentControl.mjs';
+import type { CustomXmlPartLookup } from './XmlMapping.mjs';
+import type { BindingResult } from './bindings.mjs';
+/**
+ * What the tag's `width` says: absent keeps the control's drawing and replaces its image; `auto`
+ * a new inline picture at its natural size, scaled down to the text width; `N` the same, scaled
+ * down to N twips when that is narrower than the text width (a value that is neither is `auto`,
+ * which is what docx4j does with one it cannot parse).
+ */
+export type PictureWidth = {
+    kind: 'keep';
+} | {
+    kind: 'auto';
+} | {
+    kind: 'twips';
+    twips: number;
+};
+export interface PictureOutcome {
+    done: boolean;
+    /** Why the control was left as it was. */
+    note?: string;
+}
+/** Whether a control is bound to a picture through its tag (`od:Handler=picture` with an `od:xpath`). */
+export declare function isPictureHandlerBound(control: ContentControl): boolean;
+/** The tag's `width` parameter, read as `PictureWidth` says. */
+export declare function pictureWidthOf(params: Map<string, string>): PictureWidth;
+/**
+ * Binds one control to a value: base64 image data (a data URL accepted). With `keep`, the first
+ * `a:blip`'s `r:embed` is pointed at a new image part and the drawing is left as it is; a picture
+ * control holding no picture gets a new inline one at its natural size instead (docx4j's pre-v3
+ * fallback), a tag-bound control holding none is left and noted. Otherwise the control's content
+ * becomes one run holding a new inline picture, sized as `PictureWidth` says, in the first
+ * paragraph of a block-level control (its properties kept) or as a run-level control's content.
+ * An empty value, a value that is not an image this package reads (PNG, JPEG, GIF, BMP; SVG where
+ * the drawing is kept, since it has no pixel size to place a new picture at), and a body with no
+ * part each leave the control as it was, with a note. The image part the control showed before
+ * stays in the package, as docx4j leaves it.
+ */
+export declare function bindPicture(control: ContentControl, value: string, width: PictureWidth, label: string): PictureOutcome;
+/** Binds one tag-bound control (shape b): the entry's node, the tag's width. */
+export declare function applyPictureHandlerTo(control: ContentControl, parts: CustomXmlPartLookup): PictureOutcome;
+/** The picture pass over the tag-bound controls, after the text bindings: counted into the result, what was left said in its notes. */
+export declare function applyPictureHandlersTo(controls: ContentControl[], parts: CustomXmlPartLookup, result: BindingResult): void;
+/**
+ * The reverse direction for a mapped picture control (docx4j's `UpdateXmlFromDocumentSurface`
+ * skips pictures; Word 15 writes the picture back, check 38): the bytes of the image part the
+ * first `a:blip` embeds, as base64, into the node. Nothing is written when the node already holds
+ * those bytes (compared decoded, so Word's line-wrapped base64 counts as the same), when the
+ * control shows no picture, or when the blip's part is not an image part. Asynchronous, since a
+ * part's bytes may still be in the container.
+ */
+export declare function updateFromPictureControl(control: ContentControl): Promise<boolean>;
+/** `updateFromContentControls`' picture pass: the mapped picture controls, counted into the result. */
+export declare function updateFromPictureControls(controls: ContentControl[], result: BindingResult): Promise<void>;