superdoc 2.2.1 → 2.3.0

package/dist/shared/font-system/src/epoch.d.ts

@@ -0,0 +1,6 @@
+/** The current epoch. Reuse signatures include this so they bust on a font change. */
+export declare function getFontConfigVersion(): number;
+/** Advance the epoch (call after a font loads or the configuration changes). */
+export declare function bumpFontConfigVersion(): number;
+/** Reset the epoch. Test-only; not part of the public surface. */
+export declare function __resetFontConfigVersion(): void;

package/dist/shared/font-system/src/font-offerings.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 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/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;

package/dist/shared/font-system/src/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `@superdoc/font-system` - runtime font registry, load-state, and logical->physical
+ * resolution shared across the SuperDoc rendering pipeline.
+ *
+ * Consumed by measurement (`@superdoc/measuring-dom`), paint (`painters/dom`),
+ * and editor runtimes so all layers agree on which
+ * physical face is used and whether it is ready. Separate from
+ * `@superdoc/font-utils` (CSS fallback-string composition only).
+ *
+ * Surfaces: the load-state contract + `FontRegistry` (a registry per `FontFaceSet`);
+ * the resolver (`resolveFontFamily`/`resolvePhysicalFamily`, e.g. Calibri->Carlito);
+ * and a `fontConfigVersion` epoch that reuse signatures fold in so a font change busts
+ * stale measure/paint reuse. The bundled substitute pack ships from the `./bundled`
+ * subpath; the public DX surface (T7) builds on `FontRegistry.register`.
+ */
+export type { FontLoadStatus, FontFaceSource, FontFaceDescriptor, RegisteredFace, RegisterFaceResult, FontLoadResult, FontLoadSummary, FontFaceRequest, FontFaceLoadResult, FontAssetUrlContext, FontAssetUrlResolver, RequiredFace, } from './types.js';
+export { SETTLED_STATUSES, isSettled } from './types.js';
+export type { FontResolution, FontResolutionReason, FaceKey, HasFace, FontMeasureContext, ResolvePhysicalFamily, } from './resolver.js';
+export { FontResolver, createFontResolver } from './resolver.js';
+export { resolveFontFamily, resolvePhysicalFamily, resolvePrimaryPhysicalFamily, resolvePhysicalFamilies, resolveFace, DEFAULT_FONT_MEASURE_CONTEXT, } from './resolver.js';
+export { getFontConfigVersion, bumpFontConfigVersion, __resetFontConfigVersion } from './epoch.js';
+export type { BundledFontSelection, BundledActivation, BundledActivationInput, FontAssetConfigLike, } from './activation.js';
+export { createBundledActivation, deriveBundledActivation, FULLY_ACTIVE_BUNDLED, BASELINE_BUNDLED } from './activation.js';
+export { setBundledFontAssetBase, getBundledFontAssetBase, DEFAULT_BUNDLED_FONT_BASE, markBundledPackPresent, isBundledPackPresent, __resetBundledPackPresent, } from './bundled.js';
+export type { FontResolutionRecord, ResolvedFontEvidence, UsedFace } from './report.js';
+export { buildFontReport, buildFaceReport } from './report.js';
+export type { EmbeddingPolicy } from './os2.js';
+export { parseEmbeddingPolicy } from './os2.js';
+export type { FontSetLike, FontFaceLike, FontFaceCtor, FontRegistryOptions, OwnedFaceDescriptor } from './registry.js';
+export { FontRegistry, getFontRegistryFor, getDefaultFontRegistry, DEFAULT_FONT_LOAD_TIMEOUT_MS, __resetDefaultFontRegistry, } from './registry.js';
+export type { FontOffering, OfferingClass, FontGeneric } from './font-offerings.js';
+export { FONT_OFFERINGS, getBuiltInToolbarFontOfferings, getDefaultFontOfferings, getDefaultFontFamilyOptions, fontOfferingStack, fontOfferingRenderStack, warnUnknownBundledSelection, getBundledFamilyNames, sanitizeBundledSelection, deriveBundledActivationForConfig, } from './font-offerings.js';
+export type { DocumentFontOption, FontFamilyOption } from './document-font-options.js';
+export { buildDocumentFontOptions, buildFontFamilyOptions } from './document-font-options.js';
+export type { FaceSlot as FontFaceSlot, GlyphException, SubstitutePolicyAction, SubstituteVerdict, } from './substitution-evidence.js';

package/dist/shared/font-system/src/os2.d.ts

