feat: implement full CSS flexbox specification (Phases 0-3)

Two-pass layout engine with iterative freeze algorithm inspired by
Facebook Yoga. Consolidate flex item properties into TemplateElement
base class, add flex-wrap with greedy line-breaking, per-line flex
resolution, align-content distribution (7 modes), and wrap-reverse.

Phases implemented:
- Phase 0-1: Foundation (flex properties on base class, align-self,
  display:none, direction reverse, non-uniform padding/margin)
- Phase 2: Core flexbox (iterative freeze, flex-basis with min/max
  clamping, factor flooring, shrink scaled by basis, overflow
  fallback, justify-content SpaceEvenly, SkiaRenderer align support)
- Phase 3: Wrapping (flex-wrap, CalculateFlexLines, ResolveFlexForLine,
  LayoutWrappedFlex, align-content with overflow fallback,
  wrap-reverse, row-gap/column-gap, MaxFlexLines resource limit)

All 1151 tests pass on both net8.0 and net10.0.

docs: add flexbox expansion documentation and improve Linux/Docker visibility

Add comprehensive documentation for the flexbox expansion project:
- Implementation plan, algorithm reviews, test fixtures, architecture
  reviews, and Yoga comparison review (20 docs, ~380KB)
- API reference for all flexbox properties (1152 lines)

Improve SkiaSharp Linux/Docker discoverability:
- Add prominent [!IMPORTANT] callout in README after install command
- Add Linux note to NuGet package descriptions (Skia + MetaPackage)
- Add Linux/Docker warning to llms.txt and llms-full.txt
- Add MaxFlexLines to AGENTS.md resource limits table

feat: implement CSS positioning, overflow, aspect-ratio, and auto margins (Phases 4-5)

Phase 4 — Advanced Features:
- Position absolute: excluded from flex flow, inset-based positioning and sizing
- Position relative: offset from normal flow (left/right/top/bottom with CSS priority)
- Overflow:hidden: canvas clipping in SkiaRenderer via Save/ClipRect/Restore
- Aspect ratio: width/height inference when one dimension is known

Phase 5 — Auto Margins:
- MarginValue/MarginValues readonly record structs with auto support
- PaddingParser.ParseMargin for auto token handling in CSS shorthand
- Main axis auto margins consume free space before justify-content
- Cross axis auto margins override align-items (center/push)
- Works for both Row and Column directions

Tests: 1204 total (53 new), 0 failures on net8.0 and net10.0

fix: absolute positioning fallback + aspect-ratio after flex-grow

- Absolute children without insets now respect parent's justify-content
  and align-items instead of defaulting to (0,0)
- Aspect ratio is re-applied after flex-grow/shrink resolution in both
  column and row layouts
- Updated AGENTS.md, llms.txt, llms-full.txt with Phase 4-5 features
- Added final architecture and algorithm review documents
- 1207 tests passing

test: add column-direction tests for absolute positioning and aspect-ratio

Cover column layout paths for absolute justify/align fallback and
aspect-ratio after flex-grow (1210 tests)

fix: cross-axis alignment now subtracts margins in non-wrapped paths

Center/End/Stretch cross-axis alignment formulas in LayoutColumnFlex
and LayoutRowFlex now correctly subtract margins from available space,
matching the wrapped path behavior. Added 6 tests (1216 total).

feat: add configurable BMP color depth with 6 encoding modes

Add BmpColorMode enum with Bgra32 (32-bit), Rgb24 (24-bit), Rgb565
(16-bit), Grayscale8 (8-bit), Grayscale4 (4-bit), and Monochrome1
(1-bit) modes. Each mode produces valid BMP files with proper headers,
color tables, row padding, and sub-byte pixel packing.

Expose --bmp-color CLI option in render and watch commands. Pass color
mode through SkiaRender → SkiaRenderer → BmpEncoder pipeline.

refactor: address code review findings in BmpEncoder

Replace stackalloc with ArrayPool<byte> for row buffers exceeding 1024
bytes to prevent stack overflow on wide images. Add exhaustive default
throws in WritePixelData and WriteColorTable switch statements.
Standardize row buffer clearing with Clear() across all modes. Add
Math.Min clamp to Grayscale8 luminance for defensive correctness.

Author: RoboNET

AGENTS.md

@@ -24,7 +24,7 @@ src/FlexRender.Core/            # Core library (0 external dependencies)
   Abstractions/                 # ILayoutRenderer<T>, ITemplateParser, IResourceLoader
   Configuration/                # ResourceLimits, FlexRenderOptions
   Layout/                       # Two-pass flexbox layout engine (LayoutEngine, LayoutNode, LayoutSize)
