llms-full.txt

# FlexRender -- Full Reference

> A modular .NET library for rendering images from YAML templates with flexbox layout. Render-backend agnostic with SkiaSharp as the default backend. Fully AOT-compatible with no reflection.

## Project Structure

```
src/FlexRender.Core/            # Core library (0 external dependencies)
  Abstractions/                 # ILayoutRenderer<T>, ITemplateParser, IResourceLoader
  Configuration/                # FlexRenderBuilder, FlexRenderOptions, ResourceLimits
  Layout/                       # Two-pass flexbox layout engine (LayoutEngine, LayoutNode, LayoutSize)
    Units/                      # Unit, UnitParser, PaddingValues, PaddingParser
    FlexEnums.cs                # FlexDirection, FlexWrap, JustifyContent, AlignItems, AlignContent, AlignSelf, TextDirection
    FontSizeResolver.cs         # Resolve fontSize string to pixels
    LayoutEngine.cs             # Main layout calculator
    LayoutNode.cs               # Computed layout tree node
    LayoutContext.cs            # Layout computation context
    LayoutSize.cs               # Width/Height measurement result
    IntrinsicSize.cs            # Min/Max width/height measurements
    LineHeightResolver.cs       # Resolve lineHeight string to pixels
  Loaders/                      # FileResourceLoader, Base64ResourceLoader, EmbeddedResourceLoader
  Parsing/
    Ast/                        # AST models: Template, CanvasSettings, TemplateElement, TextElement, FlexElement, QrElement, BarcodeElement, ImageElement, SvgElement, SeparatorElement, TableElement, TableColumn, TableRow
  TemplateEngine/               # TemplateProcessor, ExpressionLexer, ExpressionEvaluator, TemplateContext, InlineExpressionParser, InlineExpressionEvaluator, FilterRegistry, ITemplateFilter
    Filters/                    # Built-in filters: CurrencyFilter, CurrencySymbolFilter, NumberFilter, UpperFilter, LowerFilter, TrimFilter, TruncateFilter, FormatFilter
  Values/                       # TemplateValue (abstract), StringValue, NumberValue, BoolValue, NullValue, ArrayValue, ObjectValue

src/FlexRender.Yaml/            # YAML template parser (-> Core + YamlDotNet)
  Parsing/
    TemplateParser.cs           # YAML to AST parser (includes EachElement, IfElement)
    KnownProperties.cs          # YAML property validation with Levenshtein "Did you mean?" suggestions

src/FlexRender.Xml/             # XML template parser, alternative to YAML (same Template AST)
  Parsing/
    XmlTemplateParser.cs        # XML to AST parser; lowers XML tree to the shared element parsers, same KnownProperties validation + ResourceLimits

src/FlexRender.Http/            # HTTP resource loader (-> Core)
  HttpResourceLoader.cs         # Load images/fonts from HTTP/HTTPS URLs
  FlexRenderBuilderExtensions.cs # WithHttpLoader() extension

src/FlexRender.Skia.Render/     # SkiaSharp renderer (-> Core + SkiaSharp)
  Abstractions/                 # ISkiaRenderer, IFontLoader, IImageLoader, IFontManager
  Rendering/                    # SkiaRenderer, TextRenderer, FontManager, ColorParser, RotationHelper, BmpEncoder, BoxShadowParser, GradientParser
  Loaders/                      # FontLoader, ImageLoader
  Providers/                    # IContentProvider<T,O>, ImageProvider
src/FlexRender.Skia/            # Skia backend meta-package (renderer + providers)

src/FlexRender.QrCode.Skia.Render/     # QR provider for Skia (-> Skia + QRCoder)
  Providers/                    # QrProvider (implements IContentProvider<QrElement, SKBitmap>)
src/FlexRender.QrCode.Svg.Render/      # QR provider for SVG (-> Svg)
  Providers/                    # QrSvgProvider (implements ISvgContentProvider<QrElement>)
src/FlexRender.QrCode.ImageSharp.Render/ # QR provider for ImageSharp (-> ImageSharp + QRCoder)
  Providers/                    # QrImageSharpProvider (implements IImageSharpContentProvider<QrElement>)
src/FlexRender.QrCode/          # QR meta-package (references all renderers)

src/FlexRender.Barcode.Skia.Render/    # Barcode provider for Skia
  Providers/                    # BarcodeProvider (implements IContentProvider<BarcodeElement, SKBitmap>)
src/FlexRender.Barcode.Svg.Render/     # Barcode provider for SVG
  Providers/                    # BarcodeSvgProvider (implements ISvgContentProvider<BarcodeElement>)
src/FlexRender.Barcode.ImageSharp.Render/ # Barcode provider for ImageSharp
  Providers/                    # BarcodeImageSharpProvider (implements IImageSharpContentProvider<BarcodeElement>)
src/FlexRender.Barcode/         # Barcode meta-package (references all renderers)

src/FlexRender.HarfBuzz/        # HarfBuzz text shaping (-> Skia + SkiaSharp.HarfBuzz)
  HarfBuzzTextShaper.cs         # Shaped text measurement and drawing
  SkiaBuilderExtensions.cs      # .WithHarfBuzz() extension

src/FlexRender.ImageSharp.Render/ # ImageSharp renderer (-> Core + SixLabors.ImageSharp)
  Rendering/                    # ImageSharpRenderingEngine, ImageSharpTextRenderer, ImageSharpFontManager
  ImageSharpRender.cs           # IFlexRender implementation for ImageSharp
  ImageSharpBuilder.cs          # Builder for ImageSharp renderer configuration
src/FlexRender.ImageSharp/      # ImageSharp backend meta-package (renderer + providers)

src/FlexRender.SvgElement.Skia.Render/ # SvgElement provider for Skia (-> Svg.Skia)
  Providers/                    # SvgElementProvider (implements IContentProvider<SvgElement, SKBitmap>)
src/FlexRender.SvgElement.Svg.Render/  # SvgElement provider for SVG (native)
  Providers/                    # SvgElementSvgProvider (implements ISvgContentProvider<SvgElement>)
src/FlexRender.SvgElement/      # SvgElement meta-package (references all renderers)

src/FlexRender.Svg.Render/      # SVG output renderer (-> Core)
  SvgRender.cs                  # Renders templates to SVG format
  SvgBuilder.cs                 # Builder for SVG renderer configuration
src/FlexRender.Svg/             # SVG backend meta-package (renderer + providers)

src/FlexRender.Content.Markdown/  # Markdown content parser (-> Core + Markdig)
src/FlexRender.Content.Html/      # HTML content parser (-> Core + HtmlAgilityPack)
src/FlexRender.Content.Ndc/      # NDC (ATM receipt) content parser (-> Core)

src/FlexRender.DependencyInjection/  # Microsoft.Extensions.DI integration
  ServiceCollectionExtensions.cs     # AddFlexRender() extension method

src/FlexRender.MetaPackage/     # Meta-package (core + all backends + DI)

src/FlexRender.Cli/             # CLI tool (System.CommandLine)
  Commands/                     # render, validate, info, watch, debug-layout

tests/FlexRender.Tests/         # Unit + snapshot tests
tests/FlexRender.Cli.Tests/     # CLI integration tests
tests/FlexRender.ImageSharp.Tests/ # ImageSharp visual snapshot tests
examples/                       # Example YAML templates with data and output
```

## NuGet Package Structure

```
FlexRender.Core          (0 external deps)
  ^          ^        ^        ^
  |          |        |        |
FlexRender.Yaml  FlexRender.Http  FlexRender.Skia.Render  FlexRender.ImageSharp.Render  FlexRender.Svg.Render
                                    ^           ^                     ^                     ^
                                    |           |                     |                     |
                      Qr/Bar/SvgElement providers per renderer (Skia/Svg/ImageSharp)
                                    |           |                     |
                     FlexRender.QrCode / FlexRender.Barcode / FlexRender.SvgElement (meta)
                                    |           |
                     FlexRender.Skia / FlexRender.ImageSharp / FlexRender.Svg (backend meta)
                                    |
               FlexRender.DependencyInjection  (Microsoft.Extensions.DI)
                                    |
                           FlexRender.MetaPackage  (references all)
```

| Package | Depends On | External Deps |
|---------|-----------|---------------|
| FlexRender.Core | -- | (none) |
| FlexRender.Yaml | Core | YamlDotNet 16.3.0 |
| FlexRender.Http | Core | (none) |
| FlexRender.Skia.Render | Core | SkiaSharp 3.119.2 |
| FlexRender.Skia | Skia.Render + providers | SkiaSharp 3.119.2 |
| FlexRender.QrCode.Skia.Render | Skia.Render | QRCoder 1.7.0 |
| FlexRender.QrCode.Svg.Render | Svg.Render | QRCoder 1.7.0 |
| FlexRender.QrCode.ImageSharp.Render | ImageSharp.Render | QRCoder 1.7.0 |
| FlexRender.QrCode | All renderers | -- |
| FlexRender.Barcode.Skia.Render | Skia.Render | (none) |
| FlexRender.Barcode.Svg.Render | Svg.Render | (none) |
| FlexRender.Barcode.ImageSharp.Render | ImageSharp.Render | (none) |
| FlexRender.Barcode | All renderers | -- |
| FlexRender.HarfBuzz | Skia.Render | SkiaSharp.HarfBuzz 3.119.2, HarfBuzzSharp 8.3.1.3 |
| FlexRender.ImageSharp.Render | Core | SixLabors.ImageSharp, SixLabors.ImageSharp.Drawing, SixLabors.Fonts |
| FlexRender.ImageSharp | ImageSharp.Render + providers | SixLabors.ImageSharp, SixLabors.ImageSharp.Drawing, SixLabors.Fonts |
| FlexRender.DependencyInjection | Core | Microsoft.Extensions.DI |
| FlexRender.SvgElement.Skia.Render | Skia.Render | Svg.Skia |
| FlexRender.SvgElement.Svg.Render | Svg.Render | (none) |
| FlexRender.SvgElement | All renderers | -- |
| FlexRender.Svg.Render | Core | (none) |
| FlexRender.Svg | Svg.Render + providers | (none) |
| FlexRender.Content.Markdown | Core | Markdig 1.1.1 |
| FlexRender.Content.Html | Core | HtmlAgilityPack 1.12.4 |
| FlexRender.Content.Ndc | Core | (none) |
| FlexRender.MetaPackage | All | -- |
| flexrender-cli | All | System.CommandLine |

**Linux/Docker:** SkiaSharp requires native libraries on Linux. Add `SkiaSharp.NativeAssets.Linux` (or `SkiaSharp.NativeAssets.Linux.NoDependencies` for minimal containers without fontconfig/freetype) to your executable project to avoid `DllNotFoundException: libSkiaSharp` at runtime. When using `FlexRender.HarfBuzz`, also add `HarfBuzzSharp.NativeAssets.Linux` to avoid `DllNotFoundException: libHarfBuzzSharp`.

