refactor: extract font-readiness from PagedEditor into core controller

[jan-kubica]

First slice of the God-module extraction (audit's #1 structural item): carve orchestration out of packages/react/src/paged-editor/PagedEditor.tsx (~6,150 lines) into the framework-neutral core controller, leaving the React file as a lifecycle+DOM shell.

What moved

collectInitialLayoutFontFaces, collectInitialLayoutFontFamilies, documentFontsAreLoaded, getDocumentFontSet, waitForInitialLayoutFonts (+ their private helpers/constants) → @stll/folio-core/controller/fontReadiness. This logic decides which font faces a document needs (from its model + ProseMirror content), gates the first layout on them loading, and probes the browser font set.

Why this slice first

• Already framework-agnostic — imported only React-free core modules; nothing React/JSX touched it, it just lived in the .tsx.
• Behavior-preserving by construction — the existing font-collection unit test (which exercised these functions directly, no editor view) moves to core alongside the code and still passes. Call sites in PagedEditor are byte-identical; only the import source changed.
• Removes a latent dup — documentFontsAreLoaded is duplicated in the Vue adapter and is already an injected dependency of the core layout pipeline; a fast-follow can point Vue at this same module.
• Not the hot path — font collection runs once per load / on loadingdone, never in the pagination inner loop.

Boundary safety

document.fonts / window are only touched at call time (same pattern as the existing browserClock), so the module stays importable in non-browser hosts. react-free-core, layer-boundaries, and model-purity arch tests all stay green.

Verification

• Moved test passes (6 cases incl. 2 new: SSR/headless guard + null-model default floor)
• typecheck (all 7 packages), lint, format:check clean
• Arch tests green; layoutPipeline test (consumes the documentFontsAreLoaded seam) green
• Interaction behavior (font-ready re-layout) covered by the CI interactions job
• Changeset: core + react patch (internal refactor, no public API change)

Follow-ups (separate PRs): point the Vue adapter's documentFontsAreLoaded at this module; then the next slices (buildLayoutInputSignature, pointer pipeline, HF lifecycle).

Summary by CodeRabbit

• Bug Fixes

  • Improved initial document layout reliability by ensuring required fonts are detected and loaded before rendering.
  • Added support for server-side and headless environments where browser font APIs are unavailable.
  • Ensured the default layout font is included when document content is missing.

• Refactor

  • Centralized font-readiness handling for consistent behavior across supported integrations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: cab6f23c-b350-4684-aceb-54ff7bc28b1e

📥 Commits

Reviewing files that changed from the base of the PR and between 417f33d and 4ee4735.

📒 Files selected for processing (4)

• .changeset/extract-font-readiness-controller.md
• packages/core/src/controller/fontReadiness.test.ts
• packages/core/src/controller/fontReadiness.ts
• packages/react/src/paged-editor/PagedEditor.tsx

---

📝 Walkthrough

Walkthrough

Initial-layout font readiness utilities move from PagedEditor.tsx into a framework-neutral core controller. The controller collects and loads required font faces, supports headless environments, and is covered by relocated and expanded tests.

Changes

Font readiness extraction

Layer / File(s)	Summary
Core font readiness controller packages/core/src/controller/fontReadiness.ts	Adds browser/headless font detection, font loading with timeout handling, and exported readiness helpers.
Font face collection and tests packages/core/src/controller/fontReadiness.ts, packages/core/src/controller/fontReadiness.test.ts	Collects normalized font families and styles from document and ProseMirror content, deduplicates faces, and tests SSR behavior plus default-font handling.
React integration and release metadata packages/react/src/paged-editor/PagedEditor.tsx, .changeset/extract-font-readiness-controller.md	Uses the core helpers, removes the local implementation, retains suppression timing, and records patch releases for both packages.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant PagedEditor
  participant fontReadiness
  participant DocumentFonts
  PagedEditor->>fontReadiness: waitForInitialLayoutFonts(documentModel, pmDoc)
  fontReadiness->>fontReadiness: collect required font faces
  fontReadiness->>DocumentFonts: load font-face queries
  DocumentFonts-->>fontReadiness: readiness or timeout result
  fontReadiness-->>PagedEditor: boolean readiness result

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main refactor: extracting font-readiness logic from PagedEditor into the core controller.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/extract-font-readiness

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[gemini-code-assist]

Code Review

This pull request refactors the initial-layout font-readiness logic by moving it out of the React-specific PagedEditor.tsx component into a framework-neutral @stll/folio-core/controller/fontReadiness module, along with corresponding unit tests. Feedback on the changes highlights two potential runtime issues: a potential TypeError when accessing properties of documentModel.package if package is undefined, and a potential ReferenceError when calling window.setTimeout in non-browser environments (such as SSR or headless environments) where window is not defined.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.