PAGX Specification

1. Introduction

PAGX (Portable Animated Graphics XML) is an XML-based markup language for describing animated vector graphics. It provides a unified and powerful representation of vector graphics and animations, designed to be the vector animation interchange standard across all major tools and runtimes.

1.1 Design Goals

• Readable: Uses a plain-text XML format that is easy to read and edit, with native support for version control and diffing, facilitating debugging as well as AI understanding and generation.

• Comprehensive: Fully covers vector graphics, raster images, rich text, filter effects, blending modes, masking, and related capabilities, meeting the requirements for complex animated graphics.

• Expressive: Defines a compact yet expressive unified structure that optimizes the description of both static vector content and animations, while reserving extensibility for future interaction and scripting.

• Interoperable: Can serve as a common interchange format for design tools such as After Effects, Figma, and Tencent Design, enabling seamless asset exchange across platforms.

• Deployable: Design assets can be exported and deployed to production environments with a single action, achieving high compression ratios and excellent runtime performance after conversion to the binary PAG format.

1.2 File Structure

PAGX is a plain XML file (.pagx) that can reference external resource files (images, videos, audio, fonts, etc.) or embed resources via data URIs. PAGX and binary PAG formats are bidirectionally convertible: convert to PAG for optimized loading performance during publishing; use PAGX format for reading and editing during development and review.

1.3 Document Organization

This specification is organized in the following order:

1. Basic Data Types: Defines the fundamental data formats used throughout the document
2. Document Structure: Describes the overall organization of a PAGX document
3. Layer System: Defines layers and their related features (styles, filters, masks)
4. VectorElement System: Defines vector elements within layers and their processing model

Appendices (for quick reference):

• Appendix A: Node hierarchy and containment relationships
• Appendix B: Enumeration type reference
• Appendix C: Common usage examples

2. Basic Data Types

This section defines the basic data types and naming conventions used in PAGX documents.

2.1 Naming Conventions

2.2 Attribute Table Conventions

This specification uses the "Default" column in attribute tables to describe whether an attribute is required:

2.3 Common Attributes

The following attributes are available on any element and are not repeated in individual node attribute tables:

Custom Attribute Guidelines:

• Attribute names must begin with data- followed by at least one character
• Attribute names may only contain lowercase letters, numbers, and hyphens (-), and cannot end with a hyphen
• Attribute values are arbitrary strings interpreted by the creating application
• These attributes are not processed at runtime; used only for passing metadata between tools or storing debug information

Example:

<Layer data-name="Background Layer" data-figma-id="12:34" data-exported-by="PAGExporter">
  <Rectangle position="50,50" size="100,100"/>
  <Fill color="#FF0000"/>
</Layer>

2.4 Basic Value Types

2.5 Point

A point is represented by two comma-separated floating-point numbers:

"x,y"

Examples: "100,200", "0.5,0.5", "-50,100"

2.6 Rect

A rectangle is represented by four comma-separated floating-point numbers:

"x,y,width,height"

Examples: "0,0,100,100", "10,20,200,150"

2.7 Transform Matrix

2D Transform Matrix

2D transforms use 6 comma-separated floating-point numbers corresponding to a standard 2D affine transformation matrix:

"a,b,c,d,tx,ty"

Matrix form:

| a  c  tx |
| b  d  ty |
| 0  0  1  |

Identity matrix: "1,0,0,1,0,0"

3D Transform Matrix

3D transforms use 16 comma-separated floating-point numbers in column-major order:

"m00,m10,m20,m30,m01,m11,m21,m31,m02,m12,m22,m32,m03,m13,m23,m33"

2.8 Color

PAGX supports two color formats:

HEX Format (Hexadecimal)

HEX format represents colors in the sRGB color space using a # prefix with hexadecimal values:

Floating-Point Format

Floating-point format uses colorspace(r, g, b) or colorspace(r, g, b, a) to represent colors, supporting both sRGB and Display P3 color spaces:

Notes:

• Color space identifiers (srgb or p3) and parentheses cannot be omitted
• Wide color gamut (Display P3) component values may exceed the [0, 1] range to represent colors outside the sRGB gamut
• sRGB floating-point format and HEX format represent the same color space; use whichever best suits your needs

Color Source Reference

Use @resourceId to reference color sources (gradients, patterns, etc.) defined in Resources.

2.9 Blend Mode

Blend modes define how source color (S) combines with destination color (D).

2.10 Path Data Syntax

Path data uses SVG path syntax, consisting of a series of commands and coordinates.

Path Commands:

2.11 External Resource Reference

External resources are referenced via relative paths or data URIs, applicable to images, videos, audio, fonts, and other files.

<!-- Relative path reference -->
<Image source="photo.png"/>
<Image source="assets/icons/logo.png"/>

<!-- Data URI embedding -->
<Image source="data:image/png;base64,iVBORw0KGgo..."/>

Path Resolution Rules:

• Relative paths: Resolved relative to the directory containing the PAGX file; supports ../ to reference parent directories
• Data URIs: Begin with data:, format is data:<mediatype>;base64,<data>; only base64 encoding is supported
• Path separators must use / (forward slash); \ (backslash) is not supported

3. Document Structure

This section defines the overall structure of a PAGX document.

3.1 Coordinate System

PAGX uses a standard 2D Cartesian coordinate system:

• Origin: Located at the top-left corner of the canvas
• X-axis: Positive direction points right
• Y-axis: Positive direction points down
• Angles: Clockwise direction is positive (0° points toward the positive X-axis)
• Units: All length values default to pixels; angle values default to degrees

3.2 Root Element (pagx)

<pagx> is the root element of a PAGX document, defining the canvas dimensions and directly containing the layer list.

<?xml version="1.0" encoding="UTF-8"?>
<!-- Demonstrates basic PAGX document structure -->
<pagx version="1.0" width="400" height="400">
  <!-- Main content card with modern gradient -->
  <Layer name="content">
    <Rectangle position="200,200" size="240,240" roundness="40"/>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="240,240">
        <ColorStop offset="0" color="#6366F1"/>
        <ColorStop offset="1" color="#8B5CF6"/>
      </LinearGradient>
    </Fill>
    <DropShadowStyle offsetY="16" blurX="48" blurY="48" color="#6366F160"/>
  </Layer>
</pagx>

Canvas Clipping: The canvas defined by width and height acts as the rendering boundary. Any content extending beyond the canvas area is clipped and not rendered.

Layer Rendering Order: Layers are rendered sequentially in document order; layers earlier in the document render first (below); later layers render last (above).

3.3 Resources

<Resources> defines reusable resources including images, path data, color sources, and compositions. Resources are identified by the id attribute and referenced elsewhere in the document using the @id syntax.

Element Position: The Resources element may be placed anywhere within the root element; there are no restrictions on its position. Parsers must support forward references—elements that reference resources or layers defined later in the document.

<?xml version="1.0" encoding="UTF-8"?>
<!-- Demonstrates resource definitions and references -->
<pagx version="1.0" width="400" height="400">
  <Layer>
    <Rectangle position="200,200" size="320,320" roundness="32"/>
    <Fill color="@oceanGradient"/>
    <DropShadowStyle offsetY="12" blurX="40" blurY="40" color="#06B6D450"/>
  </Layer>
  <!-- Shape using solid color resource reference -->
  <Layer>
    <Ellipse position="200,200" size="120,120"/>
    <Fill color="@coral"/>
  </Layer>
  <Resources>
    <SolidColor id="coral" color="#F43F5E"/>
    <LinearGradient id="oceanGradient" startPoint="0,0" endPoint="320,320">
      <ColorStop offset="0" color="#06B6D4"/>
      <ColorStop offset="1" color="#3B82F6"/>
    </LinearGradient>
  </Resources>
</pagx>

3.3.1 Image

Image resources define bitmap data for use throughout the document.

<Image source="photo.png"/>
<Image source="data:image/png;base64,..."/>

Supported Formats: PNG, JPEG, WebP, GIF

3.3.2 PathData

PathData defines reusable path data for reference by Path elements and TextPath modifiers.

<PathData id="curvePath" data="M 0 0 C 50 0 50 100 100 100"/>

3.3.3 Color Sources

Color sources define colors that can be used for fills and strokes, supporting two usage patterns:

1. Shared Definition: Pre-defined in <Resources> and referenced via @id. Suitable for color sources referenced in multiple places.
2. Inline Definition: Nested directly within <Fill> or <Stroke> elements. Suitable for color sources used only once, providing a more concise syntax.

SolidColor

<SolidColor color="#FF0000"/>

LinearGradient

Linear gradients interpolate along the direction from start point to end point.

<?xml version="1.0" encoding="UTF-8"?>
<!-- Demonstrates linear gradient -->
<pagx version="1.0" width="400" height="400">
  <Layer>
    <Rectangle position="200,200" size="320,320" roundness="32"/>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="320,320">
        <ColorStop offset="0" color="#6366F1"/>
        <ColorStop offset="0.5" color="#8B5CF6"/>
        <ColorStop offset="1" color="#EC4899"/>
      </LinearGradient>
    </Fill>
    <DropShadowStyle offsetY="12" blurX="40" blurY="40" color="#8B5CF650"/>
  </Layer>
</pagx>

Calculation: For a point P, its color is determined by the projection position of P onto the line connecting start and end points.

RadialGradient

Radial gradients radiate outward from the center.

<?xml version="1.0" encoding="UTF-8"?>
<!-- Demonstrates radial gradient -->
<pagx version="1.0" width="400" height="400">
  <Layer>
    <Ellipse position="200,200" size="320,320"/>
    <Fill>
      <RadialGradient center="140,140" radius="260">
        <ColorStop offset="0" color="#FFF"/>
        <ColorStop offset="0.3" color="#06B6D4"/>
        <ColorStop offset="0.7" color="#3B82F6"/>
        <ColorStop offset="1" color="#1E293B"/>
      </RadialGradient>
    </Fill>
    <DropShadowStyle offsetY="8" blurX="32" blurY="32" color="#06B6D450"/>
  </Layer>
</pagx>

Calculation: For a point P, its color is determined by distance(P, center) / radius.

ConicGradient

Conic gradients (also known as sweep gradients) interpolate along the circumference.

<?xml version="1.0" encoding="UTF-8"?>
<!-- Demonstrates conic (sweep) gradient -->
<pagx version="1.0" width="400" height="400">
  <Layer>
    <Ellipse position="200,200" size="320,320"/>
    <Fill>
      <ConicGradient center="200,200">
        <ColorStop offset="0" color="#F43F5E"/>
        <ColorStop offset="0.2" color="#F59E0B"/>
        <ColorStop offset="0.4" color="#10B981"/>
        <ColorStop offset="0.6" color="#06B6D4"/>
        <ColorStop offset="0.8" color="#8B5CF6"/>
        <ColorStop offset="1" color="#F43F5E"/>
      </ConicGradient>
    </Fill>
    <DropShadowStyle offsetY="8" blurX="32" blurY="32" color="#8B5CF650"/>
  </Layer>
