Implement auto-layout algorithm and restructure gallery documentation

.cspell.yaml

@@ -73,6 +73,9 @@ words:
   - collinearity
   - collinearly
   - pathfinding
+  - transversal
+  - transversally
+  - unwidened
   # Non-ASCII terms retained verbatim in extracted source comments
   - façade
   - Köpf

.reviewmark.yaml

@@ -381,6 +381,36 @@ reviews:
       - "docs/reqstream/rendering-layout/engine/engine.yaml"
       - "docs/design/rendering-layout/connector-router.md"
 
+  - id: Rendering-Layout-Engine-LayoutTreePacker
+    title: Review that Rendering Layout Engine LayoutTreePacker Implementation is Correct
+    paths:
+      - "docs/reqstream/rendering-layout/engine/layout-tree-packer.yaml"
+      - "docs/design/rendering-layout/engine/layout-tree-packer.md"
+      - "docs/verification/rendering-layout/engine/layout-tree-packer.md"
+      - "src/DemaConsulting.Rendering.Layout/Engine/LayoutTreePacker.cs"
+      - "test/DemaConsulting.Rendering.Layout.Tests/Engine/LayoutTreePackerTests.cs"
+    context:
+      - "docs/design/rendering-layout.md"
+      - "docs/design/rendering-layout/engine/engine.md"
+      - "docs/reqstream/rendering-layout.yaml"
+      - "docs/reqstream/rendering-layout/engine/engine.yaml"
+
+  - id: Rendering-Layout-Engine-EdgeCountGapWidener
+    title: Review that Rendering Layout Engine EdgeCountGapWidener Implementation is Correct
+    paths:
+      - "docs/reqstream/rendering-layout/engine/edge-count-gap-widener.yaml"
+      - "docs/design/rendering-layout/engine/edge-count-gap-widener.md"
+      - "docs/verification/rendering-layout/engine/edge-count-gap-widener.md"
+      - "src/DemaConsulting.Rendering.Layout/Engine/EdgeCountGapWidener.cs"
+      - "test/DemaConsulting.Rendering.Layout.Tests/Engine/EdgeCountGapWidenerTests.cs"
+    context:
+      - "docs/design/rendering-layout.md"
+      - "docs/design/rendering-layout/engine/engine.md"
+      - "docs/design/rendering-layout/engine/containment-packer.md"
+      - "docs/design/rendering-layout/hierarchical-layout-algorithm.md"
+      - "docs/reqstream/rendering-layout.yaml"
+      - "docs/reqstream/rendering-layout/engine/engine.yaml"
+
   # Rendering.Layout system-level units
   - id: Rendering-Layout-LayeredLayoutAlgorithm
     title: Review that Rendering Layout LayeredLayoutAlgorithm Implementation is Correct
@@ -469,6 +499,19 @@ reviews:
       - "docs/design/rendering-layout.md"
       - "docs/reqstream/rendering-layout.yaml"
 
+  - id: Rendering-Layout-AutoLayoutAlgorithm
+    title: Review that Rendering Layout AutoLayoutAlgorithm Implementation is Correct
+    paths:
+      - "docs/reqstream/rendering-layout/auto-layout-algorithm.yaml"
+      - "docs/design/rendering-layout/auto-layout-algorithm.md"
+      - "docs/verification/rendering-layout/auto-layout-algorithm.md"
+      - "src/DemaConsulting.Rendering.Layout/AutoLayoutAlgorithm.cs"
+      - "test/DemaConsulting.Rendering.Layout.Tests/AutoLayoutAlgorithmTests.cs"
+    context:
+      - "docs/design/rendering-layout.md"
+      - "docs/reqstream/rendering-layout.yaml"
+      - "docs/design/rendering-layout/engine/layout-tree-packer.md"
+
   # =====================================================================
   # Rendering.Svg system
   # =====================================================================

README.md