-    Units/                      # Unit, UnitParser, PaddingValues, PaddingParser
+    Units/                      # Unit, UnitParser, PaddingValues, PaddingParser, MarginValue, MarginValues
   Loaders/                      # FileResourceLoader, Base64ResourceLoader, EmbeddedResourceLoader
   Parsing/Ast/                  # Template, CanvasSettings, TemplateElement, TextElement, FlexElement, etc.
   TemplateEngine/               # TemplateProcessor, ExpressionLexer, ExpressionEvaluator
@@ -145,7 +145,7 @@ byte[] png = await render.Render(_templates["receipt"], data);
 | Abstractions | `IFlexRender`, `IResourceLoader` |
 | Parsing | `TemplateParser`, `Template`, `CanvasSettings`, `TextElement`, `FlexElement`, `QrElement`, `BarcodeElement`, `ImageElement`, `SeparatorElement`, `EachElement`, `IfElement` |
 | Template Engine | `TemplateExpander`, `TemplateProcessor`, `ExpressionLexer`, `ExpressionEvaluator`, `TemplateContext` |
-| Layout | `LayoutEngine`, `LayoutNode`, `LayoutContext`, `LayoutSize`, `IntrinsicSize`, `Unit`, `UnitParser` |
+| Layout | `LayoutEngine`, `LayoutNode`, `LayoutContext`, `LayoutSize`, `IntrinsicSize`, `Unit`, `UnitParser`, `MarginValue`, `MarginValues`, `PaddingParser.ParseMargin` |
 | Rendering | `SkiaRender` (IFlexRender impl), `SkiaRenderer`, `TextRenderer`, `FontManager`, `ColorParser`, `RotationHelper`, `BmpEncoder` |
 | Providers | `IContentProvider<T,O>`, `QrProvider`, `BarcodeProvider`, `ImageProvider` |
 | Loaders | `FileResourceLoader`, `Base64ResourceLoader`, `EmbeddedResourceLoader`, `HttpResourceLoader` |
@@ -159,7 +159,7 @@ byte[] png = await render.Render(_templates["receipt"], data);
 - **`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`, `FlexItemProperties`)
+- **`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()`
@@ -178,6 +178,7 @@ All security limits are centralized in the `ResourceLimits` class (`Configuratio
 | `MaxTemplateNestingDepth` | 100 | Expression nesting |
 | `MaxRenderDepth` | 100 | Render tree recursion |
 | `MaxImageSize` | 10 MB | Image loading |
+| `MaxFlexLines` | 1000 | Maximum flex lines when wrapping |
 
 Configure limits via builder:
 
@@ -201,6 +202,7 @@ These limits exist to prevent abuse and resource exhaustion. Never remove or wea
 
 ## Test Conventions
 
+- **Total tests**: 1204 (unit + snapshot + integration)
 - **Framework**: xUnit with `[Fact]` and `[Theory]`/`[InlineData]`
 - **Assertions**: `Assert.*` from xUnit; `FluentAssertions` in some tests
 - **Naming**: `MethodUnderTest_Scenario_ExpectedResult` (e.g., `Parse_SimpleTextElement_ParsesCorrectly`)
@@ -364,6 +366,85 @@ var sb = new StringBuilder(estimatedCapacity);
 - **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}}`)
 
+## AST Element Properties
+
+### TemplateElement (base class)
+
+All elements inherit these properties:
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `Rotate` | string | `"none"` | Rotation of the element |
+| `Background` | string? | null | Background color in hex format |
+| `Padding` | string | `"0"` | Padding inside (px, %, em, CSS shorthand) |
+| `Margin` | string | `"0"` | Margin outside (px, %, em, auto, CSS shorthand) |
+| `Display` | Display | `Flex` | Display mode (Flex, None) |
+| `Grow` | float | 0 | Flex grow factor |
+| `Shrink` | float | 1 | Flex shrink factor |
+| `Basis` | string | `"auto"` | Flex basis (px, %, em, auto) |
+| `AlignSelf` | AlignSelf | `Auto` | Self alignment override |
+| `Order` | int | 0 | Display order |
+| `Width` | string? | null | Width (px, %, em, auto) |
+| `Height` | string? | null | Height (px, %, em, auto) |
+| `MinWidth` | string? | null | Minimum width constraint |
+| `MaxWidth` | string? | null | Maximum width constraint |
+| `MinHeight` | string? | null | Minimum height constraint |
+| `MaxHeight` | string? | null | Maximum height constraint |
+| `Position` | Position | `Static` | Positioning mode (Static, Relative, Absolute) |
+| `Top` | string? | null | Top inset for positioned elements |
+| `Right` | string? | null | Right inset for positioned elements |
+| `Bottom` | string? | null | Bottom inset for positioned elements |
+| `Left` | string? | null | Left inset for positioned elements |
+| `AspectRatio` | float? | null | Width/height ratio; when one dimension is known, the other is computed |
+
+### FlexElement (container)
+
+Additional container-only properties:
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `Direction` | FlexDirection | `Column` | Main axis direction |
+| `Wrap` | FlexWrap | `NoWrap` | Whether items wrap to new lines |
+| `Gap` | string | `"0"` | Gap shorthand (sets both row-gap and column-gap) |
+| `ColumnGap` | string? | null | Gap between items along main axis |
+| `RowGap` | string? | null | Gap between wrapped lines |
+| `Justify` | JustifyContent | `Start` | Main axis alignment |
+| `Align` | AlignItems | `Stretch` | Cross axis alignment |
+| `AlignContent` | AlignContent | `Start` | Alignment of wrapped lines (note: CSS default is Stretch) |
+| `Overflow` | Overflow | `Visible` | Content overflow behavior (Visible, Hidden) |
+
+## Layout Enums
+
+All enums in `FlexRender.Layout.FlexEnums`:
+
+| Enum | Values | Description |
+|------|--------|-------------|
+| `FlexDirection` | Row, Column, RowReverse, ColumnReverse | Main axis direction |
+| `FlexWrap` | NoWrap, Wrap, WrapReverse | Line wrapping behavior |
+| `JustifyContent` | Start, Center, End, SpaceBetween, SpaceAround, SpaceEvenly | Main axis alignment |
+| `AlignItems` | Start, Center, End, Stretch, Baseline | Cross axis alignment |
+| `AlignContent` | Start, Center, End, Stretch, SpaceBetween, SpaceAround, SpaceEvenly | Multi-line alignment |
+| `AlignSelf` | Auto, Start, Center, End, Stretch, Baseline | Per-item alignment override |
+| `Display` | Flex, None | Element visibility in layout |
+| `Position` | Static, Relative, Absolute | CSS positioning mode |
+| `Overflow` | Visible, Hidden | Content overflow handling |
+
+## Margin Types
+
+`MarginValue` -- readonly record struct representing a single margin side:
+- `MarginValue.Fixed(float px)` -- fixed pixel value
+- `MarginValue.Auto` -- auto margin that consumes free space
+- `ResolvedPixels` -- resolved value (0 for unresolved auto)
+
+`MarginValues` -- readonly record struct for all four sides:
+- `Top`, `Right`, `Bottom`, `Left` -- individual `MarginValue` sides
+- `HasAuto` -- whether any side is auto
+- `MainAxisAutoCount(bool isColumn)` -- count of auto margins on main axis (0, 1, or 2)
+- `CrossAxisAutoCount(bool isColumn)` -- count of auto margins on cross axis (0, 1, or 2)
+- `MarginValues.Zero` -- all sides zero, no auto
+
+`PaddingParser.ParseMargin(string, float, float)` -- parses CSS margin shorthand with auto support, returns `MarginValues`.
+
 ## Control Flow Elements
 
 ### Each Element (Iteration)

README.md

@@ -60,6 +60,14 @@ The `receipt-dynamic.yaml` demonstrates AST-level control flow with `type: each`
 dotnet add package FlexRender
 ```
 
+> [!IMPORTANT]
+> **Linux / Docker users:** SkiaSharp requires native libraries. Add the native assets package to avoid `DllNotFoundException: libSkiaSharp`:
+> ```bash
+> dotnet add package SkiaSharp.NativeAssets.Linux
+> # For minimal containers without fontconfig/freetype:
+> dotnet add package SkiaSharp.NativeAssets.Linux.NoDependencies
+> ```
+
 ### Individual packages
 
 | Package | Description |
@@ -81,18 +89,6 @@ dotnet add package FlexRender.Yaml
 dotnet add package FlexRender.Skia
 ```
 
