/**
 * 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;