@@ -0,0 +1,30 @@
+import type { FaceKey } from './resolver.js';
+/**
+ * The embedding policy + face axis read from a font's OS/2 table.
+ *
+ * Used to decide whether a DOCX-embedded font may be REGISTERED for rendering (its license permits
+ * embedding) and which weight/style FACE it represents - so embedded fonts become first-class
+ * registry faces with the correct {@link FaceKey} instead of being inferred from filenames.
+ */
+export interface EmbeddingPolicy {
+    /** Raw OS/2 `fsType` bit field (the licensing/embedding permissions). */
+    fsType: number;
+    /** The face this font provides, from OS/2 `usWeightClass` + the `fsSelection` italic bit. */
+    face: FaceKey;
+    /**
+     * The minimal RENDER gate: false only when fsType marks the font Restricted-License / no-embedding
+     * (bit 1). This is NOT a complete licensing model - Preview&Print vs Editable vs Installable, the
+     * No-Subsetting (0x0100) and Bitmap-only (0x0200) bits, and re-embedding for EXPORT/EDIT (vs
+     * display) all need their own policy decisions. The raw {@link fsType} is preserved so callers can
+     * apply a stricter policy without re-parsing.
+     */
+    embeddable: boolean;
+}
+/**
+ * Parse a font's OS/2 embedding policy + face from its raw bytes (a deobfuscated DOCX-embedded TTF/OTF).
+ *
+ * Returns `null` when the bytes are not a parseable SFNT or have no readable OS/2 table - callers MUST
+ * treat a null result conservatively (do NOT register; fall through to the bundled substitute), since
+ * we cannot prove the font is licensed for embedding.
+ */
+export declare function parseEmbeddingPolicy(bytes: ArrayBuffer | ArrayBufferView): EmbeddingPolicy | null;

package/dist/shared/font-system/src/registry.d.ts

@@ -0,0 +1,188 @@
+import type { FontFaceDescriptor, FontFaceLoadResult, FontFaceRequest, FontLoadResult, FontLoadStatus, RegisteredFace, RegisterFaceResult, RequiredFace } from './types.js';
+/**
+ * Default per-font budget the gate waits before treating a face as `timed_out`
+ * and proceeding with a fallback. Generous enough for a cold cache on a slow
+ * connection, short enough that a missing font never blocks first paint forever.
+ */
+export declare const DEFAULT_FONT_LOAD_TIMEOUT_MS = 3000;
+/**
+ * Structural slice of the CSS Font Loading API (`FontFaceSet`) the registry
+ * depends on. Declared as an interface (not the DOM type) so the registry is
+ * unit-testable with a fake and degrades cleanly where there is no DOM.
+ */
+export interface FontSetLike {
+    add(face: FontFaceLike): void;
+    /** Remove a managed face (DOM `FontFaceSet.delete`). Optional: some sets (domless/tests) omit it. */
+    delete?(face: FontFaceLike): boolean;
+    load(font: string, text?: string): Promise<FontFaceLike[]>;
+    check(font: string, text?: string): boolean;
+}
+/** Structural slice of a `FontFace`. */
+export interface FontFaceLike {
+    readonly family: string;
+    load(): Promise<FontFaceLike>;
+    readonly status?: string;
+}
+/** Structural slice of the global `FontFace` constructor. */
+export type FontFaceCtor = new (family: string, source: string | ArrayBuffer | ArrayBufferView, descriptors?: FontFaceDescriptors) => FontFaceLike;
+/**
+ * A document-owned font face registered from raw bytes (a deobfuscated DOCX-embedded font), the input
+ * to {@link FontRegistry.registerOwnedFace}. Carries the bytes plus the OS/2-derived face axis so the
+ * face registers under the document's family name with the correct weight/style and flows through the
+ * resolver's `registered_face` rung. `weight`/`style` are already canonical (no normalization needed).
+ */
+export interface OwnedFaceDescriptor {
+    family: string;
+    source: ArrayBuffer | ArrayBufferView;
+    weight: '400' | '700';
+    style: 'normal' | 'italic';
+}
+export interface FontRegistryOptions {
+    /** The font set to drive. Defaults to the ambient `document.fonts`. */
+    fontSet?: FontSetLike | null;
+    /** Constructor for new managed faces. Defaults to the global `FontFace`. */
+    FontFaceCtor?: FontFaceCtor | null;
+    /** Font size used in probe strings. Only affects the `font` shorthand syntax. */
+    probeSize?: string;
+    /** Timer hooks, injectable for deterministic tests. Default to the globals. */
+    scheduleTimeout?: (cb: () => void, ms: number) => unknown;
+    cancelTimeout?: (handle: unknown) => void;
+}
+/**
+ * Runtime registry of font faces and their load state.
+ *
+ * Two jobs:
+ *  1. **Register** managed faces (bundled substitutes, customer BYO fonts) so the
+ *     browser knows how to load them. Registration is lazy - it adds the face to
+ *     the set but does not download until something awaits it.
+ *  2. **Await** the specific faces a layout pass needs, with a per-font timeout,
+ *     reporting `loaded | failed | timed_out | fallback_used`. This is the
+ *     contract the load-before-measure gate consumes; it works for *any* family
+ *     in the set, whether the registry created the face (managed) or it was
+ *     injected elsewhere (embedded `@font-face`, a system font).
+ *
+ * The registry intentionally does not subscribe to font-loading events or touch
+ * measurement caches - those belong to the gate, which owns the editor lifecycle.
+ */
+export declare class FontRegistry {
+    #private;
+    constructor(options?: FontRegistryOptions);
+    /**
+     * Register a managed face. Adds it to the font set so the browser can load it
+     * on demand, but does not download yet. Safe to call where there is no DOM /
+     * constructor: the family is recorded as `unloaded` and will resolve to
+     * `fallback_used` when awaited.
+     */
+    register(descriptor: FontFaceDescriptor): RegisterFaceResult;
+    /** True if this registry created a managed face for the family. */
+    isManaged(family: string): boolean;
+    /**
+     * Register a DOCUMENT-OWNED face from raw bytes (a deobfuscated DOCX-embedded font) and return a
+     * disposer that releases EXACTLY this face. Unlike {@link register} - the shared registrar for
+     * bundled and `fonts.add` faces, idempotent by URL source - every call here creates a distinct
+     * managed face, because the registry is shared per FontFaceSet across editors and two documents can
+     * embed the same family|weight|style with different (subset) bytes. Calling the returned disposer
+     * (on a document swap or editor teardown) removes only this face; the key's `hasFace` stays true
+     * while any other owner's face remains, so one document's cleanup never drops another document's or
+     * a customer's face. The face participates in `hasFace`/await like any managed face while it lives.
+     *
+     * Returns null where there is no DOM `FontFace` constructor / font set: embedded bytes cannot render
+     * without one, so the resolver correctly falls through to the bundled substitute. The disposer is
+     * idempotent (a second call returns false).
+     */
+    registerOwnedFace(descriptor: OwnedFaceDescriptor): (() => boolean) | null;
+    /**
+     * Last known status for a family, rolled up from its faces (and any legacy family-path
+     * load). Used by declared-font diagnostics (`buildFontReport`).
+     *
+     * A FAILED/TIMED_OUT/FALLBACK_USED face surfaces OVER a loaded sibling: if a document
+     * uses Arial regular (Liberation Sans loads) and Arial bold (its face 404s), the family
+     * reports the failure (`missing: true`), not a misleadingly-clean `loaded`. This is sound
+     * because the gate only awaits USED faces - an unused face stays `unloaded` (lowest
+     * priority), so a declared-but-unused family stays `unloaded` (not settled => not missing)
+     * and a used-but-failed face is never masked. Per-face detail is in `getFaceStatus` and
+     * the load summary's per-face counts.
+     */
+    getStatus(family: string): FontLoadStatus;
+    /**
+     * Is a face (family + weight + style) provided by a REGISTERED face that has not terminally failed
+     * to load? The face-availability oracle the face-aware resolver consults to answer "does the
+     * physical family actually provide this face?" - so a single-face substitute is never mapped onto a
+     * weight/style it lacks (which the painter would faux-synthesize). Covers bundled faces (registered
+     * by `installBundledSubstitutes`) and customer `fonts.add()` faces alike, because both register
+     * through {@link register}.
+     *
+     * Two deliberate exclusions:
+     *  - A merely-AWAITED face is not a provider. The oracle reads {@link #providerFaceKeys} (registration
+     *    only), NOT `#facesByFamily` (which the await path also populates for the status rollup), so an
+     *    `as_requested` family the gate once awaited does not masquerade as a registered face on the next
+     *    resolve.
+     *  - A face whose asset terminally FAILED to load is dropped, so the ladder steps down to the bundled
+     *    clone instead of committing forever to a broken registered face. `timed_out` is NOT excluded -
+     *    the late-load reflow still recovers a slow face, and demoting it would strand the real font.
+     *
+     * Distinct from {@link isAvailable}, which asks whether a face is LOADED right now.
+     */
+    hasFace(family: string, weight: '400' | '700', style: 'normal' | 'italic'): boolean;
+    /**
+     * Synchronous availability check: is a real face for this family loaded and
+     * usable in the set *right now*? Used by the gate's late-load handler to detect
+     * a face that finished after the first measure. Returns false where there is no
+     * font set.
+     */
+    isAvailable(family: string): boolean;
+    /**
+     * Await one family with a per-font timeout. Concurrent calls for the same
+     * family share the in-flight probe. A family already known to be `loaded`
+     * resolves immediately.
+     */
+    awaitFace(family: string, timeoutMs?: number): Promise<FontLoadResult>;
+    /**
+     * Await many families. The result preserves input order after de-duplication.
+     * This is the gate's primary entry point before a measurement pass.
+     */
+    awaitFaces(families: Iterable<string>, options?: {
+        timeoutMs?: number;
+    }): Promise<FontLoadResult[]>;
+    /**
+     * Required families as `{ family, status, ready }` handles. Reading `status` is
+     * synchronous; `ready` settles when the load resolves. Calling this starts the
+     * loads (idempotently).
+     */
+    getRequiredFaces(families: Iterable<string>, timeoutMs?: number): RequiredFace[];
+    /** Snapshot of every family the registry has seen and its status (diagnostics). */
+    getStates(): RegisteredFace[];
+    /** Last known status for a specific face (`unloaded` if never seen). */
+    getFaceStatus(request: FontFaceRequest): FontLoadStatus;
+    /**
+     * Await one specific face (family + weight + style) with a per-font timeout. Uses a
+     * weight/style-specific probe (`italic 700 16px "Carlito"`), so unlike {@link awaitFace}
+     * it loads the EXACT face the run needs, not just the regular one. Concurrent awaits of
+     * the same face share one probe; an already-`loaded` face resolves immediately.
+     */
+    awaitFaceRequest(request: FontFaceRequest, timeoutMs?: number): Promise<FontFaceLoadResult>;
+    /** Await many faces; result preserves input order after de-duplication by face key. */
+    awaitFaceRequests(requests: Iterable<FontFaceRequest>, options?: {
+        timeoutMs?: number;
+    }): Promise<FontFaceLoadResult[]>;
+}
+/**
+ * The single registry bound to a given font set. There is exactly one registry
+ * per `FontFaceSet`, so a document's load gate, its bundled faces, and the public
+ * `superdoc.fonts.*` surface all share load state.
+ *
+ * Callers MUST pass the same font set they watch for load events. A consumer that
+ * awaits one set but listens to another would never observe its fonts arriving -
+ * the exact failure mode for an editor inside an iframe whose `document.fonts`
+ * differs from the top window's. Pass `null` (no DOM) to get a shared DOM-less
+ * registry whose every await resolves to `fallback_used`.
+ */
+export declare function getFontRegistryFor(fontSet: FontSetLike | null, FontFaceCtor: FontFaceCtor | null): FontRegistry;
+/**
+ * The registry for the ambient `document.fonts`. Convenience for the common
+ * single-document case; iframe/embedded callers should use {@link getFontRegistryFor}
+ * with their own document's font set so the registry and the watched set match.
+ */
+export declare function getDefaultFontRegistry(): FontRegistry;
+/** Reset the cached DOM-less registry. Test-only; not part of the public surface. */
+export declare function __resetDefaultFontRegistry(): void;