</pagx>

Calculation: For a point P, its color is determined by the ratio of atan2(P.y - center.y, P.x - center.x) within the [startAngle, endAngle] range.

Angle convention: Follows the global coordinate system convention (see §3.1): 0° points to the right (positive X-axis), and angles increase clockwise. This differs from CSS conic-gradient where 0° points to the top. Common reference angles:

DiamondGradient

Diamond gradients radiate from the center toward the four corners.

<?xml version="1.0" encoding="UTF-8"?>
<!-- Demonstrates diamond gradient -->
<pagx version="1.0" width="400" height="400">
  <!-- Rectangle size=320x320, half=160. Diamond radius=160 so corners touch rect edges exactly -->
  <Layer>
    <Rectangle position="200,200" size="320,320" roundness="24"/>
    <Fill>
      <DiamondGradient center="200,200" radius="160">
        <ColorStop offset="0" color="#FBBF24"/>
        <ColorStop offset="0.4" color="#F59E0B"/>
        <ColorStop offset="0.7" color="#D97706"/>
        <ColorStop offset="1" color="#1E293B"/>
      </DiamondGradient>
    </Fill>
    <DropShadowStyle offsetY="12" blurX="40" blurY="40" color="#F59E0B50"/>
  </Layer>
</pagx>

Calculation: For a point P, its color is determined by the Chebyshev distance max(|P.x - center.x|, |P.y - center.y|) / radius.

ColorStop

<ColorStop offset="0.5" color="#FF0000"/>

Common Gradient Rules:

• Stop Interpolation: Linear interpolation between adjacent color stops
• Stop Boundaries:
  • Stops with offset < 0 are treated as offset = 0
  • Stops with offset > 1 are treated as offset = 1
  • If there is no stop at offset = 0, the first stop's color is used to fill
  • If there is no stop at offset = 1, the last stop's color is used to fill

ImagePattern

Image patterns use an image as a color source.

<ImagePattern image="@img1" tileModeX="repeat" tileModeY="repeat"/>

TileMode: clamp, repeat, mirror, decal

FilterMode: nearest, linear

MipmapMode: none, nearest, linear

Complete Example: Demonstrates ImagePattern fill with different tile modes

<?xml version="1.0" encoding="UTF-8"?>
<!-- Demonstrates ImagePattern fill with different tile modes -->
<pagx version="1.0" width="400" height="400">
  <!-- Clamp mode: original size, centered in 140x140 rect -->
  <!-- Rectangle position=110,110 size=140,140: left-top=(40,40), right-bottom=(180,180) -->
  <!-- Image 256x256, scale 0.5 = 128x128 -->
  <!-- Center in rect: image left-top = 40 + (140-128)/2 = 46 -->
  <Layer name="ClampFill">
    <Rectangle position="110,110" size="140,140" roundness="24"/>
    <Fill>
      <ImagePattern image="@logo" tileModeX="clamp" tileModeY="clamp" matrix="0.5,0,0,0.5,46,46"/>
    </Fill>
    <Stroke color="#FFF" width="2"/>
  </Layer>

  <Layer name="RepeatFill">
    <Rectangle position="290,110" size="140,140" roundness="24"/>
    <Fill>
      <ImagePattern image="@logo" tileModeX="repeat" tileModeY="repeat" matrix="0.24,0,0,0.24,0,0"/>
    </Fill>
    <Stroke color="#FFF" width="2"/>
  </Layer>

  <Layer name="MirrorFill">
    <Rectangle position="110,290" size="140,140" roundness="24"/>
    <Fill>
      <ImagePattern image="@logo" tileModeX="mirror" tileModeY="mirror" matrix="0.24,0,0,0.24,0,0"/>
    </Fill>
    <Stroke color="#FFF" width="2"/>
  </Layer>

  <Layer name="RepeatScaled">
    <Rectangle position="290,290" size="140,140" roundness="24"/>
    <Fill>
      <ImagePattern image="@logo" tileModeX="repeat" tileModeY="repeat" matrix="0.35,0,0,0.35,0,0"/>
    </Fill>
    <Stroke color="#FFF" width="2"/>
  </Layer>
  
  <Resources>
    <Image id="logo" source="pag_logo.png"/>
  </Resources>
</pagx>

Color Source Coordinate System

Except for solid colors, all color sources (gradients, image patterns) operate within a coordinate system relative to the origin of the geometry element's local coordinate system. The matrix attribute can be used to apply transforms to the color source coordinate system.

Transform Behavior:

1. External transforms affect both geometry and color source: Group transforms, layer matrices, and other external transforms apply holistically to both the geometry element and its color source—they scale, rotate, and translate together.

2. Modifying geometry properties does not affect the color source: Directly modifying geometry element properties (such as Rectangle's width/height or Path's path data) only changes the geometry content itself without affecting the color source coordinate system.

Example: Drawing a diagonal linear gradient within a 300×300 region:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Demonstrates that color source coordinates are relative to geometry origin -->
<pagx version="1.0" width="400" height="400">
  <Layer>
    <Rectangle position="200,200" size="300,300" roundness="24"/>
    <Fill color="@grad"/>
    <DropShadowStyle offsetY="12" blurX="40" blurY="40" color="#EC489950"/>
  </Layer>
  <Resources>
    <LinearGradient id="grad" startPoint="0,0" endPoint="300,300">
      <ColorStop offset="0" color="#EC4899"/>
      <ColorStop offset="0.5" color="#8B5CF6"/>
      <ColorStop offset="1" color="#6366F1"/>
    </LinearGradient>
  </Resources>
</pagx>

• Applying scale(2, 2) transform to this layer: The rectangle becomes 600×600, and the gradient scales accordingly, maintaining consistent visual appearance
• Directly changing Rectangle's size to 600,600: The rectangle becomes 600×600, but the gradient coordinates remain unchanged, covering only the top-left quarter of the rectangle

3.3.4 Composition

Compositions are used for content reuse (similar to After Effects pre-comps).

<?xml version="1.0" encoding="UTF-8"?>
<!-- Demonstrates composition (reusable component) -->
<pagx version="1.0" width="400" height="400">
  <Layer composition="@buttonComp" x="100" y="60"/>
  <Layer composition="@buttonComp" x="100" y="170"/>
  <Layer composition="@buttonComp" x="100" y="280"/>
  <Resources>
    <Composition id="buttonComp" width="200" height="60">
      <Layer name="button">
        <Rectangle position="100,30" size="200,60" roundness="30"/>
        <Fill>
          <LinearGradient startPoint="0,0" endPoint="200,0">
            <ColorStop offset="0" color="#6366F1"/>
            <ColorStop offset="1" color="#8B5CF6"/>
          </LinearGradient>
        </Fill>
        <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#6366F180"/>
      </Layer>
      <Layer name="label">
        <Text text="Button" fontFamily="Arial" fontStyle="Bold" fontSize="22" position="100,36" textAnchor="center"/>
        <Fill color="#FFF"/>
      </Layer>
    </Composition>
  </Resources>
</pagx>

3.3.5 Font

Font defines embedded font resources containing subsetted glyph data (vector outlines or bitmaps). Embedding glyph data makes PAGX files fully self-contained, ensuring consistent rendering across platforms.

<!-- Embedded vector font -->
<Font id="myFont" unitsPerEm="1000">
  <Glyph advance="600" path="M 50 0 L 300 700 L 550 0 Z"/>
  <Glyph advance="550" path="M 100 0 L 100 700 L 400 700 C 550 700 550 400 400 400 Z"/>
</Font>

<!-- Embedded bitmap font (Emoji) -->
<Font id="emojiFont" unitsPerEm="136">
  <Glyph advance="136" image="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."/>
  <Glyph advance="136" image="emoji/heart.png" offset="0,-5"/>
</Font>

Consistency Constraint: All Glyphs within the same Font must be of the same type—either all path or all image. Mixing is not allowed.

GlyphID Rules:

• GlyphID starts from 1: Glyph list index + 1 = GlyphID
• GlyphID 0 is reserved: Represents a missing glyph; not rendered

Glyph

Glyph defines rendering data for a single glyph. Either path or image must be specified (but not both).

Glyph Types:

• Vector glyph: Specifies the path attribute using SVG path syntax to describe the outline
• Bitmap glyph: Specifies the image attribute for colored glyphs like emoji; position can be adjusted with offset

Coordinate System: Glyph paths and offsets use design space coordinates. During rendering, the scale factor is calculated from GlyphRun's fontSize and Font's unitsPerEm: scale = fontSize / unitsPerEm.

3.4 Document Hierarchy

PAGX documents organize content in a hierarchical structure:

<pagx>                          ← Root element (defines canvas dimensions)
├── <Layer>                     ← Layer (multiple allowed)
│   ├── Geometry elements       ← Rectangle, Ellipse, Path, Text, etc.
│   ├── Modifiers               ← TrimPath, RoundCorner, TextModifier, etc.
│   ├── Painters                ← Fill, Stroke
│   ├── <Group>                 ← VectorElement container (nestable)
│   ├── LayerStyle              ← DropShadowStyle, InnerShadowStyle, etc.
│   ├── LayerFilter             ← BlurFilter, ColorMatrixFilter, etc.
│   └── <Layer>                 ← Child layers (recursive structure)
│       └── ...
│
└── <Resources>                 ← Resources section (optional, defines reusable resources)
    ├── <Image>                 ← Image resource
    ├── <PathData>              ← Path data resource
    ├── <SolidColor>            ← Solid color definition
    ├── <LinearGradient>        ← Gradient definition
    ├── <ImagePattern>          ← Image pattern definition
    ├── <Font>                  ← Font resource (embedded font)
    │   └── <Glyph>             ← Glyph definition
    └── <Composition>           ← Composition definition
        └── <Layer>             ← Layers within composition

4. Layer System

Layers are the fundamental organizational units for PAGX content, offering comprehensive control over visual effects.

4.1 Core Concepts

This section introduces the core concepts of the layer system. These concepts form the foundation for understanding layer styles, filters, and masks.

Layer Rendering Pipeline

Painters (Fill, Stroke, etc.) bound to a layer are divided into background content and foreground content via the placement attribute, defaulting to background content. A single layer renders in the following order:

