/**
 * Font metrics database and similarity matching.
 *
 * Combines data from @capsizecss/metrics (Google/system fonts) with
 * fontkit measurements of Microsoft Office and macOS-only fonts.
 *
 * Use findClosestFont() to find the metrically-closest available fallback
 * for a font that may not be present on the target platform.
 */
export type FontCategory = "sans-serif" | "serif" | "monospace" | "display";
export interface FontMetrics {
    /** Font category (sans-serif, serif, monospace, display) */
    cat: FontCategory;
    /** Units per em — all other values are in these units */
    upm: number;
    /** Average advance width of Latin alphanumeric + space characters */
    xWidthAvg: number;
    /** Cap height (height of uppercase H) */
    capH: number;
    /** x-height (height of lowercase x) */
    xH: number;
    /** Ascent above baseline */
    asc: number;
    /** Descent below baseline (negative) */
    desc: number;
    /** Line gap */
    lineGap: number;
}
/**
 * Pre-computed metrics for common fonts.
 *
 * System fonts (Windows + macOS) use layout-based xWidthAvg measured with
 * fontkit — this includes GPOS kerning/spacing and accurately predicts
 * actual text width. Google Fonts use raw glyph xWidthAvg from
 * @capsizecss/metrics (capsize.dev), which is approximate.
 */
export declare const FONT_METRICS: Record<string, FontMetrics>;
/**
 * Fonts preinstalled on BOTH macOS and iOS.
 * Only includes fonts that have entries in FONT_METRICS above.
 * Use as `candidates` in findClosestFont() to ensure the result is a real system font.
 */
export declare const APPLE_SYSTEM_FONTS: ReadonlySet<string>;
/** Array form for passing to findClosestFont({ candidates }) */
export declare const APPLE_SYSTEM_FONT_LIST: readonly string[];
/**
 * macOS-only system fonts (not on iOS).
 * Combined with APPLE_SYSTEM_FONTS for macOS-specific matching.
 */
export declare const MACOS_ONLY_FONTS: ReadonlySet<string>;
/** All macOS system fonts (APPLE_SYSTEM_FONTS + MACOS_ONLY_FONTS) */
export declare const MACOS_SYSTEM_FONTS: ReadonlySet<string>;
export declare const MACOS_SYSTEM_FONT_LIST: readonly string[];
/** Width delta (%) between two fonts. Positive = target is wider. */
export declare function widthDelta(source: FontMetrics, target: FontMetrics): number;
export interface FontMatch {
    /** Matched font name */
    font: string;
    /** Similarity score (lower = better, 0 = identical) */
    score: number;
    /** Width difference as percentage (positive = wider) */
    widthDelta: number;
}
/**
 * Find the closest fonts in the database to the given source font.
 *
 * @param source - Name of the source font, or its FontMetrics
 * @param options.candidates - Limit search to these font names (default: all fonts in DB)
 * @param options.sameCategory - Only match fonts of the same category (default: true)
 * @param options.limit - Max results to return (default: 3)
 */
export declare function findClosestFont(source: string | FontMetrics, options?: {
    candidates?: readonly string[];
    sameCategory?: boolean;
    limit?: number;
}): FontMatch[];