v1.6.2 robustness: glyph sanitizer + capacity tolerance + LayerStack row + error messages

CODE_OF_CONDUCT.md

@@ -56,7 +56,7 @@ when an individual is officially representing the community in public spaces.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behaviour may be
-reported privately to the maintainer at **demchyshyn.artem@gmail.com**.
+reported privately to the maintainer at **demchishynartem@gmail.com**.
 All complaints will be reviewed and investigated promptly and fairly.
 The maintainer is obligated to respect the privacy and security of the reporter
 of any incident.

README.md

@@ -196,6 +196,10 @@ document.pageFlow().addCanvas(523, 360, canvas -> canvas
 - Recipes: [shape-as-container](./docs/recipes/shape-as-container.md) · [transforms](./docs/recipes/transforms.md) · [tables](./docs/recipes/tables.md) · [themes](./docs/recipes/themes.md) · [streaming](./docs/recipes/streaming.md) · [extending](./docs/recipes/extending.md)
 - [Migration v1.5 → v1.6](./docs/migration-v1-5-to-v1-6.md) · [Release process](./docs/release-process.md) · [Contributing](./CONTRIBUTING.md)
 
+## Companion projects
+
+- [**graphcompose-ai-flow**](https://github.com/DemchaAV/graphcompose-ai-flow) — experimental sister project exploring an AI-assisted authoring flow on top of GraphCompose. Independent codebase, separate lifecycle — nothing in this repo depends on it. Track it if you are interested in agentic document composition driven by the same semantic node model.
+
 ## License
 
 MIT — see [`LICENSE`](./LICENSE).

pom.xml

@@ -24,7 +24,7 @@
         <developer>
             <id>DemchaAV</id>
             <name>Artem Demchyshyn</name>
-            <email>demchyshyn.artem@gmail.com</email>
+            <email>demchishynartem@gmail.com</email>
             <url>https://github.com/DemchaAV</url>
             <roles>
                 <role>Lead Developer</role>

src/main/java/com/demcha/compose/document/backend/fixed/pdf/handlers/PdfParagraphFragmentRenderHandler.java

@@ -11,7 +11,6 @@
 import com.demcha.compose.document.node.InlineImageAlignment;
 import com.demcha.compose.font.FontLibrary;
 import com.demcha.compose.engine.render.pdf.PdfFont;
-import com.demcha.compose.engine.text.TextControlSanitizer;
 import org.apache.pdfbox.pdmodel.PDPageContentStream;
 import org.apache.pdfbox.pdmodel.graphics.image.PDImageXObject;
 
@@ -89,7 +88,14 @@ private void renderLine(PDPageContentStream stream,
         try {
             for (ParagraphSpan span : spans) {
                 if (span instanceof ParagraphTextSpan textSpan) {
-                    String text = sanitize(textSpan.text());
+                    PdfFont font = fonts.getFont(textSpan.textStyle().fontName(), PdfFont.class).orElseThrow();
+                    // Font-aware sanitization keeps width measurement
+                    // (PdfFont.getTextWidth) and the bytes emitted here
+                    // in lockstep. PdfFont.sanitizeForRender substitutes
+                    // any code point the resolved font cannot encode
+                    // with '?', preventing PDFBox from throwing on
+                    // arrows / bullets / emoji / unsupported unicode.
+                    String text = font.sanitizeForRender(textSpan.textStyle(), textSpan.text());
                     if (text.isEmpty()) {
                         cursorX += textSpan.width();
                         continue;
@@ -99,7 +105,6 @@ private void renderLine(PDPageContentStream stream,
                         stream.newLineAtOffset((float) cursorX, (float) baselineY);
                         inTextBlock = true;
                     }
-                    PdfFont font = fonts.getFont(textSpan.textStyle().fontName(), PdfFont.class).orElseThrow();
                     stream.setFont(font.fontType(textSpan.textStyle().decoration()), (float) textSpan.textStyle().size());
                     stream.setNonStrokingColor(textSpan.textStyle().color());
                     stream.showText(text);
@@ -150,7 +155,4 @@ private static double resolveImageBottom(ParagraphImageSpan imageSpan,
         return base + imageSpan.baselineOffset();
     }
 
-    private String sanitize(String text) {
-        return TextControlSanitizer.remove(text);
-    }
 }

src/main/java/com/demcha/compose/document/backend/fixed/pdf/handlers/PdfTableRowFragmentRenderHandler.java

@@ -181,9 +181,12 @@ private void renderCellText(PDPageContentStream stream,
                 if (line.text().isEmpty()) {
                     continue;
                 }
+                // Sanitise per-line so a single unsupported glyph in a
+                // cell does not crash the whole table render.
+                String safeText = font.sanitizeForRender(cell.style().textStyle(), line.text());
                 stream.beginText();
                 stream.newLineAtOffset((float) line.x(), (float) line.baselineY());
-                stream.showText(line.text());
+                stream.showText(safeText);
                 stream.endText();
             }
         } finally {

src/main/java/com/demcha/compose/document/layout/LayoutCompiler.java

@@ -26,6 +26,40 @@ public final class LayoutCompiler {
     private static final Logger PAGINATION_LOG = LoggerFactory.getLogger("com.demcha.compose.engine.pagination");
     private static final double EPS = 1e-6;
 
+    /**
+     * Tolerance applied when comparing a node's required outer height
+     * against the full page capacity. EPS (1e-6) is floating-point noise
+     * tolerance; CAPACITY_TOLERANCE absorbs the discrepancy between
+     * rounded human input (e.g. {@code 842.0} for an A4 height) and the
+     * exact PDF point value ({@code DocumentPageSize.A4.height() ==
+     * 841.88977}). 0.5 pt ≈ 0.18 mm — visually indistinguishable, while
+     * a > 1 pt overflow still throws {@link AtomicNodeTooLargeException}.
+     *
+     * <p>Use EPS for floating-point noise inside split / remaining-height
+     * decisions; reserve CAPACITY_TOLERANCE for the "does this fit on a
+     * full page at all?" check.</p>
+     */
+    private static final double CAPACITY_TOLERANCE = 0.5;
+
+    /**
+     * Identifies the kind of fixed slot a child is being compiled into,
+     * so the validator can distinguish "child of a horizontal row band"
+     * (where a nested {@code Row} would create real composition conflict)
+     * from "child of a {@link com.demcha.compose.document.node.LayerStackNode}
+     * layer" (where a nested {@code Row} is a normal column-row inside an
+     * already-fixed layer rectangle).
+     *
+     * <p>{@link #compileNodeInFixedSlot} takes the kind as a parameter
+     * and propagates it down recursive calls so the validator can
+     * relax just for STACK layer parents.</p>
+     */
+    private enum FixedSlotKind {
+        /** Child sits inside a horizontal row band (column of a row). */
+        ROW_SLOT,
+        /** Child sits inside a {@link LayerStackNode} layer rectangle. */
+        STACK_LAYER_SLOT
+    }
+
     private final NodeRegistry registry;
 
     /**
@@ -122,13 +156,16 @@ private void compileNode(PreparedNode<DocumentNode> prepared,
         }
 
         if (availableWidth <= EPS) {
-            throw new IllegalStateException("Node '" + path + "' has no horizontal layout space.");
+            throw new IllegalStateException("Node '" + path
+                    + "' has no horizontal layout space. "
+                    + "Reduce padding or margin on the parent, or increase the page width.");
         }
 
         MeasureResult naturalMeasure = prepared.measureResult();
         if (naturalMeasure.width() > availableWidth + EPS) {
             throw new IllegalStateException("Node '" + path + "' measured width " + naturalMeasure.width()
-                    + " exceeds available width " + availableWidth + ".");
+                    + " exceeds available width " + availableWidth + ". "
+                    + "Reduce the node width, shorten inline content, or wrap content in a smaller container.");
         }
 
         if (prepared.isComposite()) {
@@ -325,7 +362,7 @@ private void compileHorizontalRow(PreparedNode<DocumentNode> prepared,
         DocumentNode node = prepared.node();
         double rowOuterHeight = naturalMeasure.height() + margin.vertical();
         double fullPageHeight = state.canvas.innerHeight();
-        if (rowOuterHeight > fullPageHeight + EPS) {
+        if (rowOuterHeight > fullPageHeight + CAPACITY_TOLERANCE) {
             throw atomicTooLarge(path, rowOuterHeight, fullPageHeight);
         }
         if (rowOuterHeight > state.remainingHeight() + EPS && state.usedHeight > EPS) {
@@ -365,12 +402,16 @@ private void compileHorizontalRow(PreparedNode<DocumentNode> prepared,
                         (NodeDefinition<DocumentNode>) registry.definitionFor(child);
                 if (childMeasure.height() > naturalMeasure.height() - padding.vertical() + EPS) {
                     throw new IllegalStateException("Row '" + path + "' child '" + child.nodeKind()
-                            + "' measured height " + childMeasure.height() + " exceeds row inner height.");
+                            + "' measured height " + childMeasure.height() + " exceeds row inner height. "
+                            + "Reduce the child height, shorten its content, or increase the row height.");
                 }
 
                 if (childPrepared.isComposite()) {
                     PlacementContext slotCtx = new FixedSlotPlacementContext(
                             state.pageIndex, state.canvas, prepareContext, fragmentContext, nodes, fragments);
+                    // Column of a horizontal row band — keep the strict
+                    // ROW_SLOT validator so a nested horizontal row is
+                    // rejected (would compete with the parent row band).
                     compileNodeInFixedSlot(
                             childPrepared,
                             path,
@@ -379,6 +420,7 @@ private void compileHorizontalRow(PreparedNode<DocumentNode> prepared,
                             cursorX,
                             rowInnerY,
                             slotWidth,
+                            FixedSlotKind.ROW_SLOT,
                             slotCtx);
                     cursorX += slotWidth + layoutSpec.spacing();
                     continue;
@@ -499,7 +541,7 @@ private void compileStackedLayer(PreparedNode<DocumentNode> prepared,
         DocumentNode node = prepared.node();
         double stackOuterHeight = naturalMeasure.height() + margin.vertical();
         double fullPageHeight = state.canvas.innerHeight();
-        if (stackOuterHeight > fullPageHeight + EPS) {
+        if (stackOuterHeight > fullPageHeight + CAPACITY_TOLERANCE) {
             throw atomicTooLarge(path, stackOuterHeight, fullPageHeight);
         }
         if (stackOuterHeight > state.remainingHeight() + EPS && state.usedHeight > EPS) {
@@ -742,7 +784,7 @@ private void compileAtomicLeaf(PreparedNode<DocumentNode> prepared,
         double outerHeight = naturalMeasure.height() + margin.vertical();
         double fullPageHeight = state.canvas.innerHeight();
 
-        if (outerHeight > fullPageHeight + EPS) {
+        if (outerHeight > fullPageHeight + CAPACITY_TOLERANCE) {
             throw atomicTooLarge(path, outerHeight, fullPageHeight);
         }
         if (outerHeight > state.remainingHeight() + EPS && state.usedHeight > EPS) {
@@ -876,6 +918,9 @@ private void placeStackLayer(DocumentNode child,
                         ctx.nodes(),
                         ctx.fragments());
 
+        // Child sits inside a LayerStack layer rectangle — the validator
+        // can relax for STACK_LAYER_SLOT because there is no competing
+        // horizontal row band, only the layer's own fixed area.
         compileNodeInFixedSlot(
                 childPrepared,
                 parentPath,
@@ -884,6 +929,7 @@ private void placeStackLayer(DocumentNode child,
                 alignedSlotX,
                 alignedSlotTopY,
                 childOuterWidth,
+                FixedSlotKind.STACK_LAYER_SLOT,
                 layerCtx);
     }
 
@@ -974,7 +1020,9 @@ private void compileSplittableLeaf(PreparedNode<DocumentNode> prepared,
                 throw atomicTooLarge(path, pieceOuterHeight, fullPageOuterHeight);
             }
             if (tail != null && tail.equals(current)) {
-                throw new IllegalStateException("Split did not make progress for node '" + path + "'.");
+                throw new IllegalStateException("Split did not make progress for node '" + path
+                        + "'. The node's NodeDefinition.split() returned the original input as the tail — "
+                        + "check the definition for an infinite split loop and ensure each split advances.");
             }
 
             DocumentNode headNode = head.node();
@@ -1051,12 +1099,21 @@ private void compileSplittableLeaf(PreparedNode<DocumentNode> prepared,
     }
 
     /**
-     * Compiles a composite or leaf node inside a fixed horizontal row slot.
+     * Compiles a composite or leaf node inside a fixed slot.
+     *
+     * <p>The slot is constrained to a single page: composite children are
+     * laid out with a local top-down y-cursor. No global pagination state
+     * is mutated; the parent's outer height check guarantees the column
+     * fits.</p>
      *
-     * <p>The slot is constrained to a single page: composite row children are
-     * laid out as columns inside the row's atomic band, with a local
-     * top-down y-cursor. No global pagination state is mutated; the row's
-     * outer height check guarantees the column fits.</p>
+     * <p>{@code kind} identifies whether the slot is a horizontal row
+     * band ({@link FixedSlotKind#ROW_SLOT}) or a
+     * {@link com.demcha.compose.document.node.LayerStackNode} layer
+     * rectangle ({@link FixedSlotKind#STACK_LAYER_SLOT}). The validator
+     * uses it to relax the "no nested horizontal row" rule for stack
+     * layers, where a {@code Row} is a normal column-row inside an
+     * already-fixed layer rectangle rather than a competing horizontal
+     * band.</p>
      *
      * @return outer height (measured height + vertical margin) consumed by the
      *         node, used by the caller's local y-cursor
@@ -1068,6 +1125,7 @@ private double compileNodeInFixedSlot(PreparedNode<DocumentNode> prepared,
                                           double slotX,
                                           double slotTopY,
                                           double slotWidth,
+                                          FixedSlotKind kind,
                                           PlacementContext ctx) {
         // Alias locals so the body keeps the same names it had before the
         // PlacementContext refactor; the context is the only authoritative
@@ -1094,14 +1152,21 @@ private double compileNodeInFixedSlot(PreparedNode<DocumentNode> prepared,
 
         if (prepared.isComposite()) {
             CompositeLayoutSpec layoutSpec = prepared.requireCompositeLayout();
-            // Horizontal rows and splittable tables remain forbidden inside a
-            // row slot — they would compete with the parent row's horizontal
-            // band or break atomic pagination. STACK overlays (e.g.
-            // LayerStackNode) are allowed because they are atomic and place
-            // their layers at the same point with explicit alignment.
-            if (layoutSpec.axis() == CompositeLayoutSpec.Axis.HORIZONTAL) {
+            // Horizontal rows remain forbidden inside a ROW_SLOT (column
+            // of a row band) because they would compete with the parent
+            // row's horizontal band. Inside a STACK_LAYER_SLOT, however,
+            // the surrounding rectangle is already fixed by the layer's
+            // alignment — a "horizontal row" there is just a normal
+            // column-row inside the layer area, not a competing band.
+            // STACK composites (e.g. LayerStackNode) are always allowed
+            // because they are atomic and anchor their children inside
+            // the existing slot.
+            if (layoutSpec.axis() == CompositeLayoutSpec.Axis.HORIZONTAL
+                    && kind == FixedSlotKind.ROW_SLOT) {
                 throw new IllegalStateException("Row '" + path
-                        + "' cannot contain a nested horizontal row; use a section column instead.");
+                        + "' cannot contain a nested horizontal row. "
+                        + "Wrap the inner row in a LayerStack layer (allowed since v1.6.2), "
+                        + "or stack horizontal content as sections inside a vertical column.");
             }
 
             int decorationInsertIndex = fragments.size();
@@ -1213,6 +1278,9 @@ private double compileNodeInFixedSlot(PreparedNode<DocumentNode> prepared,
                 DocumentNode child = children.get(i);
                 PreparedNode<DocumentNode> childPrepared =
                         prepareForRegionWidth(prepareContext, child, childRegionWidth);
+                // Propagate the parent's slot kind so a STACK layer
+                // descendant (column → row → ...) keeps the relaxed
+                // validation policy all the way down.
                 double consumed = compileNodeInFixedSlot(
                         childPrepared,
                         path,
@@ -1221,6 +1289,7 @@ private double compileNodeInFixedSlot(PreparedNode<DocumentNode> prepared,
                         childRegionX,
                         childTopY,
                         childRegionWidth,
+                        kind,
                         ctx);
                 childTopY -= consumed;
                 if (i < children.size() - 1) {
@@ -1445,7 +1514,11 @@ private String semanticName(DocumentNode node) {
 
     private AtomicNodeTooLargeException atomicTooLarge(String path, double outerHeight, double pageHeight) {
         return new AtomicNodeTooLargeException(
-                "Node '" + path + "' requires outer height " + outerHeight + " but page capacity is " + pageHeight + ".");
+                "Node '" + path + "' requires outer height " + outerHeight
+                        + " but page capacity is " + pageHeight + ". "
+                        + "Reduce the node height, split content into multiple atomic blocks, "
+                        + "or increase the page size. Differences under 0.5 pt are tolerated as "
+                        + "rounding noise (v1.6.2+).");
     }
 
 }