1. Layer Styles (below): Render layer styles positioned below content (e.g., drop shadows)
2. Background Content: Render Fill and Stroke with placement="background"
3. Child Layers: Recursively render all child layers in document order
4. Layer Styles (above): Render layer styles positioned above content (e.g., inner shadows)
5. Foreground Content: Render Fill and Stroke with placement="foreground" (drawn above child layers)
6. Layer Filters: Use the combined output of previous steps as input to the filter chain, applying all filters sequentially

Layer Content

Layer content refers to the complete rendering result of the layer's background content, child layers, and foreground content (steps 2, 3, and 5 in the rendering pipeline). It does not include layer styles or layer filters.

Layer styles compute their effects based on layer content. For example, when fill is placed in background content and stroke is placed in foreground content, the stroke renders above child layers, but drop shadows are still calculated based on the complete layer content including fill, child layers, and stroke.

Layer Contour

Layer contour is a binary (opaque or fully transparent) mask derived from the layer content. Compared to normal layer content, layer contour has these differences:

1. Alpha=0 fills are included: Geometry painted with completely transparent color is still included in the contour
2. Solid color / gradient fills: Original colors are replaced with opaque white
3. Image fills: Fully transparent pixels remain transparent; all other pixels become fully opaque

Note: Geometry elements without painters (standalone Rectangle, Ellipse, etc.) do not participate in contour.

Layer Background

Layer background refers to the composited result of all rendered content below the current layer, including:

• Rendering results of all sibling layers below the current layer and their subtrees
• Layer styles already drawn below the current layer (excluding BackgroundBlurStyle itself)

Layer background is primarily used for:

• Layer Styles: Some layer styles require background as one of their input sources
• Blend Modes: Some blend modes require background information for correct rendering

Background Pass-through: The passThroughBackground attribute controls whether layer background passes through to child layers. When set to false, child layers' background-dependent styles cannot access the correct layer background. The following conditions automatically disable background pass-through:

• Layer uses a non-normal blend mode
• Layer has filters applied
• Layer uses 3D transforms or projection transforms

4.2 Layer

<Layer> is the basic container for content and child layers.

<?xml version="1.0" encoding="UTF-8"?>
<!-- Demonstrates layer properties and nesting -->
<pagx version="1.0" width="400" height="400">
  <!-- Parent layer with nested child -->
  <Layer name="Parent" x="50" y="50">
    <Rectangle position="150,150" size="260,260" roundness="32"/>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="260,260">
        <ColorStop offset="0" color="#F43F5E"/>
        <ColorStop offset="1" color="#EC4899"/>
      </LinearGradient>
    </Fill>
    <DropShadowStyle offsetY="16" blurX="40" blurY="40" color="#F43F5E60"/>
    <!-- Nested child layer -->
    <Layer name="Child">
      <Ellipse position="150,150" size="120,120"/>
      <Fill color="#FFF"/>
      <DropShadowStyle offsetY="4" blurX="16" blurY="16" color="#00000030"/>
    </Layer>
  </Layer>
</pagx>

Child Elements

Layer child elements are automatically categorized into four collections by type:

Recommended Order: Although child element order does not affect parsing results, it is recommended to write them in the order: VectorElement → LayerStyle → LayerFilter → child Layer, for improved readability.

Layer Attributes

groupOpacity: When false (default), the layer's alpha is applied independently to each child element, which may cause overlapping semi-transparent children to appear darker at intersections. When true, all layer content is first composited into an offscreen buffer, then alpha is applied to the buffer as a whole, producing uniform transparency across the entire layer.

preserve3D: When false (default), child layers with 3D transforms are flattened into the parent's 2D plane before compositing. When true, child layers retain their 3D positions and are rendered in a shared 3D space, enabling depth-based intersections and correct z-ordering among siblings. Similar to CSS transform-style: preserve-3d.

Transform Attribute Priority: x/y, matrix, and matrix3D have an override relationship:

• Only x/y set: Uses x/y for translation
• matrix set: matrix overrides x/y values
• matrix3D set: matrix3D overrides both matrix and x/y values

MaskType:

BlendMode: See Section 2.9 for the complete blend mode table.

4.3 Layer Styles

Layer styles add visual effects above or below layer content without modifying the original.

Input Sources for Layer Styles:

All layer styles compute effects based on layer content. During computation, layer content is converted to its opaque counterpart: geometric shapes are rendered with their normal fills, then all semi-transparent pixels are converted to fully opaque (fully transparent pixels are preserved). This means shadows produced by semi-transparent fills appear the same as those from fully opaque fills.

Some layer styles additionally use layer contour or layer background as input (see individual style descriptions). Definitions of layer contour and layer background are in Section 4.1.

<?xml version="1.0" encoding="UTF-8"?>
<!-- Demonstrates layer styles: DropShadow and InnerShadow -->
<pagx version="1.0" width="400" height="400">
  <Layer x="70" y="70">
    <Rectangle position="130,130" size="260,260" roundness="40"/>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="260,260">
        <ColorStop offset="0" color="#06B6D4"/>
        <ColorStop offset="1" color="#0891B2"/>
      </LinearGradient>
    </Fill>
    <DropShadowStyle offsetY="16" blurX="48" blurY="48" color="#06B6D480"/>
    <InnerShadowStyle offsetX="8" offsetY="8" blurX="24" blurY="24" color="#00000040"/>
  </Layer>
</pagx>

Common LayerStyle Attributes:

excludeChildEffects: When false (default), the layer style computes based on the full layer content including child layers' rendering results. When true, child layers' styles and filters are excluded from the layer content used to compute this style, but child layers' base rendering results are still included.

4.3.1 DropShadowStyle

Draws a drop shadow below the layer. Computes shadow shape based on opaque layer content.

Rendering Steps:

1. Get opaque layer content and offset by (offsetX, offsetY)
2. Apply Gaussian blur (blurX, blurY) to the offset content
3. Fill the shadow region with color
4. If showBehindLayer="false", use layer contour as erase mask to cut out occluded portion

showBehindLayer:

• true: Shadow displays completely, including portion occluded by layer content
• false: Portion of shadow occluded by layer content is cut out (using layer contour as erase mask)

4.3.2 BackgroundBlurStyle

Applies blur effect to layer background below the layer. Computes effect based on layer background, using opaque layer content as mask for clipping.

Rendering Steps:

1. Get layer background below layer bounds
2. Apply Gaussian blur (blurX, blurY) to layer background
3. Clip blurred result using opaque layer content as mask

4.3.3 InnerShadowStyle

Draws an inner shadow above the layer, appearing inside the layer content. Computes shadow range based on opaque layer content.

Rendering Steps:

1. Get opaque layer content and offset by (offsetX, offsetY)
2. Apply Gaussian blur (blurX, blurY) to the inverse of the offset content (exterior region)
3. Fill the shadow region with color
4. Intersect with opaque layer content, keeping only shadow inside content

4.4 Layer Filters

Layer filters are the final stage of layer rendering. All previously rendered results (including layer styles) accumulated in order serve as filter input. Filters are applied in chain fashion according to document order, with each filter's output becoming the next filter's input.

Unlike layer styles (Section 4.3), which independently render visual effects above or below layer content, filters modify the layer's overall rendering output. Layer styles are applied before filters.

<?xml version="1.0" encoding="UTF-8"?>
<!-- Demonstrates layer filters: Blur and DropShadow -->
<pagx version="1.0" width="400" height="400">
  <Layer x="70" y="70">
    <Rectangle position="130,130" size="260,260" roundness="40"/>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="260,260">
        <ColorStop offset="0" color="#8B5CF6"/>
        <ColorStop offset="1" color="#6366F1"/>
      </LinearGradient>
    </Fill>
    <BlurFilter blurX="4" blurY="4"/>
    <DropShadowFilter offsetX="0" offsetY="16" blurX="48" blurY="48" color="#8B5CF680"/>
  </Layer>
</pagx>

4.4.1 BlurFilter

4.4.2 DropShadowFilter

Generates shadow effect based on filter input. Unlike DropShadowStyle, the filter projects from original rendering content and preserves semi-transparency, whereas the style projects from opaque layer content.

Rendering Steps:

1. Offset filter input by (offsetX, offsetY)
2. Extract alpha channel and apply Gaussian blur (blurX, blurY)
3. Fill shadow region with color
4. Composite shadow with filter input (shadowOnly=false) or output shadow only (shadowOnly=true)

4.4.3 InnerShadowFilter

Draws shadow inside the filter input.

Rendering Steps:

1. Create inverse mask of filter input's alpha channel
2. Offset and apply Gaussian blur
3. Intersect with filter input's alpha channel
4. Composite result with filter input (shadowOnly=false) or output shadow only (shadowOnly=true)

4.4.4 BlendFilter

Overlays a specified color onto the layer using a specified blend mode.

4.4.5 ColorMatrixFilter

Transforms colors using a 4×5 color matrix.

Matrix Format (20 values, row-major):

| R' |   | m[0]  m[1]  m[2]  m[3]  m[4]  |   | R |
| G' |   | m[5]  m[6]  m[7]  m[8]  m[9]  |   | G |
| B' | = | m[10] m[11] m[12] m[13] m[14] | × | B |
| A' |   | m[15] m[16] m[17] m[18] m[19] |   | A |
                                            | 1 |

4.5 Clipping and Masking

4.5.1 scrollRect

The scrollRect attribute defines the layer's visible region; content outside this region is clipped.

<?xml version="1.0" encoding="UTF-8"?>
<!-- Demonstrates scrollRect clipping -->
<pagx version="1.0" width="400" height="400">
  <Layer x="100" y="100" scrollRect="100,100,200,200">
    <Ellipse position="200,200" size="320,320"/>
    <Fill>
      <RadialGradient center="200,200" radius="160">
        <ColorStop offset="0" color="#F43F5E"/>
        <ColorStop offset="0.6" color="#EC4899"/>
        <ColorStop offset="1" color="#8B5CF6"/>
      </RadialGradient>
    </Fill>
  </Layer>
  <!-- Visible clip region indicator (dashed border) -->
  <Layer>
    <Rectangle position="200,200" size="200,200" roundness="16"/>
    <Stroke color="#94A3B840" width="2" dashes="4,4"/>
  </Layer>
</pagx>

4.5.2 Masking

Reference another layer as a mask using the mask attribute.

<?xml version="1.0" encoding="UTF-8"?>
<!-- Demonstrates alpha masking -->
<pagx version="1.0" width="400" height="400">
  <!-- Mask shape (invisible but used for masking) -->
  <Layer id="maskShape" visible="false">
    <Polystar position="200,200" type="star" pointCount="5" outerRadius="150" innerRadius="70" rotation="-90"/>
    <Fill color="#FFF"/>
  </Layer>
  <Layer mask="@maskShape">
    <Rectangle position="200,200" size="360,360"/>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="360,360">
        <ColorStop offset="0" color="#6366F1"/>
        <ColorStop offset="0.33" color="#8B5CF6"/>
        <ColorStop offset="0.66" color="#EC4899"/>
        <ColorStop offset="1" color="#F43F5E"/>
      </LinearGradient>
    </Fill>
  </Layer>
