@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/browser/modules/word/document-io.d.ts

@@ -1,43 +1,49 @@
 /**
  * DOCX Module - Document IO
  *
- * IO operations that depend on docx-packager and docx-reader.
- * Separated from document.ts so that builder helpers can be imported
- * without pulling in archive/xml/writer code.
+ * IO operations: package/unpackage to bytes, base64, Flat OPC,
+ * plus the public Patch and Template APIs that combine read/patch/write.
  */
-import type { DocxDocument, Paragraph, Table, ImageDef } from "./types.js";
+import { type PatchOperation } from "./patcher.js";
+import type { TemplateOptions } from "./template/template-engine.js";
+import type { DocxDocument } from "./types.js";
+export type { PatchContent, PatchOperation } from "./patcher.js";
 /** Package a DocxDocument model to DOCX bytes. */
 export declare function toBuffer(doc: DocxDocument, compressionLevel?: number): Promise<Uint8Array>;
 /** Package a DocxDocument model to base64 string. */
 export declare function toBase64(doc: DocxDocument, compressionLevel?: number): Promise<string>;
-/** Type of content to patch into a placeholder. */
-export type PatchContent = {
-    readonly type: "text";
-    readonly text: string;
-} | {
-    readonly type: "paragraph";
-    readonly children: readonly Paragraph[];
-} | {
-    readonly type: "table";
-    readonly table: Table;
-} | {
-    readonly type: "image";
-    readonly image: ImageDef;
-    readonly width: number;
-    readonly height: number;
-};
-/** A single patch operation mapping a placeholder to replacement content. */
-export interface PatchOperation {
-    /** Placeholder string to find (e.g. "{{name}}"). */
-    readonly placeholder: string;
-    /** Content to replace the placeholder with. */
-    readonly content: PatchContent;
-}
 /** Options for patchDocument. */
 export interface PatchOptions {
     /** Compression level (0-9). Default: 6. */
     readonly compressionLevel?: number;
 }
+/** A compiled template that can be reused for multiple patch operations. */
+export interface CompiledTemplate {
+    /** The parsed document model (internal use only). */
+    readonly _doc: DocxDocument;
+}
+/**
+ * Compile a DOCX template for reuse with multiple data sets.
+ *
+ * Parsing the ZIP and XML is expensive. If you need to patch the same template
+ * multiple times with different data, compile it once and reuse.
+ *
+ * @param buffer - The source DOCX template file as a Uint8Array.
+ * @returns A compiled template handle.
+ */
+export declare function compileTemplate(buffer: Uint8Array): Promise<CompiledTemplate>;
+/**
+ * Apply patches to a pre-compiled template.
+ *
+ * Much faster than `patchDocument` when applying to the same template repeatedly,
+ * since ZIP/XML parsing is skipped.
+ *
+ * @param template - A compiled template from `compileTemplate`.
+ * @param patches - Array of patch operations to apply.
+ * @param options - Optional compression settings.
+ * @returns New DOCX file as a Uint8Array.
+ */
+export declare function patchTemplate(template: CompiledTemplate, patches: readonly PatchOperation[], options?: PatchOptions): Promise<Uint8Array>;
 /**
  * Read an existing DOCX file, replace placeholders with content, and produce a new DOCX.
  *
@@ -56,3 +62,29 @@ export interface PatchOptions {
  * @returns New DOCX file as a Uint8Array.
  */
 export declare function patchDocument(buffer: Uint8Array, patches: readonly PatchOperation[], options?: PatchOptions): Promise<Uint8Array>;
+/**
+ * Read a DOCX buffer, fill template placeholders with data, and produce a new DOCX.
+ *
+ * This is a convenience wrapper combining readDocx + fillTemplate + packageDocx.
+ *
+ * @param buffer - The source DOCX template file as a Uint8Array.
+ * @param data - Data object to fill into the template placeholders.
+ * @param options - Template and compression options.
+ * @returns New DOCX file as a Uint8Array.
+ */
+export declare function fillTemplateFromBuffer(buffer: Uint8Array, data: Record<string, unknown>, options?: TemplateOptions & {
+    readonly compressionLevel?: number;
+}): Promise<Uint8Array>;
+/**
+ * Package a DocxDocument model into Flat OPC XML format.
+ *
+ * This packages the document to a ZIP, then re-reads the entries to wrap
+ * them as Flat OPC XML. While this involves a ZIP round-trip, it ensures
+ * the Flat OPC output is byte-identical to what `packageDocx` would produce
+ * (same XML serialization, same relationships, same content types).
+ *
+ * @param doc - The document model.
+ * @param compressionLevel - Optional compression level (0 = no compression, faster for Flat OPC).
+ * @returns The Flat OPC XML string.
+ */
+export declare function toFlatOpcFromDoc(doc: DocxDocument, compressionLevel?: number): Promise<string>;

