@peter.prib/renderengine 0.15.1 → 0.15.3

package/documentation/REFERENCE.md

@@ -104,6 +104,31 @@ catalog `key` for you.
 | `wordCloud` | `wordCloud(data, opts)` | `Array<{text: string, value: number}>` | spiral placement + bounding-box collision; `minFontSize`, `maxFontSize`, `padding` |
 | `parallelCoordinates` | `parallelCoordinates(data, opts)` | `Array<{label?, category?, [dim: number]}>` | one vertical axis per numeric dimension; category-driven colors; `dimensions` |
 | `geoMap` | `geoMap(data, opts)` | `{features: Array<{id, name, value?, color?, geometry}>, bubbles?: Array<{lat, lon, value}>}` | equirectangular projection; `center`, `scale`, `colorScale`; see note below |
+| `polarArea` | `polarAreaChart(data, opts)` | `Array<{label, value, exploded?}>` | Nightingale rose equal-angle wedges; `scale: 'radius'|'area'`, `extrude3D`, `depth`, `innerRadiusRatio` |
+| `pie3D` | `pieChart3D(data, opts)` | `Array<{label, value}>` | isometric 3D pie; `depth`, `tilt`, `exploded`, `colors` |
+| `donut3D` | `donutChart3D(data, opts)` | `Array<{label, value}>` | isometric 3D donut; `innerRadiusRatio`, `depth`, `tilt` |
+| `pareto` | `paretoChart(data, opts)` | `Array<{label, value}>` | sorted descending bars with cumulative percentage line (80/20 rule); `barColor`, `lineColor` |
+| `lollipop` | `lollipopChart(data, opts)` | `Array<{label, value}>` | stem with circular point markers; `orientation: 'vertical'|'horizontal'`, `pointRadius` |
+| `marimekko` | `marimekkoChart(data, opts)` | `Array<{name, values: Array<{label, value}>}>` | 2D mosaic chart where both bar width and height encode values |
+| `icicle` | `icicleChart(data, opts)` | `Array<{label, value?, children?}>` | hierarchical partition chart laying out tree levels as rectangular blocks; `orientation` |
+| `dumbbell` | `dumbbellChart(data, opts)` | `Array<{label, start, end}>` or multi-series `Array<{name, values}>` | connected pair of dots showing change across categories; `colorByDelta`, `showDeltas`, `orientation` |
+| `slopegraph` | `slopegraph(data, opts)` | `Array<{label, values: number[]}>` or `Array<{label, start, end}>` | connects categories across stages with direct labels; `stageLabels`, `collisionAvoidance` |
+| `circlePack` | `circlePackChart(data, opts)` | `Array<{label, value?, children?}>` | nested tangent circles sized by value with translucent branch containment; `padding` |
+| `ridgeline` | `ridgelineChart(data, opts)` | `Array<{label, values: number[]}>` | vertically staggered, overlapping Gaussian-KDE density curves (Joy plot); `overlap`, `showMedian` |
+| `beeswarm` | `beeswarmChart(data, opts)` | `Array<{label, values: number[]}>` | packed individual sample points along category slots; `mode: 'beeswarm'|'raincloud'`, `radius` |
+| `combo` | `comboChart(data, opts)` | multi-series with type specifications | composite multi-series chart combining bars, lines, and area layers on primary/secondary axes |
+| `hexbin` | `hexbinChart(data, opts)` | `Array<{x, y, value?}>` or `Array<[x, y]>` | 2D hexagonal density binning for large scatter clouds; `radius`, `minCount`, `colorScale` |
+| `ecdf` | `ecdfChart(data, opts)` | `number[]` or `Array<{label, values: number[]}>` | empirical cumulative distribution step function (0..1); `showMedian`, `showQuantiles`, `step` |
+| `splom` | `scatterMatrixChart(data, opts)` | `Array<object>` with numeric dimensions | scatter plot matrix of pairwise bivariate relationships; `dimensions`, `colorCol` |
+| `sparklineTable` | `sparklineTableChart(data, opts)` | `Array<{label, values: number[], current?, change?}>` | data table with embedded inline trendline sparklines; `columns` |
+| `horizon` | `horizonChart(data, opts)` | `Array<{label, values: number[]}>` | compact layered area strips folding positive and negative magnitude bands; `bands`, `posColors` |
+| `ohlc` | `ohlcChart(data, opts)` | `Array<{label, open, high, low, close}>` | Open-High-Low-Close financial bar chart; `upColor`, `downColor` |
+| `alluvial` | `alluvialDiagram(data, opts)` | `{dimensions: string[], rows: Array<object>}` or `Array<{steps, value}>` | multi-stage categorical flow diagram across ordered dimensions; `nodeWidth`, `curvature` |
+| `renko` | `renkoChart(data, opts)` | `number[]` or `Array<{label, close}>` | brick-based trend-filtering chart filtering out time noise; `brickSize` |
+| `contour` | `contourChart(data, opts)` | `number[][]` (2D scalar grid) or `Array<{x, y, value}>` | marching-squares isolines and filled isoband contours; `levels`, `filled`, `showLines` |
+| `kagi` | `kagiChart(data, opts)` | `number[]` or `Array<{label, close}>` | trend reversal chart with alternating line thickness; `reversalAmount` |
+| `pointAndFigure` | `pointAndFigureChart(data, opts)` | `number[]` or `Array<{label, close}>` | columns of X's (rising) and O's (falling); `boxSize`, `reversal` |
+| `surface3D` | `surfaceChart3D(data, opts)` | `Array<{x, z, value}>` or `{xLabels, zLabels, values}` | continuous 3D surface mesh with gradient height coloring, wireframe, and orbit camera |
 
 **Gauges.** Every gauge is a `GaugeChart` (`src/charting/charts/GaugeChart.js`) and takes the same options:
 
