/**
 * Font OFFERINGS: the product layer between the substitution evidence and the UI. It answers a
 * different question than the resolver does. The resolver answers "given a logical font a document
 * already uses, what do we render?". An offering answers "should SuperDoc advertise this logical font
 * as a choice, and on which surface?".
 *
 * Three consumers are intended:
 *   1. CLEAN defaults - reliable, bundled, metric-safe fonts SuperDoc can render deterministically.
 *      Built from {@link getDefaultFontOfferings}.
 *   2. BUILT-IN toolbar options - bundled choices SuperDoc can render, plus qualified/category rows
 *      the product has explicitly chosen to advertise. Built from {@link getBuiltInToolbarFontOfferings}.
 *   3. DOCUMENT-specific options - whatever a given document actually uses. Those are
 *      document-scoped and runtime-aware; this static module only provides the default offerings.
 *
 * Derived from `SUBSTITUTION_EVIDENCE` x `BUNDLED_MANIFEST`. Adding/retiring a font is an evidence
 * edit, never a hand-maintained toolbar list.
 */
import { type BundledActivation, type BundledFontSelection, type FontAssetConfigLike } from './activation.js';
import { type CssGeneric, type SubstituteVerdict } from './substitution-evidence.js';
/** CSS generic family used to terminate an offering's fallback stack. */
export type FontGeneric = CssGeneric;
/** Which UI surface a logical font may appear on. A product decision, distinct from the verdict. */
export type OfferingClass = 'default' | 'qualified' | 'category_fallback' | 'supported_alias' | 'requires_asset' | 'customer_supplied' | 'preserve_only';
export interface FontOffering {
    /** Word-facing logical family: the toolbar label and the value stored/exported (e.g. "Calibri"). */
    logicalFamily: string;
    /** Physical render family (e.g. "Carlito"); null when nothing renders it (customer_supplied). */
    physicalFamily: string | null;
    generic: FontGeneric;
    /** Product classification: which UI surface this font may appear on (distinct from the verdict). */
    offering: OfferingClass;
    /**
     * Static fact: `physicalFamily` ships in the bundled pack. This is NOT runtime renderability - a
     * document's `fonts.add` faces or embedded fonts are unknown to this static module and belong to a
     * later document-scoped offering function.
     */
    bundled: boolean;
    /** docfonts fidelity verdict, used to separate clean defaults from qualified/category fallbacks. */
    verdict: SubstituteVerdict;
    /** Provenance back to the evidence row. */
    evidenceId: string;
}
/** Every logical font SuperDoc has evidence for, classified by offering surface. */
export declare const FONT_OFFERINGS: readonly FontOffering[];
/**
 * The metric-safe, bundled-backed offerings safe to treat as clean defaults, sorted by logical
 * family. Excludes redundant aliases even when they are renderable; those still resolve for
 * documents through the resolver.
 * Excludes qualified rows (Arial Black, Arial Narrow, Cambria, Century, Century Gothic,
 * Century Schoolbook, Cooper Black, Georgia, Baskerville Old Face, Bookman Old Style, ITC Bookman),
 * category fallbacks (Calibri Light, Tahoma, Trebuchet MS, Garamond, Comic Sans MS, Brush Script MT,
 * Gill Sans MT Condensed, Lucida Console, Consolas, Verdana, Segoe UI), supported aliases
 * (Arial MT, Courier, Times), and not-yet-bundled candidates.
 */
export declare function getDefaultFontOfferings(): FontOffering[];
/**
 * Built-in font picker options for a document, gated on its bundled-font {@link BundledActivation}:
 *
 *  - pack NOT configured (the default): the conservative {@link BUILT_IN_TOOLBAR_BASELINE_FAMILIES}
 *    baseline - only fonts that render acceptably with no pack served. SuperDoc does not advertise
 *    bundled fonts it would have to fetch from an unconfigured location.
 *  - pack configured: the clean defaults plus the advertised qualified / category fallbacks, minus
 *    any the consumer curated out (`createSuperDocFonts({ include / exclude })`).
 *
 * Documents still RESOLVE the full reviewed substitute table through the resolver when their pack is
 * active; this governs only what the picker ADVERTISES. Consumers that need strict metric-safe
 * choices should use {@link getDefaultFontOfferings}.
 */
export declare function getBuiltInToolbarFontOfferings(activation?: BundledActivation): FontOffering[];
/** The logical CSS stack stored/applied when an offering is chosen, e.g. "Calibri, sans-serif". */
export declare function fontOfferingStack(offering: FontOffering): string;
/**
 * The physical render CSS stack, for an accurate dropdown preview - the row renders in the bundled
 * clone that actually paints (e.g. "Carlito, sans-serif"), not the proprietary logical name the
 * browser lacks. Falls back to the logical stack when there is no physical family.
 */
export declare function fontOfferingRenderStack(offering: FontOffering): string;
/**
 * Default toolbar font options in the generic `{ label, value }` shape: label is the Word-facing
 * logical name (stored/exported), value is the logical CSS stack applied to the selection. The
 * built-in (Vue) toolbar builds its own richer `FontConfig` from
 * {@link getBuiltInToolbarFontOfferings}.
 */
export declare function getDefaultFontFamilyOptions(activation?: BundledActivation): readonly {
    label: string;
    value: string;
}[];
/**
 * The Word family names a document can curate (`include` / `exclude`): every logical family the
 * resolver substitutes to a bundled face, including category fallbacks like Verdana. The single
 * source of truth for the curation surface - {@link warnUnknownBundledSelection} validates against it
 * and `@superdoc-dev/fonts` generates its committed list from it. Distinct from the asset manifest's
 * `replaces`, which omits category fallbacks (the reason curation keys on offerings, not `replaces`).
 */
export declare function getBundledFamilyNames(): string[];
/**
 * Warn (once per name) at config time when a `fonts.bundled` curation entry is not a bundled family,
 * so curating it silently does nothing - and when both `include` and `exclude` are set. The safety
 * net for `fonts.bundled` set DIRECTLY: `createSuperDocFonts` already rejects unknown names and
 * structural errors in the consumer's setup code, but a hand-written `fonts.bundled` bypasses it. Warn
 * (not throw) here because this runs at editor init, where a font-name typo must not crash the editor.
 */
export declare function warnUnknownBundledSelection(selection: BundledFontSelection | undefined): void;
/**
 * Drop curation names that are not bundled families (keyed against the same set
 * {@link warnUnknownBundledSelection} validates), preserving the `include` / `exclude` KEYS so the
 * "include wins" precedence survives. A raw `fonts.bundled.include` that is all typos thus sanitizes
 * to an empty-but-present include, which {@link createBundledActivation} ignores back to the full pack
 * rather than emptying the toolbar. Silent: warnings are emitted once by
 * {@link warnUnknownBundledSelection}; this only cleans.
 */
export declare function sanitizeBundledSelection(selection: BundledFontSelection | undefined): BundledFontSelection | undefined;
/**
 * Derive a document's {@link BundledActivation} from its `fonts` config, first sanitizing raw
 * `fonts.bundled` against the known family set ({@link sanitizeBundledSelection}). Runtime documents
 * that may carry hand-written `fonts.bundled` should use this instead of the lower-level
 * {@link deriveBundledActivation}: it guarantees an all-unknown `include` cannot empty the
 * toolbar/resolver. (createSuperDocFonts validates the same names in the consumer's setup code.)
 */
export declare function deriveBundledActivationForConfig(config: FontAssetConfigLike | null | undefined): BundledActivation;