package/dist/browser/modules/word/document-io.js

@@ -1,13 +1,14 @@
 /**
  * DOCX Module - Document IO
  *
- * IO operations that depend on docx-packager and docx-reader.
- * Separated from document.ts so that builder helpers can be imported
- * without pulling in archive/xml/writer code.
+ * IO operations: package/unpackage to bytes, base64, Flat OPC,
+ * plus the public Patch and Template APIs that combine read/patch/write.
  */
-import { packageDocx } from "./docx-packager.js";
-import { readDocx } from "./docx-reader.js";
-import { bytesToBase64 } from "./internal-utils.js";
+import { bytesToBase64 } from "./core/internal-utils.js";
+import { applyPatchesToDocument } from "./patcher.js";
+import { readDocx } from "./reader/docx-reader.js";
+import { fillTemplate } from "./template/template-engine.js";
+import { packageDocx } from "./writer/docx-packager.js";
 // =============================================================================
 // Document IO (toBuffer / toBase64)
 // =============================================================================
@@ -20,6 +21,36 @@ export async function toBase64(doc, compressionLevel) {
     const bytes = await toBuffer(doc, compressionLevel);
     return bytesToBase64(bytes);
 }
+/**
+ * Compile a DOCX template for reuse with multiple data sets.
+ *
+ * Parsing the ZIP and XML is expensive. If you need to patch the same template
+ * multiple times with different data, compile it once and reuse.
+ *
+ * @param buffer - The source DOCX template file as a Uint8Array.
+ * @returns A compiled template handle.
+ */
+export async function compileTemplate(buffer) {
+    const doc = await readDocx(buffer);
+    return { _doc: doc };
+}
+/**
+ * Apply patches to a pre-compiled template.
+ *
+ * Much faster than `patchDocument` when applying to the same template repeatedly,
+ * since ZIP/XML parsing is skipped.
+ *
+ * @param template - A compiled template from `compileTemplate`.
+ * @param patches - Array of patch operations to apply.
+ * @param options - Optional compression settings.
+ * @returns New DOCX file as a Uint8Array.
+ */
+export async function patchTemplate(template, patches, options) {
+    // Deep clone the document to avoid mutating the cached template
+    const doc = structuredClone(template._doc);
+    const patched = applyPatchesToDocument(doc, patches);
+    return packageDocx(patched, options?.compressionLevel);
+}
 /**
  * Read an existing DOCX file, replace placeholders with content, and produce a new DOCX.
  *
@@ -39,201 +70,53 @@ export async function toBase64(doc, compressionLevel) {
  */
 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
-    };
+    const patched = applyPatchesToDocument(doc, patches);
     return packageDocx(patched, options?.compressionLevel);
 }
 // =============================================================================
-// Internal helpers
+// Template Engine - Convenience IO
 // =============================================================================
-/** Extract concatenated plain text from a paragraph's runs. */
-function paragraphText(para) {
-    let t = "";
-    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) {
-                    t += c.text;
-                }
-            }
-        }
-    }
-    return t;
-}
-/** Replace text within a single paragraph. */
-function replaceInParagraph(para, search, replacement) {
-    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;
-            if (before.includes(search)) {
-                c.text = before.replaceAll(search, replacement);
-            }
-        }
-    }
-    // Cross-run replacement fallback
-    const fullText = paragraphText(para);
-    if (fullText.includes(search)) {
-        const newText = fullText.replaceAll(search, replacement);
-        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 = "";
-                }
-            }
-        }
-    }
-}
-/** 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;
-        }
-    }
+/**
+ * Read a DOCX buffer, fill template placeholders with data, and produce a new DOCX.
+ *
+ * This is a convenience wrapper combining readDocx + fillTemplate + packageDocx.
+ *
+ * @param buffer - The source DOCX template file as a Uint8Array.
+ * @param data - Data object to fill into the template placeholders.
+ * @param options - Template and compression options.
+ * @returns New DOCX file as a Uint8Array.
+ */
+export async function fillTemplateFromBuffer(buffer, data, options) {
+    const doc = await readDocx(buffer);
+    const filled = fillTemplate(doc, data, options);
+    return packageDocx(filled, options?.compressionLevel);
 }
