@docx4j/core-ts 0.5.0 → 0.7.0

package/dist/model/customxml/picturePlaceholder.mjs

@@ -0,0 +1,32 @@
+import { ImagePart } from '../../parts/BinaryPart.mjs';
+import { addImagePart, imageRunOf } from '../content/InlinePicture.mjs';
+/** docx4j's placeholder picture, a PNG, as base64. */
+export const PICTURE_PLACEHOLDER_BASE64 = 'iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAIAAAAiOjnJAAAACXBIWXMAABYlAAAWJQFJUiTwAAACVklEQVR42u3cwU3jYBCGYRtx50gDNOUOckwDOaWBHNOBm6IAuEEBSByQIkv5B1njgGLP8xx3vasVeuVh82m3f/v46uDWHnwJEBbCQlggLISFsEBYCAthgbAQFsICYSEshAXCQlgU87jkF59Px+indvuDx9b+2PTH/y+sX/6gXdd9vr/O+U08ds+PnU/HdFtOIX+iT/8rncsbaxgGX8eNGcdx4TX0xsLfChEWwgJhISwq65f8pyAzP39jpZ6eX7yxcAoRFuTcYIQ26WyPSQenEGGBsBAWwgJhISxqMEITMkLjFCIsSDNC02CExilEWCAshIWwQFgIixqM0ISM0DiFCAvSjNA0GKFxChEWCAthISwQFsKiBiM0ISM0TiHCgjQjNA1GaJxChAXCQlgIC4SFsKjBCE3ICI1TiLAgzQhNgxEapxBhgbAQFsICYSEsajBCEzJC4xQiLEgzQtNghMYpRFggLISFsEBYCIsajNCEjNA4hQgL0ozQNBihcQoRFggLYSEsEBbCogYjNCEjNE4hwoI0IzQNRmicQoQFwkJYCAuEhbCowQhNyAiNU4iwIM0ITYMRGqcQYYGwEBbCAmEhLGowQhMyQuMUIixIM0LTYITGKURYICyEhbBAWAiLGozQhIzQOIUIC9KM0DQYoXEKERYIC2EhLBAWwqIGIzQhIzROIcKCNCM0DUZoNvfGuq57avoaaz7gsdU95o3Fmt9Yu/3h8m3WtZkfgXjsnh9Lf4PVLfyAFJxChIWwQFgIC2GBsBAWwgJhISyEBcJCWAgLhIWwEBb8+AbsaRgh6xNNrAAAAABJRU5ErkJggg==';
+/** The drawing's extent, Word's: 1270000 EMU (100 points) square. */
+export const PICTURE_PLACEHOLDER_EMU = 1270000;
+/** The relationship each source part's placeholder image was added under, so that every control shares one part. */
+const added = new WeakMap();
+/** The run holding the placeholder drawing in `source` (`scope` its drawing ids'), the image part added once per part. */
+export function picturePlaceholderRun(source, scope) {
+    var _a;
+    let relId = added.get(source);
+    if (relId === undefined || !(((_a = source.relationshipsPart) === null || _a === void 0 ? void 0 : _a.getPart(relId)) instanceof ImagePart)) {
+        relId = addImagePart(source, PICTURE_PLACEHOLDER_BASE64).relId;
+        added.set(source, relId);
+    }
+    return imageRunOf(relId, scope, PICTURE_PLACEHOLDER_EMU, PICTURE_PLACEHOLDER_EMU);
+}
+/**
+ * Word's form for a picture control (`w:picture`): the flag, and its content one run holding the placeholder drawing, in
+ * a paragraph where the control is block-level. What a mapped control whose node is empty shows (CR-005 section 10, D1
+ * (a2)) and what `insertContentControl('Picture')` makes (D2), as Word's do. False, and nothing changed, where the
+ * control's body has no part to hold the image.
+ */
+export function showPicturePlaceholder(control) {
+    const source = control.parentBody.part;
+    if (!source)
+        return false;
+    control.setBoundContent([picturePlaceholderRun(source, control.parentBody.container)]);
+    control.isShowingPlaceholder = true;
+    return true;
+}

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

@@ -33,9 +33,10 @@ export declare function pictureWidthOf(params: Map<string, string>): PictureWidt
  * 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
+ * An empty value gives a picture control Word's form, the flag and a placeholder picture (`picturePlaceholderRun`;
+ * CR-005 section 10, D1 (a2)), unless it shows one already; a tag-bound control it leaves, with a note. 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;

package/dist/model/customxml/pictures.mjs

@@ -5,6 +5,7 @@ import { ImagePart } from '../../parts/BinaryPart.mjs';
 import { base64Decode, base64Encode } from '../../xml/dom.mjs';
 import { enclosingCellOf } from '../properties/table.mjs';
 import { tagParamsOf, selectEntryNode, PICTURE_HANDLER } from './opendope.mjs';
