@peter.prib/renderengine 0.15.1 → 0.15.2

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`
 
@@ -3492,30 +3789,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.2",
   "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",

package/src/charting/ArchimateDiagramEditor.js

@@ -33,7 +33,8 @@ import { ExchangeFileFormat } from './archimate/ExchangeFileFormat.js';
 import { ArchimateCsvFileFormat } from './archimate/ArchimateCsvFileFormat.js';
 
 /**
- * ArchimateDiagramEditor — ArchiMate-specific diagram editor extending DiagramEditor base.
+ * ArchimateDiagramEditor — legacy GraphDiagram-based ArchiMate editor extending DiagramEditor.
+ * @deprecated Use ArchimateCanvasEditor (or ArchimateCanvasPart) for ArchiMate editing. RenderEngine.archimateDiagram() remains for read-only charts.
  *
  * Encapsulates: ArchiMate model, tree navigator, diagram tabs, rendering, controls wiring.
  * Inherits: common rendering, drag/drop, toolbar, tree, filtering from DiagramEditor.

package/src/charting/Edge.js

@@ -117,4 +117,26 @@ export class Edge {
     clearWaypoints() {
         this.waypoints = [];
     }
+
+    /** The edge as plain JSON: its endpoints, label, waypoints, side pins and style overrides. */
+    toJSON() {
+        return {
+            id: this.id,
+            sourceId: this.sourceId,
+            targetId: this.targetId,
+            label: this.label,
+            waypoints: this.waypoints.map(w => ({ x: w.x, y: w.y })),
+            sourceSide: this.sourceSide,
+            targetSide: this.targetSide,
+            visible: this.visible,
+            ...this.styleOverrides(),
+        };
+    }
+
+    /** Reconstruct an Edge from plain JSON. */
+    static fromJSON(json) {
+        if (!json) throw new TypeError('Edge.fromJSON requires a JSON object');
+        const { id, sourceId, targetId, ...rest } = json;
+        return new Edge(id, sourceId, targetId, rest);
+    }
 }

package/src/charting/archimate/ArchimateCanvasEditor.js

@@ -1034,15 +1034,28 @@ export class ArchimateCanvasEditor extends DiagramEditor {
         return element ? treeLayerOf(element) : 'other';
     }
 
-    /** An element's box holds any box but a group; on a canvas, a block holds boxes. */
+    /** An element's box holds any box; a group holds any box or nested group; on a canvas, a block holds boxes. */
     canHold(parentId, childId) {
+        if (!parentId || !childId || parentId === childId) return false;
         const parent = this.templates.get(parentId), child = this.templates.get(childId);
-        if (!parent?.instance || !child?.instance || parent instanceof ViewGroupTemplate || child instanceof ViewGroupTemplate) return false;
+        if (!parent || !child) return false;
+        if (child instanceof ViewGroupTemplate && parent instanceof ViewGroupTemplate) {
+            return !this.isAncestor(childId, parentId);
+        }
+        if (parent instanceof ViewGroupTemplate) {
+            return !this.isAncestor(childId, parentId);
+        }
+        if (child instanceof ViewGroupTemplate) return false;
+        if (!parent.instance || !child.instance) return false;
         return !!this._elementOf(parentId) || parent.instance.content?.archiVisualType === 'canvas-model-block';
     }
 
-    /** An element dropped on another nests there when a relationship a nesting stands for (NESTING_KINDS) is allowed between them. */
+    /** An element dropped on another nests there when a relationship a nesting stands for (NESTING_KINDS) is allowed between them, or when dropped into a group. */
     nestsOnDrop(parentId, childId) {
+        const parent = this.templates.get(parentId);
+        if (parent instanceof ViewGroupTemplate) {
+            return this.canHold(parentId, childId);
+        }
         if (!this._elementOf(parentId) || !this._elementOf(childId)) return false;
         return this.allowedKinds(parentId, childId).some(kind => NESTING_KINDS.includes(kind));
     }
@@ -1050,13 +1063,16 @@ export class ArchimateCanvasEditor extends DiagramEditor {
     nestCommand(childId, parentId) {
         const child = this.templates.get(childId)?.instance;
         if (!child) return null;
-        return new NestInstanceCommand(child, parentId ? this.templates.get(parentId)?.instance ?? null : null);
+        const parentTemplate = parentId ? this.templates.get(parentId) : null;
+        const parentTarget = parentTemplate?.instance ?? (parentTemplate instanceof ViewGroupTemplate ? parentTemplate : null);
+        return new NestInstanceCommand(child, parentTarget);
     }
 
-    /** After nesting an element in another: offer the relationship the nesting stands for (nestingKinds). */
+    /** After nesting an element in another: offer the relationship the nesting stands for (nestingKinds). Groups have no relationship. */
     nested(changes) {
         let chain = Promise.resolve();
         for (const { childId, parentId } of changes) {
+            if (this.templates.get(parentId) instanceof ViewGroupTemplate) continue;
             chain = chain.then(() => this.offerNestingRelationship(parentId, childId));   // taken out: nothing to offer
         }
         return chain;

package/src/charting/archimate/ViewGroupTemplate.js

@@ -47,8 +47,11 @@ export class ViewGroupTemplate extends GlyphTemplate {
         return this.view.model.getFolder(this.id);
     }
 
-    get name() { return this.folder?.name ?? 'Group'; }
-    set name(value) { if (this.folder) this.folder.name = value || 'Group'; }
+    get name() { return this.folder?.name ?? this.layout?.name ?? 'Group'; }
+    set name(value) {
+        if (this.folder) this.folder.name = value || 'Group';
+        if (this.layout) this.layout.name = value || 'Group';
+    }
 
     // The layout keeps the top-left corner; a template is placed by its centre.
     get x() { return this.layout.x + this.width / 2; }

package/src/charting/diagramModel/DiagramJsonFileFormat.js

@@ -0,0 +1,32 @@
+import { ModelFileFormat } from '../ModelFileFormat.js';
+import { DiagramModel } from './DiagramModel.js';
+
+/**
+ * DiagramJsonFileFormat — a diagram model as a file (`.diagram.json` or `.json`):
+ * its name, palette category, line style defaults, views with templates, edges,
+ * waypoints and arrangements (DiagramModel#toJSON), read back by DiagramModel.fromJSON.
+ */
+export class DiagramJsonFileFormat extends ModelFileFormat {
+    get label() { return '.diagram.json'; }
+    get accept() { return '.diagram.json,.json'; }
+    get fileName() { return 'diagrams.diagram.json'; }
+    get featureName() { return 'DiagramJson'; }
+
+    /** JSON with a diagram model's shape: templateType and views array, or views array of diagrams. */
+    recognizes(text) {
+        try {
+            const json = JSON.parse(text);
+            return !!json && typeof json === 'object' && (Array.isArray(json.views) || typeof json.templateType === 'string');
+        } catch {
+            return false;
+        }
+    }
+
+    export(model) {
+        return { data: JSON.stringify(model.toJSON(), null, 2), mimeType: 'application/json' };
+    }
+
+    import(text) {
+        return DiagramModel.fromJSON(JSON.parse(text));
+    }
+}

package/src/charting/diagramModel/DiagramModel.js

@@ -36,4 +36,43 @@ export class DiagramModel extends ViewSetModel {
     setTemplateType(templateType) {
         this.templateType = templateType;
     }
+
+    /** The diagram model as plain JSON: its name, templateType, line style defaults, active view and views. */
+    toJSON() {
+        return {
+            version: 1,
+            name: this.name,
+            templateType: this.templateType,
+            edgeStyle: JSON.parse(JSON.stringify(this.edgeStyle ?? {})),
+            currentViewId: this.currentViewId,
+            views: this.views().map(v => v.toJSON()),
+        };
+    }
+
+    /** Reconstruct a DiagramModel from plain JSON. */
+    static fromJSON(json, historyOptions = {}) {
+        if (!json) throw new TypeError('DiagramModel.fromJSON requires a JSON object');
+        const model = new DiagramModel({
+            name: json.name ?? '',
+            templateType: json.templateType ?? 'generic',
+            edgeStyle: json.edgeStyle ?? {},
+            historyOptions,
+        });
+        const views = (json.views ?? []).map(vData => DiagramView.fromJSON(vData, model.historyOptions));
+        for (const view of views) {
+            model._insertView(model._adopt(view), { current: view.id === json.currentViewId });
+        }
+        if (json.currentViewId && model._views.has(json.currentViewId)) {
+            model.currentViewId = json.currentViewId;
+        } else if (model._views.size > 0 && !model.currentViewId) {
+            model.currentViewId = model._views.keys().next().value;
+        }
+        const maxNum = Math.max(0, ...model.views().map(v => {
+            const m = String(v.id).match(/\d+$/);
+            return m ? parseInt(m[0], 10) : 0;
+        }));
+        model._nextId = maxNum + 1;
+        model.markSaved();
+        return model;
+    }
 }