import { DefaultFontSource, DefaultFontSubstitution, FontOriginRequest, FontResolverMark } from './index.js';

/**
 * One fetchable face in the pinned catalog.
 *
 * The catalog is a CLOSED set: a document-declared family is only ever a lookup key
 * against it, never interpolated into a URL, so a crafted `w:rFonts` cannot redirect a
 * fetch. Bytes are trusted by `hash`, not by origin.
 */
interface GoogleFontFace {
    /** The family name a document would name, e.g. "PT Sans". */
    readonly family: string;
    /** Only the two static weights; variable-only families are excluded by the generator. */
    readonly weight: 400 | 700;
    readonly style: 'normal' | 'italic';
    /** Immutable, commit-pinned jsDelivr URL. */
    readonly url: string;
    /** Expected size; a response of any other length is rejected before use. */
    readonly byteLength: number;
    /** `sha256:` digest the engine's admission path re-derives, catching a swapped CDN asset. */
    readonly hash: string;
}
/**
 * The main google/fonts catalog revision. Some static aliases use older immutable
 * revisions because their current upstream families are variable-only.
 */
declare const GOOGLE_FONTS_REVISION = "ea14f3c4c462af1d847b1abe96fcb3c3a8a66f97";
/**
 * Every face `googleFonts()` may fetch, sorted by family then weight then style. Closed
 * and pinned: nothing outside this list is reachable, which is what makes resolving a
 * document-declared family name safe.
 */
declare const GOOGLE_FONT_CATALOG: readonly GoogleFontFace[];

/**
 * `@docx-editor.dev/fonts/google` — Google-hosted faces, fetched on demand.
 *
 * Nothing is fetched until a document turns out to name a family this module can answer.
 * Open a file using only Calibri and exactly one family is fetched.
 *
 * Be deliberate about this: it makes OPENING A DOCUMENT perform network requests, which the
 * engine never does on its own. What keeps it safe is that a document-declared family is only
 * ever a LOOKUP KEY against a closed, commit-pinned catalog, and every face is trusted by
 * content hash rather than by origin.
 *
 * @example Resolve catalogued families as documents need them
 * ```ts
 * import { googleFonts } from '@docx-editor.dev/fonts/google';
 *
 * const editor = createDocxEditor({ document: bytes, fonts: googleFonts() });
 * ```
 *
 * @packageDocumentation
 * @public
 */

/** Every family the catalog can serve, sorted — the set a font picker may offer. */
declare const GOOGLE_FONT_FAMILIES: readonly string[];
/**
 * Word families with a METRIC-COMPATIBLE catalogued stand-in: identical advance widths,
 * so a document laid out on the substitute paginates like Word.
 *
 * Arial and Helvetica are absent on purpose. Their match is Arimo, which google/fonts now
 * ships variable-only, and the shaper refuses variation axes — a variable file would
 * render bold at regular weight. `defaultFonts()` still covers them from the bundle.
 */
declare const GOOGLE_METRIC_SUBSTITUTES: Readonly<Record<string, string>>;
/**
 * One face that did not arrive. Non-fatal: the resolver returns whatever else succeeded,
 * and the affected family falls back to the engine's fixed measurement.
 *
 * A `hashMismatch` does NOT appear here — bytes are trusted by content at the engine's
 * admission path, which rejects them after this resolver has handed them over.
 */
interface GoogleFontLoadFailure {
    /**
     * The family of the face that failed to load — the SERVING name ("Carlito", "TeX Gyre
     * Adventor"), not the name the document wrote. A document naming Calibri sees "Carlito"
     * here, because that is the file that did not arrive.
     */
    readonly family: string;
    /** The pinned catalog URL, or the asset filename for a face served from the bundle. */
    readonly url: string;
    readonly diagnostic: string;
}
/**
 * How `googleFonts()` behaves once a document hands it a family list. Every field is
 * optional; `googleFonts()` with no options fetches any catalogued family a document
 * names, over the global `fetch`, warning to the console on failure.
 */
interface GoogleFontsOptions {
    /**
     * Narrow what may ever load, by the name of the face that would SERVE the request
     * ("Carlito", "TeX Gyre Adventor"). Omitted, any family this module can answer is fair
     * game; set it to run against a closed short list.
     */
    readonly allow?: readonly string[];
    /**
     * Extra document-family -> catalog-family mappings, merged OVER
     * {@link GOOGLE_METRIC_SUBSTITUTES}. Only metric-compatible pairs keep pagination
     * Word-accurate; anything else trades line breaks for closer-looking glyphs.
     */
    readonly substitute?: Readonly<Record<string, string>>;
    /** Injectable for tests and CSP-constrained hosts; defaults to global `fetch`. */
    readonly fetcher?: typeof fetch;
    /** Per-face failures. Defaults to a console warning; pass a handler to route them. */
    readonly onFailure?: (failure: GoogleFontLoadFailure) => void;
}
/**
 * What {@link googleFonts} returns: a marked resolver over the pinned catalog.
 *
 * @public
 */
type GoogleFontsResolver = ((request: FontOriginRequest) => Promise<GoogleFontsFragment>) & FontResolverMark;
/** What one resolver call produced, for callers that want it without the editor. */
interface GoogleFontsFragment {
    /** Families this provider can serve after applying allow and substitute options. */
    readonly supportedFamilies?: readonly string[];
    readonly sources: readonly DefaultFontSource[];
    readonly substitutions: readonly DefaultFontSubstitution[];
    readonly failures: readonly GoogleFontLoadFailure[];
}
/**
 * A {@link FontResolver} that serves the document's declared families from the pinned
 * Google catalog — plus the package's own bundled faces for families the catalog has no
 * metric-compatible answer for — loading only what that document turned out to need.
 *
 * ```ts
 * <DocxEditor.Root fonts={googleFonts()} />
 * ```
 *
 * Same call shape as `packagedFonts()` from `@docx-editor.dev/fonts`, so the two compose
 * by sitting next to each other: `useFonts(packagedFonts(), googleFonts())` serves the
 * bundled faces first and reaches the catalog only for what they do not cover.
 *
 * Compose it with your own bytes by wrapping it — the resolver is an ordinary async
 * function of the families, so a wrapper can merge fragments before returning.
 */
declare function googleFonts(options?: GoogleFontsOptions): GoogleFontsResolver;

export { GOOGLE_FONTS_REVISION, GOOGLE_FONT_CATALOG, GOOGLE_FONT_FAMILIES, GOOGLE_METRIC_SUBSTITUTES, type GoogleFontFace, type GoogleFontLoadFailure, type GoogleFontsFragment, type GoogleFontsOptions, type GoogleFontsResolver, googleFonts };