</pagx>

Masking Rules:

• The mask layer itself is not rendered (the visible attribute is ignored)
• The mask layer's transforms do not affect the masked layer

5. VectorElement System

The VectorElement system defines how vector content within Layers is processed and rendered.

5.1 Processing Model

The VectorElement system employs an accumulate-render processing model: geometry elements accumulate in a rendering context, modifiers transform the accumulated geometry, and painters trigger final rendering.

5.1.1 Terminology

5.1.2 Internal Structure of Geometry Elements

Geometry elements have different internal structures when accumulating in the context:

5.1.3 Processing and Rendering Order

VectorElements are processed sequentially in document order; elements appearing earlier are processed first. By default, painters processed earlier are rendered first (appearing below).

Since Fill and Stroke can specify rendering to layer background or foreground via the placement attribute, the final rendering order may not exactly match document order. However, in the default case (all content as background), rendering order matches document order.

5.1.4 Unified Processing Flow

Geometry Elements        Modifiers              Painters
┌──────────┐          ┌──────────┐          ┌──────────┐
│Rectangle │          │ TrimPath │          │   Fill   │
│ Ellipse  │          │RoundCorn │          │  Stroke  │
│ Polystar │          │MergePath │          └────┬─────┘
│   Path   │          │TextModif │               │
│   Text   │          │ TextPath │               │
└────┬─────┘          │TextBox   │               │
     │                │ Repeater │               │
     │                └────┬─────┘               │
     │                     │                     │
     │ Accumulate          │ Transform           │ Render
     ▼                     ▼                     ▼
┌─────────────────────────────────────────────────────────┐
│ Geometry List [Path1, Path2, GlyphList1, GlyphList2...] │
└─────────────────────────────────────────────────────────┘

Rendering context accumulates a geometry list where:

• Each shape element contributes one Path
• Each Text contributes a glyph list (containing multiple glyphs)

5.1.5 Modifier Scope

Different modifiers have different scopes over elements in the geometry list:

5.2 Geometry Elements

Geometry elements provide renderable shapes.

5.2.1 Rectangle

Rectangles are defined from center point with uniform corner rounding support.

<Rectangle position="100,100" size="200,150" roundness="10" reversed="false"/>

Calculation Rules:

rect.left   = position.x - size.width / 2
rect.top    = position.y - size.height / 2
rect.right  = position.x + size.width / 2
rect.bottom = position.y + size.height / 2

Corner Rounding:

• roundness value is automatically limited to min(roundness, size.width/2, size.height/2)
• When roundness >= min(size.width, size.height) / 2, the shorter dimension becomes semicircular

Path Start Point: Rectangle path starts from the top-right corner, drawn clockwise (reversed="false").

Example:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Demonstrates Rectangle shape with various roundness values -->
<pagx version="1.0" width="400" height="400">
  <!-- Sharp rectangle -->
  <Layer>
    <Rectangle position="110,110" size="140,140"/>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="140,140">
        <ColorStop offset="0" color="#F43F5E"/>
        <ColorStop offset="1" color="#E11D48"/>
      </LinearGradient>
    </Fill>
    <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#F43F5E50"/>
  </Layer>
  <!-- Medium rounded rectangle -->
  <Layer>
    <Rectangle position="290,110" size="140,140" roundness="24"/>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="140,140">
        <ColorStop offset="0" color="#8B5CF6"/>
        <ColorStop offset="1" color="#7C3AED"/>
      </LinearGradient>
    </Fill>
    <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#8B5CF650"/>
  </Layer>
  <!-- Fully rounded rectangle (pill shape) -->
  <Layer>
    <Rectangle position="110,290" size="140,140" roundness="70"/>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="140,140">
        <ColorStop offset="0" color="#06B6D4"/>
        <ColorStop offset="1" color="#0891B2"/>
      </LinearGradient>
    </Fill>
    <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#06B6D450"/>
  </Layer>
  <!-- Wide rectangle -->
  <Layer>
    <Rectangle position="290,290" size="140,100" roundness="16"/>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="140,100">
        <ColorStop offset="0" color="#10B981"/>
        <ColorStop offset="1" color="#059669"/>
      </LinearGradient>
    </Fill>
    <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#10B98150"/>
  </Layer>
</pagx>

5.2.2 Ellipse

Ellipses are defined from center point.

<Ellipse position="100,100" size="100,60" reversed="false"/>

Calculation Rules:

boundingRect.left   = position.x - size.width / 2
boundingRect.top    = position.y - size.height / 2
boundingRect.right  = position.x + size.width / 2
boundingRect.bottom = position.y + size.height / 2

