/**
 * DOCX Module - OLE Embedded Objects
 *
 * Provides support for reading and round-tripping OLE (Object Linking and Embedding)
 * objects within DOCX files. OLE objects allow embedding other documents (Excel
 * spreadsheets, PowerPoint presentations, PDFs, etc.) within a Word document.
 *
 * OLE objects in OOXML are stored as:
 * - Binary data in word/embeddings/*.bin (OLE2 compound document)
 * - Referenced via r:id in w:object/o:OLEObject elements
 * - May have a preview image (EMF/WMF) in word/media/
 *
 * This module focuses on preservation (round-trip) and metadata extraction,
 * not full OLE compound document manipulation.
 */
import type { DocxDocument, OpaquePart } from "../types.js";
/** OLE object type classification. */
export type OleObjectType = "embedded" | "linked";
/** OLE object display style. */
export type OleDisplayAs = "icon" | "content";
/** Metadata about an OLE embedded object. */
export interface OleObject {
    /** Unique relationship ID for the OLE binary. */
    readonly rId: string;
    /** OLE ProgId (e.g. "Excel.Sheet.12", "PowerPoint.Slide.12", "Package"). */
    readonly progId: string;
    /** Whether the object is embedded or linked. */
    readonly objectType: OleObjectType;
    /** Display mode. */
    readonly displayAs: OleDisplayAs;
    /** Relationship ID for the preview image (EMF/WMF). */
    readonly imageRId?: string;
    /** Shape ID for the hosting VML shape. */
    readonly shapeId?: string;
    /** Object width in EMU. */
    readonly width?: number;
    /** Object height in EMU. */
    readonly height?: number;
    /** File name of the embedded data within the archive. */
    readonly fileName?: string;
    /** The raw binary data of the OLE object. */
    readonly data?: Uint8Array;
    /** Link target (for linked objects). */
    readonly linkTarget?: string;
    /** Raw XML of the w:object element for round-trip preservation. */
    readonly rawXml?: string;
}
/** Result of extracting OLE objects from a document. */
export interface OleExtractionResult {
    /** All OLE objects found in the document. */
    readonly objects: readonly OleObject[];
    /** Mapping of progId to count. */
    readonly summary: Readonly<Record<string, number>>;
}
/**
 * Extract metadata about OLE embedded objects from a parsed DOCX document.
 * OLE objects are preserved in opaqueParts during reading; this function
 * inspects them to extract meaningful metadata.
 *
 * @param doc - The parsed DOCX document.
 * @returns Extraction result with OLE object metadata.
 */
export declare function extractOleObjects(doc: DocxDocument): OleExtractionResult;
/**
 * Check if a document contains any OLE embedded objects.
 */
export declare function hasOleObjects(doc: DocxDocument): boolean;
/**
 * Get the binary data of a specific OLE object by its relationship ID.
 * Returns undefined if not found.
 */
export declare function getOleObjectData(doc: DocxDocument, rId: string): Uint8Array | undefined;
/**
 * Result of `createOleEmbedding`. Contains the OLE binary part and,
 * when a preview image was supplied, an additional media part for it
 * plus the relationship rIds the caller should reference from the body
 * model.
 */
export interface OleEmbeddingResult {
    /** OLE binary opaque part (always present). */
    readonly olePart: OpaquePart;
    /** Suggested rId to use for the OLE binary in the document model. */
    readonly oleRId: string;
    /** OLE ProgId the embedding was created with (e.g. "Excel.Sheet.12"). */
    readonly progId: string;
    /** Preview image media part (only when `options.previewImage` was supplied). */
    readonly previewPart?: OpaquePart;
    /** Suggested rId for the preview image. */
    readonly previewRId?: string;
}
/**
 * Create an OLE embedding plus, optionally, its preview image.
 *
 * Returns an {@link OleEmbeddingResult} with one or two `OpaquePart`s plus
 * suggested relationship IDs. Each call gets a unique counter-based file
 * name so calling this helper repeatedly does not produce path
 * collisions; pass `options.fileName` to force a specific name.
 *
 * The previous signature returned only one `OpaquePart` and silently
 * dropped `options.previewImage` / `options.previewContentType`. That has
 * been removed — the new shape forces callers to wire up preview parts
 * properly when they want one.
 *
 * @param data - The binary data of the OLE object (OLE2 compound document).
 * @param progId - The OLE ProgId (e.g. "Excel.Sheet.12").
 * @param options - Additional options.
 */
export declare function createOleEmbedding(data: Uint8Array, progId: string, options?: {
    /** Override file name. Defaults to `oleObject<N>.bin` with a process-unique counter. */
    fileName?: string;
    /** Optional preview image bytes (typically EMF or PNG). */
    previewImage?: Uint8Array;
    /** Content type for the preview image. Required when `previewImage` is set. */
    previewContentType?: string;
    /** Override preview file name. Defaults to `image<N>.<ext>` from previewContentType. */
    previewFileName?: string;
}): OleEmbeddingResult;
/**
 * Wire an {@link OleEmbeddingResult} into a document so the OLE object is
 * actually rendered and resolvable, returning a new {@link DocxDocument}.
 *
 * Unlike just stuffing the part into `opaqueParts` (which leaves the binary
 * dangling — no relationship, no body reference), this:
 *
 *  - registers the OLE binary (and optional preview) on
 *    `doc.oleObjects` so the packager emits a `word/_rels/document.xml.rels`
 *    relationship with the exact rId and a `[Content_Types].xml` override;
 *  - appends a body paragraph carrying a `<w:object>` / `<o:OLEObject>`
 *    that references the same rId and embeds the ProgId, so the object is
 *    visible in Word and round-trips through `readDocx`.
 *
 * @param doc - The document to add the OLE object to.
 * @param embedding - Result from {@link createOleEmbedding}.
 * @param options - Display geometry (defaults to a 2"×2" icon box).
 */
export declare function addOleObject(doc: DocxDocument, embedding: OleEmbeddingResult, options?: {
    /** Display width in points (default 96 = 2 inches at 48pt/in icon). */
    widthPt?: number;
    /** Display height in points (default 96). */
    heightPt?: number;
    /** Display mode. Default "icon". */
    displayAs?: OleDisplayAs;
}): DocxDocument;