-/** 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);
-                    }
-                }
-            }
-        }
+// =============================================================================
+// Flat OPC Convenience
+// =============================================================================
+/**
+ * Package a DocxDocument model into Flat OPC XML format.
+ *
+ * This packages the document to a ZIP, then re-reads the entries to wrap
+ * them as Flat OPC XML. While this involves a ZIP round-trip, it ensures
+ * the Flat OPC output is byte-identical to what `packageDocx` would produce
+ * (same XML serialization, same relationships, same content types).
+ *
+ * @param doc - The document model.
+ * @param compressionLevel - Optional compression level (0 = no compression, faster for Flat OPC).
+ * @returns The Flat OPC XML string.
+ */
+export async function toFlatOpcFromDoc(doc, compressionLevel) {
+    // Use level 0 (store-only) since we're immediately decompressing
+    const zipBytes = await packageDocx(doc, compressionLevel ?? 0);
+    const { unzip } = await import("../archive/read-archive.js");
+    const reader = unzip(zipBytes);
+    const entries = new Map();
+    for await (const entry of reader.entries()) {
+        const data = await entry.bytes();
+        const path = entry.path.replace(/^\//, "").replace(/\\/g, "/");
+        entries.set(path, data);
     }
+    const { toFlatOpc } = await import("./convert/flat-opc.js");
+    return toFlatOpc(entries);
 }

package/dist/browser/modules/word/errors.d.ts

@@ -4,7 +4,6 @@
  * All DOCX-related errors extend DocxError.
  */
 import { BaseError, type BaseErrorOptions } from "../../utils/errors.js";
-export { AbortError, createAbortError, isAbortError, throwIfAborted, createLinkedAbortController, toError, suppressUnhandledRejection, errorToJSON, getErrorChain, getRootCause, type BaseErrorOptions } from "../../utils/errors.js";
 /**
  * Base class for all DOCX-related errors.
  */
@@ -47,3 +46,47 @@ export declare class DocxUnsupportedFeatureError extends DocxError {
     name: string;
     constructor(feature: string);
 }
+/**
+ * Error thrown when a DOCX file is encrypted (CFB format) and no password
+ * was provided. Pass `{ password }` in the second argument of `readDocx()`
+ * to decrypt automatically, or call `decryptDocx()` from "excelts/word/crypto"
+ * directly if you need lower-level access to the decrypted ZIP bytes.
+ */
+export declare class DocxEncryptedError extends DocxError {
+    name: string;
+    constructor();
+}
+/**
+ * Error thrown when an encrypted DOCX cannot be decrypted with the provided
+ * password (wrong password) or when the encryption metadata is malformed.
+ */
+export declare class DocxDecryptionError extends DocxError {
+    name: string;
+}
+/**
+ * Error thrown when an input package exceeds a declared resource limit (e.g.
+ * total package size, single part size, number of parts). Used to defend
+ * against ZIP bombs and runaway memory usage.
+ */
+export declare class DocxLimitExceededError extends DocxParseError {
+    name: string;
+    /** Limit category that was exceeded. */
+    readonly limit: "packageSize" | "partSize" | "partCount";
+    /** Configured maximum. */
+    readonly maximum: number;
+    /** Actual measured value (or the value that would have been reached). */
+    readonly actual: number;
+    constructor(limit: "packageSize" | "partSize" | "partCount", maximum: number, actual: number, detail?: string);
+}
+/**
+ * Error thrown when the active `WordSecurityPolicy.rawXmlPolicy` is `"reject"`
+ * and the writer encounters opaque/preserved rawXml that would otherwise have
+ * been emitted verbatim. Callers can either drop the offending model field
+ * before serialisation or relax the policy to `"strip"` / `"preserve"`.
+ */
+export declare class DocxRawXmlPolicyError extends DocxWriteError {
+    name: string;
+    /** Short label identifying the offending writer site. */
+    readonly site: string;
+    constructor(site: string);
+}

package/dist/browser/modules/word/errors.js

@@ -4,8 +4,6 @@
  * All DOCX-related errors extend DocxError.
  */
 import { BaseError } from "../../utils/errors.js";
-// Re-export common utilities from base
-export { AbortError, createAbortError, isAbortError, throwIfAborted, createLinkedAbortController, toError, suppressUnhandledRejection, errorToJSON, getErrorChain, getRootCause } from "../../utils/errors.js";
 /**
  * Base class for all DOCX-related errors.
  */
@@ -66,3 +64,57 @@ export class DocxUnsupportedFeatureError extends DocxError {
         this.name = "DocxUnsupportedFeatureError";
     }
 }