Path Start Point: Ellipse path starts from the right midpoint (3 o'clock position).

Example:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Demonstrates Ellipse shape -->
<pagx version="1.0" width="400" height="400">
  <!-- Perfect circle -->
  <Layer>
    <Ellipse position="120,120" size="140,140"/>
    <Fill>
      <RadialGradient center="50,50" radius="100">
        <ColorStop offset="0" color="#FBBF24"/>
        <ColorStop offset="1" color="#F59E0B"/>
      </RadialGradient>
    </Fill>
    <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#F59E0B60"/>
  </Layer>
  <!-- Horizontal ellipse -->
  <Layer>
    <Ellipse position="290,110" size="160,100"/>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="160,100">
        <ColorStop offset="0" color="#EC4899"/>
        <ColorStop offset="1" color="#DB2777"/>
      </LinearGradient>
    </Fill>
    <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#EC489950"/>
  </Layer>
  <!-- Vertical ellipse -->
  <Layer>
    <Ellipse position="110,290" size="100,160"/>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="100,160">
        <ColorStop offset="0" color="#06B6D4"/>
        <ColorStop offset="1" color="#0891B2"/>
      </LinearGradient>
    </Fill>
    <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#06B6D450"/>
  </Layer>
  <!-- Large ellipse -->
  <Layer>
    <Ellipse position="290,280" size="150,150"/>
    <Fill>
      <RadialGradient center="55,55" radius="100">
        <ColorStop offset="0" color="#A78BFA"/>
        <ColorStop offset="1" color="#8B5CF6"/>
      </RadialGradient>
    </Fill>
    <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#8B5CF650"/>
  </Layer>
</pagx>

5.2.3 Polystar

Supports both regular polygon and star modes.

<Polystar position="100,100" type="star" pointCount="5" outerRadius="100" innerRadius="50" rotation="0" outerRoundness="0" innerRoundness="0" reversed="false"/>

PolystarType:

Polygon Mode (type="polygon"):

• Uses only outerRadius and outerRoundness
• innerRadius and innerRoundness are ignored

Star Mode (type="star"):

• Outer vertices at outerRadius
• Inner vertices at innerRadius
• Vertices alternate to form star shape

Vertex Calculation (i-th outer vertex):

angle = rotation + (i / pointCount) * 360°
x = position.x + outerRadius * cos(angle)
y = position.y + outerRadius * sin(angle)

Fractional Point Count:

• pointCount supports decimal values (e.g., 5.5)
• The fractional part determines how much of the final vertex is drawn, producing an incomplete corner
• pointCount <= 0 generates no path

Roundness:

• outerRoundness and innerRoundness range from 0~1
• 0 means sharp corners; 1 means fully rounded
• Roundness is achieved by adding Bézier control points at vertices

Example:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Demonstrates Polystar shape (star and polygon) -->
<pagx version="1.0" width="400" height="400">
  <!-- 5-pointed star -->
  <Layer>
    <Polystar position="110,110" type="star" pointCount="5" outerRadius="60" innerRadius="28" rotation="-90"/>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="120,120">
        <ColorStop offset="0" color="#FBBF24"/>
        <ColorStop offset="1" color="#F59E0B"/>
      </LinearGradient>
    </Fill>
    <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#F59E0B60"/>
  </Layer>
  <!-- 6-pointed star -->
  <Layer>
    <Polystar position="290,110" type="star" pointCount="6" outerRadius="60" innerRadius="32" rotation="-90"/>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="120,120">
        <ColorStop offset="0" color="#F43F5E"/>
        <ColorStop offset="1" color="#E11D48"/>
      </LinearGradient>
    </Fill>
    <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#F43F5E50"/>
  </Layer>
  <!-- Hexagon (polygon) -->
  <Layer>
    <Polystar position="110,290" type="polygon" pointCount="6" outerRadius="64"/>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="128,128">
        <ColorStop offset="0" color="#06B6D4"/>
        <ColorStop offset="1" color="#0891B2"/>
      </LinearGradient>
    </Fill>
    <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#06B6D450"/>
  </Layer>
  <!-- Pentagon (polygon) -->
  <Layer>
    <Polystar position="290,290" type="polygon" pointCount="5" outerRadius="64" rotation="-90"/>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="128,128">
        <ColorStop offset="0" color="#8B5CF6"/>
        <ColorStop offset="1" color="#7C3AED"/>
      </LinearGradient>
    </Fill>
    <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#8B5CF650"/>
  </Layer>
</pagx>

5.2.4 Path

Defines arbitrary shapes using SVG path syntax, supporting inline data or references to PathData defined in Resources.

<!-- Inline path data -->
<Path data="M 0 0 L 100 0 L 100 100 Z" reversed="false"/>

<!-- Reference PathData resource -->
<Path data="@curvePath" reversed="false"/>

Example:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Demonstrates Path shape with custom bezier curves -->
<pagx version="1.0" width="400" height="400">
  
  <!-- Heart shape (top-left quadrant: 0-200 x 0-200, center at 100,100) -->
  <Layer>
    <Path data="M 100,80 C 100,60 120,50 140,50 C 160,50 170,60 170,80 C 170,100 140,140 100,170 C 60,140 30,100 30,80 C 30,60 40,50 60,50 C 80,50 100,60 100,80 Z"/>
    <Fill>
      <LinearGradient startPoint="30,50" endPoint="170,170">
        <ColorStop offset="0" color="#F43F5E"/>
        <ColorStop offset="1" color="#EC4899"/>
      </LinearGradient>
    </Fill>
    <DropShadowStyle offsetY="4" blurX="16" blurY="16" color="#F43F5E60"/>
  </Layer>
  
  <!-- Lightning bolt (top-right quadrant: 200-400 x 0-200, center at 300,100) -->
  <Layer>
    <Path data="M 310,45 L 275,110 L 305,110 L 270,195 L 340,100 L 310,100 L 340,45 Z"/>
    <Fill>
      <LinearGradient startPoint="270,45" endPoint="340,195">
        <ColorStop offset="0" color="#FBBF24"/>
        <ColorStop offset="1" color="#F59E0B"/>
      </LinearGradient>
    </Fill>
    <DropShadowStyle offsetY="4" blurX="12" blurY="12" color="#F59E0B60"/>
  </Layer>
  
  <!-- Arrow (bottom-left quadrant: 0-200 x 200-400, center at 100,300) -->
  <Layer>
    <Path data="M 30,290 L 130,290 L 130,260 L 180,300 L 130,340 L 130,310 L 30,310 Z"/>
    <Fill color="#06B6D4"/>
    <DropShadowStyle offsetY="4" blurX="12" blurY="12" color="#06B6D460"/>
  </Layer>
  
  <!-- Star (bottom-right quadrant: 200-400 x 200-400, center at 300,300) -->
  <Layer>
    <Path data="M 300,220 L 318,270 L 370,270 L 328,300 L 343,350 L 300,322 L 257,350 L 272,300 L 230,270 L 282,270 Z"/>
    <Fill color="#8B5CF6"/>
    <DropShadowStyle offsetY="4" blurX="12" blurY="12" color="#8B5CF660"/>
  </Layer>
</pagx>

5.2.5 Text

Text elements provide geometric shapes for text content. Unlike shape elements that produce a single Path, Text produces a glyph list (multiple glyphs) after shaping, which accumulates in the rendering context's geometry list for subsequent modifier transformation or painter rendering.

<Text text="Hello World" position="100,200" fontFamily="Arial" fontStyle="Regular" fauxBold="true" fauxItalic="false" fontSize="24" letterSpacing="0" textAnchor="start"/>

Child elements: CDATA text, GlyphRun*

Text Content: Typically use the text attribute to specify text content. When text contains XML special characters (<, >, &, etc.) or needs to preserve multi-line formatting, use a CDATA child node instead of the text attribute. Text does not allow direct plain text child nodes; CDATA wrapping is required.

<!-- Simple text: use text attribute -->
<Text text="Hello World" fontFamily="Arial" fontSize="24"/>

<!-- Contains special characters: use CDATA -->
<Text fontFamily="Arial" fontSize="24"><![CDATA[A < B & C > D]]></Text>

<!-- Multi-line text: use CDATA to preserve formatting -->
<Text fontFamily="Arial" fontSize="24">
<![CDATA[Line 1
Line 2
Line 3]]>
</Text>

Rendering Modes: Text supports pre-layout and runtime layout modes. Pre-layout provides pre-computed glyphs and positions via GlyphRun child nodes, rendering with embedded fonts for cross-platform consistency. Runtime layout performs shaping and layout at runtime; due to platform differences in fonts and layout features, minor inconsistencies may occur. For pixel-perfect reproduction of design tool layouts, pre-layout is recommended.

TextAnchor (Text Anchor Alignment):

Controls how text is positioned relative to its origin point.

Runtime Layout Rendering Flow:

1. Find system font based on fontFamily and fontStyle; if unavailable, select fallback font according to runtime-configured fallback list
2. Shape using text attribute (or CDATA child node); newlines trigger line breaks (default 1.2× font size line height, customizable via TextBox)
3. Apply typography parameters: fontSize, letterSpacing
4. Construct glyph list and accumulate to rendering context

Runtime Layout Example:

<?xml version="1.0" encoding="UTF-8"?>
<pagx version="1.0" width="400" height="400">
  <Layer>
    <Text text="PAGX" fontFamily="Arial" fontStyle="Bold" fontSize="84" position="200,145" textAnchor="center"/>
    <Fill>
      <LinearGradient startPoint="-200,0" endPoint="80,0">
        <ColorStop offset="0" color="#6366F1"/>
        <ColorStop offset="0.5" color="#8B5CF6"/>
        <ColorStop offset="1" color="#EC4899"/>
      </LinearGradient>
    </Fill>
  </Layer>
  <Layer>
    <Text text="Text Shape" fontFamily="Arial" fontSize="36" position="200,230" textAnchor="center"/>
    <Fill color="#334155"/>
  </Layer>
  <Layer>
    <Text text="Beautiful Typography" fontFamily="Arial" fontSize="24" position="200,310" textAnchor="center"/>
    <Fill color="#475569"/>
  </Layer>
</pagx>

GlyphRun (Pre-layout Data)

GlyphRun defines pre-layout data for a group of glyphs, each GlyphRun independently referencing one font resource.

All attributes are optional and can be combined. When an attribute array is shorter than the glyph count, missing values use defaults.

Position Calculation:

finalX[i] = x + xOffsets[i] + positions[i].x
finalY[i] = y + positions[i].y

• When xOffsets is not specified, xOffsets[i] is treated as 0
• When positions is not specified, positions[i] is treated as (0, 0)
• When neither xOffsets nor positions is specified: First glyph positioned at (x, y), subsequent glyphs positioned by accumulating each Glyph's advance attribute

Transform Application Order:

When a glyph has scale, rotation, or skew transforms, they are applied in the following order (consistent with TextModifier):

1. Translate to anchor (translate(-anchor))
2. Scale (scale)
3. Skew (skew, along vertical axis)
4. Rotate (rotation)
5. Translate back from anchor (translate(anchor))
6. Translate to position (translate(position))

Anchor:

• Each glyph's default anchor is at (advance × 0.5, 0), the horizontal center at baseline
• The anchors attribute records offsets relative to the default anchor, final anchor = default anchor + anchors[i]

Pre-layout Example:

<?xml version="1.0" encoding="UTF-8"?>
<pagx version="1.0" width="400" height="400">
  <Layer>
    <Text text="GlyphRun" fontFamily="Arial" fontStyle="Bold" fontSize="72">
      <GlyphRun font="@font1" fontSize="72" glyphs="14,15,16,17,18,19,20,21" x="34" y="145"/>
    </Text>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="280,0">
        <ColorStop offset="0" color="#6366F1"/>
        <ColorStop offset="0.5" color="#8B5CF6"/>
        <ColorStop offset="1" color="#EC4899"/>
      </LinearGradient>
    </Fill>
  </Layer>
  <Layer>
    <Text text="Embedded Font" fontFamily="Arial" fontSize="36">
      <GlyphRun font="@font1" fontSize="36" glyphs="6,7,8,9,10,10,9,10,22,11,12,21,13" y="230" xOffsets="66,87,120,142,162,184,206,226,248,256,276,298,320"/>
    </Text>
    <Fill color="#334155"/>
  </Layer>
  <Layer>
    <Text text="Pre-shaped Glyphs" fontFamily="Arial" fontSize="24">
      <GlyphRun font="@font1" fontSize="24" glyphs="1,2,9,3,4,18,5,17,9,10,22,14,15,16,17,18,4" y="310" xOffsets="94.5,109.5,118.5,131.5,139.5,150.5,165.5,179.5,194.5,207.5,222.5,227.5,244.5,251.5,264.5,279.5,294.5"/>
    </Text>
    <Fill color="#475569"/>
  </Layer>
  <Resources>
    <Font id="font1">
      <Glyph path="M100 0L193 0L193 -299L314 -299C475 -299 584 -372 584 -531C584 -693 474 -750 310 -750L100 -750L100 0ZM193 -375L193 -674L298 -674C426 -674 492 -639 492 -531C492 -423 431 -375 301 -375L193 -375Z" advance="625"/>
      <Glyph path="M92 0L183 0L183 -337C219 -427 275 -458 320 -458C342 -458 355 -456 372 -450L390 -542C372 -538 355 -542 331 -542C271 -542 215 -497 178 -429L174 -429L167 -542L92 -542L92 0Z" advance="375"/>
      <Glyph path="M46 -250L301 -250L301 -320L46 -320L46 -250Z" advance="333.333"/>
      <Glyph path="M234 0C362 0 432 -72 432 -155C432 -251 344 -281 266 -309C204 -330 148 -348 148 -396C148 -436 181 -469 250 -469C298 -469 336 -451 372 -424L417 -480C375 -513 316 -542 249 -542C131 -542 61 -473 61 -393C61 -307 144 -272 219 -246C280 -225 344 -202 344 -150C344 -106 309 -71 237 -71C172 -71 122 -95 76 -130L31 -74C83 -32 157 0 234 0Z" advance="458.333"/>
      <Glyph path="M217 0C284 0 344 -35 396 -77L400 -77L408 0L482 0L482 -323C482 -453 426 -542 295 -542C208 -542 131 -503 81 -470L117 -410C160 -438 217 -465 280 -465C368 -465 392 -400 392 -333C161 -307 58 -251 58 -136C58 -56 126 0 217 0ZM243 -73C189 -73 146 -96 146 -154C146 -219 209 -261 392 -282L392 -140C339 -96 296 -73 243 -73Z" advance="583.333"/>
      <Glyph path="M100 0L534 0L534 -79L193 -79L193 -338L471 -338L471 -417L193 -417L193 -643L523 -643L523 -722L100 -722L100 0Z" advance="583.333"/>
      <Glyph path="M92 0L183 0L183 -392C233 -448 279 -475 320 -475C389 -475 421 -432 421 -331L421 0L512 0L512 -392C563 -448 607 -475 649 -475C718 -475 750 -432 750 -331L750 0L841 0L841 -343C841 -481 788 -556 676 -556C610 -556 553 -512 497 -451C475 -515 430 -556 347 -556C282 -556 225 -514 178 -462L175 -462L167 -556L92 -556L92 0Z" advance="916.667"/>
      <Glyph path="M331 0C456 0 567 -106 567 -286C567 -447 491 -556 350 -556C290 -556 229 -521 180 -478L183 -576L183 -794L92 -794L92 0L165 0L173 -69L177 -69C224 -26 281 0 331 0ZM316 -76C280 -76 231 -90 183 -131L183 -406C235 -453 283 -478 329 -478C432 -478 472 -400 472 -284C472 -154 406 -76 316 -76Z" advance="611.111"/>
      <Glyph path="M311 0C385 0 443 -25 491 -56L458 -113C418 -88 375 -73 322 -73C219 -73 148 -142 142 -250L508 -250C510 -263 512 -282 512 -302C512 -456 434 -556 296 -556C170 -556 51 -446 51 -271C51 -102 167 0 311 0ZM141 -316C152 -421 220 -482 297 -482C382 -482 432 -424 432 -316L141 -316Z" advance="555.556"/>
      <Glyph path="M277 0C342 0 399 -35 442 -77L445 -77L453 0L527 0L527 -794L437 -794L437 -586L441 -491C393 -531 352 -556 288 -556C164 -556 53 -445 53 -270C53 -102 141 0 277 0ZM297 -76C201 -76 147 -151 147 -278C147 -397 216 -478 304 -478C349 -478 390 -463 437 -423L437 -148C391 -100 347 -76 297 -76Z" advance="611.111"/>
      <Glyph path="M100 0L193 0L193 -333L473 -333L473 -411L193 -411L193 -643L523 -643L523 -722L100 -722L100 0Z" advance="555.556"/>
      <Glyph path="M303 0C436 0 555 -103 555 -276C555 -451 436 -556 303 -556C170 -556 51 -451 51 -276C51 -103 170 0 303 0ZM303 -76C209 -76 146 -156 146 -276C146 -397 209 -479 303 -479C397 -479 461 -397 461 -276C461 -156 397 -76 303 -76Z" advance="611.111"/>
      <Glyph path="M263 0C296 0 332 -10 363 -20L345 -88C327 -81 302 -74 283 -74C220 -74 199 -112 199 -179L199 -481L346 -481L346 -556L199 -556L199 -708L123 -708L112 -556L27 -550L27 -481L108 -481L108 -181C108 -73 147 0 263 0Z" advance="388.889"/>
      <Glyph path="M388 14C487 14 568 -22 615 -71L615 -382L375 -382L375 -306L530 -306L530 -111C501 -83 450 -67 398 -67C240 -67 153 -185 153 -372C153 -555 249 -669 396 -669C471 -669 518 -638 555 -599L605 -659C563 -704 496 -750 394 -750C200 -750 58 -606 58 -368C58 -128 196 14 388 14Z" advance="694.444"/>
      <Glyph path="M188 14C213 14 228 11 241 6L228 -64C218 -62 214 -62 209 -62C195 -62 183 -73 183 -101L183 -795L92 -795L92 -107C92 -30 120 14 188 14Z" advance="291.667"/>
      <Glyph path="M101 236C209 236 266 154 303 47L508 -542L419 -542L322 -239C307 -191 291 -136 276 -87L271 -87C254 -136 235 -192 219 -239L108 -542L13 -542L231 3L219 44C197 111 158 161 96 161C82 161 66 156 55 152L37 225C54 232 75 236 101 236Z" advance="527.778"/>
      <Glyph path="M92 222L183 222L183 45L181 -49C230 -9 282 14 331 14C456 14 567 -93 567 -279C567 -446 491 -556 351 -556C288 -556 227 -520 178 -479L175 -479L167 -542L92 -542L92 222ZM316 -62C280 -62 232 -77 183 -119L183 -403C236 -452 283 -479 329 -479C432 -479 472 -398 472 -278C472 -143 406 -62 316 -62Z" advance="625"/>
      <Glyph path="M92 0L183 0L183 -393C238 -447 276 -475 332 -475C404 -475 435 -433 435 -331L435 0L526 0L526 -343C526 -481 474 -556 360 -556C286 -556 230 -515 180 -464L183 -576L183 -794L92 -794L92 0Z" advance="611.111"/>
      <Glyph path="M100 0L193 0L193 -314L325 -314L503 0L608 0L420 -324C520 -348 586 -416 586 -529C586 -682 479 -736 330 -736L100 -736L100 0ZM193 -389L193 -660L316 -660C431 -660 494 -626 494 -529C494 -435 431 -389 316 -389L193 -389Z" advance="638.889"/>
      <Glyph path="M250 14C325 14 379 -25 430 -84L433 -84L440 0L516 0L516 -542L425 -542L425 -157C373 -92 334 -65 278 -65C206 -65 176 -108 176 -209L176 -542L85 -542L85 -198C85 -60 136 14 250 14Z" advance="611.111"/>
      <Glyph path="M92 0L183 0L183 -393C238 -447 276 -475 332 -475C404 -475 435 -433 435 -331L435 0L526 0L526 -343C526 -481 474 -556 360 -556C286 -556 230 -515 178 -464L175 -464L167 -542L92 -542L92 0Z" advance="611.111"/>
      <Glyph advance="208.333"/>
    </Font>
  </Resources>
</pagx>

5.3 Painters

Painters (Fill, Stroke) render all geometry (Paths and glyph lists) accumulated at the current moment.

5.3.1 Fill

Fill draws the interior region of geometry using a specified color source.

<?xml version="1.0" encoding="UTF-8"?>
<!-- Demonstrates different fill types -->
<pagx version="1.0" width="400" height="400">
  <!-- Solid color fill -->
  <Layer>
    <Rectangle position="110,110" size="140,140" roundness="24"/>
    <Fill color="#F43F5E"/>
    <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#F43F5E50"/>
  </Layer>
  <!-- Linear gradient fill -->
  <Layer>
    <Rectangle position="290,110" size="140,140" roundness="24"/>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="140,140">
        <ColorStop offset="0" color="#6366F1"/>
        <ColorStop offset="1" color="#8B5CF6"/>
      </LinearGradient>
    </Fill>
    <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#8B5CF650"/>
  </Layer>
  <!-- Radial gradient fill -->
  <Layer>
    <Ellipse position="200,300" size="320,140"/>
    <Fill>
      <RadialGradient center="160,70" radius="170">
        <ColorStop offset="0" color="#FFF"/>
        <ColorStop offset="0.5" color="#06B6D4"/>
        <ColorStop offset="1" color="#0891B2"/>
      </RadialGradient>
    </Fill>
    <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#06B6D450"/>
  </Layer>
</pagx>

Child elements: May embed one color source (SolidColor, LinearGradient, RadialGradient, ConicGradient, DiamondGradient, ImagePattern)

FillRule:

Text Fill:

• Text is filled per glyph
• Supports color override for individual glyphs via TextModifier
• Color override uses alpha blending: finalColor = lerp(originalColor, overrideColor, overrideAlpha)

5.3.2 Stroke

Stroke draws lines along geometry boundaries.

<?xml version="1.0" encoding="UTF-8"?>
<pagx version="1.0" width="400" height="400">
  <Layer>
    <Rectangle position="110,110" size="130,130" roundness="20"/>
    <Stroke color="#06B6D4" width="8" cap="round" join="round"/>
  </Layer>
  <Layer>
    <Rectangle position="290,110" size="130,130" roundness="20"/>
    <Stroke color="#8B5CF6" width="6" dashes="12,8" cap="round"/>
  </Layer>
  <Layer>
    <Path data="M 50,300 Q 200,180 350,300"/>
    <Stroke width="10" cap="round">
      <LinearGradient startPoint="0,0" endPoint="300,0">
        <ColorStop offset="0" color="#F43F5E"/>
        <ColorStop offset="0.5" color="#EC4899"/>
        <ColorStop offset="1" color="#8B5CF6"/>
      </LinearGradient>
    </Stroke>
  </Layer>
</pagx>

LineCap:

LineJoin:

StrokeAlign:

Inside/outside stroke is achieved by:

1. Stroking at double width
2. Boolean operation with original shape (intersection for inside, difference for outside)

Dash Pattern:

• dashes: Defines dash segment length sequence, e.g., "5,3" means 5px solid + 3px gap
• dashOffset: Dash start offset
• dashAdaptive: When true, scales the dash intervals so that the dash segments have the same length

5.3.3 LayerPlacement

The placement attribute of Fill and Stroke controls rendering order relative to child layers:

5.4 Shape Modifiers

Shape modifiers perform in-place transformation on accumulated Paths; for glyph lists, they trigger forced conversion to Paths.

5.4.1 TrimPath

Trims paths to a specified start/end range.

<TrimPath start="0" end="0.5" offset="0" type="separate"/>

TrimType:

Edge Cases:

• start > end: The start and end values are mirrored (start = 1 - start, end = 1 - end) and all path directions are reversed, then normal trimming is applied. The resulting visual is the complementary segment of the path with reversed direction
• Supports wrapping: When trim range exceeds [0,1], automatically wraps to other end of path
• When total path length is 0, no operation is performed

<?xml version="1.0" encoding="UTF-8"?>
<!-- Demonstrates TrimPath: separate vs continuous mode comparison -->
<pagx version="1.0" width="400" height="400">
  <!-- === Top row: Separate mode === -->
  <Layer>
    <Ellipse position="120,95" size="100,100"/>
    <Ellipse position="280,95" size="100,100"/>
    <Stroke color="#E2E8F0" width="8"/>
  </Layer>
  <!-- Trimmed: each ellipse trimmed independently to 0.2~0.9 -->
  <Layer>
    <Ellipse position="120,95" size="100,100"/>
    <Ellipse position="280,95" size="100,100"/>
    <TrimPath start="0.2" end="0.9"/>
    <Stroke width="10" cap="round">
      <LinearGradient startPoint="70,40" endPoint="330,150">
        <ColorStop offset="0" color="#06B6D4"/>
        <ColorStop offset="1" color="#8B5CF6"/>
      </LinearGradient>
    </Stroke>
  </Layer>
  <Layer>
    <Text text="Separate (0.2–0.9)" fontFamily="Arial" fontStyle="Bold" fontSize="18" position="200,187" textAnchor="center"/>
    <Fill color="#475569"/>
  </Layer>

  <!-- === Bottom row: Continuous mode === -->
  <Layer>
    <Ellipse position="120,265" size="100,100"/>
    <Ellipse position="280,265" size="100,100"/>
    <Stroke color="#E2E8F0" width="8"/>
  </Layer>
  <!-- Trimmed: both ellipses treated as one path, 0.2~0.9 of total length -->
  <Layer>
    <Ellipse position="120,265" size="100,100"/>
    <Ellipse position="280,265" size="100,100"/>
    <TrimPath start="0.2" end="0.9" type="continuous"/>
    <Stroke width="10" cap="round">
      <LinearGradient startPoint="70,210" endPoint="330,320">
        <ColorStop offset="0" color="#F59E0B"/>
        <ColorStop offset="1" color="#F43F5E"/>
      </LinearGradient>
    </Stroke>
  </Layer>
  <Layer>
    <Text text="Continuous (0.2–0.9)" fontFamily="Arial" fontStyle="Bold" fontSize="18" position="200,357" textAnchor="center"/>
    <Fill color="#475569"/>
  </Layer>
</pagx>

5.4.2 RoundCorner

Converts sharp corners of paths to rounded corners.

<RoundCorner radius="10"/>

Processing Rules:

• Only affects sharp corners (non-smooth connected vertices)
• Corner radius is automatically limited to not exceed half the length of adjacent edges
• radius <= 0 performs no operation

Example:

<?xml version="1.0" encoding="UTF-8"?>
<pagx version="1.0" width="400" height="400">
  <!-- Original sharp rectangle (reference) -->
  <Layer>
    <Rectangle position="120,120" size="140,140"/>
    <Stroke color="#94A3B840" width="2" dashes="4,4"/>
  </Layer>
  <Layer>
    <Rectangle position="120,120" size="140,140"/>
    <RoundCorner radius="30"/>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="140,140">
        <ColorStop offset="0" color="#10B981"/>
        <ColorStop offset="1" color="#059669"/>
      </LinearGradient>
    </Fill>
    <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#10B98160"/>
  </Layer>
  <!-- Original star (reference) -->
  <Layer>
    <Polystar position="290,120" type="star" pointCount="5" outerRadius="70" innerRadius="32" rotation="-90"/>
    <Stroke color="#94A3B840" width="2" dashes="4,4"/>
  </Layer>
  <Layer>
    <Polystar position="290,120" type="star" pointCount="5" outerRadius="70" innerRadius="32" rotation="-90"/>
    <RoundCorner radius="12"/>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="140,140">
        <ColorStop offset="0" color="#F59E0B"/>
        <ColorStop offset="1" color="#D97706"/>
      </LinearGradient>
    </Fill>
    <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#F59E0B60"/>
  </Layer>
  <Layer>
    <Polystar position="200,300" type="polygon" pointCount="6" outerRadius="80"/>
    <RoundCorner radius="20"/>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="160,160">
        <ColorStop offset="0" color="#8B5CF6"/>
        <ColorStop offset="1" color="#7C3AED"/>
      </LinearGradient>
    </Fill>
    <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#8B5CF660"/>
  </Layer>
</pagx>

5.4.3 MergePath

Merges all shapes into a single shape.

<MergePath mode="append"/>

MergePathMode:

Important Behavior:

• MergePath clears all previously accumulated Fill and Stroke effects in the current scope; only the merged path remains in the geometry list
• Current transformation matrices of shapes are applied during merge
• Merged shape's transformation matrix resets to identity matrix

Example:

<?xml version="1.0" encoding="UTF-8"?>
<pagx version="1.0" width="400" height="400">
  <Layer>
    <Rectangle position="150,150" size="180,180" roundness="24"/>
    <Ellipse position="250,250" size="180,180"/>
    <MergePath mode="union"/>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="280,280">
        <ColorStop offset="0" color="#6366F1"/>
        <ColorStop offset="0.5" color="#8B5CF6"/>
        <ColorStop offset="1" color="#EC4899"/>
      </LinearGradient>
    </Fill>
    <DropShadowStyle offsetY="12" blurX="40" blurY="40" color="#8B5CF660"/>
  </Layer>
</pagx>

5.5 Text Modifiers

Text modifiers transform individual glyphs within text.

5.5.1 Text Modifier Processing

When a text modifier is encountered, all glyph lists accumulated in the context are combined into a unified glyph list for the operation:

<Group>
  <Text text="Hello " fontFamily="Arial" fontSize="24"/>
  <Text text="World" fontFamily="Arial" fontSize="24"/>
  <TextModifier position="0,-5"/>
  <TextBox position="100,50" textAlign="center"/>
  <Fill color="#333333"/>
</Group>

5.5.2 Text to Shape Conversion

When text encounters a shape modifier, it is forcibly converted to shape paths:

Text Element           Shape Modifier          Subsequent Modifiers
┌──────────┐          ┌──────────┐
│   Text   │          │ TrimPath │
└────┬─────┘          │RoundCorn │
     │                │MergePath │
     │ Accumulated    └────┬─────┘
     │ Glyph List          │
     ▼                     │ Triggers Conversion
┌──────────────┐           │
│ Glyph List   │───────────┼──────────────────────┐
│ [H,e,l,l,o]  │           │                      │
└──────────────┘           ▼                      ▼
                  ┌──────────────┐      ┌──────────────────┐
                  │ Merged into  │      │ Emoji Discarded  │
                  │ Single Path  │      │ (Cannot convert) │
                  └──────────────┘      └──────────────────┘
                           │
                           │ Subsequent text modifiers no longer effective
                           ▼
                  ┌──────────────┐
                  │ TextModifier │ → Skipped (Already Path)
                  └──────────────┘

Conversion Rules:

1. Trigger Condition: Conversion triggered when text encounters TrimPath, RoundCorner, or MergePath
2. Merge into Single Path: All glyphs of one Text merge into one Path, not one independent Path per glyph
3. Emoji Loss: Emoji cannot be converted to path outlines; discarded during conversion
4. Irreversible Conversion: After conversion becomes pure Path; subsequent text modifiers have no effect on it

Example:

<Group>
  <Text fontFamily="Arial" fontSize="24"><![CDATA[Hello 😀]]></Text>
  <TrimPath start="0" end="0.5"/>
  <TextModifier position="0,-10"/>
  <Fill color="#333333"/>
</Group>

5.5.3 TextModifier

Applies transforms and style overrides to glyphs within selected ranges. TextModifier may contain multiple RangeSelector child elements.

<TextModifier anchor="0,0" position="0,0" rotation="0" scale="1,1" skew="0" skewAxis="0" alpha="1" fillColor="#FF0000" strokeColor="#000000" strokeWidth="1">
  <RangeSelector start="0" end="0.5" shape="rampUp"/>
  <RangeSelector start="0.5" end="1" shape="rampDown"/>
</TextModifier>

Selector Calculation:

1. Calculate selection range based on RangeSelector's start, end, offset (supports any decimal value; automatically wraps when exceeding [0,1] range)
2. Calculate raw influence value (0~1) for each glyph based on shape, then multiply by weight
3. Combine multiple selectors according to mode, then clamp the combined result to [-1, 1]

factor = clamp(combine(rawInfluence₁ × weight₁, rawInfluence₂ × weight₂, ...), -1, 1)

Transform Application:

Position and rotation are applied linearly with factor. Transforms are applied in the following order:

1. Translate to negative anchor (translate(-anchor × factor))
2. Scale from identity (scale(1 + (scale - 1) × factor))
3. Skew (skew(skew × factor, skewAxis))
4. Rotate (rotate(rotation × factor))
5. Translate back to anchor (translate(anchor × factor))
6. Translate to position (translate(position × factor))

Opacity uses the absolute value of factor:

alphaFactor = 1 + (alpha - 1) × |factor|
finalAlpha = originalAlpha × max(0, alphaFactor)

Color Override:

Color override uses the absolute value of factor for alpha blending:

blendFactor = overrideColor.alpha × |factor|
finalColor = blend(originalColor, overrideColor, blendFactor)

Example:

<?xml version="1.0" encoding="UTF-8"?>
<pagx version="1.0" width="400" height="400">
  <!-- Wave effect: triangle selector shifts characters vertically -->
  <Layer>
    <Text text="WAVE" fontFamily="Arial" fontStyle="Bold" fontSize="72" position="200,120" textAnchor="center"/>
    <TextModifier position="0,-30">
      <RangeSelector start="0" end="1" shape="triangle"/>
    </TextModifier>
    <Fill>
      <LinearGradient startPoint="-200,0" endPoint="80,0">
        <ColorStop offset="0" color="#06B6D4"/>
        <ColorStop offset="1" color="#3B82F6"/>
      </LinearGradient>
    </Fill>
  </Layer>
  <!-- Rotation effect: each character rotated with rampUp selector -->
  <Layer>
    <Text text="ROTATE" fontFamily="Arial" fontStyle="Bold" fontSize="56" position="200,240" textAnchor="center"/>
    <TextModifier rotation="30">
      <RangeSelector start="0" end="1" shape="rampUp"/>
    </TextModifier>
    <Fill>
      <LinearGradient startPoint="-200,0" endPoint="80,0">
        <ColorStop offset="0" color="#F59E0B"/>
        <ColorStop offset="1" color="#F43F5E"/>
      </LinearGradient>
    </Fill>
  </Layer>
  <!-- Color override effect: characters with gradient color override -->
  <Layer>
    <Text text="COLOR" fontFamily="Arial" fontStyle="Bold" fontSize="64" position="200,350" textAnchor="center"/>
    <TextModifier fillColor="#EC4899">
      <RangeSelector start="0" end="1" shape="triangle"/>
    </TextModifier>
    <Fill color="#8B5CF6"/>
  </Layer>
</pagx>

5.5.4 RangeSelector

Range selectors define the glyph range and influence degree for TextModifier.

<RangeSelector start="0" end="1" offset="0" unit="percentage" shape="square" easeIn="0" easeOut="0" mode="add" weight="1" randomOrder="false" randomSeed="0"/>

SelectorUnit:

SelectorShape:

SelectorMode:

5.5.5 TextPath

Arranges text along a specified path. The path can reference a PathData defined in Resources, or use inline path data. TextPath uses a baseline (a straight line defined by baselineOrigin and baselineAngle) as the text's reference line: glyphs are mapped from their positions along this baseline onto corresponding positions on the path curve, preserving their relative spacing and offsets. When forceAlignment is enabled, original glyph positions are ignored and glyphs are redistributed evenly to fill the available path length.

<?xml version="1.0" encoding="UTF-8"?>
<pagx version="1.0" width="400" height="400">
  <Layer>
    <Text text="PAGX" fontFamily="Arial" fontStyle="Bold" fontSize="56"/>
    <TextPath path="M 60,230 Q 200,30 340,230" forceAlignment="true"/>
    <Fill>
      <LinearGradient startPoint="0,0" endPoint="300,0">
        <ColorStop offset="0" color="#06B6D4"/>
        <ColorStop offset="0.5" color="#8B5CF6"/>
        <ColorStop offset="1" color="#EC4899"/>
      </LinearGradient>
    </Fill>
  </Layer>
  <!-- Guide path (dashed) to visualize the curve -->
  <Layer>
    <Path data="M 60,230 Q 200,30 340,230"/>
    <Stroke color="#64748B" width="1" dashes="6,4"/>
  </Layer>
  <Layer>
    <Text text="TextPath" fontFamily="Arial" fontStyle="Bold" fontSize="28"/>
    <TextPath path="M 80,320 Q 200,250 320,320" forceAlignment="true"/>
    <Fill color="#475569"/>
  </Layer>
</pagx>

Baseline:

• baselineOrigin: The starting point of the baseline in the TextPath's local coordinate space
• baselineAngle: The angle of the baseline in degrees. 0 means a horizontal baseline (text flows left to right along X axis), 90 means a vertical baseline (text flows top to bottom along Y axis)
• Each glyph's distance along the baseline determines where it lands on the curve, and its perpendicular offset from the baseline is preserved as a perpendicular offset from the curve

Margins:

• firstMargin: Start margin (offset inward from path start)
• lastMargin: End margin (offset inward from path end)

Force Alignment:

• When forceAlignment="true", glyphs are laid out consecutively using their advance widths, then spacing is adjusted proportionally to fill the path region between firstMargin and lastMargin

Glyph Positioning:

1. Calculate glyph center position on path
2. Get path tangent direction at that position
3. If perpendicular="true", rotate glyph perpendicular to path

Closed Paths: For closed paths, glyphs exceeding the range wrap to the other end of the path.

5.5.6 TextBox

TextBox is a text layout node that applies typography to accumulated Text elements. It re-layouts all glyph positions according to its own position, size, and alignment settings. The layout results are written into each Text element's GlyphRun data with inverse-transform compensation, so that Text's own position and parent Group transforms remain effective in the rendering pipeline. The first line is positioned using the line-box model: the line box near edge is aligned to the near edge of the text area, and the baseline is placed at halfLeading + ascent from the near edge, where halfLeading = (lineHeight - metricsHeight) / 2 and metricsHeight = ascent + descent + leading from the font metrics. Following CSS Writing Modes conventions, lineHeight is a logical property that always applies to the block-axis dimension of a line box. In vertical mode, it controls the column width rather than the line height. Columns are spaced by lineHeight (center-to-center distance). When lineHeight is 0 (auto), the column width is calculated from font metrics (ascent + descent + leading), same as horizontal auto line height. Columns flow from right to left.

TextBox is a pre-layout-only node: it is processed during the typesetting stage before rendering and is not instantiated in the render tree. If all accumulated Text elements already contain embedded GlyphRun data, the TextBox is skipped during typesetting. However, the TextBox node should still be retained even when embedded GlyphRun data and fonts are present, as design tools may read its layout attributes (size, alignment, wordWrap, etc.) for editing purposes.

Unlike other modifiers that operate on accumulated results in a chain (e.g., TrimPath modifies the path output of previous elements), TextBox only affects the initial layout of Text elements. It determines glyph positions before the modifier chain begins. Subsequent modifiers such as TextPath and TextModifier operate on the TextBox layout results. The position of TextBox in the node order does not change this behavior.

<?xml version="1.0" encoding="UTF-8"?>
<!-- Demonstrates TextBox: word wrap, text alignment, vertical writing, paragraph alignment -->
<pagx version="1.0" width="400" height="400">
  <!-- Box 1 (top-left): horizontal justify + lineHeight -->
  <Layer>
    <Rectangle position="104,104" size="180,180" roundness="6"/>
    <Stroke color="#CBD5E1" width="1" dashes="4,3"/>
  </Layer>
  <Layer>
    <Group>
      <Text text="Justify aligns words evenly 分布在 each full line." fontFamily="Arial" fontSize="18"/>
      <Fill>
        <LinearGradient startPoint="0,0" endPoint="180,0">
          <ColorStop offset="0" color="#6366F1"/>
          <ColorStop offset="1" color="#8B5CF6"/>
        </LinearGradient>
      </Fill>
    </Group>
    <TextBox position="14,14" size="180,180" lineHeight="28" textAlign="justify"/>
    <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#6366F130"/>
  </Layer>

  <!-- Box 2 (top-right): horizontal textAlign center + paragraphAlign middle -->
  <Layer>
    <Rectangle position="296,104" size="180,180" roundness="6"/>
    <Stroke color="#CBD5E1" width="1" dashes="4,3"/>
  </Layer>
  <Layer>
    <Group>
      <Text text="Centered&#10;Horizontally&#10;&amp;&#10;Vertically" fontFamily="Arial" fontStyle="Bold" fontSize="18"/>
      <Fill>
        <LinearGradient startPoint="0,0" endPoint="180,100">
          <ColorStop offset="0" color="#F43F5E"/>
          <ColorStop offset="1" color="#EC4899"/>
        </LinearGradient>
      </Fill>
    </Group>
    <TextBox position="206,14" size="180,180" textAlign="center" paragraphAlign="middle"/>
    <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#F43F5E30"/>
  </Layer>

  <!-- Box 3 (bottom-left): vertical writing -->
  <Layer>
    <Rectangle position="104,296" size="180,180" roundness="6"/>
    <Stroke color="#CBD5E1" width="1" dashes="4,3"/>
  </Layer>
  <Layer>
    <Group>
      <Text text="春眠不觉 Dawn 处处闻啼鸟 Night 来风雨声花落知多少" fontFamily="Arial" fontStyle="Bold" fontSize="18"/>
      <Fill>
        <LinearGradient startPoint="180,0" endPoint="0,180">
          <ColorStop offset="0" color="#F59E0B"/>
          <ColorStop offset="1" color="#F43F5E"/>
        </LinearGradient>
      </Fill>
    </Group>
    <TextBox position="14,206" size="180,180" writingMode="vertical" textAlign="justify"/>
    <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#F59E0B30"/>
  </Layer>

  <!-- Box 4 (bottom-right): vertical textAlign center + paragraphAlign middle -->
  <Layer>
    <Rectangle position="296,296" size="180,180" roundness="6"/>
    <Stroke color="#CBD5E1" width="1" dashes="4,3"/>
  </Layer>
  <Layer>
    <Group>
      <Text text="竖排文本&#10;居中对齐" fontFamily="Arial" fontStyle="Bold" fontSize="18"/>
      <Fill>
        <LinearGradient startPoint="0,0" endPoint="180,180">
          <ColorStop offset="0" color="#06B6D4"/>
          <ColorStop offset="1" color="#10B981"/>
        </LinearGradient>
      </Fill>
    </Group>
    <TextBox position="206,206" size="180,180" writingMode="vertical" textAlign="center" paragraphAlign="middle"/>
    <DropShadowStyle offsetY="8" blurX="24" blurY="24" color="#06B6D430"/>
  </Layer>
</pagx>

TextAlign (Text Alignment):

ParagraphAlign (Paragraph Alignment):

Aligns text lines or columns along the block-flow direction. Uses direction-neutral names (Near/Far instead of Top/Bottom) that work correctly for both horizontal and vertical writing modes. In horizontal mode this controls vertical positioning; in vertical mode this controls horizontal positioning.

WritingMode (Layout Direction):

Overflow (Overflow Behavior):

5.5.7 Rich Text

Rich text is achieved through multiple Text elements within a Group, each Text having independent Fill/Stroke styles. TextBox provides unified typography.

<?xml version="1.0" encoding="UTF-8"?>
<!-- Demonstrates rich text with mixed styles -->
<pagx version="1.0" width="400" height="400">
  <Layer>
    <Text text="Rich Text" fontFamily="Arial" fontStyle="Bold" fontSize="42" position="200,105" textAnchor="center"/>
    <Fill>
      <LinearGradient startPoint="-200,0" endPoint="0,0">
        <ColorStop offset="0" color="#8B5CF6"/>
        <ColorStop offset="1" color="#EC4899"/>
      </LinearGradient>
    </Fill>
  </Layer>

  <!-- Rich text: multiple Groups with different styles in one TextBox -->
  <Layer>
    <Group>
      <Text text="Supports " fontFamily="Arial" fontSize="20"/>
      <Fill color="#475569"/>
    </Group>
    <Group>
      <Text text="bold" fontFamily="Arial" fontStyle="Bold" fontSize="20"/>
      <Fill color="#F43F5E"/>
    </Group>
    <Group>
      <Text text=", " fontFamily="Arial" fontSize="20"/>
      <Fill color="#475569"/>
    </Group>
    <Group>
      <Text text="italic" fontFamily="Arial" fontStyle="Italic" fontSize="20"/>
      <Fill color="#10B981"/>
    </Group>
    <Group>
      <Text text=" and " fontFamily="Arial" fontSize="20"/>
      <Fill color="#475569"/>
    </Group>
    <Group>
      <Text text="colored" fontFamily="Arial" fontStyle="Bold" fontSize="20"/>
      <Fill color="#06B6D4"/>
    </Group>
    <Group>
      <Text text=" text.&#10;" fontFamily="Arial" fontSize="20"/>
      <Fill color="#475569"/>
    </Group>
    <Group>
      <Text text="Mix " fontFamily="Arial" fontSize="16"/>
      <Fill color="#475569"/>
    </Group>
    <Group>
      <Text text="different" fontFamily="Arial" fontStyle="Bold" fontSize="24"/>
      <Fill color="#F59E0B"/>
    </Group>
    <Group>
      <Text text=" sizes " fontFamily="Arial" fontSize="16"/>
      <Fill color="#475569"/>
    </Group>
    <Group>
      <Text text="freely" fontFamily="Arial" fontStyle="Bold Italic" fontSize="24"/>
      <Fill color="#8B5CF6"/>
    </Group>
    <Group>
      <Text text=" within one line.&#10;" fontFamily="Arial" fontSize="16"/>
      <Fill color="#475569"/>
    </Group>
    <Group>
      <Text text="Center " fontFamily="Arial" fontSize="20"/>
      <Fill color="#475569"/>
    </Group>
    <Group>
      <Text text="aligned" fontFamily="Arial" fontStyle="Bold" fontSize="20"/>
      <Fill color="#EC4899"/>
    </Group>
    <Group>
      <Text text=" rich text." fontFamily="Arial" fontSize="20"/>
      <Fill color="#475569"/>
    </Group>
    <TextBox position="0,142" size="400,0" lineHeight="48" textAlign="center"/>
  </Layer>

  <Layer>
    <Text text="Gradient Fill" fontFamily="Arial" fontStyle="Bold" fontSize="28" position="200,310" textAnchor="center"/>
    <Fill>
      <LinearGradient startPoint="-100,0" endPoint="100,0">
        <ColorStop offset="0" color="#F43F5E"/>
        <ColorStop offset="0.5" color="#F59E0B"/>
        <ColorStop offset="1" color="#10B981"/>
      </LinearGradient>
    </Fill>
  </Layer>
</pagx>

Note: Each Group's Text + Fill/Stroke defines a text segment with independent styling. TextBox treats all segments as a single unit for typography, enabling auto-wrapping and alignment.

5.6 Repeater

Repeater duplicates accumulated content and rendered styles, applying progressive transforms to each copy. Repeater affects both Paths and glyph lists simultaneously, and does not trigger text-to-shape conversion.

<Repeater copies="5" offset="1" order="belowOriginal" anchor="0,0" position="50,0" rotation="0" scale="1,1" startAlpha="1" endAlpha="0.2"/>

Transform Calculation (i-th copy, i starts from 0):

progress = i + offset

Transforms are applied in the following order:

1. Translate to negative anchor (translate(-anchor))
2. Scale exponentially (scale(scale^progress))
3. Rotate linearly (rotate(rotation × progress))
4. Translate linearly (translate(position × progress))
5. Translate back to anchor (translate(anchor))

Opacity Interpolation:

maxCount = ceil(copies)
t = progress / maxCount
alpha = lerp(startAlpha, endAlpha, t)
// For the last copy, alpha is further multiplied by the fractional part of copies (see below)

RepeaterOrder: