feat(fonts): face-aware font-load planner (load used faces, not declared families) by caio-pizzol · Pull Request #3612 · superdoc-dev/superdoc

caio-pizzol · 2026-06-02T23:51:10Z

Stacked on caio/font-load-gate-t3 (PR #3608) — review that first; this diff is the planner only.

Makes the load gate await the exact physical font faces a document renders — family + weight + style — instead of every family declared in the docx fontTable. Two problems this fixes: bold/italic text measured against the regular face (or a synthesized faux-bold) and reflowed once the real face arrived; and a larger font pack would over-fetch declared-but-unrendered fonts. This is the prerequisite that makes scaling past the current five-font pack safe.

What changed

@superdoc/font-system: a FontFaceRequest type and face-keyed registry APIs (awaitFaceRequest(s), getFaceStatus, weight/style-specific probes like italic 700 16px "Carlito"). register() seeds face-level status; getStatus(family) rolls up from faces for diagnostics — a failed/timed-out used face outranks a loaded sibling so a broken face is never masked.
font-load-planner.ts: walks the layout input (blocksForLayout, available before measure) — paragraph runs, table cells, list item paragraphs, and the word-layout marker run — and emits the deduped physical faces actually rendered, resolving logical→physical with the same resolver measure and paint use.
The gate gains a getRequiredFaces path (family path kept as fallback); its late-load handler reflows only when a loaded face matches a required one (“the bold face loaded”, not “the family loaded”).
Declared-font diagnostics (getDocumentFonts / getReport) are unchanged and stay separate from the narrowed load set.

Verified

Live: a doc declaring Arial/Times/Aptos but rendering only Calibri loads only Carlito (no Liberation Serif for declared-but-unused Times); bolding the text then loads Carlito-Bold.woff2 (the old family-only gate never did, causing a measured ~2% bold-width drift).
Repo typecheck clean; unit tests for the planner (extraction/dedupe/table/list/marker/unmapped/stack), the registry face APIs + rollup, and the gate face-path late-load (regular load → no reflow, bold load → one reflow).

Not included

The larger font pack itself.
The bounded late-load reflow scheduler (the next step for font-heavy docs on slow networks).
Per-numeric-weight faces (the run model is binary bold/italic; pack ships 400/700 × normal/italic).
List-marker fonts are planned from the paragraph's word-layout marker run; a marker whose font is resolved only at measure time outside that structure is not separately planned.

…red 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.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a2ddf5ac46

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-06-03T11:29:52Z

+        // 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;


Include header/footer blocks in the face plan

When a font or style is used only in headers/footers, this stashes only blocksForLayout (body plus semantic notes) before the gate runs, while #buildHeaderFooterInput() is called afterward and incrementalLayout measures those header/footer blocks via layoutHeaderFooterWithCache. In that scenario the new face planner never awaits the header/footer face, and the late-load handler also ignores its loadingdone event because the face key is not in #requiredFaceKeys, so header/footer text can be measured and cached with fallback metrics without a reflow.

Useful? React with 👍 / 👎.

cubic-dev-ai

3 issues found across 9 files

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/super-editor/src/editors/v1/core/presentation-editor/fonts/font-load-planner.ts">

<violation number="1" location="packages/super-editor/src/editors/v1/core/presentation-editor/fonts/font-load-planner.ts:67">
P2: Table-cell nested blocks are only partially traversed, so some rendered fonts can be omitted from the load plan.</violation>

<violation number="2" location="packages/super-editor/src/editors/v1/core/presentation-editor/fonts/font-load-planner.ts:91">
P3: `ListBlock` traversal in the planner is dead code for the runtime layout path, because `blocksForLayout` is paragraph/table based and does not include `kind: 'list'` blocks.

(Based on your team's feedback about no runtime ListBlock in layout.) [FEEDBACK_USED]</violation>
</file>

<file name="packages/super-editor/src/editors/v1/core/presentation-editor/fonts/FontReadinessGate.ts">

<violation number="1" location="packages/super-editor/src/editors/v1/core/presentation-editor/fonts/FontReadinessGate.ts:172">
P1: If face planning throws, the gate now skips font loading altogether instead of falling back to the family path, which can let fallback metrics reach layout.</violation>
</file>

_{Tip: cubic used a learning from your PR history. Let your coding agent read cubic learnings directly with the cubic MCP.

Re-trigger cubic}

cubic-dev-ai · 2026-06-03T11:41:56Z

+      required = getRequiredFaces();
+    } catch {
+      return this.#lastSummary ?? emptySummary();
+    }


P1: If face planning throws, the gate now skips font loading altogether instead of falling back to the family path, which can let fallback metrics reach layout.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/super-editor/src/editors/v1/core/presentation-editor/fonts/FontReadinessGate.ts, line 172: <comment>If face planning throws, the gate now skips font loading altogether instead of falling back to the family path, which can let fallback metrics reach layout.</comment> <file context> @@ -143,6 +159,55 @@ export class FontReadinessGate { + + let required: FontFaceRequest[]; + try { + required = getRequiredFaces(); + } catch { + return this.#lastSummary ?? emptySummary(); </file context>

Suggested change

required = getRequiredFaces();

} catch {

return this.#lastSummary ?? emptySummary();

}

try {

required = getRequiredFaces();

} catch {

return this.#ensureFamiliesReady();

}

cubic-dev-ai · 2026-06-03T11:41:56Z

+  for (const row of table.rows) {
+    for (const cell of row.cells) {
+      collectParagraph(out, cell.paragraph);
+      if (cell.blocks) for (const b of cell.blocks) collectBlock(out, b as FlowBlock);


P2: Table-cell nested blocks are only partially traversed, so some rendered fonts can be omitted from the load plan.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/super-editor/src/editors/v1/core/presentation-editor/fonts/font-load-planner.ts, line 67: <comment>Table-cell nested blocks are only partially traversed, so some rendered fonts can be omitted from the load plan.</comment> <file context> @@ -0,0 +1,109 @@ + for (const row of table.rows) { + for (const cell of row.cells) { + collectParagraph(out, cell.paragraph); + if (cell.blocks) for (const b of cell.blocks) collectBlock(out, b as FlowBlock); + } + } </file context>

cubic-dev-ai · 2026-06-03T11:41:56Z

+    case 'table':
+      collectTable(out, block);
+      break;
+    case 'list':


P3: ListBlock traversal in the planner is dead code for the runtime layout path, because blocksForLayout is paragraph/table based and does not include kind: 'list' blocks.

(Based on your team's feedback about no runtime ListBlock in layout.)

View Feedback

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/super-editor/src/editors/v1/core/presentation-editor/fonts/font-load-planner.ts, line 91: <comment>`ListBlock` traversal in the planner is dead code for the runtime layout path, because `blocksForLayout` is paragraph/table based and does not include `kind: 'list'` blocks. (Based on your team's feedback about no runtime ListBlock in layout.) </comment> <file context> @@ -0,0 +1,109 @@ + case 'table': + collectTable(out, block); + break; + case 'list': + collectList(out, block); + break; </file context>

superdoc-bot Bot added review: thorough review: careful and removed review: thorough labels Jun 2, 2026

caio-pizzol force-pushed the caio/font-load-planner branch from 89f3651 to fd58a97 Compare June 2, 2026 23:54

caio-pizzol mentioned this pull request Jun 3, 2026

feat(fonts): bounded late-load reflow scheduler #3613

Open

caio-pizzol added 2 commits June 2, 2026 21:35

Merge branch 'caio/font-load-gate-t3' into caio/font-load-planner

24041bf

Merge branch 'caio/font-load-gate-t3' into caio/font-load-planner

a2ddf5a

caio-pizzol marked this pull request as ready for review June 3, 2026 11:27

caio-pizzol requested a review from a team as a code owner June 3, 2026 11:27

chatgpt-codex-connector Bot reviewed Jun 3, 2026

View reviewed changes

cubic-dev-ai Bot reviewed Jun 3, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

feat(fonts): face-aware font-load planner (load used faces, not declared families)#3612
caio-pizzol wants to merge 3 commits into
caio/font-load-gate-t3from
caio/font-load-planner

caio-pizzol commented Jun 2, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jun 3, 2026

Uh oh!

cubic-dev-ai Bot left a comment

Uh oh!

cubic-dev-ai Bot Jun 3, 2026

Uh oh!

cubic-dev-ai Bot Jun 3, 2026

Uh oh!

cubic-dev-ai Bot Jun 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

caio-pizzol commented Jun 2, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant