Skip to content

feat: the host supplies font files, and documents are laid out once they are loaded - #39

Open
pierreneter wants to merge 2 commits into
mainfrom
feat/host-fonts
Open

pierreneter wants to merge 2 commits into
mainfrom
feat/host-fonts

Conversation

@pierreneter

Copy link
Copy Markdown
Member

Part of #30: plan item 4, fonts. Items 1 to 3 (splitting blocks across pages, keep rules) are a separate branch, and the exact layout mode is later work.

The host can give the viewer font files. The views load them with FontFace, and the DOCX view measures and paginates a block only once the fonts it uses are ready, or have failed or timed out.

API

The new fonts prop on DocViewer takes a list of FontSource:

{ family, src, weight?, style?, unicodeRange? }
  • src is a URL string, an ArrayBuffer, an ArrayBufferView or a Blob. All of these can be sent to a worker, so the same list can later be handed to the worker for the exact mode.
  • The embed element takes fonts as an attribute (a JSON list of fonts by URL) or as a property (bytes too).
  • FontSource is exported from the package root and from core.
  • The library ships no font files. docs/api.md has an example with the OFL fallbacks: Carlito, Caladea, and Liberation Sans, Serif and Mono.

How fonts are matched

Matching uses the stacks cssFont() already builds:

  • A font declared as Carlito serves documents in Calibri, but only where Calibri is not installed.
  • Declaring it under the original name (Calibri) also works, and then it wins over an installed Calibri.

Loading

  • Shared set: there is one set of faces per page. Each face is reference-counted by the viewers that declare it, and removed from document.fonts when no viewer declares it any more.
  • Fetching: faces are added unloaded, so nothing is fetched until a shown document uses the family. There is no <style> injection.
  • Failure: after a 3 s timeout, or on a load error, the document is laid out with the fallback. The viewer prints an [office-engine] warning, and a load error also calls onError.
  • Late fonts: the view measures again when a late font arrives. That includes a font the page itself provides through @font-face (loadingdone), which today leaves stale heights.
  • During a re-measure: pages keep their old heights until the new ones are known. The block in view keeps its place on screen, and caret and selection are kept.
  • Print gets the loaded host fonts, so printing and PDF break lines like the screen does.

XLSX and PPTX

XLSX: when the declared fonts named by the styles are ready, or a late font arrives, the cache of digit widths is cleared and numbers are fitted to their columns again. The grid does not wait for fonts before it first paints.

PPTX: unchanged. The browser lays slide text out again when the font arrives.

Security

Font URLs come only from the host. A crafted DOCX with embedded-font references to an external URL, an internal .odttf and a font name that looks like url() causes no request, and the name stays one quoted family name. This is covered in e2e/security.spec.ts and test/security.test.ts.

Tests

test/fonts.test.ts (14 tests):

  • matching through the fallback table;
  • descriptors, URL escaping, the DOCX stack walker;
  • the shared set with a fake FontFace: sharing, release, timeout then late arrival, errors, Blob versus buffer.

test/font-builder.ts builds a TrueType font of a few KB at test time, with very wide glyphs, so no binary is committed.

e2e/fonts.spec.ts (10 tests in Chromium):

  • nothing is fetched when no font is declared, or when a declared font is unused;
  • text is measured with the font;
  • the page count changes in the expected direction;
  • recorded every frame: no wrong page count before the font is ready;
  • a bytes source;
  • a Carlito declaration is fetched for a Calibri document;
  • a 404 falls back, with one onError and one warning;
  • a slow font: laid out again, and the paragraph in view stays put;
  • the selection survives a re-layout;
  • a late @font-face from the page triggers a re-measure;
  • XLSX numbers are fitted again.

Also new: the embed attribute and property in e2e/embed.spec.ts.

On main, both late @font-face tests fail with stale layout. The tests that use the new prop fail there too.

Results

In the Linux test VM with Bun 1.4.4.

Check Result
typecheck clean
bun test 1207 pass, 0 fail
build ok

Then these e2e specs, all with 0 fail:

Spec Pass
e2e/fonts.spec.ts 10
e2e/docx.spec.ts 23
e2e/docx-page.spec.ts 2
e2e/viewer.spec.ts 27
e2e/embed.spec.ts 4
e2e/sdk.spec.ts 1
e2e/security.spec.ts 8
e2e/xlsx.spec.ts 41
e2e/pptx.spec.ts 11
e2e/docx-hf.spec.ts 2
e2e/docx-qa2.spec.ts 13
e2e/docx-table.spec.ts 4
e2e/docx-track.spec.ts 2
e2e/file-menu.spec.ts 29
e2e/comments.spec.ts 6

After the rebase onto af19290, which only changes package.json, I re-ran typecheck and the font unit tests.

Not done

  • Embedded fonts are not read. They were not read before either: neither DOCX fontTable.xml embeds nor PPTX embeddedFontLst.
  • Fonts loaded per family: every declared face of a matched family is loaded, not only the weights and styles the text uses.
  • Waiting per batch: a pending font holds back its whole measuring batch, for at most 3 s.
  • Standalone views: DocxView and XlsxView used without DocViewer get no host fonts. They still measure again when the page's own fonts arrive late.
  • XLSX:
    • a row grown once for rotated text is not measured again;
    • column fit and wrap heights use whatever fonts are loaded at that moment.
  • Print gets host fonts only. The page's own @font-face fonts are still absent there, as before.

Merging with items 1 to 3

The DocxView.tsx changes are in one place:

  • a block right after the measure queue is built;
  • the fontsReady gate on the measuring container;
  • a separate scroll-anchor effect.

paginate.ts and render.tsx are not touched. The scroll anchor's blockTop sums block heights from the page's start; once paragraphs are split into fragments it has to account for them.

🤖 Generated with Claude Code

pierreneter and others added 2 commits November 20, 2026 11:58
…hey are loaded

DocViewer's `fonts` (and the `fonts` attribute / property of <office-viewer>): font files by URL or as bytes, under a
document's own font name or the metric-compatible fallback cssFont() names after it (Carlito for Calibri, Caladea,
Liberation). They are added to the page's fonts with the FontFace API, shared by the viewers that declare them, and
fetched only when a document's text is set in their family. The DOCX view measures blocks once the fonts they use are
loaded (a font that fails is reported to onError, one slower than 3 s is not waited for), and measures them again
when a font arrives late, the page's own web fonts included, keeping the block in view and the selection. XLSX fits its
numbers again; printing uses the same files. Fonts are never taken from a document.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant