@peter.prib/renderengine 0.15.0 → 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`
 
@@ -2640,6 +2937,8 @@ end. Waypoints and style are kept, and that end's side pin resets to automatic.
 empty canvas, or on the shape at the other end, cancels. This is one undo step
 (`ReconnectEdgeCommand`).
 
+**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)`).
+
 **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
@@ -3235,8 +3534,20 @@ saying why. The delivery plan's periods are put on a calendar: period 1 starts a
 the report's as-of business time, else today), each `periodDays` long (default 14). Each view is a
 `WorkbenchView` subclass (`WORKBENCH_VIEWS`); a new view is a new subclass.
 
-`examples/decision-workbench.html` is the page: open a workbench file and each view is a workspace
-perspective, its charts in `ChartPart`s and its notes in a list.
+In a workspace the workbench is one part, `DecisionWorkbenchPart` (type `decision-workbench`), a
+`ViewsPart` that reads workbench documents: a tab per view, its charts and notes, a toolbar that opens a
+file and sets the calendar.
+
+```js
+const { registerBuiltinParts, ChartPart, DecisionWorkbenchPart } = RenderEngineWorkspace;
+ws.registerParts([ChartPart, DecisionWorkbenchPart]);
+ws.addParts([{ id: 'workbench', type: 'decision-workbench', document /* optional */, start, periodDays }]);
+```
+
+`ViewsPart` (type `views`) is the general part underneath: any `{ views: [{ id, title, charts, notes }] }`
+document, or views given in its spec, shown the same way — see `documentation/WORKSPACE_ARCHITECTURE.md`
+for why it is one part and why a new kind of document is a subclass. `examples/decision-workbench.html`
+is a thin host of the workbench part (it is in the package).
 
 ## Navigation menus
 