+import { showPicturePlaceholder } from './picturePlaceholder.mjs';
 const EMU_PER_TWIP = 635;
 const BLIP = 'org_docx4j_dml.CTBlip';
 /** Whether a control is bound to a picture through its tag (`od:Handler=picture` with an `od:xpath`). */
@@ -81,16 +82,26 @@ function maxWidthEmu(control, width) {
  * 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
+ * An empty value gives a picture control Word's form, the flag and a placeholder picture (`picturePlaceholderRun`;
+ * CR-005 section 10, D1 (a2)), unless it shows one already; a tag-bound control it leaves, with a note. 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 function bindPicture(control, value, width, label) {
     const base64 = base64Of(value);
-    if (base64 === '')
-        return { done: false, note: `${label}: the node is empty; the control is left as it is` };
     const source = control.parentBody.part;
+    if (base64 === '') {
+        // a picture control's empty node: Word's form, the flag and a placeholder picture (CR-005 section 10, D1 (a2));
+        // one already showing a placeholder picture is left as it is, a tag-bound control left as before
+        if (control.type !== 'Picture')
+            return { done: false, note: `${label}: the node is empty; the control is left as it is` };
+        if (control.isShowingPlaceholder && firstBlipOf(control))
+            return { done: false };
+        if (!showPicturePlaceholder(control))
+            return { done: false, note: `${label}: the control's body has no part to hold an image` };
+        return { done: true };
+    }
     if (!source)
         return { done: false, note: `${label}: the control's body has no part to hold an image` };
     if (width.kind === 'keep') {
@@ -128,7 +139,9 @@ export function applyPictureHandlerTo(control, parts) {
     const selected = selectEntryNode(entryId, parts);
     if ('note' in selected)
         return { done: false, note: selected.note };
-    return bindPicture(control, selected.node.text, pictureWidthOf(params), `od:xpath=${entryId}`);
+    const outcome = bindPicture(control, selected.node.text, pictureWidthOf(params), `od:xpath=${entryId}`);
+    // a stale storeItemID resolved as Word would (CR-020): said where the outcome has nothing else to say
+    return selected.repair && outcome.done && !outcome.note ? { ...outcome, note: selected.repair } : outcome;
 }
 /** The picture pass over the tag-bound controls, after the text bindings: counted into the result, what was left said in its notes. */
 export function applyPictureHandlersTo(controls, parts, result) {
@@ -158,7 +171,8 @@ export function applyPictureHandlersTo(controls, parts, result) {
 export async function updateFromPictureControl(control) {
     var _a, _b;
     const mapping = control.xmlMapping;
-    if (!mapping.isMapped || control.type !== 'Picture')
+    // a control showing its placeholder picture holds no picture of its node's (CR-005 section 10)
+    if (!mapping.dataBinding || control.type !== 'Picture' || control.isShowingPlaceholder)
         return false;
     const node = mapping.customXmlNode;
     if (!node)
@@ -181,7 +195,7 @@ export async function updateFromPictureControl(control) {
 /** `updateFromContentControls`' picture pass: the mapped picture controls, counted into the result. */
 export async function updateFromPictureControls(controls, result) {
     for (const control of controls) {
-        if (control.type !== 'Picture' || !control.xmlMapping.isMapped)
+        if (control.type !== 'Picture' || !control.xmlMapping.dataBinding)
             continue;
         result.bound++;
         if (await updateFromPictureControl(control))

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

@@ -0,0 +1,57 @@
+/** The `w:storeItemID`s of the core and application properties (docx4j `BindingHandler`): not custom XML parts, never repaired. */
+export declare const CORE_PROPERTIES_STOREITEMID = "{6C3C8BC8-F283-45AE-878A-BAB7291924A1}";
+export declare const EXTENDED_PROPERTIES_STOREITEMID = "{6668398D-A668-4E3E-A5EB-62B293D839F1}";
+/** An itemID without braces, lower-cased: how `getItem` compares ids, and so how a binding's names its part. */
+export declare function normaliseStoreItemId(id: string): string;
+/** Whether an ID is the core or the application properties'. */
+export declare function isPropertiesStoreItem(id: string): boolean;
+/** One custom XML part as the resolver sees it. */
+export interface StoreItemCandidate<P> {
+    readonly part: P;
+    /** Its itemID, as its properties part spells it. */
+    readonly id: string;
+    /** Its part name: the order among several that fit. */
+    readonly partName: string;
+    /** Its document element; none where the part can't be read, which then fits nothing. */
+    readonly root: Element | null | undefined;
+    /** Whether the XPath, with these prefix mappings, selects a node in it. */
+    selects(xpath: string, prefixMappings: string | undefined): boolean;
+}
+/** The part a binding is evaluated against. */
+export interface StoreItemResolution<P> {
+    readonly part: P;
+    /** True where the binding's ID names no part and this one fits its XPath: Word's repair. */
+    readonly repaired: boolean;
+    /** Where repaired, how many parts fit the XPath's first step; this one is the first, in part-name order, that selects a node. */
+    readonly fitting: number;
+}
+/**
+ * docx4j's `StoreItemResolver.resolve` rule over a package's custom XML parts:
+ * - the part the ID names, the comparison `getItem`'s (case and braces ignored); the core and application properties'
+ *   IDs are left to the caller, and never repaired;
+ * - else the parts whose document element's namespace and local name match the XPath's first step, its prefix read with
+ *   the binding's `w:prefixMappings`, else the objects package's `NAMESPACE_PREFIXES` (docx4j reads its own table); an
+ *   XPath with no named first step (`//`, `*`, an axis, an attribute) fits every part. In part-name order: one fitting part
+ *   is taken; of several, the first whose XPath selects a node, else the first (Word's choice in every fresh session,
+ *   check 73b; CR-020 D7); none, and the binding is unresolved.
+ *
+ * What a stale ID resolves to is remembered per (ID, XPath, prefix mappings), since one stale ID fits different parts for
+ * different XPaths (the two-parts probe: B7 part 1, B11 part 2), and forgotten when the parts change (an add, a delete).
+ */
+export declare class StoreItemResolver<P> {
+    private readonly candidates;
+    private readonly memo;
+    private signature;
+    constructor(candidates: () => readonly StoreItemCandidate<P>[]);
+    /** The part for a binding: named by its ID, else the one its XPath fits; undefined where none is named and none fits. */
+    resolve(storeItemId: string | undefined, xpath: string | undefined, prefixMappings: string | undefined): StoreItemResolution<P> | undefined;
+}
+/**
+ * The XPath's first step as its namespace and local name, with the binding's prefix mappings (`/p:root[1]/p:b7[1]` with
+ * `xmlns:p='urn:x'` is `urn:x` and `root`); undefined where the XPath does not start with a named step, when every part
+ * fits. docx4j's `StoreItemResolver.firstStep`.
+ */
+export declare function firstStep(xpath: string | undefined, prefixMappings: string | undefined): {
+    namespaceURI: string;
+    localName: string;
+} | undefined;

package/dist/model/customxml/storeItems.mjs

@@ -0,0 +1,122 @@
+// CR-020: docx4j's StoreItemResolver (its CR-058 D4, `35cdeaee6`, released in 17.3.5): the custom XML part a binding is
+// evaluated against. The part its `w:storeItemID` names, or, where that names no part, the one its XPath fits, as Word
+// repairs such a binding on open (Word 365, 22 and 23 October 2026, and checks 73 and 73b: the control shows the part's
+// value, Office JS's `customXmlPart` is that part, and the save writes its ID into `w:storeItemID`). Shared by every
+// reader and the bind (CR-020 D1): the text model's bound values, `XmlMapping.customXmlPart` and `customXmlNode`,
+// `applyBindings`, `updateFromContentControls` and the `od:xpath` passes, so they all name the part Word binds.
+import { NAMESPACE_PREFIXES } from '@docx4j/generated-objects-ts';
+import { parsePrefixMappings } from './xpath.mjs';
+/** The `w:storeItemID`s of the core and application properties (docx4j `BindingHandler`): not custom XML parts, never repaired. */
+export const CORE_PROPERTIES_STOREITEMID = '{6C3C8BC8-F283-45AE-878A-BAB7291924A1}';
+export const EXTENDED_PROPERTIES_STOREITEMID = '{6668398D-A668-4E3E-A5EB-62B293D839F1}';
+/** An itemID without braces, lower-cased: how `getItem` compares ids, and so how a binding's names its part. */
+export function normaliseStoreItemId(id) {
+    return id.trim().replace(/[{}]/g, '').toLowerCase();
+}
+/** Whether an ID is the core or the application properties'. */
+export function isPropertiesStoreItem(id) {
+    const key = normaliseStoreItemId(id);
+    return key === normaliseStoreItemId(CORE_PROPERTIES_STOREITEMID) || key === normaliseStoreItemId(EXTENDED_PROPERTIES_STOREITEMID);
+}
+/**
+ * docx4j's `StoreItemResolver.resolve` rule over a package's custom XML parts:
+ * - the part the ID names, the comparison `getItem`'s (case and braces ignored); the core and application properties'
+ *   IDs are left to the caller, and never repaired;
+ * - else the parts whose document element's namespace and local name match the XPath's first step, its prefix read with
+ *   the binding's `w:prefixMappings`, else the objects package's `NAMESPACE_PREFIXES` (docx4j reads its own table); an
+ *   XPath with no named first step (`//`, `*`, an axis, an attribute) fits every part. In part-name order: one fitting part
+ *   is taken; of several, the first whose XPath selects a node, else the first (Word's choice in every fresh session,
+ *   check 73b; CR-020 D7); none, and the binding is unresolved.
+ *
+ * What a stale ID resolves to is remembered per (ID, XPath, prefix mappings), since one stale ID fits different parts for
+ * different XPaths (the two-parts probe: B7 part 1, B11 part 2), and forgotten when the parts change (an add, a delete).
+ */
+export class StoreItemResolver {
+    constructor(candidates) {
+        this.candidates = candidates;
+        this.memo = new Map();
+        this.signature = '';
+    }
+    /** The part for a binding: named by its ID, else the one its XPath fits; undefined where none is named and none fits. */
+    resolve(storeItemId, xpath, prefixMappings) {
+        var _a;
+        if (!storeItemId)
+            return undefined;
+        const all = this.candidates();
+        const key = normaliseStoreItemId(storeItemId);
+        const named = all.find((candidate) => normaliseStoreItemId(candidate.id) === key);
+        if (named)
+            return { part: named.part, repaired: false, fitting: 0 };
+        if (isPropertiesStoreItem(storeItemId))
+            return undefined;
+        const signature = all.map((candidate) => `${normaliseStoreItemId(candidate.id)} ${candidate.partName}`).join('|');
+        if (signature !== this.signature) {
+            this.memo.clear();
+            this.signature = signature;
+        }
+        const memoKey = `${key}|${xpath !== null && xpath !== void 0 ? xpath : ''}|${prefixMappings !== null && prefixMappings !== void 0 ? prefixMappings : ''}`;
+        let resolved = this.memo.get(memoKey);
+        if (resolved === undefined) {
+            resolved = (_a = repair(all, xpath !== null && xpath !== void 0 ? xpath : '', prefixMappings)) !== null && _a !== void 0 ? _a : null;
+            this.memo.set(memoKey, resolved);
+        }
+        return resolved !== null && resolved !== void 0 ? resolved : undefined;
+    }
+}
+function repair(all, xpath, prefixMappings) {
+    const step = firstStep(xpath, prefixMappings);
+    const fitting = all.filter((candidate) => {
+        var _a, _b;
+        const root = candidate.root;
+        if (!root)
+            return false;
+        return step === undefined || (((_a = root.namespaceURI) !== null && _a !== void 0 ? _a : '') === step.namespaceURI && ((_b = root.localName) !== null && _b !== void 0 ? _b : root.nodeName) === step.localName);
+    }).sort((a, b) => (a.partName < b.partName ? -1 : a.partName > b.partName ? 1 : 0));
+    if (fitting.length === 0)
+        return undefined;
+    if (fitting.length === 1)
+        return { part: fitting[0].part, repaired: true, fitting: 1 };
+    const selecting = fitting.find((candidate) => {
+        try {
+            return candidate.selects(xpath, prefixMappings);
+        }
+        catch {
+            return false;
+        }
+    });
+    return { part: (selecting !== null && selecting !== void 0 ? selecting : fitting[0]).part, repaired: true, fitting: fitting.length };
+}
+/** The objects package's prefixes, prefix to namespace: what a prefix the binding doesn't map reads as. */
+const NAMESPACES_BY_PREFIX = (() => {
+    const out = {};
+    for (const [uri, prefix] of Object.entries(NAMESPACE_PREFIXES))
+        if (prefix !== '' && !(prefix in out))
+            out[prefix] = uri;
+    return out;
+})();
+/**
+ * The XPath's first step as its namespace and local name, with the binding's prefix mappings (`/p:root[1]/p:b7[1]` with
+ * `xmlns:p='urn:x'` is `urn:x` and `root`); undefined where the XPath does not start with a named step, when every part
+ * fits. docx4j's `StoreItemResolver.firstStep`.
+ */
+export function firstStep(xpath, prefixMappings) {
+    var _a, _b;
+    if (xpath === undefined)
+        return undefined;
+    let s = xpath.trim();
+    if (s.startsWith('//'))
+        return undefined;
+    if (s.startsWith('/'))
+        s = s.slice(1);
+    const end = s.search(/[/[(\s]/);
+    const step = end < 0 ? s : s.slice(0, end);
+    if (step === '' || step === '*' || step === '.' || step === '..' || step.includes('::') || step.startsWith('@'))
+        return undefined;
+    const colon = step.indexOf(':');
+    const prefix = colon < 0 ? '' : step.slice(0, colon);
+    const localName = colon < 0 ? step : step.slice(colon + 1);
+    if (localName === '' || localName === '*')
+        return undefined;
+    const namespaceURI = prefix === '' ? '' : ((_b = (_a = parsePrefixMappings(prefixMappings)[prefix]) !== null && _a !== void 0 ? _a : NAMESPACES_BY_PREFIX[prefix]) !== null && _b !== void 0 ? _b : '');
+    return { namespaceURI, localName };
+}

package/dist/model/customxml/xhtml.mjs

@@ -1,10 +1,11 @@
 import { deepCopy } from '@docx4j/generated-objects-ts';
 import { Namespaces } from '../../parts/Namespaces.mjs';
-import { typeNameOf, linkParents, childrenOf } from '../content/tree.mjs';
+import { typeNameOf, linkParents, childrenOf, writingEveryBranch } from '../content/tree.mjs';
 import { contentOf } from '../content/ooxml.mjs';
+import { wrappingCellOf, endWithParagraph } from '../content/tableRules.mjs';
 import { convertHtml, styleLookupOf } from '../../html/convert.mjs';
 import { blocksToXml, needsOf, HYPERLINK_STYLE } from '../../html/elements.mjs';
-import { tagParamsOf, xpathsEntriesOf, XHTML_CONTENT_TYPE } from './opendope.mjs';
+import { tagParamsOf, selectEntryNode, XHTML_CONTENT_TYPE } from './opendope.mjs';
 /** Whether a control is bound to XHTML through its tag. */
 export function isXhtmlBound(control) {
     const params = tagParamsOf(control.tag);
@@ -67,20 +68,15 @@ function inlineContentOf(paragraph) {
  * `dropped` (a run-level control's blocks after the first, and what the converter dropped).
  */
 export async function applyXhtmlBindingTo(control, parts, host, options = {}) {
-    var _a, _b, _c, _d, _e, _f, _g, _h;
-    var _j;
+    var _a, _b, _c, _d, _e, _f, _g;
+    var _h;
     const params = tagParamsOf(control.tag);
     const entryId = params.get('od:xpath');
-    const entry = xpathsEntriesOf(parts).get(entryId);
-    if (!entry)
-        return { done: false, 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 { done: false, note: `od:xpath=${entryId}: no custom XML part ${entry.storeItemID}` };
-    const node = part.selectSingleNode(entry.xpath, entry.prefixMappings);
-    if (!node)
-        return { done: false, note: `od:xpath=${entryId}: ${entry.xpath} selects nothing` };
-    const parser = (_b = options.parser) !== null && _b !== void 0 ? _b : (typeof DOMParser === 'function' ? (h) => new DOMParser().parseFromString(h, 'text/html') : undefined);
+    const selected = selectEntryNode(entryId, parts);
+    if ('note' in selected)
+        return { done: false, note: selected.note };
+    const { node, repair } = selected;
+    const parser = (_a = options.parser) !== null && _a !== void 0 ? _a : (typeof DOMParser === 'function' ? (h) => new DOMParser().parseFromString(h, 'text/html') : undefined);
     if (!parser)
         return { done: false, note: `od:xpath=${entryId}: XHTML needs an HTML parser (applyBindings({ html: { parser } }))` };
     const converted = convertHtml(node.text, await lookupFor(host), { parser });
@@ -92,7 +88,7 @@ export async function applyXhtmlBindingTo(control, parts, host, options = {}) {
             await host.styles.ensure(converted.report.stylesWanted);
         }
         catch {
-            dropped['styles the defaults lack'] = ((_c = dropped['styles the defaults lack']) !== null && _c !== void 0 ? _c : 0) + converted.report.stylesWanted.length;
+            dropped['styles the defaults lack'] = ((_b = dropped['styles the defaults lack']) !== null && _b !== void 0 ? _b : 0) + converted.report.stylesWanted.length;
         }
     }
     const needs = needsOf(blocks);
@@ -109,26 +105,26 @@ export async function applyXhtmlBindingTo(control, parts, host, options = {}) {
             lists.set(key, host.numbering.restart(firstNumbered));
     }
     const links = new Map();
-    const rels = needs.links.length > 0 ? (_d = control.parentBody.part) === null || _d === void 0 ? void 0 : _d.getRelationshipsPart(true) : undefined;
+    const rels = needs.links.length > 0 ? (_c = control.parentBody.part) === null || _c === void 0 ? void 0 : _c.getRelationshipsPart(true) : undefined;
     if (rels) {
         for (const address of needs.links)
             links.set(address, rels.addExternalRelationship(Namespaces.HYPERLINK, address).id);
         host.requireStyles([HYPERLINK_STYLE]);
     }
     else if (needs.links.length > 0)
-        dropped['links'] = ((_e = dropped['links']) !== null && _e !== void 0 ? _e : 0) + needs.links.length;
+        dropped['links'] = ((_d = dropped['links']) !== null && _d !== void 0 ? _d : 0) + needs.links.length;
     const elements = await contentOf(blocksToXml(blocks, { numId: (key) => lists.get(key), relId: (address) => links.get(address) }));
     applyRunProperties(elements, control.runProperties);
     const sdt = control.sdt;
-    (_f = sdt.sdtContent) !== null && _f !== void 0 ? _f : (sdt.sdtContent = {});
-    const content = ((_g = (_j = sdt.sdtContent).content) !== null && _g !== void 0 ? _g : (_j.content = []));
+    (_e = sdt.sdtContent) !== null && _e !== void 0 ? _e : (sdt.sdtContent = {});
+    const content = ((_f = (_h = sdt.sdtContent).content) !== null && _f !== void 0 ? _f : (_h.content = []));
     if (control.form === 'Run') {
         // A run-level control holds inline content: the first paragraph's, the rest reported.
         const first = elements.find((e) => typeNameOf(e) === 'org_docx4j_wml.P');
         const inlines = first ? inlineContentOf(first) : [];
         const rest = elements.length - (first ? 1 : 0);
         if (rest > 0)
-            dropped['blocks after the first, in a run-level control'] = ((_h = dropped['blocks after the first, in a run-level control']) !== null && _h !== void 0 ? _h : 0) + rest;
+            dropped['blocks after the first, in a run-level control'] = ((_g = dropped['blocks after the first, in a run-level control']) !== null && _g !== void 0 ? _g : 0) + rest;
         content.length = 0;
         content.push(...inlines);
         linkParents(content, sdt.sdtContent);
@@ -137,9 +133,14 @@ export async function applyXhtmlBindingTo(control, parts, host, options = {}) {
         content.length = 0;
         content.push(...elements);
         linkParents(content, sdt.sdtContent);
+        // markup ending in a table, in a cell's control: the cell ends with a paragraph after it, docx4j's repair (CR-002 section 55)
+        const cell = wrappingCellOf(sdt.PARENT);
+        if (cell)
+            endWithParagraph(cell);
     }
-    control.isShowingPlaceholder = false;
-    return Object.keys(dropped).length > 0 ? { done: true, dropped } : { done: true };
+    // a control in a branch of a kept mc:AlternateContent too: the pass reaches every branch (CR-013 phase 3)
+    writingEveryBranch(() => { control.isShowingPlaceholder = false; });
+    return { done: true, ...(repair ? { note: repair } : {}), ...(Object.keys(dropped).length > 0 ? { dropped } : {}) };
 }
 /** The XHTML pass over the controls, after the text bindings: counted into the result, what was left said in its notes. */
 export async function applyXhtmlBindingsTo(controls, parts, host, result, options = {}) {

package/dist/model/dateZone.d.mts

@@ -0,0 +1,25 @@
+/** The fields a wall clock shows: `month` 1 to 12, `hour` 0 to 23. */
+export interface WallClock {
+    readonly year: number;
+    readonly month: number;
+    readonly day: number;
+    readonly hour: number;
+    readonly minute: number;
+    readonly second: number;
+}
+/** The runtime's zone, an IANA id (`Australia/Sydney`; `UTC` where the runtime has no better answer). */
+export declare function runtimeTimeZone(): string;
+/**
+ * `id` when the runtime's `Intl` knows it as a zone, else a `RangeError` naming it: a package's
+ * `dateTimeZone` is refused at the set, never ignored, since a wrong zone shifts every stamp.
+ */
+export declare function assertTimeZone(id: string): string;
+/** The wall clock `date` shows in `zone`; the runtime's zone where `zone` is undefined. */
+export declare function wallClockIn(date: Date, zone: string | undefined): WallClock;
+/**
+ * The instant at which a wall clock in `zone` shows `clock`; the runtime's zone where `zone` is
+ * undefined. Found by offset: the clock taken as UTC, corrected by what the zone shows for that
+ * guess, twice, which settles across a daylight-saving step; a clock time that does not exist on a
+ * spring-forward day gives the instant an hour on, as `Date` does for the runtime's zone.
+ */
+export declare function instantOf(clock: WallClock, zone: string | undefined): Date;

package/dist/model/dateZone.mjs

@@ -0,0 +1,57 @@
+// The package's time zone (CR-018; the portfolio's date rule of 2026-10-28, docx4j CR-067 D12): an instant a document
+// holds (a revision's or a comment's stamp, a date field) is shown, and a `w:date` without `dateUtc` read, in the zone
+// the caller sets on the package it is working on, else the runtime's. Word writes such a `w:date` as the author's local
+// wall-clock time labelled `Z` (CR-002 section 29, check 23), so the zone is what turns it into an instant and back.
+// Under Office JS the runtime's zone is the client's; under Node on a server it is the server's, hence the option.
+// Nothing here reaches a saved file as such: the zone decides which wall-clock fields are written for an instant.
+/** The runtime's zone, an IANA id (`Australia/Sydney`; `UTC` where the runtime has no better answer). */
+export function runtimeTimeZone() {
+    return new Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+}
+/**
+ * `id` when the runtime's `Intl` knows it as a zone, else a `RangeError` naming it: a package's
+ * `dateTimeZone` is refused at the set, never ignored, since a wrong zone shifts every stamp.
+ */
+export function assertTimeZone(id) {
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: id });
+    }
+    catch {
+        throw new RangeError(`Not a time zone this runtime knows: ${JSON.stringify(id)} (an IANA id, such as "Australia/Sydney")`);
+    }
+    return id;
+}
+/** The wall clock `date` shows in `zone`; the runtime's zone where `zone` is undefined. */
+export function wallClockIn(date, zone) {
+    if (zone === undefined) {
+        return {
+            year: date.getFullYear(), month: date.getMonth() + 1, day: date.getDate(),
+            hour: date.getHours(), minute: date.getMinutes(), second: date.getSeconds(),
+        };
+    }
+    const parts = new Intl.DateTimeFormat('en-US', {
+        timeZone: zone, hour12: false, year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit',
+    }).formatToParts(date);
+    const field = (type) => { var _a, _b; return Number((_b = (_a = parts.find((p) => p.type === type)) === null || _a === void 0 ? void 0 : _a.value) !== null && _b !== void 0 ? _b : NaN); };
+    return {
+        year: field('year'), month: field('month'), day: field('day'),
+        hour: field('hour') % 24, minute: field('minute'), second: field('second'), // hour12: false gives 24 at midnight on some engines
+    };
+}
+/**
+ * The instant at which a wall clock in `zone` shows `clock`; the runtime's zone where `zone` is
+ * undefined. Found by offset: the clock taken as UTC, corrected by what the zone shows for that
+ * guess, twice, which settles across a daylight-saving step; a clock time that does not exist on a
+ * spring-forward day gives the instant an hour on, as `Date` does for the runtime's zone.
+ */
+export function instantOf(clock, zone) {
+    if (zone === undefined)
+        return new Date(clock.year, clock.month - 1, clock.day, clock.hour, clock.minute, clock.second);
+    const asUtc = Date.UTC(clock.year, clock.month - 1, clock.day, clock.hour, clock.minute, clock.second);
+    let guess = asUtc;
+    for (let i = 0; i < 2; i++) {
+        const shown = wallClockIn(new Date(guess), zone);
+        guess -= Date.UTC(shown.year, shown.month - 1, shown.day, shown.hour, shown.minute, shown.second) - asUtc;
+    }
+    return new Date(guess);
+}

package/dist/model/index.d.mts

@@ -2,5 +2,8 @@ export * from './content/index.mjs';
 export * from './properties/index.mjs';
 export * from './listnumbering/index.mjs';
 export * from './fonts/index.mjs';
+export * from './color/index.mjs';
 export * from './customxml/index.mjs';
+export * from './text/index.mjs';
 export { toApiScript, type ApiScriptOptions, type ApiScriptTarget } from '../office-js/toApiScript.mjs';
+export { keptRange, rangeOf, describeReading, isUnmeasured, UNMEASURED_RANGE, type KeptRange } from './wordIntegers.mjs';

package/dist/model/index.mjs

@@ -7,8 +7,13 @@ export * from './properties/index.mjs';
 export * from './listnumbering/index.mjs';
 // CR-001 Phase B step 4: RunFontSelector, the Mapper and the default theme.
 export * from './fonts/index.mjs';
+// CR-008 phase 2: colours as Office draws them (ThemeColors, WordColors, DrawingMLColors, SpreadsheetColors).
+export * from './color/index.mjs';
 // CR-002 phase E: custom XML parts, XML mapping, the XPath engine, the typed content controls.
 export * from './customxml/index.mjs';
+// CR-012: the text model (Texts, the block model, plain text).
+export * from './text/index.mjs';
 // The source generator of CR-002 phase I: the content-API calls that reproduce a paragraph, a
 // range or a table. The `Word` shim it lives next to stays on the ./office-js subpath.
 export { toApiScript } from '../office-js/toApiScript.mjs';
+export { keptRange, rangeOf, describeReading, isUnmeasured, UNMEASURED_RANGE } from './wordIntegers.mjs';

package/dist/model/listnumbering/Emulator.d.mts

@@ -64,7 +64,8 @@ export interface NumberingResult {
     ilvl: string | undefined;
     /** The level definition, merged. Not docx4j's: a port convenience for CR-002 phase H. */
     level: LevelDefinition | undefined;
-    /** The counter's value at this level, before formatting. Not docx4j's. */
+    /** The count this paragraph's level shows (the 3 of "1.3."), its counter once this paragraph is
+     *  counted. docx4j `getValue()` (17.3.4), which this preceded. */
     count: number | undefined;
     /** No label was produced. docx4j returns an *empty* `ResultTriple` where a `w:num` or its
      *  level has no definition; this flags that case rather than leaving every member undefined
@@ -117,8 +118,32 @@ export declare class Emulator {
      * to.  The style itself, or any style it is based on, counts as the level's own.  Direct
      * formatting is never suppressed: a paragraph whose *own* `w:numPr` names such a level is
      * numbered.
+     *
+     * A level which names no style belongs to one all the same: the first paragraph style in
+     * styles.xml whose own `w:numPr` names it ({@link levelStyleId}, docx4j 17.3.4, measured in
+     * Word 365 on the three documents of docx4j's `LevelOwnerTest`).  Of two styles carrying such
+     * a level Word numbers the first in styles.xml - whatever their names, whichever the document
+     * uses first, whether or not it uses that style at all - and gives the other style's paragraphs
+     * no label and no count.  They keep the level's indent, which the effective indent already
+     * gives them.  A paragraph naming no style is the default paragraph style's in this check.
      */
     styleLinkedElsewhere(numId: string, ilvl: string, pStyleVal: string | undefined): boolean;
+    /**
+     * The paragraph style a numbering level belongs to: the one its `w:lvl/w:pStyle` names (the
+     * `w:num`'s override level's first, as {@link NumberingDefinitions.getLinkedStyleId} reads it),
+     * else the first paragraph style in styles.xml whose own `w:numPr` names a `w:num` on the same
+     * `w:abstractNum` at that level (its `w:ilvl`, 0 where it states none).  Undefined where neither:
+     * no style carries the level, so a paragraph reaches it only through its own `w:numPr`.
+     *
+     * The level is the `w:abstractNum`'s, not a `w:num`'s: a style reaching it through a second
+     * `w:num` is on the same level, even where that `w:num` overrides it with a `w:lvl` of its own.
+     * A style's level is its `w:numPr`'s `w:ilvl`, not the level whose `w:pStyle` names it, as Word
+     * reads it (ECMA-376 17.9.24 has the naming level). docx4j `Emulator.levelStyleId` (17.3.4).
+     *
+     * @param numId a `w:numId` (not 0)
+     * @param ilvl  a `w:ilvl`; undefined or empty for 0
+     */
+    levelStyleId(numId: string, ilvl: string | undefined): string | undefined;
     /**
      * The one resolution of numId and ilvl for a paragraph. docx4j `Emulator.resolve`
      * (CR-014 phase 3, which collapsed `getNumber`'s and `getInd`'s two copies onto it).
@@ -135,13 +160,18 @@ export declare class Emulator {
     resolve(pStyleVal: string | undefined, numId: string | undefined, ilvl: string | undefined, directNumPr: boolean): NumRef;
     /**
      * The numbering reference a paragraph resolves to, without taking a number and without
-     * touching any state. docx4j `Emulator.numRefFor` (17.1.1); never undefined.
+     * touching any state. docx4j `Emulator.numRefFor` (17.1.1); never undefined.  A paragraph with
+     * no `w:pPr` resolves as an empty one, against the default paragraph style, as
+     * {@link getNumber} resolves it (docx4j `c283dffdb`, 17.3.4).
      */
     numRefFor(pPr: wml.PPr | undefined): NumRef;
     /**
      * The next number for a paragraph, from its `w:pPr` (its own `w:numPr`, else its style's),
      * counted in `state` or in this emulator's default state.
      *
+     * A paragraph with no `w:pPr` resolves as one with an empty `w:pPr` does, against the default
+     * paragraph style, which may be numbered (docx4j 17.3.4; before, it was not numbered).
+     *
      * @returns undefined where the paragraph is not numbered
      */
     getNumber(pPr: wml.PPr | undefined, state?: NumberingState): NumberingResult | undefined;
@@ -176,11 +206,13 @@ export declare class Emulator {
     static peek(pkg: NumberedPackageLike, pPr: wml.PPr | undefined, state?: NumberingState): NumberingResult | undefined;
     /**
      * docx4j `Emulator.numRefFor(wmlPackage, pPr)`: where this paragraph's numbering resolves to,
-     * before any counting.  Never undefined; a package with no numbering part, a null `w:pPr` or
-     * a package whose `PropertyResolver` has not been built each answer {@link NumRef.notNumbered}
-     * with the reason.
+     * before any counting.  Never undefined; a package with no numbering part or a package whose
+     * `PropertyResolver` has not been built each answer {@link NumRef.notNumbered} with the reason.
+     * A null `w:pPr` resolves as an empty one (docx4j `c283dffdb`, 17.3.4).
      */
     static numRefFor(pkg: NumberedPackageLike | undefined, pPr: wml.PPr | undefined): NumRef;
+    /** docx4j `Emulator.levelStyleId(numberingPart, numId, levelId)`: the paragraph style a level belongs to. */
+    static levelStyleId(part: NumberingPartLike, numId: string, ilvl: string | undefined): string | undefined;
     /** docx4j `Emulator.getInd(wmlPackage, pStyleVal, numId, levelId)`. */
     static getInd(pkg: NumberedPackageLike, pStyleVal: string | undefined, numId: string | undefined, ilvl: string | undefined): wml.PPrBase.Ind | undefined;
     toString(): string;