@peter.prib/renderengine 0.0.0-stage → 0.1.0

package/src/index.js

@@ -0,0 +1,2564 @@
+import { RendererFactory } from './RendererFactory.js';
+import { Mat4 } from './Mat4.js';
+import { OrbitCamera } from './OrbitCamera.js';
+import {
+  CHART_CATALOG, getChartCatalogEntry, chartRegistry,
+  AXIS_KIND, ENCODING_CHANNEL, COORD_SYSTEM, COLOR_MODE, CAMERA_MODE,
+} from './chartCatalog.js';
+import {
+  DIAGRAM_CATALOG, getDiagramCatalogEntry, diagramRegistry,
+} from './diagramCatalog.js';
+import { ChartBox, ChartLabels } from './charting/ChartBox.js';
+import { Axis } from './charting/Axis.js';
+import { Legend } from './charting/Legend.js';
+import { ColorPalette } from './charting/ColorPalette.js';
+import { ShapePaths } from './charting/ShapePaths.js';
+import { BarChart } from './charting/charts/BarChart.js';
+import { GroupedBarChart } from './charting/charts/GroupedBarChart.js';
+import { LineChart } from './charting/charts/LineChart.js';
+import { AreaChart } from './charting/charts/AreaChart.js';
+import { StackedAreaChart } from './charting/charts/StackedAreaChart.js';
+import { PieChart } from './charting/charts/PieChart.js';
+import { DonutChart } from './charting/charts/DonutChart.js';
+import { PipeChart } from './charting/charts/PipeChart.js';
+import { StackedBarChart } from './charting/charts/StackedBarChart.js';
+import { ScatterChart } from './charting/charts/ScatterChart.js';
+import { BubbleChart } from './charting/charts/BubbleChart.js';
+import { HistogramChart } from './charting/charts/HistogramChart.js';
+import { BoxPlotChart } from './charting/charts/BoxPlotChart.js';
+import { DensityChart } from './charting/charts/DensityChart.js';
+import { ViolinChart } from './charting/charts/ViolinChart.js';
+import { QQPlotChart } from './charting/charts/QQPlotChart.js';
+import { LagPlotChart } from './charting/charts/LagPlotChart.js';
+import { TreemapChart } from './charting/charts/TreemapChart.js';
+import { SunburstChart } from './charting/charts/SunburstChart.js';
+import { OutlineChart } from './charting/charts/OutlineChart.js';
+import { RadarChart } from './charting/charts/RadarChart.js';
+import { FunnelChart } from './charting/charts/FunnelChart.js';
+import { WaterfallChart } from './charting/charts/WaterfallChart.js';
+import { BarGauge } from './charting/charts/BarGauge.js';
+import { BulletGauge } from './charting/charts/BulletGauge.js';
+import { DialGauge } from './charting/charts/DialGauge.js';
+import { BarChart3D } from './charting/charts/BarChart3D.js';
+import { BubbleChart3D } from './charting/charts/BubbleChart3D.js';
+import { BarChart3DOrbit } from './charting/charts/BarChart3DOrbit.js';
+import { StackedBarChart3DOrbit } from './charting/charts/StackedBarChart3DOrbit.js';
+import { CalendarHeatmapChart } from './charting/charts/CalendarHeatmapChart.js';
+import { GanttChart } from './charting/charts/GanttChart.js';
+import { StreamGraphChart } from './charting/charts/StreamGraphChart.js';
+import { RadialBarChart } from './charting/charts/RadialBarChart.js';
+import { PopulationPyramidChart } from './charting/charts/PopulationPyramidChart.js';
+import { SankeyDiagram } from './charting/charts/SankeyDiagram.js';
+import { ChordDiagram } from './charting/charts/ChordDiagram.js';
+import { WordCloudChart } from './charting/charts/WordCloudChart.js';
+import { ParallelCoordinatesChart } from './charting/charts/ParallelCoordinatesChart.js';
+import { GeoMapChart } from './charting/charts/GeoMapChart.js';
+import { HeatmapChart } from './charting/charts/HeatmapChart.js';
+import { CandlestickChart } from './charting/charts/CandlestickChart.js';
+import { ShapeFactory } from './charting/shapes/ShapeFactory.js';
+import { Statistics } from './charting/Statistics.js';
+import { Chart3D } from './charting/Chart3D.js';
+import { Hierarchy } from './charting/Hierarchy.js';
+import { Gauge } from './charting/Gauge.js';
+import { ChartData } from './charting/ChartData.js';
+import { DataFilter } from './charting/DataFilter.js';
+import { InteractionManager } from './charting/InteractionManager.js';
+import { ebnfAstToDiagram } from './ebnfDiagram.js';
+import { parseEbnf } from './ebnfParser.js';
+import { Command, CompositeCommand, CommandHistory } from './charting/CommandHistory.js';
+import { Diagram } from './charting/Diagram.js';
+import { Diagram3D } from './charting/Diagram3D.js';
+import { EbnfDiagram } from './charting/diagrams/EbnfDiagram.js';
+import { GraphDiagram } from './charting/diagrams/GraphDiagram.js';
+import { GraphDiagram3D } from './charting/diagrams/GraphDiagram3D.js';
+import { GraphMetrics } from './charting/diagrams/GraphMetrics.js';
+import { LabelHelper } from './charting/diagrams/LabelHelper.js';
+import { NodeGeometry } from './charting/diagrams/NodeGeometry.js';
+import { SvgCoordinate } from './charting/diagrams/SvgCoordinate.js';
+import { EdgeGeometry } from './charting/diagrams/EdgeGeometry.js';
+import { RadialLayout } from './charting/diagrams/RadialLayout.js';
+import { DerivedRelationships } from './charting/diagrams/DerivedRelationships.js';
+import { ArchimateDiagram } from './charting/diagrams/ArchimateDiagram.js';
+import { DataModelDiagram } from './charting/diagrams/DataModelDiagram.js';
+import { createDataWindow, GraphDataWindow } from './datawindow/index.js';
+import { compileFormula } from './kernelExpr.js';
+import { ArchimateNotation, ArchimateLayer, ArchimateElementType, ArchimateRelationshipType, ArchimateViewpoints } from './archimate.js';
+import { ITIconNotation, ITElementType } from './itIcons.js';
+import { ArchimateValidator } from './charting/diagrams/ArchimateValidator.js';
+import { ArchimateSpecializationRegistry } from './archimateSpecializations.js';
+import { ArchimateSpecializationSelector } from './charting/ArchimateSpecializationSelector.js';
+import { ImageSelector } from './charting/ImageSelector.js';
+import { CheckboxTreeSelector } from './charting/CheckboxTreeSelector.js';
+import { SettingsManager, settingsManager } from './charting/SettingsManager.js';
+import { showGlobalSettingsDialog } from './charting/SettingsDialog.js';
+import { ArchimateModel, ArchimateView } from './charting/diagrams/ArchimateModel.js';
+import { CanvasView } from './charting/diagrams/CanvasView.js';
+import { PlaceItemsCommand } from './charting/diagrams/PlaceItemsCommand.js';
+import { RemoveLineCommand } from './charting/diagrams/RemoveLineCommand.js';
+import { CanvasBoxKind } from './charting/canvas/CanvasBoxKind.js';
+import { CANVAS_BOX_KINDS, canvasBoxKind } from './charting/canvas/canvasBoxKinds.js';
+import { canvasBoxMenuItems } from './charting/canvas/canvasBoxMenuItems.js';
+import { ArchiHint } from './charting/canvas/ArchiHint.js';
+import { HintPanel } from './charting/HintPanel.js';
+import { EditHintCommand } from './charting/canvas/EditHintCommand.js';
+import { hintMenuItems } from './charting/canvas/hintMenuItems.js';
+import { CanvasPalette, CANVAS_BOX_MIME } from './charting/canvas/CanvasPalette.js';
+import { ViewLineEdge } from './charting/archimate/ViewLineEdge.js';
+import { ElementInstance } from './charting/diagrams/ElementInstance.js';
+import { ViewObjectInstance } from './charting/diagrams/ViewObjectInstance.js';
+import { Glyph, GLYPHS, glyphFor, drawGlyph } from './charting/glyphs/index.js';
+import { glyphElement, glyphToSvg } from './charting/glyphs/glyphSvg.js';
+import { GlyphTemplate } from './charting/templates/GlyphTemplate.js';
+import { ArchimateElementTemplate, ArchimateEdge, ArchimateCanvasEditor, ArchimatePalette, KIND_PREFERENCE, ARCHIMATE_TYPE_MIME } from './charting/archimate/index.js';
+import { RelationshipInstance } from './charting/diagrams/RelationshipInstance.js';
+import { DiagramEditor } from './charting/DiagramEditor.js';
+import { DiagramEditorState } from './charting/DiagramEditorState.js';
+import { Template, PolygonTemplate, RegularPolygonTemplate, RectangleTemplate, RoundedRectangleTemplate, StadiumTemplate, PredefinedProcessTemplate, ClassTemplate, ComponentTemplate, SwimlaneTemplate, CircleTemplate, FinalStateTemplate, EllipseTemplate, DiamondTemplate, TriangleTemplate, PentagonTemplate, HexagonTemplate, OctagonTemplate, StarTemplate, ParallelogramTemplate, TrapezoidTemplate, ManualInputTemplate, CylinderTemplate, DocumentTemplate, NoteTemplate, CloudTemplate, ActorTemplate, PackageTemplate, BoxTemplate, DataStoreTemplate, LifelineTemplate } from './charting/templates/index.js';
+import { TemplateCatalog } from './charting/TemplateCatalog.js';
+import { DIAGRAM_TYPES, getTemplatesForDiagramType, getAllDiagramTypes, getDiagramTypesByGroup } from './charting/DiagramTypeRegistry.js';
+import { EdgeMarker, ArrowMarker, DiamondMarker, CircleMarker, CrowsFootMarker, HollowDiamondMarker, HollowTriangleMarker, OpenArrowMarker, HalfArrowMarker, EDGE_MARKERS, getEdgeMarker } from './charting/edgeMarkers/index.js';
+import { Palette } from './charting/Palette.js';
+import { MoveElementCommand, BringToFrontCommand, SendToBackCommand, RaiseCommand, LowerCommand, CreateTemplateCommand, EditPropertyCommand, ResizeCommand, RotateCommand, SetPropertiesCommand, ReorderCommand } from './charting/DiagramEditorCommands.js';
+import { Edge } from './charting/Edge.js';
+import { AddEdgeCommand, DeleteEdgeCommand, ReconnectEdgeCommand, MoveWaypointCommand, AddWaypointCommand, DeleteWaypointCommand } from './charting/DiagramEditorEdgeCommands.js';
+import { EDGE_STYLE_PROPERTIES, LINE_ONLY_PROPERTIES, LINE_STYLE_DASH, EdgeStyleCascade, SetStyleCommand, EdgeStyleDialog } from './charting/edgeStyle/index.js';
+import { DiagramModel, DiagramView, ViewSetModel } from './charting/diagramModel/index.js';
+import { ViewMenu } from './charting/ViewMenu.js';
+import { CanvasTemplateLibrary } from './charting/canvas/CanvasTemplateLibrary.js';
+import { CanvasTemplateMenu } from './charting/canvas/CanvasTemplateMenu.js';
+import { TemplateLibrary } from './charting/TemplateLibrary.js';
+import { Arrangement, ItemGroup, BackgroundGroup, GroupCommand, UngroupCommand, LockCommand, BackgroundCommand, arrangeMenuItems } from './charting/arrangement/index.js';
+import { ViewPropertiesDialog } from './charting/ViewPropertiesDialog.js';
+import { SettingsViewPropertiesDialog } from './charting/SettingsViewPropertiesDialog.js';
+import { DiagramViewPropertiesDialog } from './charting/DiagramViewPropertiesDialog.js';
+import { inheritableFields, readInheritableFields } from './charting/SettingsCascade.js';
+import { LocalJsonStore } from './charting/storage/LocalJsonStore.js';
+import { PopupMenu } from './charting/PopupMenu.js';
+import { ViewTabStrip } from './charting/ViewTabStrip.js';
+import { EditorShell } from './workspace/EditorShell.js';
+import { FormDialog } from './charting/FormDialog.js';
+import { ColorField } from './charting/ColorField.js';
+import { TextStyle } from './charting/TextStyle.js';
+import { ArchimateModelChecker } from './charting/diagrams/ArchimateModelChecker.js';
+import { ViewSetChecker } from './charting/diagramModel/ViewSetChecker.js';
+import { ViewFit } from './charting/ViewFit.js';
+import { archiElementType, NEAREST_ARCHI_TYPE } from './archimateArchiTypes.js';
+import { DEFAULT_CANVAS_TEMPLATES, canvasTemplate } from './charting/canvas/defaultCanvasTemplates.js';
+import { EditViewItemCommand, viewItemChanges } from './charting/diagrams/EditViewItemCommand.js';
+import { ToolbarItem, ToolbarButton, ToolbarMenu, ToolbarSelect, ToolbarCheckbox, ToolbarText, ToolbarSeparator, pickFile } from './charting/toolbar/index.js';
+import { reorderedZ, stackingOrder } from './charting/zOrder.js';
+import { PropertiesPanel } from './charting/PropertiesPanel.js';
+import { MenuBar } from './charting/MenuBar.js';
+import { ArchimateDiagramEditor } from './charting/ArchimateDiagramEditor.js';
+import { ModelTree } from './charting/modelTree/ModelTree.js';
+import { TreeModeRegistry } from './charting/modelTree/TreeModeRegistry.js';
+import { TREE_MODE_CATALOG, treeModeRegistry, getTreeModeCatalogEntry } from './treeModeCatalog.js';
+import { buildModelTreePanel } from './charting/modelTree/ModelTreePanel.js';
+import { buildAnalysisPanel, buildAnalysisData } from './charting/modelTree/AnalysisPanel.js';
+import { buildTypeCategoryTree, buildPropertyTree } from './charting/modelTree/buildFilterTrees.js';
+import { DiagramTabs } from './charting/modelTree/DiagramTabs.js';
+import { DataModelNotation, DataModelLevel, NotationStyle } from './datamodel.js';
+import {
+    ARCHI_VISUAL_OBJECTS, ARCHI_VIEW_TYPES,
+    parseXML, parseArchiModel, toRenderEngineModel, toArchimateModel, toArchiXML, fromArchimateView, toArchiExport,
+} from './archimateArchiFormat.js';
+import { parseExchangeModel, toExchangeXML, EXCHANGE_NAMESPACE, EXCHANGE_TYPE_PROPERTY, EXCHANGE_VIEWPOINTS } from './archimateExchangeFormat.js';
+import { ModelFileFormat, modelFileMenuItems, importFile } from './charting/ModelFileFormat.js';
+import { ArchiFileFormat, ExchangeFileFormat, ArchimateCsvFileFormat, ARCHIMATE_FILE_FORMATS } from './charting/archimate/index.js';
+import { ShowElementCommand } from './charting/diagrams/ShowElementCommand.js';
+import { EmphasisRule, EMPHASIS_OPACITY, EMPHASIS_LEVELS, strongerEmphasis } from './charting/emphasis/EmphasisRule.js';
+import { HighlightRule } from './charting/emphasis/HighlightRule.js';
+import { CatalogDialog } from './charting/CatalogDialog.js';
+import { CustomViewpoints, CUSTOM_VIEWPOINTS_STORE, specializationCatalogDialog, elementTypeChoices } from './charting/archimate/index.js';
+import { ViewpointRule, ElementFilterRule } from './charting/archimate/index.js';
+import { MODEL_ELEMENT_MIME, TREE_LAYERS, treeLayerOf } from './charting/modelTree/ModelTreePanel.js';
+import { parseArchiFile, toArchiFile, ARCHI_MODEL_ENTRY } from './archimateArchive.js';
+import { ZipArchive } from './zip/ZipArchive.js';
+import {
+    exportElementsCSV, exportRelationshipsCSV, exportModelCSV,
+    importElementsCSV, importRelationshipsCSV, importModelCSV,
+} from './archimateCSV.js';
+// Safe to import here despite being browser-only in effect: every DOM/clipboard
+// reference sits inside a function body, so loading it under node does nothing.
+import {
+  copyImage, toPngBlob, downloadPng, downloadSvg, downloadBlob,
+  serializeSvg, prepareSvgMarkup, imageSize, imageFileName, findDrawable, MAX_IMAGE_PIXELS,
+} from './exportImage.js';
+// Same reasoning as exportImage: every DOM reference sits inside a function
+// body, so loading this under node does nothing.
+import {
+  showPropertiesDialog, showDiagramPropertiesDialog,
+  propertyRowsFor, coerceFieldValue, derivedRefreshPlan, LAYER_CHOICES, NODE_SECTIONS,
+} from './propertiesDialog.js';
+
+// NOTE: `src/workspace.js` is deliberately NOT re-exported here. It subclasses
+// HTMLElement at module scope, so merely importing it throws outside a browser
+// — and this module is the node entry point the test suite loads. It is a
+// separate browser-only entry: import 'renderengine/src/workspace.js' directly.
+
+export {
+  Mat4, OrbitCamera, CHART_CATALOG, getChartCatalogEntry, chartRegistry,
+  DIAGRAM_CATALOG, getDiagramCatalogEntry, diagramRegistry,
+  TREE_MODE_CATALOG, treeModeRegistry, getTreeModeCatalogEntry,
+  AXIS_KIND, ENCODING_CHANNEL, COORD_SYSTEM, COLOR_MODE, CAMERA_MODE,
+  Command, CompositeCommand, CommandHistory,
+  DiagramEditor, DiagramEditorState, Template, PolygonTemplate, RegularPolygonTemplate, RectangleTemplate, RoundedRectangleTemplate, StadiumTemplate, PredefinedProcessTemplate, ClassTemplate, ComponentTemplate, SwimlaneTemplate, CircleTemplate, FinalStateTemplate, EllipseTemplate, DiamondTemplate, TriangleTemplate, PentagonTemplate, HexagonTemplate, OctagonTemplate, StarTemplate, ParallelogramTemplate, TrapezoidTemplate, ManualInputTemplate, CylinderTemplate, DocumentTemplate, NoteTemplate, CloudTemplate, ActorTemplate, PackageTemplate, BoxTemplate, DataStoreTemplate, LifelineTemplate, TemplateCatalog, Palette, PropertiesPanel, MenuBar, MoveElementCommand, BringToFrontCommand, SendToBackCommand, RaiseCommand, LowerCommand, CreateTemplateCommand, EditPropertyCommand, ResizeCommand, RotateCommand, SetPropertiesCommand, ReorderCommand, DIAGRAM_TYPES, getTemplatesForDiagramType, getAllDiagramTypes, getDiagramTypesByGroup, EdgeMarker, ArrowMarker, DiamondMarker, CircleMarker, CrowsFootMarker, HollowDiamondMarker, HollowTriangleMarker, OpenArrowMarker, HalfArrowMarker, EDGE_MARKERS, getEdgeMarker, Edge, AddEdgeCommand, DeleteEdgeCommand, ReconnectEdgeCommand, EDGE_STYLE_PROPERTIES, LINE_ONLY_PROPERTIES, LINE_STYLE_DASH, EdgeStyleCascade, SetStyleCommand, EdgeStyleDialog, DiagramModel, DiagramView, ViewSetModel, ViewMenu, ViewPropertiesDialog, SettingsViewPropertiesDialog, DiagramViewPropertiesDialog, inheritableFields, readInheritableFields, LocalJsonStore, PopupMenu, ViewTabStrip, EditorShell, FormDialog, ToolbarItem, ToolbarButton, ToolbarMenu, ToolbarSelect, ToolbarCheckbox, ToolbarText, ToolbarSeparator, pickFile, reorderedZ, stackingOrder, MoveWaypointCommand, AddWaypointCommand, DeleteWaypointCommand,
+  ebnfAstToDiagram, parseEbnf,
+  createDataWindow, GraphDataWindow,
+  ArchimateNotation, ArchimateLayer, ArchimateElementType, ArchimateRelationshipType,
+  Glyph, GLYPHS, glyphFor, drawGlyph, glyphElement, glyphToSvg, GlyphTemplate, ArchimateElementTemplate, ArchimateEdge, ArchimateCanvasEditor, ArchimatePalette, KIND_PREFERENCE, ARCHIMATE_TYPE_MIME,
+  ArchimateModel, ArchimateView, CanvasView, PlaceItemsCommand, RemoveLineCommand, CanvasBoxKind, CANVAS_BOX_KINDS, canvasBoxKind, canvasBoxMenuItems, ArchiHint, HintPanel, EditHintCommand, hintMenuItems, CanvasPalette, CANVAS_BOX_MIME, ViewLineEdge, Arrangement, ItemGroup, BackgroundGroup, GroupCommand, UngroupCommand, LockCommand, BackgroundCommand, arrangeMenuItems, TemplateLibrary, CanvasTemplateLibrary, CanvasTemplateMenu, DEFAULT_CANVAS_TEMPLATES, canvasTemplate, EditViewItemCommand, viewItemChanges, ColorField, TextStyle, ArchimateModelChecker, ViewSetChecker, ViewFit, archiElementType, NEAREST_ARCHI_TYPE, ElementInstance, ViewObjectInstance, RelationshipInstance, ArchimateDiagramEditor,
+  ITIconNotation, ITElementType,
+  ArchimateValidator, ArchimateSpecializationSelector, ImageSelector, CheckboxTreeSelector, SettingsManager, settingsManager,
+  ModelTree, TreeModeRegistry,
+  RadialLayout, DerivedRelationships, EdgeGeometry,
+  buildModelTreePanel, buildAnalysisPanel, buildAnalysisData, buildTypeCategoryTree, buildPropertyTree, DiagramTabs,
+  DataModelNotation, DataModelLevel, NotationStyle,
+  exportElementsCSV, exportRelationshipsCSV, exportModelCSV,
+  importElementsCSV, importRelationshipsCSV, importModelCSV,
+  parseArchiModel, toArchimateModel, fromArchimateView, toArchiExport,
+  parseExchangeModel, toExchangeXML, EXCHANGE_NAMESPACE, EXCHANGE_TYPE_PROPERTY, EXCHANGE_VIEWPOINTS,
+  ModelFileFormat, modelFileMenuItems, importFile, ArchiFileFormat, ExchangeFileFormat, ArchimateCsvFileFormat, ARCHIMATE_FILE_FORMATS,
+  ShowElementCommand, MODEL_ELEMENT_MIME, TREE_LAYERS, treeLayerOf,
+  EmphasisRule, EMPHASIS_OPACITY, EMPHASIS_LEVELS, strongerEmphasis, HighlightRule, ViewpointRule, ElementFilterRule,
+  CatalogDialog, CustomViewpoints, CUSTOM_VIEWPOINTS_STORE, specializationCatalogDialog, elementTypeChoices,
+  parseArchiFile, toArchiFile, ARCHI_MODEL_ENTRY, ZipArchive,
+  copyImage, toPngBlob, downloadPng, downloadSvg, downloadBlob,
+  serializeSvg, prepareSvgMarkup, imageSize, imageFileName, findDrawable, MAX_IMAGE_PIXELS,
+  showPropertiesDialog, showDiagramPropertiesDialog, showGlobalSettingsDialog,
+  propertyRowsFor, coerceFieldValue, derivedRefreshPlan, LAYER_CHOICES, NODE_SECTIONS,
+};
+
+/**
+ * @class RenderEngine
+ * This class decides which renderer to use and provides a unified drawing API.
+ */
+export class RenderEngine {
+    /** Layout constants for graphDiagram's `shape: 'table'` node type. */
+    static TABLE_NODE = NodeGeometry.TABLE_NODE;
+
+    /** ArchiMate standard-alignment validator (relationship validity, layer
+     *  consistency) — exposed so callers building ArchiMate authoring UIs can
+     *  filter relationship-kind pickers without duplicating rules. */
+    static ArchimateValidator = ArchimateValidator;
+
+    /** IT / infrastructure icon extension catalog — firewall, laptop, server,
+     *  database, container, etc. These are not official ArchiMate types but are
+     *  resolved by `archimateDiagram` and its construction UI as custom types
+     *  with sensible layer/aspect/icon defaults. */
+    static ITIconNotation = ITIconNotation;
+    static ITElementType = ITElementType;
+
+    /** graphDiagram() node fields that are structural, not caller "extra data"
+     *  — excluded from the auto-generated extra-data tooltip lines (see
+     *  _nodeExtraDataLines). Table nodes have their own richer set since
+     *  columns/rowCount/width are structural there, not extra data. */
+    static NODE_STRUCTURAL_KEYS = new Set([
+        'id', 'name', 'label', 'x', 'y', 'shape', 'color', 'group', 'size', 'radius', 'width', 'height',
+        'icon', 'iconUrl', 'iconShape', 'iconPosition', 'iconCorner', 'labelPosition', 'textAlign', 'verticalAlign',
+        'resizable', 'resizeCorner', 'cornerStyle', 'strokeColor', 'strokeWidth', 'href', 'properties', 'specialization', 'useDistinctShape',
+        // How its text is drawn (TextStyle, in the node's names) and Archi's class for a canvas box: look, not data.
+        'textColor', 'fontFamily', 'fontSize', 'fontWeight', 'fontStyle', 'textDecoration', 'archiVisualType',
+    ]);
+    static TABLE_NODE_STRUCTURAL_KEYS = new Set(['id', 'name', 'label', 'x', 'y', 'shape', 'color', 'group', 'columns', 'rowCount', 'width', 'resizable', 'resizeCorner']);
+    /** graphDiagram() edge fields that are structural, not caller "extra
+     *  data" — same idea as NODE_STRUCTURAL_KEYS, for edges (see the
+     *  Properties-panel example in test/charts.html, which uses this to show
+     *  only a caller's own custom fields as editable). */
+    static EDGE_STRUCTURAL_KEYS = new Set([
+        'source', 'target', 'label', 'sourceLabel', 'targetLabel', 'weight', 'color', 'dashed', 'lineStyle',
+        'arrowhead', 'arrowheadStart', 'routing', 'sourceSide', 'targetSide', 'waypoints', 'fromCol', 'toCol',
+        'kind', 'properties', 'dasharray', 'tooltip', '_archimateWarning',
+    ]);
+
+    /** The ArchiMate 3.2 notation registry (layers, the official element
+     *  type catalog, relationship notations) archimateDiagram is built on —
+     *  see src/archimate.js, which owns all of it; this is just a
+     *  convenient static so callers already holding a RenderEngine instance
+     *  (`engine.constructor.ArchimateNotation`) don't need a second import,
+     *  the same reason graphDiagram's own NODE_STRUCTURAL_KEYS etc. live
+     *  here as statics. */
+    static ArchimateNotation = ArchimateNotation;
+
+    /** ArchiMate viewpoints catalog and helpers — see src/archimate.js. */
+    static ArchimateViewpoints = ArchimateViewpoints;
+
+    /** Editable specialization catalog for ArchiMate — user-defined
+     *  specializations linked to base types with their own icon/colour.
+     *  See src/archimateSpecializations.js. */
+    static ArchimateSpecializationRegistry = ArchimateSpecializationRegistry;
+
+    /** Model tree view mode registry (byLayer, byType, flat) — exposed so
+     *  callers building model tree UIs can populate mode pickers from the
+     *  registry rather than hardcoding options. See src/treeModeCatalog.js. */
+    static treeModeRegistry = treeModeRegistry;
+
+    /** The data-modelling notation registry (levels, notation styles,
+     *  cardinality vocabulary) dataModelDiagram is built on — see
+     *  src/datamodel.js. Same convenience-static reasoning as
+     *  ArchimateNotation above. */
+    static DataModelNotation = DataModelNotation;
+
+    /** outlineChart()'s node fields that are structural, not caller "extra
+     *  data" — same idea as NODE_STRUCTURAL_KEYS above, for the
+     *  treemapChart/sunburstChart/outlineChart shared hierarchy shape. */
+    static HIERARCHY_STRUCTURAL_KEYS = new Set(['label', 'value', 'children']);
+
+    /** Archi native `.archimate` XML visual-object type constants. */
+    static ARCHI_VISUAL_OBJECTS = ARCHI_VISUAL_OBJECTS;
+    static ARCHI_VIEW_TYPES = ARCHI_VIEW_TYPES;
+
+    /** Parse an Archi native `.archimate` XML string and return renderengine
+     *  inputs ready for `archimateDiagram()`: `{ elements, relationships, options }`.
+     *  `viewId` selects a specific view; defaults to the first view. */
+    static importArchiXML(xml, viewId) {
+        const archiModel = parseArchiModel(xml);
+        return toRenderEngineModel(archiModel, viewId);
+    }
+
+    /** Serialize renderengine model data back to an Archi native `.archimate`
+     *  XML string. `model` is `{ id?, name?, version?, elements[], relationships[] }`
+     *  and `views` is an array of Archi view descriptors. */
+    static exportArchiXML(model, views) {
+        return toArchiXML(model, views);
+    }
+
+    /** Export model elements/relationships to CSV strings for spreadsheet editing.
+     *  Returns `{ elementsCSV, relationshipsCSV }`. */
+    static exportModelCSV(model) {
+        return exportModelCSV(model);
+    }
+
+    /** Import model elements/relationships from CSV strings. Returns
+     *  `{ elements, relationships }` ready for `archimateDiagram()`. */
+    static importModelCSV(elementsCSV, relationshipsCSV) {
+        return importModelCSV(elementsCSV, relationshipsCSV);
+    }
+
+    /** Layout constants for outlineChart()'s indented rows. */
+    static OUTLINE_ROW_H = 22;
+    static OUTLINE_INDENT_W = 18;
+
+    /**
+     * The full list of chart types this engine supports, with a display
+     * label and the method to call for each — see chartCatalog.js. Also
+     * available as the standalone `CHART_CATALOG` export for consumers that
+     * only need the list (no RenderEngine instance) e.g. to populate a type
+     * picker before any query has run.
+     */
+    static CHART_CATALOG = CHART_CATALOG;
+
+    /**
+     * Object-oriented registry of chart types. Consumers can register custom
+     * chart types at runtime via `RenderEngine.CHART_REGISTRY.register(entry)`.
+     */
+    static CHART_REGISTRY = chartRegistry;
+
+    /**
+     * The full list of diagram types this engine supports, with the method to
+     * call for each — see diagramCatalog.js. Also available as the standalone
+     * `DIAGRAM_CATALOG` export.
+     */
+    static DIAGRAM_CATALOG = DIAGRAM_CATALOG;
+
+    /**
+     * Object-oriented registry of diagram types. Consumers can register custom
+     * diagram types at runtime via `RenderEngine.DIAGRAM_REGISTRY.register(entry)`.
+     */
+    static DIAGRAM_REGISTRY = diagramRegistry;
+
+    /**
+     * `get` trap backing the constructor's chained-access Proxy. Only falls
+     * through to a container handle when `prop` is neither a real
+     * property/method NOR already-registered (via `register()`) — instance
+     * properties like `renderer` are conditionally assigned (never set at
+     * all in container-less test mode), so an unset *real* property and an
+     * unused container id are otherwise indistinguishable from `in target`
+     * alone; requiring registry membership avoids that collision, and costs
+     * nothing since `addDataPoint`/`addGraphNode`/`refreshChart` already
+     * no-op for an id that was never registered anyway.
+     * @private
+     */
+    static _proxyHandler = {
+        get(target, prop, receiver) {
+            if (typeof prop === 'string' && !(prop in target) && target.registry && prop in target.registry) {
+                return target._containerHandle(prop);
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    };
+
+    /**
+     * Renders `data` as chart type `key` into this engine's container —
+     * looks up the method from CHART_CATALOG so a consumer's type-dispatch
+     * code doesn't need its own key→method mapping (only the data-shaping,
+     * which is inherently consumer-specific — see each entry's `dataShape`).
+     * @param {string} key A CHART_CATALOG key, e.g. 'bar', 'heatmap'.
+     * @param {*} data Shaped per that entry's `dataShape`.
+     * @param {object} [options]
+     * @throws {Error} if `key` isn't in CHART_CATALOG.
+     */
+    renderChartType(key, data, options = {}) {
+        const entry = RenderEngine.CHART_REGISTRY.get(key);
+        if (!entry) throw new Error(`Unknown chart type '${key}' — see RenderEngine.CHART_CATALOG for valid keys`);
+        return this[entry.method](data, options);
+    }
+
+    /**
+     * Renders a registered diagram type by key.
+     * @param {string} key A DIAGRAM_CATALOG key, e.g. 'graph', 'archimate'.
+     * @param {...*} args Passed through to the diagram method in the same order
+     *   it expects (e.g. `nodes, edges, options` for 'graph').
+     * @throws {Error} if `key` isn't in DIAGRAM_CATALOG.
+     */
+    renderDiagramType(key, ...args) {
+        const entry = RenderEngine.DIAGRAM_REGISTRY.get(key);
+        if (!entry) throw new Error(`Unknown diagram type '${key}' — see RenderEngine.DIAGRAM_CATALOG for valid keys`);
+        return this[entry.method](...args);
+    }
+
+    /**
+     * @param {HTMLElement} container The container element for the chart.
+     * @param {object} [options]
+     * @param {'canvas' | 'svg'} [options.rendererType='canvas']
+     */
+    constructor(container, options = {}) {
+        if (container) {
+            const { rendererType = 'canvas' } = options;
+            const width = container.clientWidth;
+            const height = container.clientHeight;
+    
+            this.container = container; // Store container for event listeners
+            this.renderer = RendererFactory.create(rendererType, container, width, height);
+        } else {
+            // Allow initialization without a container for testing
+            this.options = options;
+            console.log('RenderEngine initialized in test mode.');
+        }
+
+        if (this.container) {
+            this._interactions = new InteractionManager(this);
+            this._interactions.attach();
+        }
+
+        this._containerHandles = new Map();
+        // Lets `register`/`refreshChart`/`addDataPoint`/`addGraphNode` be
+        // called either the normal way (`engine.addGraphNode(id, ...)`) or
+        // scoped to a container id (`engine[id].addGraphNode(...)` — or
+        // `engine.someId.addGraphNode(...)` when `id` happens to be a valid
+        // identifier with no hyphens). Only property names that aren't
+        // already real properties/methods fall through to a container
+        // handle, so this never shadows anything on the class itself.
+        return new Proxy(this, RenderEngine._proxyHandler);
+    }
+
+    /**
+     * Returns (creating and caching on first use) the chained-access handle
+     * for container `id` — see the constructor's Proxy comment.
+     * @private
+     */
+    _containerHandle(id) {
+        if (!this._containerHandles.has(id)) {
+            const engine = this;
+            this._containerHandles.set(id, {
+                register:     (type, options) => engine.register(id, type, options),
+                refreshChart: () => engine.refreshChart(id),
+                addDataPoint: (pointOrFactory, opts) => engine.addDataPoint(id, pointOrFactory, opts),
+                addGraphNode: (node, newEdges, opts) => engine.addGraphNode(id, node, newEdges, opts),
+            });
+        }
+        return this._containerHandles.get(id);
+    }
+
+    /**
+     * Convenience getter: exposes the current active diagram's _graph property
+     * (GraphDiagram uses this to store node positions, edges, and other state).
+     * Returns undefined if no active diagram or if the active diagram doesn't have _graph.
+     * @private
+     */
+    get _graph() {
+        return this._activeDiagram?._graph;
+    }
+
+    /**
+     * Default plot-area box for the bar/line/stackedBar/bubble/barChart3D
+     * family, sized to the actual renderer dimensions instead of a fixed
+     * constant. Reserves margin below the plot for the x-axis tick labels
+     * (drawn at y+height+20) and axis label (drawn at y+height+45) so they
+     * stay inside the container instead of being clipped (Canvas) or
+     * overflowing it (SVG) — a fixed height that assumes a specific
+     * container size cuts these off in any container it wasn't tuned for.
+     * @private
+     */
+    _defaultChartBox() {
+        return ChartBox.fromRenderer(this.renderer);
+    }
+
+    /**
+     * Draws a list of shape descriptors or Shape instances. Each shape is
+     * dispatched to the renderer through a concrete Shape subclass, so this
+     * method no longer switches on `shape.type`.
+     * @param {Array<object|Shape>} shapes An array of shape descriptions to draw.
+     */
+    draw(shapes) {
+        if (!this.renderer) return;
+        this.renderer.clear();
+        for (const shape of shapes) {
+            const s = ShapeFactory.fromObject(shape);
+            s.render(this.renderer);
+        }
+    }
+
+    /**
+     * Render a Chart subclass instance and make it the active chart for event
+     * dispatch. This replaces the old pattern of switching on `_chartState.type`
+     * in the global click listener.
+     * @private
+     */
+    _renderChart(chart) {
+        this._activeChart = chart;
+        this._activeDiagram = null;
+        chart.render();
+    }
+
+    /**
+     * Render a Diagram subclass instance and make it the active diagram for
+     * event dispatch.
+     * @private
+     */
+    _renderDiagram(diagram) {
+        this._activeDiagram = diagram;
+        this._activeChart = null;
+        diagram.render();
+    }
+
+    /**
+     * Renders a simple bar chart.
+     * @param {Array<{label: string, value: number}>} data The data to chart.
+     * @param {object} [options] Charting options.
+     * @param {number} [options.x=50] The x-coordinate of the chart origin.
+     * @param {number} [options.y=50] The y-coordinate of the chart origin.
+     * @param {number} [options.width=500] The width of the chart area.
+     * @param {number} [options.height=300] The height of the chart area.
+     * @param {string} [options.barColor='steelblue'] The color of the bars.
+     * @param {string} [options.title] The chart title.
+     * @param {string} [options.xAxisLabel] The label for the x-axis.
+     * @param {string} [options.yAxisLabel] The label for the y-axis.
+     * @param {string[]} [options.colors] Array of colors for the bars.
+     * @param {boolean} [options.showLegend=false] Whether to show the legend.
+     */
+    barChart(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false; // leaving 3D mode — clears the SVG-zoom guard added for bubbleChart3D
+        // Store state for re-rendering and interactivity
+        this._chartState = { type: 'bar', data, options };
+        this._barDataFilter = this._barDataFilter || new DataFilter();
+        this._renderChart(new BarChart(this.renderer, data, options, this._barDataFilter));
+        return;
+    }
+
+    /**
+     * Renders a grouped (multi-set) bar chart.
+     * @param {Array<{name: string, values: Array<{label: string, value: number}>}>} data The data to chart.
+     * @param {object} [options] Charting options.
+     * @param {string[]} [options.colors] Series palette.
+     * @param {boolean} [options.legend=false] Show a series legend.
+     * @param {number} [options.groupPadding=0.2] Gap between category clusters as a fraction of cluster width.
+     * @param {number} [options.barPadding=0.05] Gap between bars inside a cluster as a fraction of bar width.
+     */
+    groupedBarChart(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'groupedBar', data, options };
+        this._renderChart(new GroupedBarChart(this.renderer, data, options));
+    }
+
+    /**
+     * Renders a simple line chart.
+     * @param {Array<{label: string, value: number}>} data The data to chart.
+     * @param {object} [options] Charting options.
+     */
+    lineChart(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'line', data, options };
+        this._renderChart(new LineChart(this.renderer, data, options));
+    }
+
+    /**
+     * Renders a multi-line chart where each line is a tapering filled ribbon
+     * ("pipe") instead of a uniform-width stroke — width at each point tracks
+     * a metric field. Neither SVG stroke-width nor Canvas lineWidth can vary
+     * along a single stroke, so this is drawn as a filled polygon: each
+     * point is offset perpendicular to the local line direction by
+     * ±width/2, and the upper/lower boundary points are connected into one
+     * closed path — the same `renderer.path()`/M...L...Z mechanism used
+     * everywhere else in this file.
+     * @param {Array<{label:string,value:number,metric?:number}>|Array<{name:string,values:Array<{label,value,metric}>}>} data
+     * @param {object} [options]
+     * @param {string} [options.metricCol='metric'] Field name driving pipe width.
+     * @param {number} [options.minWidth=4]
+     * @param {number} [options.maxWidth=28]
+     * @param {string[]} [options.colors]
+     * @param {boolean} [options.legend=false]
+     */
+    pipeChart(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false; // leaving 3D mode — clears the SVG-zoom guard added for bubbleChart3D
+        this._chartState = { type: 'pipe', data, options };
+        this._renderChart(new PipeChart(this.renderer, data, options));
+    }
+
+    /**
+     * Renders a stacked bar chart.
+     * @param {Array<object>} data The data to chart. e.g. [{ label: 'Jan', values: [10, 20] }]
+     * @param {object} [options] Charting options.
+     */
+    stackedBarChart(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false; // leaving 3D mode — clears the SVG-zoom guard added for bubbleChart3D
+        this._chartState = { type: 'stackedBar', data, options };
+        this._renderChart(new StackedBarChart(this.renderer, data, options));
+    }
+
+    // ── Color-scale helpers (heatmap) ───────────────────────────────────────
+
+    /**
+     * Maps a value within [vMin, vMax] to a color along an N-stop scale
+     * (linear interpolation between adjacent stops via ColorPalette).
+     * @private
+     */
+    _scaleColor(stops, vMin, vMax, v) {
+        return ColorPalette.scaleColor(stops, vMin, vMax, v);
+    }
+
+    /** Perceptual-ish luma check, used to pick readable text color on a colored cell/slice. @private */
+    _isDarkColor(hex) {
+        return ColorPalette.isDark(hex);
+    }
+
+    /**
+     * Renders a heatmap: a grid of cells, one per (x, y) category pair,
+     * shaded by `value` along a low→high color scale — the natural chart for
+     * a correlation matrix or any "intensity across two dimensions" dataset.
+     * @param {Array<{x: string, y: string, value: number}>} data
+     * @param {object} [options]
+     * @param {string[]} [options.xLabels] explicit x-axis category order (default: order of first appearance in data)
+     * @param {string[]} [options.yLabels] explicit y-axis category order (default: order of first appearance in data)
+     * @param {string[]} [options.colorScale=['#f7fbff','#4292c6','#08306b']] low-to-high color stops (2+ hex colors)
+     * @param {boolean} [options.showValues=false] draw the numeric value inside each cell
+     * @param {string} [options.title]
+     */
+    heatmap(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'heatmap', data, options };
+        this._renderChart(new HeatmapChart(this.renderer, data, options));
+    }
+
+    /**
+     * Renders a calendar heatmap: a year-at-a-glance grid of day cells, each
+     * shaded by its value — the classic GitHub-contribution-graph layout.
+     * @param {Array<{date: string|Date, value: number}>} data
+     * @param {object} [options]
+     * @param {number} [options.year] year to display (default current year)
+     * @param {string|Date} [options.startDate] explicit inclusive start
+     * @param {string|Date} [options.endDate] explicit inclusive end
+     * @param {string[]} [options.colorScale=['#ebedf0','#9be9a8','#40c463','#30a14e','#216e39']] low→high stops
+     * @param {string} [options.emptyColor='#ebedf0'] color for days with no data
+     * @param {number} [options.cellSize] pixel size of one day cell (auto if omitted)
+     * @param {number} [options.cellGap=2] gap between cells
+     * @param {boolean} [options.showValues=false] draw the numeric value inside each cell
+     * @param {boolean} [options.monthLabels=true] show month names above the grid
+     * @param {boolean} [options.weekdayLabels=true] show weekday names beside rows
+     * @param {0|1} [options.weekStart=0] 0 = Sunday, 1 = Monday
+     * @param {string} [options.title]
+     */
+    calendarHeatmap(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'calendarHeatmap', data, options };
+        this._renderChart(new CalendarHeatmapChart(this.renderer, data, options));
+    }
+
+    /**
+     * Renders a Gantt chart — horizontal bars on a time axis, one row per task.
+     * @param {Array<{label:string, start:string|Date|number, end:string|Date|number, progress?:number, category?:string, color?:string}>} data
+     * @param {object} [options]
+     * @param {number} [options.barHeight=24]
+     * @param {number} [options.barGap=12]
+     * @param {string[]} [options.colors] per-category palette
+     * @param {string} [options.axisLabel]
+     * @param {'auto'|'date'|'datetime'|'iso'} [options.dateFormat='auto']
+     * @param {boolean} [options.showProgress] default true if any task has progress
+     * @param {boolean} [options.showToday=true]
+     * @param {string} [options.title]
+     */
+    ganttChart(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'gantt', data, options };
+        this._renderChart(new GanttChart(this.renderer, data, options));
+    }
+
+    /**
+     * Renders a stream graph — a stacked area chart with a centered baseline,
+     * producing a flowing shape across time.
+     * @param {Array<{name: string, values: Array<{label: string, value: number}>}>} data
+     * @param {object} [options]
+     * @param {string[]} [options.colors]
+     * @param {boolean} [options.legend=true]
+     * @param {boolean} [options.smooth=true] cubic-bezier smoothing
+     * @param {number} [options.tension=0.5]
+     * @param {string} [options.title]
+     * @param {string} [options.xAxisLabel]
+     * @param {string} [options.yAxisLabel]
+     */
+    streamGraph(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'streamGraph', data, options };
+        this._renderChart(new StreamGraphChart(this.renderer, data, options));
+    }
+
+    /**
+     * Renders a radial bar chart (circular barplot) — bars radiating from a
+     * central point, one angular slice per category.
+     * @param {Array<{label:string, value:number}>} data
+     * @param {object} [options]
+     * @param {number} [options.cx]
+     * @param {number} [options.cy]
+     * @param {number} [options.radius]
+     * @param {number} [options.innerRadius]
+     * @param {number} [options.padAngle=0.02]
+     * @param {number} [options.startAngle=0]
+     * @param {number} [options.endAngle=2π]
+     * @param {string[]} [options.colors]
+     * @param {boolean} [options.showValues=false]
+     * @param {boolean} [options.legend=true]
+     * @param {string} [options.title]
+     */
+    radialBarChart(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'radialBar', data, options };
+        this._renderChart(new RadialBarChart(this.renderer, data, options));
+    }
+
+    /**
+     * Renders a population pyramid — back-to-back horizontal bars comparing
+     * two numeric values per category (commonly male/female by age group).
+     * @param {Array<{label:string, left:number, right:number}>} data
+     * @param {object} [options]
+     * @param {string} [options.leftLabel='Left']
+     * @param {string} [options.rightLabel='Right']
+     * @param {string} [options.leftColor='#4f8ef7']
+     * @param {string} [options.rightColor='#e91e63']
+     * @param {boolean} [options.showValues=false]
+     * @param {string} [options.title]
+     * @param {string} [options.xAxisLabel]
+     * @param {string} [options.yAxisLabel]
+     */
+    populationPyramid(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'populationPyramid', data, options };
+        this._renderChart(new PopulationPyramidChart(this.renderer, data, options));
+    }
+
+    /**
+     * Renders a Sankey diagram — flow links whose width is proportional to the
+     * value they carry, connecting source nodes to target nodes.
+     * @param {object} data
+     * @param {Array<{id:string, label?:string, color?:string}>} [data.nodes]
+     * @param {Array<{source:string, target:string, value:number}>} data.links
+     * @param {object} [options]
+     * @param {number} [options.nodeWidth=16]
+     * @param {number} [options.nodePadding=16]
+     * @param {number} [options.linkOpacity=0.45]
+     * @param {string[]} [options.colors]
+     * @param {string} [options.title]
+     */
+    sankeyDiagram(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'sankey', data, options };
+        this._renderChart(new SankeyDiagram(this.renderer, data, options));
+    }
+
+    /**
+     * Renders a chord diagram — nodes arranged around a circle, with curved
+     * links (chords) whose thickness is proportional to their value.
+     * @param {object} data
+     * @param {Array<{id:string, label?:string, color?:string}>} [data.nodes]
+     * @param {Array<{source:string, target:string, value:number}>} data.links
+     * @param {object} [options]
+     * @param {number} [options.radius]
+     * @param {number} [options.innerRadius]
+     * @param {number} [options.padAngle=0.04]
+     * @param {string[]} [options.colors]
+     * @param {string} [options.title]
+     */
+    chordDiagram(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'chord', data, options };
+        this._renderChart(new ChordDiagram(this.renderer, data, options));
+    }
+
+    /**
+     * Renders a word cloud — words sized by value and laid out with a simple
+     * spiral placement that avoids overlaps.
+     * @param {Array<{text:string, value:number}>} data
+     * @param {object} [options]
+     * @param {string} [options.title]
+     * @param {string[]} [options.colors]
+     * @param {number} [options.minFontSize=12]
+     * @param {number} [options.maxFontSize=48]
+     * @param {string} [options.fontFamily='sans-serif']
+     * @param {number} [options.padding=4]
+     */
+    wordCloud(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'wordCloud', data, options };
+        this._renderChart(new WordCloudChart(this.renderer, data, options));
+    }
+
+    /**
+     * Renders a parallel coordinates plot — one vertical axis per dimension,
+     * with each data row drawn as a polyline connecting its values.
+     * @param {Array<object>} data
+     * @param {object} [options]
+     * @param {string[]} [options.dimensions]
+     * @param {string[]} [options.colors]
+     * @param {number} [options.lineWidth=1.5]
+     * @param {number} [options.lineOpacity=0.6]
+     * @param {boolean} [options.showAxes=true]
+     * @param {boolean} [options.showLegend]
+     * @param {string} [options.title]
+     */
+    parallelCoordinates(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'parallelCoordinates', data, options };
+        this._renderChart(new ParallelCoordinatesChart(this.renderer, data, options));
+    }
+
+    /**
+     * Renders a simple geospatial map — equirectangular projection of
+     * GeoJSON-like Polygon/MultiPolygon features with optional choropleth
+     * fills and bubble markers.
+     * @param {object} data
+     * @param {Array<object>} data.features
+     * @param {Array<{lat:number, lon:number, value:number}>} [data.bubbles]
+     * @param {object} [options]
+     * @param {[number,number]} [options.center]
+     * @param {number} [options.scale]
+     * @param {string[]} [options.colorScale]
+     * @param {number} [options.bubbleMaxRadius=20]
+     * @param {string} [options.bubbleColor]
+     * @param {string} [options.title]
+     */
+    geoMap(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'geoMap', data, options };
+        this._renderChart(new GeoMapChart(this.renderer, data, options));
+    }
+
+    /**
+     * Renders a candlestick (OHLC) chart — one wick+body glyph per time
+     * step. The body is colored by direction (close >= open -> up-color,
+     * else down-color); the wick spans high-low, the body spans open-close.
+     * Optional `markers` overlay point-in-time annotations (e.g. dividend
+     * ex-dates, earnings dates) as small hover-tooltip circles above the
+     * chart — a click-to-expand version of this would need the same global
+     * hitTest-based click wiring `graphDiagram`'s `onNodeClick` uses, out of
+     * scope for this pass.
+     * @param {Array<{label:string, open:number, high:number, low:number, close:number}>} data
+     * @param {object} [options]
+     * @param {string} [options.upColor='#26a69a']
+     * @param {string} [options.downColor='#ef5350']
+     * @param {Array<{label:string, tooltip?:string}>} [options.markers]
+     * @param {string} [options.title]
+     */
+    candlestick(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'candlestick', data, options };
+        this._renderChart(new CandlestickChart(this.renderer, data, options));
+    }
+
+    /**
+     * Builds a path `d` string for a pie slice (rInner=0) or a doughnut/
+     * annular slice (rInner>0) spanning startAngle..endAngle (radians).
+     * @private
+     */
+    _donutSlicePath(cx, cy, rOuter, rInner, startAngle, endAngle) {
+        return ShapePaths.donutSlicePath(cx, cy, rOuter, rInner, startAngle, endAngle);
+    }
+
+    /**
+     * Renders a pie chart, or a doughnut chart when `innerRadiusRatio > 0`.
+     * @param {Array<{label:string, value:number}>} data
+     * @param {object} [options]
+     * @param {number} [options.innerRadiusRatio=0] 0 = pie; e.g. 0.6 = doughnut
+     * @param {string[]} [options.colors]
+     * @param {boolean} [options.legend=true]
+     * @param {string} [options.title]
+     */
+    pieChart(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'pie', data, options };
+        this._renderChart(new PieChart(this.renderer, data, options));
+    }
+
+    /**
+     * Renders a doughnut chart — a pie chart with a default inner radius.
+     * @param {Array<{label: string, value: number}>} data The data to chart.
+     * @param {object} [options] Same options as pieChart; innerRadiusRatio defaults to 0.5.
+     */
+    donutChart(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'donut', data, options };
+        this._renderChart(new DonutChart(this.renderer, data, options));
+    }
+
+    /**
+     * Renders an area chart — a line chart with the region below each series
+     * filled down to the baseline (or, with `stacked:true`, down to the
+     * previous series' band) to emphasize magnitude/cumulative volume rather
+     * than just trend shape.
+     * @param {Array<{label,value}>|Array<{name,values:Array<{label,value}>}>} data
+     * @param {object} [options]
+     * @param {boolean} [options.stacked=false]
+     * @param {string[]} [options.colors]
+     * @param {boolean} [options.legend=false]
+     */
+    areaChart(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'area', data, options };
+        this._renderChart(new AreaChart(this.renderer, data, options));
+    }
+
+    /**
+     * Renders a stacked area chart. Convenience wrapper around areaChart with
+     * `stacked: true`; accepts the same multi-series data shape.
+     * @param {Array<{name: string, values: Array<{label: string, value: number}>}>} data
+     * @param {object} [options]
+     */
+    stackedAreaChart(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'stackedArea', data, options };
+        this._renderChart(new StackedAreaChart(this.renderer, data, options));
+    }
+
+    /**
+     * Computes evenly-spaced bin edges/counts for a raw numeric sample —
+     * pure data transform, no rendering, DOM-free and unit-testable (same
+     * convention as `_tableNodeSize`/`_tableColumnY`).
+     * @private
+     */
+    _histogramBins(values, binCount) {
+        return Statistics.histogramBins(values, binCount);
+    }
+
+    /**
+     * Renders a histogram — frequency distribution of a raw numeric sample,
+     * binned into `binCount` evenly-spaced buckets (default: a Sturges'-rule
+     * estimate, ⌈log2(n)+1⌉, clamped to a sane 5-20 range).
+     * @param {number[]} values raw numeric sample (not pre-binned)
+     * @param {object} [options]
+     * @param {number} [options.binCount]
+     * @param {string} [options.barColor='steelblue']
+     */
+    histogram(values, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'histogram', data: values, options };
+        this._renderChart(new HistogramChart(this.renderer, values, options));
+    }
+
+    /**
+     * Inverse standard-normal CDF (the probit function) via Peter Acklam's
+     * well-known rational approximation (~1.15e-9 relative accuracy) — the
+     * "reference-distribution quantile function" qqPlot needs. Pure,
+     * DOM-free, unit-testable against known reference values.
+     * @private
+     */
+    _normalQuantile(p) {
+        return Statistics.normalQuantile(p);
+    }
+
+    /**
+     * Pairs each sorted sample value with a theoretical normal quantile at
+     * the standard `(i - 0.5)/n` plotting position — the data qqPlot
+     * scatters. Pure, DOM-free, unit-testable. Both fields come out
+     * already ascending (sample is sorted; _normalQuantile is monotonic).
+     * @returns {Array<{theoretical: number, sample: number}>}
+     * @private
+     */
+    _qqPoints(values) {
+        return Statistics.qqPoints(values);
+    }
+
+    /**
+     * `[{x: values[i-lag], y: values[i]}]` for i = lag..length-1 — the data
+     * lagPlot scatters, to visually check autocorrelation. Pure, DOM-free,
+     * unit-testable.
+     * @private
+     */
+    _lagPairs(values, lag = 1) {
+        return Statistics.lagPairs(values, lag);
+    }
+
+    /**
+     * Linear-interpolation quantile (the common "R-7"/PERCENTILE.INC method)
+     * over an already-sorted numeric array. Pure, DOM-free, unit-testable.
+     * @private
+     */
+    _quantile(sorted, p) {
+        return Statistics.quantile(sorted, p);
+    }
+
+    /**
+     * Computes box-and-whisker summary stats for a raw numeric sample:
+     * quartiles, whiskers clamped to the standard 1.5×IQR Tukey fences (and
+     * to the actual data range), and anything beyond the fences as an
+     * outlier. Pure, DOM-free, unit-testable.
+     * @private
+     */
+    _boxPlotStats(values) {
+        return Statistics.boxPlotStats(values);
+    }
+
+    /** Population standard deviation. Pure, DOM-free, unit-testable. @private */
+    _stdev(values) {
+        return Statistics.stdev(values);
+    }
+
+    /**
+     * Gaussian-kernel density estimate — a smoothed distribution curve from
+     * a raw numeric sample, the shared math core behind densityChart and
+     * violinChart. `bandwidth` defaults via Silverman's rule of thumb
+     * (`1.06 * stdev * n^(-1/5)`, the standard heuristic, not bespoke);
+     * `min`/`max` default to 3 bandwidths past the data's own extremes so
+     * the curve tapers to ~0 rather than being cut off mid-slope. Pure,
+     * DOM-free, unit-testable.
+     * @returns {Array<{x: number, density: number}>}
+     * @private
+     */
+    _kernelDensityEstimate(values, options = {}) {
+        return Statistics.kernelDensityEstimate(values, options);
+    }
+
+    /**
+     * Renders a box-and-whisker plot — one box per group, summarizing a raw
+     * numeric sample's spread (median, quartiles, whiskers, outliers)
+     * instead of plotting every point.
+     * @param {Array<{label:string, values:number[]}>} data
+     * @param {object} [options]
+     * @param {string} [options.boxColor='#5470c6']
+     */
+    boxPlot(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'boxPlot', data, options };
+        this._renderChart(new BoxPlotChart(this.renderer, data, options));
+    }
+
+    /**
+     * Renders overlaid distribution curves — one Gaussian-KDE curve per
+     * group (_kernelDensityEstimate), sharing one value-axis so shapes are
+     * visually comparable. Same top-level data shape as boxPlot (a caller
+     * can hand the identical dataset to either) and the same multi-series
+     * fill+topline+legend rendering pattern as areaChart, just with the
+     * curve computed from a raw sample instead of literal category/value
+     * points. Y is relative density (curve shape only) — no meaningful
+     * absolute-number axis, so no numeric y-tick labels, same spirit as
+     * radarChart's unlabeled radial scale.
+     * @param {Array<{label:string, values:number[]}>} data
+     * @param {object} [options]
+     * @param {string[]} [options.colors]
+     * @param {boolean} [options.legend=true]
+     */
+    densityChart(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'density', data, options };
+        this._renderChart(new DensityChart(this.renderer, data, options));
+    }
+
+    /**
+     * Renders a violin plot — one mirrored Gaussian-KDE silhouette per
+     * group in its own x-slot, the same per-group layout math as boxPlot
+     * (same top-level data shape too — a caller can hand the identical
+     * dataset to either). Unlike boxPlot's single flat `boxColor`, each
+     * violin gets its own palette color: a violin's shape is visually
+     * larger/more prominent than a thin box glyph, so per-group color
+     * materially helps distinguish many holdings at a glance (same
+     * reasoning treemapChart/sunburstChart color per top-level group). A
+     * thin median tick (reusing _quantile, like boxPlot's own) is drawn
+     * for reference — no outlier dots, since showing the full distribution
+     * shape including tails IS the point of a violin, unlike box plot's
+     * separate Tukey-fence "outlier" concept.
+     * @param {Array<{label:string, values:number[]}>} data
+     * @param {object} [options]
+     * @param {string[]} [options.colors]
+     */
+    violinChart(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'violin', data, options };
+        this._renderChart(new ViolinChart(this.renderer, data, options));
+    }
+
+    /** Layout constant for treemapChart's branch-node header band. */
+    static TREEMAP_HEADER_H = 16;
+
+    /**
+     * A leaf's own value, or a branch's value computed as the sum of its
+     * children (recursively — never required from the caller). Non-finite
+     * or non-positive values can't be allocated area/angle and are treated
+     * as 0 (filtered out by the caller doing the layout, not here). Pure —
+     * directly unit-testable. Shared by treemapChart and sunburstChart —
+     * both consume the same `Array<{label, value?, children?}>` shape.
+     * @private
+     */
+    _hierarchyValue(node) {
+        return Hierarchy.value(node);
+    }
+
+    /**
+     * Tree depth: 1 for a leaf, 1 + the deepest child for a branch. Pure.
+     * Used by sunburstChart to size each ring so an arbitrarily deep tree
+     * still fits within one fixed radius, rather than overflowing it.
+     * @private
+     */
+    _hierarchyDepth(node) {
+        return Hierarchy.depth(node);
+    }
+
+    /**
+     * The worst (largest) width:height aspect ratio among `row`'s
+     * rectangles if laid out along a strip of the given `side` length —
+     * the score squarify minimizes one row at a time. Pure. Assumes every
+     * item's `.area` is already computed (see _squarify).
+     * @private
+     */
+    _squarifyWorstRatio(row, side) {
+        return Hierarchy.squarifyWorstRatio(row, side);
+    }
+
+    /**
+     * Squarified treemap (Bruls/Huizing/van Wijk): lays `items` (each
+     * `{value, ref}`, pre-sorted descending by value by the caller) into
+     * the rect `x,y,width,height`, area-proportional to value. Repeatedly
+     * grows a "row" along the shorter side of the remaining space while
+     * the worst aspect ratio in that row keeps improving, then flushes the
+     * row and continues into what's left. Pure — operates on generic
+     * `{value, ref}` pairs, not tied to the tree-node shape, so it's
+     * directly testable with plain numbers.
+     * @returns {Array<{ref: *, x: number, y: number, width: number, height: number}>}
+     * @private
+     */
+    _squarify(items, x, y, width, height) {
+        return Hierarchy.squarify(items, x, y, width, height);
+    }
+
+    /**
+     * Recursive layout over a treemapChart() node tree. Computes each
+     * node's value (_hierarchyValue), squarifies this level (_squarify), and
+     * for a branch reserves a fixed-height header band at the top of its
+     * rect before recursing into the remaining content rect for its
+     * children at depth+1. Returns a FLAT list covering every node in the
+     * tree — a branch's own entry is pushed before its children are
+     * recursed into (pre-order), so a caller painting in array order never
+     * covers a node with its own descendant drawn first. Each entry also
+     * carries `topAncestor` (the depth-0 node this one descends from, or
+     * itself at depth 0) so a renderer can color every descendant off its
+     * top-level group without re-walking the tree. Pure — no DOM/renderer
+     * access.
+     * @returns {Array<{node: object, x: number, y: number, width: number, height: number, depth: number, isLeaf: boolean, topAncestor: object}>}
+     * @private
+     */
+    _treemapLayout(nodes, x, y, width, height, depth = 0, topAncestors = null) {
+        return Hierarchy.treemapLayout(nodes, x, y, width, height, depth, topAncestors, RenderEngine.TREEMAP_HEADER_H);
+    }
+
+    /**
+     * Renders a treemap — rectangles nested/sized proportional to value
+     * (squarified layout, see _treemapLayout), the standard chart for
+     * "composition of a whole across a hierarchy" (e.g. disk usage by
+     * folder, headcount by department/team).
+     * @param {Array<{label: string, value?: number, children?: Array}>} data
+     *   A leaf has `value` and no `children`; a branch has `children` (its
+     *   value is the sum, computed automatically) and can nest to any depth.
+     * @param {object} [options]
+     * @param {string[]} [options.colors] Palette — one color per top-level node, descendants shaded lighter by depth.
+     * @param {string} [options.title]
+     */
+    treemapChart(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'treemap', data, options };
+        this._renderChart(new TreemapChart(this.renderer, data, options));
+    }
+
+    /**
+     * Recursive angular layout over the same node tree treemapChart()
+     * consumes — mirrors _treemapLayout's shape but partitions ANGLE
+     * instead of area, one ring per depth. Unlike _treemapLayout (which
+     * sorts descending for squarify's aspect-ratio heuristic), input order
+     * is preserved — same convention as pieChart, and there's no
+     * aspect-ratio concept for a polar arc that sorting would improve.
+     * Returns a flat pre-order list, each entry carrying `topAncestor` (the
+     * depth-0 node this one descends from) for render-time color lookup —
+     * same pattern _treemapLayout established. Pure — no DOM/renderer
+     * access.
+     * @returns {Array<{node: object, cx: number, cy: number, rInner: number, rOuter: number, startAngle: number, endAngle: number, depth: number, isLeaf: boolean, topAncestor: object}>}
+     * @private
+     */
+    _sunburstLayout(nodes, cx, cy, innerRadius, ringWidth, startAngle, endAngle, depth = 0, topAncestors = null) {
+        return Hierarchy.sunburstLayout(nodes, cx, cy, innerRadius, ringWidth, startAngle, endAngle, depth, topAncestors);
+    }
+
+    /**
+     * Renders a sunburst — the same hierarchical composition treemapChart
+     * shows as nested rectangles, drawn instead as nested rings (one ring
+     * per depth), each ring's arcs sized by value like a pie chart. Shares
+     * treemapChart's exact data contract (_hierarchyValue) and its
+     * top-level-palette/depth-lightened coloring scheme; reuses
+     * _donutSlicePath (built for pieChart's doughnut mode) for the actual
+     * annular-sector geometry, since a sunburst ring IS a doughnut slice.
+     * @param {Array<{label: string, value?: number, children?: Array}>} data
+     *   Same shape as treemapChart: a leaf has `value`, a branch has
+     *   `children` (value computed as their sum) and can nest to any depth.
+     * @param {object} [options]
+     * @param {number} [options.cx] @param {number} [options.cy] @param {number} [options.radius]
+     * @param {number} [options.innerRadiusRatio=0] Fraction of `radius` left as a center hole, same semantics as pieChart.
+     * @param {string[]} [options.colors] Palette — one color per top-level node, descendants shaded lighter by depth (like treemapChart).
+     * @param {string} [options.title]
+     */
+    sunburstChart(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'sunburst', data, options };
+        this._renderChart(new SunburstChart(this.renderer, data, options));
+    }
+
+    /**
+     * Flat, pre-order list of *visible* rows for outlineChart() — a branch
+     * present in `collapsed` (a Set of node object references, not ids —
+     * this shape has no id field) contributes its own row but none of its
+     * descendants'. Threads `topAncestor` through the recursion the same
+     * way _treemapLayout/_sunburstLayout do, so the renderer can look up a
+     * row's top-level accent color without re-walking the tree. Pure — no
+     * DOM/renderer access, directly unit-testable.
+     * @returns {Array<{node: object, depth: number, hasChildren: boolean, topAncestor: object}>}
+     * @private
+     */
+    _outlineLayout(nodes, depth, collapsed, topAncestors = null) {
+        return Hierarchy.outlineLayout(nodes, depth, collapsed, topAncestors);
+    }
+
+    /**
+     * A leaf row's trailing descriptive text — every field beyond
+     * label/value/children, values only (no "key: " prefix, unlike
+     * _nodeExtraDataLines' tooltip lines — a plain dash-joined fragment
+     * reads better on an outline row than a labeled list), e.g. a table
+     * row's "3 columns · 3 rows · hybrid" from
+     * `{label:'users', columns:3, rows:3, mode:'hybrid'}`. Pure.
+     * @private
+     */
+    _outlineExtraText(node) {
+        return Hierarchy.outlineExtraText(node, RenderEngine.HIERARCHY_STRUCTURAL_KEYS);
+    }
+
+    /** Re-invokes outlineChart() with its last data/options — same
+     *  "re-render after a click-driven state change" pattern
+     *  _rerenderGraph() uses for graphDiagram's own +/− badges.
+     *  @private */
+    _rerenderOutline() {
+        if (this._chartState?.type === 'outline') this.outlineChart(this._chartState.data, this._chartState.options);
+    }
+
+    /**
+     * Renders an outline / tree list — the same hierarchical composition
+     * treemapChart/sunburstChart show as nested rectangles/rings, drawn
+     * instead as an indented, collapsible list (a file-explorer or site-menu's
+     * usual shape): one row per node, a branch's own value auto-summed from
+     * its descendants (_hierarchyValue) shown as a trailing count, a leaf's
+     * own extra fields (anything beyond label/value/children) shown as
+     * trailing descriptive text instead. Any branch gets a +/− toggle;
+     * clicking it collapses/expands just that subtree and re-renders —
+     * collapse state (`this._outlineCollapsed`, a Set of node object
+     * references) persists across re-renders of the *same* data array, the
+     * same convention graphDiagram's hierarchical-key +/− badges use for
+     * `_graphCollapsedNodes`. Content taller than the container scales down
+     * to fit (top-anchored, not centered) rather than clipping or scrolling —
+     * same "set viewBox to the content's real size" trick renderDiagram()
+     * uses for a wide railroad diagram. SVG-only: the toggle/click
+     * interactivity needs real per-row DOM elements, same reason
+     * graphDiagram is SVG-only.
+     * @param {Array<{label: string, value?: number, children?: Array}>} data
+     *   Same shape as treemapChart/sunburstChart: a leaf has `value` (or its
+     *   own extra fields), a branch has `children` (value computed as their
+     *   sum) and can nest to any depth. Any field beyond label/value/children
+     *   is extra descriptive data, not part of the structural contract.
+     * @param {object} [options]
+     * @param {string[]} [options.colors] Palette — one color per top-level node's row accent, descendants shaded lighter by depth (same scheme as treemapChart/sunburstChart).
+     * @param {string} [options.title]
+     * @param {function} [options.onNodeClick] Fired when a row's label (not its +/− toggle) is clicked.
+     */
+    outlineChart(data, options = {}) {
+        if (!this.renderer || !this.renderer.supportsSceneGraph) {
+            console.warn('Outline chart is only supported in SVG renderer.');
+            return;
+        }
+        this._chart3D = false;
+        this._chartState = { type: 'outline', data, options };
+        this._outlineCollapsed = this._outlineCollapsed || new Set();
+        this._renderChart(new OutlineChart(this.renderer, data, options, this._outlineCollapsed, () => this._rerenderOutline()));
+    }
+
+    /**
+     * Renders a radar/spider chart — one polygon per series across N shared
+     * axes, each axis scaled independently by its own max value across all
+     * series, so differently-scaled metrics (e.g. "latency ms" vs "score
+     * 0-10") share one chart without one axis flattening the others.
+     * @param {Array<{name:string, values:Array<{axis:string, value:number}>}>|Array<{axis:string,value:number}>} data
+     * @param {object} [options]
+     * @param {string[]} [options.colors]
+     * @param {boolean} [options.legend=true]
+     */
+    radarChart(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'radar', data, options };
+        this._renderChart(new RadarChart(this.renderer, data, options));
+    }
+
+    /**
+     * Renders a funnel chart — one horizontal trapezoid band per stage,
+     * width proportional to `value` relative to the largest stage, for
+     * visualizing drop-off across a sequential process (e.g. a sales
+     * pipeline). Each stage's bottom edge width comes from the *next*
+     * stage's value, so the taper between adjacent bands is continuous.
+     * @param {Array<{label:string, value:number}>} data ordered top-to-bottom (largest first, by convention)
+     * @param {object} [options]
+     * @param {string[]} [options.colors]
+     * @param {string} [options.title]
+     */
+    funnelChart(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'funnel', data, options };
+        this._renderChart(new FunnelChart(this.renderer, data, options));
+    }
+
+    /**
+     * Renders a waterfall chart — running-total bars, each floating from the
+     * previous cumulative value to the new one (a "delta" bar), except
+     * entries marked `type:'total'` which draw full-height from zero (a
+     * subtotal/grand-total checkpoint). Increases/decreases are colored
+     * distinctly; thin connector lines between consecutive bars follow the
+     * classic waterfall styling.
+     * @param {Array<{label:string, value:number, type?:'delta'|'total'}>} data
+     * @param {object} [options]
+     * @param {string} [options.upColor='#26a69a']
+     * @param {string} [options.downColor='#ef5350']
+     * @param {string} [options.totalColor='#5470c6']
+     */
+    waterfallChart(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'waterfall', data, options };
+        this._renderChart(new WaterfallChart(this.renderer, data, options));
+    }
+
+    /**
+     * Reads whatever `colorCol` names for one data point — a plain field
+     * name (unchanged behavior: `d[colorCol]`), or a compiled
+     * `{formula, params}` expression evaluated over the point's own fields
+     * (`kernelExpr.js`, the same small grammar sqlengine's compiled UDFs
+     * use — see `documentation`/`tasks.md`). Shared by every chart with a
+     * `colorCol` option (scatterChart/bubbleChart/bubbleChart3D) so a
+     * formula means the same thing wherever it's written, and each distinct
+     * value it returns gets its own palette color exactly as a plain
+     * field's distinct values already do.
+     * @private
+     */
+    _readColorCol(d, colorCol) {
+        return ChartData.readColorCol(d, colorCol);
+    }
+
+    /**
+     * Renders a plain 2D scatter plot — x/y points at a fixed marker radius,
+     * no size encoding (see bubbleChart() for that, which requires a `z`
+     * field this doesn't). Optional per-point categorical coloring via
+     * `colorCol`/`category`/`group`, same convention as bubbleChart. Uses a
+     * real [min,max] domain per axis (not a 0-anchored one), so negative
+     * values (e.g. investment returns, normal quantiles) plot correctly —
+     * qqPlot/lagPlot both delegate their entire rendering here and need
+     * exactly that.
+     * @param {Array<{label: string, x: number, y: number}>} data The data to chart.
+     * @param {object} [options] Charting options.
+     * @param {boolean|{from:{x,y},to:{x,y}}} [options.referenceLine] A dashed
+     *   reference line: `true` draws identity (y=x) over the domains'
+     *   overlap (what lagPlot uses); an explicit `{from,to}` pair (data
+     *   space) draws exactly that segment (what qqPlot's fitted Q1/Q3 line
+     *   uses — not the same as identity).
+     */
+    scatterChart(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false; // leaving 3D mode — clears the SVG-zoom guard added for bubbleChart3D
+        this._chartState = { type: 'scatter', data, options };
+        this._renderChart(new ScatterChart(this.renderer, data, options));
+    }
+
+    /**
+     * Renders a Q-Q (quantile-quantile) plot — tests whether a raw sample
+     * is approximately normally distributed, the standard tail-risk/
+     * fat-tails diagnostic for a return series before trusting a risk
+     * model's normality assumption. Each point is (theoretical normal
+     * quantile, sample quantile) via _qqPoints; a dashed reference line
+     * fit through the sample's own Q1/Q3 (the standard qqline() convention
+     * — not a plain y=x identity) shows what "perfectly normal" would look
+     * like — points hugging the line are normal-ish, systematic curvature
+     * (especially at the ends) signals fat tails/skew. Delegates its
+     * entire rendering (points + reference line) to scatterChart via its
+     * `referenceLine` option — no separate rendering code here.
+     * @param {number[]} values Raw numeric sample.
+     * @param {object} [options] Forwarded to scatterChart (title/axis labels/colors/box).
+     */
+    qqPlot(values, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'qqPlot', data: values, options };
+        this._renderChart(new QQPlotChart(this.renderer, values, options));
+    }
+
+    /**
+     * Renders a lag plot — value[t] against value[t-lag] (default lag=1),
+     * the standard visual autocorrelation check: points scattered with no
+     * structure suggest an uncorrelated (white-noise) series; a clear
+     * diagonal trend (hugging the identity reference line) suggests real
+     * serial dependence — worth checking before treating lagged values as
+     * predictive features (e.g. a KAN model's input engineering). The pure
+     * lag-pairing transform (_lagPairs) is the only genuinely new logic
+     * here — rendering delegates entirely to scatterChart.
+     * @param {number[]} values Raw ordered numeric series.
+     * @param {object} [options] `lag` (default 1) plus everything scatterChart accepts.
+     */
+    lagPlot(values, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'lagPlot', data: values, options };
+        this._renderChart(new LagPlotChart(this.renderer, values, options));
+    }
+
+    /**
+     * Renders a bubble chart.
+     * @param {Array<{label: string, x: number, y: number, z: number}>} data The data to chart.
+     * @param {object} [options] Charting options.
+     */
+    bubbleChart(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false; // leaving 3D mode — clears the SVG-zoom guard added for bubbleChart3D
+        this._chartState = { type: 'bubble', data, options };
+        this._renderChart(new BubbleChart(this.renderer, data, options));
+    }
+
+    /**
+     * Projects a normalized 3D point (each axis roughly in [-1, 1], centered
+     * on the data's own origin) through a real orbit camera (OrbitCamera.js —
+     * composed Mat4 rotation + a genuine perspective-projection matrix, not
+     * the hand-tuned `distance/(distance+depth*0.6)` heuristic this used to
+     * be) down to a 2D offset plus a depth value for z-sorting. Callers scale
+     * sx/sy by the chart's own pixel radius and offset to its center — same
+     * contract as before, so bubbleChart3D/_drawBox3D's `toScreen` closures
+     * didn't need to change. `camera` is the plain {theta,phi,distance}
+     * state `_camera3D`/`_addOrbit3DListeners` already drive; fovY/near/far
+     * aren't part of that shared state (nothing currently varies them), so
+     * OrbitCamera's own defaults apply. Square aspect (1) — callers already
+     * scale sx and sy by the same single pixelRadius, i.e. they assume
+     * uniform x/y scaling, so this preserves that.
+     * @private
+     */
+    _project3D(x, y, z, camera) {
+        return Chart3D.project(x, y, z, camera);
+    }
+
+    /**
+     * Renders a true 3D scatter/bubble chart — x/y/z are all spatial axes
+     * (unlike bubbleChart(), where z encodes bubble *size*, not position) —
+     * with an orbit camera you can drag to rotate and scroll to zoom (see
+     * _addOrbit3DListeners). Distinct from bubbleChart({zAxis:true})'s fixed
+     * isometric shift: this recomputes a real projection every frame and
+     * z-sorts points back-to-front, so nearer points correctly occlude
+     * farther ones as you rotate.
+     * @param {Array<{label: string, x: number, y: number, z: number, size?: number, category?: string}>} data
+     * @param {object} [options]
+     * @param {string|{formula:string,params:string[]}} [options.colorCol] Field name to color points by
+     *   (auto-detects `category`/`group`), or a compiled formula over the point's own fields, e.g.
+     *   `{formula: 'value > threshold ? 1 : 0', params: ['value', 'threshold']}` — see `kernelExpr.js`.
+     * @param {string[]} [options.colors] Palette for categorical coloring.
+     * @param {string} [options.title]
+     * @param {number} [options.initialTheta=-0.6] Starting azimuth (radians).
+     * @param {number} [options.initialPhi=0.35] Starting elevation (radians).
+     * @param {number} [options.initialDistance=2.2] Starting camera distance (zoom).
+     */
+    bubbleChart3D(data, options = {}) {
+        if (!this.renderer) return;
+
+        const {
+            initialTheta = -0.6, initialPhi = 0.35, initialDistance = 2.2,
+        } = options;
+
+        // Camera state persists across redraws (drag/wheel) — only seed it
+        // the first time this exact chart is drawn, not on every redraw.
+        if (!this._camera3D) this._camera3D = { theta: initialTheta, phi: initialPhi, distance: initialDistance };
+        this._initialCamera3D = { theta: initialTheta, phi: initialPhi, distance: initialDistance };
+        this._chart3D = true;
+        this._chartState = { type: 'bubble3d', data, options };
+        this._chart3DRedraw = () => this.bubbleChart3D(data, { ...options, initialTheta, initialPhi, initialDistance });
+
+        this._renderChart(new BubbleChart3D(this.renderer, data, options, this._camera3D));
+    }
+
+    /**
+     * Draws one 3D box (a bar or one segment of a stacked bar) as three
+     * visible faces — top, plus one X-side and one Z-side wall — through the
+     * orbit camera. Full backface culling/lighting is out of scope here:
+     * instead of testing every face, the X/Z side to draw is chosen by the
+     * sign of the camera's approximate world-space direction
+     * (sin(theta)/cos(theta) for a standard orbit-camera spherical→cartesian
+     * position), which is cheap and looks correct across the normal drag
+     * range even though it isn't exact culling. Bars don't interpenetrate,
+     * so the caller only needs to z-sort *bars* (by center depth), not faces.
+     * @returns {number} the box's average corner depth, for the caller's own
+     *   bar-level z-sort.
+     * @private
+     */
+    _drawBox3D(x0, x1, y0, y1, z0, z1, color, toScreen, camera) {
+        return Chart3D.drawBox(this.renderer, x0, x1, y0, y1, z0, z1, color, toScreen, camera);
+    }
+
+    /**
+     * Groups flat {x, z, ...} data into grid indices/labels for the two
+     * orbit-camera bar chart variants — shared so barChart3DOrbit and
+     * stackedBarChart3DOrbit bucket categories identically.
+     * @private
+     */
+    _bucketGrid3D(data) {
+        return Chart3D.bucketGrid(data);
+    }
+
+    /**
+     * Renders a grouped 3D bar chart across two categorical axes (x and z)
+     * with a real orbit camera — drag to rotate, scroll to zoom (see
+     * _addOrbit3DListeners). Distinct from barChart3D's isometric single-axis
+     * bars: this is what "3D bar chart" usually means (a grid of bars, viewed
+     * from any angle), not a fixed-tilt 2D chart with a depth shadow.
+     * @param {Array<{x: string, z: string, value: number}>} data
+     * @param {object} [options]
+     * @param {string[]} [options.colors] Palette, indexed by z-group.
+     * @param {string} [options.title]
+     * @param {number} [options.initialTheta=-0.5] @param {number} [options.initialPhi=0.45] @param {number} [options.initialDistance=2.4]
+     */
+    barChart3DOrbit(data, options = {}) {
+        if (!this.renderer) return;
+
+        const { initialTheta = -0.5, initialPhi = 0.45, initialDistance = 2.4 } = options;
+
+        if (!this._camera3D) this._camera3D = { theta: initialTheta, phi: initialPhi, distance: initialDistance };
+        this._initialCamera3D = { theta: initialTheta, phi: initialPhi, distance: initialDistance };
+        this._chart3D = true;
+        this._chartState = { type: 'bar3dOrbit', data, options };
+        this._chart3DRedraw = () => this.barChart3DOrbit(data, { ...options, initialTheta, initialPhi, initialDistance });
+
+        this._renderChart(new BarChart3DOrbit(this.renderer, data, options, this._camera3D));
+    }
+
+    /**
+     * Stacked-segment version of barChart3DOrbit: each (x, z) grid cell
+     * holds a stack of `values`, each drawn as its own shorter box on top of
+     * the previous segment (correct occlusion within one bar since segments
+     * share x/z and only differ in y-extent — no special-casing needed
+     * beyond the existing per-bar z-sort).
+     * @param {Array<{x: string, z: string, values: number[]}>} data
+     * @param {object} [options] Same as barChart3DOrbit, plus `colors` is
+     *   indexed by *segment index* (stack position) instead of z-group.
+     */
+    stackedBarChart3DOrbit(data, options = {}) {
+        if (!this.renderer) return;
+
+        const { initialTheta = -0.5, initialPhi = 0.45, initialDistance = 2.4 } = options;
+
+        if (!this._camera3D) this._camera3D = { theta: initialTheta, phi: initialPhi, distance: initialDistance };
+        this._initialCamera3D = { theta: initialTheta, phi: initialPhi, distance: initialDistance };
+        this._chart3D = true;
+        this._chartState = { type: 'stackedBar3dOrbit', data, options };
+        this._chart3DRedraw = () => this.stackedBarChart3DOrbit(data, { ...options, initialTheta, initialPhi, initialDistance });
+
+        this._renderChart(new StackedBarChart3DOrbit(this.renderer, data, options, this._camera3D));
+    }
+
+    /**
+     * Renders a 3D bar chart (isometric projection).
+     * @param {Array<{label: string, value: number, depth?: number}>} data The data to chart.
+     * @param {object} [options] Charting options.
+     */
+    barChart3D(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false; // leaving 3D mode — clears the SVG-zoom guard added for bubbleChart3D
+        this._chartState = { type: 'bar3d', data, options };
+        this._renderChart(new BarChart3D(this.renderer, data, options));
+    }
+
+    /**
+     * Helper function to lighten/darken a color for 3D effect.
+     * @private
+     */
+    _lightenColor(color, amount) {
+        return ColorPalette.lighten(color, amount);
+    }
+
+    /** @private hex "#rrggbb" -> {r,g,b} */
+    _hexToRgb(hex) {
+        return ColorPalette.hexToRgb(hex);
+    }
+
+    /** @private Linear-interpolates between two hex colors at t in [0,1]. */
+    _interpolateColor(c1, c2, t) {
+        return ColorPalette.interpolate(c1, c2, t);
+    }
+
+    /**
+     * Resolves a gauge `color` option to a single hex color for the given
+     * 0-100 value. A plain string passes through unchanged. An array is
+     * treated as a heat-map gradient, in either of two forms:
+     *  - plain hex strings, evenly spaced across 0-100:
+     *    `['#67e043', '#f9d939', '#f23c24']`
+     *  - `{stop, color}` pairs at explicit percentages (unevenly spaced
+     *    breakpoints, e.g. "green until 50, amber until 80, red above"):
+     *    `[{stop:0,color:'#67e043'},{stop:50,color:'#f9d939'},{stop:80,color:'#f23c24'}]`
+     * @private
+     */
+    _resolveGaugeColor(color, percent) {
+        return Gauge.resolveColor(color, percent);
+    }
+
+    /**
+     * Renders a bar gauge.
+     * @param {number} value The value to display (0-100).
+     * @param {object} [options] Charting options.
+     */
+    barGauge(value, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false; // leaving 3D mode — clears the SVG-zoom guard added for bubbleChart3D
+        this._chartState = { type: 'barGauge', data: value, options };
+        this._renderChart(new BarGauge(this.renderer, value, options));
+    }
+
+    /**
+     * Renders a bullet graph: a primary bar compared against qualitative
+     * performance ranges and a target marker.
+     * @param {number|{value:number, target?:number, ranges?:Array<{max:number, label?, color?}>}} data The actual value, or an object with value/target/ranges.
+     * @param {object} [options] Charting options.
+     */
+    bulletGauge(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'bullet', data, options };
+        this._renderChart(new BulletGauge(this.renderer, data, options));
+    }
+
+    /**
+     * Renders a dial gauge.
+     * @param {number} value The value to display (0-100).
+     * @param {object} [options] Charting options.
+     */
+    dialGauge(value, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false; // leaving 3D mode — clears the SVG-zoom guard added for bubbleChart3D
+        this._chartState = { type: 'dialGauge', data: value, options };
+        this._renderChart(new DialGauge(this.renderer, value, options));
+    }
+
+    _arcPath(cx, cy, r, startAngle, endAngle) {
+        return Gauge.arcPath(cx, cy, r, startAngle, endAngle);
+    }
+
+    /**
+     * Renders a simple network graph diagram. If any node's `id` is a
+     * Dewey-style hierarchical key (digits joined by `.`, `-`, or `/`, e.g.
+     * `"1.2.3"`, `"1-2-3"`) — see `_inferHierarchyEdges` — the parent-child
+     * relationships implied by those keys replace `edges` entirely (except
+     * "quasi-leaf" edges touching a non-Dewey-key node, which are kept and
+     * attach that plain node as an extra child) and the diagram is laid out
+     * as a top-down tree (`_computeTreeLayout`) instead of force-directed.
+     * In that mode, any node with children gets a +/− badge to collapse or
+     * expand its subtree, and a node's extra fields (beyond id/label/x/y/
+     * shape/color/group/size) are auto-listed in its hover tooltip. Call
+     * `filterGraphNodes(keyword)` at any time to live-filter which nodes are
+     * shown by label/extra-data keyword (ancestors of a match stay visible
+     * in hierarchical mode).
+     * @param {Array<{id: string, label?: string|((node:object)=>string), name?: string, x: number, y: number, size?: number, icon?: string, iconUrl?: string}>} nodes
+     *   Array of node objects — `size` (a plain number) scales that node's radius, see `sizeBy` below. `icon`
+     *   (a short glyph/emoji string) or `iconUrl` (an image/SVG file or data URI) replaces the plain initials
+     *   text centred on the node's shape — `iconUrl` wins if both are set; neither applies to `shape:'person'`
+     *   (which already draws its own glyph) or `shape:'table'`. A `shape:'rect'` node's own `width`/`height`
+     *   override the usual square-of-radius box (see `options.labelPosition` for putting its label inside it,
+     *   word-wrapped and clipped to that box rather than a single overflowing line). Its own `cornerStyle`
+     *   (`'sharp'|'rounded'|'chamfered'`, default a plain small rx) picks the corner treatment — `archimateDiagram`
+     *   uses this for ArchiMate's own generic box shapes (_archimateCornerStyle), but it's a plain graphDiagram
+     *   node field, usable without archimateDiagram at all.
+     *   **Label resolution** (see `_resolveNodeLabel`, used everywhere a node's label is shown — the box/
+     *   caption text, 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 containing `{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 `name`.
+     * @param {Array<{source: string, target: string, weight?: number}>} edges Array of edge objects linking nodes by id — replaced by the inferred hierarchy if one is detected (quasi-leaf edges excepted, see above). `weight` scales that edge's stroke width, see `minEdgeWidth` below.
+     * @param {object} [options] Rendering options.
+     * @param {'degree'} [options.sizeBy] Size nodes by connection count (in + out edges) instead of requiring the
+     *   caller to pre-populate `node.size` — useful when "how connected is this node" IS the value worth showing.
+     * @param {number} [options.minRadius] @param {number} [options.maxRadius] @param {'linear'|'sqrt'} [options.sizeScale]
+     *   Range/curve `node.size` (or degree, with `sizeBy:'degree'`) maps into — only takes effect once some node
+     *   has a finite size value; `sqrt` compresses outliers where the value scales with an area/count, not a length.
+     * @param {number} [options.minEdgeWidth] @param {number} [options.maxEdgeWidth] @param {'linear'|'sqrt'} [options.edgeWidthScale]
+     *   Same shape as node sizing, for `edge.weight` → stroke width; only takes effect once some edge has a finite weight.
+     * @param {'arrow'|'circle'|'tee'|'diamond'|'diamond-hollow'|'triangle-hollow'|'open-arrow'|'crowsfoot-one'|'crowsfoot-one-optional'|'crowsfoot-many'|'crowsfoot-many-mandatory'|'none'} [edge.arrowhead='arrow']
+     *   Glyph at the target end. `edge.arrowheadStart` is the same set, independently, for the SOURCE end (e.g.
+     *   ArchiMate composition's filled diamond there while the target end carries none — see archimateDiagram;
+     *   the `crowsfoot-*` glyphs are ERD cardinality notation, see dataModelDiagram).
+     * @param {string} [edge.sourceLabel] @param {string} [edge.targetLabel] Independent text labels near each
+     *   end (e.g. a UML association's multiplicity, '0..1'/'1..*'/...) — distinct from the one midpoint
+     *   `edge.label` above (e.g. the relationship's own name); see dataModelDiagram's 'uml' notation.
+     * @param {'solid'|'dashed'|'dotted'} [edge.lineStyle] Generalizes the older boolean `edge.dashed` (still
+     *   honored when `lineStyle` is unset) — 'dotted' is the case neither the old flag nor its fixed pattern covered.
+     * @param {'straight'|'curved'|'orthogonal'|'polyline'} [options.edgeRouting='straight'] Default auto-routing
+     *   for edges that don't set their own `edge.routing`. `'straight'` is the original point-to-point line.
+     *   `'curved'` is a smooth bezier leaving/arriving along each end's own normal. `'orthogonal'` is a
+     *   right-angle (Manhattan) connector. `'polyline'` is a straight line that steps around one other node
+     *   with a single waypoint if it's directly in the way, otherwise it's the same as `'straight'`. An
+     *   individual edge can also carry `weight`/`color`/`label`/`dashed`/`arrowhead` (existing) plus
+     *   `routing` (overrides this default) and `sourceSide`/`targetSide` (`'top'|'right'|'bottom'|'left'`,
+     *   default `'auto'`) — a pinned side fixes *where on the node* the line attaches (it stays there as the
+     *   node moves) instead of always sliding around to face whatever it's connected to; force-directed
+     *   organic routing is what `graphDiagram`'s node layout already does by default (nodes/edges settle via
+     *   the same spring simulation) — see the class doc comment above for the tree-layout alternative.
+     *   When `editable`, any edge can also be hand-routed: right-click it and choose "Add Waypoint Here" to
+     *   drop a bend point where you clicked (`_insertEdgeWaypoint`/`_edgeWaypointsWithInsertion`), drag a bend
+     *   point to move it, double-click a bend point to remove it. That builds `edge.waypoints` (`[{x,y}, ...]`,
+     *   world/SVG coordinates) — set it directly to hand a route in instead, or read it back via
+     *   `onEdgeWaypointsChange(edge, waypoints)`. Waypoints beat every auto routing style outright, threading
+     *   the line through them in order.
+     * @param {boolean} [options.resizable=false] Diagram-wide default for whether a node shows a resize
+     *   handle on hover — an individual node's own `node.resizable` (true/false) overrides this default
+     *   either way. Dragging the handle sets `node.radius` (a hard override, beating `sizeBy`/domain
+     *   sizing the same way an explicit `node.x`/`node.y` already beats computed layout) or, for a
+     *   `shape:'table'` node, `node.width` — see `onNodeResize(node)`.
+     * @param {'top-left'|'top-right'|'bottom-left'|'bottom-right'} [options.resizeCorner='top-right']
+     *   Which corner the resize handle sits at, diagram-wide. `resizeCornerByShape: {shape: corner}`
+     *   overrides it per node shape, and a node's own `node.resizeCorner` overrides both.
+     * @param {boolean} [options.edgesOnTop=false] Draw lines over boxes rather than under them (ArchiMate
+     *   tools do: a line into an element drawn inside another stays visible). Selection handles stay on top.
+     * @param {'center'|'corner'} [options.iconPosition='center'] Where a node's `icon`/`iconUrl` (see the
+     *   nodes param above) sits — centred on the shape (replacing the initials) or a small badge at a corner
+     *   (`iconCorner`/`iconCornerByShape`/node's own `node.iconCorner` — same precedence as `resizeCorner`,
+     *   independently configurable). A node's own `node.iconPosition` overrides this default.
+     * @param {'below'|'inside'} [options.labelPosition='below'] `'below'` is the original caption-under-the-
+     *   shape convention; `'inside'` left-aligns the label inside the box instead — meant for a `shape:'rect'`
+     *   node with its own `width`/`height` (a non-square override, same idea as a table node's `node.width`).
+     *   A node's own `node.labelPosition` overrides this default. See `archimateDiagram`, which sets both.
+     * @param {Array<object>} [options.contextMenuItems] Replaces the built-in node right-click menu
+     *   (Pin/Unpin, Rename [editable only], Show Details, Hide, Delete). Each entry is either
+     *   `{separator: true}`, `{label, action(node, engine)}` (`label` may be a `label(node)`
+     *   function), or `{label, items: [...]}` for a hover pulldown/submenu of the same shape —
+     *   useful for a family of related actions (e.g. several layout choices) under one row.
+     * @param {Array<object>} [options.edgeContextMenuItems] Same shape, replacing the built-in edge
+     *   menu (Rename/Delete) — only shown when `editable` is true.
+     * @param {Array<object>} [options.canvasContextMenuItems] Same shape, replacing the built-in
+     *   canvas (empty-space) menu (Add Node). Unlike the edge menu, supplying this is enough on its
+     *   own to show a canvas-level menu even with `editable` left off — the built-in Add Node default
+     *   is genuinely an editing action so *that* stays editable-gated, but a caller providing their
+     *   own canvas items (e.g. re-arranging nodes — a view action, not an edit) clearly wants a menu
+     *   regardless. Every context-menu action — built-in or one of these — receives `(subject, engine,
+     *   point)`, `point` being the right-click location in SVG/world coordinates (`{x,y}`).
+     * @param {(node:object)=>void} [options.onNodeDoubleClick] Double-click on a node calls this instead of
+     *   doing anything else — nothing built-in happens on its own (no default dialog), so a caller wanting
+     *   "double-click to edit" wires this to open their own properties UI (see the Properties dialog in
+     *   `test/charts.html`, opened this way there).
+     * @param {(edge:object)=>void} [options.onEdgeDoubleClick] Same, for double-clicking an edge's line.
+     *   Double-clicking an existing waypoint handle still removes it regardless (a distinct, precise gesture
+     *   on a small routing control point, not "the edge" in general) — this fires for the line itself.
+     * @param {(point:{x:number,y:number})=>void} [options.onCanvasDoubleClick] Double-clicking empty canvas
+     *   (no node/edge/waypoint under the cursor) calls this with the click point in SVG/world coordinates —
+     *   e.g. to open a diagram/view-level settings dialog, since there's no single node/edge object to edit.
+     */    graphDiagram(nodes, edges, options = {}) {
+        const { folders = [], folderLayout = {}, elementFolders = [] } = options;
+
+        // Build element-to-folder Map for quick lookup
+        const elementFolderMap = new Map();
+        for (const [elementId, folderId] of elementFolders) {
+            elementFolderMap.set(elementId, folderId);
+        }
+
+        // Pass elementFolderMap in options for rendering
+        const optionsWithMap = { ...options, elementFolderMap };
+
+        this._chartState = { type: 'graph', nodes, edges, folders, options: optionsWithMap };
+        this._chart3D = false;
+        if (!this.renderer || !this.renderer.supportsSceneGraph) {
+            console.warn('Advanced graph diagram is only supported in SVG renderer.');
+            return;
+        }
+        this.renderer.clear();
+        const diagram = new GraphDiagram(this.renderer, nodes, edges, optionsWithMap, this, folders);
+        this._graphDiagram = diagram;
+        this._renderDiagram(diagram);
+    }
+
+    /**
+     * ArchiMate-notation diagram — a thin transform over graphDiagram(),
+     * *not* a separate renderer: it builds plain rect nodes/edges with
+     * ArchiMate's own visual rules and calls graphDiagram() with them, so
+     * every graphDiagram capability (drag, resize, routing, right-click
+     * menus, editable add/rename/delete, ...) applies to the result exactly
+     * as it would to any other graphDiagram.
+     *
+     * The actual notation data — layers, the official ~55-name element type
+     * catalog, the 11 relationship types' line/arrowhead notation — lives in
+     * `src/archimate.js` as real objects (ArchimateLayer/ArchimateElementType/
+     * ArchimateRelationshipType), queried through the `ArchimateNotation`
+     * registry (also `RenderEngine.ArchimateNotation`) rather than this
+     * class's own flat lookup tables; an element's TYPE carries a genuine
+     * reference to its LAYER object, not a name in one map and the same name
+     * in a second one that could drift apart — see `ArchimateNotation.
+     * typesInLayer(layer)` for the query that relationship supports directly
+     * (e.g. a "type" dropdown that must narrow to match a chosen "layer" —
+     * see the Properties/Add Element dialogs in test/charts.html).
+     *
+     * Matches Archi's (archimatetool.com) visual conventions structurally —
+     * per-layer pastel fill, the label inside the box, a small type-icon
+     * badge in a corner, official box corner shapes (chamfered/rounded/sharp
+     * by layer and aspect), and the 11 official relationship line/arrowhead
+     * notations (composition's filled diamond, aggregation's hollow diamond,
+     * realization/specialization's hollow triangle, serving/access/
+     * influence's open arrow, ...). Icons are representative glyphs echoing
+     * each official pictogram's own idea, not a redraw of the real vector
+     * artwork (ArchimateElementType#icon) — there's still no true per-type
+     * icon CATALOG the way, say, a UML tool's stencil palette would have one.
+     *
+     * @param {Array<{id, label, layer?, type?, aspect?, icon?, iconUrl?, x?, y?, width?, height?, color?, cornerStyle?}>} elements
+     *   `layer` picks the fill colour (extendable/overridable via `options.layerColors`); if omitted,
+     *   derived from `type` (_archimateElementLayer/ArchimateNotation.elementLayer) — first checking
+     *   whether `type` is one of the ~55 official ArchiMate element names (most of these do NOT start
+     *   with their own layer's name — e.g. `type:'goal'` implies `layer:'motivation'`, `type:'node'`
+     *   implies `layer:'technology'` — so a plain prefix guess alone would get them wrong), then falling
+     *   back to the prefix of `type` before its first '-' for anything not in that catalog (so a custom
+     *   `type:'business-my-widget'` still implies `layer:'business'` with no extra config — this works
+     *   for ANY '<layer>-whatever' string, official name or not); `element.layer`/`type` both missing
+     *   falls back to 'other' (neutral grey). An explicit `element.color` always wins over the derived
+     *   layer colour, same as plain graphDiagram. The resolved `layer` (explicit or derived) is always
+     *   written back onto the built node — so it's present and editable even for an element that only
+     *   ever set `type`, not `layer` itself. An element's own `icon`/`iconUrl` always wins for its corner
+     *   badge; otherwise an official `type`'s own representative icon is used, then just a generic
+     *   per-layer one — either can be overridden diagram-wide via `options.defaultIcons`.
+     *   **Box corner style** (`_archimateCornerStyle`, matching the official notation's own generic
+     *   shapes): every Motivation-layer element is chamfered (all 4 corners cut) regardless of anything
+     *   else; `'behavior'` aspect (Process/Function/Service/Event/Interaction-like elements) gets rounded
+     *   corners — an explicit `aspect` wins, else an official `type`'s own aspect (so `type:'business-
+     *   process'` is rounded with zero extra config, same "official name already knows" idea as layer);
+     *   everything else is sharp (correct for active/passive-structure elements, the common case). An
+     *   element's own `cornerStyle` (`'sharp'|'rounded'|'chamfered'`) overrides all of that directly.
+     * @param {Array<{source, target, kind?, label?}>} relationships
+     *   `kind` — one of composition/aggregation/assignment/realization/specialization/serving/
+     *   access/influence/triggering/flow/association (the 11 official ArchiMate relationship
+     *   types), or your own — picks the line style/arrowhead(s), extendable/overridable via
+     *   `options.relationshipStyles`; an explicit `lineStyle`/`dashed`/`arrowhead`/`arrowheadStart`
+     *   on any one relationship still overrides its kind's default, same as a plain graphDiagram
+     *   edge. An unrecognised/missing `kind` falls back to a plain solid association line rather
+     *   than being rejected.
+     * @param {object} [options] Everything graphDiagram accepts (editable, resizable, onNodeClick,
+     *   contextMenuItems, ...), plus:
+     * @param {object} [options.layerColors] Extra/overriding `layer -> color` entries.
+     * @param {object} [options.relationshipStyles] Extra/overriding `kind -> {lineStyle,arrowhead,arrowheadStart}` entries.
+     * @param {object} [options.defaultIcons] Extra/overriding `layer -> glyph` entries — wins even over an
+     *   official type's own icon (a deliberate diagram-wide override), used ONLY for an element that sets
+     *   neither `icon` nor `iconUrl` itself, so every element still shows some corner badge out of the box.
+     * @param {number} [options.elementWidth=120] @param {number} [options.elementHeight=55]
+     *   Default box size for an element that doesn't set its own `width`/`height`.
+     * @param {'3.2'|'4'} [options.archimateVersion='4'] Which ArchiMate version's element catalog/notation
+     *   applies (`ArchimateNotation.versions()`) — defaults to '4', the current standard. Under '4' (the
+     *   default), every element is first run through `ArchimateNotation.migrateElementToV4` (a no-op for
+     *   anything not one of the 19 retired/consolidated v3.2 types — see src/archimate.js's own doc
+     *   comment), so 3.2-authored data (e.g. `type:'business-process'`) still renders correctly, auto-
+     *   upgraded to its v4 equivalent (`type:'process'`) and tagged with its own migration provenance
+     *   (`ArchiMate4_Domain`/`MigratedFrom`, or `LegacyType`/`Type`+`MigratedFrom` for a retired type) —
+     *   both plain extra data, visible in the hover tooltip/Properties dialog like any other custom field.
+     *   Under '3.2', no migration happens and the element/relationship catalogs are the original ones.
+     * @param {boolean} [options.useDistinctShapes=false] Diagram-wide default for whether an element with a
+     *   real ArchiMate notation shape (`ArchimateElementType#notationShape` — arrow for Process, chevron for
+     *   Function, cylinder for Role, cube for Node, ... — cross-checked against the spec's own Appendix A;
+     *   not every type has one) renders as that shape instead of the plain box + corner icon — an individual
+     *   element's own `useDistinctShape` (true/false) overrides this default either way. A type with no
+     *   implemented notationShape always renders as the plain box regardless.
+     */
+    archimateDiagram(elements, relationships, options = {}) {
+        this._renderDiagram(new ArchimateDiagram(this.renderer, elements, relationships, options, this));
+    }
+
+    /**
+     * Live diagram-wide setting: which choice in each element type's own
+     * `iconChoices` (src/archimate.js — choice 0 is always the ArchiMate-
+     * standard glyph) is used as the DEFAULT icon for a node that doesn't
+     * carry its own explicit `icon`/`iconUrl` — see archimateDiagram's own
+     * `iconChoiceIndex` option, which only sets this once at build time.
+     * Changing it here re-derives the icon for every node that hasn't been
+     * individually customised (its current icon still matches what
+     * auto-derivation gave it under the OLD index — the same "was it ever
+     * customised" test the Properties dialog's own layer/type-change
+     * handler uses in test/charts.html), leaving any node whose icon was
+     * deliberately picked (via that dialog, or the original `elements` data)
+     * untouched. No-op if this isn't (or is no longer) an ArchiMate diagram.
+     */
+    _archimateSetIconChoiceIndex(newIndex) {
+        ArchimateDiagram.setIconChoiceIndex(this, newIndex);
+    }
+
+    /** Pure. Maps a raw column/attribute type string (any casing/precision,
+     *  e.g. 'VARCHAR(255)', 'bigint', 'TIMESTAMPTZ') to one of the `shape:
+     *  'table'` node's own colour-coded groups (see _buildTableNodeContent's
+     *  TYPE_COLORS) — 'UNKNOWN' (a neutral grey dot) for anything
+     *  unrecognised or unset, same fallback a real sqlengine-style table
+     *  node already uses for a column with no known type. */
+    _dataModelTypeGroup(type) {
+        return DataModelDiagram.typeGroup(type);
+    }
+
+    /**
+     * Pure. Builds one dataModelDiagram node from a raw `entity` at a given
+     * level/notation — reusable directly, the same "the diagram only
+     * enriches its own up-front input" reasoning as _archimateBuildNode/
+     * _archimateBuildEdge (see their own comments) applies here too, for a
+     * caller's own "add entity" UI. `entity.name`/`description` are shared
+     * across every level (the entity's own identity); `entity[level]`
+     * supplies that level's own `attributes` (and physical's own
+     * `tableName`) — an entity with none at the current level (typical for
+     * 'conceptual') always renders as a plain box, regardless of notation.
+     * @param {object} entity {id, name, description?, x?, y?, color?,
+     *   conceptual?, logical?, physical?}
+     * @param {{level: string, notation: NotationStyle}} opts
+     */
+    _dataModelBuildNode(entity, { level, notation }) {
+        return DataModelDiagram.buildNode(entity, { level, notation });
+    }
+
+    /**
+     * Pure. Builds one dataModelDiagram edge from a raw `relationship` —
+     * ONLY for a notation whose `relationshipAsNode` is false (Chen's "the
+     * relationship IS its own diamond node, with two plain edges instead of
+     * one" is handled directly in dataModelDiagram, since it touches both
+     * the nodes and edges arrays, not just one edge). `relationship.
+     * identifying === false` renders as a dashed line (a non-identifying
+     * relationship, in real ERD terms) — unset/true stays solid.
+     * @param {object} relationship {source, target, name?,
+     *   sourceCardinality?, targetCardinality?, identifying?}
+     * @param {NotationStyle} notation
+     */
+    _dataModelBuildEdge(relationship, notation) {
+        return DataModelDiagram.buildEdge(relationship, notation);
+    }
+
+    /**
+     * A conceptual/logical/physical data (entity-relationship) diagram — a
+     * thin transform over graphDiagram, the same idea as archimateDiagram:
+     * builds enriched nodes/edges, then calls graphDiagram with them. See
+     * src/datamodel.js's own doc comment for the full reasoning; in short:
+     *
+     * **Three levels, one model — the cross-mapping.** `options.level`
+     * (`'conceptual'|'logical'|'physical'`, default `'logical'`) picks which
+     * of each entity's own `entity.conceptual`/`.logical`/`.physical`
+     * sub-object supplies its attributes — `entity.name`/`.description` stay
+     * shared across all three (the same object/visual split archimateDiagram
+     * draws between an element and its diagram, just spanning "levels"
+     * instead of "diagrams"). Re-calling this with a different `level` over
+     * the SAME `entities`/`relationships` re-renders the same model at
+     * different fidelity, so a conceptual entity, its logical attributes,
+     * and its physical column types can never drift out of correspondence —
+     * there's only ever one model, never three separately-maintained
+     * diagrams.
+     *
+     * **Three notations.** `options.notation` (`'chen'|'crowsfoot'|'uml'`,
+     * default `'crowsfoot'`) — Chen renders each relationship as its own
+     * diamond-shaped node between two plain, text-labelled edges; Crow's
+     * Foot renders cardinality as an arrowhead-style glyph at each entity
+     * end; UML shows the cardinality (as a multiplicity string) as a text
+     * label near each end instead (`edge.sourceLabel`/`targetLabel`).
+     *
+     * @param {Array<object>} entities See _dataModelBuildNode.
+     * @param {Array<object>} relationships {source, target, name?,
+     *   sourceCardinality?, targetCardinality?, identifying?} — cardinality
+     *   is a UML multiplicity string (`DataModelNotation.cardinalities()`).
+     * @param {object} [options] Everything graphDiagram accepts, plus:
+     * @param {'conceptual'|'logical'|'physical'} [options.level='logical']
+     * @param {'chen'|'crowsfoot'|'uml'} [options.notation='crowsfoot']
+     */
+    dataModelDiagram(entities, relationships, options = {}) {
+        this._renderDiagram(new DataModelDiagram(this.renderer, entities, relationships, options, this));
+    }
+
+    /**
+     * A real 3D node-graph — nodes carry (or get simulated) x/y/z positions,
+     * viewed through the same orbit camera as bubbleChart3D (drag to rotate,
+     * scroll to zoom, double-click to reset — see _addOrbit3DListeners),
+     * projected via OrbitCamera/Mat4 rather than 2D graphDiagram()'s SVG
+     * viewBox pan/zoom. Nodes are simple point+label (matching bubbleChart3D's
+     * dot style) — there is no per-node dragging in 3D (only camera orbit);
+     * dragging a point in 2D screen space doesn't have a single obvious 3D
+     * interpretation, so it's deliberately out of scope here.
+     * @param {Array<{id:string, label?:string, x?:number, y?:number, z?:number, color?:string, group?:string, size?:number}>} nodes
+     * @param {Array<{source:string, target:string, color?:string, weight?:number}>} edges
+     * @param {object} [options]
+     * @param {(node:object)=>void} [options.onNodeClick]
+     * @param {number} [options.nodeRadius=8]
+     * @param {'degree'} [options.sizeBy] Size nodes by connection count instead of `node.size`.
+     * @param {number} [options.minRadius] @param {number} [options.maxRadius] @param {'linear'|'sqrt'} [options.sizeScale]
+     * @param {number} [options.minEdgeWidth] @param {number} [options.maxEdgeWidth] @param {'linear'|'sqrt'} [options.edgeWidthScale]
+     *   Edge thickness from `edge.weight`, same scaling shape as node sizing.
+     * @param {number} [options.initialTheta=-0.6] @param {number} [options.initialPhi=0.35] @param {number} [options.initialDistance=2.2]
+     */
+    graphDiagram3D(nodes, edges, options = {}) {
+        const { initialTheta = -0.6, initialPhi = 0.35, initialDistance = 2.2 } = options;
+        if (!this._camera3D) this._camera3D = { theta: initialTheta, phi: initialPhi, distance: initialDistance };
+        this._initialCamera3D = { theta: initialTheta, phi: initialPhi, distance: initialDistance };
+        this._chart3D = true;
+        this._chart3DRedraw = () => this.graphDiagram3D(nodes, edges, options);
+        this._renderDiagram(new GraphDiagram3D(this.renderer, nodes, edges, options, this._camera3D, this));
+    }
+
+    /** Pure. Resolves a node's display label — delegates to LabelHelper. */
+    _resolveNodeLabel(node) {
+        return LabelHelper.resolveNodeLabel(node);
+    }
+
+    /** Pure. Word-wraps label text — delegates to LabelHelper. */
+    _wrapLabelLines(text, maxWidth, fontSize, maxHeight, lineHeight) {
+        return LabelHelper.wrapLabelLines(text, maxWidth, fontSize, maxHeight, lineHeight);
+    }
+
+    /** Pure. "key: value" lines for caller-supplied extra data — delegates to
+     *  LabelHelper. */
+    _nodeExtraDataLines(node, knownKeys) {
+        return LabelHelper.nodeExtraDataLines(node, knownKeys);
+    }
+
+    /** Pure. Which ArchiMate layer an element belongs to — delegates to
+     *  ArchimateDiagram.elementLayer so the real logic lives with the diagram. */
+    _archimateElementLayer(element, version) {
+        return ArchimateDiagram.elementLayer(element, version);
+    }
+
+    /** Pure. Fill colour for an ArchiMate `layer` name — delegates to
+     *  ArchimateDiagram.layerColor. */
+    _archimateLayerColor(layer, layerColors, ownColor) {
+        return ArchimateDiagram.layerColor(layer, layerColors, ownColor);
+    }
+
+    /** Pure. Default corner-badge glyph for an ArchiMate element — delegates
+     *  to ArchimateDiagram.defaultIcon. */
+    _archimateDefaultIcon(element, layer, defaultIcons, iconChoiceIndex = 0, version) {
+        return ArchimateDiagram.defaultIcon(element, layer, defaultIcons, iconChoiceIndex, version);
+    }
+
+    /** Pure. `{lineStyle, arrowhead, arrowheadStart}` notation for a
+     *  relationship `kind` — delegates to ArchimateDiagram.relationshipStyle. */
+    _archimateRelationshipStyle(kind, relationshipStyles) {
+        return ArchimateDiagram.relationshipStyle(kind, relationshipStyles);
+    }
+
+    /** Builds one archimateDiagram node from a raw `element` — delegates to
+     *  ArchimateDiagram.buildNode so the diagram class owns the transform. */
+    _archimateBuildNode(element, options = {}) {
+        return ArchimateDiagram.buildNode(element, options);
+    }
+
+    /** Pure. Builds one archimateDiagram edge from a raw `relationship` —
+     *  delegates to ArchimateDiagram.buildEdge. */
+    _archimateBuildEdge(relationship, options = {}) {
+        return ArchimateDiagram.buildEdge(relationship, options);
+    }
+
+    /** Pure. Which corner style an ArchiMate `shape:'rect'` node renders —
+     *  delegates to ArchimateDiagram.cornerStyle. */
+    _archimateCornerStyle(element, layer, version) {
+        return ArchimateDiagram.cornerStyle(element, layer, version);
+    }
+
+    /** Pure. SVG path `d` for a chamfered rectangle — delegates to NodeGeometry. */
+    _chamferedRectPath(w, h, chamfer) {
+        return NodeGeometry.chamferedRectPath(w, h, chamfer);
+    }
+
+    /** Build the SVG element for a node's shape — delegates to NodeGeometry. */
+    _nodeShapeEl(shape, R, color, size, cornerStyle, strokeColor = '#fff', strokeWidth = 2, iconUrl = null, icon = null) {
+        return NodeGeometry.nodeShapeEl(this.renderer, shape, R, color, size, cornerStyle, strokeColor, strokeWidth, iconUrl, icon);
+    }
+
+    /** Bounding box a node occupies — delegates to NodeGeometry.nodeSize. */
+    _nodeSize(node, R, sizeDomain, sizeOptions) {
+        return NodeGeometry.nodeSize(node, R, sizeDomain, sizeOptions);
+    }
+
+    /** Pure. What a node's own size VALUE is, before it's mapped to a radius —
+     *  delegates to GraphMetrics.nodeSizeValue. */
+    _nodeSizeValue(node, sizeBy, degreeMap) {
+        return GraphMetrics.nodeSizeValue(node, sizeBy, degreeMap);
+    }
+
+    /** Pure — no DOM/renderer access. {min,max} of every node's size VALUE —
+     *  delegates to GraphMetrics.computeSizeDomain. */
+    _computeSizeDomain(nodes, { sizeBy, degreeMap } = {}) {
+        return GraphMetrics.computeSizeDomain(nodes, { sizeBy, degreeMap });
+    }
+
+    /** Pure. Maps a node's size value into [minRadius,maxRadius] — delegates to
+     *  GraphMetrics.effectiveNodeRadius. */
+    _effectiveNodeRadius(node, R, sizeDomain, sizeOptions = {}) {
+        return GraphMetrics.effectiveNodeRadius(node, R, sizeDomain, sizeOptions);
+    }
+
+    /** Pure. Corner point of a box — delegates to NodeGeometry.cornerPoint. */
+    _cornerPoint(pos, size, corner) {
+        return NodeGeometry.cornerPoint(pos, size, corner);
+    }
+
+    /** Pure. Generic 3-tier corner resolution — delegates to NodeGeometry. */
+    _resolveNodeCorner(node, nodeKey, byShape, defaultCorner) {
+        return NodeGeometry.resolveNodeCorner(node, nodeKey, byShape, defaultCorner);
+    }
+
+    /** Pure. Resize-handle corner — delegates to NodeGeometry.nodeResizeCorner. */
+    _nodeResizeCorner(node, resizeCornerByShape, defaultCorner = 'top-right') {
+        return NodeGeometry.nodeResizeCorner(node, resizeCornerByShape, defaultCorner);
+    }
+
+    /** Pure. Icon-badge corner — delegates to NodeGeometry.nodeIconCorner. */
+    _nodeIconCorner(node, iconCornerByShape, defaultCorner = 'top-right') {
+        return NodeGeometry.nodeIconCorner(node, iconCornerByShape, defaultCorner);
+    }
+
+    /** Pure. Resize-handle drag result — delegates to NodeGeometry.resizedNodeValue. */
+    _resizedNodeValue(node, corner, center, mousePos) {
+        return NodeGeometry.resizedNodeValue(node, corner, center, mousePos);
+    }
+
+    /** Pure — no DOM/renderer access. Map<nodeId, connectionCount> — delegates
+     *  to GraphMetrics.computeNodeDegrees. */
+    _computeNodeDegrees(nodes, edges) {
+        return GraphMetrics.computeNodeDegrees(nodes, edges);
+    }
+
+    /** Pure. {min,max} of edge.weight across all edges — delegates to
+     *  GraphMetrics.computeEdgeWidthDomain. */
+    _computeEdgeWidthDomain(edges) {
+        return GraphMetrics.computeEdgeWidthDomain(edges);
+    }
+
+    /** Pure. Maps edge.weight into [minEdgeWidth,maxEdgeWidth] — delegates to
+     *  GraphMetrics.effectiveEdgeWidth. */
+    _effectiveEdgeWidth(edge, defaultWidth, widthDomain, widthOptions = {}) {
+        return GraphMetrics.effectiveEdgeWidth(edge, defaultWidth, widthDomain, widthOptions);
+    }
+
+    /** Pure — no DOM/renderer access. Table-node size — delegates to NodeGeometry. */
+    _tableNodeSize(node) {
+        return NodeGeometry.tableNodeSize(node);
+    }
+
+    /** World-space Y of a named column's row within a table node — delegates to
+     *  NodeGeometry.tableColumnY. */
+    _tableColumnY(node, posEntry, size, colName) {
+        return NodeGeometry.tableColumnY(node, posEntry, size, colName);
+    }
+
+    // Edge geometry helpers — delegated to EdgeGeometry.
+    _edgeAnchor(pos, size, side, ux, uy, rectBoundary) {
+        return EdgeGeometry.edgeAnchor(pos, size, side, ux, uy, rectBoundary);
+    }
+    _edgeSideOrientation(side) {
+        return EdgeGeometry.edgeSideOrientation(side);
+    }
+    _curvedEdgePath(a1, a2) {
+        return EdgeGeometry.curvedEdgePath(a1, a2);
+    }
+    _orthogonalEdgePath(a1, a2, sourceSide, targetSide) {
+        return EdgeGeometry.orthogonalEdgePath(a1, a2, sourceSide, targetSide);
+    }
+    _segmentIntersectsCircle(a1, a2, circle) {
+        return EdgeGeometry.segmentIntersectsCircle(a1, a2, circle);
+    }
+    _polylineEdgePath(a1, a2, obstacles = []) {
+        return EdgeGeometry.polylineEdgePath(a1, a2, obstacles);
+    }
+    _nearestSegmentInsertIndex(points, x, y) {
+        return EdgeGeometry.nearestSegmentInsertIndex(points, x, y);
+    }
+    _edgeWaypointsWithInsertion(edge, sourcePos, targetPos, point) {
+        return EdgeGeometry.edgeWaypointsWithInsertion(edge, sourcePos, targetPos, point);
+    }
+    _pointToSegmentDist2(a, b, x, y) {
+        return EdgeGeometry.pointToSegmentDist2(a, b, x, y);
+    }
+    _computeEdgePath(sourceInfo, sourcePos, sourceSize, targetInfo, targetPos, targetSize, edge, defaultRouting = 'straight', obstacles = []) {
+        return EdgeGeometry.computeEdgePath(sourceInfo, sourcePos, sourceSize, targetInfo, targetPos, targetSize, edge, defaultRouting, obstacles);
+    }
+
+    /** Draws a table-card node's header + one row per column into wrapper `g`. */
+    _buildTableNodeContent(g, node) {
+        return NodeGeometry.buildTableNodeContent(this.renderer, g, node);
+    }
+
+    /**
+     * Re-render the current graph diagram, if one is active. Exposed as a
+     * convenience so consumer callbacks and demo dialogs can trigger a redraw
+     * without reaching into `engine._graphDiagram` directly.
+     *
+     * Consumer code (e.g. test/charts.html's add-note/add-image dialogs) updates
+     * `engine._chartState.nodes/edges/options` and then calls this method. The
+     * active GraphDiagram instance keeps its own `_chartState`, so we push the
+     * engine state into the diagram before re-rendering and pull the resulting
+     * state back out, keeping the two references in sync.
+     */
+    _rerenderGraph() {
+        if (!this._graphDiagram) return;
+        this._graphDiagram._chartState = this._chartState;
+        this._graphDiagram._rerenderGraph();
+        this._chartState = this._graphDiagram._chartState;
+    }
+
+    /**
+     * Generate a unique node id from a label, using the current graph diagram's
+     * node list (or the static helper if no diagram is active yet). Mirrors
+     * GraphDiagram._generateNodeId so add-note / add-image dialogs don't need
+     * to reach into `engine._graphDiagram`.
+     */
+    _generateNodeId(label) {
+        if (this._graphDiagram) return this._graphDiagram._generateNodeId(label);
+        return GraphDiagram.generateNodeId(label, (this._chartState?.nodes ?? []).map(n => n.id));
+    }
+
+    /**
+     * Renders a railroad diagram.
+     * @param {Diagram} diagram A diagram object from railroadDiagram.js
+     */
+    railroadDiagram(diagram) {
+        if (this.renderer) {
+            this.renderer.clear();
+            this.renderer.renderDiagram(diagram);
+        }
+    }
+
+    /**
+     * Renders an EBNF grammar rule as a railroad (syntax) diagram. Accepts
+     * either form:
+     * - a raw EBNF string (e.g. `"DOUBLE ::= [0-9]+ ('.' [0-9]*)?"`) —
+     *   parsed via `parseEbnf` (ebnfParser.js); the verbatim input text is
+     *   also drawn in a caption band under the diagram.
+     * - an already-parsed AST node — the bnfengine-shaped tree
+     *   (`{type:'Terminal'|'NonTerminal'|'Sequence'|'Choice'|'Optional'|
+     *   'Repetition'|'Group', ...}` — see ebnfDiagram.js's own header)
+     *   converted via `ebnfAstToDiagram` before delegating to
+     *   `railroadDiagram()`. No caption is drawn for this form — there's no
+     *   source text to show.
+     * @param {string|object} rule EBNF text, or a bnfengine-shaped AST node.
+     * @param {object} [options]
+     * @param {string} [options.captionBackground='#fdf6e3'] Caption band fill (text form only).
+     */
+    ebnfDiagram(rule, options = {}) {
+        if (!this.renderer) return;
+        this._renderDiagram(new EbnfDiagram(this.renderer, rule, options));
+    }
+
+    /**
+     * Performs a hit test at the given coordinates.
+     * @param {number} x The x-coordinate.
+     * @param {number} y The y-coordinate.
+     * @returns {object | null} The shape object that was hit, or null.
+     */
+    hitTest(x, y) {
+        const direct = this.renderer?.hitTest ? this.renderer.hitTest(x, y) : null;
+        if (direct) return direct;
+        // Pixel-exact SVG hitTest misses thin or angled edges. Fall back to a
+        // distance-based search over the active graph diagram's edge paths.
+        const svgPoint = this._clientToSvgPoint?.(x, y);
+        if (!svgPoint || !this._graphDiagram) return null;
+        const tolerance = this._chartState?.options?.edgeHitTolerance ?? 14;
+        const edge = this._graphDiagram.findNearestEdge(svgPoint.x, svgPoint.y, tolerance);
+        return edge ? { isEdge: true, edge } : null;
+    }
+
+    /**
+     * Live-filter the current graph diagram by keyword. Nodes whose label or
+     * extra data does not match are hidden; edges touching hidden nodes are
+     * hidden too. In hierarchical mode ancestors of a match stay visible.
+     * Pass an empty string to clear the filter.
+     * @param {string} keyword
+     */
+    filterGraphNodes(keyword) {
+        this._graphDiagram?.filterGraphNodes?.(keyword);
+    }
+
+    /** Screen (clientX/clientY) → SVG user-space coordinates, honoring the
+     *  current pan/zoom viewBox (_addZoomListeners). Shared by drag,
+     *  add-node, and edge-creation — all of which need a graph-space point,
+     *  not a raw screen pixel. */
+    _clientToSvgPoint(clientX, clientY) {
+        return SvgCoordinate.clientToSvgPoint(this.renderer?.svg, clientX, clientY);
+    }
+
+    /**
+     * Applies a named state to a shape.
+     * @param {object} shape The shape object to apply the state to.
+     * @param {string} stateName The name of the state (e.g., 'hover').
+     */
+    enterState(shape, stateName) {
+        if (this.renderer?.enterState) {
+            this.renderer.enterState(shape, stateName);
+        }
+    }
+
+    /**
+     * Removes a named state from a shape.
+     * @param {object} shape The shape object to remove the state from.
+     * @param {string} stateName The name of the state (e.g., 'hover').
+     */
+    leaveState(shape, stateName) {
+        if (this.renderer?.leaveState) {
+            this.renderer.leaveState(shape, stateName);
+        }
+    }
+
+    // ──────────────────────────────────────────────────────────────────────────────
+    // SVGEngine Compatibility Methods & Utilities
+    // ──────────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Resolves a dot-notation path in the global data object.
+     * Compatible with SVGEngine's _resolvePath pattern.
+     * @param {string} path Dot-notation path (e.g., 'user.name', 'data.items.0.value')
+     * @param {Function} [mapper] Optional function to transform the resolved value
+     * @returns {*} The resolved value or undefined
+     */
+    resolvePath(path, mapper, globalData = this.globalData) {
+        if (!path) return undefined;
+        let val = path.split('.').reduce((p, c) => {
+            if (p && typeof p === 'object' && c in p) {
+                return p[c];
+            } else if (Array.isArray(p) && !isNaN(c)) {
+                return p[parseInt(c, 10)];
+            }
+            return undefined;
+        }, globalData);
+        return (mapper && val !== undefined) ? mapper(val, globalData) : val;
+    }
+
+    /**
+     * Sets global data that can be referenced in chart options via paths.
+     * @param {object} data The global data object
+     */
+    setGlobalData(data) {
+        this.globalData = data;
+    }
+
+    /**
+     * Generates nice round tick values for axis labels.
+     * Ensures readable, evenly-spaced values on axes.
+     * @param {number} maxVal The maximum value
+     * @param {number} [count=4] Desired number of ticks
+     * @returns {number[]} Array of tick values
+     */
+    niceTicks(maxVal, count = 4) {
+        return Axis.niceTicks(maxVal, count);
+    }
+
+    /**
+     * Formats a value for display with appropriate units (M, k, etc.).
+     * @param {number} v The value to format
+     * @returns {string} Formatted value string
+     */
+    formatValue(v) {
+        return Axis.formatValue(v);
+    }
+
+    /**
+     * Draws numeric y-axis tick marks + value labels (via niceTicks/
+     * formatValue) along the left edge of a cartesian plot area, plus a
+     * light horizontal gridline per tick. Shared by every chart method with
+     * a numeric, zero-based y-axis — call it once, before drawing the
+     * chart's own marks, so gridlines sit behind them.
+     *
+     * niceTicks rounds its top tick UP past the raw data max (e.g. a max
+     * value of 82 becomes a top tick of 100) — so this returns that
+     * "nice" max rather than the raw one passed in, and the caller MUST
+     * scale its own marks (bar heights, line points, ...) against the
+     * returned value, not the raw max, or the tallest mark won't reach the
+     * axis's own top tick.
+     * @param {number} x Left edge of the plot area (data-space origin).
+     * @param {number} y Top edge of the plot area.
+     * @param {number} width Plot area width.
+     * @param {number} height Plot area height.
+     * @param {number} rawMax The raw (un-rounded) data maximum.
+     * @returns {number} The "nice" domain max the drawn ticks actually span.
+     */
+    _drawYAxisTicks(x, y, width, height, rawMax) {
+        return new Axis().drawYAxis(this.renderer, { x, y, width, height }, rawMax);
+    }
+
+    /**
+     * Binds a tooltip to an element (for Canvas context).
+     * Can be extended for use with interactive features.
+     * @param {object} element The element or shape to bind tooltip to
+     * @param {string} text The tooltip text
+     */
+    bindTooltip(element, text) {
+        if (!text || !element) return;
+        if (element.tooltip) {
+            element.tooltip = text;
+        } else if (element.setAttribute && typeof element.setAttribute === 'function') {
+            element.setAttribute('title', text);
+        }
+    }
+
+    /**
+     * Binds a rich tooltip with multiple rows to an element.
+     * @param {object} element The element to bind tooltip to
+     * @param {object} data Object with { title, rows: [{k, v}] }
+     */
+    bindRichTooltip(element, data) {
+        if (!data || !element) return;
+        const { title, rows = [] } = data;
+        const text = `${title}\n${rows.map(r => `${r.k}: ${r.v}`).join('\n')}`;
+        this.bindTooltip(element, text);
+    }
+
+    /**
+     * Lightens or darkens a color by a factor for shading effects.
+     * Used internally for 3D effects.
+     * @param {string} color Hex color string
+     * @param {number} amount Amount to lighten (-1 to 1)
+     * @returns {string} Modified hex color
+     */
+    adjustColor(color, amount) {
+        return this._lightenColor(color, amount);
+    }
+
+    /**
+     * Registers a chart or diagram type for lazy rendering.
+     * Compatible with SVGEngine's registry pattern. For a graph type
+     * (`graphDiagram`/`graphDiagram3D`), pass `{nodes, edges, ...}` in
+     * `options` instead of `{data}` — `refreshChart`/`addGraphNode` detect
+     * the graph shape via `options.nodes`.
+     * @param {string} id Chart container ID
+     * @param {string} type A CHART_CATALOG key (e.g. 'bar', 'line'), a
+     *   DIAGRAM_CATALOG key (e.g. 'graph', 'archimate'), or — for
+     *   railroadDiagram, which isn't a registry entry — the real method name.
+     * @param {object} [options] Chart/diagram options
+     */
+    register(id, type, options = {}) {
+        if (!this.registry) this.registry = {};
+        this.registry[id] = { type, options };
+    }
+
+    /**
+     * Refreshes a registered chart, re-resolving its data and re-invoking
+     * its render method.
+     * @param {string} id Chart container ID
+     */
+    refreshChart(id) {
+        if (!this.registry || !this.registry[id]) return;
+        const config = this.registry[id];
+        const container = document.getElementById(id);
+        if (!container) return;
+
+        // Catalog keys ('bar', 'heatmap', 'graph', 'archimate', ...) resolve
+        // through the registries to their real method name; railroadDiagram
+        // isn't a registry entry, so `type` already IS the method name there.
+        const chartEntry = RenderEngine.CHART_REGISTRY.get(config.type);
+        const diagramEntry = RenderEngine.DIAGRAM_REGISTRY.get(config.type);
+        const methodName = chartEntry?.method ?? diagramEntry?.method ?? config.type;
+        if (typeof this[methodName] !== 'function') return;
+
+        if (config.options.nodes !== undefined) {
+            // Graph-shaped registration: two positional data args, not one.
+            this[methodName](config.options.nodes, config.options.edges || [], config.options);
+        } else {
+            const data = config.options.data || this.resolvePath(config.options.dataPath, config.options.dataMapper);
+            this[methodName](data, config.options);
+        }
+    }
+
+    /**
+     * Appends one data point to a registered chart's data and re-renders it,
+     * keeping at most `maxPoints` (oldest dropped first) — see
+     * REFERENCE.md's "Dynamically adding data points in a bounded window".
+     * Delegates the actual shape-aware append/trim to a `datawindow/`
+     * class, selected via the chart's `CHART_CATALOG` `streamShape`; the
+     * window instance is cached per `id` so repeated calls keep growing the
+     * same bounded collection instead of re-deriving it from scratch.
+     * @param {string} id A container id already passed to `register()`.
+     * @param {*|function} pointOrFactory A literal point, or a factory (see
+     *   the `datawindow/` classes for the exact signature each streamShape
+     *   calls it with).
+     * @param {{maxPoints?: number}} [options] `0` (default) = unbounded.
+     */
+    addDataPoint(id, pointOrFactory, { maxPoints = 0 } = {}) {
+        const config = this.registry?.[id];
+        const entry = config && RenderEngine.CHART_REGISTRY.get(config.type);
+        if (!entry || entry.streamShape === 'none') return; // not registered, or a fixed-shape type (heatmap/radar/gauges/3D-orbit grids)
+
+        this._windows = this._windows || {};
+        if (!this._windows[id]) {
+            const current = config.options.data || this.resolvePath(config.options.dataPath, config.options.dataMapper);
+            this._windows[id] = createDataWindow(entry.streamShape, current, { max: maxPoints });
+        }
+        this._windows[id].max = maxPoints; // let the cap change between calls, e.g. a live-editable "Max points" field
+        config.options.data = this._windows[id].push(pointOrFactory);
+        this.refreshChart(id);
+    }
+
+    /**
+     * Appends one node (and its edges) to a registered graph diagram and
+     * re-renders it, keeping at most `maxNodes` — oldest nodes dropped
+     * first, along with any edge left dangling off a removed node. See
+     * `GraphDataWindow` (src/datawindow/GraphDataWindow.js).
+     * @param {string} id A container id already `register()`ed with
+     *   `{nodes, edges}` in its options.
+     * @param {object} node The new node, e.g. `{id, label}`.
+     * @param {Array<object>} [newEdges] Edges connecting the new node, e.g. `[{source, target}]`.
+     * @param {{maxNodes?: number}} [options] `0` (default) = unbounded.
+     */
+    addGraphNode(id, node, newEdges = [], { maxNodes = 0 } = {}) {
+        const config = this.registry?.[id];
+        if (!config || config.options.nodes === undefined) return; // not registered, or not registered graph-shaped
+
+        this._windows = this._windows || {};
+        if (!this._windows[id]) {
+            this._windows[id] = new GraphDataWindow({ nodes: config.options.nodes, edges: config.options.edges || [] }, { max: maxNodes });
+        }
+        this._windows[id].max = maxNodes;
+        this._windows[id].push(node, newEdges);
+        config.options.nodes = this._windows[id].nodes;
+        config.options.edges = this._windows[id].edges;
+        this.refreshChart(id);
+    }
+}