@docx4j/core-ts 0.3.1 → 0.4.0

package/dist/html/elements.d.mts

@@ -0,0 +1,19 @@
+import type { PasteBlock } from './convert.mjs';
+/** Word's character style for a link's text, as `Range.hyperlink` gives it. */
+export declare const HYPERLINK_STYLE = "Hyperlink";
+/** What the blocks need from the document before they are built: a definition per list key, a relationship per link address. */
+export interface BuildNeeds {
+    lists: {
+        key: string;
+        bullet: boolean;
+    }[];
+    links: string[];
+}
+/** The document's answers: `w:numId` per list key, `r:id` per address; undefined drops the list or the link (its text kept). */
+export interface BuildResolvers {
+    numId?: (key: string) => string | undefined;
+    relId?: (address: string) => string | undefined;
+}
+export declare function needsOf(blocks: readonly PasteBlock[]): BuildNeeds;
+/** The blocks as a WordprocessingML fragment: `w:p` and `w:tbl` elements, the prefixes undeclared (`insertXml` declares them). */
+export declare function blocksToXml(blocks: readonly PasteBlock[], resolve?: BuildResolvers): string;

package/dist/html/elements.mjs

@@ -0,0 +1,182 @@
+import { highlightNameOf } from './convert.mjs';
+/** Word's character style for a link's text, as `Range.hyperlink` gives it. */
+export const HYPERLINK_STYLE = 'Hyperlink';
+function walkBlocks(blocks, onParagraph) {
+    for (const b of blocks) {
+        if (b.kind === 'paragraph')
+            onParagraph(b);
+        else
+            for (const row of b.rows)
+                for (const c of row)
+                    walkBlocks(c.blocks, onParagraph);
+    }
+}
+export function needsOf(blocks) {
+    const lists = new Map();
+    const links = new Set();
+    walkBlocks(blocks, (p) => {
+        if (p.list && !lists.has(p.list.key))
+            lists.set(p.list.key, p.list.bullet);
+        for (const i of p.inlines)
+            if ('text' in i && i.link !== undefined)
+                links.add(i.link);
+    });
+    return { lists: [...lists].map(([key, bullet]) => ({ key, bullet })), links: [...links] };
+}
+const esc = (text) => text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const attr = (value) => String(value).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/"/g, '&quot;');
+function rPrXml(run, linked) {
+    const out = [];
+    // In the schema's order: rStyle, rFonts, b, i, strike, color, sz, szCs, highlight, u, vertAlign.
+    if (linked)
+        out.push(`<w:rStyle w:val="${HYPERLINK_STYLE}"/>`);
+    else if (run.style)
+        out.push(`<w:rStyle w:val="${attr(run.style)}"/>`);
+    if (run.fontName)
+        out.push(`<w:rFonts w:ascii="${attr(run.fontName)}" w:hAnsi="${attr(run.fontName)}" w:cs="${attr(run.fontName)}"/>`);
+    if (run.bold)
+        out.push('<w:b/>');
+    if (run.italic)
+        out.push('<w:i/>');
+    if (run.strike)
+        out.push('<w:strike/>');
+    // A link's colour is its style's, as `Range.hyperlink` leaves no direct colour on a link.
+    if (run.color && !linked)
+        out.push(`<w:color w:val="${attr(run.color === 'auto' ? 'auto' : run.color.replace(/^#/, ''))}"/>`);
+    if (run.fontSize !== undefined) {
+        const half = Math.round(run.fontSize * 2);
+        out.push(`<w:sz w:val="${half}"/><w:szCs w:val="${half}"/>`);
+    }
+    if (run.highlight) {
+        const name = highlightNameOf(run.highlight);
+        if (name)
+            out.push(`<w:highlight w:val="${name}"/>`);
+    }
+    if (run.underline)
+        out.push('<w:u w:val="single"/>');
+    if (run.vertAlign)
+        out.push(`<w:vertAlign w:val="${run.vertAlign}"/>`);
+    return out.length > 0 ? `<w:rPr>${out.join('')}</w:rPr>` : '';
+}
+function runXml(run, linked) {
+    if (run.text === '')
+        return '';
+    const space = /^\s|\s$|\s\s/.test(run.text) ? ' xml:space="preserve"' : '';
+    return `<w:r>${rPrXml(run, linked)}<w:t${space}>${esc(run.text)}</w:t></w:r>`;
+}
+function inlinesXml(inlines, resolve) {
+    var _a;
+    const out = [];
+    let i = 0;
+    while (i < inlines.length) {
+        const inline = inlines[i];
+        if ('br' in inline) {
+            out.push('<w:r><w:br/></w:r>');
+            i++;
+            continue;
+        }
+        if ('tab' in inline) {
+            out.push('<w:r><w:tab/></w:r>');
+            i++;
+            continue;
+        }
+        const rId = inline.link !== undefined ? (_a = resolve.relId) === null || _a === void 0 ? void 0 : _a.call(resolve, inline.link) : undefined;
+        if (rId === undefined) {
+            out.push(runXml(inline, false));
+            i++;
+            continue;
+        }
+        // The runs of one address under one w:hyperlink, in Word's look.
+        const runs = [];
+        while (i < inlines.length) {
+            const next = inlines[i];
+            if (!('text' in next) || next.link !== inline.link)
+                break;
+            runs.push(runXml(next, true));
+            i++;
+        }
+        out.push(`<w:hyperlink r:id="${attr(rId)}">${runs.join('')}</w:hyperlink>`);
+    }
+    return out.join('');
+}
+function pPrXml(p, resolve) {
+    var _a;
+    const out = [];
+    // In the schema's order: pStyle, numPr, spacing, ind, jc.
+    if (p.style)
+        out.push(`<w:pStyle w:val="${attr(p.style)}"/>`);
+    const numId = p.list ? (_a = resolve.numId) === null || _a === void 0 ? void 0 : _a.call(resolve, p.list.key) : undefined;
+    if (p.list && numId !== undefined)
+        out.push(`<w:numPr><w:ilvl w:val="${p.list.level}"/><w:numId w:val="${attr(numId)}"/></w:numPr>`);
+    if (p.spacing)
+        out.push(`<w:spacing w:before="${p.spacing.before}"/>`);
+    if (p.ind) {
+        const a = [];
+        if (p.ind.start !== undefined)
+            a.push(`w:left="${p.ind.start}"`);
+        if (p.ind.end !== undefined)
+            a.push(`w:right="${p.ind.end}"`);
+        if (p.ind.hanging !== undefined)
+            a.push(`w:hanging="${p.ind.hanging}"`);
+        else if (p.ind.firstLine !== undefined)
+            a.push(`w:firstLine="${p.ind.firstLine}"`);
+        if (a.length > 0)
+            out.push(`<w:ind ${a.join(' ')}/>`);
+    }
+    if (p.jc)
+        out.push(`<w:jc w:val="${attr(p.jc)}"/>`);
+    return out.length > 0 ? `<w:pPr>${out.join('')}</w:pPr>` : '';
+}
+function paragraphXml(p, resolve) {
+    return `<w:p>${pPrXml(p, resolve)}${inlinesXml(p.inlines, resolve)}</w:p>`;
+}
+/** Word's default text width shared equally where the table does not say (A4 or Letter with Word's margins: 9,026 twips). */
+const TEXT_WIDTH = 9026;
+function tableXml(t, resolve) {
+    const columns = Math.max(1, ...t.rows.map((r) => r.reduce((n, c) => n + c.colspan, 0)));
+    const widths = Array.from({ length: columns }, () => Math.floor(TEXT_WIDTH / columns));
+    const first = t.rows[0];
+    if (first && first.every((c) => c.width !== undefined && c.colspan === 1) && first.length === columns)
+        first.forEach((c, i) => { widths[i] = c.width; });
+    const widthOf = (col, span) => { var _a; let w = 0; for (let k = 0; k < span; k++)
+        w += (_a = widths[col + k]) !== null && _a !== void 0 ? _a : widths[0]; return w; };
+    const tcPr = (col, span, merge) => `<w:tcPr><w:tcW w:w="${widthOf(col, span)}" w:type="dxa"/>${span > 1 ? `<w:gridSpan w:val="${span}"/>` : ''}${merge === 'restart' ? '<w:vMerge w:val="restart"/>' : merge === 'continue' ? '<w:vMerge/>' : ''}</w:tcPr>`;
+    const cellXml = (c, col) => {
+        const blocks = c.blocks.length > 0 ? blocksToXml(c.blocks, resolve) : '<w:p/>';
+        return `<w:tc>${tcPr(col, c.colspan, c.rowspan > 1 ? 'restart' : undefined)}${blocks}</w:tc>`;
+    };
+    // A cell spanning rows holds its place in the rows below with a continuation cell, as WordprocessingML writes a vertical merge.
+    const pending = new Map();
+    const rows = t.rows.map((cells, r) => {
+        const out = [];
+        let col = 0;
+        const continuation = () => {
+            const p = pending.get(col);
+            if (!p)
+                return;
+            out.push(`<w:tc>${tcPr(col, p.span, 'continue')}<w:p/></w:tc>`);
+            if (--p.rows <= 0)
+                pending.delete(col);
+            col += p.span;
+        };
+        for (const c of cells) {
+            while (pending.has(col))
+                continuation();
+            out.push(cellXml(c, col));
+            if (c.rowspan > 1)
+                pending.set(col, { rows: c.rowspan - 1, span: c.colspan });
+            col += c.colspan;
+        }
+        while (col < columns && pending.has(col))
+            continuation();
+        const trPr = r === 0 && t.headerRow ? '<w:trPr><w:tblHeader/></w:trPr>' : '';
+        return `<w:tr>${trPr}${out.join('')}</w:tr>`;
+    });
+    const tblPr = `<w:tblPr>${t.style ? `<w:tblStyle w:val="${attr(t.style)}"/>` : ''}<w:tblW w:w="0" w:type="auto"/></w:tblPr>`;
+    const grid = `<w:tblGrid>${widths.map((w) => `<w:gridCol w:w="${w}"/>`).join('')}</w:tblGrid>`;
+    return `<w:tbl>${tblPr}${grid}${rows.join('')}</w:tbl>`;
+}
+/** The blocks as a WordprocessingML fragment: `w:p` and `w:tbl` elements, the prefixes undeclared (`insertXml` declares them). */
+export function blocksToXml(blocks, resolve = {}) {
+    return blocks.map((b) => (b.kind === 'table' ? tableXml(b, resolve) : paragraphXml(b, resolve))).join('');
+}

