@docfonts/fallbacks 0.4.0 → 0.6.0

package/README.md

@@ -25,7 +25,7 @@ const fallback = getRenderableFallback("Helvetica", {
   canRenderFamily: (family) => bundledFamilies.has(family),
 });
 
-// { substituteFamily: "Liberation Sans", policyAction: "substitute", verdict: "metric_safe", lineBreakSafe: true, evidenceId: "helvetica" }
+// { substituteFamily: "Liberation Sans", policyAction: "substitute", verdict: "metric_safe", lineBreakSafe: true, evidenceId: "helvetica", generic: "sans-serif" }
 ```
 
 The result is `null` when there is nothing renderable from your available assets. Use `getFallbackDecision` when you need to know why.
@@ -38,10 +38,10 @@ Use `getFallbackDecision` for UI, diagnostics, and reporting. It distinguishes k
 import { getFallbackDecision } from "@docfonts/fallbacks";
 
 getFallbackDecision("Aptos");
-// { kind: "customer_supplied", evidenceId: "aptos" }
+// { kind: "customer_supplied", evidenceId: "aptos", generic: "sans-serif" }
 
 getFallbackDecision("Tahoma");
-// { kind: "no_recommended_fallback", evidenceId: "tahoma" }
+// { kind: "no_recommended_fallback", evidenceId: "tahoma", generic: "sans-serif" }
 
 getFallbackDecision("Made Up Font");
 // { kind: "unknown" }
@@ -49,7 +49,7 @@ getFallbackDecision("Made Up Font");
 getFallbackDecision("Georgia", {
   canRenderFamily: (family) => bundledFamilies.has(family),
 });
-// { kind: "asset_missing", substituteFamily: "Gelasio", verdict: "near_metric", evidenceId: "georgia" }
+// { kind: "asset_missing", substituteFamily: "Gelasio", verdict: "near_metric", evidenceId: "georgia", generic: "serif" }
 ```
 
 Decision kinds:
@@ -86,6 +86,7 @@ Keys are normalized. Use `normalizeFamilyName` for lookups. Rows whose substitut
 - `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`.
