@docfonts/fallbacks 0.1.0 → 0.2.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,85 @@ 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 { deriveFallbackMap } from "@docfonts/fallbacks";
+import { getFallbackDecision } from "@docfonts/fallbacks";
+
+getFallbackDecision("Aptos");
+// { kind: "customer_supplied", evidenceId: "aptos" }
 
-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.
+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" }
 ```
 
-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.
+Decision kinds:
+
+- `fallback` - render the returned `substituteFamily`.
+- `asset_missing` - docfonts has a fallback, but your app does not load that family.
+- `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 { createFallbackMap, normalizeFamilyName } from "@docfonts/fallbacks";
+
+const map = createFallbackMap({
+  canRenderFamily: (family) => bundledFamilies.has(family),
+});
+
+map[normalizeFamilyName("Times New Roman")]; // { substituteFamily: "Liberation Serif", ... }
+```
+
+Keys are normalized. Use `normalizeFamilyName` for lookups. Rows whose substitute family is not available are omitted.
 
 ## 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`.
+- `evidenceId` - the stable id for the reviewed evidence row; look the full row up in `SUBSTITUTION_EVIDENCE`.
+
+`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` (faces, per-face verdicts, glyph exceptions) for richer reporting. Face-level routing stays yours: `getFallback` answers "which family", not "which face".
+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".
 
 ## 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.
+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.
-
-## License
-
-MIT

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,31 @@
-import type { FontFallback } from "./types";
+import type { 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 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 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. `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}.
+ * 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.
  */
-export declare function deriveFallbackMap(options: FallbackMapOptions): Record<string, FontFallback>;
+export declare function createFallbackMap(options: RenderableFallbackOptions): Record<string, FontFallback>;

package/dist/fallbacks.js

@@ -1,21 +1,23 @@
 /**
- * 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. 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.
  */
-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 +25,71 @@ 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. */
+function buildFallback(row, physicalFamily) {
     return {
-        family: row.physicalFamily,
-        action: row.policyAction,
+        substituteFamily: physicalFamily,
+        policyAction: row.policyAction,
         verdict: row.verdict,
-        faithful: FAITHFUL_VERDICTS.has(row.verdict),
+        lineBreakSafe: LINE_BREAK_SAFE_VERDICTS.has(row.verdict),
         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) };
+}
+/**
+ * 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 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, 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 getFallback(logicalFamily, options = {}) {
-    const row = BY_LOGICAL.get(normalizeFamily(logicalFamily));
-    return row ? toFallback(row, options.hasFamily) : null;
+export function getRenderableFallback(family, options) {
+    const decision = getFallbackDecision(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. `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}.
+ * 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.
  */
-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, getRenderableFallback, 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, getRenderableFallback, 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,56 @@ 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;
+    /** 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`). `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;
+} | {
+    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.2.0",
   "description": "Measured open-font fallbacks for proprietary document fonts.",
   "license": "MIT",
   "type": "module",