-### Linux / Docker
-
-SkiaSharp requires native libraries on Linux. If you get `DllNotFoundException: libSkiaSharp`, add the native assets package:
-
-```bash
-# Standard Linux (requires system fontconfig/freetype)
-dotnet add package SkiaSharp.NativeAssets.Linux
-
-# Minimal containers without system libs
-dotnet add package SkiaSharp.NativeAssets.Linux.NoDependencies
-```
-
 ### CLI tool
 
 ```bash

docs/flexbox-expansion/01-gap-analysis.md

@@ -0,0 +1,96 @@
+# Gap Analysis: FlexRender vs Yoga Layout Engine
+
+## Container Properties
+
+| Property | FlexRender | Yoga | Gap |
+|---|---|---|---|
+| `flex-direction: row` | YES | YES | -- |
+| `flex-direction: column` | YES | YES | -- |
+| `flex-direction: row-reverse` | NO | YES | MISSING |
+| `flex-direction: column-reverse` | NO | YES | MISSING |
+| `flex-wrap: nowrap` | YES (default, only mode) | YES | -- |
+| `flex-wrap: wrap` | ENUM ONLY (not implemented in layout) | YES | MISSING IMPL |
+| `flex-wrap: wrap-reverse` | ENUM ONLY (not implemented) | YES | MISSING IMPL |
+| `justify-content: start` | YES | YES | -- |
+| `justify-content: center` | YES | YES | -- |
+| `justify-content: end` | YES | YES | -- |
+| `justify-content: space-between` | YES | YES | -- |
+| `justify-content: space-around` | YES | YES | -- |
+| `justify-content: space-evenly` | YES | YES | -- |
+| `align-items: start` | YES | YES | -- |
+| `align-items: center` | YES | YES | -- |
+| `align-items: end` | YES | YES | -- |
+| `align-items: stretch` | YES | YES | -- |
+| `align-items: baseline` | ENUM ONLY (not implemented) | YES | MISSING IMPL |
+| `align-content: *` | ENUM ONLY (6 values, none implemented) | YES (7 values incl SpaceEvenly) | MISSING IMPL |
+| `gap` (uniform) | YES | YES | -- |
+| `row-gap` | NO (single gap only) | YES | MISSING |
+| `column-gap` | NO (single gap only) | YES | MISSING |
+
+## Item Properties
+
+| Property | FlexRender | Yoga | Gap |
+|---|---|---|---|
+| `flex-grow` | YES | YES | -- |
+| `flex-shrink` | YES (weighted, NOT scaled by basis) | YES (scaled by basis) | WRONG FORMULA |
+| `flex-basis` | PROP ONLY (not used in layout) | YES | MISSING IMPL |
+| `align-self` | PROP ONLY (not used in layout) | YES | MISSING IMPL |
+| `order` | PROP ONLY (not used in layout) | NO (Yoga does not support) | LOW PRIORITY |
+
+## Sizing Properties
+
+| Property | FlexRender | Yoga | Gap |
+|---|---|---|---|
+| `width` | YES (px, %, em, auto) | YES (px, %, auto) | -- |
+| `height` | YES (px, %, em, auto) | YES (px, %, auto) | -- |
+| `min-width` | NO | YES | MISSING |
+| `max-width` | NO | YES | MISSING |
+| `min-height` | NO | YES | MISSING |
+| `max-height` | NO | YES | MISSING |
+| `aspect-ratio` | NO | YES | MISSING |
+
+## Spacing Properties
+
+| Property | FlexRender | Yoga | Gap |
+|---|---|---|---|
+| `padding` (4-side) | YES (top/right/bottom/left) | YES | -- |
+| `margin` (uniform) | YES (single value) | YES (4-side + auto) | PARTIAL |
+| `margin` (4-side) | NO | YES | MISSING |
+| `margin: auto` | NO | YES | MISSING |
+| `border` (width affecting layout) | NO | YES | MISSING |
+
+## Positioning Properties
+
+| Property | FlexRender | Yoga | Gap |
+|---|---|---|---|
+| `position: relative` | NO | YES | MISSING |
+| `position: absolute` | NO | YES | MISSING |
+| `position: static` | implicit default | YES (default) | -- |
+| `top/right/bottom/left` | NO | YES | MISSING |
+
+## Display & Overflow
+
+| Property | FlexRender | Yoga | Gap |
+|---|---|---|---|
+| `display: flex` | YES (implicit) | YES | -- |
+| `display: none` | NO | YES | MISSING |
+| `overflow: visible` | default behavior | YES | -- |
+| `overflow: hidden` | NO | YES | MISSING |
+
+## Direction
+
+| Property | FlexRender | Yoga | Gap |
+|---|---|---|---|
+| `direction: LTR` | YES (implicit, only mode) | YES | -- |
+| `direction: RTL` | NO | YES | MISSING |
+
+## Yoga Limitations (NOT in CSS spec)
+
+- NO `order` property -- order always determined by document order
+- NO z-index
+- NO visibility (always visible)
+- NO forced breaks
+- Default flexDirection = Column (CSS = Row)
+- Default flexShrink = 0 (CSS = 1)
+- Default alignContent = FlexStart (CSS spec: Stretch)
+- Simplified two-pass flex resolution instead of variable-pass from spec