fix(render): let a reordered line's frames say which way they read — and a chip keep its meaning

CHANGELOG.md

@@ -36,8 +36,9 @@ follow semantic versioning; release dates are ISO 8601.
  them; PowerPoint and Word have their own bidirectional engines, so the text reaches
  them in logical order rather than rewritten. Word is told the paragraph's base
  direction with `w:bidi`, which is the only way it can lay out a line that opens on a
- neutral character; PowerPoint needs no such mark, because each span is pinned in an
- absolute frame at the position the page gave it.
+ neutral character; PowerPoint is told the same thing per frame, because pinning a span
+ where the page put it settles the order *across* the line but not which side a neutral
+ falls on *inside* a frame.
 
  The bidirectional formatting characters (`U+200E`, `U+200F`, `U+061C` and the
  embeddings and isolates) now survive control-character sanitizing until the algorithm
@@ -196,6 +197,50 @@ follow semantic versioning; release dates are ISO 8601.
  While the size path was being touched: a run's size is now written as the half-points
  `w:sz` and `w:szCs` actually count, rather than rounded to whole points first. A 9.5pt
  label — the timeline builder writes two — was reaching Word as 10pt.
+- **A right-to-left slide's punctuation faces the way the line reads.** A line that gets
+ reordered reaches PowerPoint as one frame per span, each pinned where the layout put it,
+ so the order *across* the line is settled before PowerPoint sees it. What was not
+ settled is what happens inside a frame: the text handed over is logical, the frame
+ declared no base direction, and a frame holding a lone bracket had nothing to resolve
+ against — so a parenthesis closing a right-to-left line was drawn facing the way it was
+ typed rather than the way the line reads, while the same document as a PDF was correct.
+
+ Each frame carrying right-to-left text now declares it, which settles *placement*: the
+ em-dash of a mixed line moved to the side it belongs on the moment that was written.
+ That is necessary and not sufficient. Measured on a slide, PowerPoint places a neutral
+ from the declared direction but does not go on to mirror it, so the character is swapped
+ before it is handed over, at the same seam the PDF backend swaps it.
+
+ The cost is worth naming: a copy out of the slide carries the mirrored character rather
+ than the typed one. The swapped set is document punctuation and includes `<` and `>`, so
+ a comparison written between two Hebrew or Arabic words copies out reversed. A `>`
+ surrounded by Latin does not, because the wrapper gives that stretch a left-to-right span
+ of its own and the swap is keyed to the span's direction. Left-to-right frames are
+ untouched.
+
+ This rests on PowerPoint not applying UAX #9 L4 itself, which is measured rather than
+ specified. A viewer that does apply it mirrors the character a second time and draws the
+ original bug; the assumption is recorded in the backend capability matrix.
+
+- **A chip that mixes directions is drawn the way each of its parts reads — in both
+ backends.** A chip is one rounded fill, so the wrapper cannot split it at a level
+ boundary the way it splits plain text; it reaches the renderer whole, carrying its
+ first character's level. The PDF backend reversed and mirrored it whole, and that
+ inverted meaning, not just shape: a chip reading `(a > b)` after a Hebrew word drew as
+ `(b < a)` — operands swapped, comparison flipped — while the chip's interior is
+ left-to-right text that UAX #9 neither reorders nor mirrors.
+
+ The engine now resolves the chip's own embedding levels (`BidiVisualOrder`), and each
+ backend takes from that resolution exactly what its viewer lacks. The PDF draws
+ characters in the order it is given them, so it gets the full visual transform —
+ runs reordered, right-to-left ones reversed and mirrored; for a single-level chip that
+ is exactly the old reverse-and-mirror, so a wholly-Hebrew chip is unchanged, and a
+ chip holding `שנה 2026` no longer draws its year backwards. The slide backend keeps
+ the chip's text **logical** and its frame's direction declared, because PowerPoint
+ reorders strong right-to-left characters by what they are, not by what the frame says
+ — a pre-reordered string would come back with its Hebrew re-reversed. What PowerPoint
+ was measured not to do is the mirroring, so pairs are swapped for it — but only on the
+ levels UAX #9 mirrors, which is what keeps the interior's `>` a `>`.
 
 ### Fonts
 

core/src/main/java/com/demcha/compose/document/layout/ParagraphWrapping.java