## Rendering Pipeline

```
YAML Template
  -> TemplateParser           (YAML -> AST: Template with CanvasSettings + TemplateElement tree, including EachElement/IfElement)
     + KnownProperties        (validate YAML keys, warn on unknown properties with "Did you mean?" suggestions)
  -> TemplateExpander         (expand EachElement/IfElement to concrete elements based on data) [async only]
  -> TemplateProcessor        (resolve {{variable}} expressions in element properties) [async only]
  -> LayoutEngine             (two-pass: MeasureAllIntrinsics -> ComputeLayout -> LayoutNode tree)
  -> SkiaRenderer             (traverse LayoutNode tree -> draw to SKBitmap via SkiaSharp)
     OR ImageSharpRenderer    (traverse LayoutNode tree -> draw via SixLabors.ImageSharp)
```

**Async-only API:** The entire pipeline from expansion through rendering is async. There are no synchronous `Expand()`, `Process()`, `Measure()`, `ComputeLayout()`, or `Render()` methods. All public API methods return `Task` or `Task<T>`. This is required because `ContentElement` expansion involves async I/O (loading external content sources).

### XML as an Alternative Input

Templates may be authored in **XML** (`FlexRender.Xml`) instead of YAML. The XML parser (`XmlTemplateParser`) produces the **same `Template` AST** as `TemplateParser` -- same element types, same properties, same `KnownProperties` validation (with "Did you mean?" suggestions), same `ResourceLimits`. XML is offered because LLMs often emit attributes more reliably than YAML indentation. Render with the `RenderXml` extension (mirrors `RenderYaml`):

```csharp
var render = new FlexRenderBuilder().WithSkia().Build();
byte[] png = await render.RenderXml(xml, data);

// Parse once, reuse:
var parser = new XmlTemplateParser();
byte[] png = await render.RenderXml(xml, data, parser: parser);
```

Mapping rules (XML -> same AST as YAML):

- Single root `<flexrender>`; `<canvas width="300" .../>` child for canvas; `template`/`fonts` via attributes/`<fonts>`; every other child of the root is a layout element.
- Element type = XML local-name: `<text/>`, `<flex>`, `<chart/>`, `<rect/>`, `<each>`, `<if>`, `<table>`, `<draw>`.
- Scalar properties = attributes (`<text size="1em" color="#f00"/>`); names identical to YAML (kebab-case and camelCase pass through).
- `<text>Hello</text>` is equivalent to `<text content="Hello"/>` (content attribute wins if both present; svg `content` follows the same rule).
- Layout containers: `flex`/`each` children are nested elements directly (`children`). Wrappers: `if` -> `<then>`/`<else>`/`<else-if>`; `table` -> `<columns>`/`<rows>`; `chart` -> `<series .../>`, `<categories>`, `<x-labels>`/`<y-labels>`, `<palette>`; `draw` -> `<shapes>`.
- List attributes: `data="12,30,22,48"` -> number array; scatter/bubble `points="1,2; 3,4"` -> tuples; `palette="#f00,#0f0"` -> color list (or `palette="ocean"` named).

Minimal example:

```xml
<flexrender>
  <canvas width="300"/>
  <text content="Hello" size="1.5em"/>
</flexrender>
```

See `docs/wiki/Xml-Syntax.md` for the full XML<->YAML mapping and a side-by-side flex+chart example.

### Template Caching

Templates can be parsed once and cached, then rendered with different data:

```csharp
// Parse once (at startup)
var parser = new TemplateParser();
var template = parser.Parse(yaml);
templateCache["receipt"] = template;

// Render many times (per request)
var template = templateCache["receipt"];
var bytes = await render.Render(template, data);  // Expander called internally
```

### Two-Pass Layout Engine

1. **Pass 1 -- Intrinsic Measurement** (`MeasureAllIntrinsics`): Bottom-up traversal computes `IntrinsicSize` (MinWidth, MaxWidth, MinHeight, MaxHeight) for every element. Uses `TextMeasurer` delegate for content-based text sizing.
2. **Pass 2 -- Layout** (`ComputeLayout`): Top-down traversal assigns positions and sizes, producing a `LayoutNode` tree with (X, Y, Width, Height).

`IntrinsicSize` is a `readonly record struct` with `WithPadding(float)`, `WithPadding(PaddingValues)`, and `WithMargin(float)` helper methods.

## Template YAML Structure

```yaml
template:                     # Required: template metadata
  name: "my-template"         # Template name (string)
  version: 1                  # Template version (int)
  # culture: "ru-RU"          # Optional: culture for number/date formatting

fonts:                                        # Optional: list format (recommended) or dictionary format
  - "assets/fonts/Inter-Regular.ttf"          # First unnamed = default/main
  - "assets/fonts/Inter-Bold.ttf"             # File path, embedded://, or http://

canvas:                       # Required: canvas configuration
  fixed: width                # Which dimension is fixed (width|height|both|none)
  width: 300                  # Canvas width in pixels (default: 300)
  height: 0                   # Canvas height in pixels (0 = auto when not fixed)
  background: "#ffffff"       # Background color (default: "#ffffff")
  rotate: "none"              # Canvas rotation (see below)

layout:                       # Required: array of elements
  - type: text                # Element type
    # ... element properties
```

## Canvas Settings

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| fixed | FixedDimension | width | Which dimension is fixed: `width`, `height`, `both`, `none` |
| width | int | 300 | Canvas width in pixels |
| height | int | 0 | Canvas height in pixels (0 = auto when unfixed) |
| background | string | "#ffffff" | Background color in hex format |
| rotate | string | "none" | Post-render rotation |
| text-direction | TextDirection | Ltr | Text direction: `ltr` (default), `rtl`. Alias: `dir` |

### Canvas Rotation Values

| Value | Effect |
|-------|--------|
| `"none"` | No rotation |
| `"left"` | 270 degrees (90 CCW) -- swaps width/height |
| `"right"` | 90 degrees CW -- swaps width/height |
| `"flip"` | 180 degrees |
| `"<number>"` | Arbitrary degrees (e.g., `"45"`) |

Rotation is applied AFTER rendering. For thermal printers: use `"right"` to rotate a wide receipt into a tall image. All element sizes are specified for the PRE-rotation layout.

## Common Element Properties

All elements inherit from `TemplateElement`:

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| padding | string | "0" | Inner spacing (px, %, em). Supports non-uniform CSS shorthand |
| margin | string | "0" | Outer spacing (px, %, em). Supports non-uniform CSS shorthand and `auto` |
| background | string? | null | Background color in hex, or CSS gradient (null = transparent) |
| opacity | float | 1.0 | Element opacity (0.0-1.0). Applied via SaveLayer, affects element and all children |
| box-shadow | string? | null | Box shadow: `"offsetX offsetY blurRadius color"` (e.g., `"4 4 8 #00000040"`) |
| rotate | string | "none" | Element rotation (none/left/right/flip/degrees). Rendered for: text, image, qr, barcode. Rotation is around the element's center point |
| position | Position | Static | Positioning mode: `static`, `relative`, `absolute` |
| top | string? | null | Top inset for positioned elements (px, %, em) |
| right | string? | null | Right inset for positioned elements (px, %, em) |
| bottom | string? | null | Bottom inset for positioned elements (px, %, em) |
| left | string? | null | Left inset for positioned elements (px, %, em) |
| aspectRatio | float? | null | Width/height ratio. When one dimension is known, the other is computed |
| minWidth | string? | null | Minimum width constraint (px, %, em) |
| maxWidth | string? | null | Maximum width constraint (px, %, em) |
| minHeight | string? | null | Minimum height constraint (px, %, em) |
| maxHeight | string? | null | Maximum height constraint (px, %, em) |
| display | Display | Flex | Display mode: `flex` (default), `none` (removes from layout flow) |
| text-direction | TextDirection? | null | Text direction override: `ltr`, `rtl` (null = inherit from parent/canvas). Alias: `dir` |
| border | string? | null | Border shorthand for all sides: `"width style color"` (e.g., `"2 solid #333"`) |
| borderTop | string? | null | Per-side border shorthand for top: `"width style color"` |
| borderRight | string? | null | Per-side border shorthand for right side |
| borderBottom | string? | null | Per-side border shorthand for bottom side |
| borderLeft | string? | null | Per-side border shorthand for left side |
| borderWidth | string? | null | Border width override for all sides (px, em) |
| borderColor | string? | null | Border color override for all sides |
| borderStyle | string? | null | Border style override: `solid`, `dashed`, `dotted`, `none` |
| borderRadius | string? | null | Corner rounding radius (px, em, %) |

## Non-Uniform Padding and Margin

Both `padding` and `margin` accept CSS-like shorthand with 1 to 4 space-separated values:

| Format | Meaning |
|--------|---------|
| `"20"` | All sides = 20 |
| `"20 40"` | Top/Bottom = 20, Left/Right = 40 |
| `"20 40 30"` | Top = 20, Left/Right = 40, Bottom = 30 |
| `"20 40 30 10"` | Top = 20, Right = 40, Bottom = 30, Left = 10 |

Each value can include a unit suffix: `"10px 5% 2em 20"`. Parsed by `PaddingParser` into `PaddingValues` (a `readonly record struct` with Top, Right, Bottom, Left, Horizontal, Vertical).

During intrinsic measurement (Pass 1), percentage values resolve against 0 and em values against 16px default. During layout (Pass 2), percentage resolves against parent size and em against element font size.

## Positioning

Elements support CSS-like positioning via the `position` property:

| Value | Behavior |
|-------|----------|
| `static` | Normal flow (default). Inset properties are ignored |
| `relative` | Offset from its normal flow position. Still occupies space in the flow |
| `absolute` | Removed from normal flow. Positioned relative to nearest flex container |

Inset properties (`top`, `right`, `bottom`, `left`) accept px, %, or em values.

```yaml
# Badge overlay in top-right corner
- type: flex
  width: 300
  height: 200
  children:
    - type: text
      content: "Background content"
    - type: text
      content: "Badge"
      position: absolute
      top: 5
      right: 5
      background: "#ff0000"
      color: "#ffffff"
      padding: "2 8"
```

## Aspect Ratio

The `aspectRatio` property enforces a width-to-height ratio. When one dimension is specified, the other is computed automatically:

```yaml
# 16:9 aspect ratio image container
- type: flex
  width: 320
  aspectRatio: 1.7778
  background: "#000000"
```

## Auto Margins

Margins support `auto` values for centering elements within flex containers:

```yaml
# Horizontal centering with auto margins
- type: flex
  direction: row
  width: 300
  children:
    - type: text
      content: "Centered"
      width: 100
      margin: "0 auto"

# Push element to the right
- type: flex
  direction: row
  width: 300
  children:
    - type: text
      content: "Right-aligned"
      margin: "0 0 0 auto"
```

Auto margins on the main axis consume free space before `justify-content` is applied. Auto margins on the cross axis override `align-items`/`align-self`.

