From 3de9fa93e28fe2328176c6144c1d80ada94dd1d9 Mon Sep 17 00:00:00 2001
From: DemchaAV <demchaav@gmail.com>
Date: Sun, 14 Jun 2026 14:29:02 +0100
Subject: [PATCH] chore(api): mark the SVG-emitted gradient paints @Beta

DocumentPaint.LinearAxis and RadialCircle are produced only by the beta
SVG gradient reader, and their endpoint/centre normalization contract is
as provisional as that reader. Mark both records @Beta (annotation plus a
Javadoc note) so they carry the same stability signal as SvgPath/SvgIcon.
The Linear/Radial chart-authoring forms stay stable.

Annotation + Javadoc only; no behaviour change.
---
 .../com/demcha/compose/document/style/DocumentPaint.java | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/src/main/java/com/demcha/compose/document/style/DocumentPaint.java b/src/main/java/com/demcha/compose/document/style/DocumentPaint.java
index 23a57a86d..19f298dea 100644
--- a/src/main/java/com/demcha/compose/document/style/DocumentPaint.java
+++ b/src/main/java/com/demcha/compose/document/style/DocumentPaint.java
@@ -1,5 +1,6 @@
 package com.demcha.compose.document.style;
 
+import com.demcha.compose.document.api.Beta;
 
 import java.util.List;
 import java.util.Objects;
@@ -125,6 +126,9 @@ public DocumentColor primaryColor() {
      * exact: colour runs from the first stop at {@code (x0, y0)} to the last
      * stop at {@code (x1, y1)} and clamps beyond (pad spread).
      *
+     * <p>Marked {@link Beta} — emitted by the beta SVG gradient reader; the
+     * endpoint normalization contract may shift while that reader hardens.</p>
+     *
      * @param stops ordered colour stops, offsets in [0,1]; at least two
      * @param x0    axis start x, normalized to the box width
      * @param y0    axis start y, normalized to the box height
@@ -132,6 +136,7 @@ public DocumentColor primaryColor() {
      * @param y1    axis end y, normalized to the box height
      * @since 1.8.0
      */
+    @Beta
     record LinearAxis(List<Stop> stops, double x0, double y0, double x1, double y1)
             implements DocumentPaint {
         /**
@@ -166,12 +171,16 @@ public DocumentColor primaryColor() {
      * a circle when the box preserves the source's aspect ratio (the SVG
      * icon frame contract). Colour clamps beyond the last stop (pad spread).
      *
+     * <p>Marked {@link Beta} — emitted by the beta SVG gradient reader; the
+     * centre/radius normalization contract may shift while that reader hardens.</p>
+     *
      * @param stops ordered colour stops, offsets in [0,1]; at least two
      * @param cx    centre x, normalized to the box width
      * @param cy    centre y, normalized to the box height
      * @param r     radius as a fraction of the box width; positive
      * @since 1.8.0
      */
+    @Beta
     record RadialCircle(List<Stop> stops, double cx, double cy, double r)
             implements DocumentPaint {
         /**