/**
 * HighlightCoordinator
 *
 * Manages separate highlight layers for TTS (temporary) and annotations (persistent).
 * Uses CSS Custom Highlight API - zero DOM mutation, preserves accessibility.
 *
 * Features:
 * - Separate layers prevent TTS clearing from removing student annotations
 * - CSS Custom Highlight API (no DOM mutation)
 * - Full accessibility support (screen readers see original text)
 * - Configurable colors and styles
 * - Annotation persistence via RangeSerializer
 *
 * Part of PIE Assessment Toolkit.
 *
 * Browser Support:
 * - Chrome/Edge 105+
 * - Safari 17.2+
 * - Firefox: Behind flag (not recommended for production)
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/API/CSS_Custom_Highlight_API
 */
import type { HighlightCoordinatorApi } from "./interfaces.js";
import { type SerializedRange } from "./RangeSerializer.js";
/**
 * Highlight types
 */
export declare enum HighlightType {
    TTS_WORD = "tts-word",
    TTS_SENTENCE = "tts-sentence",
    ANNOTATION = "annotation"
}
/**
 * Highlight colors for annotations
 */
export declare enum HighlightColor {
    YELLOW = "yellow",
    GREEN = "green",
    BLUE = "blue",
    PINK = "pink",
    ORANGE = "orange",
    UNDERLINE = "underline"
}
/**
 * Annotation data
 */
export interface Annotation {
    id: string;
    range: Range;
    type: HighlightType.ANNOTATION;
    color: HighlightColor;
    timestamp: number;
}
/**
 * Configuration for HighlightCoordinator
 * Currently empty but allows future extension without breaking changes
 */
export type HighlightCoordinatorConfig = Record<string, never>;
export declare class HighlightCoordinator implements HighlightCoordinatorApi {
    private config;
    private ttsWordHighlight;
    private ttsSentenceHighlight;
    private ttsWordElementHighlights;
    private ttsSentenceElementHighlights;
    private annotations;
    private colorHighlights;
    private nextAnnotationId;
    private supported;
    private rangeSerializer;
    private themeObserver;
    private explicitTTSColorOverride;
    constructor(config?: HighlightCoordinatorConfig);
    private setupThemeObservation;
    private parseColor;
    private relativeLuminance;
    private contrastRatio;
    private blend;
    private resolveAdaptiveTTSStyle;
    private applyAdaptiveTTSStyle;
    /**
     * Initialize CSS Custom Highlights
     */
    private initializeHighlights;
    /**
     * Register CSS styles for highlights
     */
    private registerStyles;
    /**
     * Highlight a word for TTS (temporary)
     *
     * @param textNode Text node containing the word
     * @param startOffset Start position in text node
     * @param endOffset End position in text node
     */
    highlightTTSWord(textNode: Text, startOffset: number, endOffset: number): void;
    /**
     * Highlight a single element as the active TTS word (temporary).
     *
     * Unlike {@link highlightTTSWord} (which paints a CSS range over a text node)
     * this marks the element itself via `data-pie-tts-word-element`. It is used
     * for atomic targets that have no direct text node to range over — most
     * notably MathJax CHTML tokens (e.g. `<mjx-mi><mjx-c/></mjx-mi>`, whose glyph
     * lives in a font-driven pseudo-element a CSS range cannot paint) and
     * whole-expression fallbacks.
     *
     * The supplied element is painted exactly; we deliberately do NOT walk up to
     * a containing `<math>` / `<mjx-container>`. That escalation is what made
     * MathJax-rendered math highlight as a full block while native MathML tracked
     * per-token: a resolved single token must paint as a token, and only a
     * genuine expression fallback (where the element already is the container)
     * should paint the whole expression.
     */
    highlightTTSWordElement(element: Element): void;
    /**
     * Highlight the coarse TTS read-along band (temporary).
     * Usually one Range per visual line; CSS layer `tts-sentence` for compatibility.
     *
     * @param ranges Line (or sentence) ranges to paint with `--pie-tts-line-highlight`
     */
    highlightTTSSentence(ranges: Range[]): void;
    /**
     * Highlight sentence/block elements for TTS (background layer).
     *
     * @param elements Visible elements to paint with `--pie-tts-line-highlight`
     */
    highlightTTSSentenceElements(elements: Element[]): void;
    private static readonly SENTENCE_FALLBACK_SELECTOR;
    private static readonly WORD_FALLBACK_SELECTOR;
    private highlightTTSElementFallbacks;
    private highlightTTSWordElementFallbacks;
    private highlightElementFallbacks;
    /**
     * Clear TTS word highlight
     */
    clearTTSWord(): void;
    /**
     * Clear TTS sentence highlight
     */
    clearTTSSentence(): void;
    /**
     * Clear all TTS highlights
     */
    clearTTS(): void;
    /**
     * Add an annotation highlight (persistent)
     *
     * @param range Text range to annotate
     * @param color Highlight color
     * @returns Annotation ID for later removal
     */
    addAnnotation(range: Range, color?: HighlightColor): string;
    /**
     * Remove an annotation
     *
     * @param id Annotation ID
     */
    removeAnnotation(id: string): void;
    /**
     * Remove all annotations
     */
    clearAnnotations(): void;
    /**
     * Get all annotations
     */
    getAnnotations(): Annotation[];
    /**
     * Get annotation by ID
     */
    getAnnotation(id: string): Annotation | null;
    /**
     * Change annotation color
     *
     * @param id Annotation ID
     * @param newColor New color
     */
    changeAnnotationColor(id: string, newColor: HighlightColor): void;
    /**
     * Export annotations as serializable data for persistence.
     * Uses RangeSerializer for robust DOM range serialization.
     *
     * @param root Root element for serialization (typically document.body or content container)
     * @returns Array of serialized annotations
     */
    exportAnnotations(root?: Element): Array<SerializedRange & {
        id: string;
        color: HighlightColor;
        timestamp: number;
    }>;
    /**
     * Import annotations from serialized data.
     * Restores annotations after page navigation or refresh.
     *
     * @param data Array of serialized annotations
     * @param root Root element for deserialization (same as used in export)
     * @returns Number of successfully restored annotations
     */
    importAnnotations(data: Array<SerializedRange & {
        id?: string;
        color: HighlightColor;
        timestamp?: number;
    }>, root?: Element): number;
    /**
     * Highlight a text range (interface method)
     *
     * Generic method that adapts to the specific highlight type.
     * For more control, use the specific methods like highlightTTSWord().
     */
    highlightRange(range: Range, type: HighlightType, color?: HighlightColor): void;
    /**
     * Clear highlights of a specific type (interface method)
     */
    clearHighlights(type: HighlightType): void;
    /**
     * Clear all highlights (interface method)
     */
    clearAll(): void;
    /**
     * Check if CSS Highlight API is supported (interface method)
     */
    isSupported(): boolean;
    /**
     * Update TTS highlight style dynamically
     *
     * @param color CSS color value (e.g., '#ffeb3b')
     * @param opacity Opacity value (0.0 to 1.0)
     */
    updateTTSHighlightStyle(color: string, opacity: number): void;
    /**
     * Cleanup - remove all highlights
     */
    destroy(): void;
}
