@docfonts/fallbacks 0.1.0 → 0.3.0

package/README.md

@@ -2,9 +2,9 @@
 
 Document font substitution, measured.
 
-Measured open-font fallbacks for proprietary document fonts (Office / Word / DOCX), as a tiny runtime data package. It carries the structured substitution evidence plus one asset-aware lookup, so a renderer can map a requested proprietary font to an open one without hand-copying tables, and without routing to a font it does not bundle.
+Measured open-font fallbacks for proprietary document fonts. Use it to decide whether a requested document font can render with an open family you actually ship.
 
-It ships no fonts and no proprietary binaries: only the measured evidence (which open family stands in, the verdict, the advance delta, the license id, and a stable evidence id).
+It ships no fonts and no proprietary binaries. It ships decisions: the recommended open family when one exists, the fidelity verdict, and the honest cases where no open family should be used.
 
 ## Install
 
@@ -12,46 +12,101 @@ It ships no fonts and no proprietary binaries: only the measured evidence (which
 npm install @docfonts/fallbacks
 ```
 
-## Usage
+ESM-only. Use `import`, or let your bundler handle it. CommonJS `require()` is not supported.
 
-`getFallback` answers "what does docfonts recommend for this family?". Pass `hasFamily` to keep it to fonts you actually bundle:
+## Render A Font
+
+Use `getRenderableFallback` when you need one font family to render now. Pass `canRenderFamily` so docfonts only returns families your app can load.
 
 ```ts
-import { getFallback } from "@docfonts/fallbacks";
+import { getRenderableFallback } from "@docfonts/fallbacks";
+
+const fallback = getRenderableFallback("Helvetica", {
+  canRenderFamily: (family) => bundledFamilies.has(family),
+});
 
-getFallback("Helvetica", { hasFamily: (f) => bundled.has(f) });
-// { family: "Liberation Sans", action: "substitute", verdict: "metric_safe", faithful: true, evidenceId: "helvetica" }
+// { substituteFamily: "Liberation Sans", policyAction: "substitute", verdict: "metric_safe", lineBreakSafe: true, evidenceId: "helvetica" }
 ```
 
-`deriveFallbackMap` builds the substitute map you wire into a resolver. `hasFamily` is required here: a render map never includes a substitute whose font you cannot load.
+The result is `null` when there is nothing renderable from your available assets. Use `getFallbackDecision` when you need to know why.
+
+## Explain A Decision
+
+Use `getFallbackDecision` for UI, diagnostics, and reporting. It distinguishes known fonts with no recommended fallback from fonts docfonts has never seen.
+
+```ts
+import { getFallbackDecision } from "@docfonts/fallbacks";
+
+getFallbackDecision("Aptos");
+// { kind: "customer_supplied", evidenceId: "aptos" }
+
+getFallbackDecision("Tahoma");
+// { kind: "no_recommended_fallback", evidenceId: "tahoma" }
+
+getFallbackDecision("Made Up Font");
+// { kind: "unknown" }
+
+getFallbackDecision("Georgia", {
+  canRenderFamily: (family) => bundledFamilies.has(family),
+});
+// { kind: "asset_missing", substituteFamily: "Gelasio", verdict: "near_metric", evidenceId: "georgia" }
+```
+
+Decision kinds:
+
+- `fallback` - render the returned `substituteFamily`.
+- `asset_missing` - docfonts has a fallback, but your app does not load that family.
+- `face_missing` - (face-aware lookups only) the family has a substitute, but not for the requested face. Route that face through your absence handling; do not substitute it.
+- `no_recommended_fallback` - docfonts knows the font but recommends no renderable open family.
+- `customer_supplied` - the real font should come from the customer or environment.
+- `preserve_only` - keep the original family name. Do not substitute.
+- `unknown` - docfonts has no evidence for this family.
+
+## Create A Resolver Map
+
+Use `createFallbackMap` when wiring a resolver. `canRenderFamily` is required because a resolver map must never point at fonts you cannot load.
 
 ```ts
-import { deriveFallbackMap } from "@docfonts/fallbacks";
+import { createFallbackMap, normalizeFamilyName } from "@docfonts/fallbacks";
 
-const map = deriveFallbackMap({ hasFamily: (f) => bundled.has(f) });
-// { helvetica: { family: "Liberation Sans", ... }, calibri: { ... }, ... }
-// Rows whose family you do not bundle are left out, not routed to a missing asset.
+const map = createFallbackMap({
+  canRenderFamily: (family) => bundledFamilies.has(family),
+});
+
+map[normalizeFamilyName("Times New Roman")]; // { substituteFamily: "Liberation Serif", ... }
 ```
 
-Both resolve to `null` (or omit the row) when docfonts has no row, the recommendation is "no open font stands in", or you do not ship the physical family.
+Keys are normalized. Use `normalizeFamilyName` for lookups. Rows whose substitute family is not available are omitted. Each entry carries `faces`: a Regular-only entry is only safe in a **face-aware** resolver (one that checks `faces` or uses `getRenderableFallbackForFace`), since applying it to bold/italic would route a face the substitute does not provide.
 
 ## What the fields mean
 
-- `family` - the open family to render in place of the requested one.
-- `action` - `substitute` (a measured metric match) or `category_fallback` (right letterforms, lower fidelity).
-- `verdict` - the measured fidelity, from a fixed taxonomy (`metric_safe`, `near_metric`, `cell_width_only`, `visual_only`, ...). The headline rolls up to the worst face.
-- `faithful` - a coarse "good enough for line-break fidelity" flag (`metric_safe` or `near_metric`). Not a claim of an exact clone; read `verdict` for the tier.
-- `evidenceId` - the stable id for the reviewed evidence row.
+- `substituteFamily` - the open family to render in place of the requested one.
+- `policyAction` - what a renderer should do, not a quality claim. Use `verdict` for fidelity.
+- `verdict` - the measured fidelity. Examples: `metric_safe`, `near_metric`, `cell_width_only`, `visual_only`.
+- `lineBreakSafe` - true when advances preserve line breaks: `metric_safe`, `near_metric`, or monospace `cell_width_only`.
+- `faces` - reviewed face coverage for this evidence row. If any face is `true`, respect it as face-scoped coverage (a row can be Regular-only). If all faces are `false`, the row is **not** face-scoped (e.g. a category fallback whose physical font does have faces) and the face-aware helpers treat it as renderable for any face.
+- `evidenceId` - the stable id for the reviewed evidence row; look the full row up in `SUBSTITUTION_EVIDENCE`.
 
-The full structured rows are exported as `SUBSTITUTION_EVIDENCE` (faces, per-face verdicts, glyph exceptions) for richer reporting. Face-level routing stays yours: `getFallback` answers "which family", not "which face".
+`cell_width_only` keeps monospace advances stable, but glyph shapes can still differ. A `substitute` can still have a lower-fidelity `verdict` when one face or glyph is qualified. The verdict is the fidelity signal.
 
-## Provenance
+## Face-aware routing (Regular-only substitutes)
 
-The data comes from reviewed docfonts evidence. Measurements are produced against licensed originals,
-but this package distributes no proprietary binaries or raw proprietary metrics.
+Some substitutes provide only some faces - e.g. Baskerville Old Face -> Bacasime Antique is Regular-only. The family-level helpers above answer "which family", and every result carries `faces`, so a resolver must route per-face. The face-aware helpers do it for you:
 
-Built by the team behind SuperDoc. Standalone and neutral.
+```ts
+import { getRenderableFallbackForFace } from "@docfonts/fallbacks";
+const opts = { canRenderFamily: (family) => bundledFamilies.has(family) };
 
-## License
+getRenderableFallbackForFace("Baskerville Old Face", "regular", opts)?.substituteFamily; // "Bacasime Antique"
+getRenderableFallbackForFace("Baskerville Old Face", "bold", opts);                       // null (Regular-only)
+```
 
-MIT
+`getFallbackDecisionForFace(family, face, options)` reports the reason - `face_missing` when the substitute exists but lacks that face. A covered face carries its OWN verdict, not the family's worst-face rollup (e.g. `Cambria` regular is `metric_safe` even though the family rolls up to `visual_only`).
+
+The full structured rows are exported as `SUBSTITUTION_EVIDENCE` for richer reporting (faces, per-face verdicts, glyph exceptions).
+
+## Provenance
+
+The data comes from reviewed docfonts evidence. Measurements are produced against licensed originals, but this package distributes no proprietary binaries or raw proprietary metrics.
+
+Built by the team behind SuperDoc. Standalone and neutral.

package/dist/data.d.ts

@@ -1,2 +1,2 @@
-import type { SubstitutionEvidence } from "./types";
+import type { SubstitutionEvidence } from "./types.js";
 export declare const SUBSTITUTION_EVIDENCE: readonly SubstitutionEvidence[];

package/dist/fallbacks.d.ts

@@ -1,27 +1,46 @@
-import type { FontFallback } from "./types";
+import type { FaceSlot, FallbackDecision, FontFallback } from "./types.js";
 /** Reports whether the consumer can actually render (i.e. bundles the asset for) a physical family. */
-export type HasFamily = (family: string) => boolean;
-/** Options for {@link getFallback}. `hasFamily` is OPTIONAL here - omit it to get the raw recommendation. */
-export interface FallbackOptions {
-    /**
-     * When given, a row whose `physicalFamily` is not available resolves to null - the row stays inert
-     * until the consumer bundles it. When omitted, every row with a physical family is considered present.
-     */
-    hasFamily?: HasFamily;
+export type CanRenderFamily = (family: string) => boolean;
+/** Options for {@link getRenderableFallback} and {@link createFallbackMap}: a render map must be asset-safe. */
+export interface RenderableFallbackOptions {
+    canRenderFamily: CanRenderFamily;
 }
-/** Options for {@link deriveFallbackMap}. `hasFamily` is REQUIRED - a render map must be asset-safe. */
-export interface FallbackMapOptions {
-    hasFamily: HasFamily;
+/** Options for {@link getFallbackDecision}. `canRenderFamily` is optional - omit it for the raw decision. */
+export interface FallbackDecisionOptions {
+    canRenderFamily?: CanRenderFamily;
 }
+/** Normalize a family name to a lookup key: trim, strip surrounding quotes, lowercase (CSS-name safe). */
+export declare function normalizeFamilyName(name: string): string;
 /**
- * The open fallback for a requested font family, or null when docfonts has no row, the row recommends
- * no substitute, or the consumer does not ship the physical family. Case- and quote-insensitive.
+ * The full, honest outcome for a requested family: a discriminated union (see {@link FallbackDecision}).
+ * Distinguishes an unknown font from a measured "no open substitute", a substitute you do not bundle,
+ * and the deliberate non-substitution policies. Case- and quote-insensitive.
  */
-export declare function getFallback(logicalFamily: string, options?: FallbackOptions): FontFallback | null;
+export declare function getFallbackDecision(family: string, options?: FallbackDecisionOptions): FallbackDecision;
 /**
- * The renderer's substitute map: every fallback the consumer can actually render, keyed by the
- * normalized (lowercased) logical family. `hasFamily` is REQUIRED - rows whose physical family the
- * consumer does not bundle are excluded, so the map is safe to wire straight into a resolver. The keys
- * are exactly the families it should remap. For the un-gated single recommendation, use {@link getFallback}.
+ * The open family to render for a requested font, or null when there is nothing the consumer can render
+ * (no row, no open substitute, a deliberate non-substitution policy, or a substitute it does not
+ * bundle). For the reasons behind a null - to report them in a UI - use {@link getFallbackDecision}.
  */
-export declare function deriveFallbackMap(options: FallbackMapOptions): Record<string, FontFallback>;
+export declare function getRenderableFallback(family: string, options: RenderableFallbackOptions): FontFallback | null;
+/**
+ * Face-aware outcome for a requested family + RIBBI face. Like {@link getFallbackDecision} but adds
+ * `face_missing` when the substitute exists yet does not provide that face (a Regular-only row asked
+ * for bold/italic). A covered face's fallback carries that face's own verdict. Case- and quote-insensitive.
+ */
+export declare function getFallbackDecisionForFace(family: string, face: FaceSlot, options?: FallbackDecisionOptions): FallbackDecision;
+/**
+ * The open family to render for a requested font AND a specific face, or null when that face has no
+ * renderable substitute (face not covered, no row, a non-substitution policy, or not bundled). This is
+ * the face-SAFE lookup: a Regular-only substitute returns null for bold/italic instead of being routed
+ * to a face it does not have. Use {@link getFallbackDecisionForFace} to report the reason.
+ */
+export declare function getRenderableFallbackForFace(family: string, face: FaceSlot, options: RenderableFallbackOptions): FontFallback | null;
+/**
+ * A family-level substitute map: every fallback the consumer can render, keyed by the normalized
+ * (lowercased) logical family - normalize lookups with {@link normalizeFamilyName}. Only renderable
+ * rows are included. Each entry carries `faces`; a face-scoped (e.g. Regular-only) row is only safe in
+ * a FACE-AWARE resolver - one that checks `faces` or uses {@link getRenderableFallbackForFace} - since
+ * applying a Regular-only entry to bold/italic would route a face the substitute does not provide.
+ */
+export declare function createFallbackMap(options: RenderableFallbackOptions): Record<string, FontFallback>;

package/dist/fallbacks.js

@@ -1,21 +1,24 @@
 /**
- * Asset-aware fallback helpers. `getFallback` can inspect the raw recommendation; `deriveFallbackMap`
- * requires `hasFamily` because a renderer map must not include fonts the consumer cannot load. Face
- * routing stays consumer-owned; this package answers which family, not which face.
+ * Fallback lookups over the reviewed evidence:
+ *   - getRenderableFallback / getFallbackDecision - family-level ("which family", + the full outcome).
+ *   - getRenderableFallbackForFace / getFallbackDecisionForFace - face-SAFE: a Regular-only substitute
+ *     returns null / `face_missing` for bold/italic instead of being wrongly routed to a face it lacks.
+ *   - createFallbackMap - a family-level resolver map (asset-gated). Each entry carries `faces`, so a
+ *     consumer can route per-face; for Regular-only rows it MUST, or use the face-aware lookups.
  */
-import { SUBSTITUTION_EVIDENCE } from "./data";
-/** The two metric-grade bands. A substitution in either is line-break faithful; everything else is not. */
-const FAITHFUL_VERDICTS = new Set([
+import { SUBSTITUTION_EVIDENCE } from "./data.js";
+/**
+ * Verdicts whose advances preserve line breaks: the proportional metric-grade bands, plus
+ * cell_width_only (a monospace whose cell width - and therefore every advance - matches). Glyph shapes
+ * may still differ (read `verdict`); line breaks do not move.
+ */
+const LINE_BREAK_SAFE_VERDICTS = new Set([
     "metric_safe",
     "near_metric",
-]);
-/** Actions that mean "render this physical family". */
-const RENDERABLE_ACTIONS = new Set([
-    "substitute",
-    "category_fallback",
+    "cell_width_only",
 ]);
 /** Normalize a family name to a lookup key: trim, strip surrounding quotes, lowercase (CSS-name safe). */
-function normalizeFamily(name) {
+export function normalizeFamilyName(name) {
     return name
         .trim()
         .replace(/^['"]+|['"]+$/g, "")
@@ -23,43 +26,133 @@ function normalizeFamily(name) {
         .toLowerCase();
 }
 /** Evidence rows indexed by normalized logical family, built once. */
-const BY_LOGICAL = new Map(SUBSTITUTION_EVIDENCE.map((row) => [normalizeFamily(row.logicalFamily), row]));
-/** Project a row to a FontFallback, or null when it offers nothing the consumer can render. */
-function toFallback(row, hasFamily) {
-    if (row.physicalFamily === null)
-        return null;
-    if (!RENDERABLE_ACTIONS.has(row.policyAction))
-        return null;
-    if (hasFamily && !hasFamily(row.physicalFamily))
-        return null;
+const BY_LOGICAL = new Map(SUBSTITUTION_EVIDENCE.map((row) => [
+    normalizeFamilyName(row.logicalFamily),
+    row,
+]));
+/**
+ * Build the FontFallback for a row known to carry a renderable physical family. `verdict` is passed in
+ * so a face-aware caller can supply the per-face verdict (faceVerdicts[face]) instead of the worst-face
+ * top-level one - e.g. Cambria regular is metric_safe even though the family rolls up to visual_only.
+ */
+function buildFallback(row, physicalFamily, verdict) {
     return {
-        family: row.physicalFamily,
-        action: row.policyAction,
-        verdict: row.verdict,
-        faithful: FAITHFUL_VERDICTS.has(row.verdict),
+        substituteFamily: physicalFamily,
+        policyAction: row.policyAction,
+        verdict,
+        lineBreakSafe: LINE_BREAK_SAFE_VERDICTS.has(verdict),
+        faces: row.faces,
         evidenceId: row.evidenceId,
     };
 }
+/** Decide a single row against the consumer's asset availability. Pure. */
+function decideRow(row, canRenderFamily) {
+    const { policyAction, physicalFamily, verdict, evidenceId } = row;
+    // Deliberate non-substitution policies first: nothing renders in the original's place.
+    if (policyAction === "preserve_only")
+        return { kind: "preserve_only", evidenceId };
+    if (policyAction === "customer_supplied")
+        return { kind: "customer_supplied", evidenceId };
+    // substitute / category_fallback with no named open family: docfonts knows the font but recommends
+    // no renderable family - distinct from the `no_substitute` verdict (read the row for that nuance).
+    if (physicalFamily === null)
+        return { kind: "no_recommended_fallback", evidenceId };
+    // Named substitute the consumer does not bundle: surfaced so a UI can say which font to add.
+    if (canRenderFamily && !canRenderFamily(physicalFamily))
+        return {
+            kind: "asset_missing",
+            substituteFamily: physicalFamily,
+            verdict,
+            evidenceId,
+        };
+    return {
+        kind: "fallback",
+        fallback: buildFallback(row, physicalFamily, verdict),
+    };
+}
+/** True when a row actually scopes faces (any RIBBI face marked covered). An all-false `faces` means
+ *  the row is NOT face-scoped - e.g. a category fallback whose physical font does have faces - so it
+ *  must not be gated per-face, only a measured per-face substitute (Baskerville Regular-only) is. */
+function isFaceScoped(row) {
+    const f = row.faces;
+    return f.regular || f.bold || f.italic || f.boldItalic;
+}
+/**
+ * Face-aware variant of {@link decideRow}: same family-level outcome, but when the family HAS a
+ * renderable substitute AND the row is face-scoped, gate on whether it provides the requested `face`.
+ * A face a face-scoped substitute does not cover yields `face_missing` (route it through absence
+ * handling); a covered face yields a fallback carrying that face's own verdict. A NON-face-scoped row
+ * (category fallback, all-false `faces`) renders for any face - it never becomes face_missing.
+ */
+function decideRowForFace(row, face, canRenderFamily) {
+    const base = decideRow(row, canRenderFamily);
+    // Non-fallback outcomes (asset_missing / no_recommended_fallback / policy) do not depend on the face.
+    if (base.kind !== "fallback")
+        return base;
+    if (isFaceScoped(row) && !row.faces[face])
+        return {
+            kind: "face_missing",
+            substituteFamily: base.fallback.substituteFamily,
+            evidenceId: row.evidenceId,
+        };
+    const faceVerdict = row.faceVerdicts?.[face] ?? row.verdict;
+    return {
+        kind: "fallback",
+        fallback: buildFallback(row, base.fallback.substituteFamily, faceVerdict),
+    };
+}
+/**
+ * The full, honest outcome for a requested family: a discriminated union (see {@link FallbackDecision}).
+ * Distinguishes an unknown font from a measured "no open substitute", a substitute you do not bundle,
+ * and the deliberate non-substitution policies. Case- and quote-insensitive.
+ */
+export function getFallbackDecision(family, options = {}) {
+    const row = BY_LOGICAL.get(normalizeFamilyName(family));
+    return row ? decideRow(row, options.canRenderFamily) : { kind: "unknown" };
+}
+/**
+ * The open family to render for a requested font, or null when there is nothing the consumer can render
+ * (no row, no open substitute, a deliberate non-substitution policy, or a substitute it does not
+ * bundle). For the reasons behind a null - to report them in a UI - use {@link getFallbackDecision}.
+ */
+export function getRenderableFallback(family, options) {
+    const decision = getFallbackDecision(family, options);
+    return decision.kind === "fallback" ? decision.fallback : null;
+}
+/**
+ * Face-aware outcome for a requested family + RIBBI face. Like {@link getFallbackDecision} but adds
+ * `face_missing` when the substitute exists yet does not provide that face (a Regular-only row asked
+ * for bold/italic). A covered face's fallback carries that face's own verdict. Case- and quote-insensitive.
+ */
+export function getFallbackDecisionForFace(family, face, options = {}) {
+    const row = BY_LOGICAL.get(normalizeFamilyName(family));
+    return row
+        ? decideRowForFace(row, face, options.canRenderFamily)
+        : { kind: "unknown" };
+}
 /**
- * The open fallback for a requested font family, or null when docfonts has no row, the row recommends
- * no substitute, or the consumer does not ship the physical family. Case- and quote-insensitive.
+ * The open family to render for a requested font AND a specific face, or null when that face has no
+ * renderable substitute (face not covered, no row, a non-substitution policy, or not bundled). This is
+ * the face-SAFE lookup: a Regular-only substitute returns null for bold/italic instead of being routed
+ * to a face it does not have. Use {@link getFallbackDecisionForFace} to report the reason.
  */
-export function getFallback(logicalFamily, options = {}) {
-    const row = BY_LOGICAL.get(normalizeFamily(logicalFamily));
-    return row ? toFallback(row, options.hasFamily) : null;
+export function getRenderableFallbackForFace(family, face, options) {
+    const decision = getFallbackDecisionForFace(family, face, options);
+    return decision.kind === "fallback" ? decision.fallback : null;
 }
 /**
- * The renderer's substitute map: every fallback the consumer can actually render, keyed by the
- * normalized (lowercased) logical family. `hasFamily` is REQUIRED - rows whose physical family the
- * consumer does not bundle are excluded, so the map is safe to wire straight into a resolver. The keys
- * are exactly the families it should remap. For the un-gated single recommendation, use {@link getFallback}.
+ * A family-level substitute map: every fallback the consumer can render, keyed by the normalized
+ * (lowercased) logical family - normalize lookups with {@link normalizeFamilyName}. Only renderable
+ * rows are included. Each entry carries `faces`; a face-scoped (e.g. Regular-only) row is only safe in
+ * a FACE-AWARE resolver - one that checks `faces` or uses {@link getRenderableFallbackForFace} - since
+ * applying a Regular-only entry to bold/italic would route a face the substitute does not provide.
  */
-export function deriveFallbackMap(options) {
+export function createFallbackMap(options) {
     const out = {};
     for (const [key, row] of BY_LOGICAL) {
-        const fallback = toFallback(row, options.hasFamily);
-        if (fallback)
-            out[key] = fallback;
+        const decision = decideRow(row, options.canRenderFamily);
+        if (decision.kind === "fallback")
+            out[key] = decision.fallback;
     }
     return out;
 }

package/dist/index.d.ts

@@ -2,6 +2,6 @@
  * Runtime fallback evidence and asset-aware lookup helpers. No font parser, research data, or runtime
  * dependency.
  */
-export { SUBSTITUTION_EVIDENCE } from "./data";
-export { deriveFallbackMap, type FallbackMapOptions, type FallbackOptions, getFallback, type HasFamily, } from "./fallbacks";
-export type { AdvanceDelta, FaceCoverage, FaceSlot, FontFallback, GlyphException, PolicyAction, SubstituteGates, SubstitutionEvidence, Verdict, } from "./types";
+export { SUBSTITUTION_EVIDENCE } from "./data.js";
+export { type CanRenderFamily, createFallbackMap, type FallbackDecisionOptions, getFallbackDecision, getFallbackDecisionForFace, getRenderableFallback, getRenderableFallbackForFace, normalizeFamilyName, type RenderableFallbackOptions, } from "./fallbacks.js";
+export type { AdvanceDelta, FaceCoverage, FaceSlot, FallbackDecision, FontFallback, GlyphException, PolicyAction, SubstituteGates, SubstitutionEvidence, Verdict, } from "./types.js";

package/dist/index.js

@@ -2,5 +2,5 @@
  * Runtime fallback evidence and asset-aware lookup helpers. No font parser, research data, or runtime
  * dependency.
  */
-export { SUBSTITUTION_EVIDENCE } from "./data";
-export { deriveFallbackMap, getFallback, } from "./fallbacks";
+export { SUBSTITUTION_EVIDENCE } from "./data.js";
+export { createFallbackMap, getFallbackDecision, getFallbackDecisionForFace, getRenderableFallback, getRenderableFallbackForFace, normalizeFamilyName, } from "./fallbacks.js";

package/dist/types.d.ts

@@ -38,7 +38,8 @@ export interface GlyphException {
     note: string;
 }
 /**
- * One logical font's structured fallback evidence.
+ * One logical font's structured fallback evidence. The raw rows are exported as
+ * {@link SUBSTITUTION_EVIDENCE} for reporting; the helpers project the renderer-relevant fields.
  */
 export interface SubstitutionEvidence {
     /** docfonts evidence id, e.g. "cambria". */
@@ -65,24 +66,72 @@ export interface SubstitutionEvidence {
     exportRule: "preserve_original_name";
 }
 /**
- * The ergonomic result of {@link getFallback}: the single decision a renderer needs to act on - which
- * physical family to render, how it was chosen, and whether it is metric-faithful. The full structured
- * row stays available via {@link SUBSTITUTION_EVIDENCE} for richer reporting.
+ * A resolved fallback: which open family to render, how it was chosen, and whether advances preserve
+ * line breaks. The full structured row stays available via {@link SUBSTITUTION_EVIDENCE} for reporting.
  */
 export interface FontFallback {
-    /** the physical family to render in place of the requested font. */
-    family: string;
-    /** how it was chosen: a metric substitute vs a same-category visual fallback. */
-    action: PolicyAction;
+    /** the open family to render in place of the requested font. */
+    substituteFamily: string;
+    /**
+     * What a renderer should DO, independent of fidelity: `substitute` = render the named open family;
+     * `category_fallback` = render a lower-fidelity same-category family. NOT a quality claim - a
+     * `substitute` can still be top-level `visual_only` (e.g. Cambria). Read `verdict` for fidelity.
+     */
+    policyAction: PolicyAction;
     /** the worst-face fidelity verdict behind the choice. */
     verdict: Verdict;
     /**
-     * Coarse "good enough for line-break fidelity" flag: true for the metric-grade bands (verdict
-     * metric_safe or near_metric), false otherwise. NOT a claim of a perfect/exact clone - near_metric
-     * drifts a few glyphs, and a row can roll up to a worse top-level verdict because of one face (see
-     * Cambria). Read `verdict` (and the row's `faceVerdicts`) for the precise tier.
+     * Coarse "advances preserve line breaks" flag: true for metric_safe, near_metric, or monospace
+     * cell_width_only (cell width, and so every advance, matches). NOT a claim of a perfect/exact clone -
+     * near_metric drifts a few glyphs, cell_width_only keeps the advances but not the glyph shapes, and a
+     * row can roll up to a worse top-level verdict because of one face (see Cambria). Read `verdict` (and
+     * the row's `faceVerdicts`) for the precise tier.
      */
-    faithful: boolean;
-    /** stable reviewed-evidence id. */
+    lineBreakSafe: boolean;
+    /**
+     * Reviewed face coverage: which RIBBI faces this substitute is PROVEN to supply. A renderer MUST
+     * respect a face-scoped row: it can be Regular-only (e.g. Baskerville -> Bacasime, Cooper Black ->
+     * Caprasimo), and routing bold/italic to a face it lacks is wrong. NOTE: an all-false `faces` means
+     * the row is NOT face-scoped (e.g. a category fallback, whose physical font does have faces), NOT
+     * that the font has no faces - such rows render for any face. The face-aware helpers
+     * ({@link getRenderableFallbackForFace}) encode this rule for you.
+     */
+    faces: FaceCoverage;
+    /** stable reviewed-evidence id; look the full row up in {@link SUBSTITUTION_EVIDENCE}. */
     evidenceId: string;
 }
+/**
+ * The full, honest outcome of a fallback lookup. A discriminated union so a consumer can tell apart
+ * cases that a bare `FontFallback | null` collapses: docfonts has never heard of the font (`unknown`)
+ * vs knows it but recommends no renderable family (`no_recommended_fallback`), the substitute exists
+ * but the consumer does not bundle it (`asset_missing`), and the deliberate non-substitution policies
+ * (`preserve_only`, `customer_supplied`). The face-aware lookups add `face_missing`: a substitute is
+ * recommended for the family but does NOT provide the requested face. `evidenceId` on the terminal
+ * kinds points back into {@link SUBSTITUTION_EVIDENCE} for the full row (verdict, faces, ...).
+ */
+export type FallbackDecision = {
+    kind: "fallback";
+    fallback: FontFallback;
+} | {
+    kind: "asset_missing";
+    substituteFamily: string;
+    verdict: Verdict;
+    evidenceId: string;
+} | {
+    /** the family has a renderable substitute, but it does not provide the requested face - route
+     *  this face through face-aware absence handling, do NOT substitute it. */
+    kind: "face_missing";
+    substituteFamily: string;
+    evidenceId: string;
+} | {
+    kind: "no_recommended_fallback";
+    evidenceId: string;
+} | {
+    kind: "customer_supplied";
+    evidenceId: string;
+} | {
+    kind: "preserve_only";
+    evidenceId: string;
+} | {
+    kind: "unknown";
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docfonts/fallbacks",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Measured open-font fallbacks for proprietary document fonts.",
   "license": "MIT",
   "type": "module",