@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/esm/modules/word/template/template-engine.js

@@ -0,0 +1,1435 @@
+/**
+ * DOCX Module - Template Engine
+ *
+ * A template engine for DOCX documents supporting:
+ * - Variable interpolation: {{name}}, {{user.name}}
+ * - Conditionals: {{#if cond}}...{{/if}}, {{#if cond}}...{{else}}...{{/if}}
+ * - Loops: {{#each items}}...{{/each}} with {{.}}, {{.prop}}, {{@index}}
+ * - Table row loops: auto-duplicates table rows when {{#each}} is in a row
+ * - Table column loops: {{#cols items}}...{{/cols}} duplicates columns
+ * - Image placeholders: {{%image}} resolves to an inline image
+ * - RichText placeholders: {{&richText}} resolves to paragraph children
+ * - Sub-document insertion: {{>subDoc}} resolves to body content blocks
+ * - Chart placeholders: {{^chart}} resolves to chart content
+ *
+ * Handles cross-run placeholders (Word often splits {{name}} across runs).
+ */
+import { utf8Encoder } from "../core/internal-utils.js";
+import { isRun } from "../core/text-utils.js";
+import { DocxError } from "../errors.js";
+/** Error thrown when template processing fails. */
+export class TemplateError extends DocxError {
+    constructor(message, placeholder, location, options) {
+        super(message, options);
+        this.name = "TemplateError";
+        this.placeholder = placeholder;
+        this.location = location;
+        this.tagName = options?.tagName;
+        this.paragraphIndex = options?.paragraphIndex;
+        this.sectionPath = options?.sectionPath;
+    }
+}
+// =============================================================================
+// Token Types (internal)
+// =============================================================================
+var TokenType;
+(function (TokenType) {
+    TokenType[TokenType["Text"] = 0] = "Text";
+    TokenType[TokenType["Variable"] = 1] = "Variable";
+    TokenType[TokenType["IfOpen"] = 2] = "IfOpen";
+    TokenType[TokenType["Else"] = 3] = "Else";
+    TokenType[TokenType["IfClose"] = 4] = "IfClose";
+    TokenType[TokenType["EachOpen"] = 5] = "EachOpen";
+    TokenType[TokenType["EachClose"] = 6] = "EachClose";
+})(TokenType || (TokenType = {}));
+// =============================================================================
+// Core: fillTemplate
+// =============================================================================
+/**
+ * Fill a DOCX template document with data.
+ *
+ * Processes all body content, headers, footers, footnotes, and endnotes.
+ * Operates on the document model in-place and returns it.
+ *
+ * @param doc - The parsed DocxDocument model.
+ * @param data - Data to fill into the template.
+ * @param options - Optional template settings.
+ * @returns The same DocxDocument with placeholders resolved.
+ */
+export function fillTemplate(doc, data, options) {
+    const open = options?.delimiters?.[0] ?? "{{";
+    const close = options?.delimiters?.[1] ?? "}}";
+    const strict = options?.strict ?? true;
+    const ctx = { open, close, strict, data };
+    // Process body
+    const newBody = processBodyContent(doc.body, ctx, "body");
+    doc.body = newBody;
+    // Process headers
+    if (doc.headers) {
+        for (const [key, headerDef] of doc.headers) {
+            const newChildren = processBlockList(headerDef.content.children, ctx, `header:${key}`);
+            headerDef.content.children = newChildren;
+        }
+    }
+    // Process footers
+    if (doc.footers) {
+        for (const [key, footerDef] of doc.footers) {
+            const newChildren = processBlockList(footerDef.content.children, ctx, `footer:${key}`);
+            footerDef.content.children = newChildren;
+        }
+    }
+    // Process footnotes
+    if (doc.footnotes) {
+        for (const note of doc.footnotes) {
+            if (note.id <= 0) {
+                continue;
+            }
+            const processed = processBlockList(note.content, ctx, `footnote:${note.id}`);
+            note.content = processed;
+        }
+    }
+    // Process endnotes
+    if (doc.endnotes) {
+        for (const note of doc.endnotes) {
+            if (note.id <= 0) {
+                continue;
+            }
+            const processed = processBlockList(note.content, ctx, `endnote:${note.id}`);
+            note.content = processed;
+        }
+    }
+    return doc;
+}
+// =============================================================================
+// Cross-run text merging
+// =============================================================================
+/**
+ * Merge all text content from a paragraph's runs into a single string.
+ * This is intentionally simple — only extracts raw text from runs (no hyperlinks,
+ * no tracked changes) as template placeholders only exist in direct run content.
+ */
+function extractParagraphText(para) {
+    let result = "";
+    for (const child of para.children) {
+        if (!isRun(child)) {
+            continue;
+        }
+        for (const c of child.content) {
+            if (c.type === "text" && "text" in c) {
+                result += c.text;
+            }
+        }
+    }
+    return result;
+}
+// =============================================================================
+// Tokenizer
+// =============================================================================
+function tokenize(text, open, close) {
+    const tokens = [];
+    let pos = 0;
+    while (pos < text.length) {
+        const startIdx = text.indexOf(open, pos);
+        if (startIdx === -1) {
+            tokens.push({ type: TokenType.Text, value: text.slice(pos) });
+            break;
+        }
+        if (startIdx > pos) {
+            tokens.push({ type: TokenType.Text, value: text.slice(pos, startIdx) });
+        }
+        const endIdx = text.indexOf(close, startIdx + open.length);
+        if (endIdx === -1) {
+            // Unclosed delimiter — treat rest as text
+            tokens.push({ type: TokenType.Text, value: text.slice(startIdx) });
+            break;
+        }
+        const expr = text.slice(startIdx + open.length, endIdx).trim();
+        pos = endIdx + close.length;
+        if (expr.startsWith("#if ")) {
+            tokens.push({ type: TokenType.IfOpen, condition: expr.slice(4).trim() });
+        }
+        else if (expr === "else") {
+            tokens.push({ type: TokenType.Else });
+        }
+        else if (expr === "/if") {
+            tokens.push({ type: TokenType.IfClose });
+        }
+        else if (expr.startsWith("#each ")) {
+            tokens.push({ type: TokenType.EachOpen, collection: expr.slice(6).trim() });
+        }
+        else if (expr === "/each") {
+            tokens.push({ type: TokenType.EachClose });
+        }
+        else {
+            tokens.push({ type: TokenType.Variable, path: expr });
+        }
+    }
+    return tokens;
+}
+// =============================================================================
+// Value resolution
+// =============================================================================
+function resolvePath(data, path) {
+    if (path === ".") {
+        // In loop context, "." refers to the current item stored at key "."
+        if (data != null && typeof data === "object" && Object.hasOwn(data, ".")) {
+            return data["."];
+        }
+        return data;
+    }
+    const startPath = path.startsWith(".") ? path.slice(1) : path;
+    const parts = startPath.split(".");
+    let current = data;
+    for (const part of parts) {
+        if (current == null || typeof current !== "object") {
+            return undefined;
+        }
+        // Use Object.hasOwn so a template path can never traverse prototype
+        // properties (`{{constructor}}`, `{{__proto__.something}}`, …) and
+        // surface JS internals into the rendered document. Arrays are
+        // handled the same way — numeric indices are own properties.
+        if (!Object.hasOwn(current, part)) {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}
+function isTruthy(value) {
+    if (Array.isArray(value)) {
+        return value.length > 0;
+    }
+    return !!value;
+}
+function valueToString(value) {
+    if (value == null) {
+        return "";
+    }
+    if (typeof value === "object") {
+        return JSON.stringify(value);
+    }
+    return String(value);
+}
+// =============================================================================
+// Processing body content (handles block-level #each and #if)
+// =============================================================================
+function processBodyContent(blocks, ctx, location) {
+    const result = [];
+    let i = 0;
+    while (i < blocks.length) {
+        const block = blocks[i];
+        if (block.type === "paragraph") {
+            const text = extractParagraphText(block);
+            // Check if this paragraph starts a block-level #each
+            if (hasBlockDirective(text, ctx.open, ctx.close, "#each ")) {
+                const collectionExpr = extractDirectiveArg(text, ctx.open, ctx.close, "#each ");
+                const endIdx = findClosingBlock(blocks, i, ctx, "#each ", "/each");
+                if (endIdx === -1) {
+                    throw new TemplateError(`Unclosed {{#each ${collectionExpr}}}`, `#each ${collectionExpr}`, location, {
+                        tagName: `#each ${collectionExpr}`,
+                        paragraphIndex: i,
+                        sectionPath: location
+                    });
+                }
+                const innerBlocks = blocks.slice(i + 1, endIdx);
+                const items = resolvePath(ctx.data, collectionExpr);
+                if (Array.isArray(items)) {
+                    for (let idx = 0; idx < items.length; idx++) {
+                        const itemData = buildLoopData(items[idx], idx, ctx.data);
+                        const innerCtx = { ...ctx, data: itemData };
+                        const processed = processBodyContent(cloneBlocks(innerBlocks), innerCtx, `${location}[${idx}]`);
+                        result.push(...processed);
+                    }
+                }
+                else if (ctx.strict && items !== undefined && items !== null) {
+                    throw new TemplateError(`{{#each ${collectionExpr}}} expects an array, got ${typeof items}`, `#each ${collectionExpr}`, location, {
+                        tagName: `#each ${collectionExpr}`,
+                        paragraphIndex: i,
+                        sectionPath: location
+                    });
+                }
+                i = endIdx + 1;
+                continue;
+            }
+            // Check if this paragraph starts a block-level #if
+            if (hasBlockDirective(text, ctx.open, ctx.close, "#if ")) {
+                const condExpr = extractDirectiveArg(text, ctx.open, ctx.close, "#if ");
+                const { elseIdx, endIdx } = findIfBlock(blocks, i, ctx);
+                if (endIdx === -1) {
+                    throw new TemplateError(`Unclosed {{#if ${condExpr}}}`, `#if ${condExpr}`, location, {
+                        tagName: `#if ${condExpr}`,
+                        paragraphIndex: i,
+                        sectionPath: location
+                    });
+                }
+                const condValue = resolvePath(ctx.data, condExpr);
+                let innerBlocks;
+                if (isTruthy(condValue)) {
+                    innerBlocks = blocks.slice(i + 1, elseIdx !== -1 ? elseIdx : endIdx);
+                }
+                else {
+                    innerBlocks = elseIdx !== -1 ? blocks.slice(elseIdx + 1, endIdx) : [];
+                }
+                const processed = processBodyContent(cloneBlocks(innerBlocks), ctx, location);
+                result.push(...processed);
+                i = endIdx + 1;
+                continue;
+            }
+            // Regular paragraph — process inline templates
+            try {
+                const processed = processParagraph(block, ctx, `${location} para ${i}`);
+                result.push(processed);
+            }
+            catch (err) {
+                if (err instanceof TemplateError && err.tagName === undefined) {
+                    throw new TemplateError(err.message, err.placeholder, err.location, {
+                        cause: err.cause,
+                        tagName: err.placeholder,
+                        paragraphIndex: i,
+                        sectionPath: location
+                    });
+                }
+                throw err;
+            }
+            i++;
+        }
+        else if (block.type === "table") {
+            const processed = processTable(block, ctx, `${location} table ${i}`);
+            result.push(processed);
+            i++;
+        }
+        else if (block.type === "sdt") {
+            // Recursively process SDT content (StructuredDocumentTag)
+            const sdt = block;
+            const processedContent = processBodyContent(sdt.content, ctx, `${location} sdt ${i}`);
+            result.push({
+                ...sdt,
+                content: processedContent
+            });
+            i++;
+        }
+        else {
+            result.push(block);
+            i++;
+        }
+    }
+    return result;
+}
+function processBlockList(blocks, ctx, location) {
+    // Reuse body content processing, filtering to Paragraph | Table
+    return processBodyContent(blocks, ctx, location);
+}
+// =============================================================================
+// Paragraph processing (inline variable substitution)
+// =============================================================================
+function processParagraph(para, ctx, location) {
+    // Merge all run text, resolve inline variables, then rebuild runs
+    const fullText = extractParagraphText(para);
+    // Quick check: does this paragraph contain any delimiters?
+    if (!fullText.includes(ctx.open)) {
+        return para;
+    }
+    // Tokenize and evaluate inline expressions
+    const tokens = tokenize(fullText, ctx.open, ctx.close);
+    const resolved = evaluateInlineTokens(tokens, ctx, location);
+    // If the text didn't change, return as-is
+    if (resolved === fullText) {
+        return para;
+    }
+    // Rebuild the paragraph runs with the resolved text
+    return rebuildParagraphText(para, resolved);
+}
+/**
+ * Evaluate inline tokens (only variables and inline if/each within a single paragraph line).
+ * For simplicity, inline conditionals and loops are evaluated as text.
+ */
+function evaluateInlineTokens(tokens, ctx, location) {
+    let result = "";
+    let i = 0;
+    while (i < tokens.length) {
+        const token = tokens[i];
+        switch (token.type) {
+            case TokenType.Text:
+                result += token.value;
+                i++;
+                break;
+            case TokenType.Variable: {
+                const path = token.path;
+                let value;
+                if (path === "@index") {
+                    value = resolvePath(ctx.data, "@index");
+                }
+                else {
+                    value = resolvePath(ctx.data, path);
+                }
+                if (value === undefined && ctx.strict) {
+                    throw new TemplateError(`Unresolved variable: {{${path}}}`, path, location, {
+                        tagName: path,
+                        sectionPath: location
+                    });
+                }
+                result += valueToString(value);
+                i++;
+                break;
+            }
+            case TokenType.IfOpen: {
+                // Inline if: collect tokens until matching /if
+                const condValue = resolvePath(ctx.data, token.condition);
+                const { trueBranch, falseBranch, endIndex } = collectInlineIf(tokens, i);
+                if (endIndex === -1) {
+                    throw new TemplateError(`Unclosed inline {{#if ${token.condition}}}`, `#if ${token.condition}`, location, { tagName: `#if ${token.condition}`, sectionPath: location });
+                }
+                if (isTruthy(condValue)) {
+                    result += evaluateInlineTokens(trueBranch, ctx, location);
+                }
+                else {
+                    result += evaluateInlineTokens(falseBranch, ctx, location);
+                }
+                i = endIndex + 1;
+                break;
+            }
+            case TokenType.EachOpen: {
+                // Inline each: collect tokens until matching /each
+                const items = resolvePath(ctx.data, token.collection);
+                const { body, endIndex } = collectInlineEach(tokens, i);
+                if (endIndex === -1) {
+                    throw new TemplateError(`Unclosed inline {{#each ${token.collection}}}`, `#each ${token.collection}`, location, { tagName: `#each ${token.collection}`, sectionPath: location });
+                }
+                if (Array.isArray(items)) {
+                    for (let idx = 0; idx < items.length; idx++) {
+                        const itemData = buildLoopData(items[idx], idx, ctx.data);
+                        const innerCtx = { ...ctx, data: itemData };
+                        result += evaluateInlineTokens(body, innerCtx, location);
+                    }
+                }
+                i = endIndex + 1;
+                break;
+            }
+            default:
+                // Stray else/close tokens — skip
+                i++;
+                break;
+        }
+    }
+    return result;
+}
+function collectInlineIf(tokens, startIdx) {
+    let depth = 0;
+    const trueBranch = [];
+    const falseBranch = [];
+    let inElse = false;
+    let endIndex = -1;
+    for (let i = startIdx + 1; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (t.type === TokenType.IfOpen) {
+            depth++;
+            (inElse ? falseBranch : trueBranch).push(t);
+        }
+        else if (t.type === TokenType.IfClose) {
+            if (depth === 0) {
+                endIndex = i;
+                break;
+            }
+            depth--;
+            (inElse ? falseBranch : trueBranch).push(t);
+        }
+        else if (t.type === TokenType.Else && depth === 0) {
+            inElse = true;
+        }
+        else {
+            (inElse ? falseBranch : trueBranch).push(t);
+        }
+    }
+    return { trueBranch, falseBranch, endIndex };
+}
+function collectInlineEach(tokens, startIdx) {
+    let depth = 0;
+    const body = [];
+    let endIndex = -1;
+    for (let i = startIdx + 1; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (t.type === TokenType.EachOpen) {
+            depth++;
+            body.push(t);
+        }
+        else if (t.type === TokenType.EachClose) {
+            if (depth === 0) {
+                endIndex = i;
+                break;
+            }
+            depth--;
+            body.push(t);
+        }
+        else {
+            body.push(t);
+        }
+    }
+    return { body, endIndex };
+}
+// =============================================================================
+// Rebuild paragraph with new text content
+// =============================================================================
+/**
+ * Rebuild a paragraph's run text content with a new resolved string.
+ * Preserves the formatting of the first text run.
+ */
+function rebuildParagraphText(para, newText) {
+    // Find the first run with text content to use as formatting reference
+    let refProperties;
+    for (const child of para.children) {
+        if (!isRun(child)) {
+            continue;
+        }
+        for (const c of child.content) {
+            if (c.type === "text") {
+                refProperties = child.properties;
+                break;
+            }
+        }
+        if (refProperties !== undefined) {
+            break;
+        }
+    }
+    // If no text runs found, get properties from first run
+    if (refProperties === undefined) {
+        for (const child of para.children) {
+            if (isRun(child)) {
+                refProperties = child.properties;
+                break;
+            }
+        }
+    }
+    // Build new children:
+    //   - replace the first Run we see with `newRun` (carrying the resolved text);
+    //   - drop every other Run (their text was already concatenated into newText);
+    //   - keep non-Run children (bookmarkStart / bookmarkEnd / commentRangeStart /
+    //     commentRangeEnd / hyperlink / insertedRun / movedToRun / etc.) at
+    //     their original index. Reordering these silently miswires bookmark and
+    //     comment ranges, since the start/end markers stop bracketing the
+    //     intended content.
+    const newRun = {
+        properties: refProperties,
+        content: [{ type: "text", text: newText }]
+    };
+    const newChildren = [];
+    let runReplaced = false;
+    for (const child of para.children) {
+        if (isRun(child)) {
+            if (!runReplaced) {
+                newChildren.push(newRun);
+                runReplaced = true;
+            }
+            // Subsequent runs are absorbed into newRun's text — drop them.
+        }
+        else {
+            newChildren.push(child);
+        }
+    }
+    // If the paragraph had no runs at all (rare — typically all bookmark
+    // markers), append newRun at the end so the rendered text still appears.
+    if (!runReplaced) {
+        newChildren.push(newRun);
+    }
+    return {
+        ...para,
+        children: newChildren
+    };
+}
+// =============================================================================
+// Table processing (row-level loops)
+// =============================================================================
+function processTable(table, ctx, location) {
+    const newRows = [];
+    let i = 0;
+    while (i < table.rows.length) {
+        const row = table.rows[i];
+        const rowText = extractRowText(row);
+        // Check if this row contains a #each directive
+        if (rowText.includes(ctx.open + "#each ") || rowText.includes(ctx.open + " #each ")) {
+            const collectionExpr = extractDirectiveFromText(rowText, ctx.open, ctx.close, "#each ");
+            if (collectionExpr) {
+                // Find the closing row
+                const endRowIdx = findClosingTableRow(table.rows, i, ctx);
+                if (endRowIdx === -1) {
+                    throw new TemplateError(`Unclosed {{#each ${collectionExpr}}} in table row`, `#each ${collectionExpr}`, location, {
+                        tagName: `#each ${collectionExpr}`,
+                        paragraphIndex: i,
+                        sectionPath: location
+                    });
+                }
+                const items = resolvePath(ctx.data, collectionExpr);
+                if (Array.isArray(items)) {
+                    // If the loop is on a single row (open and close on same row)
+                    if (endRowIdx === i) {
+                        for (let idx = 0; idx < items.length; idx++) {
+                            const itemData = buildLoopData(items[idx], idx, ctx.data);
+                            const innerCtx = { ...ctx, data: itemData };
+                            const clonedRow = cloneRow(row);
+                            const processedRow = processTableRow(clonedRow, innerCtx, location);
+                            // Strip the #each and /each tags from the row
+                            const cleanedRow = stripDirectivesFromRow(processedRow, ctx, "#each ", "/each");
+                            newRows.push(cleanedRow);
+                        }
+                    }
+                    else {
+                        // Multi-row loop: duplicate all rows between open and close
+                        const templateRows = table.rows.slice(i, endRowIdx + 1);
+                        for (let idx = 0; idx < items.length; idx++) {
+                            const itemData = buildLoopData(items[idx], idx, ctx.data);
+                            const innerCtx = { ...ctx, data: itemData };
+                            for (const templateRow of templateRows) {
+                                const clonedRow = cloneRow(templateRow);
+                                const processedRow = processTableRow(clonedRow, innerCtx, location);
+                                const cleanedRow = stripDirectivesFromRow(processedRow, ctx, "#each ", "/each");
+                                newRows.push(cleanedRow);
+                            }
+                        }
+                    }
+                }
+                i = endRowIdx + 1;
+                continue;
+            }
+        }
+        // Regular row: process inline templates in each cell
+        const processedRow = processTableRow(row, ctx, location);
+        newRows.push(processedRow);
+        i++;
+    }
+    return {
+        ...table,
+        rows: newRows
+    };
+}
+function processTableRow(row, ctx, location) {
+    const newCells = [];
+    for (const cell of row.cells) {
+        const newContent = [];
+        for (const block of cell.content) {
+            if (block.type === "paragraph") {
+                newContent.push(processParagraph(block, ctx, location));
+            }
+            else if (block.type === "table") {
+                newContent.push(processTable(block, ctx, location));
+            }
+            else {
+                newContent.push(block);
+            }
+        }
+        newCells.push({ ...cell, content: newContent });
+    }
+    return { ...row, cells: newCells };
+}
+function extractRowText(row) {
+    let text = "";
+    for (const cell of row.cells) {
+        for (const block of cell.content) {
+            if (block.type === "paragraph") {
+                text += extractParagraphText(block);
+            }
+        }
+    }
+    return text;
+}
+function findClosingTableRow(rows, startIdx, ctx) {
+    // We start AFTER having seen exactly one `{{#each ...}}` token, so the
+    // virtual depth at the boundary into row `startIdx` is 1. Each row can
+    // contain any mix of `{{#each ...}}` opens and `{{/each}}` closes; we
+    // increment the depth by `opens` and decrement by `closes`. The first
+    // row where depth hits zero is the closing row.
+    //
+    // A previous implementation lumped both adjustments together and
+    // returned as soon as `depth === 0 && closes > 0`, which mis-handled
+    // rows containing two opens and one close (depth ends at 1, but the
+    // intermediate calculation hit a transient zero).
+    let depth = 1;
+    for (let i = startIdx; i < rows.length; i++) {
+        const text = extractRowText(rows[i]);
+        let opens = countOccurrences(text, ctx.open + "#each ");
+        const closes = countOccurrences(text, ctx.open + "/each" + ctx.close);
+        // The opening `{{#each ...}}` of the current loop is in row
+        // startIdx; don't count it as opening a new nested loop.
+        if (i === startIdx && opens > 0) {
+            opens--;
+        }
+        // Walk the row token-by-token in opens-then-closes order. We don't
+        // know the actual interleave from raw counts, so we apply opens
+        // first, then closes — opens always come before their matching
+        // close in valid templates, and a row that closes more than it
+        // opens (other than the top-level close in this very row) is
+        // malformed input we should still terminate on.
+        depth += opens;
+        if (depth <= 0 && opens === 0 && closes === 0) {
+            // Defensive: should never happen because we entered with depth=1.
+            return -1;
+        }
+        if (closes >= depth) {
+            // Consume `depth` worth of closes in this row; the remainder, if
+            // any, is malformed but stops the search here.
+            return i;
+        }
+        depth -= closes;
+    }
+    return -1;
+}
+function stripDirectivesFromRow(row, ctx, openDir, closeDir) {
+    const newCells = [];
+    for (const cell of row.cells) {
+        const newContent = [];
+        for (const block of cell.content) {
+            if (block.type === "paragraph") {
+                const text = extractParagraphText(block);
+                // Remove directive tags
+                const openPattern = ctx.open + openDir;
+                const closePattern = ctx.open + closeDir + ctx.close;
+                if (text.includes(openPattern) || text.includes(closePattern)) {
+                    let cleaned = text;
+                    // Remove the entire {{#each ...}} tag
+                    const eachOpenRegex = new RegExp(escapeRegex(ctx.open) +
+                        "\\s*" +
+                        escapeRegex(openDir) +
+                        "[^" +
+                        escapeRegex(ctx.close.charAt(0)) +
+                        "]*" +
+                        escapeRegex(ctx.close), "g");
+                    cleaned = cleaned.replace(eachOpenRegex, "");
+                    // Remove {{/each}}
+                    const eachCloseRegex = new RegExp(escapeRegex(ctx.open) +
+                        "\\s*" +
+                        escapeRegex(closeDir) +
+                        "\\s*" +
+                        escapeRegex(ctx.close), "g");
+                    cleaned = cleaned.replace(eachCloseRegex, "");
+                    cleaned = cleaned.trim();
+                    if (cleaned.length > 0) {
+                        newContent.push(rebuildParagraphText(block, cleaned));
+                    }
+                    else {
+                        // Keep at least one paragraph in a cell
+                        newContent.push(rebuildParagraphText(block, ""));
+                    }
+                }
+                else {
+                    newContent.push(block);
+                }
+            }
+            else {
+                newContent.push(block);
+            }
+        }
+        newCells.push({
+            ...cell,
+            content: newContent.length > 0 ? newContent : [{ type: "paragraph", children: [] }]
+        });
+    }
+    return { ...row, cells: newCells };
+}
+// =============================================================================
+// Block-level directive helpers
+// =============================================================================
+function hasBlockDirective(text, open, close, directive) {
+    // Block-level directives must occupy the *entire* paragraph (modulo
+    // surrounding whitespace). A paragraph like "Hello {{#if x}}A{{/if}}"
+    // contains an *inline* directive and must not be re-classified as a block
+    // directive — otherwise the engine tries to find the block close on
+    // following paragraphs and emits "Unclosed {{#if x}}" errors.
+    const trimmed = text.trim();
+    const opener = open + directive;
+    if (!trimmed.startsWith(opener)) {
+        return false;
+    }
+    // The opener tag must close before any other text follows. e.g. valid:
+    //   "{{#if x}}"          → block
+    //   "{{#if x}}\n"        → block
+    //   "{{#if x}}foo"       → inline (has trailing content on same paragraph)
+    const tagEnd = trimmed.indexOf(close, opener.length);
+    if (tagEnd === -1) {
+        return false;
+    }
+    const afterTag = trimmed.slice(tagEnd + close.length).trim();
+    return afterTag.length === 0;
+}
+function extractDirectiveArg(text, open, close, directive) {
+    const startIdx = text.indexOf(open + directive);
+    if (startIdx === -1) {
+        // Try with space variations
+        const idx = text.indexOf(open + " " + directive);
+        if (idx === -1) {
+            return "";
+        }
+        const argStart = idx + open.length + 1 + directive.length;
+        const endIdx = text.indexOf(close, argStart);
+        if (endIdx === -1) {
+            return "";
+        }
+        return text.slice(argStart, endIdx).trim();
+    }
+    const argStart = startIdx + open.length + directive.length;
+    const endIdx = text.indexOf(close, argStart);
+    if (endIdx === -1) {
+        return "";
+    }
+    return text.slice(argStart, endIdx).trim();
+}
+function extractDirectiveFromText(text, open, close, directive) {
+    const pattern = open + directive;
+    const idx = text.indexOf(pattern);
+    if (idx === -1) {
+        return null;
+    }
+    const argStart = idx + pattern.length;
+    const endIdx = text.indexOf(close, argStart);
+    if (endIdx === -1) {
+        return null;
+    }
+    return text.slice(argStart, endIdx).trim();
+}
+function findClosingBlock(blocks, startIdx, ctx, openDir, closeDir) {
+    let depth = 0;
+    for (let i = startIdx + 1; i < blocks.length; i++) {
+        const block = blocks[i];
+        if (block.type !== "paragraph") {
+            continue;
+        }
+        const text = extractParagraphText(block);
+        if (hasBlockDirective(text, ctx.open, ctx.close, openDir)) {
+            depth++;
+        }
+        if (text.includes(ctx.open + closeDir + ctx.close) ||
+            text.includes(ctx.open + " " + closeDir + " " + ctx.close)) {
+            if (depth === 0) {
+                return i;
+            }
+            depth--;
+        }
+    }
+    return -1;
+}
+function findIfBlock(blocks, startIdx, ctx) {
+    let depth = 0;
+    let elseIdx = -1;
+    for (let i = startIdx + 1; i < blocks.length; i++) {
+        const block = blocks[i];
+        if (block.type !== "paragraph") {
+            continue;
+        }
+        const text = extractParagraphText(block);
+        // A single paragraph can legitimately contain both `{{#if cond}}` and
+        // `{{/if}}` (an inline if). Count opens and closes independently so the
+        // pairing logic stays correct in that case — the previous else-if chain
+        // would advance `depth` and then skip the close, leaving the block
+        // permanently unterminated.
+        const openCount = countOccurrences(text, ctx.open + "#if ");
+        const closeCount = countOccurrences(text, ctx.open + "/if" + ctx.close) +
+            countOccurrences(text, ctx.open + " /if " + ctx.close);
+        if (closeCount > 0) {
+            // Account for inline opens first, then balance closes against the
+            // outstanding depth.
+            depth += openCount;
+            for (let c = 0; c < closeCount; c++) {
+                if (depth === 0) {
+                    return { elseIdx, endIdx: i };
+                }
+                depth--;
+            }
+        }
+        else if (openCount > 0) {
+            depth += openCount;
+        }
+        else if (depth === 0 &&
+            (text.trim() === ctx.open + "else" + ctx.close ||
+                text.includes(ctx.open + "else" + ctx.close))) {
+            elseIdx = i;
+        }
+    }
+    return { elseIdx, endIdx: -1 };
+}
+// =============================================================================
+// Loop data construction
+// =============================================================================
+function buildLoopData(item, index, parentData) {
+    // Build the loop context on a null-prototype object so that an item
+    // like `{ "__proto__": { injected: "X" } }` (which JSON.parse will
+    // produce as an own enumerable data property — a known
+    // prototype-pollution vector) cannot retarget the result's prototype
+    // and leak hidden fields into the rendered document.
+    const result = Object.create(null);
+    for (const key of Object.keys(parentData)) {
+        if (key === "__proto__" || key === "constructor" || key === "prototype") {
+            // Skip dangerous keys at the parent level too.
+            continue;
+        }
+        result[key] = parentData[key];
+    }
+    result["@index"] = index;
+    result["."] = item;
+    // If item is an object, spread its OWN properties so {{.name}} and
+    // {{name}} both work. Skip the same dangerous key set defensively.
+    if (item != null && typeof item === "object" && !Array.isArray(item)) {
+        const obj = item;
+        for (const key of Object.keys(obj)) {
+            if (key === "__proto__" || key === "constructor" || key === "prototype") {
+                continue;
+            }
+            // Object.hasOwn ensures we never copy something that came from the
+            // prototype (Object.keys already returns only own enumerables, but
+            // belt-and-braces).
+            if (Object.hasOwn(obj, key)) {
+                result[key] = obj[key];
+            }
+        }
+    }
+    return result;
+}
+// =============================================================================
+// Cloning helpers
+// =============================================================================
+function cloneBlocks(blocks) {
+    return structuredClone(blocks);
+}
+function cloneRow(row) {
+    return structuredClone(row);
+}
+// =============================================================================
+// Utility
+// =============================================================================
+function countOccurrences(text, search) {
+    let count = 0;
+    let pos = 0;
+    while (true) {
+        const idx = text.indexOf(search, pos);
+        if (idx === -1) {
+            break;
+        }
+        count++;
+        pos = idx + search.length;
+    }
+    return count;
+}
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+// =============================================================================
+// Tag Listing: discover all template placeholders in a document
+// =============================================================================
+/**
+ * List all template tags found in a document.
+ *
+ * Scans body, headers, footers, footnotes, and endnotes for template
+ * placeholders. Useful for validating data objects against templates.
+ *
+ * @param doc - The parsed DocxDocument model.
+ * @param options - Optional settings (custom delimiters).
+ * @returns Array of all discovered template tags.
+ */
+export function listTemplateTags(doc, options) {
+    const open = options?.delimiters?.[0] ?? "{{";
+    const close = options?.delimiters?.[1] ?? "}}";
+    const tags = [];
+    function scanBlocks(blocks, location) {
+        for (let i = 0; i < blocks.length; i++) {
+            const block = blocks[i];
+            if (block.type === "paragraph") {
+                scanParagraph(block, `${location} paragraph ${i}`);
+            }
+            else if (block.type === "table") {
+                scanTable(block, `${location} table ${i}`);
+            }
+        }
+    }
+    function scanParagraph(para, location) {
+        const text = extractParagraphText(para);
+        scanText(text, location);
+    }
+    function scanTable(table, location) {
+        for (let r = 0; r < table.rows.length; r++) {
+            const row = table.rows[r];
+            for (let c = 0; c < row.cells.length; c++) {
+                const cell = row.cells[c];
+                for (let b = 0; b < cell.content.length; b++) {
+                    const block = cell.content[b];
+                    if (block.type === "paragraph") {
+                        scanParagraph(block, `${location} row ${r} cell ${c}`);
+                    }
+                    else if (block.type === "table") {
+                        scanTable(block, `${location} row ${r} cell ${c}`);
+                    }
+                }
+            }
+        }
+    }
+    function scanText(text, location) {
+        let pos = 0;
+        while (pos < text.length) {
+            const startIdx = text.indexOf(open, pos);
+            if (startIdx === -1) {
+                break;
+            }
+            const endIdx = text.indexOf(close, startIdx + open.length);
+            if (endIdx === -1) {
+                break;
+            }
+            const expr = text.slice(startIdx + open.length, endIdx).trim();
+            pos = endIdx + close.length;
+            if (expr.startsWith("#if ")) {
+                tags.push({ expression: expr, type: "ifOpen", location });
+            }
+            else if (expr === "else") {
+                tags.push({ expression: expr, type: "else", location });
+            }
+            else if (expr === "/if") {
+                tags.push({ expression: expr, type: "ifClose", location });
+            }
+            else if (expr.startsWith("#each ")) {
+                tags.push({ expression: expr, type: "eachOpen", location });
+            }
+            else if (expr === "/each") {
+                tags.push({ expression: expr, type: "eachClose", location });
+            }
+            else if (expr.startsWith("#cols ")) {
+                tags.push({ expression: expr, type: "colsOpen", location });
+            }
+            else if (expr === "/cols") {
+                tags.push({ expression: expr, type: "colsClose", location });
+            }
+            else if (expr.startsWith("%")) {
+                tags.push({ expression: expr, type: "image", location });
+            }
+            else if (expr.startsWith("&")) {
+                tags.push({ expression: expr, type: "richText", location });
+            }
+            else if (expr.startsWith(">")) {
+                tags.push({ expression: expr, type: "subDocument", location });
+            }
+            else if (expr.startsWith("^")) {
+                tags.push({ expression: expr, type: "chart", location });
+            }
+            else if (expr.startsWith("!")) {
+                tags.push({ expression: expr, type: "htmlChunk", location });
+            }
+            else {
+                tags.push({ expression: expr, type: "variable", location });
+            }
+        }
+    }
+    // Scan body
+    scanBlocks(doc.body, "body");
+    // Scan headers
+    if (doc.headers) {
+        for (const [key, headerDef] of doc.headers) {
+            scanBlocks(headerDef.content.children, `header:${key}`);
+        }
+    }
+    // Scan footers
+    if (doc.footers) {
+        for (const [key, footerDef] of doc.footers) {
+            scanBlocks(footerDef.content.children, `footer:${key}`);
+        }
+    }
+    // Scan footnotes
+    if (doc.footnotes) {
+        for (const note of doc.footnotes) {
+            if (note.id <= 0) {
+                continue;
+            }
+            scanBlocks(note.content, `footnote:${note.id}`);
+        }
+    }
+    // Scan endnotes
+    if (doc.endnotes) {
+        for (const note of doc.endnotes) {
+            if (note.id <= 0) {
+                continue;
+            }
+            scanBlocks(note.content, `endnote:${note.id}`);
+        }
+    }
+    return tags;
+}
+// =============================================================================
+// Enhanced value resolution for image/richText/subDocument
+// =============================================================================
+function isTemplateImage(v) {
+    return v != null && typeof v === "object" && "image" in v && "width" in v && "height" in v;
+}
+function isTemplateRichText(v) {
+    if (!Array.isArray(v)) {
+        return false;
+    }
+    // Check that it looks like an array of Run objects (has .content array)
+    return v.length > 0 && "content" in v[0] && Array.isArray(v[0].content);
+}
+function isTemplateSubDocument(v) {
+    if (!Array.isArray(v)) {
+        return false;
+    }
+    // Check that it looks like body content blocks (has .type)
+    return v.length > 0 && "type" in v[0];
+}
+export function isTemplateChart(v) {
+    return v != null && typeof v === "object" && "chart" in v && !("type" in v);
+}
+function isTemplateHtmlChunk(v) {
+    return (v != null &&
+        typeof v === "object" &&
+        "html" in v &&
+        typeof v.html === "string");
+}
+/**
+ * Enhanced fillTemplate that supports image (%img), richText (&rt),
+ * subDocument (>sub), and chart (^chart) placeholders in addition to the
+ * standard variable, conditional, and loop directives.
+ *
+ * Image placeholder: {{%imagePath}} — value must be a TemplateImage object.
+ * RichText placeholder: {{&richPath}} — value must be TemplateRichText (Run[]).
+ * SubDocument placeholder: {{>subPath}} — value must be TemplateSubDocument (BodyContent[]).
+ * Chart placeholder: {{^chartPath}} — value must be a TemplateChart object.
+ */
+export function fillTemplateEnhanced(doc, data, options) {
+    const open = options?.delimiters?.[0] ?? "{{";
+    const close = options?.delimiters?.[1] ?? "}}";
+    const strict = options?.strict ?? true;
+    // First pass: handle image / richText / subDocument in body
+    const collectedImages = [];
+    const newBody = processEnhancedBody(doc.body, data, open, close, strict, collectedImages);
+    // Merge collected images into doc.images (avoid duplicates by fileName)
+    const images = doc.images ? [...doc.images] : [];
+    for (const img of collectedImages) {
+        if (!images.some(existing => existing.fileName === img.fileName)) {
+            images.push(img);
+        }
+    }
+    // Second pass: standard fillTemplate. Note that `fillTemplate` mutates
+    // its input doc in place (it edits `headerDef.content.children` and the
+    // body array directly), so we hand it a deep-cloned wrapper to avoid
+    // sneaking edits back into the caller's doc through shared references
+    // (`modifiedDoc.headers === doc.headers` would otherwise propagate
+    // mutations into `doc`).
+    const modifiedDoc = {
+        ...doc,
+        body: newBody,
+        images: images.length > 0 ? images : undefined,
+        ...(doc.headers
+            ? {
+                headers: new Map(Array.from(doc.headers, ([k, h]) => [
+                    k,
+                    {
+                        ...h,
+                        content: { ...h.content, children: [...h.content.children] }
+                    }
+                ]))
+            }
+            : {}),
+        ...(doc.footers
+            ? {
+                footers: new Map(Array.from(doc.footers, ([k, f]) => [
+                    k,
+                    {
+                        ...f,
+                        content: { ...f.content, children: [...f.content.children] }
+                    }
+                ]))
+            }
+            : {}),
+        ...(doc.footnotes
+            ? { footnotes: doc.footnotes.map(fn => ({ ...fn, content: [...fn.content] })) }
+            : {}),
+        ...(doc.endnotes
+            ? { endnotes: doc.endnotes.map(en => ({ ...en, content: [...en.content] })) }
+            : {})
+    };
+    return fillTemplate(modifiedDoc, data, options);
+}
+function processEnhancedBody(blocks, data, open, close, strict, collectedImages) {
+    const result = [];
+    for (let blockIndex = 0; blockIndex < blocks.length; blockIndex++) {
+        const block = blocks[blockIndex];
+        if (block.type === "paragraph") {
+            const text = extractParagraphText(block);
+            // Check for HTML chunk placeholder ({{!htmlPath}})
+            const htmlMatch = matchSinglePlaceholder(text, open, close, "!");
+            if (htmlMatch) {
+                const value = resolvePath(data, htmlMatch);
+                if (isTemplateHtmlChunk(value)) {
+                    const seq = nextAltChunkSeq();
+                    const altChunk = {
+                        type: "altChunk",
+                        // Use a process-monotonic sequence so two `fillTemplate`
+                        // calls on the same template don't collide on rId or path.
+                        rId: `rId_altchunk_${seq}`,
+                        contentType: value.contentType ?? "text/html",
+                        data: utf8Encoder.encode(value.html),
+                        fileName: `afchunk${seq}.html`
+                    };
+                    result.push(altChunk);
+                    continue;
+                }
+            }
+            // Check for sub-document placeholder (entire paragraph is the placeholder)
+            const subMatch = matchSinglePlaceholder(text, open, close, ">");
+            if (subMatch) {
+                const value = resolvePath(data, subMatch);
+                if (isTemplateSubDocument(value)) {
+                    result.push(...value);
+                    continue;
+                }
+            }
+            // Check for image placeholder (with optional conditional prefix)
+            const imgMatch = matchSinglePlaceholder(text, open, close, "%");
+            if (imgMatch) {
+                // Check for conditional image: {{%?condPath.imagePath}}
+                if (imgMatch.startsWith("?")) {
+                    const rest = imgMatch.slice(1); // remove leading '?'
+                    const dotIdx = rest.indexOf(".");
+                    if (dotIdx !== -1) {
+                        const condPath = rest.slice(0, dotIdx);
+                        const imagePath = rest.slice(dotIdx + 1);
+                        const condValue = resolvePath(data, condPath);
+                        if (!isTruthy(condValue)) {
+                            // Condition is falsy — skip, don't insert anything
+                            continue;
+                        }
+                        // Condition is truthy — resolve the image
+                        const value = resolvePath(data, imagePath);
+                        if (isTemplateImage(value)) {
+                            const safeFileName = sanitizeTemplateImageFileName(value.image.fileName);
+                            const rId = value.image.rId ?? `rId_tpl_${nextTemplateImageSeq()}`;
+                            const imgContent = {
+                                type: "image",
+                                rId,
+                                width: value.width,
+                                height: value.height,
+                                altText: value.altText ?? safeFileName,
+                                name: safeFileName
+                            };
+                            const newPara = {
+                                type: "paragraph",
+                                properties: block.properties,
+                                children: [{ content: [imgContent] }]
+                            };
+                            result.push(newPara);
+                            collectedImages.push({ ...value.image, rId, fileName: safeFileName });
+                            continue;
+                        }
+                    }
+                }
+                // Standard image placeholder (no conditional)
+                const value = resolvePath(data, imgMatch);
+                if (isTemplateImage(value)) {
+                    const safeFileName = sanitizeTemplateImageFileName(value.image.fileName);
+                    const rId = value.image.rId ?? `rId_tpl_${nextTemplateImageSeq()}`;
+                    const imgContent = {
+                        type: "image",
+                        rId,
+                        width: value.width,
+                        height: value.height,
+                        altText: value.altText ?? safeFileName,
+                        name: safeFileName
+                    };
+                    const newPara = {
+                        type: "paragraph",
+                        properties: block.properties,
+                        children: [{ content: [imgContent] }]
+                    };
+                    result.push(newPara);
+                    // Register image for packaging
+                    collectedImages.push({ ...value.image, rId, fileName: safeFileName });
+                    continue;
+                }
+            }
+            // Check for richText placeholder
+            const rtMatch = matchSinglePlaceholder(text, open, close, "&");
+            if (rtMatch) {
+                const value = resolvePath(data, rtMatch);
+                if (isTemplateRichText(value)) {
+                    const newPara = {
+                        type: "paragraph",
+                        properties: block.properties,
+                        children: [...value]
+                    };
+                    result.push(newPara);
+                    continue;
+                }
+            }
+            // Check for chart placeholder
+            const chartMatch = matchSinglePlaceholder(text, open, close, "^");
+            if (chartMatch) {
+                const value = resolvePath(data, chartMatch);
+                if (isTemplateChart(value)) {
+                    const chartContent = {
+                        type: "chart",
+                        chart: value.chart,
+                        altText: value.altText,
+                        name: value.name
+                    };
+                    result.push(chartContent);
+                    continue;
+                }
+            }
+            result.push(block);
+        }
+        else if (block.type === "table") {
+            // Process table column loops
+            const processed = processTableColumnLoop(block, data, open, close, strict);
+            result.push(processed);
+        }
+        else if (block.type === "sdt") {
+            // Recursively process SDT content
+            const sdt = block;
+            const processedContent = processEnhancedBody(sdt.content, data, open, close, strict, collectedImages);
+            result.push({
+                ...sdt,
+                content: processedContent
+            });
+        }
+        else {
+            result.push(block);
+        }
+    }
+    return result;
+}
+/** Match a single-placeholder paragraph: {{<prefix><path>}} */
+function matchSinglePlaceholder(text, open, close, prefix) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith(open) || !trimmed.endsWith(close)) {
+        return null;
+    }
+    const inner = trimmed.slice(open.length, trimmed.length - close.length).trim();
+    if (!inner.startsWith(prefix)) {
+        return null;
+    }
+    return inner.slice(prefix.length).trim();
+}
+// =============================================================================
+// Table Column Loop: {{#cols items}}...{{/cols}}
+// =============================================================================
+function processTableColumnLoop(table, data, open, close, _strict) {
+    // Check if any cell in the first row contains a #cols directive
+    if (table.rows.length === 0) {
+        return table;
+    }
+    const firstRow = table.rows[0];
+    let colsExpr = null;
+    let templateColIdx = -1;
+    for (let c = 0; c < firstRow.cells.length; c++) {
+        const cell = firstRow.cells[c];
+        for (const block of cell.content) {
+            if (block.type === "paragraph") {
+                const text = extractParagraphText(block);
+                const pattern = open + "#cols ";
+                if (text.includes(pattern)) {
+                    colsExpr = extractDirectiveFromText(text, open, close, "#cols ");
+                    templateColIdx = c;
+                    break;
+                }
+            }
+        }
+        if (colsExpr) {
+            break;
+        }
+    }
+    if (!colsExpr || templateColIdx === -1) {
+        return table;
+    }
+    // Find closing {{/cols}} column
+    let closeColIdx = templateColIdx;
+    for (let c = templateColIdx; c < firstRow.cells.length; c++) {
+        const cell = firstRow.cells[c];
+        for (const block of cell.content) {
+            if (block.type === "paragraph") {
+                const text = extractParagraphText(block);
+                if (text.includes(open + "/cols" + close) || text.includes(open + " /cols " + close)) {
+                    closeColIdx = c;
+                    break;
+                }
+            }
+        }
+    }
+    const items = resolvePath(data, colsExpr);
+    if (!Array.isArray(items)) {
+        return table;
+    }
+    // For each row, duplicate the template columns for each item
+    const newRows = [];
+    for (const row of table.rows) {
+        const beforeCells = row.cells.slice(0, templateColIdx);
+        const templateCells = row.cells.slice(templateColIdx, closeColIdx + 1);
+        const afterCells = row.cells.slice(closeColIdx + 1);
+        const expandedCells = [...beforeCells];
+        for (let idx = 0; idx < items.length; idx++) {
+            for (const templateCell of templateCells) {
+                const clonedCell = structuredClone(templateCell);
+                // Strip #cols and /cols directives from text
+                for (let b = 0; b < clonedCell.content.length; b++) {
+                    const block = clonedCell.content[b];
+                    if (block.type === "paragraph") {
+                        const text = extractParagraphText(block);
+                        let cleaned = text;
+                        const colsOpenRegex = new RegExp(escapeRegex(open) +
+                            "\\s*#cols\\s+[^" +
+                            escapeRegex(close.charAt(0)) +
+                            "]*" +
+                            escapeRegex(close), "g");
+                        cleaned = cleaned.replace(colsOpenRegex, "");
+                        const colsCloseRegex = new RegExp(escapeRegex(open) + "\\s*/cols\\s*" + escapeRegex(close), "g");
+                        cleaned = cleaned.replace(colsCloseRegex, "");
+                        // Resolve item variables
+                        const itemData = buildLoopData(items[idx], idx, data);
+                        const tokens = tokenize(cleaned, open, close);
+                        const ctx = { open, close, strict: false, data: itemData };
+                        const resolved = evaluateInlineTokens(tokens, ctx, "colLoop");
+                        if (resolved !== text) {
+                            clonedCell.content[b] = rebuildParagraphText(block, resolved);
+                        }
+                        else if (cleaned !== text) {
+                            clonedCell.content[b] = rebuildParagraphText(block, cleaned);
+                        }
+                    }
+                }
+                expandedCells.push(clonedCell);
+            }
+        }
+        expandedCells.push(...afterCells);
+        // Update grid (tblGrid) if needed: we'll leave that to the caller
+        newRows.push({ ...row, cells: expandedCells });
+    }
+    return { ...table, rows: newRows };
+}
+// =============================================================================
+// rId allocation helpers
+// =============================================================================
+//
+// Template-generated parts (alt chunks, dynamic images) need stable but
+// non-colliding rIds. Earlier versions of this module derived the rId
+// from `blockIndex` or the image's `fileName`, which collided as soon as
+// the same template was filled twice or two distinct images shared a
+// file name. We now use module-level monotonic counters so each generated
+// part gets a unique rId for the lifetime of the process.
+let _altChunkSeq = 0;
+let _templateImageSeq = 0;
+function nextAltChunkSeq() {
+    _altChunkSeq++;
+    return _altChunkSeq;
+}
+function nextTemplateImageSeq() {
+    _templateImageSeq++;
+    return _templateImageSeq;
+}
+/**
+ * Strip path-traversal segments and other unsafe characters from a
+ * caller-supplied image file name so it can be safely used as a ZIP
+ * entry path inside the package. Mirrors the equivalent helper in
+ * `convert/odt/odt.ts`.
+ */
+function sanitizeTemplateImageFileName(raw) {
+    if (!raw) {
+        return "image.bin";
+    }
+    const lastSep = Math.max(raw.lastIndexOf("/"), raw.lastIndexOf("\\"));
+    let leaf = lastSep >= 0 ? raw.substring(lastSep + 1) : raw;
+    while (leaf.startsWith(".")) {
+        leaf = leaf.substring(1);
+    }
+    leaf = leaf.replace(/[^A-Za-z0-9._-]/g, "_");
+    leaf = leaf.replace(/\.{2,}/g, ".");
+    return leaf || "image.bin";
+}