package/dist/html/index.d.mts

@@ -0,0 +1,2 @@
+export * from './convert.mjs';
+export * from './elements.mjs';

package/dist/html/index.mjs

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// `@docx4j/core-ts/html`: HTML to an intermediate form, and that form to WordprocessingML (CR-005 section 8).
+export * from './convert.mjs';
+export * from './elements.mjs';

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';
@@ -239,11 +239,18 @@ export class Body {
      * `values` fills it row by row. The columns are equal over the section's text width.
      */
     insertTable(rowCount, columnCount, location, values) {
+        var _a;
+        var _b;
         if (rowCount < 1 || columnCount < 1)
             throw new Docx4JException(`A table needs at least one row and one column; got ${rowCount} by ${columnCount}`);
         const rows = Array.from({ length: rowCount }, (_, r) => Array.from({ length: columnCount }, (_, c) => { var _a, _b; return (_b = (_a = values === null || values === void 0 ? void 0 : values[r]) === null || _a === void 0 ? void 0 : _a[c]) !== null && _b !== void 0 ? _b : ''; }));
         const width = writableWidthTwips(this.container);
         const element = tableOf(rows, width ? { width } : {});
+        // Word's own default (Insert Table, fixed column width Auto; the editor's check 42, Word 365): an
+        // automatic table width, no w:tblLayout, the cells in twips sharing the text width - the grid and
+        // cells the builder wrote, the table's width made automatic (CR-002 section 42.5 item 7).
+        const tblPr = ((_a = (_b = element.value).tblPr) !== null && _a !== void 0 ? _a : (_b.tblPr = {}));
+        tblPr.tblW = { w: 0, type: 'auto' };
         this.insertElement(element, location);
         return new Table(element, this.content, this);
     }
@@ -748,6 +755,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/InlinePicture.d.mts

@@ -22,7 +22,9 @@ export interface ImageInfo {
  * The size and kind of an image, from its header: PNG (IHDR and pHYs), JPEG (SOFn and the JFIF
  * APP0 densities), GIF (the logical screen descriptor) and BMP (the DIB header, with its pixels
  * per metre). docx4j reads these through XML Graphics Commons' ImageInfo; this is the same
- * information, and the same 96 dpi default when a file declares none.
+ * information, and the same 96 dpi default when a file declares none. An SVG document is told by
+ * its root element and has no pixel size (both 0): it can be the part behind an existing picture
+ * (CR-005 section 9, a binding that keeps the drawing) but not be placed as a new one.
  */
 export declare function imageInfoOf(bytes: Uint8Array): ImageInfo;
 /** The natural size of an image in EMU: pixels over the resolution it declares. */
@@ -49,10 +51,23 @@ export interface NewPicture {
     imagePart: ImagePart;
     relId: string;
 }
+/** A new image part, its relationship from the part it was added to, and what its header says. */
+export interface NewImagePart {
+    imagePart: ImagePart;
+    relId: string;
+    info: ImageInfo;
+}
 /**
  * Adds the image as a part of `source` (the main document part, or the header or footer the body
- * belongs to) with a relationship, and builds the run that shows it. docx4j:
- * `BinaryPartAbstractImage.createImagePart` then `createImageInline`.
+ * belongs to) with a relationship, and nothing else: docx4j `BinaryPartAbstractImage.createImagePart`
+ * (`BindingTraverserXSLT.createImagePartReturnRelId`, where a picture binding replaces an `r:embed`
+ * and keeps the drawing, CR-005 section 9). Throws, and adds nothing, when the bytes are not an
+ * image this package reads.
+ */
+export declare function addImagePart(source: Part, base64: string): NewImagePart;
+/**
+ * Adds the image as a part of `source` with a relationship (`addImagePart`), and builds the run
+ * that shows it. docx4j: `BinaryPartAbstractImage.createImagePart` then `createImageInline`.
  */
 export declare function addImage(source: Part, base64: string, scope: object, maxCx: number | undefined, options?: InlinePictureOptions): NewPicture;
 /** The writable width of a section in EMU (page width less the margins), for scaling. */

package/dist/model/content/InlinePicture.mjs

@@ -1,7 +1,7 @@
 import { inlinePicture } from '@docx4j/generated-objects-ts/builders/wml';
 import { Docx4JException } from '../../opc/exceptions.mjs';
 import { ContentTypes, IMAGE_CONTENT_TYPES_BY_EXTENSION } from '../../opc/ContentTypes.mjs';
-import { base64Decode, base64Encode } from '../../xml/dom.mjs';
+import { base64Decode, base64Encode, decodeXmlText } from '../../xml/dom.mjs';
 import { ImagePart } from '../../parts/BinaryPart.mjs';
 import { PartName } from '../../opc/PartName.mjs';
 import { find, runOf } from './tree.mjs';
@@ -15,7 +15,9 @@ const EMU_PER_POINT = 12700;
  * The size and kind of an image, from its header: PNG (IHDR and pHYs), JPEG (SOFn and the JFIF
  * APP0 densities), GIF (the logical screen descriptor) and BMP (the DIB header, with its pixels
  * per metre). docx4j reads these through XML Graphics Commons' ImageInfo; this is the same
- * information, and the same 96 dpi default when a file declares none.
+ * information, and the same 96 dpi default when a file declares none. An SVG document is told by
+ * its root element and has no pixel size (both 0): it can be the part behind an existing picture
+ * (CR-005 section 9, a binding that keeps the drawing) but not be placed as a new one.
  */
 export function imageInfoOf(bytes) {
     const png = pngInfo(bytes);
@@ -30,8 +32,27 @@ export function imageInfoOf(bytes) {
     const bmp = bmpInfo(bytes);
     if (bmp)
         return bmp;
+    const svg = svgInfo(bytes);
+    if (svg)
+        return svg;
     const head = Array.from(bytes.subarray(0, 8)).map((b) => b.toString(16).padStart(2, '0')).join(' ');
-    throw new Docx4JException(`Unsupported image format (first bytes ${head}); PNG, JPEG, GIF and BMP are read here`);
+    throw new Docx4JException(`Unsupported image format (first bytes ${head}); PNG, JPEG, GIF, BMP and SVG are read here`);
+}
+/** An SVG document: an XML declaration, comments and a doctype allowed before the `svg` root. */
+function svgInfo(b) {
+    if (b.length < 5)
+        return undefined;
+    let head;
+    try {
+        head = decodeXmlText(b.subarray(0, Math.min(b.length, 4096)));
+    }
+    catch {
+        return undefined;
+    }
+    const body = head.replace(/^\uFEFF/, '').replace(/<\?xml[^>]*\?>/, '').replace(/<!--[\s\S]*?-->/g, '').replace(/<!DOCTYPE[^>]*>/i, '').trimStart();
+    if (!/^<(\w+:)?svg[\s>]/.test(body))
+        return undefined;
+    return { contentType: ContentTypes.IMAGE_SVG, extension: 'svg', widthPx: 0, heightPx: 0, dpiX: DEFAULT_DPI, dpiY: DEFAULT_DPI };
 }
 function be16(b, at) { return (b[at] << 8) | b[at + 1]; }
 function be32(b, at) { return ((b[at] << 24) >>> 0) + (b[at + 1] << 16) + (b[at + 2] << 8) + b[at + 3]; }
@@ -144,11 +165,12 @@ export function naturalSizeEmu(info) {
 }
 /**
  * Adds the image as a part of `source` (the main document part, or the header or footer the body
- * belongs to) with a relationship, and builds the run that shows it. docx4j:
- * `BinaryPartAbstractImage.createImagePart` then `createImageInline`.
+ * belongs to) with a relationship, and nothing else: docx4j `BinaryPartAbstractImage.createImagePart`
+ * (`BindingTraverserXSLT.createImagePartReturnRelId`, where a picture binding replaces an `r:embed`
+ * and keeps the drawing, CR-005 section 9). Throws, and adds nothing, when the bytes are not an
+ * image this package reads.
  */
-export function addImage(source, base64, scope, maxCx, options = {}) {
-    var _a, _b;
+export function addImagePart(source, base64) {
     const pkg = source.package;
     if (!pkg)
         throw new Docx4JException('This part is not in a package yet; add it before adding an image');
@@ -157,6 +179,21 @@ export function addImage(source, base64, scope, maxCx, options = {}) {
     const imagePart = new ImagePart(freeImageName(pkg, info.extension), info.contentType);
     imagePart.setBytes(bytes);
     const rel = source.addTargetPart(imagePart);
+    return { imagePart, relId: rel.id, info };
+}
+/**
+ * Adds the image as a part of `source` with a relationship (`addImagePart`), and builds the run
+ * that shows it. docx4j: `BinaryPartAbstractImage.createImagePart` then `createImageInline`.
+ */
+export function addImage(source, base64, scope, maxCx, options = {}) {
+    var _a, _b;
+    const bytes = base64Decode(base64);
+    const info = imageInfoOf(bytes);
+    if (info.widthPx === 0 || info.heightPx === 0) {
+        throw new Docx4JException(`A ${info.extension.toUpperCase()} image has no pixel size to place it at; PNG, JPEG, GIF and BMP can be placed`);
+    }
+    const { imagePart, relId } = addImagePart(source, base64);
+    const rel = { id: relId };
     let { cx, cy } = naturalSizeEmu(info);
     if (options.width !== undefined) {
         const wanted = Math.round(options.width * EMU_PER_POINT);

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)