@@ -16,9 +16,9 @@ extensible property system, and new algorithms, renderers, and options are added
 
 ## Features
 
-- **Pluggable layout algorithms** — layered (Sugiyama-style), containment packing, and a recursive
-  hierarchical engine for compound (nested-container) graphs, each selected through the open property
-  system.
+- **Pluggable layout algorithms** — layered (Sugiyama-style), containment packing, a recursive
+  hierarchical engine for compound (nested-container) graphs, and an auto-routing meta-algorithm that
+  picks the best fit per connected component, each selected through the open property system.
 - **Orthogonal edge routing** — axis-aligned connectors in all four flow directions, with obstacle
   avoidance around intervening containers.
 - **Named ports** — first-class, labelled attachment points on a node's boundary, including parallel
@@ -29,6 +29,28 @@ extensible property system, and new algorithms, renderers, and options are added
 - **Multiple output formats** — SVG (zero external dependencies) plus PNG, JPEG, and WEBP via
   SkiaSharp, with light, dark, and print themes.
 
+## Algorithm capabilities
+
+The four bundled layout algorithms cover different concerns; pick `auto` when a diagram's shape is
+not known in advance, or select a leaf algorithm directly when it is. `auto` delegates every concern
+to whichever leaf algorithm it routes a component to, so its result is only as good as that leaf's own
+support for the row.
+
+| Concern | `layered` | `containment` | `hierarchical` | `auto` |
+| --- | --- | --- | --- | --- |
+| Horizontal gap widening by edge count | Yes | Yes | Yes | Delegates |
+| Vertical gap widening by edge count | Partial | No | No | Delegates |
+| Container auto-expansion | N/A | N/A | Yes | Delegates |
+| Port/label space reservation | Yes | No | Yes | Delegates |
+| Direction/orientation support | Yes | No | Yes | Delegates |
+| Connectivity/component awareness | Yes | No | Yes | Delegates |
+| Aspect-ratio/canvas-shape targeting | Partial | Yes | Partial | Delegates |
+| Nested/recursive containment handling | No | No | Yes | Delegates |
+
+See the [user guide][link-user-guide] for the full capability matrix with one-line reasons per cell,
+the `auto` delegation caveats, and guidance on when to call a specific algorithm directly instead of
+`auto`.
+
 ## Packages
 
 The library is split into focused packages so consumers take only what they need:

ROADMAP.md

@@ -527,7 +527,8 @@ same-face crowding (no port-spacing-by-width work):
   outward and inward faces of the same boundary point, respectively.
 
 - The gallery entry must be wired into `GalleryCatalog`/`GalleryIndex` like existing examples, so
-  it renders via `gallery.ps1` and appears in `docs/gallery/README.md`.
+  it renders via `gallery.ps1` and appears in the appropriate group's `docs/gallery/<group>/README.md`
+  page (or the top-level `docs/gallery/README.md` index if a new group is warranted).
 
 ## Unify all text rendering onto a single `LayoutLabel`/`LayoutText` primitive
 

docs/design/introduction.md

@@ -33,7 +33,7 @@ software items:
   notation-geometry helpers.
 - **Rendering.Layout (System)** — the pluggable layout algorithms and the reusable geometric
   engines they are built from: the ELK-style layered pipeline plus the bundled `layered`,
-  `containment`, and `hierarchical` algorithms, orthogonal connector routing, and the default
+  `containment`, `hierarchical`, and `auto` algorithms, orthogonal connector routing, and the default
   layout facade.
 - **Rendering.Svg (System)** — the SVG renderer.
 - **Rendering.Skia (System)** — the SkiaSharp raster renderers (PNG, JPEG, and WEBP).
@@ -86,8 +86,8 @@ understand, so unknown or not-yet-honored properties default harmlessly. New dia
 and output formats are introduced additively by implementing `ILayoutAlgorithm` or `IRenderer`
 and registering them — no existing contract changes.
 
