feat(api): expose clipToBounds on the layer-stack DSL

LayerStackNode.clipToBounds — added with the block SVG viewBox clip — was
only reachable by constructing the node directly. LayerStackBuilder now
offers clipToBounds() / clipToBounds(boolean) so DSL-built stacks can opt
into the same behaviour: the overflow: hidden of a stacking box. The flag
defaults off, so existing stacks are unchanged.

LayerStackBuilderTest covers both: clipToBounds() emits a balanced clip
pair around the layers, and the default (and explicit false) emits none.

Author: DemchaAV

CHANGELOG.md

@@ -101,7 +101,9 @@ PDF `GoTo` actions. External links are unchanged.
   the icon box: `LayerStackNode` gains an opt-in `clipToBounds` (`@since 1.9.0`,
   default off so existing stacks stay byte-identical) and `SvgIcon.node(...)`
   sets it. It reuses the `ShapeContainer` clip pipeline — one paired
-  begin/end marker per icon — so it matches the inline fix above.
+  begin/end marker per icon — so it matches the inline fix above. The same
+  flag is exposed to the DSL as `LayerStackBuilder.clipToBounds()` — the
+  `overflow: hidden` of a stacking box for any layer stack.
 
 ### Documentation
 

src/main/java/com/demcha/compose/document/dsl/LayerStackBuilder.java

@@ -26,6 +26,7 @@ public final class LayerStackBuilder {
     private String name = "";
     private DocumentInsets padding = DocumentInsets.zero();
     private DocumentInsets margin = DocumentInsets.zero();
+    private boolean clipToBounds = false;
 
     /**
      * Creates a layer stack builder.
@@ -265,12 +266,37 @@ public LayerStackBuilder margin(double margin) {
         return margin(DocumentInsets.of(margin));
     }
 
+    /**
+     * Clips the layers to the stack box — the {@code overflow: hidden} of a
+     * stacking box. Anything a layer paints outside the box (after padding) is
+     * cut away. Off by default, so layers may overflow.
+     *
+     * @return this builder
+     * @since 1.9.0
+     */
+    public LayerStackBuilder clipToBounds() {
+        return clipToBounds(true);
+    }
+
+    /**
+     * Sets whether the layers are clipped to the stack box.
+     *
+     * @param clip {@code true} to clip layers to the box, {@code false} to let
+     *             them overflow (the default)
+     * @return this builder
+     * @since 1.9.0
+     */
+    public LayerStackBuilder clipToBounds(boolean clip) {
+        this.clipToBounds = clip;
+        return this;
+    }
+
     /**
      * Builds the layer stack node.
      *
      * @return immutable layer stack node
      */
     public LayerStackNode build() {
-        return new LayerStackNode(name, List.copyOf(layers), padding, margin);
+        return new LayerStackNode(name, List.copyOf(layers), padding, margin, clipToBounds);
     }
 }

src/test/java/com/demcha/compose/document/dsl/LayerStackBuilderTest.java

@@ -3,7 +3,10 @@
 import com.demcha.compose.GraphCompose;
 import com.demcha.compose.document.api.DocumentSession;
 import com.demcha.compose.document.layout.LayoutGraph;
+import com.demcha.compose.document.layout.PlacedFragment;
 import com.demcha.compose.document.layout.PlacedNode;
+import com.demcha.compose.document.layout.payloads.ShapeClipBeginPayload;
+import com.demcha.compose.document.layout.payloads.ShapeClipEndPayload;
 import com.demcha.compose.document.node.LayerAlign;
 import com.demcha.compose.document.node.LayerStackNode;
 import com.demcha.compose.document.node.SpacerNode;
@@ -424,6 +427,51 @@ void stackPaddingShrinksLayerBoundingBox() {
         }
     }
 
+    @Test
+    void clipToBoundsEmitsBalancedClipMarkersAroundLayers() {
+        try (DocumentSession session = GraphCompose.document()
+                .pageSize(420, 320)
+                .margin(DocumentInsets.of(20))
+                .create()) {
+
+            LayerStackNode clipped = new LayerStackBuilder()
+                    .name("Clipped")
+                    .layer(new SpacerNode("Inner", 80.0, 50.0,
+                            DocumentInsets.zero(), DocumentInsets.zero()))
+                    .clipToBounds()
+                    .build();
+
+            assertThat(clipped.clipToBounds()).isTrue();
+            session.add(clipped);
+
+            List<PlacedFragment> fragments = session.layoutGraph().fragments();
+            assertThat(fragments)
+                    .filteredOn(f -> f.payload() instanceof ShapeClipBeginPayload)
+                    .as("clipToBounds() opens exactly one bounds clip")
+                    .hasSize(1);
+            assertThat(fragments)
+                    .filteredOn(f -> f.payload() instanceof ShapeClipEndPayload)
+                    .as("clipToBounds() closes exactly one bounds clip")
+                    .hasSize(1);
+        } catch (Exception e) {
+            throw new RuntimeException(e);
+        }
+    }
+
+    @Test
+    void defaultStackDoesNotClipAndExplicitFalseStaysOff() {
+        SpacerNode inner = new SpacerNode("Inner", 40.0, 30.0,
+                DocumentInsets.zero(), DocumentInsets.zero());
+
+        // Default: no clip, byte-identical to pre-1.9 stacks.
+        assertThat(new LayerStackBuilder().name("Default").layer(inner).build().clipToBounds())
+                .isFalse();
+        // Explicit false is a no-op opt-out.
+        assertThat(new LayerStackBuilder().name("Off").layer(inner).clipToBounds(false).build()
+                .clipToBounds())
+                .isFalse();
+    }
+
     private static PlacedNode nodeWithSemanticName(LayoutGraph graph, String name) {
         return graph.nodes().stream()
                 .filter(n -> name.equals(n.semanticName()))