+/**
+ * Error thrown when a DOCX file is encrypted (CFB format) and no password
+ * was provided. Pass `{ password }` in the second argument of `readDocx()`
+ * to decrypt automatically, or call `decryptDocx()` from "excelts/word/crypto"
+ * directly if you need lower-level access to the decrypted ZIP bytes.
+ */
+export class DocxEncryptedError extends DocxError {
+    constructor() {
+        super("The document is encrypted (password-protected). " +
+            'Pass { password } to readDocx(), or use decryptDocx() from "excelts/word/crypto" ' +
+            "for lower-level decryption.");
+        this.name = "DocxEncryptedError";
+    }
+}
+/**
+ * Error thrown when an encrypted DOCX cannot be decrypted with the provided
+ * password (wrong password) or when the encryption metadata is malformed.
+ */
+export class DocxDecryptionError extends DocxError {
+    constructor() {
+        super(...arguments);
+        this.name = "DocxDecryptionError";
+    }
+}
+/**
+ * Error thrown when an input package exceeds a declared resource limit (e.g.
+ * total package size, single part size, number of parts). Used to defend
+ * against ZIP bombs and runaway memory usage.
+ */
+export class DocxLimitExceededError extends DocxParseError {
+    constructor(limit, maximum, actual, detail) {
+        super(`DOCX ${limit} limit exceeded: actual ${actual} > maximum ${maximum}` +
+            (detail ? ` (${detail})` : ""));
+        this.name = "DocxLimitExceededError";
+        this.limit = limit;
+        this.maximum = maximum;
+        this.actual = actual;
+    }
+}
+/**
+ * Error thrown when the active `WordSecurityPolicy.rawXmlPolicy` is `"reject"`
+ * and the writer encounters opaque/preserved rawXml that would otherwise have
+ * been emitted verbatim. Callers can either drop the offending model field
+ * before serialisation or relax the policy to `"strip"` / `"preserve"`.
+ */
+export class DocxRawXmlPolicyError extends DocxWriteError {
+    constructor(site) {
+        super(`Raw XML rejected by security policy at "${site}". ` +
+            "Either remove the rawXml/opaque field from the model or set " +
+            "WordSecurityPolicy.rawXmlPolicy to 'preserve' or 'strip'.");
+        this.name = "DocxRawXmlPolicyError";
+        this.site = site;
+    }
+}

package/dist/browser/modules/word/excel.d.ts

@@ -0,0 +1,14 @@
+/**
+ * DOCX Module - Excel Bridge (Subpath Entry)
+ *
+ * Re-exports the Excel bridge API at `excelts/word/excel`. This file is
+ * referenced by `package.json#exports["./word/excel"]`; it forwards to the
+ * implementation under `./bridge/excel-bridge`.
+ *
+ * @example
+ * ```ts
+ * import { excelToDocx } from "excelts/word/excel";
+ * ```
+ */
+export { excelToDocx, extractTablesToExcel, renderWordChartSvg, buildWordChartExXml, wordChartToChartModel, generateChartEmbeddedXlsx } from "./bridge/excel-bridge.js";
+export type { ExcelToDocxOptions, WordChartExOptions } from "./bridge/excel-bridge.js";

package/dist/browser/modules/word/excel.js

@@ -0,0 +1,13 @@
+/**
+ * DOCX Module - Excel Bridge (Subpath Entry)
+ *
+ * Re-exports the Excel bridge API at `excelts/word/excel`. This file is
+ * referenced by `package.json#exports["./word/excel"]`; it forwards to the
+ * implementation under `./bridge/excel-bridge`.
+ *
+ * @example
+ * ```ts
+ * import { excelToDocx } from "excelts/word/excel";
+ * ```
+ */
+export { excelToDocx, extractTablesToExcel, renderWordChartSvg, buildWordChartExXml, wordChartToChartModel, generateChartEmbeddedXlsx } from "./bridge/excel-bridge.js";

package/dist/browser/modules/word/font/font-embed.d.ts