-The delivered subset implements the `layered`, `containment`, and `hierarchical` algorithms and the
-SVG and SkiaSharp (PNG, JPEG, WEBP) renderers.
+The delivered subset implements the `layered`, `containment`, `hierarchical`, and `auto` algorithms and
+the SVG and SkiaSharp (PNG, JPEG, WEBP) renderers.
 
 ## Software Structure
 
@@ -114,10 +114,13 @@ Rendering.Layout (System)
 │   ├── OrthogonalEdgeRouter (Unit)       — orthogonal (channel) edge router
 │   ├── ContainmentPacker (Unit)          — shelf packer for grouped/containment layout
 │   ├── InterconnectionLayoutEngine (Unit)— cross-edge routing among placed boxes
-│   └── LayeredPipeline (Unit)            — the ELK-style layered Sugiyama stage pipeline
+│   ├── LayeredPipeline (Unit)            — the ELK-style layered Sugiyama stage pipeline
+│   ├── LayoutTreePacker (Unit)           — shelf packer merging multiple placed LayoutTrees
+│   └── EdgeCountGapWidener (Unit)        — shared edge-count-to-gap corridor-width formula
 ├── LayeredLayoutAlgorithm (Unit)        — the public layered ILayoutAlgorithm
 ├── ContainmentLayoutAlgorithm (Unit)    — the public containment ILayoutAlgorithm
 ├── HierarchicalLayoutAlgorithm (Unit)   — the recursive hierarchical engine
+├── AutoLayoutAlgorithm (Unit)           — the auto-routing meta-algorithm
 ├── ContainmentLayout (Unit)             — public containment packing entry point
 ├── ConnectorRouter (Unit)              — public edge-routing orchestration
 ├── EdgeRoutingOption (Unit)            — the EdgeRouting option realization

docs/design/ots.md

@@ -9,7 +9,7 @@ package.
 
 ## OTS Items
 
-The repository integrates twelve OTS items:
+The repository integrates eleven OTS items:
 
 ```text
 OTS Software Items
@@ -20,7 +20,6 @@ OTS Software Items
 ├── ReviewMark   — file-review plan, report, and enforcement
 ├── SarifMark    — CodeQL SARIF-to-Markdown conversion
 ├── SkiaSharp          — raster graphics library (bitmap drawing and PNG/JPEG/WEBP encoding)
-├── SonarScanner for .NET — SonarCloud static-analysis scanner wrapper
 ├── SonarMark          — SonarCloud quality-report generation
 ├── VersionMark  — tool-version capture and publishing
 ├── WeasyPrint   — HTML-to-PDF (PDF/A) conversion

docs/design/rendering-layout.md

@@ -5,8 +5,8 @@
 `DemaConsulting.Rendering.Layout` is the placement system for the Rendering stack. A caller supplies a
 `LayoutGraph` plus `LayoutOptions`; the system returns a placed `LayoutTree` of boxes and orthogonally
 routed connectors that downstream renderers can draw without layout knowledge. The system exposes
-bundled algorithms for layered, containment, and hierarchical layout, built on reusable geometric
-engines.
+bundled algorithms for layered, containment, hierarchical, and auto (meta-algorithm) layout, built on
+reusable geometric engines.
 
 The system is composed of one subsystem and a set of public algorithm and facade units:
 
@@ -16,19 +16,21 @@ DemaConsulting.Rendering.Layout (System)
 │   ├── OrthogonalEdgeRouter (Unit)
 │   ├── ContainmentPacker (Unit)
 │   ├── InterconnectionLayoutEngine (Unit)
-│   └── LayeredPipeline (Unit)
+│   ├── LayeredPipeline (Unit)
+│   └── LayoutTreePacker (Unit)
 ├── EdgeRoutingOption (Unit)
 ├── ConnectorRouter (Unit)
 ├── ContainmentLayout (Unit)
 ├── ContainmentLayoutAlgorithm (Unit)
 ├── HierarchicalLayoutAlgorithm (Unit)
 ├── DefaultLayout (Unit)
-└── LayeredLayoutAlgorithm (Unit)
+├── LayeredLayoutAlgorithm (Unit)
+└── AutoLayoutAlgorithm (Unit)
 ```
 
 - **Engine** — reusable, model-agnostic geometric engines (orthogonal routing, containment packing,
-  interconnection placement, and the ELK-style layered stage pipeline). Detailed in Engine Subsystem
-  Design.
+  interconnection placement, the ELK-style layered stage pipeline, and layout-tree packing). Detailed
+  in Engine Subsystem Design.
 - **EdgeRoutingOption** — routing-style configuration keys. Detailed in EdgeRoutingOption Unit Design.
 - **ConnectorRouter** — routes connectors among already placed boxes. Detailed in ConnectorRouter Unit
   Design.
