feat(fonts): face-aware font-load planner (load used faces, not declared families)

The load gate waited on every family declared in the docx fontTable and only
ever loaded each family's regular face. Two problems: bold/italic text measured
against the regular face (or faux-bold) and reflowed once the real face loaded;
and a large pack would over-fetch declared-but-unrendered fonts.

The planner walks the layout input (blocksForLayout, available before measure)
and emits the exact physical faces the document RENDERS - family + weight +
style - resolving logical to physical with the same resolver measure and paint
use. The gate awaits those faces (weight/style-specific probes) and its late-load
handler reflows only when a loaded face matches a required one. Declared-font
diagnostics (getDocumentFonts / getReport) are unchanged; the registry now keys
load state per face and rolls a family up for the report (a failed used face
outranks a loaded sibling, so it is not masked).

Prerequisite for scaling to a larger font pack. Does not add the pack, the
late-load reflow scheduler, or per-numeric-weight faces.

Author: caio-pizzol

packages/super-editor/src/editors/v1/core/presentation-editor/PresentationEditor.ts

@@ -180,6 +180,7 @@ import { measureBlock } from '@superdoc/measuring-dom';
 import { resolvePhysicalFamilies, type FontResolutionRecord, type FontLoadSummary } from '@superdoc/font-system';
 import { installBundledSubstitutes } from '@superdoc/font-system/bundled';
 import { FontReadinessGate } from './fonts/FontReadinessGate';
