From f4fac05b7ef054cbc55a32ea83d6f44fa5c599c4 Mon Sep 17 00:00:00 2001 From: krflol Date: Wed, 7 Oct 2026 23:31:42 -0500 Subject: [PATCH] Document independent font synthesis controls in 2.5.16 --- docs/engine/font-registration.md | 66 ++++++++++++++++++++++++++++++-- 1 file changed, 63 insertions(+), 3 deletions(-) diff --git a/docs/engine/font-registration.md b/docs/engine/font-registration.md index ce7ce01..7ece019 100644 --- a/docs/engine/font-registration.md +++ b/docs/engine/font-registration.md @@ -1,6 +1,6 @@ # Registering regular and italic fonts -Reference imported from [v2.5.8](https://github.com/fullbleed-engine/fullbleed-official/blob/f9f1b56f550237c924254ccd7718cc852a06692d/docs/font-registration.md). Check the installed runtime for your exact version. +Reference imported from [v2.5.16](https://github.com/fullbleed-engine/fullbleed-official/blob/1813df2150cbad6213dff78963df77a1c3e1c096/docs/font-registration.md). Check the installed runtime for your exact version. Register the font files your document uses with `PdfEngine(font_files=[...])`, `font_dirs=[...]`, or an `AssetBundle`. Fullbleed reads these assets directly; @@ -20,7 +20,7 @@ and typographic family names are recognized. For example, after registering `DMSerifDisplay-Regular.ttf` and `DMSerifDisplay-Italic.ttf` from this repository's -[`design_showcase/fonts`](https://github.com/fullbleed-engine/fullbleed-official/blob/f9f1b56f550237c924254ccd7718cc852a06692d/examples/design_showcase/fonts): +[`design_showcase/fonts`](https://github.com/fullbleed-engine/fullbleed-official/tree/1813df2150cbad6213dff78963df77a1c3e1c096/examples/design_showcase/fonts): ```css body { font-family: "DM Serif Display"; font-style: normal; } @@ -57,8 +57,68 @@ default can change appearance and line breaks when the regular face is also registered. Review existing PDF baselines when upgrading. To intentionally use italics, set `font-style: italic` or map the exact face with `@font-face`. -The installed-wheel [family smoke check](https://github.com/fullbleed-engine/fullbleed-official/blob/f9f1b56f550237c924254ccd7718cc852a06692d/tools/smoke_font_families.py) +The installed-wheel [family smoke check](https://github.com/fullbleed-engine/fullbleed-official/blob/1813df2150cbad6213dff78963df77a1c3e1c096/tools/smoke_font_families.py) compares embedded face names, extracted text, and native/PDFium previews against explicit-face controls for file, directory, bundle, fixed-template, and reflow rendering. This is a focused regression check, not a claim of complete CSS font matching conformance. + +## Controlling synthetic styles + +Starting with Fullbleed 2.5.16, weight and style synthesis can be controlled +independently. When the selected registered face lacks a requested bold or +slanted style, `font-synthesis` controls which approximations Fullbleed may draw: + +```css +/* Allow synthetic italics only. */ +.label { + font-weight: 700; + font-style: italic; + font-synthesis: style; +} + +/* Allow synthetic bold only. */ +.total { + font-weight: 700; + font-style: italic; + font-synthesis: weight; +} + +/* Disable all synthetic variants. */ +.exact { font-synthesis: none; } + +/* Disable artificial slant alone. */ +.upright { font-synthesis-style: none; } +``` + +The shorthand independently sets `weight`, `style`, `small-caps`, and `position`; +omitted controls become `none`. The longhands `font-synthesis-weight`, +`font-synthesis-style`, `font-synthesis-small-caps`, and `font-synthesis-position` +accept `auto` or `none`. The style longhand also accepts `oblique-only`, which +permits a synthetic `font-style: oblique` but does not synthesize an italic +request. These properties inherit. `initial` restores all synthesis controls; +`auto` is a longhand value, not a valid shorthand value. + +The controls do not suppress a real bold or italic face already selected by +font matching. SVG text inherits the document's weight/style controls and +supports overrides in its own inline and embedded CSS. Small-cap controls govern +HTML's existing synthetic small caps; position controls govern the default +footnote-call superscript fallback. They do not add general OpenType small-cap +or positional-substitution support. + +Synthetic small caps with fixed binding slots remain unsupported; use compiled +reflow for those templates. The finalized-PDF preview reader can also omit the +synthetic-bold stroke on fixed binding slots; inspect the emitted PDF in an +independent viewer when using that combination. + +The [synthesis smoke check](https://github.com/fullbleed-engine/fullbleed-official/blob/1813df2150cbad6213dff78963df77a1c3e1c096/tools/smoke_font_synthesis.py) +registers a known regular font and compares each combination with explicit style +controls in ordinary, fixed, and reflow output. It retains 130 cases / 221 pages, +with PDFs, extracted text, and native, finalized, and PDFium previews; small-cap +positive controls cover ordinary and reflow output. All 130 PDFs and preview +case sets match across Windows and Linux in the release-preparation CI. + +[Download the executable evidence bundle](https://github.com/fullbleed-engine/fullbleed-official/releases/download/v2.5.16/fullbleed-2.5.16-font-synthesis-evidence.zip), +inspect the [verification record](https://github.com/fullbleed-engine/fullbleed-official/releases/download/v2.5.16/fullbleed-2.5.16-verification.json), +or read the [2.5.16 release notes](https://github.com/fullbleed-engine/fullbleed-official/releases/tag/v2.5.16). +The comparisons verify the named controls, not complete CSS Fonts conformance.