@@ -42,24 +44,29 @@ DemaConsulting.Rendering.Layout (System)
   Design.
 - **LayeredLayoutAlgorithm** — public layered algorithm. Detailed in LayeredLayoutAlgorithm Unit
   Design.
+- **AutoLayoutAlgorithm** — public auto-routing meta-algorithm that splits a graph into connected
+  components, routes each to whichever bundled leaf algorithm best suits its shape, and packs the
+  results into one combined tree. Detailed in AutoLayoutAlgorithm Unit Design.
 
 The public algorithms implement `ILayoutAlgorithm` from Rendering.Abstractions and compose the Engine
 subsystem's model-agnostic geometry. The `DefaultLayout` facade resolves the requested algorithm from
 the bundled registry. The hierarchical algorithm composes leaf algorithms per container and routes
-cross-container edges at the owning scope.
+cross-container edges at the owning scope. The auto algorithm composes the other three bundled
+algorithms per connected component and packs their independently-placed results with `LayoutTreePacker`.
 
 ## External Interfaces
 
 - **`ILayoutAlgorithm` implementations** — outbound; `LayeredLayoutAlgorithm`,
-  `ContainmentLayoutAlgorithm`, and `HierarchicalLayoutAlgorithm` each realize the Abstractions layout
-  contract, accepting a `LayoutGraph` plus `LayoutOptions` and returning a placed `LayoutTree`. Each
-  advertises an identifier (`layered`, `containment`, `hierarchical`) for registry resolution.
+  `ContainmentLayoutAlgorithm`, `HierarchicalLayoutAlgorithm`, and `AutoLayoutAlgorithm` each realize
+  the Abstractions layout contract, accepting a `LayoutGraph` plus `LayoutOptions` and returning a
+  placed `LayoutTree`. Each advertises an identifier (`layered`, `containment`, `hierarchical`,
+  `auto`) for registry resolution.
 - **`LayoutEngine` facade / bundled registry (DefaultLayout)** — outbound entry points; resolve and run
   the requested (or default) algorithm.
 - **`EdgeRoutingOption`** — outbound `LayoutProperty` keys that select connector routing style.
 - **Engine APIs (`OrthogonalEdgeRouter`, `ContainmentPacker`, `InterconnectionLayoutEngine`,
-  `LayeredPipeline`)** — internal geometric services composed by the public algorithms; not intended
-  for direct renderer use.
+  `LayeredPipeline`, `LayoutTreePacker`)** — internal geometric services composed by the public
+  algorithms; not intended for direct renderer use.
 
 ## Dependencies
 
@@ -80,7 +87,7 @@ architectural segregation (IEC 62304 §5.3.3).
 ```text
 LayoutGraph + LayoutOptions
         │
-        ▼  selected ILayoutAlgorithm (layered / containment / hierarchical)
+        ▼  selected ILayoutAlgorithm (layered / containment / hierarchical / auto)
    Engine geometry (layered pipeline, packing, routing)
         │
         ▼