@peter.prib/renderengine 0.0.0-stage → 0.1.0

package/REFERENCE.md

@@ -0,0 +1,2159 @@
+# RenderEngine — Reference
+
+One document for "what can I call and what does it take" — every chart/diagram entry point,
+every shared option, every utility, and (the thing none of the older docs cover) the pattern for
+feeding a chart a live, growing-then-capped data source.
+
+This supersedes `README_COMPLETE.md`, `FEATURES_ADDED.md`, `FRAMEWORK_ALIGNMENT.md`,
+`COMPATIBILITY_MATRIX.md`, and `DELIVERY_SUMMARY.md` as the day-to-day API reference — those five
+predate most of the current chart-type set (some still say "8 chart types") and are kept only as
+historical record; see `DOCUMENTATION_INDEX.md`. For *why* things are built the way they are —
+the chart-type catalog pattern, the 3D camera split, per-chart design rationale — see
+`ARCHITECTURE.md` and `CHART_TYPES_ROADMAP.md`. This doc is the *what/how*, not the *why*.
+
+## Setup
+
+```javascript
+import { RenderEngine } from 'renderengine'; // or dist/renderengine.umd.js in a browser
+
+const engine = new RenderEngine(document.getElementById('chart'), { rendererType: 'canvas' }); // or 'svg'
+const headless = new RenderEngine(null); // test mode — every chart call no-ops safely
+```
+
+- **Canvas** — higher raw point-count ceiling, no native DOM hit-testing (`hitTest()` does the
+  work manually).
+- **SVG** — native tooltips/hit-testing, crisp at any zoom, automatic wheel-zoom and
+  drag-empty-space-to-pan on every SVG-rendered chart (`resetView()` clears it back to identity;
+  a 3D-orbit chart's own drag-to-rotate/wheel-to-zoom takes over instead — see below).
+- Both renderers sit behind one primitive API (`rect`/`circle`/`path`/`text`/`line`/…) — every
+  `Chart` subclass is renderer-agnostic, so any `xChart()` call below works unchanged under either.
+
+## The rendering model (read this before the streaming section)
+
+Every chart call — `barChart`, `lineChart`, all of them — starts with `this.renderer.clear()`
+(via the `Chart.render()` base method) and redraws the entire chart from the `data` array you pass
+in. There is no incremental/diff update, no "append one point" method, no built-in windowing.
+Calling the same method again on the same container **replaces** what was there. This is deliberate
+(it's what keeps every one of the 28 chart types simple and renderer-agnostic) but it means
+"streaming"/"bounded window" behavior is entirely a caller-side pattern: keep your own array as the
+source of truth, mutate *that*, then re-call the chart method. See "Dynamically adding data points
+in a bounded window" below for the concrete pattern, straight from a real working implementation
+in this repo.
+
+## Chart types
+
+`src/chartCatalog.js` exports `CHART_CATALOG` (also reachable as `RenderEngine.CHART_CATALOG`) —
+the single source of truth for this table; build a type-picker from it rather than hand-copying
+this list (see `ARCHITECTURE.md`). `engine.renderChartType(key, data, options)` dispatches by
+catalog `key` for you.
+
+| Key | Method | Data shape | Notable options |
+|---|---|---|---|
+| `bar` | `barChart(data, opts)` | `Array<{label, value}>` | `colors`, `showLegend`, `barColor` — one of the types with numeric y-axis ticks/gridlines, see note below |
+| `groupedBar` | `groupedBarChart(data, opts)` | multi-series `Array<{name, values:Array<{label,value}>}>` | `colors`, `legend`, `groupPadding`, `barPadding` |
+| `line` | `lineChart(data, opts)` | `Array<{label, value, error?, errorPlus?, errorMinus?}>` or multi-series `Array<{name, values:[{label,value,error?,...}]}>` | `colors`, `legend`, `zAxis` (isometric depth per series); per-point `error` / `errorPlus` / `errorMinus` draw vertical error bars |
+| `pie` | `pieChart(data, opts)` | `Array<{label, value}>` | `innerRadiusRatio` (>0 = doughnut), `colors`, `legend` |
+| `donut` | `donutChart(data, opts)` | `Array<{label, value}>` | same as `pie` with `innerRadiusRatio` defaulting to 0.5 |
+| `area` | `areaChart(data, opts)` | same as `line` | `stacked`, `colors`, `legend` |
+| `stackedArea` | `stackedAreaChart(data, opts)` | multi-series `Array<{name, values:Array<{label,value}>}>` | same as `area` with `stacked:true` forced |
+| `scatter` | `scatterChart(data, opts)` | `Array<{label, x, y, errorX?, errorY?, errorXMinus?, errorXPlus?, errorYMinus?, errorYPlus?}>` | `colorCol` (color-group by field, or a compiled formula — see below), `referenceLine`; symmetric or asymmetric x/y error bars |
+| `bubble` | `bubbleChart(data, opts)` | `Array<{label, x, y, z}>` | `z` drives size; `colorCol`; `zAxis` (isometric depth) |
+| `heatmap` | `heatmap(data, opts)` | `Array<{x, y, value}>` | `colorScale` (low→high stops), `xLabels`/`yLabels` |
+| `calendarHeatmap` | `calendarHeatmap(data, opts)` | `Array<{date: string\|Date, value: number}>` | `colorScale`, `emptyColor`; one row per calendar day |
+| `gantt` | `ganttChart(data, opts)` | `Array<{label, start, end, progress?, category?, color?}>` | `start`/`end` accept Date/ISO/number; `progress` 0–100 |
+| `streamGraph` | `streamGraph(data, opts)` | multi-series `Array<{name, values:Array<{label,value}>}>` | silhouette baseline; `colors`, `legend` |
+| `radialBar` | `radialBarChart(data, opts)` | `Array<{label, value}>` | angular categories with radial bar length; `colors`, `legend` |
+| `populationPyramid` | `populationPyramid(data, opts)` | `Array<{label, left, right}>` | back-to-back horizontal bars; `leftColor`, `rightColor` |
+| `sankey` | `sankeyDiagram(data, opts)` | `{nodes?: Array<{id,label?,color?}>, links: Array<{source,target,value}>}` | proportional-width flow links; `nodeWidth`, `linkOpacity` |
+| `chord` | `chordDiagram(data, opts)` | same as `sankey` | nodes on a circle with curved chords of proportional thickness |
+| `candlestick` | `candlestick(data, opts)` | `Array<{label, open, high, low, close}>` | `upColor`, `downColor`, `markers` (tooltip annotations) |
+| `stackedBar` | `stackedBarChart(data, opts)` | `Array<{label, values:number[]}>` | `colors` (no built-in legend — a known gap) |
+| `pipe` | `pipeChart(data, opts)` | `Array<{label, value, metric?}>` or multi-series | `metric` tapers line width; `legend` |
+| `radar` | `radarChart(data, opts)` | `Array<{axis, value}>` or multi-series | `colors`, `legend` |
+| `funnel` | `funnelChart(data, opts)` | `Array<{label, value}>` (largest first) | `colors` |
+| `waterfall` | `waterfallChart(data, opts)` | `Array<{label, value, type?:'delta'|'total'}>` | `upColor`, `downColor`, `totalColor` |
+| `histogram` | `histogram(values, opts)` | `number[]` (raw sample, binned internally) | bin count derived, not caller-set |
+| `boxPlot` | `boxPlot(data, opts)` | `Array<{label, values:number[]}>` (raw per-group sample) | quartiles/whiskers computed internally |
+| `density` | `densityChart(data, opts)` | same as `boxPlot` | Gaussian KDE overlay per group; `legend` |
+| `violin` | `violinChart(data, opts)` | same as `boxPlot` | mirrored KDE silhouette per group |
+| `qq` | `qqPlot(values, opts)` | `number[]` | delegates to `scatterChart`; fitted reference line |
+| `lag` | `lagPlot(values, opts)` | `number[]` | `lag` (default 1); delegates to `scatterChart` |
+| `treemap` | `treemapChart(data, opts)` | `Array<{label, value?, children?}>` (hierarchical) | squarified layout, palette by top-level branch |
+| `sunburst` | `sunburstChart(data, opts)` | same hierarchical shape as `treemap` | nested rings by depth |
+| `outline` | `outlineChart(data, opts)` | same hierarchical shape as `treemap`/`sunburst` | `onNodeClick`; collapsible indented list |
+| `gauge-dial` | `dialGauge(value, opts)` | `number` (0–100) | `color`, `title` |
+| `gauge-bar` | `barGauge(value, opts)` | `number` (0–100) | `color`, `title` |
+| `bullet` | `bulletGauge(data, opts)` | `number` or `{value, target?, ranges?:Array<{max,label?,color?}>}` | `target`, `ranges`, `barColor`, `targetColor`, `min`, `max`, `title` |
+| `bar3D` | `barChart3D(data, opts)` | `Array<{label, value, depth?}>` | `depthScale`; fixed-angle isometric, not a real camera |
+| `bubble3D` | `bubbleChart3D(data, opts)` | `Array<{label, x, y, z, size?, category?}>` | real orbit camera — drag to rotate, wheel to zoom |
+| `bar3DOrbit` | `barChart3DOrbit(data, opts)` | `Array<{x, z, value}>` (grid) | real orbit camera |
+| `stackedBar3DOrbit` | `stackedBarChart3DOrbit(data, opts)` | `Array<{x, z, values:number[]}>` (grid) | real orbit camera |
+| `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 |
+
+**`geoMap` note:** the `test/charts.html` demo uses deliberately rough, hand-drawn continental
+polygons so the page needs no external map file. Real use should pass proper GeoJSON-like
+`Polygon`/`MultiPolygon` features; the engine itself has no bundled world geometry and makes no
+external network requests.
+
+**Not in `CHART_CATALOG`** (diagram renderers invoked directly, not "chart a tabular result"
+types — see `ARCHITECTURE.md`):
+
+- `graphDiagram(nodes, edges, opts)` — force-directed node/edge diagram. `nodes:[{id,label,group?,shape?,size?}]`,
+  `edges:[{source,target,label?,weight?}]`. Key options: `onNodeClick`, `onEdgeClick`, `editable` (drag-to-connect,
+  right-click rename/delete/add), `contextMenuItems`/`edgeContextMenuItems`/`canvasContextMenuItems`
+  (replace the built-in right-click menus; support `{label, items:[...]}` submenus), `colors`, `nodeRadius`.
+  Dewey-style hierarchical `id`s (`"1.2.3"`) auto-infer parent/child edges in place of `edges`.
+  **Sizing:** a node's `size` (or, with `sizeBy: 'degree'`, its connection count — no `size` field needed)
+  scales its radius between `minRadius`/`maxRadius` (`sizeScale: 'linear'|'sqrt'`); an edge's `weight`
+  scales its stroke width between `minEdgeWidth`/`maxEdgeWidth` (`edgeWidthScale`) the same way. Either
+  is off by default — nothing changes size until some node/edge actually carries a value (or `sizeBy` is set).
+  **Edge routing:** `edgeRouting: 'straight'|'curved'|'orthogonal'|'polyline'` sets the diagram-wide default
+  (`'straight'` unless set); any edge can override it with its own `routing`. `'curved'` is a bezier that
+  leaves/arrives perpendicular to each node; `'orthogonal'` is a right-angle Manhattan connector;
+  `'polyline'` is a straight line unless another node sits in the way, in which case it steps around it with
+  one waypoint. **Ports:** an edge's `sourceSide`/`targetSide` (`'top'|'right'|'bottom'|'left'`, default
+  `'auto'`) pin where on the node it attaches — that point stays fixed to the node (moves with it) instead of
+  always sliding around to face whatever it's connected to, matching how `fromCol`/`toCol` table links already
+  anchor to a fixed side. Table-to-table FK edges (`fromCol`/`toCol` set, both ends `shape:'table'`) keep
+  their own fixed-column bezier regardless of `routing`/side options. The force-directed *node* layout
+  (springs pulling connected nodes together, mutual repulsion apart) is what `graphDiagram` already runs by
+  default — `edgeRouting` only changes how a connector is *drawn* between wherever the two nodes end up.
+  **Edge selection tolerance:** `edgeHitTolerance` (default 8 SVG units) widens the hit area around edge
+  lines for `hitTest()`, so thin or angled connections are easier to select, hover, or double-click for
+  `onEdgeDoubleClick`. The renderer's own pixel-exact hit is tried first; if it misses, the closest edge
+  within `edgeHitTolerance` is returned.
+  **Manual routing:** with `editable: true`, right-click an edge and choose "Add Waypoint Here" to drop a
+  bend point where you clicked (`_insertEdgeWaypoint`/its pure half `_edgeWaypointsWithInsertion`), drag a
+  bend point to move it, double-click a bend point to remove it — this builds `edge.waypoints` (`[{x,y}, ...]`),
+  which beats every `routing` style outright and threads the line straight through each point in order. Set
+  `edge.waypoints` yourself to hand in a route programmatically, or read it back via
+  `onEdgeWaypointsChange(edge, waypoints)`. (Adding a waypoint used to be double-click-the-line itself — moved
+  to the context menu once double-click was repurposed for `onEdgeDoubleClick`, see below.) The same edge
+  context menu also offers **Invert Direction**, which swaps `source`/`target` in place and fires
+  `onEdgeInvert(edge, oldSource, oldTarget)`.
+  **Undo/redo:** with `editable: true`, every model edit (move, resize, rename, add/delete node,
+  add/delete edge, invert edge, waypoint edits) is recorded in a `CommandHistory` bound to the diagram.
+  Press `Ctrl+Z` / `Ctrl+Y` (or `Ctrl+Shift+Z` for redo) to step through the stack. `historySize` sets
+  the maximum number of retained edits (default `200`), and `onHistoryChange(canUndo, canRedo)` fires
+  whenever the stack changes so a UI can enable/disable its own undo/redo buttons.
+  A host that re-renders the diagram passes its own `history` (a `CommandHistory`): edits are recorded
+  there, so undo outlives each render, and the host binds the undo keys itself (the diagram's own
+  `Ctrl+Z` handler stands down; `historySize`/`onHistoryChange` then belong to the host's history).
+  Recorded commands act on whichever diagram is on screen when they are undone, finding nodes and
+  edges by `id`. Every apply, undo and redo included, reports the result, so a host's copy stays in
+  step:
+
+  | Edit | Hook |
+  |---|---|
+  | move a node | `onNodeMove(nodeId, {x, y})` |
+  | resize a node | `onNodeResize(node)` (its `width`/`height`, or `radius` for a round shape) |
+  | add, move or delete a bend point | `onEdgeWaypointsChange(edge, waypoints)` |
+  | drag an end to pin its side | `onEdgeSideChange(edge, 'source' \| 'target', side)` (`undefined` = automatic again) |
+  | draw an edge | `onEdgeAdd(edge)` on add and redo, `onEdgeRemove(edge)` on undo |
+
+  An `onEdgeAdd` handler may give the new edge an `id`; the command finds it by that id after a
+  re-render.
+
+  ```javascript
+  const history = new CommandHistory();
+  const layout = { a: { x: 80, y: 80 }, b: { x: 300, y: 200 } };
+  const draw = () => engine.graphDiagram(
+      Object.entries(layout).map(([id, p]) => ({ id, name: id.toUpperCase(), ...p })),
+      [{ id: 'ab', source: 'a', target: 'b' }],
+      { editable: true, history, onNodeMove: (id, p) => { layout[id] = p; } },
+  );
+  draw();
+  // ...the user drags A; the page redraws...
+  draw();
+  history.undo();   // A goes back on screen, and onNodeMove puts layout.a back too
+  ```
+  **Grid:** `gridSize` (number, default `0`) snaps dragged and newly-added nodes to the nearest multiple;
+  `showGrid` (boolean, default `false`) draws a light grid behind the diagram. Both are plain `graphDiagram`
+  options, so they work for any editable diagram including ArchiMate. `GraphDiagram.snapToGrid(value, gridSize)`
+  is the pure helper if you need the same rounding rule elsewhere.
+  **Double-click:** dispatches to whatever's under the cursor — `onNodeDoubleClick(node)`/
+  `onEdgeDoubleClick(edge)` fire for a node/edge's line (nothing built-in happens without one; a typical wiring
+  opens the same dialog the right-click menu's "Show/Edit Properties…" does), `onCanvasDoubleClick(point)`
+  fires for empty canvas (SVG/world coordinates — no single object there to edit, so this is the natural place
+  for a diagram/view-level settings dialog instead). Double-clicking an existing waypoint handle still removes
+  it regardless of these — a distinct, precise gesture on a small routing control point, not "the edge" in
+  general. Every context-menu action (built-in or caller-supplied, via `contextMenuItems`/
+  `edgeContextMenuItems`/`canvasContextMenuItems`) now also receives the right-click's SVG/world point as a
+  third argument, `action(subject, engine, point)`.
+  **Edge tooltips:** hovering an edge shows a tooltip with its non-structural ("extra") data, the same
+  "only what isn't already visible on the diagram itself" convention a node's own hover tooltip uses
+  (`_edgeTooltipText`) — a bare `{source,target}` edge with nothing else set shows no tooltip at all. An
+  ArchiMate relationship's `kind` (extra data from `_archimateBuildEdge`'s point of view) always shows this
+  way.
+  **Manual resize:** `resizable: true` (or a node's own `node.resizable`, which overrides the diagram
+  default either way) shows a small handle on hover; dragging it sets `node.radius` — a hard override that
+  beats `sizeBy`/domain sizing, the same way explicit `node.x`/`node.y` already beat computed layout — or,
+  for a `shape:'table'` node, `node.width` (height still comes from column count). The handle's corner
+  defaults to `'top-right'`; `resizeCorner` changes it diagram-wide, `resizeCornerByShape: {shape: corner}`
+  per shape, and a node's own `node.resizeCorner` per node — each level overriding the one before it. See
+  `onNodeResize(node)`.
+  **Icons:** a node's `icon` (a short glyph/emoji string) or `iconUrl` (an image/SVG file or `data:` URI)
+  replaces the plain initials text centred on its shape (`iconPosition: 'center'`, the default) — `iconUrl`
+  wins if both are set; scales with the node's own radius, so it grows/shrinks along with manual resize.
+  `iconPosition: 'corner'` (diagram-wide, or a node's own `node.iconPosition`) instead draws it as a small
+  badge at a corner — same node > `iconCornerByShape` > diagram-wide `iconCorner` precedence as the resize
+  handle's corner, independently configurable (`archimateDiagram` uses this for its type-icon badge). Neither
+  mode applies to `shape:'person'` (already draws its own glyph) or `shape:'table'`.
+  **Box sizing/label position:** a `shape:'rect'` node's own `width`/`height` (either or both) override the
+  usual square-of-radius box, same idea as a table node's `node.width`. `labelPosition: 'inside'` (diagram-wide
+  default `'below'`, or a node's own `node.labelPosition`) left-aligns the label inside the box instead of
+  captioning it underneath, word-wrapped to as many lines as fit the box rather than one overflowing line
+  (`_wrapLabelLines`, measured with the renderer's `measureText(text, font)` — a 2D canvas context in the SVG and
+  Canvas renderers, an average-character estimate where there is none), keeping clear of a corner icon in a top
+  corner — meant for exactly this wider-than-tall case (`archimateDiagram` sets both). A node's own text style:
+  `textColor`, `fontFamily`, `fontSize` (`"12px"` or `"9pt"`), `fontWeight`, `fontStyle`; `strokeDasharray` dashes
+  its outline (an ArchiMate Grouping is drawn dashed). `options.edgesOnTop` draws lines over boxes instead of under
+  them, as ArchiMate tools do (`archimateDiagram` sets it), so a line into an element drawn inside another stays
+  visible.
+  **Label alignment:** `textAlign` (`'left'`|`'center'`|`'right'`) and `verticalAlign` (`'top'`|`'middle'`|`'bottom'`)
+  control the label's placement. Per-node values override diagram-wide `options.textAlign`/`options.verticalAlign`.
+  Defaults preserve existing behaviour: `labelPosition:'inside'` defaults to top-left; `'below'` defaults to
+  horizontal centre. `verticalAlign` only affects inside labels.
+  **Notes / annotations:** a node with `shape:'note'` renders as a yellow sticky note with a folded corner,
+  suppresses the centred icon/initials, and wraps its label inside. `archimateDiagram` accepts an `annotations`
+  option (array of `{id?, label/name, x, y, width?, height?}`) — each annotation becomes a note node on the
+  diagram but is not validated as an ArchiMate element, so notes are saved with the view without affecting the
+  model. Any plain `graphDiagram` can also use `shape:'note'` directly.
+  **Importable images:** a node with `shape:'image'` renders its `iconUrl` as an SVG `<image>` filling the node's
+  `width`/`height` (`preserveAspectRatio` defaults to slice; set `imagePreserveAspectRatio` on the node or
+  diagram options to change, e.g. `'xMidYMid meet'`). Image nodes suppress the usual centred icon/initials and
+  caption label. An optional `href` property turns the image into a clickable hyperlink (opened on click).
+  `test/charts.html` lets users add images via a file picker, drag-and-drop, or paste, and the node Properties
+  dialog exposes the link field. `RenderEngine.importArchiXML()` maps Archi `DiagramModelImage` elements to
+  `shape:'image'` and preserves their `iconUrl`/`href`.
+  **Label resolution** (`_resolveNodeLabel`, used everywhere a label renders — the box/caption, tooltip, table
+  header, keyword search): `label` may be a plain string (used as-is), a function `(node) => string` (called
+  at render time, the same "may be a function" convention `contextMenuItems`' own `label` already uses), or a
+  string with `{field}` placeholders (each replaced with that field's own value off the node — plain
+  substitution, not a parser, e.g. `'{name} ({type})'`). An empty/unset `label` falls back to `node.name`.
+  **More arrowheads/line styles:** beyond `'arrow'|'circle'|'tee'|'none'`, `arrowhead` (and a second,
+  independent `arrowheadStart` for the source end — e.g. a diamond at the "whole" end while the target end
+  carries none) also accepts `'diamond'|'diamond-hollow'|'triangle-hollow'|'open-arrow'`. `lineStyle:
+  'solid'|'dashed'|'dotted'` generalizes the older boolean `dashed` (still honored when `lineStyle` isn't set).
+  **Node/edge properties:** `showPropertiesDialog(subject, engine, kind, {onSave})` and
+  `showDiagramPropertiesDialog(engine, {onSave})` are **shipped** (`src/propertiesDialog.js`, exported from the
+  package root) — wire them to `onNodeDoubleClick`/`onEdgeDoubleClick`/`onCanvasDoubleClick` or a context-menu
+  item and a diagram becomes editable. They used to exist only as ~400 lines inside `test/charts.html`, which
+  meant a consumer had to copy a demo to get double-click editing, so nobody did. `onSave(subject, changedKeys)`
+  fires after the subject is updated and the diagram re-rendered — that's where a consumer persists. The
+  decisions are pure and exported separately for reuse or testing: `propertyRowsFor` (which fields, which
+  section, which control), `coerceFieldValue` (read a string back as the type the field held), `derivedRefreshPlan`
+  (may a derived colour/icon be refreshed silently), `LAYER_CHOICES`, `NODE_SECTIONS`.
+  **Typed user-defined properties:** nodes and edges may carry `properties: [{name, type, value}]` where `type`
+  is `'string'`|`'integer'`|`'boolean'`|`'date'`. The Properties dialog shows these in their own section, lets
+  the user add/remove/edit them, and coerces values by type. `RenderEngine.NODE_STRUCTURAL_KEYS` and
+  `EDGE_STRUCTURAL_KEYS` include `'properties'` so they don't appear as untyped "extra data" tooltip lines.
+  A host that adds its own bookkeeping fields to the nodes and edges it hands in lists them in the
+  `internalKeys` option (an array); they are then left out of tooltips, the keyword filter and the
+  Properties dialog's "Other" section like the built-in fields. `graphDiagram.structuralKeys('node' | 'table' |
+  'edge')` returns the combined set. ArchiMate passes `ArchimateView.PROJECTION_KEYS` (`elementId`,
+  `relationshipId`, `diagramInstanceId`, `visible`, `zIndex`, `viewObject`).
+  Archi native `.archimate` import/export round-trips properties: import converts flat `<property key="..." value="..."/>`
+  elements to typed `'string'` entries; export stringifies typed values back to flat key/value pairs.
+
+  There is still no built-in "Show/Edit Properties" **menu item** — `contextMenuItems`/
+  `edgeContextMenuItems` are plain hooks a caller wires up themselves; `RenderEngine.NODE_STRUCTURAL_KEYS`/
+  `EDGE_STRUCTURAL_KEYS` (used internally to keep built-in fields out of the auto tooltip's "extra data"
+  lines) are public statics for exactly this — see the `showPropertiesDialog` example and its use in the
+  Editable + Value Sizing demo in `test/charts.html` for a small dialog that lists every field on a clicked
+  node/edge (built-in and caller-added alike) as an editable input, and `showDiagramPropertiesDialog` (wired
+  to `onCanvasDoubleClick`/a canvas context-menu item in the same demos) for a diagram/view-level settings
+  dialog — `edgeRouting`, plus (for an ArchiMate diagram) the live `iconChoiceIndex` setting via
+  `_archimateSetIconChoiceIndex`. In that Properties dialog's own layer/type cascade (`test/charts.html`),
+  changing an ArchiMate element's `layer` clears and refocuses its `type` field — every official type belongs
+  to exactly one layer, so the old type essentially never still applies once the category changes.
+- `graphDiagram3D(nodes, edges, opts)` — same data shape and sizing options, real orbit camera instead of
+  2D force layout (node radius/edge width are additionally scaled by the camera's own perspective factor).
+- `archimateDiagram(elements, relationships, opts)` — ArchiMate-notation diagram (Archi/archimatetool.com-style):
+  a thin transform over `graphDiagram` that builds rect nodes/edges with per-layer pastel fill, the label
+  inside the box, a small type-icon corner badge, and the 11 official relationship line/arrowhead notations,
+  then calls `graphDiagram` with them — every `graphDiagram` capability (drag, resize, routing, right-click
+  menus, editable add/rename/delete, ...) still applies.
+
+  **Archi native `.archimate` import/export:** `RenderEngine.importArchiXML(xml, viewId?)` parses an Archi
+  native XML file and returns `{ elements, relationships, options }` ready for `archimateDiagram()`. It maps
+  ArchiMate elements/relationships, view `DiagramObject` children (bounds, font, line thickness), and the
+  visual objects `DiagramModelNote`, `DiagramModelGroup`, `DiagramModelImage`, `DiagramModelReference`,
+  plus `SketchModelSticky`/`Actor` and `CanvasModelBlock`/`Sticky`/`Image`. Archi stores a nested visual's bounds
+  relative to its parent (a group, a group in a group, or an element drawn inside another element); import
+  turns them into positions on the view, so an element at `x="10"` inside a group at `x="100"` lands at 110.
+  A group inside a group keeps its `parentId`. On export, a view writes the groups drawn on it (those
+  with bounds in its `folderLayout`; `view.placedFolders`) nested as they are, each element inside the
+  group its folder is drawn as (`view.placedFolderOf(elementId)`, the nearest drawn ancestor), bounds
+  relative to the group. A folder that only exists in the model tree is not written as a group.
+  `model.allFolders()` lists every folder after its parent, read from `parentId`.
+  `RenderEngine.exportArchiXML(model, views)`
+  serializes back to Archi native XML, including element and relationship names, documentation and
+  properties. `views` are `{id, name, children}`; `fromArchimateView(view)` builds `children` from an
+  `ArchimateView`: one visual per instance, referencing the model element and relationship ids, with
+  bounds, bend points, and view-only notes and images.
+  The XML is what Archi 5.8 itself reads and writes (checked by opening our files in Archi and reading
+  back what it saved): all nine top-level folders in Archi's order (Archi fails to open a model with a
+  view but without them), elements as ArchiMate 3.2 classes (Archi knows no other: an ArchiMate 4
+  `process` in the application layer is written as `ApplicationProcess`, see `archimate32Type`),
+  relationships as `<Kind>Relationship` (a directed association is `AssociationRelationship
+  directed="true"`), groups and notes as `archimate:Group`/`archimate:Note` (a note's text in a
+  `<content>` element), each line naming its relationship as `archimateRelationship`, and each box
+  listing its incoming lines in `targetConnections` (without them Archi leaves some lines undrawn).
+  Import reads Archi's names and the older ones earlier versions of this module wrote.
+
+  **What an import keeps.** Checked against a real Archi model (canvas, sketch and ArchiMate views, nested
+  folders, styles, a legend, hints, report properties): Archi renders our export of it pixel-for-pixel as it
+  renders the original, and re-saving our export in Archi gives back the original model.
+  - **Positions.** The renderer places a node by its centre; Archi keeps a box's top-left corner. Import
+    centres each box (`x + width/2`), export takes the corner back (whole pixels, so a centre comes back
+    within half a pixel).
+  - **One instance per box.** Each box Archi draws is an instance with its own size and style, so the same
+    element twice on a view is two instances; each line joins the two instances it joins. A view shows what
+    Archi drew on it and nothing else (no "all elements", no lines Archi did not draw).
+  - **All views.** Views in sub-folders of Views, and canvas (`canvas:CanvasModel`) and sketch views: canvas
+    blocks and stickies and sketch stickies are view-only boxes with their text, colours and picture; a canvas
+    box without a border colour has no border; a sticky's text is centred vertically, as Archi draws it.
+  - **Style.** Archi's attributes `fillColor`, `lineColor`/`borderColor`, `fontColor`, `font` (SWT FontData:
+    name, size in points, bold/italic), `lineWidth`, `textAlignment` (centred when absent) and `textPosition`
+    become the instance's `appearance`.
+  - **Plain lines.** A line with no relationship (a note to an element, a canvas connection) is a
+    `ViewConnectionInstance` on the view, its look from Archi's `type` bits (solid/dashed/dotted; filled, hollow
+    or line arrows at either end). The validator leaves it alone.
+  - **Everything else, written back.** What the model does not use is kept on the item (`instance.archi`,
+    `view.archi`, `model.archi`, a concept's `archi`) and written back unchanged: other attributes (`hintTitle`,
+    `imagePosition`, `accessType`, `viewpoint`, a line's `locked`, ...), other child elements (`hintContent`, `notes`,
+    features such as a legend's), the original style (each attribute written as it was until its meaning is
+    changed), Archi's ids for boxes and lines, the stacking (document) order, a box's place inside another box
+    (canvas stickies in their blocks), the model-tree sub-folders (`archiFolder`), picture paths in the
+    archive, the model's id, `documentation` (Archi's purpose) and properties, and view properties (keys may
+    repeat). A copied view's boxes get new ids. Text keeps its spaces, and a CR is written as `&#xD;`.
+  - **Locks and groups.** A box's lock is the view's arrangement: Archi's `locked="true"` on import, and on
+    export where Archi can lock (canvas boxes); elsewhere (ArchiMate elements, notes, groups, images) Archi has
+    no lock, so it is the feature `renderengine.locked`, which Archi keeps. A logical group is the feature
+    `renderengine.group` (the group's id) on each member.
+  - **Canvases and templates.** A canvas (`canvas:CanvasModel`) is a `CanvasView`, its own kind of
+    `ArchimateView` (`view.constructor.kind === 'canvas'`; `ArchimateModel.registerViewType(archiViewType, Class)`
+    maps an Archi view type to a view class). A canvas kept to copy from is a template (`view.template`);
+    Archi has no such flag, so it is the view feature `renderengine.template` (`ARCHI_TEMPLATE_FEATURE`),
+    which Archi keeps. A copied view keeps its boxes inside their blocks.
+  - **Types Archi lacks.** Archi has a class for each ArchiMate 3.2 element type only, and will not open a
+    file naming another. An ArchiMate 4 type is written as its 3.2 type; any other (an IT icon type such as
+    `load-balancer`, or a custom type) as the nearest 3.2 type by layer and aspect (`archiElementType`,
+    `NEAREST_ARCHI_TYPE`: a technology device is a Node, a data store an Artifact, and so on), with its own type
+    kept as the feature `renderengine.type` and an Archi specialization named after it ("Load Balancer"), so
+    Archi users see it too. Import gives the type back and drops that specialization. An element Archi had
+    already given a specialization keeps its own.
+  - **No colour.** A box with no fill (`fillColor: 'none'`) is Archi's `alpha="0"`, and one with no outline
+    (`strokeColor: 'none'`) is Archi's `lineAlpha` feature at 0, both ways.
+  Bend points are written as Archi writes them, offsets from the centres of the two connected boxes
+  (`<bendpoint startX startY endX endY/>`, centres taken in whole pixels as Archi does). On import, bend
+  point i of n sits at `(1 - w)(sourceCentre + start) + w(targetCentre + end)` with `w = (i + 1)/(n + 1)`;
+  an `x`/`y` bend point from an earlier export is still read as a point on the view. An element saved
+  at Archi's default size (`width="-1"`) is 120 x 55 (a group 400 x 140, a note 185 x 80).
+
+  ```js
+  // Archi wrote <bendpoint startX="40" startY="13" endX="-160" endY="-87"/> on a line from a box at
+  // (0,0,120,55) to one at (200,100,120,55):
+  toRenderEngineModel(parseArchiModel(xml)).relationships[0].waypoints;   // → [{ x: 100, y: 40 }]
+  ```
+  `toArchimateModel(parseArchiModel(xml))` reads all of that back, keeping notes and images on their
+  view (not as model elements) and the model's `name`.
+
+  **Archi files with pictures** are zip archives: the XML as `model.xml` and each picture under
+  `images/`, which `imagePath` names. `parseArchiFile(input)` takes a file as text, bytes or an
+  `ArrayBuffer`, plain or archived, and returns what `parseArchiModel` does with each archived picture
+  turned into a `data:` URL. `toArchiFile(model, views)` takes what `toArchiXML` does and returns
+  `{ data, archive, mimeType }`: plain XML when no visual has a `data:` picture, otherwise an archive
+  (bytes) with the pictures under `images/`, once each. `src/archimateArchive.js` owns the bridge;
+  `ZipArchive` (`src/zip/`, with a raw DEFLATE decoder and CRC-32, no dependencies) reads stored and
+  deflated entries, which is what Archi writes, and writes stored ones.
+
+  ```js
+  const file = toArchiFile(model, views);           // { data, archive: true, mimeType: 'application/zip' }
+  const back = toArchimateModel(parseArchiFile(file.data));
+  ```
+
+  **Open Group Exchange Format** (ArchiMate Model Exchange File Format 3.1), the standard route to and
+  from other ArchiMate tools (Archi, Sparx EA, BiZZdesign, ...). `parseExchangeModel(xml)` gives what
+  `parseArchiModel` gives, and `toExchangeXML(model, views)` takes what `toArchiXML` takes, so both share
+  the Archi mapping; `toArchiExport(model)` gives an `ArchimateModel` as `[modelData, views]` for any of the
+  writers. `src/archimateExchangeFormat.js` owns what differs:
+  - **Positions.** A node's x/y and a bendpoint are on the view; Archi's are relative to the parent box and
+    offsets from the line's ends. The format allows no negative position, so a view reaching left of or
+    above 0 is moved right and down as a whole (as Archi exports).
+  - **Concepts.** Properties name a property definition (one per key). An Or junction is Archi's junction of
+    type "or"; an access relationship's `accessType` (Read, Access, ReadWrite; Write when absent) and an
+    influence's `modifier` are Archi's `accessType` and `strength`; `isDirected` is a directed association.
+    A type Archi lacks is written as its nearest 3.2 type, with its own kept in the property
+    `renderengine.type` (`EXCHANGE_TYPE_PROPERTY`), which import reads back.
+  - **Folders** are organizations: an item per Archi top-level folder, holding the sub-folders. On import an
+    outer item named as one of Archi's folders is that folder; any other outer item is a sub-folder.
+  - **Views.** Only ArchiMate diagrams: the format has no canvases or sketches, which are not written. A
+    group is a Container, a note (or picture, or view reference) a Label. A viewpoint is the format's name
+    ("Business Process Cooperation", `EXCHANGE_VIEWPOINTS`) and Archi's id (`business_process_cooperation`).
+  - **Style.** Colours are r/g/b with a 0-100 alpha (0: no fill or no line), the font a name, size and
+    `style` ("bold italic"). Only what a box or line sets itself is written; the reading tool draws the
+    rest with its own defaults.
+  - **Identifiers** must be xs:IDs: an id that is one is kept, any other (`1`, `a b`) is made one
+    (`id-1`, `id-a_b`) and every reference follows it.
+
+  Checked with Archi 5.8: Archi validates the files against the schema and opens them; a file Archi
+  exported comes back through `parseExchangeModel`, `toArchimateModel`, `toArchiExport` and
+  `toExchangeXML` identical to Archi's own import of it. Archi's importer ignores `lineWidth`.
+
+  ```js
+  const model = toArchimateModel(parseExchangeModel(xml));   // a file from Archi, Sparx EA, BiZZdesign, ...
+  const out = toExchangeXML(...toArchiExport(model));        // and back
+  ```
+
+  `src/archimateArchiFormat.js` owns the pure
+  mapping and the tiny dependency-free XML parser (uses `DOMParser` in browsers; under Node, a fallback
+  that decodes entities and character references, takes either quote, and skips comments and CDATA).
+  **CSV import/export:** `RenderEngine.exportModelCSV({elements, relationships})` returns `{ elementsCSV,
+  relationshipsCSV }` for spreadsheet editing; `RenderEngine.importModelCSV(elementsCSV, relationshipsCSV)`
+  parses them back into element/relationship objects. Columns are `id,name,type,layer,documentation,properties`
+  for elements and `id,source,target,kind,label,documentation,properties` for relationships. The `properties`
+  column holds the typed property array as JSON. `src/archimateCSV.js` owns the pure CSV helpers and is also
+  exported directly (`exportElementsCSV`, `importRelationshipsCSV`, etc.).
+
+  **`src/archimate.js`** owns the actual notation data — `ArchimateLayer`/`ArchimateElementType`/
+  `ArchimateRelationshipType` instances (all also re-exported from the package root, and as
+  `RenderEngine.ArchimateNotation`/`.ArchimateLayer`/etc. statics for convenience), queried through the
+  `ArchimateNotation` registry rather than archimateDiagram's own flat string-keyed maps — deliberately OO
+  because a type's layer is then a real object reference (`type.layer`), not a name in one lookup table and
+  the same name in a second, separate one that could silently drift apart. `ArchimateNotation.typesInLayer
+  (layerName)` is the query that relationship supports directly — the dependency a "type" control that must
+  narrow to match a chosen "layer" needs (see the cascading `layer`/`type` fields in the Properties dialog in
+  `test/charts.html`, which read exactly this both ways: picking a layer narrows type's own suggestions to
+  that layer's types; picking/typing a recognised type snaps layer to match it).
+
+  Every element type and relationship type also carries a short `description` for authoring UIs:
+  `ArchimateNotation.describe(typeName, version)` returns an element's description, and
+  `ArchimateNotation.describeRelationship(kind)` returns a relationship's description (both undefined for
+  unrecognised names). The Properties dialog in `test/charts.html` shows these in a "?" tooltip next to the
+  `type` and `kind` fields. `LLM_ARCHIMATE_GUIDE.md` packages the same catalog plus prompting guidance for
+  LLMs that generate diagram data.
+
+  **IT / infrastructure extension types.** `archimateDiagram` also recognises a set of practical IT concepts
+  that ArchiMate does not name directly: `firewall`, `laptop`, `server`, `database`, `table`, `file`, `folder`,
+  `container`, `pod`, `load-balancer`, `cloud-region`, and more (see `src/itIcons.js`/`RenderEngine.ITIconNotation`).
+  These resolve to the `technology` layer with the correct `aspect` (`active-structure` for devices/services,
+  `passive-structure` for data/files) and their own icon, so they behave like first-class ArchiMate elements in
+  diagrams, validation, and the construction UI. They are treated as extended/custom types, not official
+  ArchiMate, and the validator uses their aspect/layer for relationship advice.
+
+  `elements:[{id,label,layer?,type?,aspect?,icon?,iconUrl?}]` — `layer` (any string, not just the 7 official
+  names) picks the fill colour (`ArchimateLayer#color`, extendable via `opts.layerColors`), or derives from
+  `type` when `layer` is omitted: first checked against the full ~55 official ArchiMate element names
+  (`ArchimateNotation.elementType(type)?.layer` — most, e.g. `'goal'`/`'node'`/`'resource'`, do NOT start
+  with their own layer's name), then the prefix of `type` before its first `-` for anything not in that
+  catalog (`type:'business-my-widget'` → layer `'business'`, for ANY `'<layer>-whatever'` string, official
+  name or not). **Icons:** an element's own `icon`/`iconUrl` always wins; otherwise a recognised `type`'s own
+  representative icon (`ArchimateElementType#icon` — a glyph echoing the real pictogram's idea, e.g. Goal's
+  🎯, Location's 📍, Application Component's 🧩 — not a redraw of the actual vector artwork); otherwise a
+  generic per-layer one (`ArchimateLayer#defaultIcon`) — either can be overridden diagram-wide via
+  `opts.defaultIcons`. **Badges are the notation's own glyphs, not emoji.** In the real notation a corner
+  badge IS the element's standalone glyph drawn small — a Business Process is a box with a little arrow in
+  the corner, and that same arrow alone is the element without its box. So the badge is rendered from the
+  type's own `notationShape` (as line art, via the generic `node.iconShape` graphDiagram field), one vector
+  glyph per type used at two sizes. Every official type in both catalogs has one, so ArchiMate rendering
+  never falls back to an emoji; `opts.iconSet` (`'glyph'|'emoji'`, default `'glyph'`) switches the whole
+  diagram to the Unicode stand-in set instead, and THAT is where `iconChoiceIndex`/`iconChoices` apply — the
+  standard glyph has no alternatives to choose between, the emoji do. **Icon choice sets:** a type doesn't offer just the one icon —
+  `ArchimateElementType#iconChoices`/`ArchimateNotation.iconChoices(typeName)` return a deduplicated list with
+  the official ArchiMate-standard glyph always at index 0, followed by a few generic aspect-wide alternatives
+  (`active-structure`/`behavior`/`passive-structure`/`motivation`/`other` — e.g. behavior types alternate
+  between ▶️/🔄/⚡) and finally the type's own layer default; an unrecognised/absent type falls back to
+  `GENERIC_ICON_CHOICES` (every aspect's alternatives pooled together). Which choice is used as an element's
+  *default* (when it sets no `icon` of its own) is a diagram-wide setting, `opts.iconChoiceIndex` (default
+  `0`, the standard icon) — an out-of-range index falls back to choice 0 rather than throwing. This is what a
+  "choice of icons per type, with the ArchiMate-standard one as the default" UI (a `<select>` of
+  `iconChoices(type)`, e.g. the Properties dialog's own `icon` field in `test/charts.html`) is built on; an
+  element's own explicit `icon` still always wins over any diagram-wide choice. `iconChoiceIndex` isn't just a
+  one-shot build option — `engine._archimateSetIconChoiceIndex(newIndex)` changes it LIVE after the diagram's
+  already drawn, re-deriving the icon for every node that's still on its old auto-derived default (same "was
+  it ever customised" check the Properties dialog's own layer/type-change handler uses) and leaving any
+  individually-picked icon alone; `test/charts.html`'s `showDiagramPropertiesDialog` (opened via
+  `onCanvasDoubleClick` or a canvas context-menu item) is a small UI for this. It's kept on `engine.
+  _archimateOptions`, not on `_chartState` — `archimateDiagram`'s own settings (`iconChoiceIndex`/
+  `layerColors`/`defaultIcons`/`relationshipStyles`) aren't part of `graphDiagram`'s flat `options` (they're
+  destructured out before its own options are built), and `_chartState` itself gets overwritten wholesale on
+  every `graphDiagram`/`_rerenderGraph` call, so anything meant to survive a redraw lives on the engine
+  instance instead. **Box corner style**
+  (`ArchimateElementType#cornerStyle`): every Motivation-layer
+  element is chamfered (all 4 corners cut at 45°) regardless of anything else; `'behavior'` aspect
+  (Process/Function/Service/Event/Interaction-like) gets rounded corners — an explicit `element.aspect` wins,
+  else a recognised `type`'s own aspect (so `type:'business-process'` is rounded with zero extra config);
+  everything else is sharp (correct for active/passive-structure elements). An element's own `cornerStyle`
+  (`'sharp'|'rounded'|'chamfered'`) overrides all of that directly — and works on any plain `graphDiagram`
+  `shape:'rect'` node too, not just via `archimateDiagram`.
+
+  `relationships:[{source,target,kind?}]` — `kind` (`composition`/`aggregation`/`assignment`/`realization`/
+  `specialization`/`serving`/`access`/`influence`/`triggering`/`flow`/`association`) picks the notation
+  (`ArchimateRelationshipType`, extendable via `opts.relationshipStyles`); an explicit `lineStyle`/
+  `arrowhead`/`arrowheadStart` on one relationship still overrides its kind's default.
+
+  **Standard alignment (advisory warnings, not blocking).** `archimateDiagram` validates the model against
+  the ArchiMate metamodel and warns where it deviates. `opts.invalidRelationships` says how an invalid
+  relationship shows: `'highlight'` (the default: a red dashed line and a tooltip), `'tooltip'` (the warning
+  on hover only) or `'off'` (nothing checked); `opts.validate: false` also turns checking off. The ArchiMate
+  editor takes it from the "Invalid relationships" setting, which a diagram, its model or the tool sets
+  (see the settings cascade below). Warnings are delivered three ways:
+  - `opts.onValidationWarning(warning)` is called once per warning during render;
+  - `engine._archimateWarnings` holds the full list after render;
+  - invalid relationships carry a tooltip explaining the issue, and with `'highlight'` a red dashed stroke.
+  Relationships between ArchiMate types are checked against the specification's own relationship table
+  (The Open Group, ArchiMate 3.2 Specification, Appendix B; `ArchimateValidator.specificationKinds`), an
+  ArchiMate 4 type looked up as its 3.2 type. `src/archimateRelationshipTable.js` holds the table, generated
+  by `scripts/generate-archimate-relationships.mjs` from the machine-readable copy Archi ships. Custom and IT
+  types, which the table does not name, fall back to `ArchimateValidator.RULES`: data, each rule naming its
+  `kinds` and constraining `fromAspect(s)`, `toAspect(s)`, `aspects`, `sameAspect`, `sameLayer`, `fromTypes`
+  or `toTypes`. Also checked: v4 Common Domain elements (`process`/`function`/`service`/`interaction`/`event`)
+  needing an explicit `layer`, and retired v3.2 types used under v4.
+
+  ```js
+  ArchimateValidator.allowedKinds({ type: 'business-actor' }, { type: 'business-role' }, '4');
+  // → ['assignment', 'serving', 'triggering', 'flow', 'association', 'association-directed']
+  ``` `RenderEngine.ArchimateValidator` exposes the same checks for construction UIs:
+  `ArchimateValidator.validateModel(elements, relationships, version)`,
+  `ArchimateValidator.validateRelationship(source, target, kind, version)`, and
+  `ArchimateValidator.allowedKinds(source, target, version)` — the latter powers the filtered relationship-kind
+  dropdown in `test/charts.html`'s Add Edge and Edge Properties dialogs.
+
+  **Specializations.** `RenderEngine.ArchimateSpecializationRegistry` (src/archimateSpecializations.js)
+  stores user-defined specializations (`{id, name, baseTypes[], icon?, color?, description?}`). Tag an
+  element with `specialization: '<id-or-name>'` and `archimateDiagram` applies the specialization's icon
+  and colour unless the element already has its own. `registry.serialize()` / `registry.deserialize(array)`
+  make persistence trivial; `test/charts.html` persists the catalog in `localStorage` and exposes a
+  "Specializations…" manage dialog.
+
+  **Colours, glyphs and line weights are read out of the spec's own artwork, not eyeballed.** The
+  specification PDF embeds its "Appendix A: Summary of Language Notation" figures as LOSSLESS PNGs, so the
+  palette below is the literal pixel value of each fill: Business `#FFFFAF`, Application `#AFFFFF`,
+  Technology and Physical both `#AFFFAF` (the spec draws them the same green), Strategy `#F5DEAA`,
+  Motivation `#CCCCFF`, Implementation & Migration `#FFE0E0`, Location `#FFBF80`. A few types carry a colour
+  their own layer doesn't share — Plateau/Gap are green (`#E0FFE0`) among the pink Implementation elements,
+  Grouping is unfilled — so `ArchimateElementType#ownColor` overrides the layer fill for those (element
+  `color` > `opts.layerColors` > `ownColor` > layer). Elements are drawn with a thin BLACK outline
+  (`strokeColor: '#000000'`, `strokeWidth: 1.2` — both plain graphDiagram node fields, defaulting to the
+  usual white 2px elsewhere), which is what the real notation uses; the white stroke graphDiagram uses to
+  separate overlapping blobs is a large part of why an ArchiMate diagram drawn with plain defaults reads as
+  much brighter and softer than the spec. The relationship notations were checked glyph-by-glyph against the
+  same appendix — all 11 kinds, plus the directed-association variant (`association-directed`, a single-barb
+  `open-arrow-half`) and both junction connector forms the figure shows alongside them.
+
+  **ArchiMate version: `opts.archimateVersion` (`'3.2'|'4'`, default `'4'`, `ArchimateNotation.versions()`).**
+  ArchiMate 4 retires 19 of 3.2's element types (`src/archimate.js`'s own doc comment has the full reasoning):
+  fifteen layer-specific behavior types (`business-process`/`application-process`/`technology-process`, and
+  the same 3-layer split for `function`/`service`/`interaction`/`event`) collapse into five layer-INDEPENDENT
+  "Common Domain" types (`process`/`function`/`service`/`interaction`/`event` — `ArchimateElementType#layer`
+  is `null` for these five; the real layer must come from the element's own `layer` field, not the type name);
+  four more (`contract`, `representation`, `constraint`, `gap`) are retired outright, each replaced by an
+  existing type. Under the `'4'` default, every element is first run through `ArchimateNotation.
+  migrateElementToV4` — a direct mirror of a jArchi "Migrate Model Elements from ArchiMate 3.2 to ArchiMate 4"
+  script's own two mapping tables — a no-op for any other type (most of the ~55, e.g. `business-actor`,
+  `application-component`, `goal`, `node`, are identical in both versions and all 11 relationship notations
+  are unchanged), so 3.2-authored `elements` data still renders correctly, auto-upgraded and tagged with its
+  own migration provenance as plain extra data: `ArchiMate4_Domain` (the original layer, e.g. `'Business'`)
+  + `MigratedFrom` (the original type) for a behavior consolidation, or `LegacyType`/`Type` + `MigratedFrom`
+  for a retired type — both visible in the hover tooltip/Properties dialog like any other custom field, same
+  as `kind` already is for a relationship. An element that already carries its own `layer` keeps it; one that
+  doesn't gets it filled in from the migration's own knowledge of where it used to live (needed since a
+  Common Domain type's own layer is `null` — without this, a migrated element with no explicit `layer` would
+  silently fall through to 'other'). Under `'3.2'`, no migration happens at all — every `ArchimateNotation`
+  lookup `_archimateBuildNode`/`_archimateBuildEdge` make (`elementType`, `elementTypeNames`, `typesInLayer`,
+  `iconChoices`, `elementLayer` — all take an optional `version` parameter, default `'4'`) resolves against
+  the original 3.2 catalog instead. See the ArchiMate Diagram demo's own version `<select>` in
+  `test/charts.html`, which re-runs `archimateDiagram` over the SAME `elements`/`relationships` for either
+  choice (not a live bidirectional toggle — a v4-migrated type like `'process'` was never a v3.2 catalog entry
+  to begin with, so round-tripping back through the ALREADY-migrated data wouldn't resolve correctly; picking
+  a version is a "how should this diagram be built" choice, made fresh from the original input each time).
+
+  **Distinct notation shapes: `opts.useDistinctShapes` (boolean, default `false`).** The plain box + corner
+  icon isn't the only ArchiMate notation — the spec's own Appendix A ("Summary of Language Notation") gives
+  many types a real distinct outline instead (Process = a plain arrow, Interface = a lollipop, Node = a 3D
+  cube, ...). `ArchimateElementType#notationShape` (`src/archimate.js`) names that shape (a `graphDiagram`
+  `shape` value — see `_nodeShapeEl`) for every type that has one; `undefined` for a type the spec only ever
+  shows as a plain box (Business Object, Work Package, Deliverable, ...), or whose real glyph is still too
+  compound to render cleanly as a single node shape here (System Software's box+circle is the one gap left).
+  32 shapes implemented, verified against rendered output (not just the spec image) — see
+  `test/archimate.test.js`'s own `notationShape` describe block for the full type→shape mapping:
+  `arrow` (Process), `chevron` (Function, points up with a notched bottom — distinct from arrow, which points
+  right), `half-circle` (Interaction), `flag` (Event/Value Stream/Implementation Event), `pill` (Service, a
+  fully-rounded stadium box), `double-circle` (Collaboration), `lollipop` (Interface), `cylinder` (Role/
+  Stakeholder — a HORIZONTAL drum, left/right elliptical caps, not top/bottom), `cube` (Node, a real 3-face
+  isometric box), `target` (Goal/Outcome/Course of Action — a bullseye with a dark centre dot), `hexagon`
+  (Material — flat top/bottom, pointed left/right), `pin` (Location), `cloud` (Meaning), `document` (Artifact),
+  `parallelogram` (Requirement), `constraint` (Requirement's parallelogram plus its own internal divider
+  line), `gear` (Equipment — two overlapping cogs), `ellipse` (Value), `battery` (Resource), `component`
+  (Application Component — a box with two connector tabs on the left edge), `factory` (Facility), `device`
+  (Device — a monitor on a stand), `steps` (Capability — an ascending staircase), `wheel` (Driver — a
+  steering wheel), `magnifier` (Assessment), `stack` (Plateau — three bars), `gap-circle` (Gap — a circle
+  crossed by two lines), `principle` (Principle — a rounded square with "!"), `double-arrow`
+  (Communication/Distribution Network), `double-arrow-dashed` (Path), `junction` (a small solid dot, not the
+  plain default circle — no centred initials text), plus the existing `person` (Business Actor). Same
+  "representative, not pixel-perfect" calibration as the corner-badge icons — cross-checked against the spec,
+  a few curves/angles simplified for a clean SVG path, not a redraw of the actual vector artwork. When a
+  distinct shape is in use: the label moves below it (there's no "inside the box" for most of these,
+  `labelPosition` defaults to `'below'` instead of `'inside'`), and no default corner icon OR centred-initials
+  fallback is shown (the shape itself already says what the element is — every notationShape case sets
+  `suppressInner`) — an element's own explicit `icon`/`iconUrl` still wins regardless. `useDistinctShapes` is
+  a diagram-wide DEFAULT (off, so nothing changes for an existing diagram that hasn't opted in); an individual
+  element's own `useDistinctShape` (true/false) overrides it either way. A type with no implemented
+  `notationShape` always renders as the plain box, whichever way the setting goes. Every distinct shape also
+  honours an explicit `width`/`height` override the same way the plain box does (`_nodeSize` supports this for
+  any shape now, not just `'rect'`/`'table'` — and the generic `'below'` label offset and the plain
+  `'person'`/`'diamond'`/default-circle shapes were both fixed to size off the box's own smaller dimension
+  instead of `max(w,h)/2`, so a wide-but-short box no longer bleeds its label or an oversized circle into the
+  row below it in a dense grid). See the ArchiMate Diagram demo's own checkbox in `test/charts.html`, and the
+  dedicated **ArchiMate Notation Reference** demo right after it — every type the current version's catalog
+  has, one row per layer, built entirely from `ArchimateNotation.layers()`/`.typesInLayer()` rather than a
+  hand-picked sample, with the same box/shape toggle.
+
+  **Adding elements/relationships interactively:** archimateDiagram only enriches the `elements`/
+  `relationships` it's first called with — a node added afterward (e.g. via `editable`'s own "Add Node", or a
+  caller's own canvas action) doesn't automatically get archimateDiagram's layer colour/corner style/icon.
+  Use `engine._archimateBuildNode(element, opts)` and `engine._archimateBuildEdge(relationship, opts)` to
+  enrich a new item exactly the same way archimateDiagram does internally — see the ArchiMate Diagram demo's
+  `canvasContextMenuItems`/`onEdgeAdd` in `test/charts.html`. The built-in drag-to-connect gesture now acts as
+  a **magic connector** for ArchiMate diagrams: it picks the first relationship `kind` that
+  `ArchimateValidator.allowedKinds(source, target, version)` considers valid and immediately applies the
+  matching line/arrowhead style, falling back to a plain `{source,target}` edge only when no validator is
+  available. The right-click edge menu also offers **Invert Direction** to swap source/target in place.
+
+  See that same demo for all 11 relationship kinds, business/application/technology/motivation layers, a
+  chamfered Motivation goal, and rounded process/service boxes.
+
+  **Properties dialog fields are typed, not one-size-fits-all text boxes** (`test/charts.html`'s
+  `showPropertiesDialogUnsafe`/`addRow`): `'text'` (default) | `'textarea'` (`description`) | `'color'` (a
+  native `<input type=color>` swatch/picker for `color`, in place of a raw hex string) | `'select'` (a closed
+  list — `layer`, and `icon` sourced from `ArchimateNotation.iconChoices(subject.type)`) | `'select-editable'`
+  (an `<input list=datalist>` that still accepts free text — `type`, since archimateDiagram deliberately
+  doesn't enforce a closed type catalog). The dialog also groups a node's fields into an **Object** section
+  (`name`/`description`/`type` — the ArchiMate concept itself, the same regardless of how any one diagram
+  draws it) and a **Diagram** section (`label`/`layer`/`color`/`icon`/`group`/`size` — this view's own
+  presentation of it), with any remaining extra data under "Other"; this is a form-level grouping only —
+  `graphDiagram` itself still renders one flat node object, there's no separate model/view split under the
+  hood. The existing layer↔type cascade (`ArchimateNotation.typesInLayer`/`.elementType`) now also refreshes
+  `icon`'s own `<select>` options to the newly-chosen type's `iconChoices` whenever `type` changes, keeping the
+  current icon selected if it's still offered.
+- `dataModelDiagram(entities, relationships, opts)` — conceptual/logical/physical entity-relationship diagram,
+  the same "thin transform over `graphDiagram`" shape as `archimateDiagram`. **`src/datamodel.js`** owns the
+  notation data (`DataModelLevel`/`NotationStyle`, queried through the `DataModelNotation` registry — also
+  re-exported from the package root and as `RenderEngine.DataModelNotation`), its own separate OO file/
+  registry for the same reason `archimate.js` is: this domain's vocabulary shouldn't live inside RenderEngine
+  itself.
+  **Three levels, one model — the cross-mapping.** An entity is ONE object: `{id, name, description?, x?, y?,
+  color?, conceptual?, logical?, physical?}` — `name`/`description` are shared across every level (the
+  entity's own identity, unchanged by fidelity), while `entity.logical.attributes`/`entity.physical.
+  attributes` (`[{name, type?, isPK?, isFK?}]`, physical's own sub-object also taking `tableName`) hold that
+  level's own detail — the same object/visual split `archimateDiagram` draws between an element and its
+  diagram, just spanning "levels" instead of "diagrams". `opts.level` (`'conceptual'|'logical'|'physical'`,
+  default `'logical'`) picks which one's on screen; an entity with no attributes at the current level
+  (typical for `'conceptual'`) always renders as a plain box, regardless of notation. Re-calling
+  `dataModelDiagram` with a different `level` over the SAME `entities`/`relationships` re-renders that same
+  model at different fidelity — there's only ever one model, never three separately-maintained diagrams that
+  could drift apart (see the Data Model demo in `test/charts.html`, whose Level/Notation `<select>`s just call
+  it again).
+  **Three notations, one cardinality vocabulary.** `relationships:[{source,target,name?,sourceCardinality?,
+  targetCardinality?,identifying?}]` — cardinality is stored once as a UML-style multiplicity string
+  (`'0..1'|'1'|'0..*'|'*'|'1..*'`, `DataModelNotation.cardinalities()`), and `opts.notation`
+  (`'chen'|'crowsfoot'|'uml'`, default `'crowsfoot'`) picks how each end renders it: **Chen** turns the
+  relationship itself into its own `shape:'diamond'` node with two plain edges (not one direct edge), each
+  labelled with a plain `'1'`/`'N'` text cardinality; **Crow's Foot** renders cardinality as an arrowhead-style
+  glyph at each entity end (`crowsfoot-one`/`-one-optional`/`-many`/`-many-mandatory` — new SVGRenderer marker
+  defs, fork for "many", tick for "one", hollow circle for "optional", usable as a plain edge `arrowhead`/
+  `arrowheadStart` outside dataModelDiagram too); **UML** shows the multiplicity string itself as a text label
+  near each end instead, via the new generic `edge.sourceLabel`/`edge.targetLabel` fields (independent of the
+  existing midpoint `edge.label` — see graphDiagram's own doc comment). `relationship.identifying === false`
+  renders a dashed line (a non-identifying relationship, in real ERD terms) regardless of notation;
+  unset/`true` stays solid. None of the three notations are pixel-perfect renditions of the real, full
+  notations (same calibration as `archimateDiagram`'s own icons) — see `src/datamodel.js`'s own doc comment.
+- `railroadDiagram(diagramString)` — renders an EBNF grammar string as a railroad diagram. No node/edge
+  data at all.
+
+**Y-axis ticks.** Most cartesian chart types only draw a bare axis line — no numeric tick marks
+or gridlines. `barChart` and `groupedBarChart` are wired up to `_drawYAxisTicks` (a shared private
+helper built on `niceTicks`/`formatValue`), which draws left-edge tick marks, value labels, and
+light horizontal gridlines, and returns the "nice" (rounded-up) domain max the chart's own marks
+should scale against instead of the raw data max — see `barChart`'s own doc comment in
+`src/index.js` for why that matters (so the tallest bar actually reaches the top tick). Extending
+this to `line`/`area`/`stackedBar`/etc. is the same three-line change: call
+`this._drawYAxisTicks(x, y, width, height, rawMax)` before drawing marks, and scale against its
+return value instead of the raw max — not done yet for the rest, tracked as a follow-up.
+
+## Common options
+
+Not every method takes every option below — the table above calls out what's notable per type —
+but these recur across most 2D chart types:
+
+```javascript
+{
+  title: 'Chart Title',
+  xAxisLabel: 'X Axis', yAxisLabel: 'Y Axis',
+  colors: ['#5470c6', '#91cc75'],   // palette, indexed by series/category/segment
+  x: 70, y: 60, width: 500, height: 300, // chart box (defaults from container size)
+  showLegend: true,                 // or `legend:` depending on method — see table above
+}
+```
+
+Data-resolution options (used with `register()`/`refreshChart()`, see below):
+
+```javascript
+{ dataPath: 'metrics.sales', dataMapper: (v) => v * 1.1 }
+```
+
+### `colorCol` — plain field, or a compiled formula
+
+`scatterChart`/`bubbleChart`/`bubbleChart3D`'s `colorCol` names which field to color-group points
+by (falling back to a `category`/`group` field if present, and to one flat color if neither is
+given). It also accepts a **compiled formula** over the point's own fields, instead of just a field
+name — e.g. bucketing points by whether a value crosses a threshold, without pre-computing a
+derived field before calling into RenderEngine:
+
+```javascript
+engine.scatterChart(data, {
+  colorCol: { formula: 'value > threshold ? 1 : 0', params: ['value', 'threshold'] },
+});
+```
+
+`params` are field names read off each data point, in the order the formula uses them. The formula
+is a small, dependency-free scalar-expression language (`src/kernelExpr.js`) — arithmetic,
+comparisons, `&&`/`||`/`!`, `? :`, and `abs floor ceil round sign sqrt exp log sin cos tanh min max
+pow clamp` — compiled once per `colorCol` object with `new Function` from an AST the parser built,
+never from the formula text directly, so a bad or malicious-looking formula string is refused at
+parse time rather than reaching `eval`. Every distinct value the formula returns gets its own
+palette color, exactly the way a plain field's distinct values already do.
+
+## Data & utility methods
+
+```javascript
+engine.setGlobalData(data)              // set a global object referenceable by dot-path
+engine.resolvePath(path, mapper?)       // e.g. resolvePath('metrics.sales.0.value')
+engine.register(id, type, options)      // remember a {type, options} pair for a container id
+engine.refreshChart(id)                 // re-invoke it — resolves options.data or dataPath+dataMapper fresh each time
+engine.niceTicks(maxVal, count=4)       // readable axis tick values
+engine.formatValue(v)                   // 1234567 -> "1.23M"
+engine.bindTooltip(element, text)
+engine.bindRichTooltip(element, {title, rows:[{k,v}]})
+engine.adjustColor(hex, amount)         // lighten/darken, used internally for 3D shading
+```
+
+`register`/`refreshChart` is the registration mechanism `addDataPoint`/`addGraphNode` (next section)
+build on.
+
+## Interactivity
+
+```javascript
+engine.hitTest(x, y)              // shape under a point (manual on Canvas, native on SVG)
+engine.enterState(shape, 'hover') // apply a named visual state
+engine.leaveState(shape, 'hover')
+engine.resetView()                // reset SVG pan/zoom or 3D orbit camera to identity
+```
+
+SVG-rendered charts get wheel-zoom and drag-empty-space-to-pan for free; 3D-orbit charts
+(`bubble3D`, `bar3DOrbit`, `stackedBar3DOrbit`, `graphDiagram3D`) get drag-to-rotate/wheel-to-zoom
+instead — the two are mutually exclusive per chart, never combined.
+
+## Getting a chart out — clipboard and files
+
+```javascript
+import { copyImage, downloadPng, downloadSvg, toPngBlob } from 'renderengine';
+
+await copyImage(container, { name: 'sales-by-region' });   // → {via:'clipboard'} | {via:'download', filename}
+await downloadPng(container, { scale: 2 });
+downloadSvg(container);
+const blob = await toPngBlob(container, { scale: 2, background: '#ffffff' });
+```
+
+Pass the container, the `<svg>` or the `<canvas>` — the drawable is found either way. Options are
+`scale` (default 2, retina-sharp), `background` (default `'#ffffff'`, `null` for transparent) and
+`name` (the download's filename stem).
+
+`copyImage` **falls back to downloading the PNG** where writing images to the clipboard is
+unavailable — Firefox, and any page not on a secure context — so the button always does something.
+The returned `via` says which happened, so a caller can tell the user the truth rather than claiming
+a copy that did not occur.
+
+Three things this handles that a hand-rolled `XMLSerializer` + `canvas` will get wrong, each
+invisible until someone pastes the result somewhere:
+
+| | |
+|---|---|
+| **No intrinsic size** | An SVG sized by CSS (`width: 100%`) has no `width` attribute, and an `Image` loading that markup is 0×0 — a blank paste. Explicit pixel dimensions are set from the laid-out box. |
+| **Transparent background** | Diagrams draw no background, so a PNG pasted into anything dark shows dark-on-dark labels. A background rect goes in as the first child, behind the drawing. |
+| **Namespace loss** | Markup without `xmlns` will not load as an image at all; `xlink:href` (markers, patterns) needs its own, added only when something uses it. |
+
+Rasterizing is capped at `MAX_IMAGE_PIXELS` (32M). Over that, the **scale** is reduced rather than
+the diagram's own dimensions — halving the scale still shows the whole diagram, whereas cropping or
+shrinking it loses content or legibility. `imageSize()` and `prepareSvgMarkup()` are exported
+separately, and are pure, if you want the decisions without the DOM.
+
+**The exported image does not inherit the page's theme.** Serialized markup loaded as an image sees
+no author stylesheet, so the drawing falls back to the presentation attributes the engine itself
+emits — dark text and axes — rather than whatever the workspace's dark theme was overriding them
+with. That is the right result for something being pasted into a document on white paper, but it
+does mean a copy taken from a dark-themed app comes out light. To export a genuinely dark image,
+set `background` to the dark colour *and* render the chart with explicitly dark-friendly colours
+rather than relying on CSS.
+
+## Dynamically adding data points in a bounded window
+
+`addDataPoint`/`addGraphNode` are real `RenderEngine` methods — the engine owns the append/trim
+mechanics, not the caller. Internally they delegate to a small class hierarchy in
+`src/datawindow/` (see `ARCHITECTURE.md`'s "Data windows — streaming" section for the full design);
+this section is just how to call it.
+
+### 1. Register, then push
+
+```javascript
+engine.register('live-chart', 'line', { data: initialSeries, title: 'Live feed' });
+
+let tick = 0;
+setInterval(() => {
+  engine.addDataPoint('live-chart', () => ({ label: `T${++tick}`, value: randomValue() }), { maxPoints: 50 });
+}, 1500);
+```
+
+- `register(id, catalogKeyOrMethodName, options)` — same registration mechanism `refreshChart` has
+  always used; `options.data` is the chart's current dataset.
+- `addDataPoint(id, pointOrFactory, { maxPoints })` — appends one point (dropping the oldest once
+  past `maxPoints`; `0` = unbounded) and re-renders via `refreshChart`. `pointOrFactory` can be a
+  literal point, or a factory — required for multi-series charts (`line`/`area`/`pipe`), where it's
+  called once per series so each series can get its own value, and useful for shapes like
+  `candlestick` where the next point depends on the last one:
+
+```javascript
+// candlestick — factory receives the current data array, so the next bar
+// can continue from the previous bar's close:
+engine.addDataPoint('live-candles', (data) => {
+  const last = data[data.length - 1];
+  const open = last ? last.close : 100;
+  const close = +(open + (Math.random() - 0.5) * 6).toFixed(2);
+  return { label: `T${++tick}`, open, high: Math.max(open, close) + 1, low: Math.min(open, close) - 1, close };
+}, { maxPoints: 100 });
+```
+
+Every `CHART_CATALOG` entry declares a `streamShape` that decides how `addDataPoint` treats its
+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 |
+
+### 2. Graphs — `addGraphNode`
+
+`graphDiagram`/`graphDiagram3D` aren't `CHART_CATALOG` entries (see ARCHITECTURE.md), so they get
+their own method rather than going through `streamShape`. Register with `{nodes, edges}` instead of
+`{data}` — `refreshChart` detects the graph shape via `options.nodes`:
+
+```javascript
+engine.register('live-graph', 'graphDiagram', { nodes: initialNodes, edges: initialEdges });
+
+setInterval(() => {
+  const parent = engine.registry['live-graph'].options.nodes[Math.floor(Math.random() * n)];
+  engine.addGraphNode('live-graph', { id: `n${++tick}`, label: `Node ${tick}` }, [{ source: parent.id, target: `n${tick}` }], { maxNodes: 30 });
+}, 1500);
+```
+
+`addGraphNode(id, node, newEdges, { maxNodes })` drops the oldest nodes once past `maxNodes`, and
+any edge left dangling off a removed node along with them.
+
+### Chained form — `engine[id].addGraphNode(...)`
+
+Once an id is `register()`ed, `engine[id]` (or `engine.someId` when the id happens to be a valid
+identifier — most DOM ids, e.g. `chart-container`, contain a hyphen, so bracket notation is what
+you'll actually type) returns a handle scoped to that container, dropping the repeated `id` first
+argument:
+
+```javascript
+engine.register('live-graph', 'graphDiagram', { nodes: initialNodes, edges: initialEdges });
+
+setInterval(() => {
+  const parent = engine.registry['live-graph'].options.nodes[Math.floor(Math.random() * n)];
+  engine['live-graph'].addGraphNode({ id: `n${++tick}`, label: `Node ${tick}` }, [{ source: parent.id, target: `n${tick}` }], { maxNodes: 30 });
+}, 1500);
+```
+
+Both forms work interchangeably — `engine.addGraphNode(id, ...)` and `engine[id].addGraphNode(...)`
+call the same method underneath. The handle also exposes `register`/`refreshChart`/`addDataPoint`
+the same way. It only resolves for an id already in `engine.registry` (i.e. `register()` must still
+be called the normal way first) — an unregistered id falls through to a real, `undefined` property
+instead of a handle, same as before this existed.
+
+### 3. If you never `register()` a container
+
+`addDataPoint`/`addGraphNode` require a prior `register()` call (they look up the chart's type and
+current data from the registry). For a one-off container you don't want to register, own the array
+yourself and re-call the chart method directly — `createDataWindow(streamShape, data, {max})` (also
+exported, see `src/datawindow/index.js`) gives you the same append/trim classes standalone:
+
+```javascript
+import { createDataWindow } from 'renderengine';
+
+const window = createDataWindow('flat', initialData, { max: 50 });
+setInterval(() => {
+  const data = window.push(() => ({ label: `T${++tick}`, value: randomValue() }));
+  engine.lineChart(data, { title: 'Live feed' });
+}, 1500);
+```
+
+### Performance guidance
+
+- Every tick is a full `clear()` + redraw, not a diff — cheap for tens–low-hundreds of points per
+  series, but don't drive it faster than the container actually needs to look "live." 1–2 second
+  intervals read as real-time to a human; sub-100ms intervals mostly burn CPU redrawing pixels
+  nobody perceives changing.
+- If your update source fires faster than you want to redraw (e.g. a WebSocket pushing every
+  message), buffer incoming points and flush `addDataPoint` on a `requestAnimationFrame` or fixed
+  interval instead of calling it per message.
+- **Canvas** renderer for high point counts or high-frequency updates (5,000+ point ceiling vs
+  SVG's ~1,000+); **SVG** if you need native per-point tooltips/hit-testing more than raw throughput.
+- `graphDiagram`'s force layout (`_layoutForce3D`, `iterations` default 150) re-settles the whole
+  graph on every redraw — fine for occasional `addGraphNode` calls, but don't drive it on a
+  sub-second timer with a large node count; pin node positions (`arrange`-style layouts, see
+  `ARCHITECTURE.md`) if you need cheap, jitter-free incremental adds.
+
+See `examples/csv-chart-builder.html`'s "Live updates" panels (section 4 for charts, section 8 for
+graphs) for a full working implementation of all of the above, including the per-shape synthetic
+value generators (`LIVE_APPENDERS`) that decide *what* value to invent each tick — legitimately
+demo-specific, unlike the append/trim mechanics above.
+
+## ArchiMate Diagram Editor (OO component)
+
+**`examples/archimate.html` is the canvas editor now** (`ArchimateCanvasPart`, type `archimate-canvas`, below under
+"Diagram templates and palette categories"); this section's graph-engine editor is kept in
+`examples/archimate-legacy.html` until the canvas editor has replaced it.
+
+**In a workbench: `ArchimateEditorPart`.** The legacy modeller is a workbench part (type
+`archimate-editor`, workspace bundle) built on `EditorPart`: it takes the model as part of its JSON
+spec, fills its pane, and sits in a `<ws-workspace>` beside any other parts. `examples/archimate-legacy.html`
+is this, and nothing else:
+
+```javascript
+const { el, registerBuiltinParts, ArchimateEditorPart } = RenderEngineWorkspace;
+const ws = document.body.appendChild(el({ tag: 'ws-workspace', attrs: { label: 'ArchiMate Modeller', theme: 'light' } }));
+registerBuiltinParts(ws);
+ws.registerPart(ArchimateEditorPart);
+ws.addParts([{ id: 'modeller', type: 'archimate-editor', title: 'Model', elements: [...], relationships: [...], views: [...] }]);
+ws.registerPerspective('Modelling', { type: 'part', partId: 'modeller' });
+ws.activatePerspective('Modelling');
+ws.getPart('modeller').model;    // the ArchimateModel (an import replaces it)
+```
+
+Spec options: `elements`, `relationships`, `views` and `name` (as `ArchimateModel` takes them),
+`features` (toolbar controls; all on unless set `false`) and `analysis` (`true` adds the analysis panel).
+The part builds the `ArchimateModel` and hands it to `ArchimateDiagramEditor` (its `model` option), with
+`fullPage: false` and region ids unique to the part, and `ARCHIMATE_SERVICES` (the editor's classes and
+dialogs, imported directly) as its `workspace`.
+
+**View settings, warnings and labels on the editor's canvas.** A host hands the editor the current view's
+resolved settings as `viewSettings: () => settingsManager.getEffectiveSettings(view, modelId)`
+(`editor.viewSettings()`, {} without one). The base editor draws the view's background, title band and
+watermark round the drawing from them (`applyViewDecorations` on the element holding the `<svg>`; a view
+without a background goes back to the page's own). `editor.edgeWarning(edge)` says what is wrong with a
+line, `{ message, highlight }` or null: the message is the line's tooltip, and with `highlight` the line is
+drawn red and dashed unless it has its own colour or dashes (class `edge-warning`). The ArchiMate canvas
+editor warns about a relationship the ArchiMate rules do not allow for its version (`ArchimateValidator`), as
+the view's `invalidRelationships` setting says: 'highlight' (the default), 'tooltip' or 'off'. A label
+expression (`${name} (${type})` or `{name}`, on the element's `label` or the instance's `labelOverride`) is
+resolved by the instance (`ElementInstance#getDisplayName`, through `LabelHelper.resolveNodeLabel`), so the
+tree, the dialogs and both editors show the same text.
+
+**Properties: the shape, and what it stands for.** The base editor's shape dialog (`editTemplateProperties`:
+name, position, stacking, colours, text) and line dialog (label, sides, then only the style the line sets for
+itself, `edge.styleProperties`) each end with a subclass's own section: `conceptFields(template)` and
+`edgeConceptFields(edge)` give FormDialog fields, and `conceptCommand(template, values)` /
+`edgeConceptCommand(edge, values)` the command applying them; the whole edit is one undo step. The ArchiMate
+canvas editor's sections edit the model element (its own name, type, specialization among those registered for its
+type, icon among its type's choices, documentation, typed properties) and the
+relationship (kind, among those the rules allow and its own; documentation; typed properties), the same on every
+view, through `EditViewItemCommand`; an empty box or list is unset, and a new type drops a stored layer. An
+ArchiMate line's dashes and arrows come from its kind and a plain line's from its type, so neither is offered.
+
+**Type pictures.** The model tree shows each element with its type's glyph in its layer colour, as the palette's tiles
+do, and a folder of one type in the Layers tree too (`typeGlyph(typeName, { size, version })` in
+`archimate/typeGlyph.js`, the one drawing both use; a 3.2 type under ArchiMate 4 is drawn as 3.2 draws it).
+`TreeBuilder`'s `iconFor(node)` gives a node a picture in place of its `icon` text.
+
+**Nesting.** In the ArchiMate canvas editor, dropping a box wholly inside an element's box nests it there (Archi's
+nested elements): it moves with its parent, is raised above it, and an Archi file writes it inside it (whatever order
+they were added in). Dragged out again, it is taken out. The move and the nesting are one undo step. On a canvas, a
+block holds boxes the same way. Nesting one element in another then asks which relationship it stands for, among
+Archi's nesting kinds (`NESTING_KINDS`: composition, aggregation, assignment, realization, specialization) that the
+rules allow from parent to child, and none when the two already have one; **Add** puts it in the model, drawn as no
+line (the nesting shows it), as its own undo step; **No relationship** adds none. The shared editor does the
+finding: after a move, `DiagramEditor#nestingChanges(ids)` gives each moved shape's new parent (the innermost shape
+that wholly holds it and `canHold` it), and a subclass supplies `parentOf`, `canHold`, `nestCommand`
+(`NestInstanceCommand`) and `nested(changes)`; the template editor has no nesting. Model checks: **Check model…**
+warns of an element drawn inside another with no such relationship (`nested-without-relationship`), and a
+relationship a nesting shows is not reported as unused (`viewNestings(view)`, `nestingRelationships` in
+`diagrams/nesting.js`).
+
+**Format painter.** The toolbar's **🖌** turns it on (Archi's Format Painter): with a shape selected it holds that
+shape's format, otherwise the first shape clicked gives it; every shape clicked after gets it (one undo step each),
+and nothing is selected or moved meanwhile. **Esc** or 🖌 again turns it off. A shape's menu has **🖌 Copy format**
+and, once one is held, **Paste format** (to the selection, when the shape is part of it). A format is what
+`Template#format()` reads from the shape's `static formatKeys` (paint and text style here; an ArchiMate shape's or
+group's whole appearance), as the shape holds it: a colour it takes from elsewhere (an ArchiMate layer colour) is
+left unset, so the shape painted gets its own default. `DiagramEditor#copyFormat(id)`, `pasteFormat(ids)` (each
+shape takes the keys it has; a locked one stops it) and `setFormatPainter(on)`.
+
+**Properties of several shapes at once.** With more than one shape selected, a selected shape's menu offers
+**Properties of N shapes** (double-clicking one opens it too): one dialog with the colours and text style
+(`appearanceFields(template)`, the same fields as one shape's dialog) in which every field starts on **Keep**,
+greyed out, showing the value the shapes share (or empty, with "Differs between them"). Untick Keep and what you
+set goes to every shape; the rest stays as each one has it. The whole edit is one undo step; a locked shape in the
+selection stops it. `DiagramEditor#editSelectionProperties(ids?)` opens it and
+`selectionPropertiesCommand(templates, values)` is the edit (a value left `undefined` changes nothing); a
+subclass adds its own section with `manyConceptFields(templates)` and `manyConceptCommand(templates, values)`.
+The ArchiMate canvas editor's, when every selected shape is an element: their **type**, their **specialization**
+when they share a type, and **Set property** (a name and value, set where an element has that property and added
+where it doesn't), from `manyElementsFields` and `manyElementsEditCommands` in `archimate/elementProperties.js`.
+`PropertyListEditor` (`PropertyListEditor.field(properties, { key })`) is the typed-property list both
+ArchiMate dialogs use. Both editors fill the specialization catalog the same way:
+`ArchimateSpecializationRegistry.loadFrom(store)` reads the saved catalog (`SPECIALIZATIONS_STORE`, this browser's),
+or registers the defaults and saves them.
+
+**Boxes, the tree and the menus on the canvas.** Every ArchiMate view adds boxes besides elements through
+`view.addBox(kindKey, at)` (one undo step), from the kinds its class lists in `BOX_KINDS`: Archi's Note and Image
+on an ArchiMate view (`DIAGRAM_BOX_KINDS`), Block, Sticky and Image on a canvas (`CANVAS_BOX_KINDS`);
+`canvasBoxMenuItems(view, at)` offers them on right-click in either editor. The canvas editor's element menu adds
+**Generate View For This** and **Add Missing Relationships (n)** (`missingRelationshipsOf(boxId)`, drawn as one
+step by `addMissingRelationships`), and ⚙ Settings → **Model settings…** when it has a `settingsManager`. The base
+editor reports selection changes (`editor.onSelectionChange(({ templateId, edgeId }) => …)`, which returns an
+unsubscribe); the canvas part keeps the model tree in step with it both ways and shows a canvas's hint, or the
+selected box's. `SettingsManager#onSettingsChange` returns an unsubscribe too.
+
+**Specializations and viewpoints of your own.** ⚙ Settings → **Specializations…** and **Viewpoints…**, in both
+editors, list the user's catalog with Edit and Delete and "+ New …". A specialization has a name, an icon, a
+colour, a description and the element types it applies to (none: every type); it is saved in
+`SPECIALIZATIONS_STORE` and offered on elements of those types (`specializationCatalogDialog({ version, store,
+onChange })`). A viewpoint has a name (not a standard one's), a description and the element types it allows (at
+least one); it is saved in `CUSTOM_VIEWPOINTS_STORE` (`CustomViewpoints.load()`, `save(list)`,
+`dialog(options)`) and offered after the standard viewpoints, where it fades or hides the rest and limits the
+palette like any other. There is no "Custom" placeholder any more. `CatalogDialog` is the list editor both use
+(`{ title, noun, items, label, fields, validate, save, remove, onChange }`; deleting asks first), and FormDialog's
+`checklist` field (`choices` `[[value, text, group]]`, reads as the chosen values) is the element type list,
+grouped by layer as the palette groups them (`elementTypeChoices(version)`, from `elementTypeGroups`).
+
+**An element's menu in the model tree** (both editors; `elementMenuItems(element, host)`): **Properties…** edits the
+element itself, the same on every view (`editElementProperties`: its name, type, specialization, icon,
+documentation and typed properties, one undo step on the open view); **Show in View (n)** lists the views it is on
+and opens the chosen one with it selected; **Add to "…"**, when the open view lacks it, shows it there in the middle
+of what is in sight (`visibleCentre()`) with its relationships to what is shown; **Generate View For This**. The
+element fields are one definition (`elementPropertyFields`, `elementEditCommand`), which the canvas editor's shape
+dialog also uses for its Element section.
+
+**Pictures, analysis and filters on the canvas.** A picture file dropped on a view, or pasted, is an image box
+there (`editor.addImage(dataURL, point)`, one undo step, selected; the base editor's `enableImageDrop`). With
+`analysis: true` in its spec the canvas part shows the selected element's analysis (views it is in, its
+relationships) under the palette, for an element chosen on the canvas or in the tree. The tree's own filters (its
+"Filters…" dialog: text, types, specializations, properties) dim what they leave out on the canvas too:
+`modelTree.matchingElementIds()` (null with no filter on) and `modelTree.onFilterChange(fn)` feed
+`editor.setElementFilter`. The analysis names an element's layer as the tree files it (`treeLayerOf`).
+
+**Groups on the canvas.** An Archi group (a model folder with bounds on the view, `view.placedFolders`) is a
+`ViewGroupTemplate`: Archi's box with a name tab (`TabbedBoxGlyph`), placed by its centre while its layout entry
+(`view.folderLayout[id]`: top-left x/y, width, height, zIndex, `appearance`) keeps the corner, so the editor's
+move, resize, restack and paint commands edit the view and undo there; renaming it renames the folder. Its paint
+is imported into `appearance` and written back as boxes' is (a change written, the rest as the file had it). A
+line to a group is drawn. Moving a container moves what it holds, however deep: the base editor's
+`moversFor` adds `containedIn(id)` (none in the base) for each mover; the canvas editor's groups hold the
+elements in their folder, the notes and pictures Archi drew in them (`instance.archi.parent`) and the groups
+inside them, and a canvas block holds the boxes Archi drew in it. Deleting a group takes it off the view
+(`RemoveGroupFromViewCommand`); what it held stays.
+
+**Derived relationships on the canvas.** With `nodeOptions.showDerived` (⚙ Settings → Show derived, off by
+default; the canvas part's spec `showDerived`), the ArchiMate canvas editor draws each relationship
+`DerivedRelationships.compute(model, { maxHops: 2 })` derives between two elements on the view, as a
+`DerivedEdge`: dotted, labelled with its chain ("composition→assignment"), with "Derived: …" as its tooltip. It
+is drawn only: `edge.editable` is false, so the editor neither selects, routes nor deletes it (deleting a box
+leaves it alone). Any `Edge` can say so (`editable`, default true) and add to its tooltip (`tooltip`).
+
+**Selecting several shapes.** In the base editor (so the template editor and the ArchiMate canvas alike): drag a
+box on empty canvas to select the shapes wholly inside it (Ctrl or Cmd adds them to the selection;
+`editor.templatesInside(rect)`, `editor.selectTemplates(ids, { extend })`); Shift- or Ctrl-click adds one;
+**Ctrl+A** selects every shape that is drawn (`selectableIds()`). Whatever is selected acts together, each as one
+undo step: dragging any of them moves them all (with their groups and what they hold); the arrow keys nudge
+them a grid step, one pixel without a grid, ten times as far with Shift (`nudgeSelection(dx, dy)`); **Delete**
+removes them once confirmed, and every line joined to any of them once (`deleteSelection()`,
+`deleteTemplatesCommand(ids)`; a subclass gives the per-shape part, `removeTemplateCommand(id)`, and the step's
+name, `deleteLabel(ids)`); grouping, locking and the Arrange menu already took the selection. A fixed shape among
+them stops a move or a delete.
+
+**One undo history per model.** As in Archi, a model has one undo stack, `model.history` (a `ModelHistory`),
+that all its views share (`view.history` is it): every edit on any view, and the model's own changes, in the order
+made. Adding a view (New, Duplicate, Generate View, a new canvas, a model template), renaming one and deleting one
+are undo steps too (`AddViewCommand`, `RenameViewCommand`, `RemoveViewCommand`), as are a view's name and
+documentation from its Properties…. Each step remembers the view in front when it was made, and undoing or redoing
+it brings that view to the front, so the change is seen (Ctrl+Z on one tab can undo an edit made on another).
+Unsaved changes follow the one history (`isDirty()`). A model a part has just made or opened starts with nothing
+to undo.
+
+```js
+const model = new DiagramModel();
+const a = model.createView('A');          // one undo step
+model.renameView(a.id, 'First');          // another
+model.history.undo();                     // 'A' again
+model.history.undo();                     // the view is gone
+```
+
+**Find and replace.** Every `EditorPart` (the ArchiMate canvas part and the template editor) has an **Edit** menu
+after File: **Undo**, **Redo** and **Find and replace…**, over the whole model (`model.search()`, a
+`ModelSearch`, as `checker()` and `report()` are). The dialog (`FindReplaceDialog`) lists what matches as you
+type, with **Match case**, **Whole words**, **Regular expression** (`$1` in the replacement is its first group)
+and **Look in** names, documentation and property values; choosing a match shows it (its view, then the item
+selected), and **Replace all** replaces every match as one undo step on the model's history. What is
+searched: the model's name, documentation and properties and each view's title (never emptied), documentation and
+properties (`ModelSearch`); in the template editor also each shape's name and line's label
+(`DiagramModelSearch`); in an ArchiMate model also every element's and relationship's name, documentation and
+properties, and the notes on each view (`ArchimateModelSearch`). A property whose value is a number or true/false is
+left out. A notation's search adds its own texts with `viewItemTargets(view)` and `conceptTargets()`.
+
+```js
+const search = model.search();
+search.find('customer', { wholeWord: true, fields: ['name'] });   // [{ kind: 'element', id, owner, fieldLabel: 'Name', text, count, target }, ...]
+const cmd = search.replaceCommand('(\\w+) DB', 'DB of $1', { regex: true });   // a ReplaceTextCommand, or null
+model.currentView.history.execute(cmd);                            // one undo step
+```
+
+**Transform names, rename a property, fit to text.** The **Edit** menu has **Transform names…**: Title Case,
+Sentence case, split camelCase (OrderService → Order Service), camelCase, remove extra spaces, UPPER or lower case,
+on every name in the model or on those containing some text (`NAME_TRANSFORMS`, `transformName(key, name)` in
+`diagramModel/nameTransforms.js`; `model.search().transformCommand(key, text)`), one undo step, a view never left
+without a name. **Rename property…** renames a property everywhere it is (the model, its views, and an ArchiMate
+model's elements and relationships), one undo step; where something has both names, the old value fills the new one
+only if that is empty (`search.renamePropertyCommand(from, to)`, `search.propertyNames()`, over
+`search.propertyHolders()`, which a notation's search extends). Several elements' Properties also has **Remove
+property** (one any of them has). A shape's menu has **Fit to text**: the shape (or the selection it is part of) sized
+to its label, keeping its top-left corner, one undo step (`DiagramEditor.textSize(text, fontPixels, {padding, min})`
+estimates it; `editor.textFit(template)` gives the room a shape needs, more for an ArchiMate element's badge).
+
+**HTML report.** File → **Export HTML report** (every `EditorPart` whose model has `report()`: the ArchiMate
+canvas part and the template editor) saves the whole model as one HTML file that opens in any browser, with nothing
+else to load: a tree on the left (Elements by layer, Relationships by kind, Views), a search box that keeps what
+matches by name, type or documentation, and a page per item. A view's page has its picture, and clicking an element
+on it opens that element's page; an element's page has its type, layer, documentation, properties, relationships
+(each with the element at the other end) and the views it is on; a relationship's links its source and target. The
+address says which page (`#element:id`), so Back and links work.
+
+The parts, each usable alone:
+
+```js
+import { ArchimateModel } from './src/charting/diagrams/ArchimateModel.js';
+import { reportHtml, reportFileName } from './src/charting/report/reportHtml.js';
+
+const model = new ArchimateModel({
+    name: 'Shop',
+    elements: [{ id: 'a', name: 'Customer', type: 'business-actor' }, { id: 'b', name: 'Order app', type: 'application-component' }],
+    relationships: [{ id: 'r', kind: 'serving', source: 'b', target: 'a' }],
+    views: [{ id: 'v', name: 'Main', elementIds: ['a', 'b'] }],
+});
+const data = model.report().data();     // plain JSON: { title, home, sections, items }
+data.items['element:a'].lists;           // [{ title: 'Relationships', rows: [{ key: 'relationship:r' }] }, { title: 'Views', ... }]
+const html = reportHtml(data);           // the file's text
+reportFileName(data.title);              // 'shop-report.html'
+```
+
+`model.report({ pictures, title })` is a `ModelReport` (`src/charting/diagramModel/`): the model's page and a page
+per view, for any `ViewSetModel`; `ArchimateModel` returns an `ArchimateModelReport`, which adds the elements and
+relationships. A subclass adds items with `conceptItems()`, tree sections with `conceptSections()`, and a view's
+facts and lists with `viewFacts(view)` / `viewLists(view)`. Pictures come from the editor:
+`DiagramEditor#viewPicture()` is the current view as SVG cropped to what is drawn (no grid, selection or zoom), with
+a box per shape whose `reportRef(template)` names its page (`{kind: 'element', id}` in the ArchiMate editor);
+`part.viewPictures()` shows each view in turn to collect them. The page is written from `el()` specs by
+`toHtml(spec)` (`src/workspace/dom.js`: the same spec, as escaped HTML text), and its script is `reportViewer`.
+
+**The File menu, grouped.** Every editor part's File menu (`EditorPart#fileMenuItems`) is: **New** ▸ (a view or
+diagram, a canvas, from a template, a model), Open…, Save, Save As… (with a ModelsPart also Open… in a new tab and
+Close model), **Import** ▸ (each format that imports, then the part's own: an Archi template, CSV with mapping),
+**Export** ▸ (each format, the part's own, then the HTML report and the pictures), the part's own groups (the canvas
+part's **Templates** ▸), and **This view** ▸ (its properties, duplicate, delete). A group of one item is that item
+(named as the group says it: "Export HTML report"). A part adds to it with `newItems()`, `ownImportItems()`,
+`ownExportItems()` and `ownFileItems()`; `EditorPart.menuGroup(label, items, { prefix })` and
+`EditorPart.tidyMenu(items)` make the groups; `modelFileMenuItems(formats, { only: 'export' | 'import' })` gives
+one direction's items.
+
+**Open, save, and unsaved changes.** An editor part with file formats (`EditorPart`, the ArchiMate canvas part) has
+**Open…**, **Save** and **Save As…** at the top of File (**Ctrl+O**, **Ctrl+S**, **Ctrl+Shift+S**), kept by its
+`part.file` (`ModelFile`). Open asks for a file and takes the first of the part's formats whose extension and
+contents fit (`format.acceptsName(name)`, `format.recognizes(data)`: a `.xml` is Archi's or the Exchange Format by its
+namespace); Save writes back to that file where the browser can (the File System Access API: Chrome and Edge),
+otherwise it is Save As, which asks where (or, with no save dialog in the browser, downloads) in the open file's
+format or the part's `saveFormat()` (Archi's for the canvas part). The part knows whether the model changed since it
+was opened or saved: `model.markSaved()` / `model.isDirty()` / `model.onEdit(fn)` (`ViewSetModel`), from the model's
+one history (`CommandHistory#stateToken`, the same whenever it is back in a state, so undoing back is clean again),
+views added, renamed or deleted included. `part.fileLabel` ("shop.archimate •") shows in the part's toolbar and the page
+title, and leaving the page with changes unsaved asks first. An import is not a file: Save then asks where.
+`file.open()` is `file.choose()` (ask for a file and read it as a model, opening it nowhere yet) then
+`file.adopt(chosen)`.
+
+**Several models open at once.** A `ModelsPart` (type `models`, one of `BUILTIN_PARTS`) holds one editor part per
+model, each a tab of a work area (`WorkArea`), so each keeps its own file, unsaved state and undo history, and copy
+and paste go between them. Its spec names the editor part type and what to open: `{ id, type: 'models', editorType:
+'archimate-canvas', models: [editor part spec, ...], newModel: editor part spec }`. An editor part it hosts
+(`part.modelsHost`) has **New model**, **Open… in a new tab** (with file formats: the file is read first, and the
+tab is made only for a model) and **Close model** at the top of File. A tab shows what the model is called (its file's name, else the model's name, as the toolbar does) and
+• with unsaved changes; closing one that has them asks first (its × too); the last one closed leaves a new, empty
+model; the page title follows the model in front. Keys an editor listens for on the page (undo, delete, Ctrl+S, ...)
+act only for the one on screen (`Part#isShown()`, `DiagramEditor#isShown()`). `examples/archimate.html` and the
+template editor's testbed host their editor this way:
+
+```js
+ws.addParts([{ id: 'models', type: 'models', editorType: 'archimate-canvas', newModel: { analysis: true },
+    models: [{ id: 'modeller', title: 'Sample model', elements: [...], views: [...] }] }]);
+ws.registerPerspective('Modelling', { type: 'part', partId: 'models' });
+```
+
+**Align, distribute, match size, in every editor.** With two or more shapes selected, a shape's menu and the
+toolbar's **Arrange** menu (there always, greyed out with too few) offer **Align** (Left, Centre, Right, Top,
+Middle, Bottom), **Distribute** (Horizontally, Vertically; three or more) and **Match size** (Width, Height, Width
+and height). Align and match size follow the primary shape (the one selected last), as in Archi; distribute keeps
+the outermost two and makes the gaps between neighbours equal; match size keeps each shape's top-left corner. Each
+is one undo step; what a moved container holds moves with it; a locked shape stops it. `DiagramEditor` has
+`alignSelection(edge)`, `distributeSelection(direction)`, `matchSelectionSize(dimension)` and
+`alignMenuItems()`; where the shapes go is worked out from their boxes alone by `align`, `distribute` and
+`matchSize` (`src/charting/arrangement/alignment.js`), which return just the boxes that change:
+
+```js
+import { align, distribute, matchSize } from './src/charting/arrangement/alignment.js';
+const boxes = [{ id: 'a', left: 0, top: 0, width: 100, height: 50 }, { id: 'b', left: 150, top: 40, width: 60, height: 30 }, { id: 'c', left: 400, top: 10, width: 120, height: 80 }];
+align(boxes, 'top', boxes[1]);        // [{ id: 'a', left: 0, top: 40 }, { id: 'c', left: 400, top: 40 }]
+distribute(boxes, 'horizontal');      // [{ id: 'b', left: 220, top: 40 }]
+matchSize(boxes, 'width', boxes[0]);  // [{ id: 'b', width: 100, height: 30 }, { id: 'c', width: 100, height: 80 }]
+```
+
+**Import CSV with mapping.** File > **Import CSV with mapping…** (the ArchiMate canvas part) adds a spreadsheet's
+rows to the open model (it never replaces it): choose which column holds the name, the type (any case, a title, or
+CamelCase as Archi's elements.csv writes it; or one type for every row), an id, the documentation and which columns
+are properties, and optionally one whose cells name (or give the ids of) elements each row's element is related to,
+with the kind and direction. A row whose id, or name and type, is an element the model has updates its
+documentation and properties instead of making a second; rows naming the same element are one; a relationship the
+model has is not added twice, nor one the rules do not allow. The new elements can go on the open view, in a grid.
+One undo step; rows that could not be read (no name, an unknown type, an element to relate to that is not there)
+are listed after. The dialog suggests the columns from their names (Name, Type, ID, Documentation; the rest as
+properties), so Archi's elements.csv imports as it is. The CSV reader (`parseCsvTable`, `parseCsvRecords`,
+`guessDelimiter` in `src/csvTable.js`, which the CSV file format uses too) takes quoted cells with line breaks
+and commas, semicolons or tabs. `planCsvImport(table, mapping, model)` (`archimate/csvMapping.js`) plans it and
+`ImportRowsCommand` carries it out:
+
+```js
+const table = parseCsvTable(text);
+const plan = planCsvImport(table, { name: 'Name', type: 'Type', properties: ['Owner'], related: 'Uses', relatedKind: 'serving', relatedDirection: 'in' }, model);
+model.history.execute(new ImportRowsCommand(model, plan, { view: model.currentView }));   // plan.problems: [{row, message}]
+```
+
+**draw.io export.** File > **Export draw.io (.drawio)** (the ArchiMate canvas part) saves every view as a page of one
+draw.io (diagrams.net) file, in draw.io's own ArchiMate 3 shapes: each box with its place, size, colours (its
+layer colour when it has none of its own) and text placement, a box nested in another as its child cell, notes,
+groups and canvas boxes; each line with its relationship's look (access by its access type) and its bendpoints. An
+element's or relationship's id, type, documentation and properties go on its cell's object, so draw.io keeps them.
+It is export only (`ModelFileFormat#imports` is false: no Import item, and Open… does not offer it).
+`toDrawioXML(model, { viewIds })` (`src/archimateDrawio.js`) writes it; `DRAWIO_ELEMENT_STYLES` and
+`DRAWIO_RELATIONSHIP_STYLES` are the type-to-shape tables.
+
+**Roadmaps.** On the ArchiMate canvas, **View > Generate roadmap…** makes a new view of elements on a time line:
+each element with a start and an end date (by default its "Start Date" and "End Date" properties; ISO dates, a
+year and month, or day/month/year) is a bar from one to the other, under a header of years and months (short or
+full names), with month columns behind; bars that overlap in time go in lanes below each other. It takes the
+selected elements, or every element in the model with both dates; those without them are left out. The view comes
+to the front; one undo step. `model.generateRoadmap(elementIds, { startProperty, endProperty, name, monthNames })`
+returns `{ view, skipped }`; where everything goes is `roadmapPlan(items, options)` and dates are read by
+`parseDate(text)` (`src/charting/diagrams/roadmap.js`):
+
+```js
+const { view, skipped } = model.generateRoadmap(model.elements().map(e => e.id), { startProperty: 'From', endProperty: 'To' });
+```
+
+A note's own fill colour is drawn (it was always yellow); one without keeps the yellow sticky look.
+
+**Add from text, in every editor.** Right-click the canvas → **Add from text…**: paste a list of names (from a
+document, a spreadsheet, a mail) and choose their kind, and a shape is made for each, placed in a grid from where
+you clicked, selected, one undo step. A name a line; a tab after it starts its documentation; blank lines are
+skipped and bullets and numbering ("- ", "• ", "1. ", "2) ") taken off. A first line `types=<kind>,<kind>,...`
+makes each tab-separated column that kind and each line a row of shapes (a kind by its key or its name, any case:
+`types=Business Actor,application-component`). The template editor makes its palette's shapes; the ArchiMate
+canvas makes new model elements with their boxes (the kinds its viewpoint allows; not on a canvas, whose boxes
+are not elements). `parseShapeText(text, {defaultType, resolveType})` and `placeShapes(parsed, at)`
+(`src/charting/textToShapes.js`) read and place the text; `DiagramEditor#addFromText(text, type, at)`,
+`shapeTypes()` and `createShapesCommand(items)`, which a subclass overrides to make its own kind of shape.
+
+**Colour by, and legends, in every editor.** The **View** menu has **Colour by…** (a heat map): choose what to
+colour by, then a colour for each of its values (a soft palette by default, `DiagramEditor.COLOUR_PALETTE`; "No
+colour" leaves a value's shapes as they are), and whether to add a legend. Each shape takes its value's colour as
+its own fill, so the colours are kept like any other (an Archi file included), and one undo puts them back. The
+template editor colours by the kind of shape; the ArchiMate canvas by **Layer**, **Type**, **Specialization** or any
+**property** its elements have (notes and pictures have no value and stay as they are). A legend is a title and a
+box per value in its colour, in a row under the drawing (notes; on a canvas, stickies). **Add legend of the kinds
+shown** adds one for the kinds of shape (ArchiMate: the element types) in the colour of each's first shape. A
+locked shape keeps its colour. `colourKeys()`, `colourValue(template, key)`, `colourValues(key)`,
+`colourByCommand(key, colours, { legend })`, `kindLegendEntries()` and `legendCommand(entries, title)`, which a
+subclass overrides to say what its shapes are coloured by and what its legend boxes are:
+
+```js
+editor.colourByCommand('property:Lifecycle', { invest: '#98fb98', maintain: '#ffc300', retire: '#ffa07a' }, { legend: true });
+```
+
+**Layouts, in every editor.** The toolbar's **Arrange** menu has **Layout** (**Layout the view** with fewer than two
+shapes selected): **Grid**, **Circle**, **Tree, top down**, **Tree, left to right** (along the lines between the
+shapes: a parent centred over its children; a shape no line reaches is a root), **Force-directed** (lines pull,
+shapes push apart; the same input gives the same result) and **By kind, a row each** (the shape class in the
+template editor, the layer on the ArchiMate canvas). The shapes keep the top-left corner of the area they took;
+what a container holds goes with it; one undo step; a locked shape stops it. On the ArchiMate canvas, an element
+with parts on the view (the targets of its composition and aggregation relationships) has **Nest its parts inside**
+in its menu: each part nested in it, theirs in them however deep, in a grid below its label, the parent grown to
+hold them. `DiagramEditor#layoutShapes(kind, ids?)`, `layoutCategory(template)`, `partsOf(id)` and
+`nestPartsInside(id)`; where shapes go comes from `layout(kind, boxes, {edges, categoryOf, gap})` and
+`nestLayout(rootId, partsOf, boxOf)` (`src/charting/arrangement/layouts.js`), from the boxes alone:
+
+```js
+import { layout } from './src/charting/arrangement/layouts.js';
+const boxes = [{ id: 'a', left: 0, top: 0, width: 100, height: 50 }, { id: 'b', left: 0, top: 100, width: 100, height: 50 }, { id: 'c', left: 0, top: 200, width: 100, height: 50 }];
+layout('tree-down', boxes, { edges: [{ source: 'a', target: 'b' }, { source: 'a', target: 'c' }], gap: 40 });
+// [{ id: 'a', left: 70, top: 0 }, { id: 'b', left: 0, top: 110 }, { id: 'c', left: 140, top: 110 }]
+```
+
+**Copy and paste, in every editor.** **Ctrl+C** copies the selection, **Ctrl+X** cuts it (one undo step), **Ctrl+V**
+pastes (a little further along each time, selected), **Ctrl+D** duplicates without touching the clipboard; a shape's
+menu has Cut, Copy and Duplicate and the canvas menu **Paste here** (its top-left corner where you clicked). The
+clipboard is the page's (`DiagramClipboard`), so a copy pastes into another view, tab or model; an editor pastes only
+copies of its own kind (`static clipboardKind`: 'diagram' for the template editor, 'archimate' for ArchiMate views).
+An editor gives what a copy is (`copyPayload(ids)`) and how it is made again (`pasteCommand(payload, { dx, dy })`):
+the template editor copies each shape (its class and `serialize()`) and the lines between them; an ArchiMate view
+copies its items (`view.toJSON({ itemIds })`: boxes, the lines and relationships between them, the elements and
+relationships they show) and pastes them as new boxes for the **same** elements (`view.pasteCommand(data)`,
+`PlaceItemsCommand`), adding to the model what it lacks (a paste from another model) and to a view's element list
+what it does not list. Groups are not copied (they are folders).
+
+**Mouse buttons, in every editor.** A left drag on empty canvas draws the selection box; the **right button drags
+the view** (a right-click that does not move still opens the menu), as do the middle button and Shift+left (Alt+left
+in the main ArchiMate editor). In the main ArchiMate editor (the graph engine) the box selects nodes too
+(`graph.selectNodes(ids, { extend })`, kept on the engine across redraws and marked with a glow), and dragging one of
+them moves them all as one undo step.
+
+**Emphasis: highlight, viewpoint, filter.** A shape or line can be drawn as usual, dimmed (opacity 0.3),
+faded (0.2) or not at all (hidden), and only how it is drawn changes. Each reason is an `EmphasisRule`
+(`template(template, editor)` and `edge(edge, editor)` give `null`, `'dimmed'`, `'faded'` or `'hidden'`);
+`editor.emphasisRules()` lists the active ones, and the strongest level any of them gives wins
+(`templateEmphasis`, `edgeEmphasis`; a line to a hidden shape is hidden). A dimmed or faded item is drawn in
+a `<g opacity data-emphasis>` with its `data-template-id` or `data-edge-id`. The base editor's rule is the
+highlight: **View → Highlight…** (`editor.setHighlight(text)`, `HighlightRule`) dims every shape whose name
+does not contain the text, in any case, in the template editor and the ArchiMate canvas alike. The ArchiMate canvas
+editor adds `ViewpointRule`: with `nodeOptions.viewpoint` (⚙ Settings → Viewpoint), elements of types the
+viewpoint does not allow are faded, or hidden with `viewpointMode: 'hide'` (⚙ Settings → Outside the
+viewpoint), a line with one end outside is faded and one with both outside hidden; notes and canvas boxes are
+left alone. It also adds `ElementFilterRule` (`editor.setElementFilter(elementIds)`, null clears), which
+dims the model elements a filter did not keep. The palette then offers only the types the viewpoint allows
+(`new ArchimatePalette({ viewpoint })`).
+
+```js
+editor.setHighlight('order');                       // the rest dimmed
+canvasEditor.nodeOptions = { ...canvasEditor.nodeOptions, viewpoint: 'Organization', viewpointMode: 'fade' };
+canvasEditor.templateEmphasis(appComponentShape);   // 'faded'
+```
+
+**View menu, image export, model check, generated views.** These live in the `DiagramEditor` base, so the
+template editor (the testbed) and both ArchiMate editors have them. The **View** menu
+(`editor.viewMenuItems()`) has **Zoom to fit** (`editor.zoomToFit()`: everything drawn in sight, in the
+drawing's own units; `ViewFit` computes it, as a viewBox for the graph engine or a scale and pan for the
+template editor), **Reset zoom**, **Highlight…** (below), and, when the editor has a `model`, **Check model…**
+(`editor.showModelCheck()`). The checks are the model's own (`model.checker(options)`): a `ViewSetChecker` for
+any view set (empty views; an empty template is not one), and for an ArchiMate model an `ArchimateModelChecker`
+that adds relationships the specification does not allow, likely duplicates (elements of one type whose names
+have the same words, ignoring case, punctuation, word order and filler words such as "of" and "the":
+`nameKey(name)` and `duplicateGroups(elements)` in `diagrams/duplicates.js`), elements and relationships on no
+view, nested elements with no relationship, and names or documentation with unprintable characters (control
+characters, zero-width spaces; tabs and line breaks are fine in documentation). Each check is a method listed by
+`checks()`, so a subclass changes the set; choosing a finding shows it (`editor.revealFinding(finding)`: its view,
+its shape, or in the ArchiMate tree), and a finding can offer actions beside it (`editor.findingActions(finding)`).
+On the ArchiMate canvas, likely duplicates have **Merge…**: choose the element to keep (each choice says how many
+views and relationships use it) and the others are merged into it, one undo step (`model.mergeCommand(keepId,
+otherIds)`, a `MergeElementsCommand`). The kept element takes their relationships, their boxes on every view, the
+documentation and properties it lacks and a specialization if it has none; a relationship left joining it to
+itself, or the same as another, goes, its lines drawn as the other. The **File** menu (`EditorPart`'s, and the ArchiMate editor's) exports the current view
+as an image: PNG, SVG or a copy to the clipboard (`editor.exportImage('png' | 'svg' | 'copy')`, without the grid
+or selection; the ArchiMate editor's is off with `features.exportImage: false`). **Generate View For This**, on
+an element's menu in the diagram or the tree, makes a view of the element with everything related to it
+around it and every relationship between them (`model.generateView(elementIds, { name, related })`, Archi's
+"Generate View For").
+
+```js
+model.checker({ version: '3.2' }).run();   // [{ code, severity, kind, ids, message }, ...]
+model.generateView(['customer']);          // a new current view: the customer and what it relates to
+```
+
+**Properties of an element, note or line.** Double-click it, or **Show/Edit Properties…** on its menu. The
+dialog's Object section is the concept (name, type, documentation as "description", specialization,
+properties), the same on every view; its Diagram section is how this view draws it: label, fill colour, line
+colour, text colour and icon, and a **Text** section from `TextStyle` (font, text size, bold, italic, alignment,
+position; the same fields the template editor shows). Bold and italic go to Archi in its font; Archi has no
+underline, so it is offered for template shapes only. Save
+keeps the changes where they live: the concept's in the model (a note's, image's or plain line's in the item
+itself), the rest on the view's instance, as one undo step on the view (`EditViewItemCommand`;
+`editor.editItemProperties(item, kind)` opens it, `viewItemChanges(kind, before, after)` sorts an edit). A
+line's colour is this view's. "No colour" (`none`) draws no fill or no outline; an element's icon then stays
+black.
+
+**Views.** Right-click a view's tab, or its node in the model tree, for **Properties…**, **Duplicate**
+and **Delete** (the last view stays); the File menu starts with **New view…** and the current view's
+items. Double-clicking empty canvas, or the canvas menu's **View Properties…**, opens the same
+properties. `SettingsViewPropertiesDialog` edits the view's name (through `model.renameView`) and
+documentation, then the view's level of the settings cascade: routing, grid size and grid shown under
+Diagram, and background colour and image, a title band (text, position) and the watermark under
+Appearance. A cascading setting may inherit, and shows the value and the level it would come from. The diagram draws the view's resolved settings (background, title band, watermark).
+A filter (the tree's Filters…) is matched by model element, so it treats every view, a duplicate
+included, the same way, and never dims notes or images.
+A duplicate is independent: every element and relationship instance is copied with a new id, each
+relationship re-linked to the copied ends, with the element filter, viewpoint, documentation, view
+settings and folder layout; its undo history starts empty. View documentation round-trips through
+Archi export and import. The editor follows its model, so the same happens however a view is
+changed: `editor.model.duplicateView(id)` opens and shows the copy, deleting a view closes its tab.
+
+**Canvases and templates.** As in Archi, canvases (`CanvasView`) have a **Canvases** folder of their own in
+the model tree, keeping Archi's sub-folders, and **Views** lists only the other views (`model.diagramViews()`,
+`model.canvases()`, `model.templates()`). The **Templates** folder holds the model's own templates (canvases
+marked `template`, saved in the `.archimate` file) and a **Library** of templates kept across models: a
+`CanvasTemplateLibrary` (a `TemplateLibrary`, the base any kind of view's library extends: entries, built-ins
+`DEFAULTS`, storage under `STORAGE_KEY`, change events), by default in this browser's storage (the editor's `templateLibrary` option takes
+another, or `null` for none). Right-click Canvases for **New canvas…** and **New canvas from template**; a
+canvas for **Save as model template…** and **Save to template library…**; a template for **New canvas from
+this**; Templates or Library for **Import Archi template…**, which reads Archi's `.archicanvas` and
+`.architemplate` files (a zip of a manifest, a thumbnail and the template's model, pictures included) into the
+library. The File menu offers the same. `CanvasTemplateMenu` builds these items, as `ViewMenu` does for views;
+its `askName`, `chooseFile` and `report` options replace the dialogs. A canvas made from a template gets new
+ids and the template's boxes and lines; the boxes become the canvas's background (a locked `BackgroundGroup`,
+behind everything added later; see "A background" under grouping and locking).
+
+**Drawing on a canvas: Archi's palette, lines and hints.** On a canvas, right-click empty space for **Add
+Block**, **Add Sticky** and **Add Image…** (a picture file): the box is centred where you clicked, one undo step
+(`canvas.addBox(kind, at, { name, iconUrl })`; the kinds, with Archi's classes and looks, are `CANVAS_BOX_KINDS`,
+each a `CanvasBoxKind`; `canvasBoxMenuItems(view, at)` is the one menu definition both ArchiMate editors use).
+A line drawn between two boxes is a canvas connection (Archi's `CanvasModelConnection`), not a relationship:
+which a line is, is the view's rule (`view.linesAreRelationships(a, b)`: both ends model elements), so a line
+from a note on an ArchiMate view is a plain line too (`view.connect(a, b)` draws one, `view.removeRelationship(id)`
+takes it off; one undo step each). A **Hints** panel in the drawing's corner (`HintPanel`, folds to its header)
+shows the canvas's hint, and a box's own when it is clicked (`canvas.hint`, `canvas.hintFor(id)`; `ArchiHint`
+reads Archi's `hintTitle`/`hintContent` from any record and turns the HTML into plain text: it is never
+inserted as HTML). **Edit Hint…** on a box, and **Edit Canvas Hint…** on empty canvas, set a hint as a title and
+plain text, one undo step (`EditHintCommand`, on anything with an `archi` record; `ArchiHint.write` stores the
+text as escaped HTML paragraphs, as Archi keeps it; `hintMenuItems(view, itemId)` is the one menu definition). In
+the canvas editor, a canvas's side palette is Archi's (`CanvasPalette`, a kind of `ArchimatePalette`: Block,
+Sticky, Image, clicked or dragged in), and its plain lines are drawn and edited like any line (`ViewLineEdge`).
+
+```js
+const goal = canvas.addBox('block', { x: 300, y: 200 }, { name: 'Goals' });
+const idea = canvas.addBox('sticky', { x: 600, y: 200 }, { name: 'Idea' });
+canvas.connect(idea.id, goal.id);                      // a CanvasModelConnection
+canvas.hintFor(goal.id);                               // { title, content, text } or the canvas's
+```
+
+**Placing a template, and saving part of a canvas.** Right-click empty canvas for **Place template ▸** (the
+model's templates, then the library's): its boxes and lines go where you clicked, as their own locked
+background group, one undo step (`canvas.placeTemplate(source, { at, name })`, a `PlaceItemsCommand`), in front
+of any earlier background and behind everything else. Right-click a box for **Save as template ▸** (model or
+library): the box with its group (in the canvas editor, the selection with its groups), and the lines between
+them (`canvas.toJSON({ itemIds })`, `model.saveAsTemplate(viewId, title, { itemIds })`; `Arrangement#only(ids)`
+keeps their groups and locks). `CanvasTemplateMenu` builds these items (`placeTemplateItems(viewId, at)`,
+`saveAsTemplateItems(viewId, { itemIds })`) for both ArchiMate editors; the template editor's base offers the
+hooks (`shapeMenuExtras(id)`, `canvasMenuItems(at)` for empty canvas).
+
+```js
+canvas.placeTemplate(library.get('builtin-kanban').view, { at: { x: 400, y: 300 } });   // locked, behind
+model.saveAsTemplate(canvas.id, 'Lanes', { itemIds: [laneA, laneB] });                // a model template of two boxes
+```
+
+The library starts with built-in templates, so there is something to choose before anything is imported:
+SWOT analysis, PESTLE analysis, Stakeholder map (power and interest), Priority matrix (urgent and
+important), Retrospective, Kanban board and Architecture decision (`DEFAULT_CANVAS_TEMPLATES`). They are
+written for RenderEngine; each block carries a hint (Archi's `hintTitle`/`hintContent`), so a canvas made
+from one explains itself in Archi too. Built-ins come first, are marked `builtIn`, are not stored, and cannot
+be renamed or removed; `new CanvasTemplateLibrary({ defaults })` replaces them, and `defaults: []` gives none.
+`canvasTemplate({ id, name, description, blocks })` makes an entry from a list of blocks.
+
+```js
+const library = new CanvasTemplateLibrary();                 // or { store: { load(fallback), save(value) } }
+model.newCanvasFromTemplate(library.get('builtin-swot').view, 'Our SWOT');
+const [bmc] = library.importArchiTemplate(bytes);           // an .archicanvas file's bytes
+const canvas = model.newCanvasFromTemplate(bmc.view, 'Our business model');   // current view
+model.saveAsTemplate(canvas.id, 'Business model template'); // a model template; current view unchanged
+library.add({ view: canvas.toJSON(), name: 'Mine' });       // a library template
+```
+
+Archi's own canvas templates are not bundled (their content is licensed CC BY-SA); import them from an
+Archi install's `plugins/com.archimatetool.canvas_<version>/templates` folder.
+
+**`ArchimateDiagramEditor`** is a reusable, self-contained class that encapsulates the complete lifecycle
+of an ArchiMate modeling UI: DOM structure creation, toolbar UI generation, model management, tree
+navigation, diagram rendering with styling, export/import, and control wiring. It is exported from both
+`RenderEngine` and `RenderEngineWorkspace`.
+
+### Self-contained design
+
+The class owns **everything**: DOM structure, CSS styling, toolbar controls, event handling, and diagram
+rendering. The host HTML needs only:
+- One outer container div (e.g., `<div id="app"></div>`)
+- Model data (elements, relationships, views)
+- Feature configuration
+
+### Setup (with automatic toolbar)
+
+```javascript
+new RenderEngineWorkspace.ArchimateDiagramEditor({
+    elements: [...],
+    relationships: [...],
+    views: [...],
+    document,
+    appContainerId: 'app',  // Class generates toolbar, main, tree, diagram divs
+    features: {              // Toolbar is auto-generated based on these flags
+        version: true,
+        viewpoint: true,
+        distinctShapes: true,
+        showDerived: true,
+        exportCSV: true,
+        importCSV: true,
+        exportArchimate: true,
+        importArchimate: true,
+    },
+    workspace: window.RenderEngineWorkspace,
+}).render();
+```
+
+### Setup (legacy: manual HTML + wireControls)
+
+If you prefer to supply your own HTML with existing controls, omit `features` and use `wireControls()`:
+
+```javascript
+const editor = new RenderEngineWorkspace.ArchimateDiagramEditor({
+    elements: [...],
+    relationships: [...],
+    views: [...],
+    document,
+    appContainerId: 'app',           // or provide pre-made divs:
+    toolbarContainerId: 'toolbar',   // treeContainerId: 'tree',
+    treeContainerId: 'tree',         // diagramContainerId: 'diagram'
+    diagramContainerId: 'diagram',
+    workspace: window.RenderEngineWorkspace,
+});
+
+// Wire controls for manually-created HTML
+editor.wireControls();
+editor.render();
+```
+
+### Core methods
+
+- **`render(options)`** — Render the current view's diagram with all options, styling, and position persistence. Called automatically on control changes if auto-toolbar is enabled.
+- **`savePositions()`** — Save element positions before a view switch.
+- **`exportCSV()`** — Export model to CSV format (elements + relationships). Returns a `Blob`.
+- **`importCSV(elementsCSV, relationshipsCSV)`** — Import the two CSV tables and replace the model: its elements and relationships, with one view of them all ("Imported elements"; a CSV holds no views). `importCSVText(text)` takes the one file `exportCSV()` writes.
+- **`replaceModel(model)`** — Edit another `ArchimateModel` in place of this one (every import ends here), closing the old views' tabs.
+- **`exportArchimate()`** — Export the model with every view as `.archimate` XML. Returns XML string (pictures stay `data:` URLs).
+- **`exportArchimateFile()`** — Export as Archi saves it: `toArchiFile`'s `{ data, archive, mimeType }`, a zip archive when a view holds pictures. The File menu's Export uses it.
+- **`importArchimate(file)`** — Import an Archi file, as XML text or as the file's bytes (plain or archived), and replace the entire model.
+- **`exportExchange()`** — Export the model as an Open Group Exchange Format file (XML text); its ArchiMate views are written, canvases and sketches are not. The File menu's "Export Exchange Format (.xml)" (feature `exportExchange`) downloads it.
+- **`importExchange(xml)`** — Import an Exchange Format file and replace the entire model (File menu, feature `importExchange`).
+- **`fileFormats`** (constructor option, default `ARCHIMATE_FILE_FORMATS`) — The file formats the File menu exports and imports; each is offered when its `features` flags are on (`export<featureName>`, `import<featureName>`).
+- **`wireControls(options)`** — Wire up control event listeners for manually-created HTML controls (version, viewpoint, distinct shapes, show derived, manage dialogs, filter). Auto-renders on change. Optional callbacks for custom handlers.
+- **`setupImageDragDrop()`** — Enable drag-drop and paste image support on diagram.
+- **`setDependencies(deps)`** — Inject dialog functions and custom callbacks (dependency injection).
+- **`saveSpecializations()`** — Persist specialization registry to localStorage.
+- **`getOption(controlId, defaultValue)`** — Read a control value from the DOM.
+
+### Properties (read-only)
+
+- **`model`** — The `ArchimateModel` instance.
+- **`tree`** — The `ModelTree` navigator.
+- **`currentView`** — The active `ArchimateView`.
+- **`currentEngine`** — The active `RenderEngine` instance for the view.
+- **`diagrams`** — The `DiagramTabs` tab manager. `diagrams.containerFor(viewId)` is the element a view is
+  drawn in. Nothing it builds carries an id (it uses the classes `diagram-area`, `diagram-tab-bar`, and
+  `diagram-view` with `data-view-id`), and each `SVGRenderer` prefixes its line-end marker ids
+  (`renderer.markerId('arrow')`, `renderer.markerUrl('arrow')` → `url(#re0-arrow)`), so several editors can
+  share a page.
+
+### Styling & View Properties
+
+The `render()` method applies:
+- **Background color** and **background image** to the diagram container.
+- **Title** (top or bottom, or hidden).
+- **Watermark** with three repeat modes: `'none'` (centered), `'repeat'` (diagonal), `'tile'` (canvas background).
+
+All are properties of the current view's model object and persisted with the view.
+
+All styling (page layout, containers, toolbar controls, tree nodes) is **generated by the class via CSS**—
+no stylesheets needed in host HTML.
+
+### Feature flags (auto-toolbar mode)
+
+When a `features` config is provided, the class builds its toolbar from `menuBarItems()`, rendered by
+the shared `MenuBar` (see "Toolbars and dialogs" below):
+
+- **`search`** — Regex-based element filter with magnifying glass icon (🔍) above the tree. Real-time filtering as user types. Accepts regex patterns (case-insensitive). Clear with backspace to restore full diagram. Also searches documentation with `{ searchDocs: true }` option.
+- **⚙ Settings** — a menu, always present, as in the template editor (`settingsMenuItems()`). It holds
+  the notation settings below, each shown with its current value, then **Model settings…** (the model
+  settings dialog, `showModelSettings()`: routing, grid, watermark).
+- **`version`** — Settings ▸ Version ▸ ArchiMate 4 / 3.2
+- **`viewpoint`** — Settings ▸ Viewpoint (every built-in and custom viewpoint) and ▸ Viewpoint mode (fade/hide)
+- **`distinctShapes`** — Settings ▸ Distinct shapes: on/off
+- **`showDerived`** — Settings ▸ Show derived: on/off
+- **`exportCSV`**, **`importCSV`**, **`exportArchimate`**, **`importArchimate`** — entries in the **File** menu,
+  after the view items (New view…, Properties…, Duplicate, Delete)
+
+An element's right-click menu orders it with the same **⬍ Order** submenu as the template editor
+(Bring to Front, Send to Back, Raise, Lower; `DiagramEditor.ORDER_OPERATIONS`), each one undo step on
+the view.
+
+Set any to `false` to leave that setting out of the menu. Values live on the editor: `getOption(key)` / `setOption(key, value)`,
+keys `archimate-version`, `archimate-viewpoint`, `archimate-viewpoint-mode`, `archimate-distinct-shapes`,
+`archimate-show-derived`. Hosts that supply their own controls with those element ids (legacy
+`wireControls()` mode) are read from the DOM when the editor holds no value.
+
+**Search feature examples:**
+```javascript
+// Basic search by name
+setFilter('business')         // Shows only business-layer elements
+
+// Regex patterns
+setFilter('actor|process')    // Shows actors and processes (alternation)
+setFilter('.*service')        // Shows elements ending with 'service'
+setFilter('^Customer')        // Shows elements starting with 'Customer'
+
+// Include documentation in search
+setFilter('critical', { searchDocs: true })
+setFilter('urgent', { searchDocs: true })
+
+// Clear filter
+setFilter('')                 // Restores full diagram
+```
+
+**Display behavior:**
+- **Diagram view:** Highlights matching elements with gold glow (others at 30% opacity)
+- **Tree panel:** Hides non-matching nodes (shows only matches)
+- **Combined effect:** Focus on matches while preserving diagram context
+
+**Visual styles:**
+- **Diagram matches:** Gold glow + 110% brightness
+- **Diagram non-matches:** 30% opacity (visible but de-emphasized)
+- **Tree non-matches:** Hidden completely (CSS display: none)
+
+### Example: Minimal setup (recommended)
+
+HTML: just an app container.
+```html
+<!DOCTYPE html>
+<html>
+<head><meta charset="UTF-8"><title>ArchiMate</title></head>
+<body>
+    <div id="app"></div>
+    <script src="renderengine-workspace.umd.js"></script>
+    <script>
+        new window.RenderEngineWorkspace.ArchimateDiagramEditor({
+            elements: [...],
+            relationships: [...],
+            views: [...],
+            document,
+            appContainerId: 'app',
+            features: {
+                version: true, viewpoint: true, distinctShapes: true,
+                showDerived: true, exportCSV: true, importCSV: true,
+                exportArchimate: true, importArchimate: true,
+            },
+            workspace: window.RenderEngineWorkspace,
+        }).render();
+    </script>
+</body>
+</html>
+```
+
+For a page of its own, `fullPage` (default `true`) fills the viewport; `false` fills the app container
+instead, as inside a workbench part. `model` hands in an `ArchimateModel` rather than building one from
+`elements`/`relationships`/`views`. See `examples/archimate-legacy.html` for the workbench host, and
+`test/charts.html` for integration with the workspace shell and dialog handlers.
+
+## Diagram templates and palette categories
+
+`DiagramEditor` shapes are `Template` subclasses (`src/charting/templates/`). Geometry is
+centre-based — `(x, y)` is the centre of a `width × height` box — and every template accepts
+`{ x, y, width, height, rotation, zIndex, fillColor, fillOpacity, strokeColor, strokeWidth, textColor }`
+and a text style: `fontFamily`, `fontSize` (a bare number is points), `fontWeight: 'bold'`, `fontStyle: 'italic'`,
+`textDecoration: 'underline'`, `textAlign` ('left' | 'center' | 'right') and `textPosition` ('top' | 'middle' |
+'bottom') (`TextStyle`; unset, the name is drawn at 12px at the shape's own label point). Unset sizes and
+colours come from the class's `static defaults`. A shape's properties dialog (double-click it) edits its name,
+place, colours and text style (Font, Text size, Bold, Italic, Underline, Alignment, Position) as one undo step;
+`serialize()` keeps the style. `TextStyle` is the one definition every editor uses: `fields(style)` and
+`fromValues(values)` for a FormDialog, `fromNode`/`toNode` for a graph-renderer node (whose position is
+`verticalAlign`), `svgAttributes(style)` and `block(style, box, lines)` for drawing (the graph renderer, the
+ArchiMate canvas shapes and the template shapes all place text with it).
+
+```js
+new RectangleTemplate('r1', 'Billing', { fontFamily: 'Georgia', fontSize: '14pt', fontWeight: 'bold', textAlign: 'left', textPosition: 'top' });
+```
+
+| Family | Classes |
+|---|---|
+| 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` |
+| Other | `CylinderTemplate`, `DocumentTemplate`, `NoteTemplate`, `DataStoreTemplate`, `ActorTemplate`, `LifelineTemplate` |
+
+A template draws its outline in `shapeElements(doc)`, or in `points()` when it extends
+`PolygonTemplate`. The base class adds the group, rotation, label and editor wiring, and
+`renderPreview(size)` reuses the same outline for the palette tile.
+
+**Edge endpoints.** `outline()` returns the visible outline as a polygon, with curves sampled
+(the default is the box). `boundaryPoint(dx, dy)` is where a ray from the centre in that
+on-screen direction meets the outline, rotation included. For concave outlines it uses the
+outermost crossing. A shape whose outline isn't its box overrides `outline()` to match what it
+draws. `EdgeGeometry.computeEdgePath` uses `info.boundaryPoint` whenever a node supplies one,
+for `'auto'` anchors and for pinned sides (`sourceSide`/`targetSide`). Nodes without one keep
+the `shape`-based model. `EdgeGeometry.endDirections(d)` returns the direction in which a path
+arrives at each end.
+
+**Selecting and bending edges.** Selection is editor state (`selectedEdgeId` /
+`selectedTemplateId`). Selecting a shape deselects the edge, and clicking empty canvas clears both
+(`clearSelection()`). Only the selected edge shows handles: end dots, solid waypoints, and a
+hollow handle mid-segment. Click or drag a hollow handle, double-click the line, or right-click →
+*Add waypoint here* to add a bend. It is inserted into the nearest segment, so the route keeps
+its order. Drag a waypoint to move it. Double-click it or right-click → *Delete waypoint* to
+remove it, or use *Straighten* to remove all of them. Points snap to the grid while it is shown
+and are converted through pan/zoom. The programmatic forms are `addWaypoint(edgeId, {x, y})`,
+`removeWaypoint(edgeId, index)` and `clearWaypoints(edgeId)`. Each is one undo step.
+
+**Reconnecting.** Drag either end dot of the selected edge onto another shape to move that
+end. Waypoints and style are kept, and that end's side pin resets to automatic. Dropping it on
+empty canvas, or on the shape at the other end, cancels. This is one undo step
+(`ReconnectEdgeCommand`).
+
+**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
+single list of cascading properties:
+
+| Key | Values (default first) |
+|---|---|
+| `routing` | `straight`, `orthogonal`, `curved`, `polyline` (bends around other shapes) |
+| `attach` | `floating` (outline, aimed at the other end), `sides` (middle of the facing side) |
+| `lineStyle` | `solid`, `dashed`, `dotted` (same dash patterns as `GraphDiagram`, via `LINE_STYLE_DASH`) |
+| `strokeColor`, `strokeWidth` | `#666666`, `2` |
+| `startMarker`, `endMarker` | `none`, or an `EdgeMarker` key |
+
+`LINE_ONLY_PROPERTIES` lists `label`, `sourceSide` and `targetSide`; these never cascade. A
+pinned side beats `attach`. `editor.editLineStyle(levelKey)` opens the defaults dialog for one
+level, and the edge's *Properties* dialog edits the line. In both, every cascading field offers
+*Inherit*, labelled with the value and the level it would come from. Changes go through
+`SetStyleCommand` (one undo step; `undefined` = inherit). The editor never stores the levels
+itself, so the host decides what a level is and where it persists:
+
+```javascript
+new DiagramEditor({
+    diagramContainerId: 'canvas',
+    edgeStyleLevels: [
+        { key: 'view', label: 'Diagram', style: view.edgeStyle },   // per diagram tab
+        { key: 'model', label: 'Model', style: model.edgeStyle },   // shared by the model's diagrams
+        { key: 'tool', label: 'Tool', style: toolDefaults },        // e.g. persisted in localStorage
+    ],
+});
+```
+
+`MenuBar`'s Settings menu adds one *Line style: … defaults* entry per level.
+
+**Edge markers.** `edge.startMarker` / `edge.endMarker` hold an `EdgeMarker` key:
+`arrow`, `openarrow`, `openarrowhalf`, `trianglehollow`, `diamond`, `diamondhollow`, `circle` or
+`crowsfoot` (`EDGE_MARKERS`). `getEdgeMarker(value)` ignores case and punctuation, so
+`"Crow's Foot"` resolves too, and so do ArchiMate's own arrowhead names (`diamond-hollow`,
+`open-arrow-half`, …). A marker's `shapes(tip, dir, size, color, background)` returns element
+descriptors whose tip is on the boundary and whose body extends back along the arriving
+segment, so nothing is hidden under the node; hollow markers are filled with `background`
+(default white) so the line does not show through them.
+
+**Glyphs.** Every node shape the graph engine draws (`rect`, `circle`, `diamond`, `note`,
+`image`, `icon`, `person` and the ArchiMate notation shapes `pill`, `cube`, `chevron`, …) is a
+`Glyph` subclass in `src/charting/glyphs/`, one per file. `glyphFor(key)` returns it (an unknown key
+gives the circle) and `GLYPHS` maps every key. `glyph.parts(Glyph.context({R, size, color,
+cornerStyle, strokeColor, strokeWidth, icon, iconUrl}))` describes the shape centred on (0, 0) as
+`rect`/`circle`/`path`/`image`/`text`/`group` parts; `drawGlyph(renderer, parts)` draws them through
+a renderer. A glyph whose `ownsInterior` is true gets no centred icon or initials on top.
+
+```javascript
+const parts = glyphFor('cube').parts(Glyph.context({ R: 30, size: { w: 120, h: 55 }, color: '#AFFFAF', strokeColor: '#000', strokeWidth: 1.2 }));
+parts.children.length;   // 3: front, top and side faces
+```
+
+`GlyphTemplate` is a template drawn by a glyph: a subclass names the glyph (`glyph()`) and its
+context, and the template draws its parts as SVG (`glyphToSvg`; `glyphElement(part)` gives the tag and
+attributes, by the SVG renderer's rules) and attaches lines to the glyph's `outline(ctx)`. Every glyph
+has an outline: its box by default, the real shape for round, skewed and pointed ones.
+
+**ArchiMate in the template editor.** `ArchimateElementTemplate(instance, model, {nodeOptions})` and
+`ArchimateEdge(instance, view)` put an `ArchimateView` into a `DiagramEditor`. Neither keeps a copy:
+position, size, stacking and per-view paint are read from and written to the `ElementInstance`, the
+route, pinned sides and per-line style to the `RelationshipInstance`, so the editor's move, resize,
+waypoint, side and style commands edit the view and undo through `view.history`. A template looks as
+the graph engine draws the element (`ArchimateDiagram.buildNode`: layer colour, corner style, type
+glyph badge, or the full notation shape with `nodeOptions.useDistinctShapes`); notes and images
+(`ViewObjectInstance`) draw their own glyph. A line's dashes and end markers come from its
+relationship's kind and cannot be set on the line; routing, attach, colour and width can, and unset
+inherits. Its ends come from the instance (re-linking an end is a model edit, not a line edit).
+
+```javascript
+const view = model.currentView;
+const templates = new Map([...view.elementInstances.values()].map(i => [i.id, new ArchimateElementTemplate(i, model)]));
+const edges = new Map([...view.relationshipInstances.values()].map(i => [i.id, new ArchimateEdge(i, view)]));
+new DiagramEditor({ diagramContainerId: 'canvas', templates, edges, history: view.history }).render();
+```
+
+`ArchimateCanvasEditor({view, model, nodeOptions, chooseKind, ...DiagramEditor options})` is that
+editor as a class: it rebuilds its templates and lines from the view on every render (so an undone
+view edit shows at once), uses the view's history, and does through the view and model what stands
+for something else in ArchiMate, each as one undo step:
+- `addElement(type, point)`, and dropping an `ArchimatePalette` tile (`ARCHIMATE_TYPE_MIME`), creates a
+  model element named after its type and shows it;
+- connecting two elements (`connect(sourceId, targetId)`) creates a relationship. Its kind is asked
+  for through `chooseKind(kinds, from, to)` (a promise or value; null cancels) among
+  `allowedKinds(sourceId, targetId)`, or without a chooser is the first of `KIND_PREFERENCE` that is
+  allowed (the dependency kinds before the structural whole/part ones). Notes and images take none;
+- deleting an element takes it and its lines off the view; deleting a line takes the relationship
+  off; the model keeps both.
+
+`ArchimatePalette({version, onPick, document})` renders the element types grouped by layer
+(`ArchimatePalette.groups(version)`: the notation's layers, then ArchiMate 4's common behaviour types),
+each tile only its notation glyph in its layer colour, four to a row (`ArchimatePalette.TILE`; the name shows on hover); drag a tile onto the canvas or click it (`onPick`).
+
+`ArchimateCanvasPart` (workspace bundle, type `archimate-canvas`; `examples/archimate.html`, and the testbed
+`test/archimate-canvas-testbed.html`) is the
+modeller on this canvas: toolbar (File with the view items,
+version, distinct shapes, zoom, connect, Settings), palette, one tab per view (Properties…, Duplicate,
+Delete) and the canvas; connecting opens a picker of the allowed kinds. The model tree is on the left, with a search box
+(the tree's text filter: it hides what it leaves out there and dims it on the canvas), and the palette on the right,
+as in Archi. File offers New view…, New canvas… and New canvas from template (`EditorPart#newItems()`), the open
+canvas saved as a template, and Import Archi template…. Dragging an element from the tree onto the canvas shows it there
+with its relationships to the elements already shown, one undo step (`editor.showElement(elementId, point)`,
+`ShowElementCommand`: only lines to or from the new box; redo adds the same lines). The File menu exports
+and imports CSV, `.archimate` and the Exchange Format; an import replaces the part's model
+(`part.replaceModel`) and the tree, canvas and menus follow it. Spec: `elements`, `relationships`,
+`views`, `name`, `archimateVersion`, `distinctShapes`, `viewpoint`, `viewpointMode`.
+
+**File formats.** `ModelFileFormat` is one format a model is exported to and imported from: a subclass gives
+`label`, `accept`, `fileName`, `readsBytes` (import gets the file's bytes, not its text), `featureName`, and
+`export(model)` (`{ data, mimeType }`) and `import(data)` (a new model). `modelFileMenuItems(formats, { model,
+onImport, enabled })` makes the File menu's Export and Import items, one group per format: export downloads
+the file, import asks for one and hands the new model to `onImport` (a failure is reported and the model kept).
+`ARCHIMATE_FILE_FORMATS` are `ArchimateCsvFileFormat` (both tables in one file; import lays all the elements
+out in one view), `ArchiFileFormat` and `ExchangeFileFormat`; both ArchiMate editors read them.
+
+```js
+import { ARCHIMATE_FILE_FORMATS } from 'renderengine';
+const [csv] = ARCHIMATE_FILE_FORMATS;
+const { data } = csv.export(model);          // '=== elements.csv ===\n...'
+const copy = csv.import(data);               // a new ArchimateModel, with the view "Imported elements"
+```
+
+**Model tree layers.** The tree's Layers folder files an element under its layer as the diagram draws it
+(`treeLayerOf(element)`: its own `layer`, an IT type's, or its notation type's), in the order `TREE_LAYERS`;
+anything else (junction, grouping, location, an ArchiMate 4 common type) is under Other, as in Archi. A
+tree leaf dragged anywhere carries its element id as `MODEL_ELEMENT_MIME`.
+
+An instance's `appearance` (`fillColor`, `fillOpacity`, `strokeColor`, `strokeWidth`, `textColor`, the text style
+keys `fontFamily`, `fontSize`, `fontWeight`, `fontStyle`, `textDecoration`; on a
+relationship instance the line style keys) is this occurrence's own paint; the graph engine draws it
+too. A template whose properties are computed reports what it holds itself through
+`ownProperty(key)`, which `SetPropertiesCommand` uses so undo restores "unset" rather than the
+computed value.
+
+Each ArchiMate relationship type gives its notation as line style values:
+`ArchimateNotation.relationshipType('composition').edgeStyle()` is
+`{ lineStyle: 'solid', startMarker: 'diamond', endMarker: 'none' }`; arrowheads come back as marker keys
+(`realization` ends in `'trianglehollow'`).
+
+`DIAGRAM_TYPES` (19 categories in the groups General, Process, UML, Data, Infrastructure,
+Business, Ideas) decides which templates the palette offers. `editor.initPaletteForDiagramType(container, key)`
+renders a grouped category picker above a grid of draggable tiles. `editor.setPaletteCategory(key)`
+switches category, and `onTemplateTypeChange(key)` (a constructor option) reports the switch.
+Unknown keys fall back to `'generic'` (Basic Shapes).
+
+Adding a shape and a category (runs under Node — no DOM needed until render):
+
+```javascript
+import { PolygonTemplate, DIAGRAM_TYPES, getDiagramTypesByGroup } from './src/index.js';
+
+class ChevronTemplate extends PolygonTemplate {
+    static defaults = { width: 120, height: 50 };
+    points() {
+        const n = this.height / 2;
+        return [[this.left, this.top], [this.right - n, this.top], [this.right, this.y],
+                [this.right - n, this.bottom], [this.left, this.bottom], [this.left + n, this.y]];
+    }
+}
+
+DIAGRAM_TYPES['value-chain'] = {
+    name: 'Value Chain', group: 'Business', description: 'Primary activities in sequence',
+    templates: [{ id: 'activity', name: 'Activity', factory: (id, x, y) => new ChevronTemplate(id, 'Activity', { x, y }) }],
+};
+
+console.log(DIAGRAM_TYPES['value-chain'].templates[0].factory('a1', 100, 50).points().length); // 6
+console.log(getDiagramTypesByGroup().find(g => g.group === 'Business').types.map(t => t.key));
+// [ 'organizational-chart', 'value-chain' ]
+```
+
+### Diagram models and the editor part
+
+`ViewSetModel` is the base of a model edited as several views: `views()`, `viewCount`, `getView`,
+`currentView`, and `createView`, `duplicateView`, `renameView`, `deleteView` (the last view can't be
+deleted; `canDeleteView` says so) and `switchTo`, each notifying `onChange` listeners. A subclass
+makes its own kind of view in `_newView(id, title)`; a view has an `id`, a `title` and
+`copy(id, title)`. `DiagramModel` and `ArchimateModel` both extend it.
+
+`ViewMenu(model, {document, noun, editProperties})` turns those operations into menu items:
+`newViewItem()` (asks for a name) and `items(viewId)` (Rename…, Duplicate, and Delete after a
+confirmation when allowed). Given `editProperties(view)`, a properties dialog that includes the name,
+**Properties…** takes Rename's place. Tab strips, File menus and the ArchiMate model tree all use it,
+and both editors pass a properties dialog, so their tabs offer the same **Properties…**, **Duplicate**
+and **Delete**.
+
+`ViewPropertiesDialog({model, view})` is the base of those dialogs: the view's name and documentation;
+a subclass adds `sections()` (more FormDialog fields) and `applySections(values)`.
+`SettingsViewPropertiesDialog` adds the view's level of the SettingsManager cascade (the ArchiMate
+editor's); `DiagramViewPropertiesDialog({cascade, levelKey, onStyleChange})` adds a diagram's
+line-style defaults, the `levelKey` level of an `EdgeStyleCascade`, applied as one undo step on the
+view's history (the template editor's). Both build their inheritable fields with
+`inheritableFields(properties, own, inherited)` (and read them back with `readInheritableFields`)
+from `SettingsCascade.js`, as `EdgeStyleDialog` does: each field shows its own value or offers
+"Inherit", labelled with the value and the level it would come from. `MODEL_SETTINGS_PROPERTIES`
+carries the labels, types and choices those forms use.
+
+The SettingsManager cascade resolves each of those settings through a view's own settings, then its
+model's, then the tool's, then the default (`cascade(view, modelId)`; `getModelOverrides(modelId)` is
+what the model level itself sets, `getModelSettings(modelId)` the model's resolved values). Global
+Settings sets the tool's value and the model's (which may inherit the tool's); a view's Properties sets
+the diagram's (which may inherit the model's). "Invalid relationships" (`invalidRelationships`:
+`highlight`, `tooltip`, `off`) is set this way.
+
+```js
+settingsManager.saveToolSettings({ invalidRelationships: 'tooltip' });   // every model, unless it says otherwise
+settingsManager.saveViewSettings(view, { invalidRelationships: 'off' });  // this diagram only
+settingsManager.getEffectiveSettings(view, 'default').invalidRelationships; // → 'off'
+```
+
+`DiagramModel` holds a set of diagrams (`DiagramView`s) edited together. It adds the palette
+category they share (`templateType`) and the model-level line style (`edgeStyle`). Each `DiagramView` owns its `templates`
+and `edges` maps, a diagram-level `edgeStyle` and its own `CommandHistory`. `view.copy()` is
+independent: shapes and lines are copied, and the history starts empty.
+
+Passing a view's maps and history to `DiagramEditor` binds the editor to that view: edits land
+in the view directly, and a rebuilt editor carries on with the same undo history:
+
+```javascript
+import { DiagramModel, DiagramEditor, RectangleTemplate } from './src/index.js';
+
+const model = new DiagramModel({ templateType: 'flowchart' });
+const view = model.createView('Context');
+const editor = new DiagramEditor({
+    enableKeyboardShortcuts: false,                 // no DOM needed for this example
+    templates: view.templates, edges: view.edges, history: view.history,
+});
+editor.addTemplate(new RectangleTemplate('a', 'Box'));
+console.log(view.templates.has('a'), model.duplicateView(view.id).title);   // true 'Context (copy)'
+```
+
+Call `editor.dispose()` before discarding an editor on a page that lives on. Its keyboard
+shortcuts and pan listeners are registered on `document`. Shortcuts ignore keys typed into
+form fields.
+
+**Subclassing.** The undo shortcuts and every command use `editor.history`, an accessor a
+subclass can redirect. `ArchimateDiagramEditor` maps it to `currentView.history` (the model's one history), and hands the same history to the graph engine it draws with. Canvas edits
+(move, resize, bend points, pinned sides, drawing a relationship) are recorded there too, written
+back to the view through the hooks above, and undo across re-renders. A relationship drawn between
+two elements is created in the model and on the view, and its kind is asked for once; undo removes
+it from both. The line's right-click **Delete from View** takes one relationship instance off the
+view and leaves the model relationship.
+
+**Views.** `DiagramEditorState` is the abstract base of every diagram view: its own `history` and
+the stacking operations below. A subclass says what stacks through `layerItems()`.
+`DiagramView` (the template editor's tabs) stacks its templates. `ArchimateView` stacks its element
+instances, and records adding and removing them as undo steps:
+`view.addToView(instance, { element })` shows an `ElementInstance` (creating the model element
+first when `element` is given, and widening `elementIds` to it), and `view.deleteElement(instanceId)`
+takes one off the view. Undo of either reverses all of it. `ArchimateModel.addElement(el)` and
+`removeElement(id)` are the model's side; position stays on the instance, so `addElement` does not
+keep an element's `x`/`y`.
+
+Relationships work the same way. `view.missingRelationshipInstances(elementId)` lists the pairings
+the view could draw but doesn't (each instance of the element against each instance at the other
+end of its relationships), `view.addRelationshipsToView(instances)` adds them as one undo step, and
+`view.removeRelationship(instanceId)` takes one off. `ArchimateModel.addRelationship(rel)` and
+`removeRelationship(id)` are the model's side.
+
+What a view draws per occurrence lives on the instance, so two occurrences of one element or
+relationship can differ:
+
+| Instance | Field | Meaning |
+|---|---|---|
+| `ElementInstance` | `x`, `y`, `zIndex` | position and stacking |
+| `ElementInstance` | `size` | `{width, height}` or `{radius}` set on this view; `{}` = the element's own |
+| `RelationshipInstance` | `waypoints` | this line's bend points; `null` inherits the model relationship's, `[]` is straight |
+| `RelationshipInstance` | `sourceSide`, `targetSide` | pinned attachment side; `null` = automatic |
+
+A note or image belongs to one view, not the model, so it is a `ViewObjectInstance` (a subclass of
+`ElementInstance`): it carries its own `content` (`{id, name, shape: 'note' | 'image', label, iconUrl,
+href, width, height}`), shows whatever the element filter says, and never appears in the model tree.
+A view also takes them as `viewObjects: [{content, x, y}]`, which is what an Archi import produces.
+
+```javascript
+view.addToView(new ViewObjectInstance({ id: 'n1', name: 'Remember', label: 'Remember', shape: 'note' }, 40, 300));
+model.getElement('n1');   // undefined: the note is the view's
+```
+
+A view's `edgeLayout` (`{relationshipId: {waypoints}}`, what an Archi import produces) is read once,
+at construction: it routes each instance of that relationship that has no route of its own.
+
+```javascript
+const model = new ArchimateModel({ elements: [{ id: 'a', name: 'A' }], views: [{ id: 'v', elementIds: ['a'] }] });
+const view = model.views()[0];
+view.addToView(new ElementInstance('note-1', 40, 60), { element: { id: 'note-1', name: 'Remember', shape: 'note' } });
+view.history.undo();   // the note leaves the view and the model; elementIds is ['a'] again
+``` A subclass whose drawing engine owns zoom, pan and canvas clicks passes
+`enableCanvasInteractions: false`. One that draws into another SVG overrides `_canvasSvg()` so
+`_clientToDiagram` and `_snapToGrid` keep working.
+
+**Stacking order.** `BringToFrontCommand`, `SendToBackCommand`, `RaiseCommand` and
+`LowerCommand` (all `ReorderCommand`s) work on any target with `layerItems()`: the editor's
+templates, or any view's `layerItems()` (`view.bringToFront(id)` and similar record one undo step
+on `view.history`). Raise and lower swap with the item actually drawn
+above or below, ties and gaps included. Each operation renumbers the stack to consecutive
+integers, and undo restores every previous value.
+
+`EditorPart` (workspace bundle) is the base of the workbench parts that edit a `ViewSetModel`: a
+subclass builds its model from the part's spec in `createModel(spec)`, and gets `part.model`,
+`part.viewMenu` and `fileMenu()` (the view items, then `fileMenuItems()`: export and import in each of
+its `fileFormats()`, none by default, then the image export), and its editor disposed with the part. An
+import goes through `replaceModel(model)`, which a subclass follows in `modelReplaced(model)`.
+`DiagramEditorPart`, `ArchimateEditorPart` and `ArchimateCanvasPart` extend it.
+
+`DiagramEditorPart` (workspace bundle) puts this together: `MenuBar` (File creates and deletes
+diagrams; Settings has the grid and line-style levels), the palette, a `ViewTabStrip` (right-click
+a tab for its **Properties…**: name, documentation and the diagram's line style; **Duplicate**;
+**Delete**) and the canvas. `part.edgeStyleLevels(view)` gives a diagram's line-style levels and
+`part.showViewProperties(view)` opens its properties. Spec options: `templateType`,
+`tabOrientation` (`'horizontal'`/`'vertical'`), `diagramTitle`, and `toolStyleKey`, the
+localStorage key for tool-level line style (`null` keeps it in memory only), saved through
+`LocalJsonStore`. Its levels are Diagram (`view.edgeStyle`), Model (`model.edgeStyle`) and Tool.
+
+```javascript
+const { DiagramEditorPart } = window.RenderEngineWorkspace;
+ws.registerPart(DiagramEditorPart);
+ws.addParts([{ id: 'editor', type: 'diagram-editor', title: 'Diagram Editor', templateType: 'flowchart' }]);
+ws.getPart('editor').model.currentView;   // seed or inspect content before or after mounting
+```
+
+The workspace bundle includes its own copy of the engine, so a page can hold two copies of every
+class. Library code imports its collaborators directly rather than looking them up on
+`window.RenderEngine`, and `CommandHistory.execute` accepts any object with `execute()` and
+`undo()` rather than checking `instanceof Command`. A command built from either bundle therefore
+works in either bundle's history.
+
+### Toolbars and dialogs
+
+`MenuBar` renders a row of toolbar items and has no controls of its own. Each editor contributes its
+items through `menuBarItems()`: the template editor gives zoom, connect mode and a ⚙ Settings menu (grid,
+grid size, line-style levels), and `ArchimateDiagramEditor` gives its File menu and a ⚙ Settings menu
+(notation and model settings). Each editor's ⚙ Settings menu reads `settingsMenuItems()`, which a
+subclass extends (ArchimateCanvasEditor puts version and distinct shapes in front of the grid and line
+styles). Every editor's shape menu orders with `orderMenuItem(id)`, the one Order submenu. A host can add more; `DiagramEditorPart` prepends its File menu (new, duplicate, rename, delete
+diagram). After an item acts, the bar re-renders. Items with live labels (the zoom %) also refresh on
+`editor.onRendered`.
+
+| Item | Use |
+|---|---|
+| `ToolbarMenu(label, items)` | Button opening a `PopupMenu`; `items` may be a function, evaluated on open |
+| `ToolbarButton(label, action, { title, active })` | Action, or a toggle when `active()` is given |
+| `ToolbarSelect(label, choices, value, onChange)` | Labelled dropdown; `choices()` returns `[value, text, title?]` |
+| `ToolbarCheckbox(label, checked, onChange)` | Labelled switch |
+| `ToolbarText(text, style)` | Live text |
+| `ToolbarSeparator()` | Divider |
+
+```javascript
+new MenuBar({ container, editor, items: [
+    new ToolbarMenu('File', [{ label: 'Export', action: exportIt }]),
+    ...editor.menuBarItems(),
+] }).render();
+```
+
+`FormDialog` is the one modal form: `fields` of type `text`, `textarea`, `number`, `color`, `select`
+or `checkbox`. A field with `inherit: { text, short? }` may be left unset; it then reads as `undefined` (a select
+offers `text` as its first choice; any other field, a checkbox too, gets a checkbox named `short`, default
+"Inherit", that greys it out). `FormDialog.many(fieldLists)` makes one form for several items from each one's
+fields: every field on "Keep" showing the value they share, read-only fields left out.
+`onApply(values)` receives every field; `onClose(applied)` is told once when the dialog closes, whether it
+was applied (false for Cancel, Escape or a click outside), so a caller waiting on a choice can settle.
+`EdgeStyleDialog`, the grid-size and diagram-name prompts are all `FormDialog`s. A dialog fits the window
+(at most 90% of its height): its fields scroll between the title and the buttons, which stay in view, and
+dragging the title moves it. A `textarea` scrolls inside its own box (at most 40% of the window) and can be
+dragged taller; a properties dialog shows `description`, `documentation`, `notes` and `tooltip` that way.
+A `color` field (`ColorField`) holds its value as text, `#rrggbb` or `none` for no colour (transparent, which a
+browser colour input cannot hold), beside the colour picker and a row of preset swatches: no colour, black,
+white, red, green, blue, yellow, orange, purple, grey and light grey (`ColorField.PRESETS`). A field's
+`presets` (`[{value, name}]`) replaces them, and `allowNone: false` leaves out "No colour".
+
+```js
+new FormDialog({ title: 'Box', fields: [
+    { key: 'fill', label: 'Fill colour', type: 'color', value: '#ffffb5' },                  // presets, none included
+    { key: 'text', label: 'Text colour', type: 'color', value: '#000000', allowNone: false },
+    { key: 'brand', label: 'Brand colour', type: 'color', presets: [{ value: '#0b5394', name: 'Brand blue' }] },
+], onApply: (values) => console.log(values.fill) }).open();                              // '#ffffb5', or 'none'
+
+const fields = (t) => [{ key: 'fill', label: 'Fill colour', type: 'color', value: t.fill }];
+new FormDialog({ title: '2 boxes', fields: FormDialog.many([fields({ fill: '#ff0000' }), fields({ fill: '#ff0000' })]),
+    onApply: (values) => console.log(values.fill) }).open();     // undefined while Keep is ticked
+```
+
+**Grouping and locking shapes.** A view's `arrangement` (`Arrangement`, on every `DiagramEditorState`, so a
+template diagram's `DiagramView` and an `ArchimateView` alike) says which items move as one (an
+`ItemGroup`: logical, it draws nothing but a dashed outline while a member is selected) and which are fixed in
+place (locked: not moved, resized, rotated, reordered, edited or deleted until unlocked; trying says so). A
+group can be locked as a whole; groups do not nest (grouping a member brings its group). Changes are one undo
+step each: `view.group(ids)`, `view.ungroup(id)`, `view.setLocked(ids, locked)`, or the commands
+`GroupCommand`, `UngroupCommand`, `LockCommand`. In the template editor (and ArchiMate's canvas editor, its
+subclass), Shift/Ctrl/⌘+click adds to the selection; dragging a selected shape moves the selection with its
+groups, as one step, and nothing moves if any of it is locked. In ArchiMate's graph editor, dragging a box
+moves its group with it, as one step. A shape's menu offers Group, Ungroup and Lock / Unlock
+(`arrangeMenuItems(arrangement, ids, act)`, the one definition every editor uses; Ungroup only once unlocked),
+as do Ctrl+G, Ctrl+Shift+G and Ctrl+L; a locked shape shows a lock and no resize or rotate handles.
+
+**A background.** A kind of group is an `ItemGroup` subclass, kept by its JSON's `kind`. A `BackgroundGroup` is
+pinned behind everything else on its view: its members stack below every other item, so "Send to back" on
+anything else stops just in front of it, and its own members reorder only among themselves.
+`view.arrangeAsBackground(ids, { name })` (or the undoable `BackgroundCommand`) makes items one locked
+background group, behind the rest. A canvas made from a template gets its template's boxes this way, so the
+template stays at the back and holds still until it is unlocked (the shape's menu, **Unlock background**);
+unlocked, it moves as one; ungrouped, its boxes are ordinary boxes. Archi files keep it: each member carries
+the group (`renderengine.group`), its kind (`renderengine.groupKind`) and the lock.
+
+```js
+const groupId = view.group(['a', 'b']);   // a and b move together
+view.setLocked(['a'], true);               // the group is fixed in place
+view.arrangement.canMove(['b']);           // → false
+view.history.undo();                       // free again
+view.arrangeAsBackground(['t1', 't2']);    // behind everything, locked, moved as one when unlocked
+```
+
+**Connecting and deleting in the template editor** are commands, one undo step each:
+`editor.connect(sourceId, targetId)` runs `connectCommand(sourceId, targetId)` (a new line), and
+`deleteTemplate(id)` / `deleteEdge(id)` run `deleteTemplateCommand(id)` (the shape and the lines joined
+to it) / `deleteEdgeCommand(id)`. A subclass whose shapes and lines stand for something else
+overrides those factories (ArchimateCanvasEditor does). A template class says whether the editor
+offers it a rotate handle (`static rotatable`, true by default; ArchiMate's templates are not). `pickFile(accept)` resolves with the chosen `File` (or `null`).
+
+## Where to go next
+
+- **`ARCHITECTURE.md`** — module layout, the chart-type catalog mechanics, how to add a new chart type.
+- **`CHART_TYPES_ROADMAP.md`** — per-chart-type design rationale and what's deliberately deferred.
+- **`examples/csv-chart-builder.html`** — every chart type live, including the actual "Live updates"
+  panel this doc's streaming section is drawn from; open it in a browser to see the pattern run.
+- **`test/charts.html`** — a plainer interactive demo of the core chart set.