@docfonts/fallbacks 0.2.0 → 0.4.0

package/README.md

@@ -56,6 +56,7 @@ 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.
@@ -75,7 +76,7 @@ const map = createFallbackMap({
 map[normalizeFamilyName("Times New Roman")]; // { substituteFamily: "Liberation Serif", ... }
 ```
 
-Keys are normalized. Use `normalizeFamilyName` for lookups. Rows whose substitute family is not available are omitted.
+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
 
@@ -83,11 +84,27 @@ Keys are normalized. Use `normalizeFamilyName` for lookups. Rows whose substitut
 - `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`.
+- `glyphExceptions` - named glyph-level divergences that qualify this fallback (e.g. one codepoint reflows), or omitted when none. A family lookup carries all of the row's; a face lookup (`getRenderableFallbackForFace`) carries only that face's, so Cambria Regular shows none while Bold Italic shows its grave-accent exception.
 
 `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.
 
-The full structured rows are exported as `SUBSTITUTION_EVIDENCE` for richer reporting, including faces, per-face verdicts, and glyph exceptions. Face-level routing stays yours: these helpers answer "which family", not "which face".
+## Face-aware routing (Regular-only substitutes)
+
+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:
+
+```ts
+import { getRenderableFallbackForFace } from "@docfonts/fallbacks";
+const opts = { canRenderFamily: (family) => bundledFamilies.has(family) };
+
+getRenderableFallbackForFace("Baskerville Old Face", "regular", opts)?.substituteFamily; // "Bacasime Antique"
+getRenderableFallbackForFace("Baskerville Old Face", "bold", opts);                       // null (Regular-only)
+```
+
+`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
 

package/dist/fallbacks.d.ts

@@ -1,4 +1,4 @@
-import type { FallbackDecision, FontFallback } from "./types.js";
+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 CanRenderFamily = (family: string) => boolean;
 /** Options for {@link getRenderableFallback} and {@link createFallbackMap}: a render map must be asset-safe. */
@@ -24,8 +24,23 @@ export declare function getFallbackDecision(family: string, options?: FallbackDe
  */
 export declare function getRenderableFallback(family: string, options: RenderableFallbackOptions): FontFallback | null;
 /**
- * The renderer's substitute map: every fallback the consumer can actually render, keyed by the
- * normalized (lowercased) logical family - normalize lookups with {@link normalizeFamilyName}. Only
- * `kind: "fallback"` rows are included, so the map is safe to wire straight into a resolver.
+ * 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,9 +1,10 @@
 /**
- * Fallback lookups over the reviewed evidence. Three intents:
- *   - getRenderableFallback - "I need a family to render now" (asset-gated, returns a family or null).
- *   - getFallbackDecision   - "I need diagnostics / UI / reporting" (the full honest outcome).
- *   - createFallbackMap      - "I need a resolver map" (asset-gated, render-only rows).
- * Face routing stays consumer-owned: these answer 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.js";
 /**
@@ -29,14 +30,31 @@ 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. */
-function buildFallback(row, physicalFamily) {
+/**
+ * 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.
+ * `faceSlot` (a face lookup) scopes the glyph exceptions to that face; omitting it (a family lookup)
+ * carries all of the row's. Empty exception sets are dropped so the field is present only when it bites.
+ */
+function buildFallback(row, physicalFamily, verdict, faceSlot) {
+    // Always hand back a FRESH array - filter() already copies; the family path must copy too, or a
+    // consumer mutating it would corrupt the shared evidence row for later lookups.
+    const glyphExceptions = faceSlot
+        ? row.glyphExceptions?.filter((g) => g.slot === faceSlot)
+        : row.glyphExceptions
+            ? [...row.glyphExceptions]
+            : undefined;
     return {
         substituteFamily: physicalFamily,
         policyAction: row.policyAction,
-        verdict: row.verdict,
-        lineBreakSafe: LINE_BREAK_SAFE_VERDICTS.has(row.verdict),
+        verdict,
+        lineBreakSafe: LINE_BREAK_SAFE_VERDICTS.has(verdict),
+        faces: row.faces,
         evidenceId: row.evidenceId,
+        ...(glyphExceptions && glyphExceptions.length > 0
+            ? { glyphExceptions }
+            : {}),
     };
 }
 /** Decide a single row against the consumer's asset availability. Pure. */
@@ -59,7 +77,41 @@ function decideRow(row, canRenderFamily) {
             verdict,
             evidenceId,
         };
-    return { kind: "fallback", fallback: buildFallback(row, physicalFamily) };
+    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, face),
+    };
 }
 /**
  * The full, honest outcome for a requested family: a discriminated union (see {@link FallbackDecision}).
@@ -80,9 +132,32 @@ export function getRenderableFallback(family, 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 - normalize lookups with {@link normalizeFamilyName}. Only
- * `kind: "fallback"` rows are included, so the map is safe to wire straight into a resolver.
+ * 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 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 getRenderableFallbackForFace(family, face, options) {
+    const decision = getFallbackDecisionForFace(family, face, options);
+    return decision.kind === "fallback" ? decision.fallback : 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 function createFallbackMap(options) {
     const out = {};

package/dist/index.d.ts

@@ -3,5 +3,5 @@
  * dependency.
  */
 export { SUBSTITUTION_EVIDENCE } from "./data.js";
-export { type CanRenderFamily, createFallbackMap, type FallbackDecisionOptions, getFallbackDecision, getRenderableFallback, normalizeFamilyName, type RenderableFallbackOptions, } from "./fallbacks.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

@@ -3,4 +3,4 @@
  * dependency.
  */
 export { SUBSTITUTION_EVIDENCE } from "./data.js";
-export { createFallbackMap, getFallbackDecision, getRenderableFallback, normalizeFamilyName, } from "./fallbacks.js";
+export { createFallbackMap, getFallbackDecision, getFallbackDecisionForFace, getRenderableFallback, getRenderableFallbackForFace, normalizeFamilyName, } from "./fallbacks.js";

package/dist/types.d.ts

@@ -88,16 +88,34 @@ export interface FontFallback {
      * the row's `faceVerdicts`) for the precise tier.
      */
     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;
+    /**
+     * Named glyph-level divergences that qualify this fallback (e.g. one codepoint reflows). Scoped to
+     * the lookup: a family lookup ({@link getRenderableFallback}) carries ALL of the row's exceptions; a
+     * face lookup ({@link getRenderableFallbackForFace}) carries only the requested face's. Omitted when
+     * none apply - so a renderer can surface a precise "this face reflows on U+0060" without re-deriving.
+     * A fresh array each call (readonly): mutating it never affects another lookup.
+     */
+    glyphExceptions?: readonly GlyphException[];
 }
 /**
  * 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`). `evidenceId` on the terminal kinds points back into
- * {@link SUBSTITUTION_EVIDENCE} for the full row (verdict, faces, ...).
+ * (`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";
@@ -107,6 +125,12 @@ export type FallbackDecision = {
     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;

package/package.json

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