@@ -0,0 +1,112 @@
+/**
+ * DOCX Module - Embedded Font Writer
+ *
+ * Provides the ability to embed font files into DOCX documents.
+ * Supports TTF, OTF, and WOFF fonts with optional ODTTF obfuscation
+ * as required by the OOXML specification for embedded fonts.
+ *
+ * ECMA-376 Part 1, §17.8.3 describes how fonts are embedded:
+ * - Fonts are stored in word/fonts/ directory
+ * - Each embedded font has a relationship in fontTable.xml
+ * - Obfuscation uses a GUID-based XOR scheme (ODTTF format)
+ *
+ * Supports font subsetting to reduce file size by only including
+ * glyphs that are actually used in the document.
+ */
+import type { DocxDocument, FontDef, EmbeddedFont } from "../types.js";
+/** Font embedding style (which variants to embed). */
+export type FontEmbedStyle = "regular" | "bold" | "italic" | "boldItalic";
+/** Options for embedding a font. */
+export interface EmbedFontOptions {
+    /** Font family name as it will appear in the document. */
+    readonly name: string;
+    /** The raw font file data (TTF/OTF/WOFF). */
+    readonly data: Uint8Array;
+    /** Which style variant this is. Default: "regular". */
+    readonly style?: FontEmbedStyle;
+    /** Whether to apply ODTTF obfuscation. Default: true. */
+    readonly obfuscate?: boolean;
+    /** Font family classification. */
+    readonly family?: "roman" | "swiss" | "modern" | "script" | "decorative" | "auto";
+    /** Font pitch. */
+    readonly pitch?: "default" | "fixed" | "variable";
+    /** Panose-1 classification (10-byte hex string). */
+    readonly panose1?: string;
+    /** Character set (0 = ANSI). */
+    readonly charset?: number;
+    /**
+     * Characters used in the document for subsetting.
+     * When provided, the embedded font will only contain glyphs for these characters,
+     * significantly reducing file size. Pass all unique characters from the document
+     * that use this font.
+     */
+    readonly usedCharacters?: string;
+}
+/** Result of embedding a font. */
+export interface EmbedFontResult {
+    /** The font definition to add to `doc.fonts`. */
+    readonly fontDef: FontDef;
+    /** The embedded font entry to add to `doc.embeddedFonts`. */
+    readonly embeddedFont: EmbeddedFont;
+}
+/**
+ * Subset a TrueType/OpenType font to include only the specified characters.
+ *
+ * This performs a minimal subset by:
+ * 1. Parsing the cmap table to find glyph IDs for requested characters
+ * 2. Building a new glyf/loca table with only needed glyphs (+ composite dependencies)
+ * 3. Rebuilding the font with minimal tables
+ *
+ * For CFF (PostScript-outline) fonts, subsetting is more complex and we fall back
+ * to embedding the full font.
+ *
+ * @param fontData - Raw TTF/OTF font bytes
+ * @param characters - String of characters to keep
+ * @returns Subsetted font bytes, or original if subsetting fails/not applicable
+ */
+export declare function subsetFont(fontData: Uint8Array, characters: string): Uint8Array;
+/**
+ * Prepare a font for embedding into a DOCX document.
+ *
+ * Returns both the FontDef (for the font table) and the EmbeddedFont
+ * (for the embedded binary). The caller should add these to the document model.
+ *
+ * @param options - Font embedding options.
+ * @returns The font definition and embedded font data.
+ *
+ * @example
+ * ```ts
+ * const result = embedFont({
+ *   name: "CustomFont",
+ *   data: fontFileBytes,
+ *   style: "regular",
+ *   obfuscate: true
+ * });
+ *
+ * // Add to document
+ * const doc = {
+ *   ...existingDoc,
+ *   fonts: [...(existingDoc.fonts ?? []), result.fontDef],
+ *   embeddedFonts: [...(existingDoc.embeddedFonts ?? []), result.embeddedFont]
+ * };
+ * ```
+ */
+export declare function embedFont(options: EmbedFontOptions): EmbedFontResult;
+/**
+ * Embed multiple font variants (regular, bold, italic, boldItalic) for a font family.
+ *
+ * @param name - Font family name.
+ * @param variants - Map of style to font data.
+ * @param options - Shared options for all variants.
+ * @returns Array of embed results.
+ */
+export declare function embedFontFamily(name: string, variants: Partial<Record<FontEmbedStyle, Uint8Array>>, options?: Omit<EmbedFontOptions, "name" | "data" | "style">): EmbedFontResult[];
+/**
+ * Add embedded fonts to an existing document model.
+ * Merges new fonts with existing font definitions.
+ *
+ * @param doc - The existing document.
+ * @param results - Embed results from `embedFont` or `embedFontFamily`.
+ * @returns A new document with embedded fonts added.
+ */
+export declare function addEmbeddedFonts(doc: DocxDocument, results: readonly EmbedFontResult[]): DocxDocument;