Skip to content

fix(pptx): let a family's own faces say which one a run wants - #1072

Merged
DemchaAV merged 4 commits into
developfrom
fix/pptx-run-flag-from-the-registration
Nov 16, 2026
Merged

DemchaAV merged 4 commits into
developfrom
fix/pptx-run-flag-from-the-registration

Conversation

@DemchaAV

@DemchaAV DemchaAV commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

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:

the registration the plain run was after this change
one definition under Acme-Sans-Bold, a regular file and a bold one 544.80 — drawn from the bold program, 12.90pt over the frame 531.94, from the regular program; the bold paragraph does not move
one definition under Acme-Sans-Bold, a single regular file 522.73 — 9.17pt short of the frame 531.94
per face: Acme-Sans + Acme-Sans-Bold, one file each, one wordFamily 531.94 / 544.69, as laid out unchanged — and 12.88pt short of the frame if the flag is taken away

The "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.
PptxRenderEnvironment records which style elements a registered family's own
programs fill, and that decides what its name is allowed to say:

  • two or more programs carried — nothing. The family distinguishes its faces by the element a
    run asks for, and the decoration is what says which.
  • one program carried — the name may be read, but only if its suffix names that program's own
    style. This is the per-face registration above, where nothing but the name can name a face. A
    -Bold name over a regular program says nothing, and neither does one over a bold-italic
    program: a run flagged bold alone would ask for an element that deck does not hold.
  • none carried — every token. A family registered without sources travels by name only and has
    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, one
holding a regular file writes <p:regular/> alone — and it is the same read the embedder already
does 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.ascentPoints consequently takes the face as two parameters instead of reading
it 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 what
it 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.familyFor no longer takes a style suffix off a
name. Nothing reachable went through it: a registered family declares its own wordFamily() and
never 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-Regular and Roboto-Bold into 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:

  • the two cases that pinned the limit now assert the opposite, one per half — a family carrying two
    faces is not named by its name, and a family carrying one regular face may not be named bold;
  • the italic axis the same way, on a written deck;
  • the rule's unit case is now a hand-written expectation table (thirteen names) instead of a
    comparison against the stripping it can no longer use, so a spelling dropped from the suffix list
    reddens it too;
  • a new unit case pins the other half of the rule on its own — what a family's faces leave for the
    name — by passing that permission by hand;
  • familyFor on a suffixed name now returns the name, and the substitution-warning counts follow;
  • and two arms of the permission that a review round found untested — a per-face italic
    registration, and a single bold-italic program under a -Bold name — 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 both
sources 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=0 said.

The knowledge pack is regenerated in this PR: excluded.json gains the two new @Internal methods
by 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 — every
document 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 change
only 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.

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
DemchaAV marked this pull request as ready for review November 15, 2026 21:30
@DemchaAV
DemchaAV merged commit 8ba822d into develop Nov 16, 2026
13 checks passed
@DemchaAV
DemchaAV deleted the fix/pptx-run-flag-from-the-registration branch November 16, 2026 16:11
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