@@ -1340,6 +1365,278 @@ SVG each mark answers a click with `{ label, series }`.
 engine.barChart(data, { onDatumClick: ({ label }) => openDetail(label) });
 ```
 
+## Advanced Statistical, Flow, Distribution & 3D Charts
+
+Specialized charts designed for dense distributions, multi-stage transitions, continuous terrains, and flow modeling.
+
+### Dumbbell / Gap Chart — `dumbbellChart(data, options)`
+
+A connected pair of dots per category showing before/after, actual/target, or interval comparisons without the visual clutter of clustered bars.
+
+- **Data shapes:**
+  - `Array<{label: string, start: number, end: number}>`
+  - Multi-series `Array<{name: string, values: Array<{label: string, value: number}>}>` (first two series used as start and end)
+- **Notable options:**
+  - `orientation`: `'horizontal'` (default) or `'vertical'`.
+  - `colorByDelta`: `true` to color connectors and endpoints by direction of change (green for gain, red for loss).
+  - `startColor`, `endColor`: Custom endpoint colors when `colorByDelta` is false.
+  - `upColor`, `downColor`, `neutralColor`: Colors used when `colorByDelta: true`.
+  - `showDeltas`: `true` to render direct delta badges (e.g. `+12%`, `-5`) next to the endpoints.
+  - `showValues`: `true` to render numeric value labels at dots.
+  - `pointRadius`: Radius of endpoint circles in pixels (default `5`).
+  - `startLabel`, `endLabel`: Custom legend labels for the start and end series.
+
+```javascript
+engine.dumbbellChart([
+    { label: 'Latency', start: 240, end: 110 },
+    { label: 'Throughput', start: 850, end: 1420 },
+    { label: 'Error Rate', start: 4.2, end: 0.8 },
+], { colorByDelta: true, showDeltas: true, showValues: true });
+```
+
+### Slopegraph — `slopegraph(data, options)`
+
+Connects categories across two or more discrete stages or time points to highlight hierarchy shifts, rate-of-change differences, and rank reversals.
+
+- **Data shapes:**
+  - `Array<{label: string, values: number[]}>` (multi-stage trajectory)
+  - `Array<{label: string, start: number, end: number}>` (2-stage before/after)
+- **Notable options:**
+  - `stageLabels`: Array of column headings for the stages (e.g. `['2024', '2025', '2026']`).
+  - `showDirectLabels`: `true` (default) to label line endpoints directly, avoiding an external legend.
+  - `labelSide`: `'both'` (default), `'left'`, or `'right'`.
+  - `collisionAvoidance`: `true` (default) to run iterative vertical relaxation preventing overlapping text labels on crowded axes.
+  - `lineWidth`: Stroke width of trajectory lines (default `2`).
+  - `pointRadius`: Radius of dots at each stage (default `4`).
+  - `highlightOnHover`: `true` (default) to dim competing lines on cursor hover.
+
+```javascript
+engine.slopegraph([
+    { label: 'Product Alpha', values: [12, 19, 28] },
+    { label: 'Product Beta',  values: [24, 21, 15] },
+    { label: 'Product Gamma', values: [8,  14, 22] },
+], { stageLabels: ['Q1', 'Q2', 'Q3'], showDirectLabels: true });
+```
+
+### Ridgeline Plot (Joy Plot) — `ridgelineChart(data, options)`
+
+Vertically staggered, partially overlapping Gaussian kernel density estimates (KDE) across multiple ordered or categorical groups. Ideal for comparing distributions over time or stages in compact vertical space.
+
+- **Data shape:** `Array<{label: string, values: number[]}>` (raw sample observations per group).
+- **Notable options:**
+  - `overlap`: Vertical overlap ratio between adjacent ridges (default `0.65`; `0` = non-overlapping rows, `1.0` = high overlap).
+  - `fillOpacity`: Opacity of the filled ridge area under each density curve (default `0.74`).
+  - `showMedian`: `true` (default) to draw vertical line ticks at each group's sample median.
+  - `medianColor`: Color of the median tick indicator (default `'#ffffff'`).
+  - `colors`: Palette array for ridges, or auto-assigned from workspace theme.
+
+```javascript
+engine.ridgelineChart([
+    { label: 'Sprint 1', values: [14, 18, 22, 25, 27, 28, 30, 35, 42] },
+    { label: 'Sprint 2', values: [10, 12, 15, 18, 20, 22, 24, 26, 29] },
+    { label: 'Sprint 3', values: [8,  9,  11, 14, 16, 17, 18, 20, 22] },
+], { overlap: 0.7, showMedian: true });
+```
+
+### Beeswarm & Raincloud Plot — `beeswarmChart(data, options)`
+
+Plots every individual observation as a non-overlapping circle packed tightly along a category axis without jitter noise. Raincloud mode pairs the packed dot cloud with a half-KDE density violin and a compact box plot.
+
+- **Data shape:** `Array<{label: string, values: number[]}>` (raw sample numbers per group).
+- **Notable options:**
+  - `mode`: `'beeswarm'` (default; centered packed point swarm) or `'raincloud'` (half-violin cloud + box plot + offset swarm).
+  - `radius`: Radius of each observation dot (default `3.5`).
+  - `padding`: Minimum pixel gap between adjacent packed points (default `1`).
+  - `halfViolin`: In raincloud mode, draws upper density envelope (default `true`).
+  - `boxPlot`: In raincloud mode, draws embedded quartiles and median bar (default `true`).
+  - `colors`: Array of categorical colors per group.
+
+```javascript
+engine.beeswarmChart([
+    { label: 'Control',    values: [2.1, 2.4, 2.5, 2.7, 2.9, 3.1, 3.2, 3.6, 4.0] },
+    { label: 'Treatment',  values: [3.2, 3.5, 3.8, 4.1, 4.2, 4.5, 4.8, 5.2, 5.9] },
+], { mode: 'raincloud', radius: 4 });
+```
+
+### Empirical Cumulative Distribution Function — `ecdfChart(data, options)`
+
+Draws exact empirical step CDFs \(P(X \le x)\) from 0 to 1, comparing distributions without bin-width artifacts. Includes automated Kolmogorov-Smirnov distance calculations.
+
+- **Data shapes:**
+  - `number[]` (single sample)
+  - `Array<{label: string, values: number[]}>` (multi-group comparison)
+- **Notable options:**
+  - `showMedian`: `true` (default) to project dashed 50th-percentile lines to axes.
+  - `showQuantiles`: `true` to annotate 25th, 50th, and 75th percentile markers.
+  - `step`: Step interpolation style (`'vh'` default: vertical-then-horizontal, or `'hv'`).
+  - `compare`: When two series are supplied, calculates and highlights the maximum vertical distance \(D_{KS}\) (`EcdfChart.ksDistance(s1, s2)`).
+  - `colors`: Palette array for series steps.
+
+```javascript
+engine.ecdfChart([
+    { label: 'Algorithm A', values: [12, 15, 18, 22, 25, 29, 34, 40] },
+    { label: 'Algorithm B', values: [8,  11, 14, 16, 19, 21, 24, 28] },
+], { showMedian: true, compare: true });
+```
+
+### Hexagonal 2D Density Binning — `hexbinChart(data, options)`
+
+Aggregates dense 2D scatter coordinate clouds into regular hexagonal tiles, preventing visual saturation and overplotting in large point datasets.
+
+- **Data shapes:**
+  - `Array<{x: number, y: number, value?: number}>`
+  - `Array<[x: number, y: number]>`
+- **Notable options:**
+  - `radius`: Outer radius of each hexagon cell in pixels (default `14`).
+  - `minCount`: Minimum point count threshold required to render a cell (default `1`).
+  - `colorScale`: Sequential color palette array (e.g. `['#e0f3f8', '#67a9cf', '#02818a', '#bd0026']`).
+  - `title`, `xAxisLabel`, `yAxisLabel`: Chart and axis labels.
+
+```javascript
+const points = Array.from({ length: 5000 }, () => ({
+    x: Math.random() * 100,
+    y: Math.random() * 100,
+}));
+engine.hexbinChart(points, { radius: 12, minCount: 2 });
+```
+
+### Horizon Chart — `horizonChart(data, options)`
+
+Folds continuous time-series magnitude into 2 to 5 layered colored bands within a narrow vertical band (e.g. 30–50px), preserving high precision while displaying dozens of series simultaneously.
+
+- **Data shape:** `Array<{label: string, values: number[]}>`
+- **Notable options:**
+  - `bands`: Number of layered folding bands (default `3`).
+  - `posColors`: Color gradient array for positive values (default 3-stage blues).
+  - `negColors`: Color gradient array for negative values (default 3-stage reds).
+  - `title`: Chart title.
+
+```javascript
+engine.horizonChart([
+    { label: 'CPU Core 0', values: [10, 25, 45, 80, 95, 60, 40, 30] },
+    { label: 'CPU Core 1', values: [-15, 20, 50, 70, 85, 45, 20, -10] },
+], { bands: 3 });
+```
+
+### Circle Packing — `circlePackChart(data, options)`
+
+Represents hierarchical tree structures as nested tangent circles sized by value, with translucent ancestor boundary rings and hover elevation.
+
+- **Data shape:** Hierarchical tree `Array<{label: string, value?: number, children?: Array}>`
+- **Notable options:**
+  - `padding`: Pixel gap between tangent sibling circles (default `2`).
+  - `showLabels`: `true` (default) to label circles that have sufficient interior area.
+  - `minLabelRadius`: Minimum circle radius in pixels required to render text inside (default `14`).
+  - `colors`: Palette array mapped across top-level tree branches.
+
+```javascript
+engine.circlePackChart([{
+    label: 'Architecture',
+    children: [
+        { label: 'Backend', children: [{ label: 'API', value: 40 }, { label: 'DB', value: 30 }] },
+        { label: 'Frontend', children: [{ label: 'Web', value: 25 }, { label: 'Mobile', value: 15 }] },
+    ],
+}], { padding: 4 });
+```
+
+### Alluvial Diagram — `alluvialDiagram(data, options)`
+
+Visualizes categorical flows across three or more sequential dimensions using smooth cubic bezier ribbons whose widths represent flow volumes.
+
+- **Data shapes:**
+  - Multi-stage pathway list: `Array<{steps: string[], value: number}>`
+  - Tabular rows: `{dimensions: string[], rows: Array<object>}`
+  - Edge list: `Array<{source: string, target: string, value: number}>`
+- **Notable options:**
+  - `dimensions`: Array of dimension stage names (e.g. `['Role', 'Department', 'Access Level']`).
+  - `nodeWidth`: Width of category pillar rectangles in pixels (default `18`).
+  - `nodePadding`: Vertical separation between category nodes (default `12`).
+  - `curvature`: Bezier curvature ratio for flow links (default `0.5`).
+  - `linkOpacity`: Fill opacity for flow ribbons (default `0.55`).
+  - `colors`: Palette array for node categories.
+
+```javascript
+engine.alluvialDiagram([
+    { steps: ['Engineering', 'Senior', 'Admin'],  value: 12 },
+    { steps: ['Engineering', 'Junior', 'User'],   value: 28 },
+    { steps: ['Product',     'Lead',   'Admin'],  value: 5 },
+    { steps: ['Product',     'Analyst', 'User'],  value: 15 },
+], { dimensions: ['Department', 'Seniority', 'Permission'] });
+```
+
+### Polar Area (Nightingale Rose) — `polarAreaChart(data, options)`
+
+Divides a circle into equal angular sectors where the radial distance (or area) of each sector represents its magnitude. Supports optional 3D isometric extrusion and interactive wedge pull-out.
+
+- **Data shape:** `Array<{label: string, value: number, exploded?: boolean}>`
+- **Notable options:**
+  - `scale`: `'radius'` (linear radial distance) or `'area'` (square-root scaling so slice area is proportional to value).
+  - `extrude3D`: `true` to render as an isometric 3D cylindrical cylinder with depth shading.
+  - `depth`: Extrusion height in pixels when `extrude3D: true` (default `22`).
+  - `innerRadiusRatio`: Donut hole ratio (default `0.12`).
+  - `padAngle`: Angular spacing between sectors in radians (default `0.02`).
+  - `hoverExplode`: `true` to pull out wedges under the cursor.
+
+```javascript
+engine.polarAreaChart([
+    { label: 'North', value: 45 },
+    { label: 'East',  value: 80 },
+    { label: 'South', value: 35 },
+    { label: 'West',  value: 60 },
+], { scale: 'area', extrude3D: true, depth: 25 });
+```
+
+### 3D Surface Mesh — `surfaceChart3D(data, options)`
+
+Renders continuous 3D mathematical surfaces, terrain elevations, or 2D matrix loss landscapes using true 4×4 perspective transformations and interactive orbit camera rotation.
+
+- **Data shapes:**
+  - Regular grid: `{xLabels: string[]|number[], zLabels: string[]|number[], values: number[][]}`
+  - Coordinate tuples: `Array<{x: string|number, z: string|number, value: number}>`
+- **Notable options:**
+  - `wireframe`: `true` (default) to overlay contrasting grid lines on surface polygons.
+  - `wireframeColor`: Stroke color for wireframe lines (default `'rgba(255,255,255,0.45)'`).
+  - `colorScale`: Array of gradient color stops for height-based surface shading.
+  - `initialTheta`, `initialPhi`, `initialDistance`: Initial camera angles and zoom distance.
+  - Orbit interaction: Drag to rotate camera azimuth and elevation, mouse wheel to zoom in/out.
+
+```javascript
+const xLabels = [-2, -1, 0, 1, 2];
+const zLabels = [-2, -1, 0, 1, 2];
+const values = xLabels.map(x => zLabels.map(z => Math.sin(Math.sqrt(x * x + z * z))));
+
+engine.surfaceChart3D({ xLabels, zLabels, values }, {
+    title: 'Bivariate Ripple Surface',
+    wireframe: true,
+});
+```
+
+### Contour Plot — `contourChart(data, options)`
+
+Generates smooth isoline curves and filled isoband color regions from 2D scalar fields using the marching-squares algorithm with automated numeric elevation labels.
+
+- **Data shapes:**
+  - 2D scalar matrix: `number[][]` (rows × columns)
+  - Coordinate list: `Array<{x: number, y: number, value: number}>`
+- **Notable options:**
+  - `levels`: Number of contour threshold intervals (default `8`), or an explicit array of numbers `[0.1, 0.25, 0.5, 0.75]`.
+  - `filled`: `true` (default) to render shaded polygon bands between isolines.
+  - `showLines`: `true` (default) to stroke isoline boundaries.
+  - `showLabels`: `true` (default) to annotate contour lines with numeric elevation values.
+  - `colorScale`: Array of colors interpolated across contour levels.
+  - `lineColor`: Stroke color for isolines (default `'rgba(0,0,0,0.3)'`).
+
+```javascript
+const grid = [
+    [0.1, 0.2, 0.4, 0.2, 0.1],
+    [0.2, 0.6, 0.9, 0.6, 0.2],
+    [0.4, 0.9, 1.0, 0.9, 0.4],
+    [0.2, 0.6, 0.9, 0.6, 0.2],
+    [0.1, 0.2, 0.4, 0.2, 0.1],
+];
+engine.contourChart(grid, { levels: 6, filled: true, showLabels: true });
+```
+
 ## Common options
 
 Not every method takes every option below — the table above calls out what's notable per type —
@@ -1523,10 +1820,10 @@ data — `addDataPoint` is a **no-op** when it's `'none'`:
 
 | `streamShape` | Chart types | Behavior |
 |---|---|---|
-| `flat` | `bar`, `pie`, `scatter`, `bubble`, `candlestick`, `stackedBar`, `funnel`, `waterfall`, `histogram`, `qq`, `lag`, `treemap`, `sunburst`, `outline`, `bar3D`, `bubble3D` | one new record appended to the outer array |
-| `series` | `line`, `area`, `pipe` | every series' own `values` grows by one point |
-| `grouped-sample` | `boxPlot`, `density`, `violin` | exactly ONE randomly-chosen group's `values` grows (a new sample observation belongs to one group, unlike a shared time axis) |
-| `none` | `heatmap`, `radar` (fixed matrix/axis-set), `bar3DOrbit`/`stackedBar3DOrbit` (fixed grid), `gauge-dial`/`gauge-bar`/`bullet` (a value to replace, not a window) | `addDataPoint` no-ops — for gauges, just call `dialGauge(newValue)`/`barGauge(newValue)`/`bulletGauge(newValue)` again directly |
+| `flat` | `bar`, `pie`, `scatter`, `bubble`, `candlestick`, `stackedBar`, `funnel`, `waterfall`, `histogram`, `qq`, `lag`, `treemap`, `sunburst`, `outline`, `bar3D`, `bubble3D`, `dumbbell`, `slopegraph`, `circlePack`, `horizon`, `polarArea`, `hexbin`, `pareto`, `lollipop` | one new record appended to the outer array |
+| `series` | `line`, `area`, `pipe`, `combo` | every series' own `values` grows by one point |
+| `grouped-sample` | `boxPlot`, `density`, `violin`, `ecdf`, `beeswarm`, `ridgeline` | exactly ONE randomly-chosen group's `values` grows (a new sample observation belongs to one group, unlike a shared time axis) |
+| `none` | `heatmap`, `radar` (fixed matrix/axis-set), `bar3DOrbit`/`stackedBar3DOrbit`/`surface3D` (fixed grid), `gauge-dial`/`gauge-bar`/`bullet` (a value to replace, not a window), `alluvial`, `contour`, `splom` | `addDataPoint` no-ops — for gauges, just call `dialGauge(newValue)`/`barGauge(newValue)`/`bulletGauge(newValue)` again directly |
 
 ### 2. Graphs — `addGraphNode`
 
@@ -2610,6 +2907,7 @@ new RectangleTemplate('r1', 'Billing', { fontFamily: 'Georgia', fontSize: '14pt'
 | Boxes | `RectangleTemplate`, `RoundedRectangleTemplate`, `StadiumTemplate`, `PredefinedProcessTemplate`, `ClassTemplate`, `ComponentTemplate`, `SwimlaneTemplate`, `PackageTemplate`, `BoxTemplate` (3D) |
 | Round | `CircleTemplate`, `EllipseTemplate`, `FinalStateTemplate`, `CloudTemplate` |
 | Polygons | `DiamondTemplate`, `TriangleTemplate`, `PentagonTemplate`, `HexagonTemplate`, `OctagonTemplate`, `StarTemplate`, `ParallelogramTemplate`, `TrapezoidTemplate`, `ManualInputTemplate` |
+| C4 Architecture | `C4PersonTemplate`, `C4SystemTemplate`, `C4ContainerTemplate`, `C4ComponentTemplate`, `C4BoundaryTemplate` |
 | Other | `CylinderTemplate`, `DocumentTemplate`, `NoteTemplate`, `DataStoreTemplate`, `ActorTemplate`, `LifelineTemplate` |
 
 A template draws its outline in `shapeElements(doc)`, or in `points()` when it extends
@@ -2642,6 +2940,19 @@ empty canvas, or on the shape at the other end, cancels. This is one undo step
 
 **Container nesting and hierarchy.** Shapes such as `PackageTemplate`, `SwimlaneTemplate`, and `BoxTemplate` are containers (`isContainer = true`). When an element is dropped inside a container (`nestsOnDrop(parentId, childId)`), it is parented via `NestElementCommand` (setting `child.parentId`). Moving a container recursively moves all nested descendants (`moversFor(templateId)`). Containers can automatically expand their bounds to fit their contents via `fitNesting(changes, { padding })`. Ancestor loops are prevented (`isAncestor(childId, parentId)`).
 
+**C4 Model notation & architecture diagrams.** The `'c4-architecture'` category in `DIAGRAM_TYPES` (and `editor.setPaletteCategory('c4-architecture')`) provides first-class support for Simon Brown's C4 model across Context, Container, Component, and Code levels:
+- `C4PersonTemplate`: A human user, actor, persona, or stakeholder (`#08427b`, white text) with an integrated person silhouette badge and `[Person]` tagline.
+- `C4SystemTemplate`: Software system in focus (`#1168bd`, white text, `[Software System]`) or external software systems (`external: true`, `#999999`, `[Software System: External]`).
+- `C4ContainerTemplate`: Applications, web services, or microservices (`#438dd5`, white text, `[Container: <technology>]`), and database datastores (`containerType: 'database'`, cylinder icon).
+- `C4ComponentTemplate`: Modular components, controllers, and services (`#85bbf0`, dark text, `[Component: <technology>]`) with the UML component glyph.
+- `C4BoundaryTemplate`: Enterprise, system, or container scope boundaries (`isContainer = true`, dashed border `#707070`, bracketed header `[<boundaryType> Boundary]`) that enclose nested child elements.
+
+```javascript
+const person = new C4PersonTemplate('p1', 'Customer', { description: 'Personal banking customer' });
+const system = new C4SystemTemplate('s1', 'Internet Banking System', { description: 'Allows customers to view accounts and make payments' });
+const boundary = new C4BoundaryTemplate('b1', 'Big Bank plc', { boundaryType: 'Enterprise' });
+```
+
 **Line style levels.** A line's style resolves through `EdgeStyleCascade`: the line itself,
 then each level in `editor.edgeStyleLevels` (most specific first, `[{ key, label, style }]`),
 then the schema default. A value a level doesn't set is inherited. `EDGE_STYLE_PROPERTIES` is the