+import { planRequiredFontFaces } from './fonts/font-load-planner';
 import type { FontsChangedPayload } from '../types/EditorEvents';
 import type {
   ColumnLayout,
@@ -530,6 +531,8 @@ export class PresentationEditor extends EventEmitter {
   #selectionSync = new SelectionSyncCoordinator();
   /** Load-before-measure gate: awaits required fonts before measurement, reflows on late load. */
   #fontGate: FontReadinessGate | null = null;
+  /** Layout blocks for the current render, stashed so the gate's planner reads the live set. */
+  #fontPlanBlocks: FlowBlock[] | null = null;
   /** Dedup key for `fonts-changed`: epoch + per-face load status. Null until the first emit. */
   #lastFontsChangedKey: string | null = null;
   /** Last emitted `fonts-changed` payload, so a late relay subscriber can replay it. */
@@ -959,8 +962,13 @@ export class PresentationEditor extends EventEmitter {
           this.#pendingDocChange = true;
           this.#scheduleRerender();
         },
-        // Wait on the resolved PHYSICAL families (Calibri -> Carlito), so the gate holds
-        // measurement until the substitute that measure + paint will use has loaded.
+        // Face-aware required set: the exact physical faces (family + weight + style) the
+        // rendered document uses, from the planner walking the current layout blocks. The
+        // gate awaits these - so bold/italic load before measure and declared-but-unused
+        // fonts are not fetched. Reads the blocks stashed just before each gate await.
+        getRequiredFaces: () => planRequiredFontFaces(this.#fontPlanBlocks),
+        // Fallback family path (used only if getRequiredFaces is unavailable): wait on the
+        // resolved PHYSICAL families (Calibri -> Carlito).
         resolveFamilies: resolvePhysicalFamilies,
         // Register the bundled substitute pack (Carlito) into the document's registry the
         // first time it resolves, so the substitute is available with no manual setup.
@@ -6707,6 +6715,9 @@ export class PresentationEditor extends EventEmitter {
       // Bounded by a per-font timeout; resolves to the cached summary once fonts are stable;
       // never throws, so font readiness can never block layout.
       try {
+        // Stash the blocks this render will measure so the gate's planner extracts the
+        // exact used faces (footnote/endnote blocks are already part of blocksForLayout).
+        this.#fontPlanBlocks = blocksForLayout;
         const fontSummary = (await this.#fontGate?.ensureReadyForMeasure()) ?? null;
         // Now that the gate has settled, the font report reflects real load status. Emit
         // the authoritative `fonts-changed` once the picture first resolves and whenever it

packages/super-editor/src/editors/v1/core/presentation-editor/fonts/FontReadinessGate.test.ts

@@ -1,7 +1,15 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest';
-import type { FontLoadResult, FontLoadStatus, FontRegistry } from '@superdoc/font-system';
+import type {
+  FontFaceLoadResult,
+  FontFaceRequest,
+  FontLoadResult,
+  FontLoadStatus,
+  FontRegistry,
+} from '@superdoc/font-system';
 import { FontReadinessGate, type FontEnvironment } from './FontReadinessGate';
 
+const faceKey = (r: FontFaceRequest) => `${r.family.toLowerCase()}|${r.weight}|${r.style}`;
+
 /** Minimal FontFace constructor stand-in for the environment (unused when a registry is injected). */
 class FakeFontFace {
   constructor(public readonly family: string) {}
@@ -28,6 +36,18 @@ class FakeRegistry {
     this.awaitCalls.push(unique);
     return unique.map((family) => ({ family, status: this.getStatus(family) }));
   }
+
+  // Face-level slice for the face path.
+  readonly faceStatuses = new Map<string, FontLoadStatus>();
+  readonly faceAwaitCalls: string[][] = [];
+  getFaceStatus(request: FontFaceRequest): FontLoadStatus {
+    return this.faceStatuses.get(faceKey(request)) ?? 'unloaded';
+  }
+  async awaitFaceRequests(requests: Iterable<FontFaceRequest>): Promise<FontFaceLoadResult[]> {
+    const unique = [...requests];
+    this.faceAwaitCalls.push(unique.map(faceKey));
+    return unique.map((request) => ({ request, status: this.getFaceStatus(request) }));
+  }
   asRegistry(): FontRegistry {
     return this as unknown as FontRegistry;
   }
@@ -182,4 +202,49 @@ describe('FontReadinessGate', () => {
 
     await expect(gate.ensureReadyForMeasure()).resolves.toMatchObject({ loaded: 0 });
   });
+
+  describe('face-aware path (getRequiredFaces)', () => {
+    const BOLD: FontFaceRequest = { family: 'Carlito', weight: '700', style: 'normal' };
+
+    function makeFaceGate(getRequiredFaces: () => FontFaceRequest[]) {
+      return new FontReadinessGate({
+        registry: registry.asRegistry(),
+        getDocumentFonts: () => [],
+        getRequiredFaces,
+        requestReflow,
+        invalidateCaches,
+        getFontEnvironment: () => ({ fontSet: fontSet.asFontSet(), FontFaceCtor: fakeCtor }),
+        timeoutMs: 1000,
+      });
+    }
+
+    it('awaits the exact required faces (family + weight + style), not families', async () => {
+      registry.faceStatuses.set(faceKey(BOLD), 'loaded');
+      const gate = makeFaceGate(() => [BOLD]);
+      const summary = await gate.ensureReadyForMeasure();
+      expect(registry.faceAwaitCalls).toEqual([['carlito|700|normal']]);
+      expect(summary.loaded).toBe(1);
+    });
+
+    it('reflows once when the required bold face loads after a timed-out first paint', async () => {
+      registry.faceStatuses.set(faceKey(BOLD), 'timed_out');
+      const gate = makeFaceGate(() => [BOLD]);
+      await gate.ensureReadyForMeasure();
+      expect(requestReflow).not.toHaveBeenCalled();
+
+      // A REGULAR Carlito face finishing must NOT reflow - it is not a required face.
+      fontSet.fire('loadingdone', { fontfaces: [{ family: 'Carlito', weight: 'normal', style: 'normal' }] });
+      expect(requestReflow).not.toHaveBeenCalled();
+
+      // The required BOLD face finishing DOES reflow, exactly once.
+      registry.faceStatuses.set(faceKey(BOLD), 'loaded');
+      fontSet.fire('loadingdone', { fontfaces: [{ family: 'Carlito', weight: 'bold', style: 'normal' }] });
+      expect(requestReflow).toHaveBeenCalledTimes(1);
+      expect(invalidateCaches).toHaveBeenCalledTimes(1);
+
+      // A second loadingdone for the same face does not reflow again (no loop).
+      fontSet.fire('loadingdone', { fontfaces: [{ family: 'Carlito', weight: 'bold', style: 'normal' }] });
+      expect(requestReflow).toHaveBeenCalledTimes(1);
+    });
+  });
 });

packages/super-editor/src/editors/v1/core/presentation-editor/fonts/FontReadinessGate.ts

@@ -5,6 +5,8 @@ import {
   DEFAULT_FONT_LOAD_TIMEOUT_MS,
   type FontRegistry,
   type FontLoadResult,
+  type FontFaceRequest,
+  type FontFaceLoadResult,
   type FontLoadSummary,
   type FontResolutionRecord,
 } from '@superdoc/font-system';
@@ -26,8 +28,16 @@ export interface FontEnvironment {
 }
 
 export interface FontReadinessGateOptions {
-  /** Logical font families the current document uses. Cheap to call per render. */
+  /** Logical font families the current document DECLARES (fontTable). Used for diagnostics. */
   getDocumentFonts: () => string[];
+  /**
+   * The exact physical FACES (family + weight + style) the current document RENDERS, from
+   * the planner walking layout input. When provided, the gate awaits these faces instead of
+   * declared families - so bold/italic load before measure and declared-but-unused fonts are
+   * not fetched. Falls back to the {@link getDocumentFonts} + {@link resolveFamilies} family
+   * path when omitted (tests / non-layout callers).
+   */
+  getRequiredFaces?: () => FontFaceRequest[];
   /** Trigger a re-measure + re-layout + repaint (PresentationEditor's immediate render). */
   requestReflow: () => void;
   /**
@@ -76,6 +86,7 @@ export interface FontReadinessGateOptions {
  */
 export class FontReadinessGate {
   readonly #getDocumentFonts: () => string[];
+  readonly #getRequiredFaces: (() => FontFaceRequest[]) | null;
   readonly #resolveFamilies: (families: string[]) => string[];
   readonly #requestReflow: () => void;
   readonly #getFontEnvironment: () => FontEnvironment | null;
@@ -90,13 +101,18 @@ export class FontReadinessGate {
   #fontConfigVersion = 0;
   #requiredSignature = '';
   #requiredFamilies = new Set<string>();
-  /** Families observed available, so the late-load handler fires at most once per face. */
+  /** Required face keys (family|weight|style) for the face path's late-load matching. */
+  #requiredFaceKeys = new Set<string>();
+  /** Families observed available, so the family-path late-load handler fires once per face. */
   readonly #seenAvailable = new Set<string>();
+  /** Face keys observed available, so the face-path late-load handler fires once per face. */
+  readonly #seenAvailableFaces = new Set<string>();
   #lastSummary: FontLoadSummary | null = null;
   #loadingDoneHandler: ((event: FontFaceSetLoadEvent) => void) | null = null;
 
   constructor(options: FontReadinessGateOptions) {
     this.#getDocumentFonts = options.getDocumentFonts;
+    this.#getRequiredFaces = options.getRequiredFaces ?? null;
     this.#resolveFamilies = options.resolveFamilies ?? ((families) => families);
     this.#requestReflow = options.requestReflow;
     this.#getFontEnvironment = options.getFontEnvironment ?? defaultFontEnvironment;
@@ -143,6 +159,55 @@ export class FontReadinessGate {
    * must not break layout.
    */
   async ensureReadyForMeasure(): Promise<FontLoadSummary> {
+    if (this.#getRequiredFaces) return this.#ensureFacesReady(this.#getRequiredFaces);
+    return this.#ensureFamiliesReady();
+  }
+
+  /** Face-aware path: await the exact physical faces the rendered document uses. */
+  async #ensureFacesReady(getRequiredFaces: () => FontFaceRequest[]): Promise<FontLoadSummary> {
+    const registry = this.#resolveContext().registry;
+
+    let required: FontFaceRequest[];
+    try {
+      required = getRequiredFaces();
+    } catch {
+      return this.#lastSummary ?? emptySummary();
+    }
+
+    const keyed = required.map((r) => ({ request: r, key: faceKeyOf(r.family, r.weight, r.style) }));
+    const signature = keyed
+      .map((k) => k.key)
+      .sort()
+      .join('|');
+    const unchangedAndLoaded =
+      signature === this.#requiredSignature && keyed.every((k) => registry.getFaceStatus(k.request) === 'loaded');
+    if (unchangedAndLoaded && this.#lastSummary) {
+      return this.#lastSummary;
+    }
+
+    this.#requiredSignature = signature;
+    this.#requiredFaceKeys = new Set(keyed.map((k) => k.key));
+    this.#requiredFamilies = new Set();
+    this.#ensureSubscribed();
+
+    let results: FontFaceLoadResult[] = [];
+    try {
+      results = required.length ? await registry.awaitFaceRequests(required, { timeoutMs: this.#timeoutMs }) : [];
+    } catch {
+      results = [];
+    }
+
+    for (const result of results) {
+      if (result.status === 'loaded') {
+        this.#seenAvailableFaces.add(faceKeyOf(result.request.family, result.request.weight, result.request.style));
+      }
+    }
+    this.#lastSummary = summarizeFaces(results);
+    return this.#lastSummary;
+  }
+
+  /** Legacy family path: await declared families (tests / non-layout callers). */
+  async #ensureFamiliesReady(): Promise<FontLoadSummary> {
     const registry = this.#resolveContext().registry;
 
     let required: string[];
@@ -161,6 +226,7 @@ export class FontReadinessGate {
 
     this.#requiredSignature = signature;
     this.#requiredFamilies = new Set(required);
+    this.#requiredFaceKeys = new Set();
     this.#ensureSubscribed();
 
     let results: FontLoadResult[] = [];
@@ -185,6 +251,7 @@ export class FontReadinessGate {
     this.#fontConfigVersion += 1;
     bumpFontConfigVersion(); // bump the global epoch so measure/paint reuse signatures bust
     this.#seenAvailable.clear();
+    this.#seenAvailableFaces.clear();
     this.#requiredSignature = '';
     this.#invalidateCaches();
     this.#requestReflow();
@@ -233,20 +300,40 @@ export class FontReadinessGate {
   }
 
   #onLoadingDone(event: FontFaceSetLoadEvent): void {
-    // A required face that the last measure could not use just finished loading -> that
-    // paint used a fallback, so invalidate and reflow. We key off the faces the event
+    // A required face/family that the last measure could not use just finished loading ->
+    // that paint used a fallback, so invalidate and reflow. We key off the faces the event
     // actually reports as loaded (reliable), NOT FontFaceSet.check() (which lies for
-    // unregistered bare families). The seen-set fires this once per face; never a loop.
-    const loadedKeys = new Set((event?.fontfaces ?? []).map((face) => normalizeFamilyKey(face.family)));
-    if (loadedKeys.size === 0) return;
+    // unregistered bare families). The seen-set fires this at most once per face.
+    const faces = event?.fontfaces ?? [];
+    if (faces.length === 0) return;
     let changed = false;
-    for (const family of this.#requiredFamilies) {
-      if (this.#seenAvailable.has(family)) continue;
-      if (loadedKeys.has(normalizeFamilyKey(family))) {
-        this.#seenAvailable.add(family);
-        changed = true;
+
+    if (this.#requiredFaceKeys.size > 0) {
+      // Face path: reflow only when a loaded face matches a REQUIRED face key (family +
+      // weight + style). "Liberation Sans bold loaded and it was required" - not merely
+      // "Liberation Sans (regular) loaded".
+      const loadedFaceKeys = new Set(
+        faces.map((face) => faceKeyOf(face.family, normalizeWeightToken(face.weight), normalizeStyleToken(face.style))),
+      );
+      for (const key of this.#requiredFaceKeys) {
+        if (this.#seenAvailableFaces.has(key)) continue;
+        if (loadedFaceKeys.has(key)) {
+          this.#seenAvailableFaces.add(key);
+          changed = true;
+        }
+      }
+    } else {
+      // Legacy family path.
+      const loadedFamilies = new Set(faces.map((face) => normalizeFamilyKey(face.family)));
+      for (const family of this.#requiredFamilies) {
+        if (this.#seenAvailable.has(family)) continue;
+        if (loadedFamilies.has(normalizeFamilyKey(family))) {
+          this.#seenAvailable.add(family);
+          changed = true;
+        }
       }
     }
+
     if (!changed) return;
     this.#fontConfigVersion += 1;
     bumpFontConfigVersion(); // bump the global epoch so measure/paint reuse signatures bust
@@ -263,6 +350,27 @@ function normalizeFamilyKey(family: string): string {
     .toLowerCase();
 }
 
+/** Canonical weight token for face matching: bold/>=600 -> '700', else '400'. */
+function normalizeWeightToken(weight: string | undefined): '400' | '700' {
+  if (!weight) return '400';
+  const w = weight.trim().toLowerCase();
+  if (w === 'bold' || w === 'bolder') return '700';
+  const n = Number(w);
+  return Number.isFinite(n) && n >= 600 ? '700' : '400';
+}
+
+/** Canonical style token for face matching: italic/oblique -> 'italic', else 'normal'. */
+function normalizeStyleToken(style: string | undefined): 'normal' | 'italic' {
+  if (!style) return 'normal';
+  const s = style.trim().toLowerCase();
+  return s.startsWith('italic') || s.startsWith('oblique') ? 'italic' : 'normal';
+}
+
+/** Face key matching the registry's: normalized family + weight + style. */
+function faceKeyOf(family: string, weight: '400' | '700', style: 'normal' | 'italic'): string {
+  return `${normalizeFamilyKey(family)}|${weight}|${style}`;
+}
+
 /** The font-system registry accepts a structural font set + face ctor; the DOM types satisfy them. */
 type FontSetLikeArg = Parameters<typeof getFontRegistryFor>[0];
 type FontFaceCtorArg = Parameters<typeof getFontRegistryFor>[1];
@@ -279,6 +387,19 @@ function summarize(results: FontLoadResult[]): FontLoadSummary {
   return summary;
 }
 
+/** Summarize face results (counts are per-FACE; `results` keeps the physical family name). */
+function summarizeFaces(results: FontFaceLoadResult[]): FontLoadSummary {
+  const summary = emptySummary();
+  summary.results = results.map((r) => ({ family: r.request.family, status: r.status }));
+  for (const result of results) {
+    if (result.status === 'loaded') summary.loaded += 1;
+    else if (result.status === 'failed') summary.failed += 1;
+    else if (result.status === 'timed_out') summary.timedOut += 1;
+    else if (result.status === 'fallback_used') summary.fallbackUsed += 1;
+  }
+  return summary;
+}
+
 function emptySummary(): FontLoadSummary {
   return { loaded: 0, failed: 0, timedOut: 0, fallbackUsed: 0, results: [] };
 }