Skip to content

fix(pptx): read a run's face from a style suffix, not from anywhere in the name - #1071

Merged
DemchaAV merged 2 commits into
developfrom
fix/pptx-style-token-in-registered-name
Nov 15, 2026
Merged

DemchaAV merged 2 commits into
developfrom
fix/pptx-style-token-in-registered-name

Conversation

@DemchaAV

@DemchaAV DemchaAV commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

Why

A PPTX deck asks the viewer for a face with a bold or italic flag on each run. That flag was set by
any bold, italic or oblique anywhere in the name a family was registered under, so a
family registered as Acme Sans Bold, or Boldoni Text, carried it on every run of itself —
including the plain ones the page had measured in the regular program. The name is the caller's own
choice, so the consequence was theirs.

Measured in PowerPoint 16, one deck per PowerPoint instance, a 45-character line at 20pt, under a
declared name no font on the machine answers to (checked in the font folders, both font registry
keys and Office's cloud-font cache), with the two faces marked in one glyph by +400 and +800
units so that no other build of them could pass for them. The page laid out 531.90 plain and 544.68
bold:

the family flags written the plain line drawn from
a name with no token, two faces false / true 531.94 ✓ the regular program, as laid out
Acme Sans Bold, two faces true / true 544.80 — 12.90pt wider than the frame the bold program (A=2189 in the subset PowerPoint embedded)
Acme Sans Bold, one regular face true / true 522.73 — 9.17pt short of the frame the regular program, same size, 45 glyphs of the same widths, the line simply ending earlier; why was not measured
the same, flag off the plain run false / true 531.94 ✓ restored the regular program

Two findings shaped the fix rather than decorating it.

The case the mapping's test defended is not reachable. That test pins
isBold(FontName.of("Acme-Sans-Bold")) for a family nobody registered, on the grounds that a
viewer holding the family needs the flag. Such a style never reaches the backend: the engine fails
the layout first — IllegalStateException: Font not found for style: Lato-Bold — so no deck is
written. The reachable form of the same intent is a registration per face: Acme-Sans with the
regular file beside Acme-Sans-Bold with the bold one, both declaring one wordFamily, neither
paragraph carrying a decoration. There the name really is the only signal, and it is load-bearing:
measured, that paragraph comes out 12.88pt short of the frame, from the regular program, with
the flag taken away.

Nothing in this repository is affected. Of the 50 FontName constants, the nine that carry a
style token are the standard-14 aliases, which this read already excluded; no preset and no example
registers a family under a name with a token (Acme-Sans-Bold, Acme-Sans-Italic and
Roboto-Bold appear only in render-pptx tests and one comment). The flag's old branch was
reachable only through a caller's own FontName.of(...).

What changed

  • The flag comes from a style suffix at the end of the name and from nothing else, read off the
    one list of suffixes PptxFontMapping already had. The rule narrows which names speak; what a
    deck declares is a separate thing and this does not touch it — for a registered family that
    is wordFamily(), which defaults to the registered name with the suffix left on, and the javadoc
    says so rather than claiming the two readings now agree. (stripStyleSuffix is reached only by a
    name no registration covers, which is a dead path on its own and is left alone here.)
  • -Regular ends the name and contributes no face, which is what keeps "ends in something" from
    reading as "is bold"; the invariant test covers that corner explicitly.
  • The standard-14 exclusion is untouched: those names are family aliases and the engine measures
    them with regular metrics.
  • docs/font-coverage.md gains a section for the caller — which shape of name speaks, what the old
    behaviour cost in points, the spelling that loses the flag, and the limit below. The PPTX
    font-portability entry of the capability details gains a sentence tying the run's flag to the
    style element a face is declared under, and links to it.
  • The mapping's own test keeps binaryFamilySuffixStillCarriesTheFace and now names the reachable
    shape and the measured cost of dropping it.

The known limit, with its number

A single definition under a name ending in -Bold that holds both a regular and a bold file
still flags every run of itself. Measured on its own deck, not inferred from the one above: the
plain paragraph is drawn from the bold program at 544.80 where the page laid out 531.90 — the same
12.90pt over the frame. So is a definition under such a name holding a regular file alone.

A rule on the name cannot reach this: the style token in the name and the face the file holds are
never compared anywhere. Closing it means keying the flag on the registration — how many faces
the definition holds, and which of them a run was measured in — which is a different change. The
limit is stated in the javadoc, on the font-coverage page, and pinned by a test so that it is a
known state rather than something the next reader discovers.

A review round of this change caught the first version of that test asserting this arrangement as
the desired outcome. It is the defect, measured, and it is now labelled as the limit.

One spelling the first draft of this rule got half right

Acme-Sans-Bold-Italic — the pair spelled with an inner hyphen — matched -italic and nothing
else, so the run asked for an italic face that is not bold where the page had measured the
bold-italic program: the same defect in the lighter direction. The list now holds -Bold-Italic and
-Bold-Oblique ahead of -Italic and -Oblique, which is why its order is part of the rule and
says so. A unit case pins both halves of that face, and familyFor strips such a name to the
family rather than to Acme-Sans-Bold.

Verification

./mvnw -B -ntp test -pl :graph-compose-render-pptx — 196 tests, none skipped, up from 188.
Eight new cases. Three in PptxFontMappingTest: a token the name keeps is not a face, over the
four spellings a caller reaches; the rule itself, asserted as "flagged exactly where this class's
own stripping takes a suffix off the name" over twelve names including -Regular; and the
inner-hyphen pair. Five in PptxRunFlagFromTheNameTest, which reads the written runs through POI
as its neighbours do: a two-face family under a name that merely contains the token, the per-face
registration, the limit above, a name with no token as the floor, and the same rule on the italic
axis, since the mapping reads two tokens.

The documentation guards in qa: DocxCapabilityMatrixGuardTest (14) and DocsBoldFaceGuardTest
— the capability matrix cell and its details entry agree on the mark, which that guard enforces.

Two sabotages, each turning exactly one named deck-level case red (tests=1 failures=1) with the
source byte-identical afterwards: restoring the substring read makes the kept-token case fail, and
dropping -bold from the suffix list makes the per-face case fail. One per direction, because
either reading can break the rule — and the unit invariant test cannot catch the second, since both
readings move together there, which is why the deck cases exist.

The 105-document DOCX corpus, exported from this branch and from develop: unchanged — every
document byte-identical with the same 1718 report notes, 0 added and 0 removed. No DOCX path is
touched; the export is reported because the claim is cheap to check.

The full reactor gate on the final head: GATE PASS — core, the three render backends, templates,
testing, qa and coverage, the knowledge-pack checks, core javadoc, then the install and the
examples suite. That shows the examples still render; it does not compare their bytes, which are
not comparable across runs here, since the deck writers stamp live timestamps. The reach claim
rests on the sweep above instead: no example registers a name this change can reach.

…n the name

A deck asks the viewer for a face with a flag on each run, and that flag was set
by any `bold`, `italic` or `oblique` anywhere in the name a family was registered
under. A family registered as `Acme Sans Bold`, or `Boldoni Text`, therefore
carried the flag on every run of itself — the plain ones included, which the page
had measured in the regular program. The name is the caller's own choice, so the
consequence was theirs.

Measured in PowerPoint 16 on a 45-character line at 20pt, one deck per PowerPoint
instance, under a declared name no font on the machine answers to — checked in the
font folders, both font registry keys and Office's cloud-font cache — with the two
faces marked in one glyph so that no other build of them could pass for them. The
page laid out 531.90 plain and 544.68 bold. A family of two faces under such a
name had its plain paragraph drawn from the bold program at 544.80, 12.90pt wider
than the frame the engine had sized for it. A family of one regular face under the
same name had that line drawn from the regular program at the same size, 45 glyphs
of the same widths, yet ending at 522.73 — 9.17pt short of the frame; why it ends
earlier was not measured. Taking the flag off the plain run drew both at 531.94,
within four hundredths of what the page laid out.

The flag now comes from a style suffix at the end of the name and from nothing
else, read off the one list of suffixes this class already had. What a deck
declares is a separate thing and this rule does not touch it: for a registered
family it is `wordFamily()`, which defaults to the registered name with the suffix
left on.

The arrangement this keeps is the one where the name is the only signal there is:
a registration per face, `Acme-Sans` holding the regular file beside
`Acme-Sans-Bold` holding the bold one, under one `wordFamily`, with no decoration
on either paragraph. Measured, the second comes out 12.88pt short of the frame,
drawn from the regular program, when the flag is taken away. The case the
mapping's test defended before — an unregistered `Acme-Sans-Bold` on a machine
that has the family — is not reachable at all: the engine fails the layout with
"Font not found for style" before a deck is written, so the test is kept and its
reachable form named.

What this costs: the same per-face registration spelled with a space loses the
flag. The spelling is the caller's, and the font-coverage page says so with the
number.

What it does not reach, measured rather than reasoned and pinned by a test: a
single definition under a name ending in `-Bold` that holds both a regular and a
bold file still flags every run of itself, and its plain paragraph is drawn from
the bold program at the same 12.90pt over the frame. So does such a name over a
regular file alone. The style token in the name and the face the file holds are
never compared, and closing that means keying the flag on the registration rather
than on the name.

Deck bytes change only for a family registered under a name carrying a style token
away from its end. Of the 50 `FontName` constants the nine that carry one are
standard-14 aliases, which this read already excluded, and no preset or example
here registers such a name.
…ecides

A review round of this change found the rule right and three of its sentences
wrong, one of them the claim this change had already retracted once.

`Acme-Sans-Bold-Italic` matched `-italic` and nothing else, so a run under that
name asked the viewer for an italic face that is not bold where the page had
measured the bold-italic program — the same defect as before, in the lighter
direction, for a spelling that used to work. The list holds `-Bold-Italic` and
`-Bold-Oblique` ahead of the shorter two now, which makes the order part of the
rule, and the field says so instead of claiming the order does not matter.

What decides is the suffix, not where the word sits. "A style token away from the
end of the name" excluded `Acme Sans Bold`, which ends in the word and is the
very family the measurements are about; the CHANGELOG, the javadoc, the
font-coverage page and the capability details now name the suffixes and say that
the hyphen is what the rule reads, not the position.

The test javadoc still said the flag and the declared family are two readings of
one name made to agree. They are not: a registered family declares its
`wordFamily()` with the suffix left on, which the production javadoc in this same
change already says. The invariant case is renamed for what it pins — the flag
against this class's own stripping — and its failure message no longer calls that
the declared name.

Three things take this flag and only one was named: the run attribute, the record
of which faces a bundled family is embedded with, and the viewer ascent that
seats the frame. The javadoc names all three and says which of them the
measurements read; the CHANGELOG says the bundled face set cannot move here,
since no bundled name carries a token at all.

The standard-14 exclusion is by the name's beginning, so a caller's own
`Courier Prime-Bold` never reaches the suffix read. The javadoc said "the
standard-14 variants and their siblings", which reads as a closed set, and now
says what the check is.

Two cases added where the rule was pinned on one axis only: the inner-hyphen pair,
and the italic axis read off a written deck.
@DemchaAV
DemchaAV marked this pull request as ready for review November 15, 2026 19:28
@DemchaAV
DemchaAV merged commit 39072d9 into develop Nov 15, 2026
13 checks passed
@DemchaAV
DemchaAV deleted the fix/pptx-style-token-in-registered-name branch November 15, 2026 19:32
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