type FarmFontDisplay = "auto" | "block" | "swap" | "fallback" | "optional";
interface FarmFontSource {
    /** Local file path or remote URL, depending on the loader. */
    path: string;
    /** A fixed weight (`400`) or variable range (`100 900`). */
    weight?: number | string;
    /** Font style for this source. */
    style?: string;
    /** Optional CSS unicode-range descriptor. */
    unicodeRange?: string;
}
interface FarmFontOptions {
    /** CSS font-family name. */
    family: string;
    /** A fixed weight (`400`) or variable range (`100 900`). */
    weight?: number | string;
    /** Font style. @default "normal" */
    style?: string;
    /** Browser loading behavior. @default "swap" */
    display?: FarmFontDisplay;
    /** CSS custom property populated by `variable`, for example `--font-sans`. */
    variable?: `--${string}`;
    /** Fallback family names appended to the generated stack. */
    fallback?: string[];
    /** Emit font preload hints. @default true */
    preload?: boolean;
}
interface LocalFontOptions extends FarmFontOptions {
    /**
     * A file relative to this module, a package font specifier, or explicit
     * sources for a multi-weight family.
     */
    src: string | FarmFontSource[];
}
interface RemoteFontSource extends FarmFontSource {
    /** Optional integrity value for this source. Overrides the family-level value. */
    integrity?: string;
}
interface RemoteFontOptions extends FarmFontOptions {
    /** HTTPS font URL, or explicit remote sources for a multi-weight family. */
    src: string | RemoteFontSource[];
    /** Download and fingerprint the font during the build, or retain its URL. */
    strategy?: "self-host" | "external";
    /** Optional Subresource Integrity value checked while self-hosting. */
    integrity?: string;
}
interface FarmFont {
    /** Generated class that applies the font family and fallback stack. */
    className: string;
    /** Generated class that defines the configured CSS custom property. */
    variable: string;
    /** Inline-style equivalent of the generated family. */
    style: Readonly<{
        fontFamily: string;
        fontStyle?: string;
        fontWeight?: number | string;
    }>;
    /** Compiled resources that should be preloaded when this font is selected. */
    preloads: readonly Readonly<{
        href: string;
        type: string;
    }>[];
}
/** Semantic font roles inherited by framework-owned surfaces such as Farm Docs. */
interface FarmLayoutFonts {
    /** Default text and prose font. */
    body?: FarmFont;
    /** Code, keyboard input, and other technical UI font. */
    code?: FarmFont;
}
interface FarmLayoutFontModule {
    fonts?: FarmLayoutFonts;
}
/**
 * Define the semantic fonts exported by a layout.
 *
 * Layouts are resolved from the root toward the requested route. A nearer
 * layout overrides only the roles it defines, so it can replace `body` while
 * continuing to inherit `code` from a parent layout.
 */
declare function defineLayoutFonts<const T extends FarmLayoutFonts>(fonts: T): T;
/** Resolve semantic font roles from root layout to nearest layout. */
declare function resolveFarmLayoutFonts(layouts: readonly FarmLayoutFontModule[]): FarmLayoutFonts | undefined;
/**
 * Compile local font files into hashed application assets and generated CSS.
 * The call is removed at build time and adds no font-loader runtime code.
 */
declare function localFont(_options: LocalFontOptions): FarmFont;
/**
 * Compile a remote font into a self-hosted application asset by default.
 * Use `strategy: "external"` only when the browser should retain the remote URL.
 */
declare function remoteFont(_options: RemoteFontOptions): FarmFont;

export { type FarmFont, type FarmFontDisplay, type FarmFontOptions, type FarmFontSource, type FarmLayoutFontModule, type FarmLayoutFonts, type LocalFontOptions, type RemoteFontOptions, type RemoteFontSource, defineLayoutFonts, localFont, remoteFont, resolveFarmLayoutFonts };