fix(pdf): resolve a chip against its own base, not against having one

[DemchaAV]

Why

A chip takes its direction from its first character, and that character settles only where the chip sits in the line — not what the chip holds. PdfParagraphFragmentRenderHandler.renderChip read that flag as the question of whether to resolve the span at all:

if (span.rightToLeft()) { text = BidiVisualOrder.visualize(sanitizedLogical); }

So a chip opening on Latin — "a בית" inside a right-to-left paragraph — is flagged left-to-right, skips the resolution entirely, and its Hebrew reaches the content stream in logical order. A PDF draws characters in the order it is given them, so the word is drawn backwards. The chip is the only span exposed to this: everything else is split at level boundaries by ParagraphWrapping and arrives single-level.

This is the other half of the atomicity gap #548 closed. That PR fixed the chip whose flag is right-to-left; this one fixes the chip whose flag is left-to-right and whose contents are not.

What changed

The direction is now the base the resolution runs against, not the question of whether to run it. BidiVisualOrder.visualize and mirrorRightToLeftLevels take that base instead of assuming right-to-left, and the PDF resolves a chip whenever BidiParagraphResolver.requiresBidi says its text needs it. Against a left-to-right base the Hebrew inside the chip is its own right-to-left run and is reversed; the Latin around it stays put. A wholly right-to-left chip is unchanged (same reverse-and-mirror it already had), and one carrying no such script is untouched.

BidiVisualOrder is unreleased — it ships in 2.2.0-SNAPSHOT — so the signature moves without a compatibility question.

The slide backend has the same gap, and gets the same fix. PowerPoint orders the Hebrew itself, so the letters need no help — but a neutral standing between two right-to-left words takes their level even under a left-to-right base, and PowerPoint does not mirror what it places. a בית > ספר reached the slide with its comparison facing the wrong way. Its gate is now span.rightToLeft() || requiresBidi(text) with the flag as the base, matching the PDF path.

An earlier revision of this PR claimed the opposite — that nothing inside such a chip resolves to a right-to-left level, so PPTX needed nothing. That was generalised from four probe samples (a בית, a (בית), (בית) a, a בית (x)) which all happen to be no-ops: a mirrorable neutral only takes the right-to-left level when it stands between two right-to-left runs, and none of the four had one. The claim was false and the revision removed a correct fix; both are restored here.

Verification

./mvnw clean verify over the full reactor — all 13 modules, BUILD SUCCESS. render-pdf 210, render-pptx 114, qa (visual baselines) 734.

Five cases. Four are checked against the state they are meant to catch; the fifth is a contract pin and is marked as one:

Case	Red without the fix
BidiVisualOrderTest.aLeftToRightBaseKeepsItsHebrewOnTheSideThatBaseGivesIt	yes — make baseOf ignore its argument
PdfRtlChipTest.aChipThatOpensOnLatinStillDrawsItsHebrewInReadingOrder	yes — restore the span.rightToLeft() gate
PptxRightToLeftFrameTest.aChipThatOpensOnLatinStillMirrorsANeutralBetweenTwoHebrewWords	yes — restore the span.rightToLeft() gate
PptxRightToLeftFrameTest.aChipThatOpensOnLatinMirrorsOnlyItsRightToLeftLevelPunctuation	yes — same
PptxRightToLeftFrameTest.aChipThatOpensOnLatinCarriesNothingToMirrorWhenItHoldsOnlyLetters	no — and it says so in its own comment

Only the last PPTX case is a contract pin rather than a regression guard — a chip of letters only is genuinely untouched either way, and its comment says so. The two carrying a mirrored character are real guards.

The PDF case reads the drawn glyphs by position (DrawnGlyphs) rather than extracted text — extraction goes through ActualText and the font's ToUnicode map, both of which deliberately answer with what the author wrote whichever order the page drew, so they cannot see this bug.

No shipped example or visual baseline pairs a chip with right-to-left text, so committed previews are untouched by construction.

[DemchaAV]

Confirmed and fixed — the Major stands, and my reasoning for dismissing it was wrong.

I re-probed with your example against the built classes:

a בית → changed=false
a בית > ספר → changed=true a בית < ספר
a בית (ספר) → changed=true a בית )ספר(
a בית > x → changed=false

A mirrorable neutral takes the right-to-left level only when it stands between two right-to-left runs. All four samples I had probed earlier lacked one, and I generalised "nothing inside such a chip resolves to a right-to-left level" from them — which is false, as you say: the Hebrew itself is level 1. On the strength of that generalisation an earlier revision of this PR removed a correct PPTX fix. Both are restored.

Major — renderChip now gates on span.rightToLeft() || BidiParagraphResolver.requiresBidi(text) with the flag as the base, as you specified. Three cases replace the one that could not see this:

stored	red with the old gate
a בית → a בית	no — pins a contract, and its comment says so
a בית > ספר → a בית < ספר	yes
a בית (ספר) → a בית )ספר(	yes

Reverting the gate fails exactly those two of eleven.

Minor — all four sites corrected. The BidiVisualOrder class javadoc no longer claims an always-right-to-left base or right-to-left-only runs, and now states the distinction directly: a left-to-right base is not a left-to-right run, Hebrew inside such a chip resolves to level 1, and the base decides how the runs order rather than whether they exist. Same correction in CHANGELOG.md, in the comments at both seams, and in the PPTX test. I grepped the repository for the false invariant's phrasing — no other copy.

Full reactor clean verify, 13/13 modules, BUILD SUCCESS; git diff --check clean, no baselines touched.