import type { Datum } from "../charts/shared/datumTypes";
/**
 * M3 — Amount & density management (Rahman et al.'s sixth consideration:
 * "balance explanatory support against clutter").
 *
 * A pure, geometry-light pass that decides *which* note-like annotations should
 * stay on screen when there are more than the plot area can carry without
 * clutter. It does not move anything (that is M2's `annotationLayout`); it
 * partitions notes into a persistent set and a deferred set by importance and
 * freshness, with the lowest-priority notes shed first.
 *
 * Priority signals, reusing what M0/M1 already attach:
 *   • `emphasis` (M1) — `"primary"` is the floor (never shed); `"secondary"`
 *     ranks below an un-emphasised note.
 *   • `provenance.confidence` (M0) — a small nudge so a higher-confidence note
 *     outranks a lower-confidence one at the same emphasis.
 *   • `lifecycle.freshness` (M0) — `fresh > aging > stale`; `expired` is shed
 *     first.
 *
 * Only note types compete for the budget; reference lines, bands, enclosures
 * and statistical overlays pass through untouched (they are not "clutter notes"
 * in the paper's sense and a density cap shedding a threshold line would be
 * surprising).
 *
 * The persistent set is the floor and is never empty when any note exists — the
 * paper's "keep the core message persistent; hover is not guaranteed."
 */
/** Plot area (px²) allotted per note before the budget tightens. */
export declare const DEFAULT_AREA_PER_ANNOTATION = 20000;
export interface AnnotationDensityConfig {
    /**
     * Hard cap on simultaneously-persistent notes. When set, overrides the
     * `width`×`height`-derived budget.
     */
    maxAnnotations?: number;
    /**
     * Plot area (px²) allotted per note when deriving the budget from the chart
     * dimensions. Larger ⇒ fewer notes. Default {@link DEFAULT_AREA_PER_ANNOTATION}.
     */
    areaPerAnnotation?: number;
    /** Minimum notes kept regardless of budget. Default 1. */
    minVisible?: number;
}
export interface AnnotationDensityOptions extends AnnotationDensityConfig {
    annotations: ReadonlyArray<Datum>;
    /** Plot width in px (used to derive the budget when `maxAnnotations` is unset). */
    width: number;
    /** Plot height in px. */
    height: number;
}
export interface AnnotationDensityResult {
    /** Notes kept on screen plus every non-note annotation, in author order. */
    visible: Datum[];
    /** Notes shed by the budget, in author order. Empty when nothing is shed. */
    deferred: Datum[];
    /** The note budget that produced this partition. */
    budget: number;
}
/**
 * Derive the note budget for a plot. Exported so the clutter diagnostic
 * (`diagnoseConfig`) and the runtime pass agree on the same threshold.
 */
export declare function annotationBudget(width: number, height: number, config?: AnnotationDensityConfig): number;
/**
 * Partition annotations into a persistent (visible) set and a deferred set
 * given a note budget. Pure and deterministic; preserves author order within
 * each returned array.
 */
export declare function annotationDensity(options: AnnotationDensityOptions): AnnotationDensityResult;
