import type { EmbeddedFile } from './embedded-files.ts';
import type { OutputIntent } from './output-intent.ts';
import type { PDFPage } from './pdf-page.ts';
import type { PDFResource } from './pdf-resource.ts';
import type { XMPFragment } from './xmp-metadata.ts';
/**
 * Supported PDF versions.
 */
export type PDFVersion = '1.0' | '1.1' | '1.2' | '1.3' | '1.4' | '1.5' | '1.6' | '1.7' | '2.0';
/**
 * Metadata for a PDF document, included in the document's Info dictionary.
 * Supports both standard PDF metadata fields and custom fields.
 */
export type PDFDocumentInfo = {
    /** The document's title. */
    title?: string;
    /** The name of the person who created the document. */
    author?: string;
    /** The subject of the document. */
    subject?: string;
    /** Keywords associated with the document. */
    keywords?: string;
    /** The application that created the original document. */
    creator?: string;
    /** The application that produced the PDF. */
    producer?: string;
    /** The date the document was created. */
    creationDate?: Date;
    /** The date the document was last modified. */
    modDate?: Date;
    /** Custom metadata fields. */
    [key: string]: string | Date | undefined;
};
export type PDFDocumentOptions = {
    /**
     * The PDF version to use. Defaults to '1.7'.
     */
    version?: PDFVersion;
    /**
     * Metadata for the document.
     */
    info?: PDFDocumentInfo;
    /**
     * The natural language of the document text, as an IETF BCP 47 language
     * tag (e.g. `'en-US'`, `'de'`, `'fr-CA'`). Sets the `/Lang` entry in the
     * document catalog.
     */
    lang?: string;
};
/**
 * Options for writing a PDF document.
 */
export type WriteOptions = {
    /**
     * Compression settings for the PDF output.
     */
    compression?: {
        /**
         * Controls whether stream objects are compressed when writing the
         * PDF. Defaults to `true`.
         *
         * This option should normally be left enabled. Compression
         * significantly reduces file size and is the standard behavior for
         * PDF generators. Disabling it is primarily intended for debugging
         * or inspection of raw content streams.
         */
        enabled?: boolean;
    };
    /**
     * When enabled, packs multiple small objects into compressed object
     * streams (PDF 1.5+). This significantly reduces file size by
     * eliminating per-object overhead and applying compression across
     * multiple objects. Defaults to `true`.
     *
     * Objects that cannot be stored in object streams (streams, the
     * catalog, and encryption dictionaries) are written as regular
     * indirect objects.
     */
    useObjectStreams?: boolean;
    /**
     * Controls the format of the cross-reference section.
     * - `'table'`: Traditional text-based xref table (PDF 1.4 compatible)
     * - `'stream'`: Compressed xref stream (PDF 1.5+, smaller file size)
     *
     * Defaults to `'stream'`.
     *
     * Note: When `useObjectStreams` is enabled, xref streams are always
     * used regardless of this setting, since object streams require
     * type 2 xref entries which cannot be represented in a traditional
     * xref table.
     */
    xrefStyle?: 'table' | 'stream';
};
/**
 * Context passed to `unsafeOnRender` callbacks. Provides access to internal
 * PDF structures during document rendering.
 *
 * **Warning:** This type is NOT semver-stable. Properties may be added,
 * changed, or removed in any release without notice.
 *
 * @experimental
 */
export type UnsafeRenderContext = {
    /** The PDF object context for adding indirect objects. */
    readonly context: unknown;
    /** The document catalog dictionary. */
    readonly catalog: unknown;
    /** Registers a resource and returns its reference. */
    registerResource(resource: PDFResource): unknown;
};
/**
 * Represents a PDF document, allowing for the creation and manipulation
 * of PDF pages and the writing of the final PDF file.
 */
export declare class PDFDocument {
    private readonly _pages;
    private readonly _embeddedFiles;
    private readonly _outputIntents;
    private readonly _unsafeOnRenderHooks;
    private _info;
    private _xmpFragments;
    private _unsafeXMPMetadata;
    /**
     * The PDF version of this document.
     */
    readonly version: PDFVersion;
    /**
     * The natural language of the document text, as a language tag
     * (e.g. `'en-US'`, `'de'`, `'fr-CA'`). Sets the `/Lang` entry in
     * the document catalog.
     */
    readonly lang: string | undefined;
    /**
     * Creates a new PDFDocument.
     */
    constructor(options?: PDFDocumentOptions);
    /**
     * Adds a page to the PDF document.
     */
    addPage(page: PDFPage): void;
    /**
     * Returns an array of all pages in the document.
     */
    get pages(): readonly PDFPage[];
    /**
     * Sets metadata for the document. Overwrite previous info on each call.
     */
    setInfo(info: PDFDocumentInfo): void;
    /**
     * Returns the document metadata.
     */
    get info(): PDFDocumentInfo | undefined;
    /**
     * Adds a custom XMP metadata fragment to be merged into the
     * auto-generated XMP. Each fragment declares a namespace and provides
     * XML content for that namespace. Fragments are only used when XMP is
     * auto-generated from the Info dictionary; they are ignored when
     * explicit XMP is set via `unsafeSetXMPMetadata()`.
     */
    addXMPFragment(fragment: XMPFragment): void;
    /**
     * Returns the custom XMP fragments or `undefined` if no fragments have been added.
     */
    get xmpFragments(): readonly XMPFragment[] | undefined;
    /**
     * Sets a raw XMP metadata XML string that **overrides** the library's
     * auto-generated XMP entirely. When set, this string is used verbatim
     * as the XMP metadata stream and XMP fragments are ignored. The caller
     * is fully responsible for providing valid XMP XML, including
     * consistency with the Info dictionary.
     *
     * Prefer `setInfo` combined with `addXMPFragment` instead. Only use
     * this when you need complete control over the XMP output.
     */
    unsafeSetXMPMetadata(xmp: string): void;
    /**
     * Returns the raw XMP metadata XML string set via
     * `unsafeSetXMPMetadata`, or `undefined` if not set.
     */
    get unsafeXMPMetadata(): string | undefined;
    /**
     * Adds an embedded file to the document.
     */
    addEmbeddedFile(embeddedFile: EmbeddedFile): void;
    /**
     * Returns an array of all embedded files in the document.
     */
    get embeddedFiles(): readonly EmbeddedFile[];
    /**
     * Adds an output intent to the document. Output intents declare the
     * intended output device or condition, and are required for PDF/A and
     * PDF/X compliance.
     */
    addOutputIntent(intent: OutputIntent): void;
    /**
     * Returns the output intents of the document.
     */
    get outputIntents(): readonly Readonly<OutputIntent>[];
    /**
     * Registers a callback to be invoked during document rendering with access
     * to internal PDF structures. This API is NOT semver-stable and may change
     * or be removed at any time without notice.
     *
     * Use at your own risk for advanced use cases not covered by the public API.
     * @experimental
     */
    unsafeOnRender(cb: (ctx: UnsafeRenderContext) => void): void;
    /**
     * Writes the PDF document and returns the bytes as a Uint8Array.
     */
    write(opts?: WriteOptions): Uint8Array;
}