@@ -939,8 +939,10 @@ private static ResolvedDirection directionOf(List<ParagraphSpan> spans,
  }
  if (textSpan.background() != null) {
  // A chip is one rounded fill, so it cannot be split; it takes its first
- // character's level whole. A chip whose text changes direction inside
- // itself keeps logical order within the chip — a known approximation.
+ // character's level whole, for placement in the line. Its interior is
+ // not flattened to that level: the render seam resolves the chip's own
+ // levels (BidiVisualOrder), so a chip whose text changes direction
+ // inside itself still draws each part the way it reads.
  resolved.add(withDirection(textSpan, levels[start]));
  resolvedLevels.add(levels[start]);
  continue;

core/src/main/java/com/demcha/compose/engine/text/bidi/BidiVisualOrder.java

@@ -0,0 +1,133 @@
+package com.demcha.compose.engine.text.bidi;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Turns one atomic right-to-left run into the exact string a backend draws, level by
+ * level.
+ *
+ * <p>A plain span never needs this: the wrapper splits it wherever its characters
+ * resolve to a different embedding level, so each piece is single-level and reversing
+ * it whole is correct. An inline chip cannot be split — it is one rounded fill — so it
+ * reaches the backend carrying its first character's level and whatever its interior
+ * holds. Reversing <em>that</em> whole is wrong the moment the interior sits at the
+ * opposite level: a chip reading {@code (a > b)} after a Hebrew word was drawn as
+ * {@code (b < a)}, the comparison inverted, because the left-to-right interior was
+ * reversed and mirrored along with the brackets that enclose it.</p>
+ *
+ * <p>This class re-resolves the run's own levels (right-to-left base, matching the
+ * flag the caller holds), reorders the level runs visually, and reverses and mirrors
+ * only the right-to-left ones — UAX #9's L2 and L4 applied to the one span the wrapper
+ * could not split. For a single-level run the result is identical to reversing and
+ * mirroring the whole string, so the transform is safe for every chip, not only the
+ * mixed ones.</p>
+ *
+ * <p>Ownership: shared engine foundation.</p>
+ *
+ * @since 2.2.0
+ */
+public final class BidiVisualOrder {
+
+ private BidiVisualOrder() {
+ }
+
+ /**
+ * Mirrors only the characters that resolve to a right-to-left level, keeping
+ * logical order.
+ *
+ * <p>For a viewer that runs the bidirectional algorithm itself — PowerPoint — the
+ * text must stay logical: reordering is a property of strong right-to-left
+ * characters, not of a declared direction, so a pre-reordered string would have its
+ * Hebrew re-reversed on display. What such a viewer was measured not to do is
+ * UAX&nbsp;#9's L4, so the paired punctuation is swapped for it here — but only
+ * where L4 itself would apply. A run at the left-to-right level keeps its brackets
+ * and comparisons exactly as typed; mirroring those, as the whole-string swap did,
+ * turns {@code a > b} into {@code a < b} in the only copy of the text the file
+ * has.</p>
+ *
+ * <p>For a single-level right-to-left run this is {@link BidiMirroring#mirror},
+ * unchanged.</p>
+ *
+ * @param text run text in logical order
+ * @return the same order with paired punctuation at right-to-left levels swapped
+ */
+ public static String mirrorRightToLeftLevels(String text) {
+ if (text == null || text.isEmpty()) {
+ return "";
+ }
+ int[] levels = BidiParagraphResolver.levelsFor(
+ text, BidiParagraphResolver.BaseDirection.RIGHT_TO_LEFT);
+ if (levels.length == 0) {
+ return text;
+ }
+ StringBuilder mirrored = new StringBuilder(text.length());
+ int from = 0;
+ while (from < text.length()) {
+ int level = levels[from];
+ int to = from + 1;
+ while (to < text.length() && levels[to] == level) {
+ to++;
+ }
+ String run = text.substring(from, to);
+ mirrored.append(BidiParagraphResolver.isRightToLeftLevel(level)
+ ? BidiMirroring.mirror(run)
+ : run);
+ from = to;
+ }
+ return mirrored.toString();
+ }
+
+ /**
+ * Resolves one right-to-left run into visual order, mirroring what moves.
+ *
+ * <p>Level runs are reordered as UAX #9 orders them; a right-to-left run is
+ * reversed by grapheme cluster and its paired punctuation mirrored, a
+ * left-to-right run passes through as written. Text that resolves to no
+ * right-to-left level at all is returned unchanged — drawing it as written is
+ * already correct.</p>
+ *
+ * @param text run text in logical order
+ * @return the text as a left-to-right drawing order
+ */
+ public static String visualize(String text) {
+ if (text == null || text.isEmpty()) {
+ return "";
+ }
+ int[] levels = BidiParagraphResolver.levelsFor(
+ text, BidiParagraphResolver.BaseDirection.RIGHT_TO_LEFT);
+ if (levels.length == 0) {
+ return text;
+ }
+
+ List<String> runs = new ArrayList<>();
+ List<Integer> runLevels = new ArrayList<>();
+ int from = 0;
+ while (from < text.length()) {
+ int level = levels[from];
+ int to = from + 1;
+ while (to < text.length() && levels[to] == level) {
+ to++;
+ }
+ runs.add(text.substring(from, to));
+ runLevels.add(level);
+ from = to;
+ }
+
+ int[] levelArray = new int[runLevels.size()];
+ for (int index = 0; index < levelArray.length; index++) {
+ levelArray[index] = runLevels.get(index);
+ }
+ int[] order = BidiParagraphResolver.visualOrder(levelArray);
+
+ StringBuilder visual = new StringBuilder(text.length());
+ for (int position = 0; position < runs.size(); position++) {
+ int logical = order.length == 0 ? position : order[position];
+ String run = runs.get(logical);
+ visual.append(BidiParagraphResolver.isRightToLeftLevel(levelArray[logical])
+ ? BidiMirroring.mirror(BidiText.reverseForDisplay(run))
+ : run);
+ }
+ return visual.toString();
+ }
+}