@@ -3209,7 +3520,7 @@ drawn with this library's charts. It reads decisionengine's JSON, not decisionen
 document
 
 ```js
-{ kind: 'sadis-workbench', report, plan?, before? }   // report.toJSON(), plan.toJSON(), an earlier report.toJSON()
+{ kind: 'sadis-workbench', report, plan?, before?, graph? }   // report.toJSON(), plan.toJSON(), an earlier report.toJSON(), the scored graph
 ```
 
 which decisionengine's SADIS Explorer downloads ("Download for the Decision Workbench").
@@ -3228,6 +3539,7 @@ for (const view of workbench.views()) {
 |---|---|---|
 | Executive | a report | `kpi-tile` (what to build next; half the value delivered by), `stackedBar` (score part by part), `line` (value delivered by period) |
 | Architecture | a report | `scatter` (visible rating against basin position: foundations sit high and left), `lollipop` (share each frees) |
+| Explore | the scored graph | `graph` diagram of the first candidate's neighbourhood: its ways up to each objective it reaches (shortest, along contributions) and what waits on it (depends on it, or is blocked by it); notes spell each way out. Walked with `NavigatorModel.forGraph` |
 | Delivery | a plan | `gantt` (the plan on a calendar), `stackedBar` (capacity used per period, per team when planned by team) |
 | Portfolio | a report with perspectives | `heatmap` (rank by perspective), `dumbbell` (best and worst rank, most contested first) |
 | Replay | an earlier report | `slopegraph` (rank then → now); notes say what entered, left (and why) and moved |
@@ -3385,7 +3697,7 @@ nav.back();        // returns to 'billing-app'
 const paths = nav.findPaths('billing-app', 'ledger-db', 5);
 
 // Trace transitive downstream or upstream impact:
-const impact = nav.findImpact('billing-app', { maxDepth: 4, direction: 'outgoing' });
+const impact = nav.traceImpact('billing-app', { maxDepth: 4, direction: 'outgoing' });
 
 // 2. Build or render the Navigator UI panel:
 const panel = new NavigatorPanel({
@@ -3400,7 +3712,26 @@ const panel = new NavigatorPanel({
 - **Cycle detection and path tracking:** Tracks visited nodes along active branches to prevent infinite recursion in cyclic relationship graphs, annotating cycles in tree outputs.
 - **Directional filters:** Traversal can follow outgoing relationships, incoming relationships, or bidirectional connections (`setDirection('outgoing' | 'incoming' | 'both')`).
 - **History stack:** Maintains full forward and backward navigation stacks (`focus(id)`, `back()`, `forward()`, `canGoBack`, `canGoForward`).
-- **Impact and path finding:** Built-in BFS/DFS algorithms find connecting pathways (`findPaths(fromId, toId, maxDepth)`) and downstream dependency cascades (`findImpact(elementId, { maxDepth, direction })`).
+- **Impact and path finding:** Built-in BFS/DFS algorithms find connecting pathways (`findPaths(fromId, toId, maxDepth)`) and downstream dependency cascades (`traceImpact(elementId, { maxDepth, direction })`).
+
+
+**Any graph, not only ArchiMate.** `NavigatorModel` reads its graph only through four questions —
+`getElement(id)`, `relationshipsFor(id)` (`{ incoming, outgoing }`, each `{ id, source, target, kind }`),
+`viewsContaining(id)` and `layerOf(element)` — the `GraphSource` interface
+(`src/charting/graph/GraphSource.js`). `ArchimateModel` answers them already (its layers from
+`treeLayerOf`); `DocumentGraph` answers them for a graph document, `{ nodes: [{ id, labels, props }],
+edges: [{ from, to, type, props }] }` — sqlengine's graphs and decisionengine's portfolios — a node's type its
+first label, its layer its type:
+
+```javascript
+import { NavigatorModel, DocumentGraph } from '@peter.prib/renderengine';
+const nav = NavigatorModel.forGraph(graphDocument, { rootId: 'cap-semantic-registry' });
+nav.findPaths('cap-semantic-registry', 'obj-trusted-data', { direction: 'outgoing', allowedKinds: ['ENABLES', 'SUPPORTS'] });
+nav.traceImpact('cap-semantic-registry', { direction: 'incoming', allowedKinds: ['DEPENDS_ON'] });
+```
+
+Why an interface rather than a second walker: traversal is the same for every graph; only these reads
+differ, so each kind of graph answers them and the one walker (paths, impact, history, the tree) serves all.
 
 ## Templated Reports (`TemplatedReport`)
 
@@ -3492,30 +3823,55 @@ dataModel.addArchimateLink(link);
 
 ## Multi-View Chart Dashboards (`ViewsPart` / `DecisionWorkbenchPart`)
 
-`ViewsPart` (`src/workspace/parts/ViewsPart.js`) and `DecisionWorkbenchPart` (`src/workspace/parts/DecisionWorkbenchPart.js`) render multi-tab dashboards of coordinated charts and note cards inside the `<ws-workspace>` application shell.
+`ViewsPart` (`src/workspace/parts/ViewsPart.js`, type `views`) shows a set of chart **views** inside
+one workspace part: a tab per view, each a grid of charts with its notes underneath, and a toolbar that
+opens a file. A view is plain data:
 
-```javascript
-// Declarative view specification for a workspace layout node:
-const layout = {
-    type: 'part',
-    part: 'views',
-    views: [
-        {
-            id: 'executive-summary',
-            title: 'Executive Summary',
-            charts: [
-                { title: 'System Health', chartType: 'gauge dial', data: [{ score: 94 }], options: { min: 0, max: 100 } },
-                { title: 'Revenue Trend', chartType: 'area', data: [...] }
-            ],
-            notes: ['All latency thresholds met', 'Quarterly SLA target achieved']
-        }
-    ]
-};
+```js
+{ id: 'summary', title: 'Summary',
+  charts: [{ title, chartType, data, options? }],   // chartType: a CHART_CATALOG key ('kpi-tile', 'bar', 'gantt', …)
+  notes: ['plain lines the charts cannot show'] }
 ```
 
-- **Self-contained workbench part:** Embeds cleanly into tabs, split panes, or WorkArea documents alongside diagram modellers and data tables without hijacking global workspace perspective state.
-- **Catalog-driven composition:** Composes existing `ChartPart`s driven by `CHART_CATALOG` keys alongside `ListPart` note cards. Small gauge charts automatically tile along the top banner.
-- **Decision Workbench:** Specialized `DecisionWorkbenchPart` reads SADIS analysis reports and optimization plans (`viewsFrom(doc)`), projecting trade-off curves, capability radars, and decision matrices directly into tabs.
+Like any part it is registered, added with `addParts`, and placed in a layout by its `partId`. It uses
+`ChartPart`, so it is registered with it rather than being among `BUILTIN_PARTS`:
+
+```js
+const { registerBuiltinParts, ChartPart, ViewsPart } = RenderEngineWorkspace;
+registerBuiltinParts(ws);
+ws.registerParts([ChartPart, ViewsPart]);
+ws.addParts([{
+    id: 'summary', type: 'views', title: 'Summary',
+    views: [{
+        id: 'health', title: 'Health',
+        charts: [
+            { title: 'Availability (%)', chartType: 'kpi-tile', data: { value: 99.95 } },
+            { title: 'Errors by service', chartType: 'bar', data: [{ label: 'api', value: 12 }, { label: 'web', value: 3 }] },
+        ],
+        notes: ['All latency thresholds met'],
+    }],
+}]);
+ws.registerPerspective('Summary', { type: 'part', partId: 'summary' });
+```
+
+- **One part, any layout.** It sits in a tab, a split, a dashboard cell or a WorkArea document beside
+  what else the host shows; it does not register perspectives of its own.
+- **Composed from existing parts.** Each chart is a `ChartPart`, the notes a `ListPart`. Gauge-like
+  charts (catalog `category: 'gauge'`, e.g. `kpi-tile`, `gauge-bar`, `bullet`) share the top row as
+  tiles; other charts take half a row, or the whole row when a view has one (`ViewsPart.layout(views)`).
+- **Spec:** `views`, `open` (default true: the toolbar's file opener), `empty` (the text shown with no
+  views). `part.read(doc)` shows a `{ views: [...] }` document from code. The views shown are kept in
+  `spec.views`, so a serialized workspace comes back showing them.
+- **Other kinds of document** are subclasses overriding `viewsFrom(doc)` (and `accept`, `controls()`,
+  `controlValues()` for options their reader takes). Why a subclass and not a reader in the spec, and
+  why one part rather than perspectives: `documentation/WORKSPACE_ARCHITECTURE.md` (Parts).
+
+`DecisionWorkbenchPart` (`src/workspace/parts/DecisionWorkbenchPart.js`, type `decision-workbench`) is
+the first such subclass. It reads a SADIS workbench document from decisionengine
+(`{ kind: 'sadis-workbench', report, plan?, before? }`) through `DecisionWorkbench` and shows its
+**executive**, **architecture**, **delivery**, **portfolio** and **replay** views (see *Decision
+Workbench* above), with toolbar fields for the calendar the delivery plan is drawn on. Spec: `ViewsPart`'s
+plus `document`, `start`, `periodDays`. `examples/decision-workbench.html` hosts one.
 
 ## Where to go next
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peter.prib/renderengine",
-  "version": "0.15.1",
+  "version": "0.15.3",
   "description": "ArchiMate modeller, data modeller, diagram editor, OLAP cube & pivot chart studio, and 50+ type chart library for the browser, with no runtime dependencies.",
   "type": "module",
   "main": "src/index.js",