## Overflow

FlexElement containers support content clipping via the `overflow` property:

| Value | Behavior |
|-------|----------|
| `visible` | Content renders outside container bounds (default) |
| `hidden` | Content is clipped at container bounds |

```yaml
# Clipped container
- type: flex
  width: 200
  height: 100
  overflow: hidden
  children:
    - type: text
      content: "This text will be clipped if it exceeds the container bounds"
```

## Borders

All elements support CSS-like border properties. Borders consume space in layout (added to element size alongside padding).

**Shorthand format:** `"width style color"` (e.g., `"2 solid #333"`, `"1 dashed"`, `"3"`)

**CSS cascade order:**
1. `border` shorthand sets all four sides
2. `borderWidth`, `borderColor`, `borderStyle` override individual properties on all sides
3. `borderTop`, `borderRight`, `borderBottom`, `borderLeft` override specific sides

**Border styles:** `solid`, `dashed`, `dotted`, `none`

```yaml
# Solid border with rounded corners
- type: flex
  border: "2 solid #3498db"
  border-radius: "12"
  padding: "16"
  children:
    - type: text
      content: "Rounded box"

# Per-side borders
- type: flex
  border-top: "3 solid #3498db"
  border-bottom: "1 dashed #cccccc"
  padding: "16"
  children:
    - type: text
      content: "Different borders"
```

## Order

The `order` property controls the visual display order of flex items. Items are sorted by `order` before layout -- lower values appear first. Items with equal `order` preserve source order (stable sort). Default is `0`. Negative values are supported. Absolute-positioned children are excluded from order sorting.

```yaml
# Display order: B (0), C (1), A (2)
- type: flex
  direction: row
  children:
    - type: text
      content: "A"
      order: 2
    - type: text
      content: "B"
      order: 0
    - type: text
      content: "C"
      order: 1
```

## RTL (Right-to-Left) Support

- Canvas `text-direction`: `ltr` (default), `rtl` -- sets default text direction for the entire template
- Element `text-direction`: `ltr`, `rtl`, or null (inherit from parent/canvas) -- per-element override
- Text `align`: `start` and `end` are logical values that resolve based on direction
- Row layout is mirrored in RTL: items flow right-to-left
- Column layout is unaffected by direction
- Arabic font support: use an Arabic-capable font (e.g., Noto Sans Arabic) in the `fonts` section for Arabic text rendering
- HarfBuzz text shaping: optional `FlexRender.HarfBuzz` package provides proper Arabic/Hebrew glyph shaping via `.WithHarfBuzz()` on the Skia builder

## Fonts

Fonts are registered in the `fonts:` section of the YAML template. Two formats are supported. Supported file types: `.ttf` and `.otf`. Font sources can be local file paths, `embedded://` resources, or `http://` URLs. System fonts are used when no custom font is registered.

### Font Registration -- Dictionary Format (Legacy)

Key-value pairs where the key is a reference name used in `font:` properties:

```yaml
fonts:
  default: "assets/fonts/Inter-Regular.ttf"
  heading: "assets/fonts/Roboto-Regular.ttf"
  icon: "embedded://MyApp.Fonts.icons.ttf"
  remote: "https://example.com/font.ttf"
```

### Font Registration -- List Format (Recommended)

An array of font entries. Simple strings and objects with `path`/`name`/`fallback` can be mixed:

```yaml
fonts:
  # Simple strings -- first unnamed font automatically becomes "default" (and "main")
  - "assets/fonts/Inter-Regular.ttf"
  - "assets/fonts/Inter-Bold.ttf"
  - "assets/fonts/Inter-Italic.ttf"

  # With optional name and fallback
  - path: "assets/fonts/Roboto-Regular.ttf"
    name: heading
    fallback: "Arial"
```

**Rules:**
- The first unnamed font automatically becomes `default` (and `main`)
- Fonts can be mixed: simple strings and objects with `path`/`name`/`fallback`
- Named fonts are referenced via `font:` on elements (e.g., `font: heading`)

### Font Properties on Text Elements

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `font` | string | `main` | Reference to a registered font name |
| `fontFamily` | string | (empty) | CSS-like font family name -- searches registered fonts by FamilyName metadata, then system fonts |
| `fontWeight` | string/number | `normal` | Font weight (see table below), or numeric 100-900 |
| `fontStyle` | string | `normal` | Font style: `normal`, `italic`, `oblique` |

### Font Resolution Priority

```
font (registered name) > fontFamily (family name) > fallback (default)
```

- If `font` is set to a non-default value, resolve by registered name
- If `fontFamily` is set, search registered fonts by FamilyName metadata, then system fonts
- Otherwise, use the default font (`main`)

For weight/style variants: **automatic sibling discovery** scans the same directory as the base font file for `.ttf`/`.otf` files with matching family name and weight/style.

### Automatic Sibling Font Discovery

Only the regular/default font file needs to be registered per family. When a text element uses `fontWeight` or `fontStyle`, FlexRender automatically scans the same directory as the registered font for sibling files with a matching family name and weight/style (within +/-100 units for weight, case-insensitive).

**Convention:** Place all weight/style variants of a font family in the same directory:

```
assets/fonts/
  Inter-Regular.ttf      # weight 400, upright
  Inter-Bold.ttf         # weight 700, upright
  Inter-SemiBold.ttf     # weight 600, upright
  Inter-Italic.ttf       # weight 400, italic
  Inter-BoldItalic.ttf   # weight 700, italic
```

Then in templates:

```yaml
- type: text
  content: "Bold text"
  fontWeight: bold          # uses Inter-Bold.ttf automatically

- type: text
  content: "Light italic"
  fontWeight: light
  fontStyle: italic         # discovers Inter-LightItalic.ttf if present
```

For multiple font families, register each family's regular font and use `font:` to select:

```yaml
fonts:
  - "assets/fonts/Inter-Regular.ttf"
  - path: "assets/fonts/Roboto-Regular.ttf"
    name: heading
```

```yaml
- type: text
  font: heading
  fontWeight: bold          # discovers Roboto-Bold.ttf in the same directory
  content: "Bold Heading"
```

### Table Header Font Properties

Tables support font properties on the header row:

| Property | Aliases | Description |
|----------|---------|-------------|
| `headerFont` | `header-font` | Font name for header cells |
| `headerFontWeight` | `header-fontWeight` | Font weight for headers |
| `headerFontStyle` | `header-fontStyle` | Font style for headers (normal, italic, oblique) |
| `headerFontFamily` | `header-fontFamily` | CSS-like font family for headers |

### fontWeight Values

| Name | Numeric |
|------|---------|
| `thin` | 100 |
| `extra-light` | 200 |
| `light` | 300 |
| `normal` (default) | 400 |
| `medium` | 500 |
| `semi-bold` | 600 |
| `bold` | 700 |
| `extra-bold` | 800 |
| `black` | 900 |

Numeric values (100-900) are also accepted: `fontWeight: 600`.

### fontStyle Values

`normal` (default), `italic`, `oblique`.

### Examples

**Minimal (system fonts only, no registration):**

```yaml
layout:
  - type: text
    content: "Hello"
    fontFamily: "Arial"
    fontWeight: bold
```

**List registration with fontWeight/fontStyle:**

```yaml
fonts:
  - "assets/fonts/Inter-Regular.ttf"
  - "assets/fonts/Inter-Bold.ttf"
  - "assets/fonts/Inter-Italic.ttf"

layout:
  - type: text
    content: "Bold text"
    fontWeight: bold
  - type: text
    content: "Italic text"
    fontStyle: italic
```

**Mixed: named + unnamed, font + fontFamily:**

```yaml
fonts:
  - "assets/fonts/Inter-Regular.ttf"
  - path: "assets/fonts/NotoSansArabic-Regular.ttf"
    name: arabic

layout:
  - type: text
    content: "Inter bold"
    fontWeight: bold
  - type: text
    content: "System Georgia"
    fontFamily: "Georgia"
  - type: text
    content: "Arabic"
    font: arabic
```

### Limitations

- **Variable fonts are NOT supported** -- SkiaSharp 3.x does not expose an API for font variation axes. Use separate static font files per weight/style instead.
- Sibling discovery relies on font file metadata (family name, weight, slant). If files use non-standard naming, register them explicitly in the `fonts:` section.

## Flex-Item Properties

All leaf elements (text, image, qr, barcode, separator, rect, circle, ellipse, draw, chart) and flex containers (when nested) have these flex-item properties:

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| grow | float | 0 | Flex grow factor |
| shrink | float | 1 | Flex shrink factor |
| basis | string | "auto" | Flex basis (px, %, em, auto) |
| order | int | 0 | Display order for sorting. Lower values appear first. Negative values supported. Stable sort preserves source order for equal values |
| alignSelf | AlignSelf | Auto | Individual alignment override |
| width | string? | null | Explicit width (px, %, em, auto) |
| height | string? | null | Explicit height (px, %, em, auto) |

## Element Type: text (TextElement)

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| content | string | "" | Text content, may contain `{{variable}}` expressions |
| font | string | "main" | Font reference name from `fonts` section |
| fontFamily | string | "" | CSS-like font family name -- searches registered fonts by FamilyName, then system fonts |
| fontWeight | string? | null | Font weight: `thin` (100), `extra-light` (200), `light` (300), `normal` (400), `medium` (500), `semi-bold` (600), `bold` (700), `extra-bold` (800), `black` (900), or numeric 100-900 |
| fontStyle | string? | null | Font style: `normal`, `italic`, `oblique` |
| size | string | "1em" | Font size (px, em, %) |
| color | string | "#000000" | Text color in hex format |
| align | TextAlign | Left | Text alignment: `left`, `center`, `right`, `start` (logical), `end` (logical) |
| wrap | bool | true | Whether text wraps to multiple lines |
| overflow | TextOverflow | Ellipsis | Overflow handling: `ellipsis`, `clip`, `visible` |
| maxLines | int? | null | Maximum number of lines (null = unlimited) |
| lineHeight | string | "" | Line height for multi-line text (see below) |

### lineHeight Values

| Format | Example | Behavior |
|--------|---------|----------|
| Empty string | `""` | Use font-defined default spacing |
| Plain number | `"1.8"` | Multiplier of fontSize |
| Pixel units | `"24px"` | Absolute pixel value |
| Em units | `"2em"` | Relative to element's fontSize |

Resolved by `LineHeightResolver.Resolve(lineHeight, fontSize, defaultLineHeight)`. Values are clamped to >= 0.

## Element Type: flex (FlexElement)

