@cj-tech-master/excelts 9.4.2 → 9.5.0

package/dist/esm/modules/word/document.js

@@ -0,0 +1,1795 @@
+/**
+ * DOCX Module - Document Builder
+ *
+ * High-level fluent API for constructing DOCX documents programmatically.
+ * Provides convenience methods for common operations including comments,
+ * track changes, TOC, math, text boxes, checkboxes, and custom properties.
+ */
+import { packageDocx } from "./docx-packager.js";
+import { readDocx } from "./docx-reader.js";
+import { bytesToBase64 } from "./internal-utils.js";
+// =============================================================================
+// Helper Builders
+// =============================================================================
+/** Create a text run. */
+export function text(content, properties) {
+    return { properties, content: [{ type: "text", text: content }] };
+}
+/** Create a bold text run. */
+export function bold(content, properties) {
+    return text(content, { ...properties, bold: true });
+}
+/** Create an italic text run. */
+export function italic(content, properties) {
+    return text(content, { ...properties, italic: true });
+}
+/** Create a run with a page break. */
+export function pageBreak() {
+    return { content: [{ type: "break", breakType: "page" }] };
+}
+/** Create a run with a line break. */
+export function lineBreak() {
+    return { content: [{ type: "break" }] };
+}
+/** Create a run with a column break. */
+export function columnBreak() {
+    return { content: [{ type: "break", breakType: "column" }] };
+}
+/** Create a tab run. */
+export function tab() {
+    return { content: [{ type: "tab" }] };
+}
+/** Create a positional tab (w:ptab). */
+export function positionalTab(options) {
+    return {
+        content: [
+            {
+                type: "ptab",
+                alignment: options.alignment,
+                relativeTo: options.relativeTo,
+                leader: options.leader
+            }
+        ]
+    };
+}
+/**
+ * Create a ruby (phonetic guide) run — e.g. Japanese furigana or Chinese pinyin.
+ *
+ * @param baseText - The main text being annotated.
+ * @param rubyText - The phonetic text shown above the base.
+ * @param properties - Optional ruby properties (alignment, font size, language).
+ */
+export function ruby(baseText, rubyText, properties) {
+    const normalize = (v) => {
+        if (typeof v === "string") {
+            return [text(v)];
+        }
+        if (Array.isArray(v)) {
+            return v;
+        }
+        return [v];
+    };
+    return {
+        content: [
+            {
+                type: "ruby",
+                properties,
+                baseText: normalize(baseText),
+                rubyText: normalize(rubyText)
+            }
+        ]
+    };
+}
+/** Create a carriage return run. */
+export function carriageReturn() {
+    return { content: [{ type: "carriageReturn" }] };
+}
+/** Create a no-break hyphen run. */
+export function noBreakHyphen() {
+    return { content: [{ type: "noBreakHyphen" }] };
+}
+/** Create a soft hyphen run. */
+export function softHyphen() {
+    return { content: [{ type: "softHyphen" }] };
+}
+/** Create a run with a field code. */
+export function field(instruction, cachedValue) {
+    return { content: [{ type: "field", instruction, cachedValue }] };
+}
+/** Create a PAGE field (current page number). */
+export function pageNumberField(cachedValue) {
+    return field(" PAGE ", cachedValue ?? "1");
+}
+/** Create a NUMPAGES field (total page count). */
+export function totalPagesField(cachedValue) {
+    return field(" NUMPAGES ", cachedValue ?? "1");
+}
+/** Create a SECTIONPAGES field (pages in section). */
+export function sectionPagesField(cachedValue) {
+    return field(" SECTIONPAGES ", cachedValue ?? "1");
+}
+/** Create a SECTION field (current section number). */
+export function sectionField(cachedValue) {
+    return field(" SECTION ", cachedValue ?? "1");
+}
+/** Create a DATE field. */
+export function dateField(format, cachedValue) {
+    const fmt = format ?? "yyyy-MM-dd";
+    return field(` DATE \\@ "${fmt}" `, cachedValue);
+}
+/** Create a SEQ (sequence) field for numbering figures, tables, etc. */
+export function sequenceField(identifier, options) {
+    let instruction = ` SEQ ${identifier} `;
+    if (options?.hide) {
+        instruction += "\\h ";
+    }
+    return field(instruction, options?.cachedValue);
+}
+/** Create a TIME field (current time). */
+export function timeField(format, cachedValue) {
+    const fmt = format ?? "HH:mm:ss";
+    return field(` TIME \\@ "${fmt}" `, cachedValue);
+}
+/** Create an AUTHOR field. */
+export function authorField(cachedValue) {
+    return field(" AUTHOR ", cachedValue);
+}
+/** Create a TITLE field. */
+export function titleField(cachedValue) {
+    return field(" TITLE ", cachedValue);
+}
+/** Create a SUBJECT field. */
+export function subjectField(cachedValue) {
+    return field(" SUBJECT ", cachedValue);
+}
+/** Create a KEYWORDS field. */
+export function keywordsField(cachedValue) {
+    return field(" KEYWORDS ", cachedValue);
+}
+/** Create a FILENAME field. */
+export function fileNameField(options) {
+    const instruction = options?.includePath ? " FILENAME \\p " : " FILENAME ";
+    return field(instruction, options?.cachedValue);
+}
+/** Create a FILESIZE field. */
+export function fileSizeField(cachedValue) {
+    return field(" FILESIZE ", cachedValue);
+}
+/**
+ * Create a STYLEREF field (references text from nearest paragraph with given style).
+ *
+ * Commonly used in headers to show current chapter/section heading.
+ */
+export function styleRefField(styleName, options) {
+    let instruction = ` STYLEREF "${styleName}" `;
+    if (options?.fromBottom) {
+        instruction += "\\l ";
+    }
+    if (options?.insertParagraphNumber) {
+        instruction += "\\n ";
+    }
+    if (options?.insertPosition) {
+        instruction += "\\p ";
+    }
+    if (options?.suppressNonNumeric) {
+        instruction += "\\t ";
+    }
+    return field(instruction, options?.cachedValue);
+}
+/**
+ * Create a REF field (references a bookmark).
+ */
+export function refField(bookmarkName, options) {
+    let instruction = ` REF ${bookmarkName} `;
+    if (options?.insertNumber) {
+        instruction += "\\n ";
+    }
+    if (options?.hyperlink) {
+        instruction += "\\h ";
+    }
+    if (options?.paragraphNumber) {
+        instruction += "\\w ";
+    }
+    if (options?.relativeParagraphNumber) {
+        instruction += "\\r ";
+    }
+    if (options?.fullContext) {
+        instruction += "\\w ";
+    }
+    if (options?.suppressNonDelimiter) {
+        instruction += "\\t ";
+    }
+    return field(instruction, options?.cachedValue);
+}
+/** Create a PAGEREF field (references page of bookmark). */
+export function pageRefField(bookmarkName, options) {
+    let instruction = ` PAGEREF ${bookmarkName} `;
+    if (options?.hyperlink) {
+        instruction += "\\h ";
+    }
+    if (options?.relativePosition) {
+        instruction += "\\p ";
+    }
+    return field(instruction, options?.cachedValue);
+}
+/** Create a NOTEREF field (references a footnote/endnote). */
+export function noteRefField(bookmarkName, options) {
+    let instruction = ` NOTEREF ${bookmarkName} `;
+    if (options?.hyperlink) {
+        instruction += "\\h ";
+    }
+    if (options?.insertNumberFormat) {
+        instruction += "\\f ";
+    }
+    return field(instruction, options?.cachedValue);
+}
+/** Create a HYPERLINK field (alternative to w:hyperlink element). */
+export function hyperlinkField(target, options) {
+    let instruction = ` HYPERLINK "${target}" `;
+    if (options?.anchor) {
+        instruction += `\\l "${options.anchor}" `;
+    }
+    if (options?.newWindow) {
+        instruction += "\\n ";
+    }
+    if (options?.tooltip) {
+        instruction += `\\o "${options.tooltip}" `;
+    }
+    return field(instruction, options?.cachedValue ?? options?.displayText);
+}
+/** Create a QUOTE field (literal text). */
+export function quoteField(text, cachedValue) {
+    return field(` QUOTE "${text}" `, cachedValue ?? text);
+}
+/**
+ * Create a TOC field for table of contents.
+ *
+ * @param options - TOC options.
+ */
+export function tocField(options) {
+    let instruction = " TOC ";
+    if (options?.headingLevels) {
+        instruction += `\\o "${options.headingLevels}" `;
+    }
+    if (options?.styles && options.styles.length > 0) {
+        instruction += `\\t "${options.styles.join(";")}" `;
+    }
+    if (options?.tcLevels) {
+        instruction += `\\f ${options.tcLevels} `;
+    }
+    if (options?.hyperlink) {
+        instruction += "\\h ";
+    }
+    if (options?.rightAlignedPageNumbers) {
+        instruction += "\\z ";
+    }
+    if (options?.tabLeader) {
+        instruction += `\\p "${options.tabLeader}" `;
+    }
+    if (options?.noPageNumbers) {
+        instruction += "\\n ";
+    }
+    if (options?.captionIdentifier) {
+        instruction += `\\c "${options.captionIdentifier}" `;
+    }
+    return field(instruction, options?.cachedValue);
+}
+/** Create a TC (table of contents entry) field. */
+export function tcField(text, options) {
+    let instruction = ` TC "${text}" `;
+    if (options?.level !== undefined) {
+        instruction += `\\l ${options.level} `;
+    }
+    if (options?.suppressPageNumber) {
+        instruction += "\\n ";
+    }
+    return field(instruction, options?.cachedValue);
+}
+/** Create an XE (index entry) field. */
+export function indexEntryField(text, options) {
+    let instruction = ` XE "${text}" `;
+    if (options?.bold) {
+        instruction += "\\b ";
+    }
+    if (options?.italic) {
+        instruction += "\\i ";
+    }
+    return field(instruction, options?.cachedValue);
+}
+/** Create an INDEX field (renders index from XE entries). */
+export function indexField(options) {
+    let instruction = " INDEX ";
+    if (options?.bookmark) {
+        instruction += `\\b ${options.bookmark} `;
+    }
+    if (options?.columns) {
+        instruction += `\\c ${options.columns} `;
+    }
+    if (options?.entryType) {
+        instruction += `\\f "${options.entryType}" `;
+    }
+    return field(instruction, options?.cachedValue);
+}
+/** Create an IF field (conditional content). */
+export function ifField(condition, trueText, falseText, cachedValue) {
+    return field(` IF ${condition} "${trueText}" "${falseText}" `, cachedValue);
+}
+/** Create an INCLUDETEXT field (includes external file content). */
+export function includeTextField(filePath, options) {
+    let instruction = ` INCLUDETEXT "${filePath}" `;
+    if (options?.bookmark) {
+        instruction += `${options.bookmark} `;
+    }
+    return field(instruction, options?.cachedValue);
+}
+/** Create an INCLUDEPICTURE field. */
+export function includePictureField(filePath, cachedValue) {
+    return field(` INCLUDEPICTURE "${filePath}" `, cachedValue);
+}
+/** Create a FORMTEXT field (legacy text form field). */
+export function formTextField(cachedValue) {
+    return field(" FORMTEXT ", cachedValue);
+}
+/** Create a FORMCHECKBOX field (legacy checkbox form field). */
+export function formCheckboxField(cachedValue) {
+    return field(" FORMCHECKBOX ", cachedValue);
+}
+/** Create a FORMDROPDOWN field (legacy dropdown form field). */
+export function formDropdownField(cachedValue) {
+    return field(" FORMDROPDOWN ", cachedValue);
+}
+/** Create a paragraph. */
+export function paragraph(children, properties) {
+    return { type: "paragraph", properties, children };
+}
+/** Create a simple text paragraph. */
+export function textParagraph(content, properties) {
+    const { run: runProps, ...pProps } = properties ?? {};
+    return paragraph([text(content, runProps)], Object.keys(pProps).length > 0 ? pProps : undefined);
+}
+/** Create a heading paragraph. */
+export function heading(content, level) {
+    return paragraph([text(content)], { style: `Heading${level}` });
+}
+/** Create a hyperlink. */
+export function hyperlink(linkText, options) {
+    return {
+        type: "hyperlink",
+        rId: options.rId,
+        url: options.url,
+        anchor: options.anchor,
+        tooltip: options.tooltip,
+        children: [text(linkText, options.properties ?? { color: "0563C1", underline: "single" })]
+    };
+}
+/** Create a bookmark start. */
+export function bookmarkStart(id, name) {
+    return { type: "bookmarkStart", id, name };
+}
+/** Create a bookmark end. */
+export function bookmarkEnd(id) {
+    return { type: "bookmarkEnd", id };
+}
+/** Create a comment range start marker. */
+export function commentRangeStart(id) {
+    return { type: "commentRangeStart", id };
+}
+/** Create a comment range end marker. */
+export function commentRangeEnd(id) {
+    return { type: "commentRangeEnd", id };
+}
+/** Create a comment reference (inside paragraph children). */
+export function commentReference(id) {
+    return { type: "commentReference", id };
+}
+/** Create an inserted run (track changes). */
+export function insertedRun(run, revision) {
+    return { type: "insertedRun", revision, run };
+}
+/** Create a deleted run (track changes). */
+export function deletedRun(run, revision) {
+    return { type: "deletedRun", revision, run };
+}
+/** Create a moved-from run (track changes — source of a move). */
+export function movedFromRun(run, revision) {
+    return { type: "movedFromRun", revision, run };
+}
+/** Create a moved-to run (track changes — destination of a move). */
+export function movedToRun(run, revision) {
+    return { type: "movedToRun", revision, run };
+}
+/** Create a move range start marker. */
+export function moveFromRangeStart(id, author, options) {
+    return { type: "moveFromRangeStart", id, author, date: options?.date, name: options?.name };
+}
+/** Create a move range end marker. */
+export function moveFromRangeEnd(id) {
+    return { type: "moveFromRangeEnd", id };
+}
+/** Create a move-to range start marker. */
+export function moveToRangeStart(id, author, options) {
+    return { type: "moveToRangeStart", id, author, date: options?.date, name: options?.name };
+}
+/** Create a move-to range end marker. */
+export function moveToRangeEnd(id) {
+    return { type: "moveToRangeEnd", id };
+}
+/** Create a checkbox. */
+export function checkBox(options) {
+    return {
+        type: "checkBox",
+        checked: options?.checked,
+        checkedState: options?.checkedState,
+        uncheckedState: options?.uncheckedState
+    };
+}
+// =============================================================================
+// Math Builders
+// =============================================================================
+/** Create a math block. */
+export function mathBlock(content) {
+    return { type: "math", content };
+}
+/** Create a math text run. */
+export function mathRun(mathText, properties) {
+    return { type: "mathRun", text: mathText, properties };
+}
+/** Create a math fraction. */
+export function mathFraction(numerator, denominator, fractionType) {
+    return { type: "mathFraction", fractionType, numerator, denominator };
+}
+/** Create a math square root. */
+export function mathSqrt(content) {
+    return { type: "mathRadical", content, hideDegree: true };
+}
+/** Create a math nth root. */
+export function mathRoot(degree, content) {
+    return { type: "mathRadical", degree, content };
+}
+/** Create a math summation. */
+export function mathSum(content, sub, sup) {
+    return { type: "mathNary", char: "\u2211", sub, sup, content };
+}
+/** Create a math integral. */
+export function mathIntegral(content, sub, sup) {
+    return { type: "mathNary", char: "\u222B", sub, sup, content };
+}
+/** Create a math product. */
+export function mathProduct(content, sub, sup) {
+    return { type: "mathNary", char: "\u220F", sub, sup, content };
+}
+/** Create a math superscript. */
+export function mathSuperScript(base, superScript) {
+    return { type: "mathSuperScript", base, superScript };
+}
+/** Create a math subscript. */
+export function mathSubScript(base, subScript) {
+    return { type: "mathSubScript", base, subScript };
+}
+/** Create a math sub-superscript. */
+export function mathSubSuperScript(base, subScript, superScript) {
+    return { type: "mathSubSuperScript", base, subScript, superScript };
+}
+/** Create a math pre-sub-superscript (subscript/superscript before the base). */
+export function mathPreSubSuperScript(base, preSubScript, preSuperScript) {
+    return { type: "mathPreSubSuperScript", base, preSubScript, preSuperScript };
+}
+/** Create a math phantom (invisible expression that takes up space). */
+export function mathPhantom(content, options) {
+    return { type: "mathPhantom", content, ...options };
+}
+/** Create a math group character (e.g. a horizontal brace over an expression). */
+export function mathGroupChar(base, options) {
+    return { type: "mathGroupChar", base, ...options };
+}
+/** Create a math border box (draw borders around / strike through an expression). */
+export function mathBorderBox(content, options) {
+    return { type: "mathBorderBox", content, ...options };
+}
+/** Create a math delimiter (parentheses, brackets, etc.). */
+export function mathDelimiter(content, options) {
+    return {
+        type: "mathDelimiter",
+        beginChar: options?.beginChar,
+        endChar: options?.endChar,
+        separatorChar: options?.separatorChar,
+        content
+    };
+}
+/** Create a math n-ary operator (sum, integral, product, etc.). */
+export function mathNary(char, content, sub, sup) {
+    return { type: "mathNary", char, sub, sup, content };
+}
+/** Create a math function (sin, cos, lim, etc.). */
+export function mathFunction(name, content) {
+    return { type: "mathFunction", name, content };
+}
+/** Create a math limit (upper or lower). */
+export function mathLimit(base, limit, limitType = "lower") {
+    return { type: "mathLimit", base, limit, limitType };
+}
+/** Create a math matrix. */
+export function mathMatrix(rows) {
+    return { type: "mathMatrix", rows };
+}
+/** Create a math accent (hat, tilde, etc.). */
+export function mathAccent(content, char) {
+    return { type: "mathAccent", content, char };
+}
+/** Create a math bar (overbar/underbar). */
+export function mathBar(content, position) {
+    return { type: "mathBar", content, position: position ?? "top" };
+}
+/** Create a math box. */
+export function mathBox(content) {
+    return { type: "mathBox", content };
+}
+/** Create a math equation array. */
+export function mathEquationArray(rows) {
+    return { type: "mathEquationArray", rows };
+}
+/** Create a symbol run. */
+export function symbol(font, char, properties) {
+    return { properties, content: [{ type: "symbol", font, char }] };
+}
+/** Create a floating image (body-level). */
+export function floatingImage(options) {
+    return {
+        type: "floatingImage",
+        rId: options.rId,
+        width: options.width,
+        height: options.height,
+        horizontalPosition: options.horizontalPosition ?? { relativeTo: "column", offset: 0 },
+        verticalPosition: options.verticalPosition ?? { relativeTo: "paragraph", offset: 0 },
+        wrap: options.wrap ?? { style: "square" },
+        altText: options.altText,
+        name: options.name,
+        behindDoc: options.behindDoc,
+        lockAnchor: options.lockAnchor,
+        layoutInCell: options.layoutInCell,
+        allowOverlap: options.allowOverlap,
+        simplePos: options.simplePos,
+        distT: options.distT,
+        distB: options.distB,
+        distL: options.distL,
+        distR: options.distR,
+        rotation: options.rotation,
+        flipHorizontal: options.flipHorizontal,
+        flipVertical: options.flipVertical,
+        srcRect: options.srcRect
+    };
+}
+/** Create a DrawingML shape. */
+export function drawingShape(options) {
+    return {
+        type: "drawingShape",
+        shapeType: options.shapeType,
+        width: options.width,
+        height: options.height,
+        fillColor: options.fillColor,
+        noFill: options.noFill,
+        outlineColor: options.outlineColor,
+        outlineWidth: options.outlineWidth,
+        noOutline: options.noOutline,
+        textContent: options.textContent,
+        altText: options.altText,
+        name: options.name,
+        horizontalPosition: options.horizontalPosition ?? { relativeTo: "column", offset: 0 },
+        verticalPosition: options.verticalPosition ?? { relativeTo: "paragraph", offset: 0 },
+        wrap: options.wrap ?? { style: "square" },
+        behindDoc: options.behindDoc,
+        rotation: options.rotation
+    };
+}
+/** Create a chart content block. */
+export function chart(options) {
+    return {
+        type: "chart",
+        chart: {
+            type: options.type,
+            series: options.series,
+            title: options.title,
+            legend: options.legend,
+            categoryAxis: options.categoryAxis,
+            valueAxis: options.valueAxis,
+            plotAreaColor: options.plotAreaColor,
+            chartAreaColor: options.chartAreaColor,
+            view3d: options.view3d,
+            style: options.style,
+            width: options.width,
+            height: options.height
+        },
+        altText: options.altText,
+        name: options.name
+    };
+}
+/** Create a structured document tag (content control). */
+export function structuredDocumentTag(content, properties) {
+    return { type: "sdt", properties: properties ?? {}, content };
+}
+// =============================================================================
+// Table Builders
+// =============================================================================
+/** Shorthand border. */
+export function border(style = "single", size = 4, color = "auto") {
+    return { style, size, space: 0, color };
+}
+/** Create standard grid borders for a table. */
+export function gridBorders(size = 4, color = "auto") {
+    const b = border("single", size, color);
+    return { top: b, left: b, bottom: b, right: b, insideH: b, insideV: b };
+}
+/** Create a table cell. */
+export function cell(content, properties) {
+    if (typeof content === "string") {
+        return { properties, content: [textParagraph(content)] };
+    }
+    return { properties, content };
+}
+/** Create a table row. */
+export function row(cells, properties) {
+    return { properties, cells };
+}
+/** Create a table. */
+export function table(rows, properties, columnWidths) {
+    return { type: "table", properties, columnWidths, rows };
+}
+/** Create a simple table from a 2D string array. */
+export function simpleTable(data, options) {
+    const opts = { headerRow: true, borders: true, ...options };
+    const tableRows = data.map((rowData, rowIndex) => {
+        const cells = rowData.map(cellText => cell(cellText));
+        return row(cells, rowIndex === 0 && opts.headerRow ? { tableHeader: true } : undefined);
+    });
+    return table(tableRows, {
+        width: opts.width ?? { value: 5000, type: "pct" },
+        borders: opts.borders ? gridBorders() : undefined
+    }, opts.columnWidths);
+}
+// =============================================================================
+// Document Builder Class
+// =============================================================================
+/**
+ * Fluent builder for constructing DOCX documents.
+ *
+ * @example
+ * ```ts
+ * const doc = new DocumentBuilder()
+ *   .addHeading("Hello World", 1)
+ *   .addParagraph("This is a paragraph.")
+ *   .addTable([["Name", "Age"], ["Alice", "30"]])
+ *   .build();
+ *
+ * const bytes = await doc.toBuffer();
+ * ```
+ */
+export class DocumentBuilder {
+    constructor() {
+        this._body = [];
+        this._styles = [];
+        this._abstractNumberings = [];
+        this._numberingInstances = [];
+        this._headers = new Map();
+        this._footers = new Map();
+        this._footnotes = [];
+        this._endnotes = [];
+        this._images = [];
+        this._fonts = [];
+        this._comments = [];
+        this._customProperties = [];
+        this._nextImageId = 1;
+        this._nextFootnoteId = 1;
+        this._nextEndnoteId = 1;
+        this._nextBookmarkId = 0;
+        this._nextAbstractNumId = 0;
+        this._nextNumId = 1;
+        this._nextDrawingId = 1;
+        this._nextCommentId = 0;
+    }
+    /** Add raw body content. */
+    addContent(content) {
+        this._body.push(content);
+        return this;
+    }
+    /** Add a paragraph with runs. */
+    addParagraphElement(para) {
+        this._body.push(para);
+        return this;
+    }
+    /** Add a simple text paragraph. */
+    addParagraph(content, properties) {
+        this._body.push(textParagraph(content, properties));
+        return this;
+    }
+    /** Add a heading. */
+    addHeading(content, level = 1) {
+        this._body.push(heading(content, level));
+        return this;
+    }
+    /** Add a page break. */
+    addPageBreak() {
+        this._body.push(paragraph([pageBreak()]));
+        return this;
+    }
+    /** Add a table from a 2D array. */
+    addTable(data, options) {
+        this._body.push(simpleTable(data, options));
+        return this;
+    }
+    /** Add a table element. */
+    addTableElement(tbl) {
+        this._body.push(tbl);
+        return this;
+    }
+    /** Add an inline image. Returns the image relationship ID and drawing ID. */
+    addImage(data, mediaType, width, height, options) {
+        const fileName = `image${this._nextImageId}.${mediaType}`;
+        const rId = `__img_${this._nextImageId}`;
+        const drawingId = this._nextDrawingId++;
+        this._images.push({ data, mediaType, fileName, rId });
+        this._body.push(paragraph([
+            {
+                content: [
+                    {
+                        type: "image",
+                        rId,
+                        width,
+                        height,
+                        altText: options?.altText,
+                        name: options?.name ?? `Picture ${this._nextImageId}`,
+                        drawingId
+                    }
+                ]
+            }
+        ]));
+        this._nextImageId++;
+        return { rId, drawingId };
+    }
+    /** Add a floating image. Returns the image relationship ID. */
+    addFloatingImage(data, mediaType, width, height, options) {
+        const fileName = `image${this._nextImageId}.${mediaType}`;
+        const rId = `__img_${this._nextImageId}`;
+        this._images.push({ data, mediaType, fileName, rId });
+        this._body.push(floatingImage({
+            rId,
+            width,
+            height,
+            altText: options?.altText,
+            name: options?.name ?? `Picture ${this._nextImageId}`,
+            horizontalPosition: options?.horizontalPosition,
+            verticalPosition: options?.verticalPosition,
+            wrap: options?.wrap,
+            behindDoc: options?.behindDoc,
+            lockAnchor: options?.lockAnchor,
+            layoutInCell: options?.layoutInCell,
+            allowOverlap: options?.allowOverlap,
+            distT: options?.distT,
+            distB: options?.distB,
+            distL: options?.distL,
+            distR: options?.distR,
+            rotation: options?.rotation,
+            flipHorizontal: options?.flipHorizontal,
+            flipVertical: options?.flipVertical
+        }));
+        this._nextImageId++;
+        return rId;
+    }
+    /** Add a custom font definition. */
+    addFont(font) {
+        this._fonts.push(font);
+        return this;
+    }
+    /** Set a text watermark on the document. */
+    setWatermark(watermark) {
+        this._watermark = watermark;
+        return this;
+    }
+    /** Add a footnote. Returns the footnote ID. */
+    addFootnote(content) {
+        const id = this._nextFootnoteId++;
+        const paras = typeof content === "string" ? [textParagraph(content)] : content;
+        this._footnotes.push({ id, content: paras });
+        return id;
+    }
+    /** Add an endnote. Returns the endnote ID. */
+    addEndnote(content) {
+        const id = this._nextEndnoteId++;
+        const paras = typeof content === "string" ? [textParagraph(content)] : content;
+        this._endnotes.push({ id, content: paras });
+        return id;
+    }
+    /** Add a comment. Returns the comment ID. */
+    addComment(author, content, options) {
+        const id = this._nextCommentId++;
+        const paras = typeof content === "string" ? [textParagraph(content)] : content;
+        this._comments.push({
+            id,
+            author,
+            date: options?.date,
+            initials: options?.initials,
+            content: paras
+        });
+        return id;
+    }
+    /** Add a Table of Contents. */
+    addTableOfContents(options) {
+        this._body.push({
+            type: "tableOfContents",
+            headingStyleRange: options?.headingStyleRange ?? "1-3",
+            hyperlink: options?.hyperlink ?? true,
+            ...options
+        });
+        return this;
+    }
+    /** Add a math equation block. */
+    addMath(content) {
+        this._body.push(mathBlock(content));
+        return this;
+    }
+    /** Add a text box. */
+    addTextBox(content, options) {
+        const paras = typeof content === "string" ? [textParagraph(content)] : content;
+        this._body.push({
+            type: "textBox",
+            content: paras,
+            width: options?.width,
+            height: options?.height,
+            stroke: options?.stroke,
+            fill: options?.fill
+        });
+        return this;
+    }
+    /** Add a bullet list. */
+    addBulletList(items, level = 0) {
+        // Create abstract numbering for bullets if not exists
+        let bulletAbsId = this._abstractNumberings.find(a => a.levels[0]?.format === "bullet")?.abstractNumId;
+        if (bulletAbsId === undefined) {
+            bulletAbsId = this._nextAbstractNumId++;
+            this._abstractNumberings.push({
+                abstractNumId: bulletAbsId,
+                multiLevelType: "hybridMultilevel",
+                levels: [
+                    {
+                        level: 0,
+                        start: 1,
+                        format: "bullet",
+                        text: "\uF0B7",
+                        justification: "left",
+                        paragraphProperties: { indent: { left: 720, hanging: 360 } },
+                        runProperties: { font: { ascii: "Symbol", hAnsi: "Symbol" } }
+                    },
+                    {
+                        level: 1,
+                        start: 1,
+                        format: "bullet",
+                        text: "o",
+                        justification: "left",
+                        paragraphProperties: { indent: { left: 1440, hanging: 360 } },
+                        runProperties: { font: { ascii: "Courier New", hAnsi: "Courier New" } }
+                    },
+                    {
+                        level: 2,
+                        start: 1,
+                        format: "bullet",
+                        text: "\uF0A7",
+                        justification: "left",
+                        paragraphProperties: { indent: { left: 2160, hanging: 360 } },
+                        runProperties: { font: { ascii: "Wingdings", hAnsi: "Wingdings" } }
+                    }
+                ]
+            });
+            this._numberingInstances.push({
+                numId: this._nextNumId++,
+                abstractNumId: bulletAbsId
+            });
+        }
+        const numId = this._numberingInstances.find(n => n.abstractNumId === bulletAbsId).numId;
+        for (const item of items) {
+            this._body.push(textParagraph(item, { numbering: { numId, level } }));
+        }
+        return this;
+    }
+    /** Add a numbered list. */
+    addNumberedList(items, level = 0) {
+        let numAbsId = this._abstractNumberings.find(a => a.levels[0]?.format === "decimal")?.abstractNumId;
+        if (numAbsId === undefined) {
+            numAbsId = this._nextAbstractNumId++;
+            this._abstractNumberings.push({
+                abstractNumId: numAbsId,
+                multiLevelType: "hybridMultilevel",
+                levels: [
+                    {
+                        level: 0,
+                        start: 1,
+                        format: "decimal",
+                        text: "%1.",
+                        justification: "left",
+                        paragraphProperties: { indent: { left: 720, hanging: 360 } }
+                    },
+                    {
+                        level: 1,
+                        start: 1,
+                        format: "lowerLetter",
+                        text: "%2.",
+                        justification: "left",
+                        paragraphProperties: { indent: { left: 1440, hanging: 360 } }
+                    },
+                    {
+                        level: 2,
+                        start: 1,
+                        format: "lowerRoman",
+                        text: "%3.",
+                        justification: "right",
+                        paragraphProperties: { indent: { left: 2160, hanging: 180 } }
+                    }
+                ]
+            });
+            this._numberingInstances.push({
+                numId: this._nextNumId++,
+                abstractNumId: numAbsId
+            });
+        }
+        const numId = this._numberingInstances.find(n => n.abstractNumId === numAbsId).numId;
+        for (const item of items) {
+            this._body.push(textParagraph(item, { numbering: { numId, level } }));
+        }
+        return this;
+    }
+    /** Set section properties (page size, margins, etc.). */
+    setSectionProperties(props) {
+        this._sectionProperties = props;
+        return this;
+    }
+    /** Set document defaults. */
+    setDocDefaults(defaults) {
+        this._docDefaults = defaults;
+        return this;
+    }
+    /** Add a style definition. */
+    addStyle(style) {
+        this._styles.push(style);
+        return this;
+    }
+    /** Set default styles (Normal, Heading1-6, Hyperlink, etc.). */
+    useDefaultStyles() {
+        this._docDefaults = {
+            runProperties: {
+                font: { ascii: "Calibri", hAnsi: "Calibri", eastAsia: "SimSun", cs: "Times New Roman" },
+                size: 22,
+                sizeCs: 22,
+                language: { val: "en-US" }
+            },
+            paragraphProperties: {
+                spacing: { after: 160, line: 259, lineRule: "auto" }
+            }
+        };
+        this._styles.push({ type: "paragraph", styleId: "Normal", name: "Normal", isDefault: true, qFormat: true }, {
+            type: "paragraph",
+            styleId: "Heading1",
+            name: "heading 1",
+            basedOn: "Normal",
+            next: "Normal",
+            qFormat: true,
+            uiPriority: 9,
+            paragraphProperties: {
+                keepNext: true,
+                keepLines: true,
+                spacing: { before: 240, after: 0 }
+            },
+            runProperties: { font: "Calibri Light", color: "2F5496", size: 32 }
+        }, {
+            type: "paragraph",
+            styleId: "Heading2",
+            name: "heading 2",
+            basedOn: "Normal",
+            next: "Normal",
+            qFormat: true,
+            uiPriority: 9,
+            paragraphProperties: { keepNext: true, keepLines: true, spacing: { before: 40, after: 0 } },
+            runProperties: { font: "Calibri Light", color: "2F5496", size: 26 }
+        }, {
+            type: "paragraph",
+            styleId: "Heading3",
+            name: "heading 3",
+            basedOn: "Normal",
+            next: "Normal",
+            qFormat: true,
+            uiPriority: 9,
+            paragraphProperties: { keepNext: true, keepLines: true, spacing: { before: 40, after: 0 } },
+            runProperties: { font: "Calibri Light", color: "1F3763", size: 24 }
+        }, {
+            type: "character",
+            styleId: "Hyperlink",
+            name: "Hyperlink",
+            uiPriority: 99,
+            runProperties: { color: "0563C1", underline: "single" }
+        }, {
+            type: "table",
+            styleId: "TableGrid",
+            name: "Table Grid",
+            basedOn: "TableNormal",
+            uiPriority: 39,
+            tableProperties: { borders: gridBorders(4, "auto") }
+        });
+        return this;
+    }
+    /** Set a header for the given type. */
+    setHeader(type, content) {
+        this._headers.set(type, { content });
+        return this;
+    }
+    /** Set a footer for the given type. */
+    setFooter(type, content) {
+        this._footers.set(type, { content });
+        return this;
+    }
+    /** Set document settings. */
+    setSettings(settings) {
+        this._settings = settings;
+        return this;
+    }
+    /** Set core properties (metadata). */
+    setCoreProperties(props) {
+        this._coreProperties = props;
+        return this;
+    }
+    /** Set application properties. */
+    setAppProperties(props) {
+        this._appProperties = props;
+        return this;
+    }
+    /** Set document background. */
+    setBackground(background) {
+        this._background = background;
+        return this;
+    }
+    /** Add a custom document property. */
+    addCustomProperty(name, value) {
+        this._customProperties.push({ name, value });
+        return this;
+    }
+    /** Add a section break with properties. */
+    addSectionBreak(props) {
+        // Insert as the last paragraph's section properties
+        if (this._body.length > 0) {
+            const last = this._body[this._body.length - 1];
+            if (last.type === "paragraph") {
+                const existingProps = last.properties ?? {};
+                this._body[this._body.length - 1] = {
+                    ...last,
+                    properties: { ...existingProps, sectionProperties: props }
+                };
+                return this;
+            }
+        }
+        // If no previous paragraph, add an empty one with section properties
+        this._body.push(paragraph([], { sectionProperties: props }));
+        return this;
+    }
+    /** Get next available bookmark ID. */
+    nextBookmarkId() {
+        return this._nextBookmarkId++;
+    }
+    /** Build the DocxDocument model. */
+    build() {
+        return {
+            body: this._body,
+            sectionProperties: this._sectionProperties ?? {
+                pageSize: { width: 12240, height: 15840 },
+                margins: { top: 1440, right: 1440, bottom: 1440, left: 1440 }
+            },
+            styles: this._styles.length > 0 ? this._styles : undefined,
+            docDefaults: this._docDefaults,
+            abstractNumberings: this._abstractNumberings.length > 0 ? this._abstractNumberings : undefined,
+            numberingInstances: this._numberingInstances.length > 0 ? this._numberingInstances : undefined,
+            headers: this._headers.size > 0 ? this._headers : undefined,
+            footers: this._footers.size > 0 ? this._footers : undefined,
+            footnotes: this._footnotes.length > 0 ? this._footnotes : undefined,
+            endnotes: this._endnotes.length > 0 ? this._endnotes : undefined,
+            images: this._images.length > 0 ? this._images : undefined,
+            fonts: this._fonts.length > 0 ? this._fonts : undefined,
+            settings: this._settings,
+            coreProperties: this._coreProperties,
+            appProperties: this._appProperties,
+            comments: this._comments.length > 0 ? this._comments : undefined,
+            background: this._background,
+            customProperties: this._customProperties.length > 0 ? this._customProperties : undefined,
+            watermark: this._watermark
+        };
+    }
+    /** Build and package to DOCX bytes. */
+    async toBuffer(compressionLevel) {
+        return packageDocx(this.build(), compressionLevel);
+    }
+    /** Build and package to base64 string. */
+    async toBase64(compressionLevel) {
+        const bytes = await this.toBuffer(compressionLevel);
+        return bytesToBase64(bytes);
+    }
+}
+// =============================================================================
+// Theme Color Resolution
+// =============================================================================
+/**
+ * Map OOXML theme color attribute names to theme color scheme keys.
+ * Word uses different names in run/paragraph properties vs the theme XML.
+ */
+const THEME_COLOR_MAP = {
+    dark1: "dk1",
+    light1: "lt1",
+    dark2: "dk2",
+    light2: "lt2",
+    accent1: "accent1",
+    accent2: "accent2",
+    accent3: "accent3",
+    accent4: "accent4",
+    accent5: "accent5",
+    accent6: "accent6",
+    hyperlink: "hlink",
+    followedHyperlink: "folHlink",
+    // Direct names also work
+    dk1: "dk1",
+    lt1: "lt1",
+    dk2: "dk2",
+    lt2: "lt2",
+    hlink: "hlink",
+    folHlink: "folHlink"
+};
+/**
+ * Resolve a ColorSpec to an actual hex RGB color using the document theme.
+ *
+ * Applies theme color lookup + tint/shade transformations per OOXML spec.
+ *
+ * @param color - The color value (HexColor string or ColorSpec).
+ * @param theme - The document theme (from `doc.theme`).
+ * @returns Resolved hex color string (6 chars, no #), or undefined if unresolvable.
+ */
+export function resolveThemeColor(color, theme) {
+    if (color === undefined) {
+        return undefined;
+    }
+    if (typeof color === "string") {
+        return color;
+    }
+    // ColorSpec with val — use directly
+    if (color.val && color.val !== "auto") {
+        return color.val;
+    }
+    // Resolve via theme
+    if (!color.themeColor || !theme) {
+        return color.val;
+    }
+    const key = THEME_COLOR_MAP[color.themeColor] ?? color.themeColor;
+    const base = theme.colorScheme.colors[key];
+    if (!base) {
+        return color.val;
+    }
+    // Apply tint or shade
+    if (color.themeTint) {
+        return applyTint(base, parseInt(color.themeTint, 16) / 255);
+    }
+    if (color.themeShade) {
+        return applyShade(base, parseInt(color.themeShade, 16) / 255);
+    }
+    return base;
+}
+/** Apply tint to a hex color. tint=1 → white, tint=0 → original. */
+function applyTint(hex, tint) {
+    const r = parseInt(hex.slice(0, 2), 16);
+    const g = parseInt(hex.slice(2, 4), 16);
+    const b = parseInt(hex.slice(4, 6), 16);
+    const nr = Math.round(r + (255 - r) * tint);
+    const ng = Math.round(g + (255 - g) * tint);
+    const nb = Math.round(b + (255 - b) * tint);
+    return toHex2(nr) + toHex2(ng) + toHex2(nb);
+}
+/** Apply shade to a hex color. shade=1 → original, shade=0 → black. */
+function applyShade(hex, shade) {
+    const r = parseInt(hex.slice(0, 2), 16);
+    const g = parseInt(hex.slice(2, 4), 16);
+    const b = parseInt(hex.slice(4, 6), 16);
+    const nr = Math.round(r * shade);
+    const ng = Math.round(g * shade);
+    const nb = Math.round(b * shade);
+    return toHex2(nr) + toHex2(ng) + toHex2(nb);
+}
+function toHex2(n) {
+    const h = Math.max(0, Math.min(255, n)).toString(16);
+    return h.length < 2 ? "0" + h : h;
+}
+/** Extract concatenated plain text from a paragraph's runs. */
+function paragraphText(para) {
+    let text = "";
+    for (const child of para.children) {
+        if ("content" in child && Array.isArray(child.content)) {
+            for (const c of child.content) {
+                if ("type" in c && c.type === "text" && "text" in c) {
+                    text += c.text;
+                }
+            }
+        }
+    }
+    return text;
+}
+// =============================================================================
+// Document Query API (read-only helpers)
+// =============================================================================
+/**
+ * Count all top-level paragraphs in the document body.
+ */
+export function paragraphCount(doc) {
+    let count = 0;
+    for (const block of doc.body) {
+        if (block.type === "paragraph") {
+            count++;
+        }
+    }
+    return count;
+}
+/**
+ * Count words across all paragraphs in the document body.
+ * Uses simple whitespace splitting; for East Asian text, each CJK character
+ * is counted as one "word" to approximate meaningful unit count.
+ */
+export function countWords(doc) {
+    let count = 0;
+    const cjkRe = /[\u4e00-\u9fff\u3040-\u30ff\uac00-\ud7af]/g;
+    const walkParagraphs = (blocks) => {
+        for (const block of blocks) {
+            if (block.type === "paragraph") {
+                const text = paragraphText(block);
+                // Count CJK chars + latin word-like tokens
+                const cjkCount = (text.match(cjkRe) ?? []).length;
+                const latin = text.replace(cjkRe, " ").trim();
+                const latinCount = latin ? latin.split(/\s+/).length : 0;
+                count += cjkCount + latinCount;
+            }
+            else if (block.type === "table") {
+                for (const row of block.rows) {
+                    for (const cell of row.cells) {
+                        walkParagraphs(cell.content);
+                    }
+                }
+            }
+            else if (block.type === "sdt") {
+                const filtered = block.content.filter(c => "type" in c && (c.type === "paragraph" || c.type === "table"));
+                walkParagraphs(filtered);
+            }
+        }
+    };
+    walkParagraphs(doc.body);
+    return count;
+}
+/**
+ * Extract the heading outline from a document.
+ *
+ * Matches paragraphs whose style is `Heading1` through `Heading9` (case-insensitive),
+ * or whose `outlineLevel` property is set (0-8).
+ */
+export function getHeadings(doc) {
+    const out = [];
+    doc.body.forEach((block, i) => {
+        if (block.type !== "paragraph") {
+            return;
+        }
+        const style = block.properties?.style;
+        const styleMatch = style ? /^Heading\s*(\d)$/i.exec(style) : null;
+        let level;
+        if (styleMatch) {
+            level = parseInt(styleMatch[1], 10);
+        }
+        else if (block.properties?.outlineLevel !== undefined && block.properties.outlineLevel < 9) {
+            level = block.properties.outlineLevel + 1;
+        }
+        if (level !== undefined && level >= 1 && level <= 9) {
+            out.push({
+                level,
+                text: paragraphText(block),
+                paragraphIndex: i,
+                style
+            });
+        }
+    });
+    return out;
+}
+/**
+ * Find a bookmark by name.
+ *
+ * @returns The bookmark start marker + its location, or `undefined` if not found.
+ */
+export function findBookmark(doc, name) {
+    for (let i = 0; i < doc.body.length; i++) {
+        const block = doc.body[i];
+        if (block.type !== "paragraph") {
+            continue;
+        }
+        for (let j = 0; j < block.children.length; j++) {
+            const ch = block.children[j];
+            if ("type" in ch && ch.type === "bookmarkStart" && ch.name === name) {
+                return { bookmark: ch, paragraphIndex: i, childIndex: j };
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Find a comment by its ID.
+ */
+export function findComment(doc, id) {
+    return doc.comments?.find(c => c.id === id);
+}
+/**
+ * List all images registered in the document.
+ */
+export function listImages(doc) {
+    return doc.images ?? [];
+}
+/**
+ * List all tables in the document body (top-level only).
+ */
+export function listTables(doc) {
+    return doc.body.filter((b) => b.type === "table");
+}
+/**
+ * Collect all hyperlinks in the document body.
+ */
+export function listHyperlinks(doc) {
+    const out = [];
+    const walk = (children) => {
+        for (const ch of children) {
+            if ("type" in ch && ch.type === "hyperlink") {
+                out.push(ch);
+                walk(ch.children);
+            }
+        }
+    };
+    for (const block of doc.body) {
+        if (block.type === "paragraph") {
+            walk(block.children);
+        }
+    }
+    return out;
+}
+/**
+ * Get the total number of tables (top-level) and nested tables.
+ */
+export function tableCount(doc) {
+    let count = 0;
+    const walk = (blocks) => {
+        for (const block of blocks) {
+            if (block.type === "table") {
+                count++;
+                for (const row of block.rows) {
+                    for (const cell of row.cells) {
+                        walk(cell.content);
+                    }
+                }
+            }
+        }
+    };
+    walk(doc.body);
+    return count;
+}
+/**
+ * Extract plain text from the entire document body.
+ *
+ * Paragraphs are separated by `\n`. Tables render as tab-separated cell text.
+ */
+export function extractText(doc) {
+    const lines = [];
+    const walk = (blocks) => {
+        for (const block of blocks) {
+            if (block.type === "paragraph") {
+                lines.push(paragraphText(block));
+            }
+            else if (block.type === "table") {
+                for (const row of block.rows) {
+                    const cellTexts = [];
+                    for (const cell of row.cells) {
+                        const cellLines = [];
+                        walk(cell.content);
+                        // collect last paragraphs text
+                        cellTexts.push(cellLines.join(" "));
+                    }
+                    lines.push(cellTexts.join("\t"));
+                }
+            }
+        }
+    };
+    walk(doc.body);
+    return lines.join("\n");
+}
+/**
+ * Search for text occurrences in a document's body paragraphs.
+ *
+ * @param doc - The document model to search.
+ * @param query - String or RegExp to search for.
+ * @returns Array of search results.
+ */
+export function searchText(doc, query) {
+    const results = [];
+    for (let i = 0; i < doc.body.length; i++) {
+        const block = doc.body[i];
+        if (block.type !== "paragraph") {
+            continue;
+        }
+        const text = paragraphText(block);
+        if (typeof query === "string") {
+            let idx = text.indexOf(query);
+            while (idx !== -1) {
+                results.push({ paragraphIndex: i, match: query, offset: idx });
+                idx = text.indexOf(query, idx + 1);
+            }
+        }
+        else {
+            const re = new RegExp(query.source, query.flags.includes("g") ? query.flags : query.flags + "g");
+            let m;
+            while ((m = re.exec(text)) !== null) {
+                results.push({ paragraphIndex: i, match: m[0], offset: m.index });
+                if (!re.global) {
+                    break;
+                }
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Replace text in a document's body paragraphs (mutates the document).
+ *
+ * Performs simple text replacement within run content. Each run's text content
+ * is individually searched and replaced. For cross-run matches, the paragraph
+ * text is reconstructed and split back into runs.
+ *
+ * @param doc - The document model to modify (mutated in place).
+ * @param search - String or RegExp to find.
+ * @param replacement - Replacement string (supports $1, $2 etc. for RegExp).
+ * @returns Number of replacements made.
+ */
+export function replaceText(doc, search, replacement) {
+    let count = 0;
+    for (const block of doc.body) {
+        if (block.type !== "paragraph") {
+            continue;
+        }
+        count += replaceInParagraph(block, search, replacement);
+    }
+    return count;
+}
+// =============================================================================
+// Mail Merge
+// =============================================================================
+/** Regex to parse MERGEFIELD instruction: MERGEFIELD "FieldName" or MERGEFIELD FieldName */
+const MERGEFIELD_RE = /^\s*MERGEFIELD\s+(?:"([^"]+)"|(\S+))/i;
+/**
+ * Execute a mail merge: replace all MERGEFIELD fields in the document with values from the data map.
+ *
+ * Fields not found in the data map are left unchanged (or optionally cleared).
+ *
+ * @param doc - The document to modify (mutated in place).
+ * @param data - Map of field names to replacement values.
+ * @param options - Optional settings.
+ * @returns The number of fields replaced.
+ */
+export function mailMerge(doc, data, options) {
+    let count = 0;
+    const removeUnmatched = options?.removeUnmatched ?? false;
+    // Process body
+    for (const block of doc.body) {
+        if (block.type === "paragraph") {
+            count += mergeFieldsInParagraph(block, data, removeUnmatched);
+        }
+        else if (block.type === "table") {
+            count += mergeFieldsInTable(block, data, removeUnmatched);
+        }
+        else if (block.type === "sdt") {
+            for (const sdtChild of block.content) {
+                if ("type" in sdtChild && sdtChild.type === "paragraph") {
+                    count += mergeFieldsInParagraph(sdtChild, data, removeUnmatched);
+                }
+                else if ("type" in sdtChild && sdtChild.type === "table") {
+                    count += mergeFieldsInTable(sdtChild, data, removeUnmatched);
+                }
+            }
+        }
+    }
+    // Process headers and footers
+    if (doc.headers) {
+        for (const [, header] of doc.headers) {
+            count += mergeFieldsInHeaderFooter(header.content, data, removeUnmatched);
+        }
+    }
+    if (doc.footers) {
+        for (const [, footer] of doc.footers) {
+            count += mergeFieldsInHeaderFooter(footer.content, data, removeUnmatched);
+        }
+    }
+    return count;
+}
+function mergeFieldsInTable(table, data, removeUnmatched) {
+    let count = 0;
+    for (const row of table.rows) {
+        for (const cell of row.cells) {
+            for (const block of cell.content) {
+                if (block.type === "paragraph") {
+                    count += mergeFieldsInParagraph(block, data, removeUnmatched);
+                }
+                else if (block.type === "table") {
+                    count += mergeFieldsInTable(block, data, removeUnmatched);
+                }
+            }
+        }
+    }
+    return count;
+}
+function mergeFieldsInHeaderFooter(content, data, removeUnmatched) {
+    let count = 0;
+    for (const child of content.children) {
+        if (child.type === "paragraph") {
+            count += mergeFieldsInParagraph(child, data, removeUnmatched);
+        }
+        else if (child.type === "table") {
+            count += mergeFieldsInTable(child, data, removeUnmatched);
+        }
+    }
+    return count;
+}
+function mergeFieldsInParagraph(para, data, removeUnmatched) {
+    let count = 0;
+    const children = para.children;
+    for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        if (!("content" in child) || !Array.isArray(child.content)) {
+            continue;
+        }
+        const run = child;
+        const content = run.content;
+        for (let j = 0; j < content.length; j++) {
+            const c = content[j];
+            if (c.type !== "field") {
+                continue;
+            }
+            const match = MERGEFIELD_RE.exec(c.instruction);
+            if (!match) {
+                continue;
+            }
+            const fieldName = match[1] ?? match[2];
+            if (fieldName in data) {
+                // Replace field with text
+                content[j] = { type: "text", text: data[fieldName] };
+                count++;
+            }
+            else if (removeUnmatched) {
+                // Remove unmatched field
+                content[j] = { type: "text", text: "" };
+                count++;
+            }
+        }
+    }
+    return count;
+}
+/** Replace text within a single paragraph. */
+function replaceInParagraph(para, search, replacement) {
+    // First try simple per-run replacement
+    let count = 0;
+    for (const child of para.children) {
+        if (!("content" in child) || !Array.isArray(child.content)) {
+            continue;
+        }
+        for (const c of child.content) {
+            if (!("type" in c) || c.type !== "text" || !("text" in c)) {
+                continue;
+            }
+            const before = c.text;
+            const after = typeof search === "string"
+                ? replaceAll(before, search, replacement)
+                : before.replace(search, replacement);
+            if (after !== before) {
+                c.text = after;
+                count += typeof search === "string" ? countOccurrences(before, search) : 1;
+            }
+        }
+    }
+    // If no per-run matches, try cross-run replacement
+    if (count === 0) {
+        const fullText = paragraphText(para);
+        const newText = typeof search === "string"
+            ? replaceAll(fullText, search, replacement)
+            : fullText.replace(search, replacement);
+        if (newText !== fullText) {
+            // Rebuild: put all text into first text run, clear others
+            let placed = false;
+            for (const child of para.children) {
+                if (!("content" in child) || !Array.isArray(child.content)) {
+                    continue;
+                }
+                for (const c of child.content) {
+                    if (!("type" in c) || c.type !== "text" || !("text" in c)) {
+                        continue;
+                    }
+                    if (!placed) {
+                        c.text = newText;
+                        placed = true;
+                    }
+                    else {
+                        c.text = "";
+                    }
+                }
+            }
+            count = typeof search === "string" ? countOccurrences(fullText, search) : 1;
+        }
+    }
+    return count;
+}
+function replaceAll(str, search, replacement) {
+    if (search === "") {
+        return str;
+    }
+    return str.replaceAll(search, replacement);
+}
+function countOccurrences(str, search) {
+    if (search === "") {
+        return 0;
+    }
+    return str.split(search).length - 1;
+}
+/**
+ * Read an existing DOCX file, replace placeholders with content, and produce a new DOCX.
+ *
+ * Placeholders are strings like `{{name}}` embedded in the document text.
+ * They may span across multiple runs — the patcher handles cross-run matching.
+ *
+ * Supported patch content types:
+ * - `text` — simple text replacement (preserves formatting of the first run)
+ * - `paragraph` — replaces the entire paragraph containing the placeholder
+ * - `table` — replaces the entire paragraph with a table
+ * - `image` — replaces the placeholder with an inline image
+ *
+ * @param buffer - The source DOCX file as a Uint8Array.
+ * @param patches - Array of patch operations to apply.
+ * @param options - Optional compression settings.
+ * @returns New DOCX file as a Uint8Array.
+ */
+export async function patchDocument(buffer, patches, options) {
+    const doc = await readDocx(buffer);
+    // Build lookup map for quick placeholder matching
+    const patchMap = new Map();
+    for (const patch of patches) {
+        patchMap.set(patch.placeholder, patch);
+    }
+    // Process body content
+    const newBody = [];
+    for (const block of doc.body) {
+        if (block.type === "paragraph") {
+            const result = patchParagraph(block, patchMap);
+            if (result) {
+                if (Array.isArray(result)) {
+                    newBody.push(...result);
+                }
+                else {
+                    newBody.push(result);
+                }
+            }
+        }
+        else if (block.type === "table") {
+            patchTable(block, patchMap);
+            newBody.push(block);
+        }
+        else {
+            newBody.push(block);
+        }
+    }
+    // Patch headers
+    if (doc.headers) {
+        for (const [, headerDef] of doc.headers) {
+            patchHeaderFooterContent(headerDef.content, patchMap);
+        }
+    }
+    // Patch footers
+    if (doc.footers) {
+        for (const [, footerDef] of doc.footers) {
+            patchHeaderFooterContent(footerDef.content, patchMap);
+        }
+    }
+    // Add any new images from patches
+    const images = doc.images ? [...doc.images] : [];
+    for (const patch of patches) {
+        if (patch.content.type === "image") {
+            const imgContent = patch.content;
+            const existing = images.find(i => i.fileName === imgContent.image.fileName);
+            if (!existing) {
+                images.push(imgContent.image);
+            }
+        }
+    }
+    const patched = {
+        ...doc,
+        body: newBody,
+        images: images.length > 0 ? images : undefined
+    };
+    return packageDocx(patched, options?.compressionLevel);
+}
+/** Patch a paragraph — returns replacement content or null to remove. */
+function patchParagraph(para, patchMap) {
+    const text = paragraphText(para);
+    for (const [placeholder, patch] of patchMap) {
+        if (!text.includes(placeholder)) {
+            continue;
+        }
+        switch (patch.content.type) {
+            case "text": {
+                replaceInParagraph(para, placeholder, patch.content.text);
+                return para;
+            }
+            case "paragraph": {
+                return patch.content.children;
+            }
+            case "table": {
+                return patch.content.table;
+            }
+            case "image": {
+                const img = patch.content.image;
+                const rId = img.rId ?? `rId_img_${img.fileName}`;
+                const imgContent = {
+                    type: "image",
+                    rId,
+                    width: patch.content.width,
+                    height: patch.content.height,
+                    altText: img.fileName,
+                    name: img.fileName
+                };
+                const newPara = {
+                    type: "paragraph",
+                    properties: para.properties,
+                    children: [{ content: [imgContent] }]
+                };
+                return newPara;
+            }
+        }
+    }
+    return para;
+}
+/** Patch text inside table cells recursively. */
+function patchTable(table, patchMap) {
+    for (const row of table.rows) {
+        for (const cell of row.cells) {
+            const newContent = [];
+            for (const block of cell.content) {
+                if (block.type === "paragraph") {
+                    const result = patchParagraph(block, patchMap);
+                    if (result) {
+                        if (Array.isArray(result)) {
+                            newContent.push(...result);
+                        }
+                        else {
+                            newContent.push(result);
+                        }
+                    }
+                }
+                else if (block.type === "table") {
+                    patchTable(block, patchMap);
+                    newContent.push(block);
+                }
+                else {
+                    newContent.push(block);
+                }
+            }
+            cell.content = newContent;
+        }
+    }
+}
+/** Patch text in header/footer content. */
+function patchHeaderFooterContent(content, patchMap) {
+    for (const child of content.children) {
+        if (child.type === "paragraph") {
+            for (const [placeholder, patch] of patchMap) {
+                if (patch.content.type === "text") {
+                    const text = paragraphText(child);
+                    if (text.includes(placeholder)) {
+                        replaceInParagraph(child, placeholder, patch.content.text);
+                    }
+                }
+            }
+        }
+    }
+}