Repository navigation
fix(pptx): let a family's own faces say which one a run wants - #1072
Merged
Merged
Conversation
A run's bold and italic flags are the span's decoration plus a style suffix at the end of the name the family was registered under. The name was read even for a family that distinguishes its faces itself, and then it asked the viewer for a face the page had not measured: a single definition under `Acme-Sans-Bold` holding a regular file and a bold one flagged every run of itself, the plain ones included, and one holding a single regular file asked for a bold face it has not got. 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. The two-face definition drew its plain paragraph from the bold program at 544.80, 12.90pt over the frame the engine had sized for it; on the same deck with that run's flag cleared, which is what is written now, it drew 531.94 from the regular program and the bold paragraph did not move. The one-face definition drew 522.73, 9.17pt short of the frame, and 531.94 with the flag cleared. So the name is read only where the family cannot answer. A family carrying two or more programs says nothing by its name; one carrying a single program may be named in the style that program itself is; one carrying none — registered without sources, travelling by name only — has nothing else. The style a carried program is comes from the program and not from the slot a caller filled, because the two need not agree: the file passed as a family's regular source may be a bold program, which is exactly the per-face registration this reads. That registration still asks for its face, and still needs to: measured, its paragraph comes out 12.88pt short of the frame, drawn from the regular program, with the flag taken away. One answer, asked once. The flag decides three things — the attribute a run carries, the face recorded as drawn, and the viewer ascent the frame is seated on — and all three now ask the render environment rather than reading the style again. `PptxViewerMetrics.ascentPoints` therefore takes the face as two parameters instead of reading it off the style: its javadoc says it is the one seat formula the render and the geometry mirror in the tests share so the two cannot drift line by line, so the mirror moved with the signature and passes what it writes on the run it checks. `PptxFontMapping.familyFor` no longer takes a style suffix off a name, a branch nothing reachable went through: a registered family declares its own `wordFamily()` and never arrives there, a bundled name carries no suffix, and a name nothing registers has to resolve in the font library to be laid out at all. One observable thing goes with it — the substitution warning used to group `Roboto-Regular` and `Roboto-Bold` into one line and now counts such spellings apart, neither of which can reach a render. Deck bytes change for a family registered under a name carrying a style token that the family's own faces already answer for. No preset or example here registers such a name.
A review round found the permission too loose in one arm and the prose behind it in five places. The loose arm: a family carrying a single bold-italic program was granted every token, so a name ending `-Bold` over it flagged the run bold alone — asking the viewer for an element that deck does not hold, which is the defect this change exists to close, one axis over. The permission is now the rule in one line: the name speaks only where it names exactly the face the family carries, or where the family carries none. `PptxFontMapping.namesExactly` answers that by reading the name's suffix as a pair, so a name claiming more than the family holds says nothing — a `-Bold` name over a regular program, over a bold-italic one, or an `-Italic` name over a bold one. Two arms had no deck behind them, and a sabotage of the italic one stayed green: a per-face italic registration, which is the exact mirror of the bold case this change pins, and the bold-italic corner above. Both now have one. The prose: the class contract of `PptxFontMapping` still described the stripping this change deletes and said nothing of the gate it adds; the comment above the substitution warning still explained the facet grouping that went with the stripping; the test javadoc for the suffix case still said the flag comes "from nothing else"; the previous CHANGELOG entry still called the suffix list shared with the stripping; and the capability matrix cell still stated the name's reading unconditionally while its details entry had moved. Each now says what the code does, and the details entry keeps the suffix-position rule it had dropped. Smaller corrections of the same kind. The field recording what a family carries said an absent entry means a refusal, where it also covers a bundled family, a family registered without sources and a hand-over that failed part way — which leaves what it took, so the name does speak over a face in that one case. The seat formula's javadoc said the geometry mirror passes what it writes on the run; it passes what it expects, which is the same thing only because its fixtures carry no style suffix, and the mirror's own comment claimed its answer was production's for every fixture, where one of them registers four faces. One figure was attributed to this change's deck and was measured on the previous change's. The CHANGELOG said a DOCX corpus evidences deck bytes, which it cannot.
The pack is generated from the compiled classes and gated like a lockfile, and the gate reported it out of date: `excluded.json` lists what the surfaces leave out and why, so two new `@Internal` methods belong in it by name — `PptxRenderEnvironment#runIsBold` and `#runIsItalic`, the one place the backend now answers which face a run asks for. Only that file moves, and only by those two entries and the count. The other generated files come back byte-identical apart from line endings, which this repository does not restage. A commit of its own rather than folded into the change, because the change was already pushed for review; the gate's own check runs on the tree, not on the commit boundaries, and reports the pack current again.
DemchaAV
marked this pull request as ready for review
November 15, 2026 21:30
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
A PPTX run's bold and italic flags are what a viewer picks the face by, and they came from the
span's decoration plus a style suffix at the end of the name the family was registered under. The
name was read even where the family can answer the question itself, and then the deck asked for a
face the page had never measured.
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 so that no other
build of them could pass for them. The page laid out 531.90 plain and 544.68 bold:
Acme-Sans-Bold, a regular file and a bold oneAcme-Sans-Bold, a single regular fileAcme-Sans+Acme-Sans-Bold, one file each, onewordFamilyThe "after" column is measured, not derived: the first row is that deck with the plain run's flag
cleared — exactly what is written now — exported through PowerPoint again.
What changed
The name speaks only where it names exactly the face the family carries, or where the family
carries none.
PptxRenderEnvironmentrecords which style elements a registered family's ownprograms fill, and that decides what its name is allowed to say:
run asks for, and the decoration is what says which.
style. This is the per-face registration above, where nothing but the name can name a face. A
-Boldname over a regular program says nothing, and neither does one over a bold-italicprogram: a run flagged bold alone would ask for an element that deck does not hold.
nothing else; so does a bundled or standard-14 name, which no registration covers, and a family
the presentation did not take.
The style a carried program is comes from the program, not from the slot a caller filled,
because the two need not agree: the file passed as a family's regular source may be a bold program.
That is visible in the deck — a definition holding one bold file writes
<p:bold/>alone, oneholding a regular file writes
<p:regular/>alone — and it is the same read the embedder alreadydoes to seat a face, so nothing is parsed twice.
One answer, asked once. The flag decides three things: the attribute a run carries, the face
recorded as drawn (which picks what a bundled family is embedded with), and the viewer ascent the
frame is seated on. All three now ask
PptxRenderEnvironment.runIsBold/runIsItalic.PptxViewerMetrics.ascentPointsconsequently takes the face as two parameters instead of readingit off the style — and that formula is deliberately shared, its javadoc saying it is the one seat
formula the render and the geometry mirror in the tests use "so the two cannot drift line-by-line".
Both moved together: the production caller passes the environment's answer, and the mirror
(
PptxGeometryAssertions, plus the two geometry tests that call the formula directly) passes whatit writes on the run it is checking. They still compute the same seat, which the geometry suites
assert as they did before — they are green unchanged.
A dead branch goes with it.
PptxFontMapping.familyForno longer takes a style suffix off aname. Nothing reachable went through it: a registered family declares its own
wordFamily()andnever arrives, a bundled name carries no suffix, and a name nothing registers has to resolve in the
font library to be laid out at all. One observable thing changes — the substitution warning used to
group
Roboto-RegularandRoboto-Boldinto a single line, and now counts such spellings apart.Neither can reach a render; the test that pinned the grouping now says so.
The suffix rule stays, with its condition stated: a style suffix is still what the name is read
for, and now only where the family carries one program of that style, or none at all.
Verification
./mvnw -B -ntp test -pl :graph-compose-render-pptx— 200 tests, none skipped.Six existing tests moved, every one because it pinned the behaviour this change relocates, and each
says so in its own words:
faces is not named by its name, and a family carrying one regular face may not be named bold;
comparison against the stripping it can no longer use, so a spelling dropped from the suffix list
reddens it too;
name — by passing that permission by hand;
familyForon a suffixed name now returns the name, and the substitution-warning counts follow;registration, and a single bold-italic program under a
-Boldname — now have a deck case each.A sabotage of the italic arm had stayed green before them.
Three sabotages, each turning exactly one named deck case red (
tests=1 failures=1) with bothsources byte-identical afterwards: letting a two-face family's name speak again, granting a carried
regular program the right to be named bold, and reading the name in the mapping without asking
the registration. The second had to be re-aimed: the first attempt broke the branch beside the one
the fixture exercises and the case stayed green, which is what
tests=1 failures=0said.The knowledge pack is regenerated in this PR:
excluded.jsongains the two new@Internalmethodsby name and its count, which is the whole of it — the first gate run failed on exactly that, with
the pack reporting itself out of date, and reports itself current again after.
The 105-document DOCX corpus, exported from this branch and from
develop:unchanged— everydocument byte-identical with the same 1718 report notes, 0 added and 0 removed. No DOCX path is
touched.
The full reactor gate on the final head:
GATE PASS, the examples suite included. Deck bytes changeonly for a family registered under a name carrying a style token its own faces already answer for,
and no preset or example here registers such a name — which is the sweep, not the gate: example
decks stamp live timestamps and are not byte-comparable across runs.