@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/chartCatalog.js

@@ -0,0 +1,589 @@
+// Copyright 2026 Jaroslav Peter Prib, Purveyor of Excellence
+/**
+ * Single source of truth for "what chart types does RenderEngine support" —
+ * see ARCHITECTURE.md's "Chart-type catalog" section for the full story.
+ *
+ * This is not just a flat {key,label} list. Chart types share real,
+ * composable capabilities — every one of them takes a title; several accept
+ * a legend; several take a customizable color palette while others take a
+ * fixed semantic pair (up/down) or a single color; every one has at least
+ * one data-driving "axis," but an axis isn't always a spatial position —
+ * bubbleChart's `size` is a driving value encoded as a property of the
+ * marker object itself (its radius), not a position, and bubbleChart's
+ * `colorCol` similarly encodes a *group* as the marker's color rather than
+ * a spatial dimension. This file models each chart type as the specific
+ * JOINT combination of these reusable pieces (`axes`, `coordSystem`,
+ * `legend`, `colorMode`, `camera`) it supports, extracted empirically from
+ * every method's real `options` destructure (not aspirational/guessed) —
+ * see git history for the audit this came from.
+ */
+
+// ── Vocabulary — the reusable pieces every chart type composes from ────────
+
+/** What kind of value a given axis role expects. */
+export const AXIS_KIND = {
+  CATEGORICAL:  'categorical',   // a label/group string
+  NUMERIC:      'numeric',       // a single number
+  NUMERIC_LIST: 'numeric-list',  // an array of numbers (one chart glyph, several values — e.g. a stacked bar's segments)
+  RAW_SAMPLE:   'raw-sample',    // a raw numeric array the chart itself aggregates (histogram bins it, boxPlot computes quartiles) — not pre-aggregated by the caller
+};
+
+/**
+ * WHERE an axis role's value actually shows up visually. Most are a literal
+ * screen position (`position-*`); the rest are "axis within object" —
+ * exactly the bubble/size case: the value drives a property of the marker
+ * shape itself (its size, its width, its color, its depth) rather than
+ * where it sits on the chart. A future "sphere/ellipsoid" bubble variant
+ * with two independent radii is still just two roles both channeled through
+ * `shape-size` — the schema doesn't need to change to describe it, only the
+ * catalog entry gains a second `shape-size` role.
+ */
+export const ENCODING_CHANNEL = {
+  POSITION_X:        'position-x',
+  POSITION_Y:         'position-y',
+  POSITION_Z:         'position-z',
+  POSITION_Y_LENGTH:   'position-y-length',   // bar height from a zero baseline
+  POSITION_Y_STACKED:  'position-y-stacked',  // bar height, one of several segments stacked from a zero baseline
+  POSITION_Y_HEIGHT:   'position-y-height',   // orbit-3D bar height
+  POSITION_Y_DELTA:    'position-y-delta',    // waterfall's floating delta bar
+  POSITION_ORDER:      'position-order',      // funnel/boxPlot-group: sequence matters, not a numeric coordinate
+  RADIAL_AXIS:         'radial-axis',         // radar: one of N shared spokes
+  RADIAL_DISTANCE:      'radial-distance',    // radar: distance out along its axis
+  ANGLE_OR_AREA:        'angle-or-area',      // pie/doughnut slice
+  SHAPE_SIZE:            'shape-size',        // bubble radius — "axis within object"
+  SHAPE_WIDTH:            'shape-width',      // pipe line-width / funnel band width — "axis within object"
+  SHAPE_DEPTH:             'shape-depth',     // barChart3D's isometric depth shadow — "axis within object"
+  SHAPE_GLYPH:              'shape-glyph',    // candlestick's whole open/high/low/close body+wick is one compound glyph
+  COLOR:                    'color',          // a category mapped to marker/point color — "axis within object"
+  COLOR_SCALE:               'color-scale',   // a continuous value mapped along a color gradient (heatmap)
+  SEMANTIC_COLOR:             'semantic-color', // a fixed meaning (up/down/total), not an arbitrary palette index
+  FILL_PERCENT:                'fill-percent', // gauge's single 0-100 fill
+  DERIVED:                      'derived',    // histogram/boxPlot: the chart computes the real visual encoding internally from a raw sample
+  TEXT_VALUE:                    'text-value', // outlineChart's row count — shown as literal text, not any geometric/color property (a genuinely new "where" — every other channel above drives position/size/color, this one drives displayed text)
+};
+
+/** The coordinate system a chart type's `x/y/width/height` (or `cx/cy/r`, or none) options address. */
+export const COORD_SYSTEM = {
+  CARTESIAN: 'cartesian',  // {x,y,width,height} box
+  RADIAL:    'radial',     // {cx,cy,radius} or {cx,cy,r} — pie, radar, dialGauge
+  ORBIT_3D:  'orbit-3d',   // no 2D box at all — a real camera (theta/phi/distance) owns the space
+};
+
+/** How a chart type accepts color customization — these are genuinely different contracts, not degrees of the same one. */
+export const COLOR_MODE = {
+  PALETTE:       'palette',       // string[] indexed by series/category/segment
+  SCALE:         'scale',         // low→high gradient stops (heatmap's colorScale)
+  SEMANTIC:      'semantic',      // fixed-meaning named colors (candlestick's upColor/downColor, waterfall's +totalColor)
+  SINGLE:        'single',        // one color, no per-item variation
+  GROUPED_FIELD: 'grouped-field', // colorCol — an actual data column drives color per-point (a group "axis within object"; also has a matching ENCODING_CHANNEL.COLOR axis role)
+  NONE:          'none',          // no color option at all
+};
+
+/** Whether/how a chart type does 3D — these are two unrelated implementations, not degrees of the same feature. */
+export const CAMERA_MODE = {
+  NONE:      'none',
+  ISOMETRIC: 'isometric', // fixed-angle depth shadow, still 2D mouse interaction (barChart3D, bubbleChart({zAxis:true}))
+  ORBIT:     'orbit',     // real Mat4/OrbitCamera — drag-to-rotate, wheel-to-zoom (bubbleChart3D, bar/stackedBarChart3DOrbit)
+};
+
+// ── The catalog ──────────────────────────────────────────────────────────
+
+export const CHART_CATALOG = [
+  {
+    key: 'bar', label: 'Bar', method: 'barChart', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: true, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'category', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_X, required: true },
+      { role: 'value',    kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.POSITION_Y_LENGTH, required: true },
+    ],
+    dataShape: 'Array<{label, value}>',
+    streamShape: 'flat',
+  },
+  {
+    key: 'groupedBar', label: 'Grouped Bar', method: 'groupedBarChart', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: true, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    seriesCapable: true,
+    axes: [
+      { role: 'category', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_X, required: true },
+      { role: 'value',    kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.POSITION_Y_LENGTH, required: true },
+      { role: 'series',   kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.COLOR, required: true },
+    ],
+    dataShape: 'Multi-series Array<{name, values:Array<{label,value}>}>',
+    streamShape: 'series',
+  },
+  {
+    key: 'line', label: 'Line', method: 'lineChart', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: true, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.ISOMETRIC,
+    seriesCapable: true,
+    axes: [
+      { role: 'category', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_X, required: true },
+      { role: 'value',    kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.POSITION_Y, required: true },
+    ],
+    dataShape: 'Array<{label, value}> or multi-series Array<{name, values:Array<{label,value}>}> — {zAxis:true} adds an isometric depth shadow per series',
+    streamShape: 'series',
+  },
+  {
+    key: 'pie', label: 'Pie / Doughnut', method: 'pieChart', category: '2d',
+    coordSystem: COORD_SYSTEM.RADIAL, title: true, legend: true, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'category', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.ANGLE_OR_AREA, required: true },
+      { role: 'value',    kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.ANGLE_OR_AREA, required: true },
+    ],
+    dataShape: 'Array<{label, value}> — innerRadiusRatio>0 makes it a doughnut, same method/data',
+    streamShape: 'flat',
+  },
+  {
+    key: 'donut', label: 'Donut', method: 'donutChart', category: '2d',
+    coordSystem: COORD_SYSTEM.RADIAL, title: true, legend: true, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'category', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.ANGLE_OR_AREA, required: true },
+      { role: 'value',    kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.ANGLE_OR_AREA, required: true },
+    ],
+    dataShape: 'Array<{label, value}> — donutChart is pieChart with a default innerRadiusRatio of 0.5',
+    streamShape: 'flat',
+  },
+  {
+    key: 'area', label: 'Area', method: 'areaChart', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: true, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    seriesCapable: true,
+    axes: [
+      { role: 'category', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_X, required: true },
+      { role: 'value',    kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.POSITION_Y, required: true },
+    ],
+    dataShape: 'Array<{label, value}> or multi-series (same shape as line) — {stacked:true} bands each series atop the previous',
+    streamShape: 'series',
+  },
+  {
+    key: 'stackedArea', label: 'Stacked Area', method: 'stackedAreaChart', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: true, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    seriesCapable: true,
+    axes: [
+      { role: 'category', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_X, required: true },
+      { role: 'value',    kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.POSITION_Y, required: true },
+    ],
+    dataShape: 'Multi-series Array<{name, values:Array<{label,value}>}> — each series banded atop the previous',
+    streamShape: 'series',
+  },
+  {
+    key: 'scatter', label: 'Scatter', method: 'scatterChart', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.GROUPED_FIELD, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'x',     kind: AXIS_KIND.NUMERIC,     channel: ENCODING_CHANNEL.POSITION_X, required: true },
+      { role: 'y',     kind: AXIS_KIND.NUMERIC,     channel: ENCODING_CHANNEL.POSITION_Y, required: true },
+      { role: 'group', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.COLOR,       required: false },
+    ],
+    dataShape: 'Array<{label, x, y}> — plain x/y points at a fixed marker radius; `colorCol` names a field to color-group by (same convention as bubbleChart, minus its required size axis)',
+    streamShape: 'flat',
+  },
+  {
+    key: 'bubble', label: 'Bubble', method: 'bubbleChart', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.GROUPED_FIELD, camera: CAMERA_MODE.ISOMETRIC,
+    axes: [
+      { role: 'x',     kind: AXIS_KIND.NUMERIC,     channel: ENCODING_CHANNEL.POSITION_X, required: true },
+      { role: 'y',     kind: AXIS_KIND.NUMERIC,     channel: ENCODING_CHANNEL.POSITION_Y, required: true },
+      { role: 'size',  kind: AXIS_KIND.NUMERIC,     channel: ENCODING_CHANNEL.SHAPE_SIZE,  required: false },
+      { role: 'group', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.COLOR,       required: false },
+    ],
+    dataShape: 'Array<{label, x, y, z}> — z drives bubble size; `colorCol` names a field to color-group by; {zAxis:true} adds an isometric depth shadow',
+    streamShape: 'flat',
+  },
+  {
+    key: 'heatmap', label: 'Heatmap', method: 'heatmap', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.SCALE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'x',     kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_X,   required: true },
+      { role: 'y',     kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_Y,   required: true },
+      { role: 'value', kind: AXIS_KIND.NUMERIC,     channel: ENCODING_CHANNEL.COLOR_SCALE,  required: true },
+    ],
+    dataShape: 'Array<{x, y, value}> — two category axes shaded by value',
+    streamShape: 'none', // fixed x/y category matrix — "add one point" isn't meaningful
+  },
+  {
+    key: 'calendarHeatmap', label: 'Calendar Heatmap', method: 'calendarHeatmap', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.SCALE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'date',  kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_X,   required: true },
+      { role: 'weekday', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_Y, required: true },
+      { role: 'value', kind: AXIS_KIND.NUMERIC,     channel: ENCODING_CHANNEL.COLOR_SCALE,  required: true },
+    ],
+    dataShape: 'Array<{date: string|Date, value: number}> — one row per calendar day, shaded by value; empty days use emptyColor',
+    streamShape: 'none',
+  },
+  {
+    key: 'gantt', label: 'Gantt', method: 'ganttChart', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'time',  kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.POSITION_X,   required: true },
+      { role: 'task',  kind: AXIS_KIND.CATEGORICAL,  channel: ENCODING_CHANNEL.POSITION_ORDER, required: true },
+      { role: 'progress', kind: AXIS_KIND.NUMERIC,   channel: ENCODING_CHANNEL.FILL_PERCENT, required: false },
+    ],
+    dataShape: 'Array<{label, start, end, progress?, category?, color?}> — start/end are Dates, ISO strings, or numbers; progress is 0-100',
+    streamShape: 'flat',
+  },
+  {
+    key: 'streamGraph', label: 'Stream Graph', method: 'streamGraph', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: true, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    seriesCapable: true,
+    axes: [
+      { role: 'time',  kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_X,   required: true },
+      { role: 'value', kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.POSITION_Y,   required: true },
+      { role: 'series', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.COLOR,        required: true },
+    ],
+    dataShape: 'Multi-series Array<{name, values:Array<{label,value}>}> — stacked areas with a centered (silhouette) baseline',
+    streamShape: 'series',
+  },
+  {
+    key: 'radialBar', label: 'Radial Bar', method: 'radialBarChart', category: '2d',
+    coordSystem: COORD_SYSTEM.RADIAL, title: true, legend: true, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'category', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.RADIAL_AXIS,     required: true },
+      { role: 'value',    kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.RADIAL_DISTANCE, required: true },
+    ],
+    dataShape: 'Array<{label, value}> — angular categories with radial bar length',
+    streamShape: 'flat',
+  },
+  {
+    key: 'populationPyramid', label: 'Population Pyramid', method: 'populationPyramid', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.SEMANTIC, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'category', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_ORDER, required: true },
+      { role: 'left',    kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.POSITION_X,     required: true },
+      { role: 'right',   kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.POSITION_X,     required: true },
+    ],
+    dataShape: 'Array<{label, left, right}> — back-to-back horizontal bars (commonly age groups by sex)',
+    streamShape: 'flat',
+  },
+  {
+    key: 'sankey', label: 'Sankey Diagram', method: 'sankeyDiagram', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'source', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_X, required: true },
+      { role: 'target', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_X, required: true },
+      { role: 'value',  kind: AXIS_KIND.NUMERIC,     channel: ENCODING_CHANNEL.SHAPE_WIDTH,  required: true },
+    ],
+    dataShape: '{nodes?: Array<{id,label?,color?}>, links: Array<{source,target,value}>} — proportional-width flow links between nodes',
+    streamShape: 'none',
+  },
+  {
+    key: 'chord', label: 'Chord Diagram', method: 'chordDiagram', category: '2d',
+    coordSystem: COORD_SYSTEM.RADIAL, title: true, legend: false, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'source', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.RADIAL_AXIS,     required: true },
+      { role: 'target', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.RADIAL_AXIS,     required: true },
+      { role: 'value',  kind: AXIS_KIND.NUMERIC,     channel: ENCODING_CHANNEL.SHAPE_WIDTH,    required: true },
+    ],
+    dataShape: '{nodes?: Array<{id,label?,color?}>, links: Array<{source,target,value}>} — nodes on a circle with curved chords of proportional thickness',
+    streamShape: 'none',
+  },
+  {
+    key: 'wordCloud', label: 'Word Cloud', method: 'wordCloud', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'text',  kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.TEXT_VALUE, required: true },
+      { role: 'value', kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.SHAPE_SIZE,  required: true },
+    ],
+    dataShape: 'Array<{text: string, value: number}> — words sized by value, laid out with spiral placement and bounding-box collision avoidance',
+    streamShape: 'flat',
+  },
+  {
+    key: 'parallelCoordinates', label: 'Parallel Coordinates', method: 'parallelCoordinates', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: true, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'dimension', kind: AXIS_KIND.NUMERIC, channel: ENCODING_CHANNEL.POSITION_Y, required: true, repeats: true },
+      { role: 'category',  kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.COLOR, required: false },
+    ],
+    dataShape: 'Array<{label?, category?, [dim: number]}> — one vertical axis per numeric dimension; each row is a polyline; category drives color',
+    streamShape: 'flat',
+  },
+  {
+    key: 'geoMap', label: 'Geospatial Map', method: 'geoMap', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.SCALE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'longitude', kind: AXIS_KIND.NUMERIC, channel: ENCODING_CHANNEL.POSITION_X, required: true },
+      { role: 'latitude',  kind: AXIS_KIND.NUMERIC, channel: ENCODING_CHANNEL.POSITION_Y, required: true },
+      { role: 'value',     kind: AXIS_KIND.NUMERIC, channel: ENCODING_CHANNEL.COLOR_SCALE, required: false },
+    ],
+    dataShape: '{features: Array<{id, name, value?, color?, geometry:{type, coordinates}}>, bubbles?: Array<{lat, lon, value}>} — equirectangular-projection choropleth and bubble map; no external geo library',
+    streamShape: 'none',
+  },
+  {
+    key: 'candlestick', label: 'Candlestick / OHLC', method: 'candlestick', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.SEMANTIC, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'time', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_X,   required: true },
+      { role: 'ohlc', kind: AXIS_KIND.NUMERIC_LIST, channel: ENCODING_CHANNEL.SHAPE_GLYPH, required: true, fields: ['open', 'high', 'low', 'close'] },
+    ],
+    dataShape: 'Array<{label, open, high, low, close}> — optional `markers` overlay point-in-time tooltip annotations',
+    streamShape: 'flat',
+  },
+  {
+    key: 'stackedBar', label: 'Stacked Bar', method: 'stackedBarChart', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'category', kind: AXIS_KIND.CATEGORICAL,  channel: ENCODING_CHANNEL.POSITION_X,        required: true },
+      { role: 'values',   kind: AXIS_KIND.NUMERIC_LIST, channel: ENCODING_CHANNEL.POSITION_Y_STACKED, required: true },
+    ],
+    dataShape: "Array<{label, values:number[]}> e.g. [{label:'Jan', values:[10,20]}] — no built-in legend option despite being multi-series (a real gap; areaChart's stacked mode has one, this doesn't)",
+    streamShape: 'flat', // a new stacked bar is a whole new {label,values} record appended to the outer array, not growth of an existing record's values
+  },
+  {
+    key: 'pipe', label: 'Pipe', method: 'pipeChart', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: true, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    seriesCapable: true,
+    axes: [
+      { role: 'category', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_X, required: true },
+      { role: 'value',    kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.POSITION_Y, required: true },
+      { role: 'width',    kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.SHAPE_WIDTH, required: false },
+    ],
+    dataShape: 'Array<{label, value, metric?}> or multi-series — metric drives tapering line width ("axis within object", same idea as bubble size)',
+    streamShape: 'series',
+  },
+  {
+    key: 'radar', label: 'Radar / Spider', method: 'radarChart', category: '2d',
+    coordSystem: COORD_SYSTEM.RADIAL, title: true, legend: true, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    seriesCapable: true,
+    axes: [
+      { role: 'axis',  kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.RADIAL_AXIS,     required: true, repeats: true },
+      { role: 'value', kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.RADIAL_DISTANCE, required: true },
+    ],
+    dataShape: 'Array<{axis, value}> or multi-series Array<{name, values:Array<{axis,value}>}> — each axis scaled independently by its own max',
+    streamShape: 'none', // fixed radial axis set — "add one point" would mean adding a new axis to every series at once, not a single value
+  },
+  {
+    key: 'funnel', label: 'Funnel', method: 'funnelChart', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'stage', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_ORDER, required: true },
+      { role: 'value', kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.SHAPE_WIDTH,    required: true },
+    ],
+    dataShape: 'Array<{label, value}> ordered largest-first by convention',
+    streamShape: 'flat',
+  },
+  {
+    key: 'waterfall', label: 'Waterfall', method: 'waterfallChart', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.SEMANTIC, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'label', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_X,     required: true },
+      { role: 'value', kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.POSITION_Y_DELTA, required: true },
+      { role: 'type',  kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.SEMANTIC_COLOR, required: false, values: ['delta', 'total'] },
+    ],
+    dataShape: "Array<{label, value, type?:'delta'|'total'}> — 'total' entries draw full-height checkpoints",
+    streamShape: 'flat',
+  },
+  {
+    key: 'histogram', label: 'Histogram', method: 'histogram', category: 'statistical',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.SINGLE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'sample', kind: AXIS_KIND.RAW_SAMPLE, channel: ENCODING_CHANNEL.DERIVED, required: true },
+    ],
+    dataShape: 'number[] — a raw sample, binned internally (not pre-aggregated); no category axis at all, unlike every other cartesian type here',
+    streamShape: 'flat',
+  },
+  {
+    key: 'boxPlot', label: 'Box Plot', method: 'boxPlot', category: 'statistical',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.SINGLE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'group',  kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_X, required: true },
+      { role: 'sample', kind: AXIS_KIND.RAW_SAMPLE,  channel: ENCODING_CHANNEL.DERIVED,    required: true },
+    ],
+    dataShape: 'Array<{label, values:number[]}> — raw per-group samples, quartiles/whiskers/outliers computed internally (1.5×IQR Tukey fences)',
+    streamShape: 'grouped-sample',
+  },
+  {
+    key: 'density', label: 'Density Plot', method: 'densityChart', category: 'statistical',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: true, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'group',  kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.COLOR,   required: true },
+      { role: 'sample', kind: AXIS_KIND.RAW_SAMPLE,  channel: ENCODING_CHANNEL.DERIVED, required: true },
+    ],
+    dataShape: "Array<{label, values:number[]}> — same shape as boxPlot; each group's raw sample becomes an overlaid Gaussian-KDE curve on one shared value-axis, colored per group (not positioned — group drives color here, unlike boxPlot where it drives x-position)",
+    streamShape: 'grouped-sample',
+  },
+  {
+    key: 'violin', label: 'Violin Plot', method: 'violinChart', category: 'statistical',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'group',  kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_X, required: true },
+      { role: 'sample', kind: AXIS_KIND.RAW_SAMPLE,  channel: ENCODING_CHANNEL.DERIVED,    required: true },
+    ],
+    dataShape: "Array<{label, values:number[]}> — same shape as boxPlot (and interchangeable with it); each group's raw sample becomes a mirrored Gaussian-KDE silhouette in its own x-slot, colored per group",
+    streamShape: 'grouped-sample',
+  },
+  {
+    key: 'qq', label: 'Q-Q Plot', method: 'qqPlot', category: 'statistical',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.SINGLE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'sample', kind: AXIS_KIND.RAW_SAMPLE, channel: ENCODING_CHANNEL.DERIVED, required: true },
+    ],
+    dataShape: "number[] — a raw sample; each point is (theoretical normal quantile, sample quantile), with a dashed reference line fit through the sample's own Q1/Q3 — deviation signals non-normality (fat tails, skew); delegates entirely to scatterChart",
+    streamShape: 'flat',
+  },
+  {
+    key: 'lag', label: 'Lag Plot', method: 'lagPlot', category: 'statistical',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.SINGLE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'sample', kind: AXIS_KIND.RAW_SAMPLE, channel: ENCODING_CHANNEL.DERIVED, required: true },
+    ],
+    dataShape: 'number[] — an ordered series (e.g. daily returns); plots each value against itself lagged by options.lag (default 1) to visually check autocorrelation — delegates entirely to scatterChart',
+    streamShape: 'flat',
+  },
+  {
+    key: 'treemap', label: 'Treemap', method: 'treemapChart', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'value', kind: AXIS_KIND.NUMERIC,     channel: ENCODING_CHANNEL.ANGLE_OR_AREA,  required: true },
+      { role: 'group',  kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_ORDER, required: false },
+    ],
+    dataShape: 'Array<{label, value?, children?}> — a leaf has `value` (no children); a branch has `children` (value computed as their sum) and can nest to any depth; rectangle AREA is proportional to value (squarified layout); color comes from each top-level branch, descendants shaded progressively lighter by depth',
+    streamShape: 'flat', // appends a new top-level leaf; adding a point below an existing branch isn't supported by addDataPoint
+  },
+  {
+    key: 'sunburst', label: 'Sunburst', method: 'sunburstChart', category: '2d',
+    coordSystem: COORD_SYSTEM.RADIAL, title: true, legend: false, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'value', kind: AXIS_KIND.NUMERIC,     channel: ENCODING_CHANNEL.ANGLE_OR_AREA,  required: true },
+      { role: 'group',  kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_ORDER, required: false },
+    ],
+    dataShape: 'Array<{label, value?, children?}> — same hierarchical shape as treemap (shares _hierarchyValue); angle (not area) is proportional to value within each ring, ring = depth',
+    streamShape: 'flat',
+  },
+  {
+    key: 'outline', label: 'Outline / Tree List', method: 'outlineChart', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'value', kind: AXIS_KIND.NUMERIC,     channel: ENCODING_CHANNEL.TEXT_VALUE,     required: false },
+      { role: 'group', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_ORDER, required: false },
+    ],
+    dataShape: 'Array<{label, value?, children?}> — same hierarchical shape as treemap/sunburst (shares _hierarchyValue); drawn as an indented, collapsible list instead of nested rectangles/rings — a branch\'s value is auto-summed from its descendants and shown as a trailing count, a leaf\'s own extra fields (anything beyond label/value/children) shown as trailing descriptive text instead',
+    streamShape: 'flat',
+  },
+  {
+    key: 'gauge-dial', label: 'Gauge (Dial)', method: 'dialGauge', category: 'gauge',
+    coordSystem: COORD_SYSTEM.RADIAL, title: true, legend: false, colorMode: COLOR_MODE.SINGLE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'value', kind: AXIS_KIND.NUMERIC, channel: ENCODING_CHANNEL.FILL_PERCENT, required: true, range: [0, 100] }, // the default; the min/max options change it
+    ],
+    dataShape: 'number, {value, target?}, or [{value, label?, color?}] (a needle each) — no category axis; the only role IS the value (0-100 unless min/max are given)',
+    streamShape: 'none', // no array/window at all — update by calling dialGauge(newValue) again directly
+  },
+  {
+    key: 'gauge-bar', label: 'Gauge (Bar)', method: 'barGauge', category: 'gauge',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.SINGLE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'value', kind: AXIS_KIND.NUMERIC, channel: ENCODING_CHANNEL.FILL_PERCENT, required: true, range: [0, 100] }, // the default; the min/max options change it
+    ],
+    dataShape: 'number, or {value, target?} (0-100 unless min/max are given)',
+    streamShape: 'none', // no array/window at all — update by calling barGauge(newValue) again directly
+  },
+  {
+    key: 'bullet', label: 'Bullet Graph', method: 'bulletGauge', category: 'gauge',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.SEMANTIC, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'value', kind: AXIS_KIND.NUMERIC, channel: ENCODING_CHANNEL.FILL_PERCENT, required: true },
+      { role: 'target', kind: AXIS_KIND.NUMERIC, channel: ENCODING_CHANNEL.POSITION_X, required: false },
+    ],
+    dataShape: 'number or {value, target?, ranges?:Array<{max, label?, color?}>}',
+    streamShape: 'none',
+  },
+  {
+    key: 'gauge-arc', label: 'Gauge (Arc)', method: 'arcGauge', category: 'gauge',
+    coordSystem: COORD_SYSTEM.RADIAL, title: true, legend: false, colorMode: COLOR_MODE.SINGLE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'value', kind: AXIS_KIND.NUMERIC, channel: ENCODING_CHANNEL.FILL_PERCENT, required: true, range: [0, 100] }, // the default; the min/max options change it
+    ],
+    dataShape: 'number, or {value, target?} (0-100 unless min/max are given) — a half circle by default, any startAngle/sweep',
+    streamShape: 'none',
+  },
+  {
+    key: 'gauge-ring', label: 'Gauge (Ring)', method: 'ringGauge', category: 'gauge',
+    coordSystem: COORD_SYSTEM.RADIAL, title: true, legend: false, colorMode: COLOR_MODE.SINGLE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'value', kind: AXIS_KIND.NUMERIC, channel: ENCODING_CHANNEL.FILL_PERCENT, required: true, range: [0, 100] }, // the default; the min/max options change it
+    ],
+    dataShape: 'number, or {value, target?} (0-100 unless min/max are given)',
+    streamShape: 'none',
+  },
+  {
+    key: 'gauge-rings', label: 'Gauge (Rings)', method: 'multiRingGauge', category: 'gauge',
+    coordSystem: COORD_SYSTEM.RADIAL, title: true, legend: true, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'value', kind: AXIS_KIND.NUMERIC, channel: ENCODING_CHANNEL.FILL_PERCENT, required: true, range: [0, 100] }, // the default; the min/max options change it
+    ],
+    dataShape: 'Array<number|{value, label?, color?, min?, max?}> — one ring per value, outer first, each on its own scale',
+    streamShape: 'none',
+  },
+  {
+    key: 'gauge-thermometer', label: 'Gauge (Thermometer)', method: 'thermometerGauge', category: 'gauge',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.SINGLE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'value', kind: AXIS_KIND.NUMERIC, channel: ENCODING_CHANNEL.FILL_PERCENT, required: true, range: [0, 100] }, // the default; the min/max options change it
+    ],
+    dataShape: 'number, or {value, target?} (0-100 unless min/max are given)',
+    streamShape: 'none',
+  },
+  {
+    key: 'kpi-tile', label: 'KPI Tile', method: 'kpiTile', category: 'gauge',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.SINGLE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'value', kind: AXIS_KIND.NUMERIC, channel: ENCODING_CHANNEL.FILL_PERCENT, required: true, range: [0, 100] }, // the default; the min/max options change it
+    ],
+    dataShape: 'number, or {value?, previous?, history?:number[]} — the figure, its change since the previous value, a sparkline of the history',
+    streamShape: 'none',
+  },
+  {
+    key: 'bar3D', label: 'Bar (3D)', method: 'barChart3D', category: '3d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.ISOMETRIC,
+    axes: [
+      { role: 'category', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_X,      required: true },
+      { role: 'value',    kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.POSITION_Y_LENGTH, required: true },
+      { role: 'depth',    kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.SHAPE_DEPTH,     required: false },
+    ],
+    dataShape: 'Array<{label, value, depth?}> — a single fixed-angle isometric shadow per bar, not a real camera (see bar3DOrbit for that)',
+    streamShape: 'flat',
+  },
+  {
+    key: 'bubble3D', label: 'Bubble (3D)', method: 'bubbleChart3D', category: '3d',
+    coordSystem: COORD_SYSTEM.ORBIT_3D, title: true, legend: false, colorMode: COLOR_MODE.GROUPED_FIELD, camera: CAMERA_MODE.ORBIT,
+    axes: [
+      { role: 'x',     kind: AXIS_KIND.NUMERIC,     channel: ENCODING_CHANNEL.POSITION_X, required: true },
+      { role: 'y',     kind: AXIS_KIND.NUMERIC,     channel: ENCODING_CHANNEL.POSITION_Y, required: true },
+      { role: 'z',     kind: AXIS_KIND.NUMERIC,     channel: ENCODING_CHANNEL.POSITION_Z, required: true },
+      { role: 'size',  kind: AXIS_KIND.NUMERIC,     channel: ENCODING_CHANNEL.SHAPE_SIZE, required: false },
+      { role: 'group', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.COLOR,      required: false },
+    ],
+    dataShape: 'Array<{label, x, y, z, size?, category?}> — real orbit camera (drag-rotate/wheel-zoom); a future sphere/ellipsoid variant is this same shape with a second shape-size-channeled role, not a new chart type',
+    streamShape: 'flat',
+  },
+  {
+    key: 'bar3DOrbit', label: 'Bar (3D Orbit)', method: 'barChart3DOrbit', category: '3d',
+    coordSystem: COORD_SYSTEM.ORBIT_3D, title: true, legend: false, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.ORBIT,
+    axes: [
+      { role: 'x',     kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_X,      required: true },
+      { role: 'z',     kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_Z,      required: true },
+      { role: 'value', kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.POSITION_Y_HEIGHT, required: true },
+    ],
+    dataShape: 'Array<{x, z, value}> — grouped across two categorical axes, real orbit camera; colors indexed by z-group',
+    streamShape: 'none', // fixed x*z grid
+  },
+  {
+    key: 'stackedBar3DOrbit', label: 'Stacked Bar (3D Orbit)', method: 'stackedBarChart3DOrbit', category: '3d',
+    coordSystem: COORD_SYSTEM.ORBIT_3D, title: true, legend: false, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.ORBIT,
+    axes: [
+      { role: 'x',      kind: AXIS_KIND.CATEGORICAL,  channel: ENCODING_CHANNEL.POSITION_X,      required: true },
+      { role: 'z',      kind: AXIS_KIND.CATEGORICAL,  channel: ENCODING_CHANNEL.POSITION_Z,      required: true },
+      { role: 'values', kind: AXIS_KIND.NUMERIC_LIST, channel: ENCODING_CHANNEL.POSITION_Y_HEIGHT, required: true },
+    ],
+    dataShape: 'Array<{x, z, values:number[]}> — same grid as bar3DOrbit, each cell a stack of segments; colors indexed by segment position, not z-group',
+    streamShape: 'none', // fixed x*z grid
+  },
+];
+
+import { ChartRegistry } from './charting/ChartRegistry.js';
+
+/** Canonical registry instance seeded with the built-in chart types. */
+export const chartRegistry = new ChartRegistry(CHART_CATALOG);
+
+/** Look up one catalog entry by key, or undefined if the key is unknown. */
+export function getChartCatalogEntry(key) {
+  return chartRegistry.get(key);
+}