@@ -3349,6 +3660,185 @@ const bar = RenderEngine.askBar(document.getElementById('ask-bar'), {
 - **For a host:** `bar.setSuggest(fn)` swaps where suggestions come from, for example when the user picks another model or ontology. `bar.setValue(text)` sets the question without suggesting. `bar.focus()` puts the cursor in the question, and `bar.destroy()` removes the bar and cancels any pending close.
 - **Accessible:** the input is a WAI-ARIA combobox over a `listbox` of `option`s. `aria-expanded` follows the popup and `aria-activedescendant` follows the active item. Each bar's list has its own id, so several bars can share a page.
 
+## Navigator & Relationship Explorer (`NavigatorModel` / `NavigatorPanel`)
+
+`NavigatorModel` (`src/charting/modelTree/NavigatorModel.js`) and `NavigatorPanel` (`src/charting/modelTree/NavigatorPanel.js`) provide interactive graph traversal and relationship exploration for models. It enables navigating through connected elements step-by-step to arbitrary depth with cycle detection, navigation history (back/forward), direction filters, path-finding, and transitive impact analysis.
+
+```javascript
+import { NavigatorModel, NavigatorPanel, buildNavigatorPanel } from '@peter.prib/renderengine';
+
+// 1. Create a pure, DOM-free traversal model:
+const nav = new NavigatorModel(archimateModel, {
+    rootId: 'billing-app',
+    direction: 'both', // 'both' | 'outgoing' | 'incoming'
+    allowedKinds: ['serving-relationship', 'composition-relationship'],
+});
+
+nav.focus('crm-app');
+nav.canGoBack;     // true
+nav.back();        // returns to 'billing-app'
+
+// Find all paths between two elements (up to maxDepth):
+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' });
+
+// 2. Build or render the Navigator UI panel:
+const panel = new NavigatorPanel({
+    model: archimateModel,
+    navigator: nav,
+    onSelectElement: (elId) => editor.selectElement(elId),
+    onOpenView: (viewId) => editor.openView(viewId),
+});
+```
+
+- **DOM-free engine:** `NavigatorModel` operates completely without DOM dependencies, making it directly testable in Node.js and reusable across diverse UI shells.
+- **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 })`).
+
+## Templated Reports (`TemplatedReport`)
+
+`TemplatedReport` (`src/charting/report/TemplatedReport.js`) provides multi-format, template-driven report generation matching Archi's Jasper-style reporting capabilities. It extracts model metadata, viewpoints, diagrams (SVG/PNG), elements, properties, and relationships into document formats.
+
+```javascript
+import { TemplatedReport, REPORT_TEMPLATES } from '@peter.prib/renderengine';
+
+const report = new TemplatedReport(archimateModel, {
+    title: 'Enterprise Architecture Overview',
+    template: REPORT_TEMPLATES.DETAILED, // 'executive' | 'detailed' | 'tabular'
+    pictures: { 'view-1': 'data:image/svg+xml;utf8,...' },
+});
+
+// Generate various formats:
+const htmlDoc = report.toHtml({ printable: true }); // PDF-ready HTML with @media print CSS
+const wordDoc = report.toWord();                    // Microsoft Word (.doc HTML format)
+const excelXml = report.toExcel();                  // Excel SpreadsheetML (.xml)
+const csvData = report.toCsv('elements');           // RFC 4180 CSV ('elements' | 'relationships')
+const markdown = report.toMarkdown();               // GitHub-flavored Markdown
+```
+
+- **Output formats:** Generates printable PDF-ready HTML with page-break controls, Word-compatible HTML documents (`.doc`), Excel SpreadsheetML workbooks (`.xml`) with styled headers and filters, RFC 4180 CSV tables, and GitHub-flavored Markdown (`.md`).
+- **Built-in templates:** Includes `REPORT_TEMPLATES.EXECUTIVE` (high-level summary with diagrams), `REPORT_TEMPLATES.DETAILED` (full catalog of views, elements, relationships, and user properties), and `REPORT_TEMPLATES.TABULAR` (matrix-focused presentation).
+- **Embedded diagram pictures:** Accepts rendered SVG data URIs or base64 raster images in the `pictures` dictionary keyed by view ID to embed high-resolution diagrams directly into generated documents.
+
+## Sketch Views & Palettes (`SketchView` / `sketchBoxKinds`)
+
+`SketchView` (`src/charting/diagrams/SketchView.js`) implements freeform sketching views (corresponding to Archi's `archimate:SketchModel`). It supports sticky notes, stick-figure actors, groups, freehand lines, and customizable palettes on grid or lined canvas backgrounds.
+
+```javascript
+import { SketchView, SKETCH_BOX_KINDS, DEFAULT_SKETCH_PALETTE } from '@peter.prib/renderengine';
+
+const sketch = new SketchView(model, {
+    name: 'Brainstorming Session',
+    background: SketchView.BACKGROUNDS.GRID, // NONE (0), GRID (1), LINES (2)
+    palette: DEFAULT_SKETCH_PALETTE,
+});
+
+// Custom palette management:
+sketch.addPaletteItem({ id: 'custom-note', name: 'Critical Note', fill: '#ffcccc' });
+const jsonConfig = sketch.exportPalette();
+sketch.importPalette(jsonConfig);
+```
+
+- **Sketch box types:** Native support for sticky notes (`sketch-model-sticky`) and stick figures (`sketch-model-actor`) via `SKETCH_BOX_KINDS`.
+- **Background styles:** Configurable canvas backgrounds including plain (`NONE`), grid paper (`GRID`), and lined notebook paper (`LINES`).
+- **Palette customization:** Dynamically add, remove, reset, export, and import custom sticky colors and presets as JSON configurations.
+- **Archi XML compatibility:** Full bi-directional fidelity with `.archimate` sketch model XML representations (`archimate:SketchModel`, `archimate:Sticky`, `archimate:Actor`).
+
+## Cross-Model Data Lineage & ArchiMate Linking
+
+`ModelMapping` (`src/charting/datamodel/ModelMapping.js`), `DataLineage` (`src/charting/datamodel/DataLineage.js`), and `ArchimateDataLink` (`src/charting/datamodel/ArchimateDataLink.js`) extend the data modeling subsystem (`src/charting/datamodel/`) with enterprise cross-model data lineage and architectural traceability aligned with DMBOK2 and TOGAF.
+
+```javascript
+import { DataModel, ModelMapping, DataLineage, ArchimateDataLink } from '@peter.prib/renderengine';
+
+// 1. Cross-model mapping with attribute-level transformation rules:
+const mapping = new ModelMapping({
+    name: 'Core Banking to EDW',
+    sourceModel: 'OLTP-Core',
+    targetModel: 'EDW-Analytical',
+    entityMappings: [{ sourceEntityId: 'account', targetEntityId: 'dim_account', rule: 'SCD Type 2' }],
+    attributeMappings: [
+        { sourceEntityId: 'account', sourceAttribute: 'bal', targetEntityId: 'dim_account', targetAttribute: 'current_balance', transformation: 'ROUND(bal, 2)' }
+    ],
+});
+
+dataModel.addModelMapping(mapping);
+
+// 2. Trace end-to-end lineage and downstream impact:
+const lineage = dataModel.crossModelLineage();
+const upstreamHops = lineage.traceLineage('dim_account', 'current_balance'); // Upstream provenance
+const downstreamImpact = lineage.traceImpact('account', 'bal');              // Downstream impact
+
+// 3. Connect Data Model entities to ArchiMate enterprise architecture:
+const link = new ArchimateDataLink({
+    dataModelEntityId: 'account',
+    level: 'conceptual',
+    archimateElementId: 'business-obj-account',
+    archimateType: 'business-object',
+});
+dataModel.addArchimateLink(link);
+```
+
+- **DMBOK2 integration:** Enables tracking provenance across conceptual, logical, and physical models, including disparate source and target data stores.
+- **Multi-hop traversal:** Traces multi-hop transformations forwards (`traceImpact`) and backwards (`traceLineage`) across complex data pipelines.
+- **ArchiMate alignment:** Bridges data model entities to ArchiMate Business Objects (Business Layer), Data Objects (Application Layer), and Artifacts (Technology Layer).
+
+## Multi-View Chart Dashboards (`ViewsPart` / `DecisionWorkbenchPart`)
+
+`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:
+
+```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'] }
+```
+
+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
 
 - **`ARCHITECTURE.md`** — module layout, the chart-type catalog mechanics, how to add a new chart type.