+- `generic` - the logical font's broad CSS category (`serif`, `sans-serif`, or `monospace`), for a last-resort generic `font-family` keyword when no named substitute renders. Also present on the known (non-`unknown`) decision kinds.
 - `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.

package/dist/data.js

@@ -1,6 +1,7 @@
 export const SUBSTITUTION_EVIDENCE = [
     {
         "evidenceId": "calibri",
+        "generic": "sans-serif",
         "logicalFamily": "Calibri",
         "physicalFamily": "Carlito",
         "verdict": "metric_safe",
@@ -30,6 +31,7 @@ export const SUBSTITUTION_EVIDENCE = [
     },
     {
         "evidenceId": "cambria",
+        "generic": "serif",
         "logicalFamily": "Cambria",
         "physicalFamily": "Caladea",
         "verdict": "visual_only",
@@ -75,6 +77,7 @@ export const SUBSTITUTION_EVIDENCE = [
     },
     {
         "evidenceId": "arial",
+        "generic": "sans-serif",
         "logicalFamily": "Arial",
         "physicalFamily": "Liberation Sans",
         "verdict": "metric_safe",
@@ -103,6 +106,7 @@ export const SUBSTITUTION_EVIDENCE = [
     },
     {
         "evidenceId": "times-new-roman",
+        "generic": "serif",
         "logicalFamily": "Times New Roman",
         "physicalFamily": "Liberation Serif",
         "verdict": "metric_safe",
@@ -131,6 +135,7 @@ export const SUBSTITUTION_EVIDENCE = [
     },
     {
         "evidenceId": "courier-new",
+        "generic": "monospace",
         "logicalFamily": "Courier New",
         "physicalFamily": "Liberation Mono",
         "verdict": "metric_safe",
@@ -159,6 +164,7 @@ export const SUBSTITUTION_EVIDENCE = [
     },
     {
         "evidenceId": "georgia",
+        "generic": "serif",
         "logicalFamily": "Georgia",
         "physicalFamily": "Gelasio",
         "verdict": "near_metric",
@@ -214,6 +220,7 @@ export const SUBSTITUTION_EVIDENCE = [
     },
     {
         "evidenceId": "arial-narrow",
+        "generic": "sans-serif",
         "logicalFamily": "Arial Narrow",
         "physicalFamily": "Liberation Sans Narrow",
         "verdict": "visual_only",
@@ -259,6 +266,7 @@ export const SUBSTITUTION_EVIDENCE = [
     },
     {
         "evidenceId": "aptos",
+        "generic": "sans-serif",
         "logicalFamily": "Aptos",
         "physicalFamily": null,
         "verdict": "no_substitute",
@@ -283,6 +291,7 @@ export const SUBSTITUTION_EVIDENCE = [
     },
     {
         "evidenceId": "consolas",
+        "generic": "monospace",
         "logicalFamily": "Consolas",
         "physicalFamily": "Inconsolata SemiExpanded",
         "verdict": "cell_width_only",
@@ -311,6 +320,7 @@ export const SUBSTITUTION_EVIDENCE = [
     },
     {
         "evidenceId": "verdana",
+        "generic": "sans-serif",
         "logicalFamily": "Verdana",
         "physicalFamily": null,
         "verdict": "visual_only",
@@ -335,6 +345,7 @@ export const SUBSTITUTION_EVIDENCE = [
     },
     {
         "evidenceId": "tahoma",
+        "generic": "sans-serif",
         "logicalFamily": "Tahoma",
         "physicalFamily": null,
         "verdict": "visual_only",
@@ -359,6 +370,7 @@ export const SUBSTITUTION_EVIDENCE = [
     },
     {
         "evidenceId": "trebuchet-ms",
+        "generic": "sans-serif",
         "logicalFamily": "Trebuchet MS",
         "physicalFamily": null,
         "verdict": "visual_only",
@@ -383,6 +395,7 @@ export const SUBSTITUTION_EVIDENCE = [
     },
     {
         "evidenceId": "comic-sans-ms",
+        "generic": "sans-serif",
         "logicalFamily": "Comic Sans MS",
         "physicalFamily": "Comic Neue",
         "verdict": "visual_only",
@@ -411,6 +424,7 @@ export const SUBSTITUTION_EVIDENCE = [
     },
     {
         "evidenceId": "candara",
+        "generic": "sans-serif",
         "logicalFamily": "Candara",
         "physicalFamily": null,
         "verdict": "visual_only",
@@ -435,6 +449,7 @@ export const SUBSTITUTION_EVIDENCE = [
     },
     {
         "evidenceId": "constantia",
+        "generic": "serif",
         "logicalFamily": "Constantia",
         "physicalFamily": null,
         "verdict": "visual_only",
@@ -459,6 +474,7 @@ export const SUBSTITUTION_EVIDENCE = [
     },
     {
         "evidenceId": "corbel",
+        "generic": "sans-serif",
         "logicalFamily": "Corbel",
         "physicalFamily": null,
         "verdict": "visual_only",
@@ -483,6 +499,7 @@ export const SUBSTITUTION_EVIDENCE = [
     },
     {
         "evidenceId": "lucida-console",
+        "generic": "monospace",
         "logicalFamily": "Lucida Console",
         "physicalFamily": "Cousine",
         "verdict": "cell_width_only",
@@ -511,6 +528,7 @@ export const SUBSTITUTION_EVIDENCE = [
     },
     {
         "evidenceId": "aptos-display",
+        "generic": "sans-serif",
         "logicalFamily": "Aptos Display",
         "physicalFamily": null,
         "verdict": "customer_supplied",
@@ -532,6 +550,7 @@ export const SUBSTITUTION_EVIDENCE = [
     },
     {
         "evidenceId": "cambria-math",
+        "generic": "serif",
         "logicalFamily": "Cambria Math",
         "physicalFamily": null,
         "verdict": "preserve_only",
@@ -553,6 +572,7 @@ export const SUBSTITUTION_EVIDENCE = [
     },
     {
         "evidenceId": "helvetica",
+        "generic": "sans-serif",
         "logicalFamily": "Helvetica",
         "physicalFamily": "Liberation Sans",
         "verdict": "metric_safe",
@@ -581,6 +601,7 @@ export const SUBSTITUTION_EVIDENCE = [
     },
     {
         "evidenceId": "calibri-light",
+        "generic": "sans-serif",
         "logicalFamily": "Calibri Light",
         "physicalFamily": "Carlito",
         "verdict": "visual_only",
@@ -609,6 +630,7 @@ export const SUBSTITUTION_EVIDENCE = [
     },
     {
         "evidenceId": "baskerville-old-face",
+        "generic": "serif",
         "logicalFamily": "Baskerville Old Face",
         "physicalFamily": "Bacasime Antique",
         "verdict": "visual_only",
@@ -645,5 +667,37 @@ export const SUBSTITUTION_EVIDENCE = [
                 "note": "Bacasime Antique Regular's no-break space (U+00A0) advance diverges ~49% from Baskerville Old Face; lines containing NBSP reflow. Every other Latin-core glyph is advance-identical, which is why this is visual_only with a single named exception, not near_metric."
             }
         ]
+    },
+    {
+        "evidenceId": "cooper-black",
+        "generic": "serif",
+        "logicalFamily": "Cooper Black",
+        "physicalFamily": "Caprasimo",
+        "verdict": "metric_safe",
+        "faces": {
+            "regular": true,
+            "bold": false,
+            "italic": false,
+            "boldItalic": false
+        },
+        "gates": {
+            "static": "pass",
+            "metric": "pass",
+            "layout": "not_run",
+            "ship": "not_run"
+        },
+        "policyAction": "substitute",
+        "measurementRefs": [
+            "cooper-black_regular__caprasimo#regular#w400#786ab84e#analytic_advance#2026-06-05"
+        ],
+        "exportRule": "preserve_original_name",
+        "advance": {
+            "meanDelta": 0,
+            "maxDelta": 0
+        },
+        "candidateLicense": "OFL-1.1",
+        "faceVerdicts": {
+            "regular": "metric_safe"
+        }
     }
 ];

package/dist/fallbacks.js

@@ -52,6 +52,7 @@ function buildFallback(row, physicalFamily, verdict, faceSlot) {
         lineBreakSafe: LINE_BREAK_SAFE_VERDICTS.has(verdict),
         faces: row.faces,
         evidenceId: row.evidenceId,
+        generic: row.generic,
         ...(glyphExceptions && glyphExceptions.length > 0
             ? { glyphExceptions }
             : {}),
@@ -59,16 +60,16 @@ function buildFallback(row, physicalFamily, verdict, faceSlot) {
 }
 /** Decide a single row against the consumer's asset availability. Pure. */
 function decideRow(row, canRenderFamily) {
-    const { policyAction, physicalFamily, verdict, evidenceId } = row;
+    const { policyAction, physicalFamily, verdict, evidenceId, generic } = row;
     // Deliberate non-substitution policies first: nothing renders in the original's place.
     if (policyAction === "preserve_only")
-        return { kind: "preserve_only", evidenceId };
+        return { kind: "preserve_only", evidenceId, generic };
     if (policyAction === "customer_supplied")
-        return { kind: "customer_supplied", evidenceId };
+        return { kind: "customer_supplied", evidenceId, generic };
     // 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 };
+        return { kind: "no_recommended_fallback", evidenceId, generic };
     // Named substitute the consumer does not bundle: surfaced so a UI can say which font to add.
     if (canRenderFamily && !canRenderFamily(physicalFamily))
         return {
@@ -76,6 +77,7 @@ function decideRow(row, canRenderFamily) {
             substituteFamily: physicalFamily,
             verdict,
             evidenceId,
+            generic,
         };
     return {
         kind: "fallback",
@@ -106,6 +108,7 @@ function decideRowForFace(row, face, canRenderFamily) {
             kind: "face_missing",
             substituteFamily: base.fallback.substituteFamily,
             evidenceId: row.evidenceId,
+            generic: row.generic,
         };
     const faceVerdict = row.faceVerdicts?.[face] ?? row.verdict;
     return {

package/dist/index.d.ts

@@ -4,4 +4,4 @@
  */
 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";
+export type { AdvanceDelta, CssGeneric, FaceCoverage, FaceSlot, FallbackDecision, FontFallback, GlyphException, PolicyAction, SubstituteGates, SubstitutionEvidence, Verdict, } from "./types.js";

package/dist/types.d.ts

@@ -10,6 +10,12 @@ export type PolicyAction = "substitute" | "category_fallback" | "preserve_only"
 export type GateStatus = "pass" | "not_run" | "fail";
 /** RIBBI face slot - the renderer's coarse face bucket. */
 export type FaceSlot = "regular" | "bold" | "italic" | "boldItalic";
+/**
+ * CSS generic family for the logical font: the broad category a renderer can drop in as a
+ * last-resort `font-family` keyword when no named substitute renders. Only the categories consumers
+ * currently need.
+ */
+export type CssGeneric = "serif" | "sans-serif" | "monospace";
 /** Advance-width divergence vs the proprietary oracle, as fractions (0 = identical advances). */
 export interface AdvanceDelta {
     meanDelta: number;
@@ -46,6 +52,8 @@ export interface SubstitutionEvidence {
     evidenceId: string;
     /** the proprietary family the document asks for, e.g. "Cambria". */
     logicalFamily: string;
+    /** the logical font's broad CSS category, for a last-resort generic `font-family` keyword. */
+    generic: CssGeneric;
     /** the physical substitute rendered in its place; null when no candidate is recommended. */
     physicalFamily: string | null;
     /** worst-face fidelity verdict (the public summary; see `faceVerdicts` when faces disagree). */
@@ -99,6 +107,8 @@ export interface FontFallback {
     faces: FaceCoverage;
     /** stable reviewed-evidence id; look the full row up in {@link SUBSTITUTION_EVIDENCE}. */
     evidenceId: string;
+    /** the logical font's broad CSS category, for a last-resort generic `font-family` keyword. */
+    generic: CssGeneric;
     /**
      * 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
@@ -115,7 +125,9 @@ export interface FontFallback {
  * 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, ...).
+ * kinds points back into {@link SUBSTITUTION_EVIDENCE} for the full row (verdict, faces, ...). The
+ * known (non-`unknown`) kinds also carry the logical font's `generic`, so a consumer with no
+ * renderable substitute can still emit a same-category generic `font-family` keyword.
  */
 export type FallbackDecision = {
     kind: "fallback";
@@ -125,21 +137,26 @@ export type FallbackDecision = {
     substituteFamily: string;
     verdict: Verdict;
     evidenceId: string;
+    generic: CssGeneric;
 } | {
     /** 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;
+    generic: CssGeneric;
 } | {
     kind: "no_recommended_fallback";
     evidenceId: string;
+    generic: CssGeneric;
 } | {
     kind: "customer_supplied";
     evidenceId: string;
+    generic: CssGeneric;
 } | {
     kind: "preserve_only";
     evidenceId: string;
+    generic: CssGeneric;
 } | {
     kind: "unknown";
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docfonts/fallbacks",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Measured open-font fallbacks for proprietary document fonts.",
   "license": "MIT",
   "type": "module",
@@ -35,6 +35,8 @@
     "directory": "packages/fallbacks"
   },
   "scripts": {
+    "gen:data": "bun run scripts/generate-data.ts",
+    "acquire": "bun run scripts/acquire.ts",
     "build": "tsc -p tsconfig.build.json",
     "prepack": "bun run build"
   },