### Container Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| direction | FlexDirection | Column | Main axis direction: `row`, `column`, `row-reverse`, `column-reverse` |
| wrap | FlexWrap | NoWrap | Wrapping behavior: `nowrap`, `wrap`, `wrap-reverse` |
| gap | string | "0" | Gap between items (px, %, em). Shorthand for both row-gap and column-gap |
| rowGap | string? | null | Gap between wrapped lines. Overrides gap for the row direction |
| columnGap | string? | null | Gap between columns. Overrides gap for the column direction |
| justify | JustifyContent | Start | Main axis alignment: `start`, `center`, `end`, `space-between`, `space-around`, `space-evenly` |
| align | AlignItems | Stretch | Cross axis alignment: `start`, `center`, `end`, `stretch`, `baseline` |
| alignContent | AlignContent | Start | Wrapped lines alignment: `start`, `center`, `end`, `stretch`, `space-between`, `space-around`, `space-evenly` |
| overflow | Overflow | Visible | Content clipping: `visible`, `hidden` |
| children | TemplateElement[] | [] | Child elements |

## Element Type: image (ImageElement)

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| src | string | "" | Image source: file path, base64 data URL, embedded://, http:// |
| width | int? | null | Image container width in pixels (null = natural width) |
| height | int? | null | Image container height in pixels (null = natural height) |
| fit | ImageFit | Contain | How the image fits within bounds |

### Image Fit Modes

| Mode | Description |
|------|-------------|
| `fill` | Stretch to fill bounds (may distort aspect ratio) |
| `contain` | Scale to fit within bounds preserving ratio (may have empty space) |
| `cover` | Scale to cover bounds preserving ratio (may be cropped) |
| `none` | Use image's natural size without scaling |

## Element Type: qr (QrElement)

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| data | string | "" | Data to encode in the QR code |
| size | int | 100 | QR code size in pixels (width = height) |
| errorCorrection | ErrorCorrectionLevel | M | Error correction level |
| foreground | string | "#000000" | Foreground (module) color in hex |

### QR Error Correction Levels

| Level | Recovery Capacity |
|-------|------------------|
| `L` | ~7% recovery |
| `M` | ~15% recovery (default) |
| `Q` | ~25% recovery |
| `H` | ~30% recovery |

## Element Type: barcode (BarcodeElement)

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| data | string | "" | Data to encode |
| format | BarcodeFormat | Code128 | Barcode format |
| width | int | 200 | Barcode width in pixels |
| height | int | 80 | Barcode height in pixels |
| showText | bool | true | Show encoded text below barcode |
| foreground | string | "#000000" | Bar color in hex |

### Barcode Formats

| Format | Description |
|--------|-------------|
| `code128` | Alphanumeric, high density |
| `code39` | Alphanumeric, widely supported |
| `ean13` | 13 digits, retail |
| `ean8` | 8 digits, compact retail |
| `upc` | 12 digits, North American retail (UPC-A) |

## Element Type: table (TableElement)

Tabular data with configurable columns, optional header, and support for dynamic (array-based) and static rows. During template expansion, the `table` element is expanded into a tree of `flex` and `text` elements.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| array | string | "" | Path to data array for dynamic rows |
| as | string? | null | Variable name for current item |
| columns | TableColumn[] | -- | Column definitions (required, at least one) |
| rows | TableRow[] | [] | Static rows (alternative to array) |
| headerFont | string? | null | Font for header row |
| headerFontWeight | string? | null | Font weight for header row |
| headerFontStyle | string? | null | Font style for header row (normal, italic, oblique) |
| headerFontFamily | string? | null | CSS-like font family for header row |
| headerColor | string? | null | Text color for header row |
| headerSize | string? | null | Font size for header row |
| headerBackground | string? | null | Background color for header row |

### TableColumn Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| key | string | -- | Data field name (required) |
| label | string? | null | Header text |
| width | string? | null | Explicit column width (px, %, em) |
| grow | float | 0 | Flex grow factor |
| align | TextAlign | Left | Text alignment: left, center, right |
| font | string? | null | Font override for cells |
| color | string? | null | Text color override for cells |
| size | string? | null | Font size override for cells |
| format | string? | null | Format string for cell values |

### TableRow Properties (Static Rows)

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| values | Dictionary<string,string> | -- | Column key to value mapping (required, case-insensitive) |
| font | string? | null | Font override for this row |
| color | string? | null | Text color override |
| size | string? | null | Font size override |

```yaml
# Dynamic table with header
- type: table
  array: items
  as: item
  headerFont: bold
  headerBackground: "#333333"
  headerColor: "#ffffff"
  columns:
    - key: name
      label: "Product"
      grow: 1
    - key: price
      label: "Price"
      width: "80"
      align: right

# Static summary table
- type: table
  columns:
    - key: label
      grow: 1
      font: bold
    - key: value
      width: "80"
      align: right
  rows:
    - values: { label: "Subtotal", value: "85.00 $" }
    - values: { label: "Tax", value: "8.50 $" }
    - values: { label: "Total", value: "93.50 $" }
      font: bold
```

## Element Type: separator (SeparatorElement)

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| orientation | SeparatorOrientation | Horizontal | Direction: `horizontal`, `vertical` |
| style | SeparatorStyle | Dotted | Line style: `dotted`, `dashed`, `solid` |
| thickness | float | 1 | Line thickness in pixels |
| color | string | "#000000" | Line color in hex |
| width | string? | null | Explicit width override |
| height | string? | null | Explicit height override |

Horizontal separators stretch to full width and use thickness as height. Vertical separators stretch to full height and use thickness as width. The default style is `dotted`, chosen for the primary receipt printing use case.

## Shape Elements

The `rect`, `circle`, and `ellipse` elements are **box shapes** -- flex boxes that are painted as a filled and/or stroked vector shape. They participate in flex layout exactly like any other box: they honor `width`, `height`, `margin`, `padding`, and all flex-item properties (`grow`, `shrink`, `basis`, `order`, `alignSelf`). The shape is drawn to fill the box content area.

### Shared Box-Shape Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| fill | string OR object | none | Solid hex color (e.g. `"#4A90D9"`) OR a gradient object (see below) |
| stroke | string | none | Stroke (outline) color in hex |
| stroke-width | number | 0 | Stroke width in pixels |
| opacity | number | 1.0 | Inherited base opacity, `0..1` |
| radius | unit | none | Corner radius in px/em (**rect only**) |
| size | unit | none | Shorthand setting both width and height = diameter (**circle only**) |

### Gradient Fill Object

The `fill` property accepts an object form to paint a gradient. It is converted internally to a CSS gradient string.

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| gradient | string | -- | `linear` or `radial` (required) |
| colors | string[] | -- | Two or more hex color stops (required, minimum 2) |
| angle | number | 0 | Angle in degrees (linear only; radial ignores `angle`) |

```yaml
- type: rect
  width: 100
  height: 100
  fill:
    gradient: linear
    colors: ["#f00", "#00f"]
    angle: 45
```

## Element Type: rect (RectElement)

A flex box drawn as a filled/stroked rectangle, optionally with rounded corners.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| fill | string OR object | none | Solid hex color or gradient object |
| stroke | string | none | Stroke color in hex |
| stroke-width | number | 0 | Stroke width in pixels |
| opacity | number | 1.0 | Base opacity, `0..1` |
| radius | unit | none | Corner radius (px/em) |

```yaml
- type: rect
  width: 100
  height: 50
  fill: "#4A90D9"
  stroke: "#333333"
  stroke-width: 2
  radius: 4
```

## Element Type: circle (CircleElement)

A flex box drawn as a circle. Use `size` as a shorthand to set both width and height (the diameter); the circle is inscribed in the resulting box.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| fill | string OR object | none | Solid hex color or gradient object |
| stroke | string | none | Stroke color in hex |
| stroke-width | number | 0 | Stroke width in pixels |
| opacity | number | 1.0 | Base opacity, `0..1` |
| size | unit | none | Sets both width and height (diameter) |

```yaml
- type: circle
  size: 40
  fill: "#e74c3c"
```

## Element Type: ellipse (EllipseElement)

A flex box drawn as an ellipse that fills its `width` by `height` box.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| fill | string OR object | none | Solid hex color or gradient object |
| stroke | string | none | Stroke color in hex |
| stroke-width | number | 0 | Stroke width in pixels |
| opacity | number | 1.0 | Base opacity, `0..1` |

```yaml
- type: ellipse
  width: 120
  height: 60
  fill: "#2ecc71"
```

## Element Type: draw (DrawElement)