package/examples/decision-workbench.html

@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>Decision Workbench</title></head>
+<body style="margin:0;height:100vh;display:flex;font:14px system-ui">
+<!--
+  The Decision Workbench: decisionengine's SADIS recommendation, drawn. A thin host, as data-model.html is:
+  everything it does is DecisionWorkbenchPart's (reading a workbench file, the calendar) and ViewsPart's
+  (a tab per view, its charts and notes, opening a file). Open a workbench file — decisionengine's SADIS
+  Explorer downloads one ("Download for the Decision Workbench"). Runs straight off disk.
+-->
+<script src="../dist/renderengine-workspace.umd.js"></script>
+<script>
+    const { el, registerBuiltinParts, ChartPart, DecisionWorkbenchPart } = window.RenderEngineWorkspace;
+    const ws = document.body.appendChild(el({
+        tag: 'ws-workspace',
+        attrs: { label: 'Decision Workbench', theme: 'light' },
+        style: { flex: '1 1 auto', minHeight: '0' },
+    }));
+    registerBuiltinParts(ws);
+    ws.registerParts([ChartPart, DecisionWorkbenchPart]);
+    ws.addParts([{ id: 'workbench', type: 'decision-workbench', title: 'Decision Workbench' }]);
+    ws.registerPerspective('Decision Workbench', { type: 'part', partId: 'workbench' });
+    ws.activatePerspective('Decision Workbench');
+</script>
+</body>
+</html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peter.prib/renderengine",
-  "version": "0.15.0",
+  "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",
@@ -23,6 +23,7 @@
     "examples/archimate.html",
     "examples/diagram-editor.html",
     "examples/data-model.html",
+    "examples/decision-workbench.html",
     "README.md",
     "documentation/REFERENCE.md",
     "LICENSE"

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);
+    }
 }