Define LayoutTree vocabulary and enhance documentation and tests

.cspell.yaml

@@ -65,6 +65,34 @@ words:
   - versionmark
   - Weasyprint
   - yamlfix
+  - LayoutBadge
+  - LayoutBand
+  - LayoutLifeline
+  - LayoutActivation
+  - LayoutGrid
+  - LayoutCompartment
+  - ArrowheadStyle
+  - BandOrientation
+  - BadgeShape
+  - PortSide
+  - FontDescriptor
+  - DepthFillColors
+  - LineCornerRadius
+  - LabelPadding
+  - CentreX
+  - CentreY
+  - ColSpan
+  - DiagramRenderer
+  - ILayoutStrategy
+  - RenderOutput
+  - DepthLimit
+  - waypoints
+  - arrowhead
+  - pseudostate
+  - pseudostates
+  - renderable
+  - Segoe
+  - colour
 
 # Exclude common build artifacts, dependencies, and vendored third-party code
 ignorePaths:

.reviewmark.yaml

@@ -242,6 +242,46 @@ reviews:
       - "test/DemaConsulting.SysML2Tools.Tests/Semantic/SemanticOmgModelsTests.cs"
       - "test/SysMLModels/software-structure.sysml"
 
+  - id: SysML2Tools-Core-Layout-Design
+    title: Review that DemaConsulting.SysML2Tools Layout Design is Consistent and Complete
+    context:
+      - docs/reqstream/sysml2-tools-core.yaml
+      - docs/reqstream/sysml2-tools-core/layout.yaml
+    paths:
+      - "docs/design/introduction.md"
+      - "docs/design/sysml2-tools-core.md"
+      - "docs/design/sysml2-tools-core/layout.md"
+
+  - id: SysML2Tools-Core-Layout-Verification
+    title: Review that DemaConsulting.SysML2Tools Layout Verification is Consistent and Complete
+    context:
+      - docs/reqstream/sysml2-tools-core.yaml
+      - docs/reqstream/sysml2-tools-core/layout.yaml
+    paths:
+      - "docs/verification/introduction.md"
+      - "docs/verification/sysml2-tools-core.md"
+      - "docs/verification/sysml2-tools-core/layout.md"
+
+  - id: SysML2Tools-Core-Rendering-Design
+    title: Review that DemaConsulting.SysML2Tools Rendering Design is Consistent and Complete
+    context:
+      - docs/reqstream/sysml2-tools-core.yaml
+      - docs/reqstream/sysml2-tools-core/rendering.yaml
+    paths:
+      - "docs/design/introduction.md"
+      - "docs/design/sysml2-tools-core.md"
+      - "docs/design/sysml2-tools-core/rendering.md"
+
+  - id: SysML2Tools-Core-Rendering-Verification
+    title: Review that DemaConsulting.SysML2Tools Rendering Verification is Consistent and Complete
+    context:
+      - docs/reqstream/sysml2-tools-core.yaml
+      - docs/reqstream/sysml2-tools-core/rendering.yaml
+    paths:
+      - "docs/verification/introduction.md"
+      - "docs/verification/sysml2-tools-core.md"
+      - "docs/verification/sysml2-tools-core/rendering.md"
+
   # SysML2Tools SVG Renderer
   - id: SysML2Tools-Svg-Architecture
     title: Review that DemaConsulting.SysML2Tools.Svg Architecture Satisfies Requirements

docs/design/introduction.md

@@ -45,6 +45,8 @@ system, subsystem, and unit levels:
       - **SymbolTable** (Unit) — registry mapping qualified names to declaration nodes
       - **ReferenceResolver** (Unit) — resolves supertype references; detects circular imports
       - **SupertypeWalker** (Unit) — walks specialization chains; detects cyclic specialization
+  - **Layout** (Subsystem) — LayoutTree intermediate representation: nine node types covering all SysML diagram elements
+  - **Rendering** (Subsystem) — rendering pipeline interfaces: IRenderer, ILayoutStrategy, Theme, RenderOptions, DiagramRenderer
 - **DemaConsulting.SysML2Tools.Svg** (System) — SVG renderer: renders `LayoutTree` to
   SVG output with zero external dependencies
   - TODO: subsystems and units to be defined in Phase 4+
@@ -87,9 +89,11 @@ reviewers an explicit navigation aid from design to code:
 - **src/** — source projects
   - **DemaConsulting.SysML2Tools/** — core library
     - **Grammar/** — ANTLR4 grammar files (hand-maintained; see Grammar/README.md)
+    - **Layout/** — LayoutTree intermediate representation (Phase 3+)
     - **Parser/** — SysML v2 parsing subsystem
       - **Antlr/** — ANTLR4-generated C# (committed; not hand-written)
       - **Internal/** — internal implementation (SysmlDiagnosticListener, StdlibLoader)
+    - **Rendering/** — rendering interfaces and theme (Phase 3+)
     - **Stdlib/** — embedded SysML v2 standard library files (EPL-2.0; see Stdlib/README.md)
   - **DemaConsulting.SysML2Tools.Svg/** — SVG renderer (Phase 0: stub)
   - **DemaConsulting.SysML2Tools.Png/** — PNG renderer (Phase 0: stub)

docs/design/sysml2-tools-core.md

@@ -15,6 +15,12 @@ internal subsystem with `AstBuilder`, `SymbolTable`, `ReferenceResolver`, and `S
 Supporting data types (`DiagnosticSeverity`, `SysmlDiagnostic`, `WorkspaceParseResult`,
 `SysmlLoadResult`, `SysmlWorkspace`) are declared at the appropriate namespace levels.
 
+Phase 3 adds two further subsystems: **Layout** and **Rendering**. The Layout subsystem defines
+the `LayoutTree` intermediate representation consumed by renderers — nine immutable node record
+types covering all SysML diagram elements. The Rendering subsystem defines the interfaces and
+data types that form the rendering pipeline: `IRenderer`, `ILayoutStrategy`, `Theme`,
+`RenderOptions`, `RenderOutput`, and `DiagramRenderer`.
+
 ```mermaid
 flowchart TD
     subgraph Parser
@@ -29,13 +35,29 @@ flowchart TD
         ReferenceResolver
         SupertypeWalker
     end
+    subgraph Layout
+        LayoutTree
+        LayoutNode
+    end
+    subgraph Rendering
+        DiagramRenderer
+        ILayoutStrategy
+        IRenderer
+        Theme
+        RenderOptions
+    end
     WorkspaceParser --> StdlibLoader
     WorkspaceParser --> SysmlDiagnosticListener
     WorkspaceLoader --> WorkspaceParser
     WorkspaceLoader --> AstBuilder
     WorkspaceLoader --> SymbolTable
     WorkspaceLoader --> ReferenceResolver
     WorkspaceLoader --> SupertypeWalker
+    DiagramRenderer --> ILayoutStrategy
+    DiagramRenderer --> IRenderer
+    ILayoutStrategy --> LayoutTree
+    IRenderer --> LayoutTree
+    DiagramRenderer --> WorkspaceLoader
 ```
 
 ## External Interfaces
@@ -101,6 +123,35 @@ file path.
 - *Contract*: Exposes `IReadOnlyList<string> Files` and
   `IReadOnlyDictionary<string, object> Declarations`.
 
+**IRenderer**: Low-level renderer interface (Phase 3+).
+
+- *Type*: Interface.
+- *Role*: Consumer.
+- *Contract*: `string MediaType { get; }`, `string DefaultExtension { get; }`,
+  `void Render(LayoutTree layout, RenderOptions options, Stream output)`.
+  Implementations must be pure and stateless.
+
+**ILayoutStrategy**: Layout computation interface (Phase 3+).
+
+- *Type*: Interface.
+- *Role*: Provider.
+- *Contract*: `LayoutTree BuildLayout(ViewContext context, RenderOptions options)`.
+
+**LayoutTree**: Intermediate representation for one rendered diagram view (Phase 3+).
+
+- *Type*: Sealed record.
+- *Role*: Data container.
+- *Contract*: `double Width`, `double Height`, `IReadOnlyList<LayoutNode> Nodes`.
+  All coordinates are absolute; origin is top-left.
+
+**Theme**: Visual rendering configuration (Phase 3+).
+
+- *Type*: Sealed record.
+- *Role*: Configuration.
+- *Contract*: `DepthFillColors`, `StrokeColor`, `StrokeWidth`, `LineCornerRadius`,
+  `FontSizeTitle`, `FontSizeBody`, `LabelPadding`, `Font`. Three built-in instances are
+  provided by `Themes.Light`, `Themes.Dark`, and `Themes.Print`.
+
 ## Dependencies
 
 - **Antlr4.Runtime.Standard** — ANTLR4 C# runtime; provides `AntlrInputStream`,
@@ -156,6 +207,24 @@ N/A — not a safety-classified software item.
 6. A `SysmlWorkspace` is constructed from the loaded file list and symbol table, and wrapped
    in a `SysmlLoadResult` with all accumulated diagnostics.
 
+### Layout and Rendering Data Flow
+
+1. `DiagramRenderer.RenderWorkspace` receives a `SysmlWorkspace`, an `IRenderer`, and
+   `RenderOptions`. For each view declared in the workspace it constructs a `ViewContext`
+   containing the view name and workspace reference.
+2. `ILayoutStrategy.BuildLayout` is called with the `ViewContext` and `RenderOptions`. The
+   strategy places all nodes with absolute coordinates, routes all lines using A* path-finding
+   with even waypoint spacing, and returns a fully resolved `LayoutTree`.
+3. `IRenderer.Render` is called with the `LayoutTree`, `RenderOptions`, and a fresh output
+   `Stream`. The renderer reads each `LayoutNode` in the tree, translates it to output-format
+   primitives, and writes bytes to the stream.
+4. Fill colors for `LayoutBox` nodes are derived by the renderer as
+   `Theme.DepthFillColors[box.Depth % theme.DepthFillColors.Count]`.
+5. Corner rounding for `LayoutLine` elbows is applied by the renderer using
+   `Theme.LineCornerRadius`; `0.0` produces sharp corners.
+6. Each rendered stream is wrapped in a `RenderOutput` with `SuggestedFileName` derived from
+   the view name and `IRenderer.DefaultExtension`.
+
 ## Design Constraints
 
 - Platform: multi-targets net8.0, net9.0, and net10.0 on Windows, Linux, and macOS.