A flex box that holds an ordered list of absolute-coordinate `shapes`. Shapes are painted in list order (painter's algorithm -- later shapes are drawn on top). All coordinates are relative to the `draw` element's top-left corner. The number of shapes is capped by `ResourceLimits.MaxShapesPerDraw` (default 1000).

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| width | unit | none | Box width |
| height | unit | none | Box height |
| shapes | Shape[] | [] | Ordered list of shapes (painted in order) |

Each entry in `shapes` is a single-key object whose key selects the shape kind:

| Shape | Keys | Description |
|-------|------|-------------|
| line | `x1`, `y1`, `x2`, `y2`, `stroke`, `stroke-width` | Straight line segment |
| polyline | `points` (`[[x,y],...]`), `stroke`, `stroke-width`, `fill` | Connected line segments, optionally filled |
| rect | `x`, `y`, `width`, `height`, `fill`, `stroke`, `stroke-width`, `radius` | Rectangle (optional rounded corners) |
| circle | `cx`, `cy`, `r`, `fill`, `stroke`, `stroke-width` | Circle centered at (`cx`,`cy`) with radius `r` |
| path | `d`, `fill`, `stroke`, `stroke-width` | SVG-style path (see grammar below) |

### Path `d` Grammar

The `path` shape's `d` string supports **absolute commands only**: `M` (moveto), `L` (lineto), `Q` (quadratic Bézier), `C` (cubic Bézier), and `Z` (closepath). Lowercase/relative commands are rejected, and non-finite numbers are rejected.

```
M x y            # move to (x, y)
L x y            # line to (x, y)
Q cx cy x y      # quadratic Bézier, control (cx, cy), end (x, y)
C c1x c1y c2x c2y x y   # cubic Bézier, two controls, end point
Z                # close path
```

Example: `d: "M 0 0 L 100 50 Q 150 0 200 50 Z"`

```yaml
- type: draw
  width: 400
  height: 200
  shapes:
    - line: {x1: 0, y1: 100, x2: 400, y2: 50, stroke: "#333", stroke-width: 2}
    - circle: {cx: 200, cy: 75, r: 30, fill: "#e74c3c"}
    - path: {d: "M 0 0 L 100 50 Q 150 0 200 50 Z", fill: "#2ecc71"}
```

## Element Type: chart (ChartElement)

A declarative chart element that renders bar, line, area, pie, donut, scatter, bubble, gauge, progress, sparkline, heatmap, and radar charts. The chart paints into its `width` by `height` box and participates in flex layout like any other element. Both `width` and `height` are required.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| chart-type | string | `bar` | Chart kind: `bar`, `line`, `area`, `pie`, `donut`, `scatter`, `bubble`, `gauge`, `progress`, `sparkline`, `heatmap`, `radar` |
| width | number | none | Chart width in pixels (**required**) |
| height | number | none | Chart height in pixels (**required**) |
| categories | string[] | `[]` | X-axis category labels (bar/line/area) or slice labels (pie/donut) |
| series | Series[] | `[]` | List of series, each `{ label?, data }` (see below) |
| palette | string OR string[] | theme default | Named palette (`default`, `ocean`, `sunset`, `forest`, `mono`, `vivid`) OR an explicit color list `["#hex", ...]` |
| theme | string | template theme | Per-element theme override: `light`, `dark`, `minimal` |
| legend | string | `bottom` | Legend placement: `top`, `bottom`, `left`, `right`, `none` |
| title | string | none | Optional chart title |
| horizontal | bool | `false` | **Bar only.** Render bars horizontally |
| stacked | bool | `false` | **Bar only.** Stack series on top of each other |
| smooth | bool | `false` | **Line/area/sparkline only.** Smooth (curved) lines instead of straight segments |
| points | bool | `false` | **Line/area/sparkline only.** Draw point markers at each data value |
| labels | string | `percent` | **Pie/donut only.** Slice label content: `percent`, `value`, `none` |
| value | number | none | **Gauge/progress only.** The indicator value |
| max | number | `100` | **Gauge/progress only.** The indicator maximum |
| label | string | none | **Gauge/progress only.** Centered caption under the value |
| x-labels | string[] | `[]` | **Heatmap only.** Column (x-axis) labels; falls back to `categories` if omitted |
| y-labels | string[] | `[]` | **Heatmap only.** Row (y-axis) labels, one per series/row |
| cell-values | bool | `false` | **Heatmap only.** Draw each cell's numeric value inside the cell |

### Series and Data Binding

Each entry in `series` is an object with an optional `label` (used in the legend) and a required `data` value. For bar/line/area/pie/donut/sparkline, `data` is either an inline array of numbers, **or** a `{{ expression }}` string that resolves to a number array from the render data context -- the same binding mechanism used by `table` rows. This lets chart data come directly from the data file:

```yaml
series:
  - label: "2024"
    data: [12, 30, 22, 48]      # inline literal numbers
  - label: "2025"
    data: "{{ sales }}"          # resolves to a number array from data
```

### Phase-3 Chart Types

**Scatter and bubble** take tuple data instead of a flat number array: `data: [[x, y], ...]` for `scatter` and `data: [[x, y, r], ...]` for `bubble`, where `r` sizes each bubble. Tuple data is inline-only (expression-bound tuples are not yet supported).

```yaml
- type: chart
  chart-type: scatter
  width: 480
  height: 320
  series:
    - data: [[1, 12], [3, 30], [5, 22], [7, 48], [9, 35]]
- type: chart
  chart-type: bubble
  width: 480
  height: 320
  series:
    - data: [[1, 12, 6], [3, 30, 18], [5, 22, 10], [7, 48, 24]]
```

**Gauge and progress** are single-value indicators that ignore `series`/`categories` and instead use `value`, `max` (default 100), and `label` (a centered caption). Gauge draws a 270-degree dial; progress draws a ring filled to `value` / `max`.

```yaml
- type: chart
  chart-type: gauge
  width: 280
  height: 220
  value: 72
  max: 100
  label: CPU
- type: chart
  chart-type: progress
  width: 240
  height: 240
  value: 64
  label: Disk
```

**Sparkline** is a tiny inline line chart with no axes, legend, or title (chrome-free). It uses a plain numeric `data` array and honors `smooth` and `points`.

```yaml
- type: chart
  chart-type: sparkline
  width: 200
  height: 50
  smooth: true
  series:
    - data: [3, 8, 4, 10, 6, 9, 5, 11]
```

### Phase-4 Chart Types

Heatmap takes 2D data: each `series` entry is one ROW (`series[i].data` = that row's column values), `x-labels` label the columns (or `categories` if omitted), `y-labels` label the rows, and `cell-values: true` prints each cell's number. Cell color is interpolated between the palette's first ("low") and second ("high") colors. Radar uses `categories` as spokes (one axis per category, starting at the top); each `series` is a closed polygon along the spokes, filled semi-transparently and stroked, sharing one radial scale anchored at zero at the center.

```yaml
- type: chart
  chart-type: heatmap
  width: 420
  height: 300
  x-labels: [Mon, Tue, Wed, Thu, Fri]
  y-labels: [Morning, Afternoon, Evening]
  cell-values: true
  series:
    - data: [2, 8, 4, 10, 6]
    - data: [5, 3, 9, 7, 1]
    - data: [8, 6, 2, 4, 9]
  legend: none
  palette: ocean
- type: chart
  chart-type: radar
  width: 360
  height: 360
  categories: [Speed, Power, Range, Agility, Armor, Stealth]
  series:
    - label: Alpha
      data: [4, 3, 5, 2, 4, 3]
    - label: Bravo
      data: [3, 5, 2, 4, 3, 5]
  legend: bottom
  palette: vivid
```

### Palettes and Themes

The `palette` selects series colors. Use one of the named palettes (`default`, `ocean`, `sunset`, `forest`, `mono`, `vivid`) or supply an explicit list of hex colors that is applied to series/slices in order. The `theme` (`light`, `dark`, `minimal`) controls the chart's background, axis, grid, and text colors; it overrides the template-level theme for this element only.

### "No Data" Behavior

A chart whose `series` is empty or missing -- or whose series contain no data points -- renders a centered **"no data"** placeholder inside its box. This is never treated as an error, so charts bound to optional or empty data sources degrade gracefully.

### Resource Limits

Charts are bounded by `ResourceLimits.MaxSeriesPerChart` (default 50) and `ResourceLimits.MaxDataPointsPerSeries` (default 10000).

```yaml
- type: chart
  chart-type: bar
  width: 600
  height: 300
  categories: [Q1, Q2, Q3, Q4]
  series:
    - label: "2024"
      data: "{{ sales }}"
    - label: "2025"
      data: [12, 30, 22, 48]
  palette: ocean
  legend: bottom
  title: "Revenue"
  theme: dark
```

## Element Type: svg (SvgElement)

Renders SVG vector graphics. Supports external files (`src`) or inline markup (`content`). These are mutually exclusive.

> Requires `FlexRender.SvgElement.Skia.Render` (or `FlexRender.SvgElement`) package: `.WithSkia(skia => skia.WithSvgElement())`

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| src | string? | null | Path to SVG file (loaded via resource loaders). Mutually exclusive with `content`. |
| content | string? | null | Inline SVG markup string. Mutually exclusive with `src`. |
| width | int? | null | Target render width in pixels. `null` = SVG intrinsic or container. |
| height | int? | null | Target render height in pixels. `null` = SVG intrinsic or container. |
| fit | ImageFit | contain | How SVG fits within bounds: `fill`, `contain`, `cover`, `none`. |

```yaml
# From file
- type: svg
  src: "assets/icons/logo.svg"
  width: 120
  height: 40

# Inline SVG
- type: svg
  content: '<svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" fill="#4CAF50"/></svg>'
  width: 48
  height: 48
```

## Element Type: content (ContentElement)

Embeds formatted text (Markdown, HTML, or NDC binary data) that is parsed into an AST subtree at render time. Requires a content parser to be registered.

**Important:** Content element expansion is async-only (`ExpandAsync()`). There is no synchronous expansion path. This is why the entire pipeline is async.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| source | string | "" | Content to parse. `text:` prefix for plain text, `{{variable}}` for `string`/`BytesValue`, everything else delegates to IResourceLoader chain |
| format | string | "markdown" | Content format: `markdown`, `html`, or `ndc` -- must match a registered parser |
| options | dict? | null | Parser-specific options (e.g., NDC `columns`, `charsets`). Passed to the content parser. |

```yaml
- type: content
  source: "{{body}}"     # text with formatting (from data)
  format: markdown       # or "html" -- must match registered parser
```

Content source resolution (inlined in TemplateExpander):
- `{{variable}}` -> if variable is BytesValue (byte[]), passes binary directly to IBinaryContentParser
- `text:...` -> plain text (bypasses loaders)
- All other sources delegate to IResourceLoader chain (`data:`, `base64:`, `file:`, `http://`, `embedded://`)
- If no loader handles the source -> falls back to plain text

Binary data binding:
```csharp
// Pass byte[] directly to binary parsers (e.g., NDC)
var data = new ObjectValue { ["receipt"] = new BytesValue(bytes) };
var data = new ObjectValue { ["receipt"] = BytesValue.FromStream(stream) };
```

Requires content parser registration: `.WithMarkdown()` (Markdig), `.WithHtml()` (HtmlAgilityPack), or `.WithNdc()` (built-in).
Converts formatted text into FlexRender AST elements at render time (bold -> FontWeight.Bold, italic -> FontStyle.Italic, headings, lists, etc.).

### NDC Format

The `ndc` format parses binary NDC (NCR ATM protocol) printer data streams. Supports both text (`IContentParser`) and binary (`IBinaryContentParser`) input.

Key features:
- Charset switching with per-charset styling (font, color, encoding)
- QWERTY→JCUKEN character encoding for Russian
- Embedded barcode support (UPC-A, UPC-E, EAN-13, EAN-8, Code39, Code128, Codabar)
- Auto font size calculation based on parent width
- Form feed, line spacing, tab controls

```yaml
# Load NDC data from a local file
- type: content
  source: "file:ndc-data/receipt.bin"
  format: ndc
  options:
    columns: 40
    font_family: "JetBrains Mono"
    charsets:
      I:
        font: bold
        font_style: bold
        encoding: qwerty-jcuken
        uppercase: true
      J:
        encoding: qwerty-jcuken
      "2":
        font: default

# Or load from a template variable (C# API with BytesValue)
- type: content
  source: "{{receiptData}}"
  format: ndc
  options:
    columns: 40
    input_encoding: latin1
    font_family: "JetBrains Mono"
    charsets:
      "1":
        encoding: "qwerty-jcuken"
        font_style: bold
```

NDC options:
- `columns` -- receipt width in characters (default: 40, standard for 80mm thermal printers)
- `input_encoding` -- byte encoding: `latin1` (default), `utf-8`, `ascii`
- `font_family` -- monospaced font for accurate column alignment
- `char_width_ratio` -- character width ratio (default: 0.6)
- `charsets` -- per-charset styling keyed by designator character from `ESC(X` sequences:
  - `encoding` -- `qwerty-jcuken` (Latin→Cyrillic), `none`, `ascii`
  - `font` / `font_style` -- font name or style (`bold`, `italic`, `bold-italic`, `regular`)
  - `font_size` -- explicit size in pixels (auto-calculated if omitted)
  - `color` -- text color (hex)
  - `uppercase` -- convert to uppercase after encoding

Register via `.WithNdc()` (FlexRender.Content.Ndc package, 0 external dependencies).

## Color Format

Colors are specified in hex format:

- `#rrggbb` -- 6-digit hex (e.g., `"#ff0000"` for red)
- `#rgb` -- 3-digit hex shorthand (e.g., `"#f00"` for red)

Parsed by `ColorParser` in the Rendering namespace.

## YAML Validation

The parser validates all YAML property names against known properties for each element type. Unknown properties trigger a `TemplateParseException` with a "Did you mean?" suggestion using Levenshtein distance:

```
Unknown property 'colour' for element type 'text'. Did you mean 'color'?
Unknown property 'backgrund' for element type 'flex'. Did you mean 'background'?
```

Known properties are maintained per element type in `KnownProperties` (src/FlexRender.Yaml/Parsing/KnownProperties.cs). This covers all 11 element types and their specific + common properties.

## Supported Units

| Unit | Syntax | Resolution |
|------|--------|------------|
| Pixels | `"100"`, `"100px"` | Absolute pixel value (default) |
| Percentage | `"50%"` | Percentage of parent container size |
| Em | `"1.5em"` | Relative to font size |
| Auto | `"auto"` | Automatic sizing by layout engine |

Parsed by `UnitParser.Parse(string?)` which returns a `Unit` value. Plain numbers without suffix are treated as pixels.

## Expression Syntax

### Variable Substitution

- `{{variable}}` -- simple variable lookup
- `{{user.name}}` -- dot notation path traversal
- `{{items[0]}}` -- array index access
- `{{items[0].name}}` -- combined path and index

### Inline Expressions

Expressions within `{{ }}` support arithmetic, comparison, logical NOT, null coalescing, and filters:

- `{{price * quantity}}` -- arithmetic (`+`, `-`, `*`, `/`, unary `-`)
- `{{total > 1000}}` -- comparison (`==`, `!=`, `<`, `>`, `<=`, `>=`)
- `{{!active}}` -- logical NOT (inverts truthiness)
- `{{name || 'Guest'}}` -- truthy coalescing / logical OR (fallback for null, "", 0, false)
- `{{a && b}}` -- logical AND (returns first falsy or last value)
- `{{nickname ?? name ?? 'Guest'}}` -- null coalescing chain
- `{{price | currency}}` -- filter pipe
- `{{total * 1.1 | currency}}` -- combined
- `{{date | format:"dd.MM.yyyy"}}` -- filter with argument
- Literals: `true`, `false`, `null` (e.g., `{{status == null}}`, `{{active == true}}`)

**Precedence** (highest to lowest): `!`/unary `-`, `*`/`/`, `+`/`-`, `==`/`!=`/`<`/`>`/`<=`/`>=`, `&&`, `||`, `??`, `|`

**Comparison rules:**
- Numbers: compared by value
- Strings: ordinal (case-sensitive) comparison
- Booleans: only `==` and `!=`; ordered comparisons return false
- Null: `null == null` is true; `null != <anything>` is true; ordered comparisons with null return false
- Mixed types: `==` is false, `!=` is true, ordered comparisons return false
- Chained comparisons (e.g., `a < b < c`) are not supported (parse error)

**Built-in filters (enabled by default):** `currency` (2dp), `currencySymbol` (ISO 4217 code to symbol, e.g., USD -> $, RUB -> ruble sign), `number:N` (N decimal places, 0-20), `upper`, `lower`, `trim`, `truncate:N` (default 50, max 10000), `format:str` (number/date formatting via .NET format strings). Use `WithoutDefaultFilters()` to disable.

**Limits:** Max expression length = 2000 chars, max depth = 50

### Text Blocks (inside `content` strings)

Text blocks provide control flow inside text `content` values. They are processed by the template engine at render time.

**Conditional:** `{{#if condition}}...{{else}}...{{/if}}`
- Condition is evaluated for truthiness (non-empty string, non-zero number, true, non-empty array/object = truthy)
- Supports full expressions: `{{#if status == 'paid'}}...{{/if}}`, `{{#if total > 100}}...{{/if}}`, `{{#if !disabled}}...{{/if}}`, `{{#if role == 'admin' || role == 'mod'}}...{{/if}}`, `{{#if active && verified}}...{{/if}}`

**Loop:** `{{#each arrayPath}}...{{/each}}`
- Iterates over an array. Inside the body, current item properties are accessible directly
- Loop variables: `@index` (0-based), `@first`, `@last`

```yaml
- type: text
  content: "{{#if status == 'paid'}}Paid{{else}}Unpaid{{/if}}"

- type: text
  content: "{{#each items}}{{name}}{{#if @last}}.{{else}}, {{/if}}{{/each}}"
```

> **Note:** Text blocks (`{{#if}}`, `{{#each}}`) work inside text `content` values. For element-level conditions and loops, use `type: if` and `type: each` elements instead.

### Visual Effects Properties

- `opacity`: float (0.0-1.0, default 1.0) -- element transparency via `canvas.SaveLayer()`, affects entire subtree
- `box-shadow`: `"offsetX offsetY blurRadius color"` -- rendered via `SKMaskFilter.CreateBlur()` before element content
- `background` accepts CSS gradients in addition to hex colors:
  - `linear-gradient(to right, #ff0000, #0000ff)` -- direction keywords or angle in degrees
  - `linear-gradient(45deg, #ff0000, #00ff00 50%, #0000ff)` -- with color stop positions
  - `radial-gradient(#ffffff, #000000)` -- radial from center outward
  - Direction keywords: `to top`, `to right`, `to bottom`, `to left`, `to top right`, etc.
  - Color stops: optional percentage positions, evenly distributed if omitted

### Culture Support

- `template.culture`: optional culture string in YAML (e.g., `"ru-RU"`, `"en-US"`)
- `RenderOptions.Culture`: per-call `CultureInfo` override in C# code
- Priority: `RenderOptions.Culture` > `template.culture` > `CultureInfo.InvariantCulture`
- Affects built-in filters (enabled by default): `currency`, `currencySymbol`, `number`, `format`

```csharp
// Per-call culture override
byte[] png = await render.RenderToPng(template, data,
    renderOptions: new RenderOptions { Culture = new CultureInfo("ru-RU") });
```

## Control Flow Elements (AST-Level)

Control flow is handled at AST level via dedicated element types (`EachElement`, `IfElement`), enabling template caching.

### Element Type: each (EachElement)

Iterates over an array in the data, creating child elements for each item.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| array | string | Yes | Path to array in data (e.g., "items", "order.lines") |
| as | string | No | Variable name for each item (e.g., "item" to use {{item.name}}) |
| children | TemplateElement[] | Yes | Template elements to render per item |

```yaml
- type: each
  array: items
  as: item
  children:
    - type: text
      content: "{{item.name}}: {{item.price}}"
```

### Loop Variables

Available inside `each` children:

| Variable | Type | Description |
|----------|------|-------------|
| `{{@index}}` | int | Zero-based index of current item |
| `{{@first}}` | bool | True for the first item |
| `{{@last}}` | bool | True for the last item |

### Element Type: if (IfElement)

Conditional rendering based on data values. Supports 13 operators.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| condition | string | Yes | Path to value for condition check |
| then | TemplateElement[] | Yes | Elements to render when condition is true |
| elseIf | IfElement | No | Nested else-if condition |
| else | TemplateElement[] | No | Elements to render when all conditions are false |

**Condition Operators** (only one per `if`, use nested `if` for AND/OR):

| Operator | YAML Key | Value Type | Description |
|----------|----------|------------|-------------|
| Truthy | (none) | - | Value exists and is non-empty/non-zero/non-false |
| Equals | `equals` | any | Value equals (numbers, strings, bool, arrays, null) |
| NotEquals | `notEquals` | any | Value does not equal |
| In | `in` | array | Value is in the list |
| NotIn | `notIn` | array | Value is not in the list |
| Contains | `contains` | any | Array contains the element |
| GreaterThan | `greaterThan` | number | Numeric greater than |
| GreaterThanOrEqual | `greaterThanOrEqual` | number | Numeric >= |
| LessThan | `lessThan` | number | Numeric less than |
| LessThanOrEqual | `lessThanOrEqual` | number | Numeric <= |
| HasItems | `hasItems` | bool | Array is non-empty (true) or empty (false) |
| CountEquals | `countEquals` | number | Array length equals N |
| CountGreaterThan | `countGreaterThan` | number | Array length > N |

```yaml
# Truthy check (non-empty, non-zero, non-false)
- type: if
  condition: isPremium
  then:
    - type: text
      content: "Premium member"

# Equality (works with numbers, strings, bool, arrays, null)
- type: if
  condition: status
  equals: "paid"
  then:
    - type: text
      content: "Paid"

# In list
- type: if
  condition: role
  in: ["admin", "moderator"]
  then:
    - type: text
      content: "Staff member"

# Numeric comparison
- type: if
  condition: total
  greaterThan: 1000
  then:
    - type: text
      content: "Large order"

# Array checks
- type: if
  condition: items
  hasItems: true
  then:
    - type: each
      array: items
      children:
        - type: text
          content: "{{item.name}}"

# Else-if chain
- type: if
  condition: status
  equals: "paid"
  then:
    - type: text
      content: "Paid"
  elseIf:
    condition: status
    equals: "pending"
    then:
      - type: text
        content: "Pending"
  else:
    - type: text
      content: "Unknown"
```

### Content Embedding

```yaml
- type: content
  source: "{{body}}"     # text with formatting (from data)
  format: markdown       # or "html" -- must match registered parser
```

Requires content parser registration: `.WithMarkdown()` (Markdig), `.WithHtml()` (HtmlAgilityPack), or `.WithNdc()` (built-in).
Converts formatted text into FlexRender AST elements at render time (bold -> FontWeight.Bold, italic -> FontStyle.Italic, headings, lists, etc.).

### Processing Layers

1. **AST-Level** (`TemplateExpander`): Expands `type: each` and `type: if` elements into concrete elements based on data. Enables template caching — parse once, expand many times with different data.
2. **Inline** (`TemplateProcessor`): Resolves `{{variable}}` expressions in element property values after expansion.

## Resource Loading Chain

Resources (images, fonts) are loaded through `IResourceLoader` implementations using Chain of Responsibility pattern. Loaders are tried in priority order (lower = higher priority).

| Loader | Priority Range | Handles | URI Scheme |
|--------|---------------|---------|------------|
| Base64ResourceLoader | 0-99 (High) | Base64-encoded data | `data:`, `data://`, `base64:`, `base64://` |
| EmbeddedResourceLoader | 0-99 (High) | Assembly embedded resources | `embedded://` |
| FileResourceLoader | 100-199 (Normal) | Local file system (relative paths only) | `file:`, `file://`, `file:///`, relative paths |
| HttpResourceLoader | 200+ (Low) | Remote HTTP/HTTPS resources | `http://`, `https://` |

> **Security:** FileResourceLoader rejects absolute paths with `ArgumentException`. Only relative paths resolved against `BasePath` are allowed. Unrecognized URI schemes are also rejected.

Custom loaders can be added via `builder.ResourceLoaders.Add(new CustomLoader())` (internal API). Implement `IResourceLoader` with `CanHandle()`, `Load()`, and `Priority`.

## Builder API

### Without DI (Minimal)

```csharp
var render = new FlexRenderBuilder()
    .WithSkia()
    .Build();

var parser = new TemplateParser();
var template = parser.Parse(yaml);
byte[] png = await render.Render(template, data);
```

### Without DI (Full Configuration)

```csharp
var render = new FlexRenderBuilder()
    .WithHttpLoader(httpClient)                   // HTTP resource loading
    .WithEmbeddedLoader(typeof(Program).Assembly) // Embedded resources
    .WithBasePath("./templates")                  // Base path for files
    .WithLimits(limits => limits.MaxRenderDepth = 200)
    .WithMarkdown()                               // optional: Markdown content parsing
    .WithHtml()                                   // optional: HTML content parsing
    .WithNdc()                                    // optional: NDC ATM receipt parsing
    .WithSkia(skia => skia
        .WithQr()                                 // QR code support
        .WithBarcode())                           // Barcode support
    .Build();

// Extension from FlexRender.Yaml
byte[] png = await render.RenderFile("receipt.yaml", data);
byte[] jpg = await render.RenderFile("receipt.yaml", data, ImageFormat.Jpeg);
byte[] raw = await render.RenderFile("receipt.yaml", data, ImageFormat.Raw);
```

### With DI

```csharp
// Program.cs - simple
services.AddFlexRender(builder => builder
    .WithSkia(skia => skia.WithQr().WithBarcode()));

// Program.cs - with service provider
services.AddFlexRender((sp, builder) =>
{
    var config = sp.GetRequiredService<IConfiguration>();
    var basePath = config["FlexRender:BasePath"] ?? "./templates";

    builder
        .WithHttpLoader()
        .WithBasePath(basePath)
        .WithSkia(skia => skia
            .WithQr()
            .WithBarcode());
});

// In your service
public class ReceiptService(IFlexRender render)
{
    public async Task<byte[]> Generate(ReceiptData data)
    {
        var values = MapToObjectValue(data);
        return await render.RenderFile("receipt.yaml", values);
    }
}
```

### Sandboxed (No File System Access)

```csharp
var render = new FlexRenderBuilder()
    .WithoutDefaultLoaders()
    .WithEmbeddedLoader(typeof(Program).Assembly)
    .WithSkia(skia => skia.WithQr())
    .Build();
```

### Template Caching (User-Controlled)

```csharp
// Parse once at startup
var parser = new TemplateParser();
_templates["receipt"] = await parser.ParseFileAsync("receipt.yaml");

// Render per request
byte[] png = await render.Render(_templates["receipt"], data);
```

### FlexRenderBuilder Methods

| Method | Description |
|--------|-------------|
| `WithSkia(Action<SkiaBuilder>?)` | Configure Skia renderer |
| `WithImageSharp(Action<ImageSharpBuilder>?)` | Configure ImageSharp renderer (pure .NET, no native deps) |
| `WithBasePath(string)` | Base path for resolving relative file paths |
| `WithLimits(Action<ResourceLimits>)` | Configure resource limits |
| `WithEmbeddedLoader(Assembly)` | Add embedded resource loader |
| `WithHttpLoader(HttpClient?)` | Add HTTP resource loader |
| `WithFilter(ITemplateFilter)` | Register a custom template filter for inline expressions (works alongside built-in filters) |
| `WithMarkdown()` | Enable Markdown content parsing (requires FlexRender.Content.Markdown) |
| `WithHtml()` | Enable HTML content parsing (requires FlexRender.Content.Html) |
| `WithNdc()` | Enable NDC content parsing (requires FlexRender.Content.Ndc) |
| `WithBinaryContentParser(IBinaryContentParser)` | Register a binary content parser |
| `WithoutDefaultLoaders()` | Remove File and Base64 loaders |
| `WithoutDefaultFilters()` | Remove all 8 built-in filters (enabled by default), leaving only custom-registered filters |

### SkiaBuilder Methods

| Method | Description |
|--------|-------------|
| `WithQr()` | Enable QR code support (requires FlexRender.QrCode.Skia.Render or FlexRender.QrCode) |
| `WithBarcode()` | Enable barcode support (requires FlexRender.Barcode.Skia.Render or FlexRender.Barcode) |
| `WithHarfBuzz()` | Enable HarfBuzz text shaping for RTL scripts (requires FlexRender.HarfBuzz) |

### ImageSharpBuilder Methods

`ImageSharpBuilder` is configured via `WithImageSharp()` and supports QR/barcode providers.

| Method | Description |
|--------|-------------|
| `WithQr()` | Enable QR code support (requires FlexRender.QrCode.ImageSharp.Render or FlexRender.QrCode) |
| `WithBarcode()` | Enable barcode support (requires FlexRender.Barcode.ImageSharp.Render or FlexRender.Barcode) |

```csharp
var render = new FlexRenderBuilder()
    .WithImageSharp(imageSharp => imageSharp.WithQr().WithBarcode())
    .Build();
```

**Limitations:** ImageSharp does not support SVG elements. It is NOT AOT-compatible (SixLabors.ImageSharp uses reflection).

### SvgBuilder Methods

| Method | Description |
|--------|-------------|
| `WithSkia(Action<SkiaBuilder>?)` | Use Skia as raster fallback for SVG output |
| `WithRasterBackend(Func<FlexRenderBuilder, IFlexRender>)` | Use any IFlexRender impl as raster fallback |

If both `WithSkia` and `WithRasterBackend` are called, Skia takes precedence.

```csharp
// SVG output with ImageSharp as raster backend
var render = new FlexRenderBuilder()
    .WithSvg(svg => svg.WithRasterBackend(
        ImageSharpFlexRenderBuilderExtensions.CreateRendererFactory()))
    .Build();
```

### IFlexRender Interface

```csharp
public interface IFlexRender : IDisposable
{
    Task<byte[]> Render(
        Template template,
        ObjectValue? data = null,
        ImageFormat format = ImageFormat.Png,
        CancellationToken cancellationToken = default);

    Task Render(
        Stream output,
        Template template,
        ObjectValue? data = null,
        ImageFormat format = ImageFormat.Png,
        CancellationToken cancellationToken = default);
}

// Extension methods from FlexRender.Yaml:
// - RenderYaml(yaml, data, format, ct) - render from YAML string
// - RenderFile(path, data, format, ct) - render from YAML file

// Extension methods from FlexRender.Xml:
// - RenderXml(xml, data, format, parser?, ct) - render from XML string (mirrors RenderYaml)
```

### ImageFormat Enum

| Value | Description |
|-------|-------------|
| `Png` | Lossless PNG (default) |
| `Jpeg` | Lossy JPEG |
| `Bmp` | Uncompressed BMP |
| `Raw` | Raw BGRA pixel data (4 bytes/pixel) |

## Configurable Resource Limits

The `ResourceLimits` class centralizes all security limits. All properties validate positive values and throw `ArgumentOutOfRangeException` on invalid input.

| Property | Type | Default | Purpose |
|----------|------|---------|---------|
| MaxTemplateFileSize | long | 1,048,576 (1 MB) | Maximum YAML template file size in bytes |
| MaxDataFileSize | long | 10,485,760 (10 MB) | Maximum JSON data file size in bytes |
| MaxTemplateNestingDepth | int | 100 | Maximum nesting depth for template engine control flow |
| MaxRenderDepth | int | 100 | Maximum recursion depth when rendering layout tree |
| MaxImageSize | int | 10,485,760 (10 MB) | Maximum allowed image size in bytes |
| MaxFlexLines | int | 1,000 | Maximum flex lines when wrapping |
| MaxShapesPerDraw | int | 1,000 | Maximum shapes in a single `draw` element |
| MaxSeriesPerChart | int | 50 | Maximum series in a single `chart` element |
| MaxDataPointsPerSeries | int | 10,000 | Maximum data points per chart series |

### Direct Usage

```csharp
var limits = new ResourceLimits
{
    MaxRenderDepth = 200,
    MaxTemplateFileSize = 2 * 1024 * 1024
};
using var renderer = new SkiaRenderer(limits);
```

### Via Builder

```csharp
builder.WithLimits(limits =>
{
    limits.MaxRenderDepth = 200;
    limits.MaxTemplateFileSize = 2 * 1024 * 1024;
});
```

These limits exist to prevent abuse and resource exhaustion. Never remove or weaken them without explicit justification.

## FlexRenderOptions

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| Limits | ResourceLimits | new() | Resource limits configuration (read-only, configure via WithLimits) |
| BasePath | string? | null | Base path for resolving relative file paths |
| DefaultFontFamily | string | "Arial" | Default font family |
| BaseFontSize | float | 12 | Base font size in points |
| MaxImageSize | int | 10 MB | Delegates to Limits.MaxImageSize |
| EnableCaching | bool | true | Resource caching toggle |
| EmbeddedResourceAssemblies | List\<Assembly\> | [] | Assemblies for embedded resource search |

## HttpResourceLoaderOptions

Configuration for HTTP resource loading (fonts, images from URLs):

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| Timeout | TimeSpan | 30 seconds | Timeout for HTTP requests |
| MaxResourceSize | int | 10,485,760 (10 MB) | Maximum allowed resource size in bytes |

### Usage

```csharp
builder.WithHttpLoader(configure: opts =>
{
    opts.Timeout = TimeSpan.FromMinutes(1);
    opts.MaxResourceSize = 20 * 1024 * 1024;
});
```

## Data Types (TemplateValue)

AOT-compatible, no reflection. All are sealed classes with implicit conversions.

| Type | C# Class | Description |
|------|----------|-------------|
| String | StringValue | String value, implicit from `string` |
| Number | NumberValue | Numeric value, implicit from `int` |
| Boolean | BoolValue | Boolean value, implicit from `bool` |
| Null | NullValue | Null sentinel |
| Array | ArrayValue | Implements `IReadOnlyList<TemplateValue>` |
| Object | ObjectValue | Dictionary-like with indexer, `StringComparer.OrdinalIgnoreCase` |
| Bytes | BytesValue | Binary data with optional MIME type |

### Creating Data

```csharp
var data = new ObjectValue
{
    ["title"] = "My Title",           // StringValue (implicit)
    ["count"] = 42,                   // NumberValue (implicit)
    ["active"] = true,                // BoolValue (implicit)
    ["items"] = new ArrayValue(new TemplateValue[]
    {
        new ObjectValue { ["name"] = "Item 1" },
        new ObjectValue { ["name"] = "Item 2" }
    })
};
```

## Code Examples

### Basic Rendering

```csharp
var render = new FlexRenderBuilder()
    .WithBasePath("./templates")
    .WithSkia(skia => skia.WithQr())
    .Build();

var data = new ObjectValue { ["name"] = "World" };
byte[] png = await render.RenderFile("template.yaml", data);
```

### Process Template Expressions

```csharp
var processor = new TemplateProcessor();
var result = processor.Process("Hello {{name}}!", new ObjectValue { ["name"] = "World" });
// result = "Hello World!"
```

### With Custom Limits

```csharp
var render = new FlexRenderBuilder()
    .WithLimits(limits =>
    {
        limits.MaxRenderDepth = 200;
        limits.MaxTemplateFileSize = 2 * 1024 * 1024;
    })
    .WithSkia()
    .Build();
```

## CLI Tool

### Install as dotnet tool

```bash
dotnet tool install -g flexrender-cli
```

After installation the `flexrender` command is available globally:

```bash
flexrender render template.yaml -d data.json -o output.png
flexrender validate template.yaml
flexrender info template.yaml
flexrender watch template.yaml -d data.json -o preview.png
flexrender debug-layout template.yaml -d data.json
```

### Native AOT binary

The CLI is fully AOT-compatible (`IsAotCompatible=true` on all projects, no reflection). Build a standalone native binary (no .NET runtime required):

```bash
dotnet publish src/FlexRender.Cli -c Release -r <RID> /p:PublishAot=true
```

Common RIDs: `osx-arm64`, `osx-x64`, `linux-x64`, `linux-arm64`, `win-x64`. The resulting binary is a single self-contained executable with no external dependencies (except native SkiaSharp libs).

### Run from source (development)

```bash
dotnet run --project src/FlexRender.Cli -- render template.yaml -d data.json -o output.png
```

Global options: `-v`/`--verbose`, `--fonts <dir>`, `--scale <float>`, `-b`/`--backend <skia|imagesharp>`

The `--backend` option selects the rendering backend: `skia` (default, full features including QR, barcode, SVG elements) or `imagesharp` (pure .NET, no native deps, QR/barcode support with `FlexRender.QrCode.ImageSharp.Render` and `FlexRender.Barcode.ImageSharp.Render`, no SVG elements).

The `--scale` option uses invariant culture -- always use `.` as the decimal separator (e.g., `--scale 2.0`).

Working directory matters: CLI resolves all relative paths (template, data, fonts, image src) from the current working directory.

### Distribution channels

| Channel | Install | Requires .NET? | Use case |
|---------|---------|---------------|----------|
| dotnet tool | `dotnet tool install -g flexrender-cli` | Yes | .NET developers |
| GitHub Release | Download binary from Releases | No | Everyone else (CI, Docker, non-.NET) |
| Build from source | `dotnet publish /p:PublishAot=true -r <RID>` | Build-time only | Custom builds |

Native AOT binaries are attached to every GitHub Release for: osx-arm64, linux-x64, win-x64.

## Example Templates

Reference these YAML files for real-world template patterns. Each file is a complete, working template.

### Complete Templates (examples/)

| File | Description | Key Features |
|------|-------------|-------------|
| `examples/receipt.yaml` | Thermal receipt | Basic text, separator, flex row, data binding |
| `examples/receipt-dynamic.yaml` | Receipt with loops | `type: each` iteration, `@index`/`@last` variables |
| `examples/ticket.yaml` | Event ticket | Horizontal layout, QR code, background colors |
| `examples/label.yaml` | Product label | Compact layout, barcode, border-radius |
| `examples/table-invoice.yaml` | Invoice with table | `type: table` element, columns, header styling |
| `examples/expressions-demo.yaml` | Expression showcase | Arithmetic, filters, null coalescing, formatting |
| `examples/visual-effects.yaml` | Visual effects | Gradients, box-shadow, opacity, border-radius |
| `examples/svg-icons.yaml` | SVG icons | Inline SVG elements, vector shapes |
| `examples/showcase.yaml` | Full feature showcase | All element types, 14 sections, HTTP images |
| `examples/showcase-capabilities.yaml` | Renderer comparison | Conditional rendering per backend (`type: if` with `renderer`) |
| `examples/showcase-all-features.yaml` | All features showcase | Every supported feature in one template |
| `examples/markdown-content.yaml` | Markdown content demo | `type: content` with `format: markdown`, dynamic body |
| `examples/html-content.yaml` | HTML content demo | `type: content` with `format: html`, inline styles |

### Cookbook (docs/wiki/Cookbook.md)

9 practical recipes for common use cases:
- Simple receipt, dynamic receipt with loops, table invoice
- NDC ATM receipt (binary content parsing)
- Receipt with QR code, shipping label, event ticket
- Conditional content, multi-language template

Each recipe is a complete, copy-paste-ready YAML template with sample JSON data.

### Per-Feature Examples (examples/visual-docs/)

Minimal, focused templates -- one feature per file:

| Category | Files | What They Show |
|----------|-------|----------------|
| `text/` | align, wrap, maxLines, lineHeight | Text alignment, wrapping, truncation |
| `justify/` | start, end, center, space-between, space-around, space-evenly | Flex justify-content modes |
| `align/` | start, end, center, stretch, baseline | Flex align-items modes |
| `direction/` | row, column, row-reverse, column-reverse, rtl-* | Flex direction + RTL |
| `wrap/` | wrap, nowrap, wrap-reverse | Flex wrapping behavior |
| `image/` | contain, cover, fill, none | Image fit modes |
| `position/` | absolute-*, relative-offset, overlay, badge, floating-label | CSS-style positioning |
| `border/` | solid, styles, per-side, radius | Border rendering |
| `separator/` | styles, thickness, orientation | Separator element options |
| `canvas/` | fixed-*, background, rotate-* | Canvas settings |
| `qr/` | colors, errorCorrection | QR code options |
| `barcode/` | colors, showText | Barcode options |
| `order/` | basic, negative | Flex item ordering |

### Renderer-Specific Projects (examples/*RenderExample/)

| Project | Backend | Shows |
|---------|---------|-------|
| `examples/SkiaRenderExample/` | Skia | Receipt with QR + barcode, `FlexRenderBuilder` setup |
| `examples/ImageSharpRenderExample/` | ImageSharp | Product label, pure .NET rendering |
| `examples/SvgRenderExample/` | SVG | Business card, vector output |

### Data Files

Most templates accept a JSON data file via `-d` flag. Example data files:

| Template | Data File |
|----------|-----------|
| `examples/showcase.yaml` | `examples/showcase-data.json` |
| `examples/showcase-capabilities.yaml` | `examples/showcase-capabilities-skia.json` (or `-imagesharp`, `-svg`) |
| `examples/showcase-all-features.yaml` | `examples/showcase-all-features-data.json` |

Templates without a listed data file use inline data or have no dynamic content.

## Coding Conventions

- **.NET 10**, C# latest, `Nullable=enable`, `TreatWarningsAsErrors=true`
- **AOT compatible** -- `IsAotCompatible=true` on library and CLI. No reflection anywhere. Use pattern matching (`switch` on concrete types) for type dispatch
- **`GeneratedRegex`** -- source-generated regex for AOT compatibility
- **`sealed` classes** -- all leaf/value/concrete classes must be `sealed`
- **`sealed record`** -- for token types and small immutable data
- **`readonly record struct`** -- for small value types (`IntrinsicSize`, `LayoutRect`, `PaddingValues`)
- **File-scoped namespaces** -- `namespace Foo.Bar;`
- **XML documentation** -- `<summary>`, `<param>`, `<returns>`, `<exception>` on all public APIs
- **Guard clauses** -- `ArgumentNullException.ThrowIfNull()`, `ArgumentException.ThrowIfNullOrWhiteSpace()`, `ObjectDisposedException.ThrowIf()`
- **Immutability** -- value types are `readonly`, collections exposed as `IReadOnlyList<T>`
- **Thread safety** -- `ConcurrentDictionary` where concurrent access is expected (e.g., `FontManager`)
- **String comparison** -- `StringComparer.OrdinalIgnoreCase` for dictionaries keyed by names
- **Switch-based dispatch** -- element type dispatch uses `switch` on concrete types, not base class properties

## Test Conventions

- **Framework**: xUnit with `[Fact]` and `[Theory]`/`[InlineData]`
- **Assertions**: `Assert.*` from xUnit; `FluentAssertions` in some tests
- **Naming**: `MethodUnderTest_Scenario_ExpectedResult` (e.g., `Parse_SimpleTextElement_ParsesCorrectly`)
- **Class naming**: `{ClassName}Tests`
- **Organization**: Mirrors source structure -- `Tests/Values/`, `Tests/Layout/`, `Tests/Parsing/`, etc.
- **Snapshot testing**: `SnapshotTestBase` with golden images in `golden/`. Pixel-by-pixel comparison with `colorThreshold` and `maxDifferencePercent` (0.0 = exact match). Set `UPDATE_SNAPSHOTS=true` to regenerate
- **Pattern**: Arrange-Act-Assert

```bash
dotnet test                           # Run all tests
dotnet test --filter "ClassName"      # Filter by test class
dotnet test --filter "MethodName"     # Filter by test method
UPDATE_SNAPSHOTS=true dotnet test     # Regenerate golden snapshots
```

## Git Conventions

Conventional Commits: `type(scope): description`

- **Types**: `feat`, `fix`, `refactor`, `build`, `test`, `docs`, `chore`
- **Scopes** (optional): `parser`, `layout`, `renderer`, `ast`, `examples`, `cli`
- **Description**: lowercase, imperative mood

## Important Patterns

- **TextMeasurer delegate** -- `Func<TextElement, float, float, LayoutSize>?` on `LayoutEngine` (element, fontSize, maxWidth), wired up by `SkiaRenderer` for content-based text sizing with wrap-aware height measurement
- **Content providers** -- `IContentProvider<TElement,TOutput>` returns rendered content for QR, barcode, image elements
- **Resource loader chain** -- `IResourceLoader` with `CanHandle()`, `Load()`, `Priority` -- chain of responsibility pattern
- **Flex-item properties** -- declared per concrete element class, dispatched via `switch` pattern matching (not on base class)
- **Template processing layers** -- AST-level (`TemplateExpander` for `type: each`/`type: if`) and inline (`TemplateProcessor` for `{{variable}}`)

## How to Add a New Element Type

1. Create sealed AST class in `Parsing/Ast/` extending `TemplateElement`, add to `ElementType` enum
2. Add parser function in `TemplateParser.cs` -- register in `_elementParsers` dictionary
3. Add flex-item property support via `switch` pattern matching in layout engine
4. Add rendering in `SkiaRenderer.RenderNode()` or create a provider implementing `IContentProvider<T,O>`
5. Write tests for each step following TDD approach

## How to Add a New Template Expression

1. Add token type as `sealed record` in `ExpressionToken.cs`
2. Add lexer support in `ExpressionLexer.cs`
3. Add evaluation in `TemplateProcessor.cs`
4. Write tests

## How to Add a New Barcode Format

1. Add format to `BarcodeFormat` enum in `Parsing/Ast/BarcodeElement.cs`
2. Add parsing case in `TemplateParser.ParseBarcodeElement()`
3. Add generation in `BarcodeProvider`
4. Write tests