import { FlowBlock, PageNumberChapterSeparator, TrackedChangesMode } from '../../../../../../layout-engine/contracts/src/index.js';
import { HeaderFooterBatch } from '../../../../../../layout-engine/layout-bridge/src/index.js';
import { Editor } from '../Editor.js';
import { EventEmitter } from '../EventEmitter.js';
declare const HEADER_FOOTER_VARIANTS: readonly ["default", "first", "even", "odd"];
export type HeaderFooterKind = 'header' | 'footer';
export type HeaderFooterVariant = (typeof HEADER_FOOTER_VARIANTS)[number];
/**
 * Descriptor identifying a unique header or footer section in a document.
 *
 * Each descriptor combines a relationship ID (from DOCX structure), a kind
 * (header/footer), and an optional variant (default/first/even/odd) to
 * uniquely identify a section for editing and layout.
 *
 * @property id - Relationship ID from DOCX structure (e.g., "rId-header-default")
 * @property kind - Section type: 'header' or 'footer'
 * @property variant - Optional page variant: 'default', 'first', 'even', or 'odd'
 */
export type HeaderFooterDescriptor = {
    id: string;
    kind: HeaderFooterKind;
    variant?: HeaderFooterVariant;
};
/**
 * Structure representing a header/footer document in JSON format.
 * This is the ProseMirror document structure for a header or footer section.
 */
export interface HeaderFooterDocument {
    type: string;
    content?: unknown[];
    [key: string]: unknown;
}
export type HeaderFooterTrackedChangesRenderConfig = {
    mode: TrackedChangesMode;
    enabled: boolean;
};
export type HeaderFooterCacheStats = {
    /** Total number of cached editors */
    cachedEditors: number;
    /** Maximum cache size limit */
    maxCachedEditors: number;
    /** Number of times ensureEditor returned a cached editor */
    cacheHits: number;
    /** Number of times ensureEditor created a new editor */
    cacheMisses: number;
    /** Number of editors evicted due to LRU policy */
    evictions: number;
    /** Cache hit rate (0-1), or 0 if no accesses yet */
    hitRate: number;
};
export declare class HeaderFooterEditorManager extends EventEmitter {
    #private;
    /**
     * Creates a new HeaderFooterEditorManager for managing header and footer editors.
     *
     * Note: This constructor has a side effect - it calls refresh() to immediately
     * scan the root editor's converter for header/footer data and build the initial
     * descriptor registry.
     *
     * @param editor - The root editor instance containing the converter with header/footer data
     */
    constructor(editor: Editor);
    /**
     * Refreshes the internal header/footer descriptor registry by re-scanning
     * the root editor's converter data.
     *
     * This method should be called when the document structure changes in a way
     * that adds or removes header/footer sections (e.g., after document conversion,
     * section additions/deletions, or page setup changes).
     *
     * Side effects:
     * - Re-extracts collections from the converter
     * - Rebuilds the descriptor map
     * - Tears down editors for sections that no longer exist
     *
     * When `purgeCachedEditors` is true, all cached header/footer sub-editors are
     * disposed first. Use after a full document replace: the same relationship id
     * can point at new OOXML while `getDocumentJson` would otherwise keep serving
     * the old live editor's PM JSON.
     *
     * @throws Never throws - errors during editor teardown are caught and logged
     */
    refresh(options?: {
        purgeCachedEditors?: boolean;
    }): void;
    /**
     * Destroys all managed header/footer editors and cleans up resources.
     * After calling destroy(), the manager should not be used.
     *
     * @throws May throw if individual editor cleanup fails, but continues cleanup
     */
    destroy(): void;
    /**
     * Ensures an editor instance exists for the given descriptor.
     *
     * If an editor already exists, it will be marked as recently used and returned.
     * Otherwise, a new editor is created, cached, and tracked in the LRU access order.
     * When the cache exceeds its size limit, the least recently used editor is evicted.
     *
     * Handles concurrent calls for the same descriptor by tracking pending creations
     * and returning the same promise to all callers.
     *
     * @param descriptor - The header or footer descriptor. Must have a valid id property.
     * @param options - Optional configuration for editor creation
     * @param options.editorHost - The HTMLElement to mount the editor in. If provided, must be a valid HTMLElement.
     * @param options.availableWidth - The width of the editing region in pixels. Must be a positive number if provided.
     * @param options.availableHeight - The height of the editing region in pixels. Must be a positive number if provided.
     * @param options.currentPageNumber - The current page number for PAGE field resolution. Must be a positive integer if provided.
     * @param options.currentPageNumberText - The current formatted PAGE field display text if provided.
     * @param options.currentPageDisplayNumber - The current numeric PAGE display value for local field formatting.
     * @param options.currentPageChapterNumberText - The PAGE chapter prefix for local field formatting.
     * @param options.currentPageChapterSeparator - The PAGE chapter separator for local field formatting.
     * @param options.totalPageCount - The total page count for NUMPAGES field resolution. Must be a positive integer if provided.
     * @param options.sectionPageCount - The current section page count for SECTIONPAGES field resolution. Must be a positive integer if provided.
     * @returns The editor instance, or null if creation failed
     *
     * @throws Never throws - errors are logged and emitted as events. Invalid parameters return null with error logged.
     */
    ensureEditor(descriptor: HeaderFooterDescriptor, options?: {
        editorHost?: HTMLElement;
        availableWidth?: number;
        availableHeight?: number;
        currentPageNumber?: number;
        currentPageNumberText?: string;
        currentPageDisplayNumber?: number;
        currentPageChapterNumberText?: string;
        currentPageChapterSeparator?: PageNumberChapterSeparator;
        totalPageCount?: number;
        sectionPageCount?: number;
    }): Promise<Editor | null>;
    /**
     * Synchronously returns the cached editor for a descriptor, creating it on demand.
     *
     * Presentation-mode story activation needs a stable editor instance and DOM
     * target immediately so input can be forwarded into the hidden host without
     * waiting for the async `create` event. The normal lifecycle hooks still run
     * through the returned entry's `ready` promise.
     */
    ensureEditorSync(descriptor: HeaderFooterDescriptor, options?: {
        editorHost?: HTMLElement;
        availableWidth?: number;
        availableHeight?: number;
        currentPageNumber?: number;
        currentPageNumberText?: string;
        currentPageDisplayNumber?: number;
        currentPageChapterNumberText?: string;
        currentPageChapterSeparator?: PageNumberChapterSeparator;
        totalPageCount?: number;
        sectionPageCount?: number;
    }): Editor | null;
    /**
     * Retrieves the editor instance for a given header/footer descriptor,
     * if one has been created.
     *
     * This method only returns already-created editors. To ensure an editor
     * exists (creating it if necessary), use ensureEditor() instead.
     *
     * @param descriptor - The header or footer descriptor
     * @returns The editor instance if it exists, null otherwise
     *
     * @example
     * ```typescript
     * const descriptor = manager.getDescriptorById('rId-header-default');
     * const editor = manager.getEditor(descriptor);
     * if (editor) {
     *   // Editor exists, can be used immediately
     * }
     * ```
     */
    getEditor(descriptor: HeaderFooterDescriptor): Editor | null;
    /**
     * Returns all header/footer descriptors, optionally filtered by kind.
     *
     * @param kind - Optional filter: 'header' or 'footer'. If omitted, returns all descriptors.
     * @returns Array of descriptors matching the filter criteria
     *
     * @example
     * ```typescript
     * // Get all descriptors
     * const all = manager.getDescriptors();
     *
     * // Get only headers
     * const headers = manager.getDescriptors('header');
     *
     * // Get only footers
     * const footers = manager.getDescriptors('footer');
     * ```
     */
    getDescriptors(kind?: HeaderFooterKind): HeaderFooterDescriptor[];
    /**
     * Retrieves a header/footer descriptor by its relationship ID.
     *
     * @param id - The relationship ID (e.g., 'rId-header-default')
     * @returns The descriptor if found, undefined otherwise
     *
     * @example
     * ```typescript
     * const descriptor = manager.getDescriptorById('rId-header-default');
     * if (descriptor) {
     *   console.log(`Found ${descriptor.kind} with variant ${descriptor.variant}`);
     * }
     * ```
     */
    getDescriptorById(id: string): HeaderFooterDescriptor | undefined;
    /**
     * Retrieves the ProseMirror document JSON for a header/footer section.
     *
     * This method first attempts to get the live document from an active editor
     * (if one exists). If that fails or no editor exists, it falls back to the
     * converter's snapshot of the document.
     *
     * @param descriptor - The header or footer descriptor
     * @returns The document JSON structure, or null if not found
     *
     * @example
     * ```typescript
     * const descriptor = manager.getDescriptorById('rId-header-default');
     * const json = manager.getDocumentJson(descriptor);
     * if (json) {
     *   // Process the ProseMirror document structure
     * }
     * ```
     */
    getDocumentJson(descriptor: HeaderFooterDescriptor): HeaderFooterDocument | null;
    /**
     * Returns the root editor instance that this manager was created with.
     *
     * @returns The root editor containing the main document
     */
    get rootEditor(): Editor;
    /**
     * Returns the relationship ID associated with the requested Word header/footer variant.
     *
     * @param kind - The header or footer kind
     * @param variant - The page variant (default, first, even, or odd)
     * @returns The relationship ID if found, null otherwise
     */
    getVariantId(kind: HeaderFooterKind, variant: HeaderFooterVariant): string | null;
    /**
     * Pin the editor for a given descriptor id. Pinned editors are exempt from
     * LRU eviction, so owners with reachable history (e.g. the document-wide
     * history coordinator) can guarantee the editor stays alive.
     */
    pin(id: string): void;
    /** Remove a previous `pin()`. The editor may become evictable on the next access. */
    unpin(id: string): void;
    /** True while the descriptor id is pinned. */
    isPinned(id: string): boolean;
    /**
     * Sets the maximum number of cached header/footer editors.
     *
     * Least recently used editors will be disposed when this limit is exceeded.
     * If the new limit is lower than the current number of cached editors,
     * excess editors are immediately evicted.
     *
     * @param max - Maximum number of editors to keep in memory (must be between 1 and 100, and an integer)
     * @throws Error if max is less than 1, greater than 100, or not an integer
     *
     * @example
     * ```typescript
     * manager.setMaxCachedEditors(5); // Limit to 5 cached editors
     * ```
     */
    setMaxCachedEditors(max: number): void;
    /**
     * Returns cache performance statistics for monitoring and debugging.
     *
     * Provides metrics about cache effectiveness, including hit rate, number of
     * cached editors, and eviction counts. Useful for tuning cache size and
     * understanding access patterns in production.
     *
     * @returns Object containing cache statistics
     *
     * @example
     * ```typescript
     * const stats = manager.getCacheStats();
     * console.log(`Cache hit rate: ${(stats.hitRate * 100).toFixed(1)}%`);
     * console.log(`Evictions: ${stats.evictions}`);
     * ```
     */
    getCacheStats(): HeaderFooterCacheStats;
    /**
     * Resets cache statistics (hits, misses, evictions) to zero.
     * Does not clear cached editors or affect cache behavior.
     *
     * Useful for starting fresh measurements after configuration changes
     * or for periodic monitoring resets.
     *
     * @example
     * ```typescript
     * manager.resetCacheStats();
     * // ... perform operations ...
     * const stats = manager.getCacheStats(); // Fresh stats from reset point
     * ```
     */
    resetCacheStats(): void;
}
/**
 * Adapter for converting header/footer editor content to layout-engine FlowBlocks.
 *
 * This class bridges the gap between the HeaderFooterEditorManager (which manages
 * ProseMirror editors for header/footer sections) and the layout engine (which
 * requires FlowBlock representations for rendering).
 *
 * Features:
 * - Converts ProseMirror JSON documents to FlowBlock arrays
 * - Caches conversion results for performance
 * - Provides invalidation mechanisms when content changes
 * - Organizes blocks by variant (default, first, even, odd) for page-based layout
 *
 * @example
 * ```typescript
 * const adapter = new HeaderFooterLayoutAdapter(manager, mediaFiles);
 * const headerBatch = adapter.getBatch('header');
 * // Returns: { default: [...blocks], first: [...blocks], ... }
 * ```
 */
export declare class HeaderFooterLayoutAdapter {
    #private;
    /**
     * Creates a new HeaderFooterLayoutAdapter.
     *
     * @param manager - The HeaderFooterEditorManager instance to source content from
     * @param mediaFiles - Optional mapping of media IDs to URLs for image resolution
     */
    constructor(manager: HeaderFooterEditorManager, mediaFiles?: Record<string, string>);
    setTrackedChangesRenderConfig(config: HeaderFooterTrackedChangesRenderConfig): void;
    /**
     * Retrieves FlowBlock batches for all variants of a given header/footer kind.
     *
     * This method converts the ProseMirror documents for all available variants
     * (default, first, even, odd) into FlowBlock arrays suitable for the layout engine.
     * Results are cached based on document identity to avoid redundant conversions.
     *
     * @param kind - The type of section to retrieve: 'header' or 'footer'
     * @returns An object mapping variant names to FlowBlock arrays, or undefined if no content exists
     *
     * @example
     * ```typescript
     * const headerBatch = adapter.getBatch('header');
     * if (headerBatch) {
     *   // headerBatch.default contains blocks for default pages
     *   // headerBatch.first contains blocks for first page (if exists)
     * }
     * ```
     */
    getBatch(kind: HeaderFooterKind): HeaderFooterBatch | undefined;
    /**
     * Retrieves FlowBlocks for ALL header/footer content, keyed by relationship ID.
     *
     * Unlike getBatch() which only returns content for variant-associated IDs,
     * this method returns content for ALL registered header/footer IDs. This is
     * essential for multi-section documents where different sections may use
     * different content for the same variant type.
     *
     * @param kind - The type of section to retrieve: 'header' or 'footer'
     * @returns A Map of rId to FlowBlock arrays, or undefined if no content exists
     *
     * @example
     * ```typescript
     * const footersByRId = adapter.getBlocksByRId('footer');
     * if (footersByRId) {
     *   // footersByRId.get('rId14') - blocks for footer with rId14
     *   // footersByRId.get('rId18') - blocks for footer with rId18 (different section)
     * }
     * ```
     */
    getBlocksByRId(kind: HeaderFooterKind): Map<string, FlowBlock[]> | undefined;
    /**
     * Retrieves FlowBlocks for a specific header/footer by its relationship ID.
     *
     * @param rId - The relationship ID (e.g., 'rId14')
     * @returns FlowBlock array for the specified rId, or undefined if not found
     */
    getBlocksForRId(rId: string): FlowBlock[] | undefined;
    /**
     * Invalidates the cached FlowBlocks for a specific header/footer section.
     *
     * Call this method when the content of a specific section changes to force
     * re-conversion on the next getBatch() call.
     *
     * @param rId - The relationship ID of the section to invalidate
     *
     * @example
     * ```typescript
     * // After editing a header
     * manager.on('contentChanged', ({ descriptor }) => {
     *   adapter.invalidate(descriptor.id);
     * });
     * ```
     */
    invalidate(rId: string): void;
    /**
     * Invalidates all cached FlowBlocks.
     *
     * Should be called when mediaFiles are updated globally, as image references
     * in blocks may need to be regenerated with new media URLs. Also useful when
     * the converter context changes (styles, numbering, etc.).
     *
     * @example
     * ```typescript
     * // After updating media files
     * adapter.invalidateAll();
     * const freshBatch = adapter.getBatch('header'); // Will re-convert all sections
     * ```
     */
    invalidateAll(): void;
    /**
     * Clears all cached FlowBlocks.
     *
     * Alias for invalidateAll(). Useful for cleanup operations.
     */
    clear(): void;
}
export {};
//# sourceMappingURL=HeaderFooterRegistry.d.ts.map