core/src/test/java/com/demcha/compose/engine/text/bidi/BidiVisualOrderTest.java

@@ -0,0 +1,79 @@
+package com.demcha.compose.engine.text.bidi;
+
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Pins the level-aware transform for the one span the wrapper cannot split.
+ *
+ * <p>The failure it guards inverted meaning, not just shape: a chip reading
+ * {@code (a > b)} after a Hebrew word was reversed whole, and the page said
+ * {@code (b < a)} — operands swapped and the comparison flipped, in the only copy of
+ * the text the file has. The interior of that chip sits at the left-to-right level,
+ * where UAX #9 reorders nothing and mirrors nothing; only the brackets enclosing it
+ * belong to the right-to-left level that moves.</p>
+ */
+class BidiVisualOrderTest {
+
+ private static final String HEBREW = "שלום";
+ private static final String HEBREW_REVERSED = new StringBuilder(HEBREW).reverse().toString();
+
+ @Test
+ void aBracketWrappedLeftToRightInteriorKeepsItsMeaning() {
+ // Brackets are right-to-left level and swap positions and forms; the interior
+ // is left-to-right level and must come through exactly as written. The two
+ // effects cancel on the brackets, so the visual string equals the logical one —
+ // which is precisely what reversing the whole span destroys.
+ assertThat(BidiVisualOrder.visualize("(a > b)")).isEqualTo("(a > b)");
+ }
+
+ @Test
+ void aSingleLevelRunIsReversedAndMirroredWhole() {
+ // For homogeneous text the transform must agree with the treatment plain spans
+ // always had: reverse by cluster, mirror the pairs.
+ assertThat(BidiVisualOrder.visualize("(" + HEBREW + ")"))
+ .isEqualTo("(" + HEBREW_REVERSED + ")");
+ }
+
+ @Test
+ void digitsInsideARightToLeftRunStayForward() {
+ // Digits resolve to the left-to-right level even in Hebrew text: the year in
+ // "ב-2026" reads forwards. Reversed whole, it would not.
+ assertThat(BidiVisualOrder.visualize(HEBREW + " 123"))
+ .isEqualTo("123 " + HEBREW_REVERSED);
+ }
+
+ @Test
+ void levelKeyedMirroringSwapsOnlyWhatTheAlgorithmWould() {
+ // For a viewer with its own bidi engine the text must stay logical — strong
+ // right-to-left characters are reordered by what they are, not by what the
+ // paragraph declares, so a pre-reordered string would come back re-reversed.
+ // Only the mirroring is done for it, and only on the levels L4 touches.
+ assertThat(BidiVisualOrder.mirrorRightToLeftLevels("(a > b)"))
+ .describedAs("brackets sit at the right-to-left level and swap; the "
+ + "interior's comparison does not")
+ .isEqualTo(")a > b(");
+ assertThat(BidiVisualOrder.mirrorRightToLeftLevels("(" + HEBREW + ")"))
+ .describedAs("a single-level run is the whole-string mirror, unchanged")
+ .isEqualTo(BidiMirroring.mirror("(" + HEBREW + ")"));
+ assertThat(BidiVisualOrder.mirrorRightToLeftLevels(HEBREW + " 2026"))
+ .describedAs("nothing mirrors, nothing reorders — the letters stay "
+ + "logical for the viewer's own engine")
+ .isEqualTo(HEBREW + " 2026");
+ assertThat(BidiVisualOrder.mirrorRightToLeftLevels("plain latin"))
+ .isEqualTo("plain latin");
+ assertThat(BidiVisualOrder.mirrorRightToLeftLevels("")).isEmpty();
+ assertThat(BidiVisualOrder.mirrorRightToLeftLevels(null)).isEmpty();
+ }
+
+ @Test
+ void textWithoutARightToLeftLevelPassesThrough() {
+ // The flag the caller holds comes from paragraph context; if the run's own
+ // analysis finds nothing right-to-left, drawing it as written is already
+ // correct and the transform must not invent a reversal.
+ assertThat(BidiVisualOrder.visualize("plain latin")).isEqualTo("plain latin");
+ assertThat(BidiVisualOrder.visualize("")).isEmpty();
+ assertThat(BidiVisualOrder.visualize(null)).isEmpty();
+ }
+}