@docfonts/fallbacks 0.3.0 → 0.4.0

package/README.md

@@ -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`.
+- `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/fallbacks.js

@@ -34,8 +34,17 @@ const BY_LOGICAL = new Map(SUBSTITUTION_EVIDENCE.map((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.
+ * `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) {
+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,
@@ -43,6 +52,9 @@ function buildFallback(row, physicalFamily, 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. */
@@ -98,7 +110,7 @@ function decideRowForFace(row, face, canRenderFamily) {
     const faceVerdict = row.faceVerdicts?.[face] ?? row.verdict;
     return {
         kind: "fallback",
-        fallback: buildFallback(row, base.fallback.substituteFamily, faceVerdict),
+        fallback: buildFallback(row, base.fallback.substituteFamily, faceVerdict, face),
     };
 }
 /**

package/dist/types.d.ts

@@ -99,6 +99,14 @@ export interface FontFallback {
     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

package/package.json

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