package/dist/shared/font-system/src/report.d.ts

@@ -0,0 +1,98 @@
+import { type FaceKey, type FontResolutionReason, type FontResolver } from './resolver.js';
+import type { FontRegistry } from './registry.js';
+import type { GlyphException, SubstituteVerdict, SubstitutePolicyAction } from './substitution-evidence.js';
+import { type FontLoadStatus } from './types.js';
+/**
+ * docfonts fidelity evidence for a row where SuperDoc rendered the recommended substitute. Local types
+ * only (no `@docfonts/fallbacks` in the emitted `.d.ts`). `verdict` describes THIS row: the worst-face
+ * top-level verdict on family rows, the per-face verdict on face rows - so a consumer never reads
+ * `reason: 'bundled_substitute'` as a clean clone (Cambria -> Caladea is `visual_only` overall but
+ * `metric_safe` at Regular).
+ */
+export interface ResolvedFontEvidence {
+    /** docfonts evidence id, e.g. "cambria". */
+    evidenceId: string;
+    /** renderer-neutral action behind the substitution. */
+    policyAction: SubstitutePolicyAction;
+    /** fidelity verdict for this row (per-face on face rows; worst-face top-level on family rows). */
+    verdict: SubstituteVerdict;
+    /** advances preserve line breaks: metric_safe, near_metric, or monospace cell_width_only. */
+    lineBreakSafe: boolean;
+    /** named glyph-level divergences qualifying this row's face(s); omitted when none apply. */
+    glyphExceptions?: readonly GlyphException[];
+}
+/**
+ * One row of the font report: what the document asked for, what SuperDoc actually
+ * renders, why, whether it was ready before measurement, and what export preserves.
+ *
+ * This is the observable answer to "what font did SuperDoc use, and is that faithful?"
+ * e.g. requested Calibri -> rendered Carlito (bundled_substitute), loaded before measure,
+ * export still Calibri.
+ */
+export interface FontResolutionRecord {
+    /** The family the document requested (e.g. "Calibri"). */
+    logicalFamily: string;
+    /** The physical family actually measured and painted (e.g. "Carlito"). */
+    physicalFamily: string;
+    /** Why the physical family differs from the logical one. */
+    reason: FontResolutionReason;
+    /** Load state of the physical face at report time (`loaded` = ready before measurement). */
+    loadStatus: FontLoadStatus;
+    /** The family export writes back - always the logical name, so intent is preserved. */
+    exportFamily: string;
+    /**
+     * True when SuperDoc did NOT faithfully render the requested font with a metric-compatible face.
+     * Two ways this happens:
+     *   - a non-metric substitute rendered but is not faithful, so it is missing EVEN WHEN `loaded`:
+     *     `reason: 'category_fallback'` (wrong weight / reflows, e.g. Calibri Light -> Carlito), and on
+     *     face-level rows `reason: 'fallback_face_absent'` (the substitute lacks this weight/style).
+     *   - the physical face settled to a state other than `loaded`: a font with no known substitute
+     *     (`reason: 'as_requested'`, e.g. Aptos), or a substitute whose asset failed
+     *     (`reason: 'bundled_substitute'`, `loadStatus: 'failed'`, e.g. a 404ing `assetBaseUrl`).
+     * Transient states (`unloaded` / `loading`) are NOT missing, so an early `getReport()` pull before
+     * the gate settles does not over-report. `reason` and `loadStatus` distinguish the cause.
+     */
+    missing: boolean;
+    /**
+     * The specific face (weight/style) this row describes, present only on FACE-level rows
+     * ({@link buildFaceReport}); undefined on family-level rows ({@link buildFontReport}). A
+     * face-level row with `reason: 'fallback_face_absent'` means a substitute exists for the family
+     * but not for THIS face, so this face renders unsubstituted (non-metric) while other faces of the
+     * same family may substitute. Optional + additive, so existing consumers are unaffected.
+     */
+    face?: {
+        weight: '400' | '700';
+        style: 'normal' | 'italic';
+    };
+    /**
+     * docfonts fidelity evidence, present ONLY when SuperDoc rendered the recommended substitute
+     * (`reason` `bundled_substitute` or `category_fallback`). Lets a consumer distinguish a clean clone
+     * (Calibri -> Carlito, `metric_safe`) from a qualified one (Cambria -> Caladea, `visual_only`)
+     * instead of treating every `bundled_substitute` alike. Optional + additive. See {@link ResolvedFontEvidence}.
+     */
+    evidence?: ResolvedFontEvidence;
+}
+/**
+ * Build the per-font resolution report for a document's logical fonts. Pure given the
+ * resolver map and the registry's current load state, so it reflects exactly what was
+ * resolved and loaded for the last measurement pass.
+ *
+ * This is the diagnostics seam: the public `superdoc.fonts.getReport()` (T7) and the
+ * upgraded `onFontsResolved` payload are thin wrappers over this - they must not compute
+ * resolution independently, or the report could disagree with what actually painted.
+ */
+export declare function buildFontReport(logicalFamilies: Iterable<string>, registry: FontRegistry, resolver?: FontResolver): FontResolutionRecord[];
+/** One used (logical family + face) the document actually renders, for the face-level report. */
+export interface UsedFace extends FaceKey {
+    logicalFamily: string;
+}
+/**
+ * Face-level resolution report: one row per (logical family, face) the document RENDERS, resolved
+ * FACE-aware so a substitute that lacks a face is reported `fallback_face_absent` unless docfonts
+ * explicitly names a synthetic source face. The caller passes the used faces (the runtime builds them
+ * from the load planner, which carries logical family + weight/style); `registry.hasFace` is the
+ * face-availability oracle. Unlike {@link buildFontReport} (one row per declared family), this
+ * explains per-face fidelity, e.g. "Baskerville Regular -> Bacasime (custom_mapping); Baskerville Bold
+ * -> fallback_face_absent". Deduped by logical family + weight + style.
+ */
+export declare function buildFaceReport(usedFaces: Iterable<UsedFace>, registry: FontRegistry, resolver?: FontResolver): FontResolutionRecord[];