@taylorwong/ichartjs 2.0.1

package/src/capabilities.mjs

@@ -0,0 +1,190 @@
+/**
+ * Machine-readable chart capabilities and deterministic Agent planning.
+ */
+import { inspectData } from './data.mjs';
+import { planStyle, styleCapabilities } from './theme.mjs';
+
+export const chartTypes = ['line', 'area', 'bar', 'column', 'pie', 'scatter', 'funnel', 'gauge', 'heatmap', 'radar', 'gantt', 'timeline', 'milestone', 'burndown', 'flow', 'swimlane'];
+
+const cartesian = ['line', 'area', 'bar', 'column', 'scatter'];
+const project = ['gantt', 'timeline', 'milestone', 'burndown'];
+const diagrams = ['flow', 'swimlane'];
+const status = (supported, notApplicable = []) => Object.fromEntries(supported.map(name => [name, 'supported']).concat(notApplicable.map(name => [name, 'not-applicable'])));
+const commonPresentation = ['title', 'subtitle', 'theme', 'responsive', 'empty-state', 'invalid-data-state', 'export', 'branding'];
+
+const definitions = {
+  line: { family: 'cartesian', intents: ['trend', 'time-series'], required: ['dimension', 'measure'], optional: ['series'], interactions: ['hover', 'tooltip', 'selection', 'crosshair', 'zoom', 'pan', 'keyboard'], features: status([...commonPresentation, 'axes', 'grid', 'legend', 'labels', 'formatting', 'multi-series', 'dual-axis']) },
+  area: { family: 'cartesian', intents: ['trend', 'composition'], required: ['dimension', 'measure'], optional: ['series'], interactions: ['hover', 'tooltip', 'selection', 'crosshair', 'zoom', 'pan', 'keyboard'], features: status([...commonPresentation, 'axes', 'grid', 'legend', 'labels', 'formatting', 'multi-series', 'stacked', 'percent-stacked']) },
+  bar: { family: 'cartesian', intents: ['comparison', 'ranking'], required: ['dimension', 'measure'], optional: ['series'], interactions: ['hover', 'tooltip', 'selection', 'zoom', 'pan', 'keyboard'], features: status([...commonPresentation, 'axes', 'grid', 'legend', 'labels', 'formatting', 'multi-series', 'stacked', 'percent-stacked']) },
+  column: { family: 'cartesian', intents: ['comparison', 'distribution', 'composition'], required: ['dimension', 'measure'], optional: ['series'], interactions: ['hover', 'tooltip', 'selection', 'zoom', 'pan', 'keyboard'], features: status([...commonPresentation, 'axes', 'grid', 'legend', 'labels', 'formatting', 'multi-series', 'stacked', 'percent-stacked', 'mixed-line-column', 'dual-axis', 'bin']) },
+  pie: { family: 'part-to-whole', intents: ['part-to-whole'], required: ['dimension', 'measure'], optional: [], interactions: ['hover', 'tooltip', 'selection', 'keyboard'], features: status([...commonPresentation, 'legend', 'labels', 'formatting', 'donut', 'zero-total'], ['axes', 'grid', 'zoom', 'pan']) },
+  scatter: { family: 'cartesian', intents: ['relationship', 'correlation'], required: ['measure', 'measure'], optional: ['dimension'], interactions: ['hover', 'tooltip', 'selection', 'brush', 'zoom', 'pan', 'keyboard'], features: status([...commonPresentation, 'axes', 'grid', 'labels', 'formatting'], ['stacked']) },
+  funnel: { family: 'stage', intents: ['funnel', 'conversion'], required: ['dimension', 'measure'], optional: [], interactions: ['hover', 'tooltip', 'selection', 'keyboard'], features: status([...commonPresentation, 'labels', 'formatting'], ['axes', 'grid', 'zoom', 'pan']) },
+  gauge: { family: 'indicator', intents: ['progress', 'single-value'], required: ['measure'], optional: ['dimension'], interactions: ['hover', 'tooltip', 'selection', 'keyboard'], features: status([...commonPresentation, 'labels', 'formatting', 'domain'], ['axes', 'grid', 'legend', 'zoom', 'pan']) },
+  heatmap: { family: 'matrix', intents: ['matrix', 'correlation-grid'], required: ['dimension', 'dimension', 'measure'], optional: [], interactions: ['hover', 'tooltip', 'selection', 'keyboard'], features: status([...commonPresentation, 'axes', 'labels', 'formatting', 'color-scale', 'missing-values'], ['zoom', 'pan']) },
+  radar: { family: 'radial', intents: ['multidimensional', 'profile'], required: ['three-or-more-measures'], optional: ['series'], interactions: ['hover', 'tooltip', 'selection', 'keyboard'], features: status([...commonPresentation, 'legend', 'labels', 'formatting', 'multi-series', 'indicator-domains', 'mixed-unit-warning'], ['axes', 'grid', 'zoom', 'pan']) },
+  gantt: { family: 'project', intents: ['schedule', 'variance'], required: ['id', 'start', 'end'], optional: ['dependencies', 'progress', 'baseline', 'actual'], interactions: ['hover', 'tooltip', 'selection', 'zoom', 'pan', 'keyboard', 'linked-filter', 'linked-selection'], features: status([...commonPresentation, 'labels', 'formatting', 'critical-path', 'slack', 'baseline-actual-variance', 'working-calendar', 'dependencies']) },
+  timeline: { family: 'project', intents: ['timeline', 'milestone'], required: ['date', 'label'], optional: ['status'], interactions: ['hover', 'tooltip', 'selection', 'zoom', 'pan', 'keyboard'], features: status([...commonPresentation, 'labels', 'formatting']) },
+  milestone: { family: 'project', intents: ['milestone'], required: ['date', 'label'], optional: ['baseline', 'actual'], interactions: ['hover', 'tooltip', 'selection', 'zoom', 'pan', 'keyboard'], features: status([...commonPresentation, 'labels', 'formatting', 'baseline-actual-variance']) },
+  burndown: { family: 'project', intents: ['progress', 'release'], required: ['date', 'remaining'], optional: ['ideal', 'scopeChange'], interactions: ['hover', 'tooltip', 'selection', 'zoom', 'pan', 'keyboard'], features: status([...commonPresentation, 'axes', 'labels', 'formatting', 'scope-change', 'release-forecast']) },
+  flow: { family: 'diagram', intents: ['workflow'], required: ['nodes'], optional: ['edges', 'groups', 'ports'], interactions: ['hover', 'selection', 'drag', 'keyboard-edit', 'keyboard-port-connect', 'port-connect', 'copy-paste'], features: status([...commonPresentation, 'labels', 'routing', 'layout', 'groups', 'ports', 'history'], ['axes', 'grid', 'legend']) },
+  swimlane: { family: 'diagram', intents: ['responsibility'], required: ['nodes', 'lanes'], optional: ['edges', 'groups', 'ports'], interactions: ['hover', 'selection', 'drag', 'keyboard-edit', 'keyboard-port-connect', 'port-connect', 'copy-paste'], features: status([...commonPresentation, 'labels', 'routing', 'layout', 'groups', 'ports', 'lanes', 'history'], ['axes', 'grid', 'legend']) }
+};
+
+export const chartProfiles = Object.fromEntries(chartTypes.map(type => [type, {
+  type,
+  ...definitions[type],
+  dataShapes: definitions[type].family === 'diagram' ? ['diagram-spec'] : definitions[type].family === 'project' ? ['records'] : ['records', 'data-table'],
+  renderers: ['canvas', 'svg'],
+  exports: ['png', 'svg', 'json'],
+  limits: type === 'pie' ? { recommendedCategories: 8 } : type === 'radar' ? { minimumIndicators: 3, recommendedIndicators: 8 } : type === 'heatmap' ? { recommendedCells: 2500 } : {}
+}]));
+
+const intentMap = {
+  schedule: 'gantt', variance: 'gantt', timeline: 'timeline', milestone: 'milestone', progress: 'burndown', release: 'burndown', capacity: 'column', risk: 'scatter', aging: 'bar', matrix: 'heatmap', 'correlation-grid': 'heatmap', multidimensional: 'radar', profile: 'radar', workflow: 'flow', responsibility: 'swimlane', trend: 'line', 'time-series': 'line', 'part-to-whole': 'pie', distribution: 'column', relationship: 'scatter', correlation: 'scatter', funnel: 'funnel', conversion: 'funnel', 'single-value': 'gauge', ranking: 'bar', comparison: 'bar', composition: 'column'
+};
+
+const alternatives = {
+  heatmap: ['scatter', 'column'], radar: ['bar', 'line'], gantt: ['timeline', 'milestone'], timeline: ['milestone', 'gantt'], milestone: ['timeline', 'gantt'], burndown: ['line', 'gantt'], column: ['bar', 'line'], scatter: ['bar', 'line'], bar: ['column', 'line'], flow: ['swimlane', 'gantt'], swimlane: ['flow', 'gantt'], line: ['area', 'column'], pie: ['bar', 'column'], funnel: ['bar', 'column'], gauge: ['column', 'bar']
+};
+
+function warning(code, path, message, suggestion) { return { code, path, message, ...(suggestion ? { suggestion } : {}) }; }
+
+export function getChartCapability(type) {
+  return chartProfiles[type] ? JSON.parse(JSON.stringify(chartProfiles[type])) : null;
+}
+
+export function planChart(input, options = {}) {
+  const report = inspectData(input);
+  const requestedIntent = options.intent || 'comparison';
+  const warnings = [...report.warnings];
+  let primary = intentMap[requestedIntent];
+  if (!primary) {
+    primary = report.fields.some(field => field.type === 'temporal') ? 'line' : report.measures.length >= 2 && report.dimensions.length === 0 ? 'scatter' : 'bar';
+    warnings.push(warning('UNKNOWN_INTENT', 'intent', `Intent ${requestedIntent} is not registered.`, 'Use an intent returned by getCapabilities().intents.'));
+  }
+  const profile = chartProfiles[primary];
+  const requiredFields = [];
+  const nextActions = [];
+  if (!report.rows && !diagrams.includes(primary)) warnings.push(warning('EMPTY_DATA', 'data', 'No rows are available for chart planning.', 'Provide at least one record.'));
+  if (['pie', 'funnel'].includes(primary) && report.dimensions.length) {
+    const field = report.fields.find(item => item.name === report.dimensions[0]);
+    if (field?.cardinality > 8) warnings.push(warning('HIGH_CARDINALITY_PART_TO_WHOLE', `data.${field.name}`, `${field.cardinality} categories may make ${primary} hard to read.`, 'Use bar for comparison or filter to the most important categories.'));
+  }
+  if (profile.family === 'cartesian' || ['part-to-whole', 'stage'].includes(profile.family)) {
+    if (!report.dimensions.length) requiredFields.push('dimension');
+    if (!report.measures.length) requiredFields.push('measure');
+  }
+  if (primary === 'heatmap') {
+    if (report.dimensions.length < 2) requiredFields.push('second dimension');
+    if (!report.measures.length) requiredFields.push('measure');
+  }
+  if (primary === 'radar' && report.measures.length < 3) requiredFields.push('three quantitative measures');
+  if (requiredFields.length) {
+    warnings.push(warning('INSUFFICIENT_FIELDS', 'data', `${primary} requires ${requiredFields.join(' and ')}.`, 'Add the required fields or choose an alternative chart.'));
+    nextActions.push(`Provide ${requiredFields.join(' and ')}.`);
+  }
+  if (warnings.length) nextActions.push('Review warnings before rendering.');
+  nextActions.push(`Validate the ${primary} Spec with validateSpec().`);
+  const confidence = !report.rows || requiredFields.length ? 0.35 : warnings.some(item => item.code !== 'MISSING_VALUE') ? 0.65 : 0.9;
+  const styleRecommendation = planStyle({ type: primary, intent: requestedIntent, data: Array.isArray(input) ? input : input?.values || input, encoding: { x: report.dimensions[0] ? { field: report.dimensions[0] } : undefined, y: report.measures.map(field => ({ field })) } }, options);
+  warnings.push(...styleRecommendation.warnings);
+  return {
+    version: '1.0',
+    intent: requestedIntent,
+    primary,
+    alternatives: alternatives[primary] || ['column', 'line'],
+    confidence,
+    reasons: [`${primary} supports the ${requestedIntent} intent.`, `Detected ${report.dimensions.length} dimensions and ${report.measures.length} measures across ${report.rows} rows.`],
+    requiredFields,
+    suggestedEncodings: { dimension: report.dimensions[0] || null, measure: report.measures[0] || null, secondaryMeasure: report.measures[1] || null },
+    assumptions: ['Field roles are inferred from provided values; business meaning and units are not inferred.'],
+    warnings,
+    unsupportedRequests: options.renderer && !profile.renderers.includes(options.renderer) ? [`renderer:${options.renderer}`] : [],
+    nextActions,
+    capability: getChartCapability(primary),
+    styleRecommendation,
+    data: report
+  };
+}
+
+export function explainChart(spec, model = {}) {
+  const profile = chartProfiles[spec.type];
+  const encodings = Object.fromEntries(Object.entries(spec.encoding || {}).map(([channel, value]) => [channel, Array.isArray(value) ? value.map(item => item?.field).filter(Boolean) : value?.field]).filter(([, value]) => Array.isArray(value) ? value.length : value));
+  const warnings = [...(model.data?.warnings || []), ...(model.state?.projectAnalytics?.warnings || [])];
+  return {
+    version: '1.0',
+    type: spec.type,
+    family: profile?.family || 'unknown',
+    purpose: profile?.intents?.[0] || 'visualization',
+    renderer: spec.renderer,
+    dataCount: model.data?.rows?.length || 0,
+    encodings,
+    transforms: spec.transform ? (Array.isArray(spec.transform) ? spec.transform : [spec.transform]).map(item => item.type) : [],
+    interactions: Object.keys(spec.interaction || {}).filter(key => spec.interaction[key]),
+    assumptions: [...(model.data?.assumptions || []), ...(model.state?.projectAnalytics?.assumptions || [])],
+    warnings,
+    style: spec.theme && typeof spec.theme === 'object' ? { name: spec.theme.name, preset: spec.theme.preset, mode: spec.theme.mode, resolvedMode: spec.theme.resolvedMode, palette: spec.theme.palette, reasons: spec.theme.reasons || [], warnings: spec.theme.warnings || [] } : planStyle(spec),
+    lineage: { recordIds: (model.data?.rows || []).map((row, index) => String(row.id ?? row.key ?? `record-${index}`)), sourcePreserved: true },
+    accessibility: { enabled: Boolean(spec.accessibility?.enabled), summary: spec.accessibility?.description || spec.title?.text || `${spec.type} chart with ${model.data?.rows?.length || 0} data items.` }
+  };
+}
+
+export function getCapabilities() {
+  const intents = [...new Set(Object.values(chartProfiles).flatMap(profile => profile.intents))];
+  const exp = {
+    types: ['png', 'jpeg', 'svg', 'json'],
+    mime: { png: 'image/png', jpeg: 'image/jpeg', svg: 'image/svg+xml', json: 'application/json' },
+    browser: { png: true, jpeg: true, svg: true, json: true },
+    headless: {
+      png: 'optional: install the `canvas` npm package for createCanvas',
+      jpeg: 'same as png',
+      svg: true,
+      json: true,
+    },
+    methods: {
+      exportPNG: 'chart.export({ type:"png" }) returns base64 data URL (browser); pass as:"blob" for a Blob. In Node headless either install the canvas package or fall back to SVG.',
+      exportSVG: 'chart.export({ type:"svg" }) returns the SVG string in both browser and headless; as:"dataurl" for embeds, as:"blob" for a Blob (browser).',
+      exportJSON: 'chart.export({ type:"json" }) returns pretty JSON; use as:"object" to get the parsed {version,spec,state}.',
+      downloadPNG: 'chart.downloadPNG() triggers a browser save-as dialog (filename derived from title + timestamp).',
+      downloadSVG: 'chart.downloadSVG() same semantics as downloadPNG but for SVG.',
+      downloadJSON: 'chart.downloadJSON() saves {version,spec,state} as a .json document.',
+      toDataURL: 'chart.toDataURL("image/png"|"image/svg+xml") returns a data URL string.',
+      toBlob: 'chart.toBlob("image/png"|"image/svg+xml") returns a Blob (browser-only).',
+    },
+    options: { as: ['string', 'object', 'dataurl', 'blob'] },
+    branding: 'By default PNG/SVG exports include the Powered by iChart.js branding watermark. Pass branding: { enabled: false } or branding: false to remove it for white-label output.',
+  };
+  return {
+    version: '2.0',
+    contractVersion: '1.0',
+    chartTypes,
+    charts: JSON.parse(JSON.stringify(chartProfiles)),
+    intents,
+    chartModes: { stack: ['stacked', 'percent'], pie: ['standard', 'donut'], composition: ['multi-series', 'mixed-line-column', 'dual-axis'], transforms: ['bin'] },
+    projectManagement: project,
+    projectIntelligence: {
+      intents: ['schedule', 'milestone', 'progress', 'variance', 'capacity', 'release', 'risk', 'aging', 'workflow', 'responsibility'],
+      views: ['gantt', 'burndown', 'column', 'area', 'scatter', 'bar'],
+      analytics: ['calendar', 'dependency-normalization', 'critical-path', 'slack', 'baseline-actual-variance', 'capacity', 'cumulative-flow', 'velocity', 'release-forecast', 'risk-matrix', 'issue-aging'],
+      linkedState: ['owner', 'status', 'priority', 'sprint', 'label'],
+    },
+    diagrams,
+    excluded: ['map', '3d'],
+    renderers: ['canvas', 'svg'],
+    interactions: [...new Set(Object.values(chartProfiles).flatMap(profile => profile.interactions))],
+    exports: ['png', 'svg', 'json'],
+    headless: {
+      preview: true,
+      json: true,
+      svg: true,
+      png: 'Node headless PNG requires the optional `canvas` npm package (createCanvas). Otherwise use chart.export({type:"svg"}).',
+    },
+    export: exp,
+    data: ['normalize', 'inspect', 'filter', 'sort', 'groupBy', 'sum', 'average', 'topN', 'percentage', 'bin'],
+    themes: [...styleCapabilities.modes],
+    styleSystem: JSON.parse(JSON.stringify(styleCapabilities)),
+    plugins: true,
+    branding: { defaultEnabled: true, signature: 'Powered by iChart.js', options: [{ name: 'enabled', type: 'boolean', default: true }] },
+  };
+}

package/src/charts.mjs

@@ -0,0 +1,234 @@
+/**
+ * Chart-to-scene builders for generic and project visualizations.
+ * Keeps chart specifications independent from Canvas and SVG renderers.
+ */
+import { Scene, SceneNode } from './scene.mjs';
+import { normalizeData } from './data.mjs';
+import { applyTransforms } from './transforms.mjs';
+import { buildProjectScene } from './project.mjs';
+import { formatValue } from './format.mjs';
+import { resolveTheme } from './theme.mjs';
+
+const pick = (row, encoding, fallback) => row?.[encoding?.field || fallback];
+const font = (spec, role, fallback = '12px system-ui') => spec.theme?.typography?.[role]?.font || fallback;
+
+function styledSpec(spec) {
+  const theme = spec.theme && typeof spec.theme === 'object' && spec.theme.typography ? spec.theme : resolveTheme(spec.theme, spec);
+  return { ...spec, theme, colors: spec.colors || theme.colors, background: spec.background || theme.background, padding: spec.padding || theme.layout.padding };
+}
+
+function layout(spec, data) {
+  const p = spec.padding, width = spec.width, height = spec.height;
+  const categoryField = spec.encoding.x?.field || 'name';
+  const categoryLabelLength = spec.type === 'bar' ? Math.max(0, ...data.rows.map(row => String(row[categoryField] ?? '').length)) : 0;
+  const plotLeft = spec.type === 'bar' ? Math.min(width * 0.35, Math.max(p.left, categoryLabelLength * 8 + 24)) : p.left;
+  const plotTop = Math.max(p.top, spec.title?.subtitle ? 72 : spec.title?.text ? 56 : p.top);
+  const plot = { x: plotLeft, y: plotTop, width: Math.max(1, width - plotLeft - p.right), height: Math.max(1, height - plotTop - p.bottom) };
+  const xEncoding = spec.encoding.x || { field: 'name', type: 'category' };
+  const xField = xEncoding.field || 'name';
+  const yEncodings = Array.isArray(spec.encoding.y) ? spec.encoding.y : [spec.encoding.y || { field: 'value', type: 'quantitative' }];
+  const yField = yEncodings[0]?.field || 'value';
+  const categories = [...new Set(data.rows.map(row => String(row[xField] ?? '')))].filter(Boolean);
+  const stackMode = typeof spec.stack === 'string' ? spec.stack : spec.stack?.mode;
+  const stackTotals = stackMode ? data.rows.flatMap(row => {
+    const values = yEncodings.map(encoding => Number(row[encoding.field])).filter(Number.isFinite);
+    if (stackMode === 'percent') return [0, 1];
+    return [values.filter(value => value >= 0).reduce((sum, value) => sum + value, 0), values.filter(value => value < 0).reduce((sum, value) => sum + value, 0)];
+  }) : [];
+  const numbers = (stackTotals.length ? stackTotals : data.rows.flatMap(row => yEncodings.map(encoding => Number(row[encoding.field])))).filter(Number.isFinite);
+  const min = Math.min(0, ...(numbers.length ? numbers : [0]));
+  const max = Math.max(1, ...(numbers.length ? numbers : [1]));
+  const temporal = xEncoding.type === 'temporal' || xEncoding.type === 'time';
+  const quantitativeX = xEncoding.type === 'quantitative' || xEncoding.type === 'linear';
+  const dates = temporal ? data.rows.map(row => new Date(row[xField]).getTime()).filter(Number.isFinite) : [];
+  const xNumbers = quantitativeX ? data.rows.map(row => Number(row[xField])).filter(Number.isFinite) : [];
+  const xMin = dates.length ? Math.min(...dates) : xNumbers.length ? Math.min(...xNumbers) : 0, xMax = dates.length ? Math.max(...dates) : xNumbers.length ? Math.max(...xNumbers) : 1;
+  const x = category => temporal ? plot.x + ((new Date(category).getTime() - xMin) / (xMax - xMin || 1)) * plot.width : quantitativeX ? plot.x + ((Number(category) - xMin) / (xMax - xMin || 1)) * plot.width : plot.x + (categories.indexOf(String(category)) + 0.5) * plot.width / Math.max(1, categories.length);
+  const axisType = spec.yAxis?.type || yEncodings[0]?.type || 'linear';
+  const transform = value => axisType === 'log' ? Math.log10(Math.max(0.000001, Number(value))) : Number(value);
+  const transformedMin = transform(min), transformedMax = transform(max);
+  const y = value => plot.y + plot.height - ((transform(value) - transformedMin) / (transformedMax - transformedMin || 1)) * plot.height;
+  const yRightNumbers = data.rows.map(row => Number(row[yEncodings[1]?.field])).filter(Number.isFinite);
+  const rightMin = Math.min(0, ...(yRightNumbers.length ? yRightNumbers : [0])), rightMax = Math.max(1, ...(yRightNumbers.length ? yRightNumbers : [1]));
+  const rightType = spec.yAxis?.right?.type || yEncodings[1]?.type || 'linear';
+  const rightTransform = value => rightType === 'log' ? Math.log10(Math.max(0.000001, Number(value))) : Number(value);
+  const yRight = value => plot.y + plot.height - ((rightTransform(value) - rightTransform(rightMin)) / (rightTransform(rightMax) - rightTransform(rightMin) || 1)) * plot.height;
+  return { plot, xField, xEncoding, temporal, quantitativeX, xMin, xMax, yField, yEncodings, categories, min, max, rightMin, rightMax, x, y, yRight, axisType, rightType };
+}
+
+function addText(scene, id, text, x, y, style = {}, dataRef = null) { scene.add(new SceneNode({ id, type: 'text', geometry: { text: String(text), x, y }, style, dataRef })); }
+
+function addAxes(scene, spec, state) {
+  const { plot, categories, min, max, x, y, yRight } = state;
+  scene.add(new SceneNode({ id: 'axis-x', type: 'line', geometry: { x1: plot.x, y1: plot.y + plot.height, x2: plot.x + plot.width, y2: plot.y + plot.height }, style: { stroke: spec.theme.axis } }));
+  scene.add(new SceneNode({ id: 'axis-y', type: 'line', geometry: { x1: plot.x, y1: plot.y, x2: plot.x, y2: plot.y + plot.height }, style: { stroke: spec.theme.axis } }));
+  if (spec.type === 'bar') {
+    const ticks = [min, min + (max - min) / 2, max], numericX = value => plot.x + ((value - min) / (max - min || 1)) * plot.width;
+    if (spec.grid?.visible !== false) ticks.forEach((value, index) => scene.add(new SceneNode({ id: `grid-x-${index}`, type: 'line', geometry: { x1: numericX(value), y1: plot.y, x2: numericX(value), y2: plot.y + plot.height }, style: { stroke: spec.grid?.color || spec.theme.grid, strokeWidth: spec.theme.marks.gridWidth }, zIndex: -2 })));
+    ticks.forEach(value => addText(scene, `label-x-value-${value}`, formatValue(value, spec.xAxis?.format || spec.yAxis?.format), numericX(value), plot.y + plot.height + 22, { fill: spec.theme.muted, font: font(spec, 'axis'), textAnchor: 'middle' }));
+    categories.forEach((category, index) => addText(scene, `label-y-category-${index}`, category, plot.x - 10, plot.y + (index + .5) * plot.height / Math.max(1, categories.length) + 4, { fill: spec.theme.muted, font: font(spec, 'axis'), textAnchor: 'end' }));
+    return;
+  }
+  const labels = state.temporal || state.quantitativeX ? timeTicks(state.xMin, state.xMax, 5) : categories;
+  const yTicks = [min, min + (max - min) / 2, max];
+  if (spec.grid?.visible !== false) yTicks.forEach((value, index) => scene.add(new SceneNode({ id: `grid-y-${index}`, type: 'line', geometry: { x1: plot.x, y1: y(value), x2: plot.x + plot.width, y2: y(value) }, style: { stroke: spec.grid?.color || spec.theme.grid, strokeWidth: spec.theme.marks.gridWidth }, zIndex: -2 })));
+  labels.forEach(category => addText(scene, `label-x-${category}`, state.temporal ? formatTime(category, state.xMax - state.xMin) : state.quantitativeX ? formatValue(category, spec.xAxis?.format) : category, x(category), plot.y + plot.height + 22, { fill: spec.theme.muted, font: font(spec, 'axis'), textAnchor: 'middle' }));
+  yTicks.forEach(value => addText(scene, `label-y-${value}`, formatValue(value, spec.yAxis?.format), plot.x - 10, y(value) + 4, { fill: spec.theme.muted, font: font(spec, 'axis'), textAnchor: 'end' }));
+  if (state.yEncodings.length > 1 && !spec.stack) [state.rightMin, (state.rightMin + state.rightMax) / 2, state.rightMax].forEach(value => addText(scene, `label-y-right-${value}`, formatValue(value, spec.yAxis?.right?.format), plot.x + plot.width + 10, yRight(value) + 4, { fill: spec.theme.muted, font: font(spec, 'axis') }));
+  if (spec.xAxis?.title) addText(scene, 'axis-x-title', spec.xAxis.title, plot.x + plot.width / 2, plot.y + plot.height + 42, { fill: spec.theme.text, font: font(spec, 'axis'), textAnchor: 'middle' });
+  if (spec.yAxis?.title) addText(scene, 'axis-y-title', spec.yAxis.title, 8, plot.y + 12, { fill: spec.theme.text, font: font(spec, 'axis') });
+}
+
+function addTitles(scene, spec) {
+  if (spec.title?.text) addText(scene, 'title', spec.title.text, spec.width / 2, 22, { fill: spec.theme.text, font: font(spec, 'title'), textAnchor: 'middle' });
+  if (spec.title?.subtitle) addText(scene, 'subtitle', spec.title.subtitle, spec.width / 2, 40, { fill: spec.theme.muted, font: font(spec, 'subtitle'), textAnchor: 'middle' });
+}
+
+function addLegend(scene, spec, entries) {
+  if (spec.legend?.visible === false || entries.length < 2) return;
+  const startX = Math.max(12, spec.width - spec.padding.right - entries.length * 92), y = spec.title?.subtitle ? 52 : 38;
+  entries.forEach((entry, index) => { const x = startX + index * 92; scene.add(new SceneNode({ id: `legend-swatch-${index}`, type: 'rect', geometry: { x, y: y - 8, width: 10, height: 10 }, style: { fill: entry.color } })); addText(scene, `legend-label-${index}`, entry.name, x + 15, y, { fill: spec.theme.muted, font: font(spec, 'legend') }); });
+}
+
+function addMarkLabel(scene, spec, id, value, x, y, dataRef) {
+  if (!spec.labels?.enabled) return;
+  addText(scene, `${id}-label`, formatValue(value, spec.labels.format), x, y, { fill: spec.labels.color || spec.theme.text, font: spec.labels.font || font(spec, 'label'), textAnchor: 'middle' }, dataRef);
+}
+
+function hexRgb(value) { const hex = String(value || '').replace('#', ''); if (!/^[0-9a-f]{6}$/i.test(hex)) return [37, 99, 235]; return [0, 2, 4].map(index => parseInt(hex.slice(index, index + 2), 16)); }
+function colorMix(start, end, ratio) { const left = hexRgb(start), right = hexRgb(end), value = Math.max(0, Math.min(1, ratio)); return `rgb(${left.map((channel, index) => Math.round(channel + (right[index] - channel) * value)).join(',')})`; }
+
+function addHeatmapScene(scene, spec, data, state, colors) {
+  const xField = spec.encoding.x?.field || 'x', yField = spec.encoding.y?.field || 'y', valueField = spec.encoding.color?.field || 'value';
+  const xValues = [...new Set(data.rows.map(row => String(row[xField])))], yValues = [...new Set(data.rows.map(row => String(row[yField])))];
+  const numericValue = row => row[valueField] == null || row[valueField] === '' ? null : Number(row[valueField]);
+  const values = data.rows.map(numericValue).filter(Number.isFinite), min = spec.colorScale?.domain?.[0] ?? Math.min(...values, 0), max = spec.colorScale?.domain?.[1] ?? Math.max(...values, 1);
+  const palette = spec.theme.palette === 'diverging' ? spec.theme.palettes.diverging : spec.theme.palettes.sequential;
+  const low = spec.colorScale?.range?.[0] || palette[0], high = spec.colorScale?.range?.at(-1) || palette.at(-1) || colors[0], missing = spec.colorScale?.missing || spec.theme.palettes.missing;
+  const gap = Math.max(0, Number(spec.cellPadding ?? 2)), width = state.plot.width / Math.max(1, xValues.length), height = state.plot.height / Math.max(1, yValues.length);
+  xValues.forEach((value, index) => addText(scene, `heatmap-x-${index}`, value, state.plot.x + (index + .5) * width, state.plot.y + state.plot.height + 20, { fill: spec.theme.muted, font: font(spec, 'axis'), textAnchor: 'middle' }));
+  yValues.forEach((value, index) => addText(scene, `heatmap-y-${index}`, value, state.plot.x - 10, state.plot.y + (index + .5) * height + 4, { fill: spec.theme.muted, font: font(spec, 'axis'), textAnchor: 'end' }));
+  data.rows.forEach((row, index) => { const xIndex = xValues.indexOf(String(row[xField])), yIndex = yValues.indexOf(String(row[yField])), value = numericValue(row), geometry = { x: state.plot.x + xIndex * width + gap / 2, y: state.plot.y + yIndex * height + gap / 2, width: Math.max(1, width - gap), height: Math.max(1, height - gap) }; scene.add(new SceneNode({ id: `heatmap-cell-${index}`, type: 'rect', geometry, bounds: geometry, style: { fill: Number.isFinite(value) ? colorMix(low, high, (value - min) / (max - min || 1)) : missing, stroke: spec.theme.background, strokeWidth: 1 }, dataRef: { dataIndex: index, x: row[xField], y: row[yField], value: Number.isFinite(value) ? value : null, recordId: row.id || `record-${index}` }, interactive: true })); });
+  state.matrix = { xValues, yValues, min, max };
+}
+
+function addRadarScene(scene, spec, data, state, colors) {
+  const indicators = spec.indicators, cx = state.plot.x + state.plot.width / 2, cy = state.plot.y + state.plot.height / 2, radius = Math.min(state.plot.width, state.plot.height) * .38;
+  if (indicators.some(indicator => !Number.isFinite(Number(indicator.min)) || !Number.isFinite(Number(indicator.max)))) data.warnings.push({ code: 'AMBIGUOUS_RADAR_DOMAIN', message: 'Declare finite min and max for every radar indicator, especially for mixed units.' });
+  const point = (indicator, index, ratio = 1) => { const angle = -Math.PI / 2 + index * Math.PI * 2 / indicators.length; return { x: cx + Math.cos(angle) * radius * ratio, y: cy + Math.sin(angle) * radius * ratio }; };
+  [0.25, 0.5, 0.75, 1].forEach((ratio, level) => scene.add(new SceneNode({ id: `radar-grid-${level}`, type: 'path', geometry: { points: indicators.map((indicator, index) => point(indicator, index, ratio)), closed: true }, style: { fill: 'none', stroke: spec.theme.grid, strokeWidth: spec.theme.marks.gridWidth } })));
+  indicators.forEach((indicator, index) => { const edge = point(indicator, index); scene.add(new SceneNode({ id: `radar-axis-${index}`, type: 'line', geometry: { x1: cx, y1: cy, x2: edge.x, y2: edge.y }, style: { stroke: spec.theme.axis } })); const label = point(indicator, index, 1.14); addText(scene, `radar-label-${index}`, indicator.name || indicator.field, label.x, label.y + 4, { fill: spec.theme.muted, font: font(spec, 'axis'), textAnchor: 'middle' }); });
+  data.rows.forEach((row, seriesIndex) => { const points = indicators.map((indicator, index) => { const min = Number(indicator.min ?? 0), max = Number(indicator.max ?? 1), raw = row[indicator.field], value = raw == null || raw === '' ? NaN : Number(raw); if (!Number.isFinite(value)) data.warnings.push({ code: 'INVALID_RADAR_VALUE', path: `rows.${seriesIndex}.${indicator.field}`, message: 'Radar indicator value must be numeric.' }); return point(indicator, index, Number.isFinite(value) ? Math.max(0, Math.min(1, (value - min) / (max - min || 1))) : 0); }); scene.add(new SceneNode({ id: `radar-series-${seriesIndex}`, type: 'path', geometry: { points, closed: true }, style: { fill: `${colors[seriesIndex % colors.length]}33`, stroke: colors[seriesIndex % colors.length], strokeWidth: 2 }, dataRef: { dataIndex: seriesIndex, recordId: row.id || `record-${seriesIndex}` } })); points.forEach((position, indicatorIndex) => { const dataRef = { dataIndex: seriesIndex, indicatorIndex, field: indicators[indicatorIndex].field, recordId: row.id || `record-${seriesIndex}` }; scene.add(new SceneNode({ id: `radar-item-${seriesIndex}-${indicatorIndex}`, type: 'circle', geometry: { cx: position.x, cy: position.y, r: 4 }, bounds: { x: position.x - 7, y: position.y - 7, width: 14, height: 14 }, style: { fill: colors[seriesIndex % colors.length] }, dataRef, interactive: true })); addMarkLabel(scene, spec, `radar-item-${seriesIndex}-${indicatorIndex}`, row[indicators[indicatorIndex].field], position.x, position.y - 7, dataRef); }); });
+  state.indicators = indicators.map(indicator => ({ ...indicator }));
+}
+
+function timeTicks(min, max, count) { return Array.from({ length: count }, (_, index) => min + (max - min) * index / Math.max(1, count - 1)); }
+function formatTime(value, span) { const date = new Date(value); if (span > 1000 * 86400000 * 365) return String(date.getUTCFullYear()); if (span > 1000 * 86400000 * 60) return `${date.getUTCFullYear()}-${String(date.getUTCMonth() + 1).padStart(2, '0')}`; return `${date.getUTCMonth() + 1}/${date.getUTCDate()}`; }
+
+function projectRows(spec, data) { return data.rows.length ? data.rows : (spec.tasks || spec.events || []); }
+function projectDate(value, min, max, plot) { const time = new Date(value).getTime(); return plot.x + ((time - min) / (max - min || 1)) * plot.width; }
+function addProjectAxes(scene, plot, min, max) { scene.add(new SceneNode({ id: 'project-axis', type: 'line', geometry: { x1: plot.x, y1: plot.y + plot.height, x2: plot.x + plot.width, y2: plot.y + plot.height }, style: { stroke: '#94a3b8' } })); timeTicks(min, max, 5).forEach(value => addText(scene, `project-label-${value}`, formatTime(value, max - min), projectDate(value, min, max, plot), plot.y + plot.height + 22, { fill: '#475569', font: '12px system-ui', textAnchor: 'middle' })); }
+function addProjectScene(scene, spec, data, state, colors) {
+  const { plot } = state;
+  if (['gantt', 'timeline', 'milestone'].includes(spec.type)) {
+    const rows = projectRows(spec, data), dates = rows.flatMap(row => [new Date(row.start || row.date || row.end).getTime(), new Date(row.end || row.date || row.start).getTime()]).filter(Number.isFinite), min = Math.min(...(dates.length ? dates : [Date.now()])), max = Math.max(...(dates.length ? dates : [min + 86400000]));
+    addProjectAxes(scene, plot, min, max);
+    const positions = new Map(); rows.forEach((row, index) => { const y = plot.y + (index + 0.5) * plot.height / Math.max(1, rows.length), start = projectDate(row.start || row.date || row.end, min, max, plot), end = projectDate(row.end || row.date || row.start, min, max, plot), x = Math.min(start, end), width = Math.max(8, Math.abs(end - start)); positions.set(row.id, { x, y, end, row }); const milestone = spec.type === 'milestone' || row.milestone || start === end; const geometry = milestone ? { cx: start, cy: y, r: 7 } : { x, y: y - 10, width, height: 20 }; scene.add(new SceneNode({ id: `project-item-${index}`, type: milestone ? 'circle' : 'rect', geometry, bounds: milestone ? { x: start - 10, y: y - 10, width: 20, height: 20 } : geometry, style: { fill: colors[index % colors.length], stroke: '#ffffff', strokeWidth: 1 }, dataRef: { dataIndex: index, taskId: row.id, field: 'project' }, interactive: true })); addText(scene, `project-label-${index}`, row.name || row.title || row.label || row.id || `Item ${index + 1}`, plot.x - 8, y + 4, { fill: '#334155', font: '12px system-ui', textAnchor: 'end' }); if (row.progress != null && !milestone) scene.add(new SceneNode({ id: `project-progress-${index}`, type: 'rect', geometry: { x, y: y - 10, width: width * Math.max(0, Math.min(1, Number(row.progress) > 1 ? Number(row.progress) / 100 : Number(row.progress))), height: 20 }, style: { fill: '#0f172a', opacity: 0.25 }, interactive: false })); });
+    const criticalPath = new Set(spec.criticalPath || []);
+    rows.forEach((row, index) => (row.dependencies || []).forEach((dependency, dependencyIndex) => { const from = positions.get(dependency), to = positions.get(row.id); if (!from || !to) return; const critical = criticalPath.has(row.id) && criticalPath.has(dependency); const angle = Math.atan2(to.y - from.y, to.x - from.end), arrow = 7; scene.add(new SceneNode({ id: `dependency-${index}-${dependencyIndex}`, type: 'line', geometry: { x1: from.end, y1: from.y, x2: to.x, y2: to.y }, style: { stroke: critical ? '#dc2626' : '#64748b', strokeWidth: critical ? 2.5 : 1.5, opacity: 0.85 }, dataRef: { from: dependency, to: row.id, critical }, interactive: false, zIndex: -1 })); scene.add(new SceneNode({ id: `dependency-arrow-${index}-${dependencyIndex}`, type: 'path', geometry: { points: [{ x: to.x, y: to.y }, { x: to.x - arrow * Math.cos(angle - Math.PI / 6), y: to.y - arrow * Math.sin(angle - Math.PI / 6) }, { x: to.x - arrow * Math.cos(angle + Math.PI / 6), y: to.y - arrow * Math.sin(angle + Math.PI / 6) }] }, style: { stroke: critical ? '#dc2626' : '#64748b', fill: critical ? '#dc2626' : '#64748b', strokeWidth: 1 }, interactive: false, zIndex: -1 })); }));
+    return;
+  }
+  if (spec.type === 'burndown') {
+    const rows = projectRows(spec, data), dates = rows.map(row => new Date(row.date).getTime()).filter(Number.isFinite), min = Math.min(...(dates.length ? dates : [Date.now()])), max = Math.max(...(dates.length ? dates : [min + 86400000])), values = rows.map(row => Number(row.remaining ?? row.actual ?? row.value)).filter(Number.isFinite), maxValue = Math.max(1, ...values, ...rows.map(row => Number(row.ideal)).filter(Number.isFinite)); addProjectAxes(scene, plot, min, max); const point = row => ({ x: projectDate(row.date, min, max, plot), y: plot.y + plot.height - (Number(row.remaining ?? row.actual ?? row.value) / maxValue) * plot.height }); const actual = rows.map(point).filter(point => Number.isFinite(point.y)); if (actual.length > 1) scene.add(new SceneNode({ id: 'burndown-actual', type: 'path', geometry: { points: actual }, style: { stroke: colors[0], strokeWidth: 2 } })); const ideal = rows.map((row, index) => ({ x: projectDate(row.date, min, max, plot), y: plot.y + plot.height - (Number(row.ideal ?? maxValue * (1 - index / Math.max(1, rows.length - 1))) / maxValue) * plot.height })); if (ideal.length > 1) scene.add(new SceneNode({ id: 'burndown-ideal', type: 'path', geometry: { points: ideal }, style: { stroke: '#94a3b8', strokeWidth: 1, opacity: 0.8 } })); rows.forEach((row, index) => { if (index && Number(row.scopeChange)) { const x = projectDate(row.date, min, max, plot); scene.add(new SceneNode({ id: `burndown-scope-${index}`, type: 'line', geometry: { x1: x, y1: plot.y, x2: x, y2: plot.y + plot.height }, style: { stroke: '#f59e0b', strokeWidth: 1.5, opacity: 0.8 }, dataRef: { dataIndex: index, field: 'scopeChange', datum: row } })); } }); actual.forEach((point, index) => scene.add(new SceneNode({ id: `burndown-item-${index}`, type: 'circle', geometry: { cx: point.x, cy: point.y, r: 4 }, bounds: { x: point.x - 7, y: point.y - 7, width: 14, height: 14 }, style: { fill: colors[0] }, dataRef: { dataIndex: index, field: 'remaining', datum: rows[index] }, interactive: true }))); const last = actual.at(-1), lastRow = rows.at(-1); if (last && lastRow && Number(lastRow.remaining ?? lastRow.actual ?? lastRow.value) > 0 && rows.length > 1) { const slope = (Number(lastRow.remaining ?? lastRow.actual ?? lastRow.value) - Number(rows[0].remaining ?? rows[0].actual ?? rows[0].value)) / Math.max(1, dates.length - 1), projected = slope < 0 ? new Date(new Date(lastRow.date).getTime() + Math.ceil(Number(lastRow.remaining ?? lastRow.actual ?? lastRow.value) / -slope) * 86400000) : null; if (projected) addText(scene, 'burndown-projected', `Projected ${formatTime(projected, max - min)}`, Math.min(plot.x + plot.width, last.x + 12), plot.y + 18, { fill: '#dc2626', font: '12px system-ui' }); } return;
+  }
+  if (['flow', 'swimlane'].includes(spec.type)) {
+    const nodes = spec.nodes || spec.data.nodes || [], edges = spec.edges || spec.data.edges || [], lanes = spec.lanes || spec.data.lanes || [], laneHeight = plot.height / Math.max(1, lanes.length || 1); const nodeMap = new Map(); nodes.forEach((node, index) => { const laneIndex = lanes.length ? Math.max(0, lanes.findIndex(lane => lane.id === node.laneId)) : 0, columns = Math.max(1, Math.ceil(Math.sqrt(nodes.length))), column = index % columns, row = Math.floor(index / columns), x = plot.x + (column + 0.5) * plot.width / columns, y = lanes.length ? plot.y + laneIndex * laneHeight + laneHeight / 2 : plot.y + (row + 0.5) * plot.height / Math.max(1, Math.ceil(nodes.length / columns)); nodeMap.set(node.id, { ...node, x, y }); if (lanes.length) { scene.add(new SceneNode({ id: `lane-${laneIndex}`, type: 'rect', geometry: { x: plot.x, y: plot.y + laneIndex * laneHeight, width: plot.width, height: laneHeight }, style: { fill: laneIndex % 2 ? '#f8fafc' : '#ffffff', stroke: '#e2e8f0', strokeWidth: 1 }, interactive: false })); addText(scene, `lane-label-${laneIndex}`, lanes[laneIndex].label || lanes[laneIndex].id, plot.x - 8, plot.y + laneIndex * laneHeight + 18, { fill: '#475569', font: '12px system-ui', textAnchor: 'end' }); } }); edges.forEach((edge, index) => { const from = nodeMap.get(edge.from), to = nodeMap.get(edge.to); if (!from || !to) return; scene.add(new SceneNode({ id: `edge-${index}`, type: 'line', geometry: { x1: from.x, y1: from.y, x2: to.x, y2: to.y }, style: { stroke: '#64748b', strokeWidth: 1.5 }, dataRef: { edgeIndex: index, from: edge.from, to: edge.to } })); }); nodeMap.forEach((node, id) => { const geometry = { x: node.x - 48, y: node.y - 18, width: 96, height: 36 }; scene.add(new SceneNode({ id: `node-${id}`, type: 'rect', geometry, bounds: geometry, style: { fill: colors[0], stroke: '#ffffff', strokeWidth: 1 }, dataRef: { nodeId: id, field: 'node' }, interactive: true })); addText(scene, `node-label-${id}`, node.label || id, node.x, node.y + 4, { fill: '#ffffff', font: '12px system-ui', textAnchor: 'middle' }); });
+  }
+}
+
+function addBranding(scene, spec) {
+  if (spec.branding?.enabled !== true) return;
+  const x = Math.max(12, Number(spec.width) - 4);
+  const y = Math.max(12, Number(spec.height) - 4);
+  const fontFamily = spec.theme?.typography?.axis?.font ? `500 9px ${String(spec.theme.typography.axis.font).split(/px\s*/).slice(1).join('px ').trim() || 'system-ui'}` : '500 9px system-ui, sans-serif';
+  scene.add(new SceneNode({
+    id: 'branding-watermark',
+    type: 'text',
+    geometry: { text: 'Powered by iChart.js', x, y },
+    style: {
+      fill: spec.theme?.muted || '#536274',
+      opacity: 0.35,
+      font: fontFamily,
+      textAnchor: 'end',
+      textAlign: 'end',
+      textBaseline: 'bottom',
+      baseline: 'bottom',
+      pointerEvents: 'none',
+      ariaHidden: 'true',
+      role: 'presentation'
+    },
+    interactive: false,
+    zIndex: 9999,
+    decorative: true
+  }));
+}
+
+export function buildScene(spec) {
+  const baseSpec = styledSpec(spec);
+  const brandingEnabled = baseSpec.branding?.enabled === true;
+  const effectivePadding = {
+    top: Number(baseSpec.padding?.top ?? 48),
+    right: Number(baseSpec.padding?.right ?? 24) + (brandingEnabled ? 2 : 0),
+    bottom: Number(baseSpec.padding?.bottom ?? 48) + (brandingEnabled ? 18 : 0),
+    left: Number(baseSpec.padding?.left ?? 56),
+  };
+  spec = { ...baseSpec, padding: effectivePadding };
+  const isProjectFamily = ['gantt', 'timeline', 'milestone', 'burndown', 'flow', 'swimlane'].includes(spec.type);
+  if (isProjectFamily) {
+    const result = buildProjectScene(spec);
+    addBranding(result.scene, spec);
+    return result;
+  }
+  const data = spec.transform ? applyTransforms(spec.data, spec.transform) : normalizeData(spec.data);
+  if (spec.view && (spec.view.start !== undefined || spec.view.end !== undefined)) {
+    const start = Math.max(0, Number(spec.view.start) || 0), end = Math.min(data.rows.length, spec.view.end === undefined ? data.rows.length : Number(spec.view.end));
+    data.rows = data.rows.slice(start, Math.max(start, end));
+    data.viewOffset = start;
+  }
+  const scene = new Scene(spec.width, spec.height);
+  const state = layout(spec, data);
+  const colors = spec.colors;
+  addTitles(scene, spec);
+  if (!['pie', 'funnel', 'gauge', 'heatmap', 'radar'].includes(spec.type)) addAxes(scene, spec, state);
+  const hasDiagramNodes = ['flow', 'swimlane'].includes(spec.type) && (spec.nodes || spec.data.nodes)?.length;
+  if (!data.rows.length && !hasDiagramNodes) { addText(scene, 'empty', spec.emptyText || 'No data', spec.width / 2, spec.height / 2, { fill: spec.theme.muted, font: font(spec, 'subtitle'), textAnchor: 'middle' }); addBranding(scene, spec); return { scene, data, state }; }
+  const yField = state.yField;
+  const series = Array.isArray(spec.encoding.y) ? spec.encoding.y : [{ ...spec.encoding.y, name: spec.encoding.y?.name || spec.encoding.y?.field }];
+  if (spec.type === 'heatmap') addHeatmapScene(scene, spec, data, state, colors);
+  else if (spec.type === 'radar') { addRadarScene(scene, spec, data, state, colors); addLegend(scene, spec, data.rows.map((row, index) => ({ name: row.name || row.id || `Series ${index + 1}`, color: colors[index % colors.length] }))); }
+  else if (spec.type === 'line' || spec.type === 'area') {
+    const mode = typeof spec.stack === 'string' ? spec.stack : spec.stack?.mode, accumulators = data.rows.map(() => ({ positive: 0, negative: 0 }));
+    series.forEach((encoding, seriesIndex) => { const yMap = seriesIndex === 1 && !mode ? state.yRight : state.y, values = data.rows.map(row => Number(row[encoding.field])), totals = data.rows.map((row, index) => series.reduce((sum, item) => sum + Math.abs(Number(row[item.field]) || 0), 0) || Math.abs(values[index]) || 1); const points = [], bases = []; data.rows.forEach((row, index) => { let value = values[index]; if (!Number.isFinite(value)) return; if (mode === 'percent') value /= totals[index]; const accumulator = value >= 0 ? 'positive' : 'negative', start = mode ? accumulators[index][accumulator] : 0, end = mode ? start + value : value; if (mode) accumulators[index][accumulator] = end; points.push({ x: state.x(pick(row, spec.encoding.x, 'name')), y: yMap(end), row, index, value }); bases.push({ x: state.x(pick(row, spec.encoding.x, 'name')), y: yMap(start) }); }); if (spec.type === 'area' && points.length) scene.add(new SceneNode({ id: `area-fill-${seriesIndex}`, type: 'path', geometry: { points: [...bases.slice().reverse(), ...points.map(point => ({ x: point.x, y: point.y }))], closed: true }, style: { fill: `${colors[seriesIndex]}33`, stroke: 'transparent' } })); if (points.length > 1) scene.add(new SceneNode({ id: `series-${seriesIndex}-line`, type: 'path', geometry: { points }, style: { stroke: colors[seriesIndex], strokeWidth: 2, fill: 'none' } })); points.forEach(point => { const dataRef = { seriesIndex, dataIndex: point.index, field: encoding.field }; scene.add(new SceneNode({ id: `series-${seriesIndex}-item-${point.index}`, type: 'circle', geometry: { cx: point.x, cy: point.y, r: 5 }, bounds: { x: point.x - 8, y: point.y - 8, width: 16, height: 16 }, style: { fill: colors[seriesIndex] }, dataRef, interactive: true })); addMarkLabel(scene, spec, `series-${seriesIndex}-item-${point.index}`, point.value, point.x, point.y - 8, dataRef); }); });
+    addLegend(scene, spec, series.map((encoding, index) => ({ name: encoding.name || encoding.field, color: colors[index % colors.length] })));
+  } else if (spec.type === 'bar' || spec.type === 'column') {
+    const band = state.plot.width / Math.max(1, state.categories.length), bar = band * 0.58;
+    const mode = typeof spec.stack === 'string' ? spec.stack : spec.stack?.mode, accumulators = data.rows.map(() => ({ positive: 0, negative: 0 }));
+    series.forEach((encoding, seriesIndex) => { if (encoding.mark === 'line') { const yMap = encoding.axis === 'right' ? state.yRight : state.y, points = data.rows.map((row, index) => ({ x: state.x(row[state.xField]), y: yMap(row[encoding.field]), index, value: Number(row[encoding.field]) })).filter(point => Number.isFinite(point.y)); if (points.length > 1) scene.add(new SceneNode({ id: `series-${seriesIndex}-line`, type: 'path', geometry: { points }, style: { fill: 'none', stroke: colors[seriesIndex], strokeWidth: 2 } })); points.forEach(point => { const dataRef = { seriesIndex, dataIndex: point.index, field: encoding.field }; scene.add(new SceneNode({ id: `series-${seriesIndex}-item-${point.index}`, type: 'circle', geometry: { cx: point.x, cy: point.y, r: 4 }, bounds: { x: point.x - 7, y: point.y - 7, width: 14, height: 14 }, style: { fill: colors[seriesIndex] }, dataRef, interactive: true })); addMarkLabel(scene, spec, `series-${seriesIndex}-item-${point.index}`, point.value, point.x, point.y - 7, dataRef); }); return; } data.rows.forEach((row, index) => { let value = Number(row[encoding.field]) || 0; const barSeries = series.filter(item => item.mark !== 'line'), barSeriesIndex = barSeries.indexOf(encoding), total = barSeries.reduce((sum, item) => sum + Math.abs(Number(row[item.field]) || 0), 0) || 1; if (mode === 'percent') value /= total; const accumulator = value >= 0 ? 'positive' : 'negative', start = mode ? accumulators[index][accumulator] : 0, end = start + value; if (mode) accumulators[index][accumulator] = end; const yMap = encoding.axis === 'right' ? state.yRight : state.y, base = yMap(start), valueY = yMap(end); const vertical = spec.type === 'column'; const horizontalStart = state.plot.x + ((start - state.min) / (state.max - state.min || 1)) * state.plot.width, horizontalEnd = state.plot.x + ((end - state.min) / (state.max - state.min || 1)) * state.plot.width, rowBand = state.plot.height / Math.max(1, data.rows.length), totalHeight = rowBand * .62, itemHeight = mode ? totalHeight : totalHeight / Math.max(1, barSeries.length); const geometry = vertical ? { x: state.x(row[state.xField]) - bar / 2 + (mode ? 0 : seriesIndex * bar / Math.max(1, series.length)), y: Math.min(base, valueY), width: mode ? bar : bar / Math.max(1, series.length), height: Math.abs(base - valueY) } : { x: Math.min(horizontalStart, horizontalEnd), y: state.plot.y + index * rowBand + (rowBand - totalHeight) / 2 + (mode ? 0 : barSeriesIndex * itemHeight), width: Math.abs(horizontalEnd - horizontalStart), height: itemHeight }; const dataRef = { seriesIndex, dataIndex: index, field: encoding.field, stackStart: start, stackEnd: end }; scene.add(new SceneNode({ id: `series-${seriesIndex}-item-${index}`, type: 'rect', geometry, bounds: geometry, style: { fill: colors[seriesIndex] }, dataRef, interactive: true })); addMarkLabel(scene, spec, `series-${seriesIndex}-item-${index}`, value, vertical ? geometry.x + geometry.width / 2 : geometry.x + geometry.width + 12, vertical ? geometry.y - 5 : geometry.y + geometry.height / 2 + 4, dataRef); }); });
+    addLegend(scene, spec, series.map((encoding, index) => ({ name: encoding.name || encoding.field, color: colors[index % colors.length] })));
+  } else if (spec.type === 'scatter') {
+    data.rows.forEach((row, index) => { const xValue = Number(row[state.xField]), yValue = Number(row[state.yField]); if (!Number.isFinite(xValue) || !Number.isFinite(yValue)) return; const geometry = { cx: state.x(xValue), cy: state.y(yValue), r: 5 }, dataRef = { seriesIndex: 0, dataIndex: index, field: state.yField }; scene.add(new SceneNode({ id: `series-0-item-${index}`, type: 'circle', geometry, bounds: { x: geometry.cx - 8, y: geometry.cy - 8, width: 16, height: 16 }, style: { fill: colors[0] }, dataRef, interactive: true })); addMarkLabel(scene, spec, `series-0-item-${index}`, yValue, geometry.cx, geometry.cy - 8, dataRef); });
+  } else if (spec.type === 'pie') {
+    const categoryField = spec.encoding.category?.field || 'name', valueField = spec.encoding.value?.field || 'value', total = data.rows.reduce((sum, row) => sum + Math.max(0, Number(row[valueField]) || 0), 0), cx = spec.width / 2, cy = spec.height / 2 + 12, radius = Math.min(spec.width, spec.height) * 0.28, innerR = radius * Number(spec.innerRadius || 0); let angle = -Math.PI / 2;
+    if (!(total > 0)) { data.warnings.push({ code: 'ZERO_TOTAL', path: `encoding.value.${valueField}`, message: 'Pie requires a positive total.' }); addText(scene, 'pie-zero-total', spec.emptyText || 'No positive values', cx, cy, { fill: spec.theme.muted, font: font(spec, 'subtitle'), textAnchor: 'middle' }); }
+    else data.rows.forEach((row, index) => { const value = Math.max(0, Number(row[valueField]) || 0), end = angle + value / total * Math.PI * 2, middle = angle + (end - angle) / 2, dataRef = { seriesIndex: 0, dataIndex: index, category: row[categoryField], value }; scene.add(new SceneNode({ id: `series-0-item-${index}`, type: 'arc', geometry: { cx, cy, r: radius, innerR, start: angle, end }, bounds: { x: cx - radius, y: cy - radius, width: radius * 2, height: radius * 2 }, style: { fill: colors[index % colors.length], stroke: spec.theme.background, strokeWidth: 1 }, dataRef, interactive: true })); addMarkLabel(scene, spec, `series-0-item-${index}`, value / total, cx + Math.cos(middle) * radius * .72, cy + Math.sin(middle) * radius * .72, dataRef); angle = end; });
+    addLegend(scene, spec, data.rows.map((row, index) => ({ name: String(row[categoryField]), color: colors[index % colors.length] })));
+  } else if (spec.type === 'funnel') {
+    const valueField = spec.encoding.value?.field || 'value'; const maxValue = Math.max(...data.rows.map(row => Number(row[valueField]) || 0), 1); const segmentHeight = state.plot.height / data.rows.length;
+    data.rows.forEach((row, index) => { const value = Number(row[valueField]) || 0, ratio = Math.max(0.1, value / maxValue); const width = state.plot.width * ratio; const geometry = { x: state.plot.x + (state.plot.width - width) / 2, y: state.plot.y + index * segmentHeight, width, height: Math.max(2, segmentHeight - 3) }, dataRef = { seriesIndex: 0, dataIndex: index, field: valueField }; scene.add(new SceneNode({ id: `series-0-item-${index}`, type: 'rect', geometry, bounds: geometry, style: { fill: colors[index % colors.length] }, dataRef, interactive: true })); addMarkLabel(scene, spec, `series-0-item-${index}`, value, spec.width / 2, geometry.y + geometry.height / 2 + 4, dataRef); });
+  } else if (spec.type === 'gauge') {
+    const valueField = spec.encoding.value?.field || 'value', domain = spec.domain || [0, 100], rawValue = Number(data.rows[0]?.[valueField]) || 0, value = Math.max(Number(domain[0]), Math.min(Number(domain[1]), rawValue)), ratio = (value - Number(domain[0])) / (Number(domain[1]) - Number(domain[0]) || 1), cx = spec.width / 2, cy = spec.height * 0.62, radius = Math.min(spec.width, spec.height) * 0.3, start = Math.PI, end = start + Math.PI * ratio;
+    scene.add(new SceneNode({ id: 'gauge-background', type: 'arc', geometry: { cx, cy, r: radius, start: Math.PI, end: Math.PI * 2 }, style: { fill: spec.theme.grid } })); scene.add(new SceneNode({ id: 'gauge-value', type: 'arc', geometry: { cx, cy, r: radius, start, end }, style: { fill: colors[0] }, dataRef: { seriesIndex: 0, dataIndex: 0, value }, interactive: true })); addText(scene, 'gauge-label', formatValue(value, spec.labels?.format || spec.encoding.value?.format || { style: 'percent', ratio: false }), cx, cy - 12, { fill: spec.theme.text, font: font(spec, 'metric'), textAnchor: 'middle' });
+  }
+  addBranding(scene, spec);
+  return { scene, data, state };
+}

package/src/command.mjs

@@ -0,0 +1,93 @@
+/**
+ * Agent edit command normalization, validation, and capability discovery.
+ * Commands are JSON-safe, stable-ID based, and do not mutate input data.
+ */
+import { copyJSON, issue } from './schema.mjs';
+
+export const commandVersion = '1.0';
+export const operationTypes = ['updateField', 'updateRecord', 'updateTask', 'shiftTask', 'updateProgress', 'addDependency', 'removeDependency', 'updateMilestone', 'moveNode', 'moveNodes', 'moveNodeToLane', 'resizeNode', 'alignNodes', 'snapNodes', 'moveGroup', 'resizeGroup', 'assignNodesToGroup', 'duplicateGroup', 'deleteGroup', 'updateEdge', 'toggleGroupCollapse', 'addEdge', 'duplicateSelection', 'pasteSelection'];
+
+export function normalizeCommand(input) {
+  const command = copyJSON(input);
+  if (!command.version) command.version = commandVersion;
+  if (!command.type) command.type = 'edit';
+  if (!Array.isArray(command.operations)) command.operations = [];
+  return command;
+}
+
+export function validateCommand(command) {
+  const errors = [];
+  let value;
+  try { value = normalizeCommand(command); } catch (error) { return { valid: false, errors: [issue('INVALID_COMMAND', 'command', error.message)], command: null }; }
+  if (value.version !== commandVersion) errors.push(issue('COMMAND_VERSION', 'command.version', `Unsupported command version: ${value.version}.`, 'Use command version 1.0.'));
+  if (value.type !== 'edit' && value.type !== 'layout-edit') errors.push(issue('COMMAND_TYPE', 'command.type', 'Command type must be edit or layout-edit.'));
+  if (!Array.isArray(value.operations) || !value.operations.length) errors.push(issue('EMPTY_COMMAND', 'command.operations', 'At least one operation is required.'));
+  value.operations.forEach((operation, index) => {
+    const path = `command.operations.${index}`;
+    if (!operation || typeof operation.op !== 'string' || !operationTypes.includes(operation.op)) errors.push(issue('OPERATION_TYPE', `${path}.op`, 'Unsupported edit operation.'));
+    if (operationTypes.includes(operation.op) && !['moveNodes', 'alignNodes', 'snapNodes', 'moveGroup', 'resizeGroup', 'assignNodesToGroup', 'duplicateGroup', 'deleteGroup', 'toggleGroupCollapse', 'duplicateSelection', 'pasteSelection', 'addEdge'].includes(operation.op) && (typeof operation.recordId !== 'string' && typeof operation.taskId !== 'string' && typeof operation.nodeId !== 'string' && typeof operation.edgeId !== 'string')) errors.push(issue('OPERATION_TARGET', path, 'Operation requires a stable recordId, taskId, nodeId, or edgeId.'));
+    if (['updateField', 'updateRecord', 'updateTask'].includes(operation.op) && !operation.changes && operation.op !== 'updateField') errors.push(issue('OPERATION_CHANGES', `${path}.changes`, 'Operation requires changes.'));
+    if (operation.op === 'updateField' && typeof operation.field !== 'string') errors.push(issue('OPERATION_FIELD', `${path}.field`, 'updateField requires a field name.'));
+    if (operation.op === 'shiftTask' && (typeof operation.days !== 'number' || !Number.isFinite(operation.days))) errors.push(issue('OPERATION_DAYS', `${path}.days`, 'shiftTask requires finite numeric days.'));
+    if (['addDependency', 'removeDependency'].includes(operation.op) && typeof operation.dependencyId !== 'string') errors.push(issue('OPERATION_DEPENDENCY', `${path}.dependencyId`, 'Dependency operations require dependencyId.'));
+    if (operation.op === 'moveNode' && (!operation.position || typeof operation.position.x !== 'number' || typeof operation.position.y !== 'number')) errors.push(issue('OPERATION_POSITION', `${path}.position`, 'moveNode requires numeric x and y.'));
+    if (operation.op === 'moveNodes' && (!Array.isArray(operation.nodeIds) || !operation.nodeIds.length || typeof operation.delta?.x !== 'number' || typeof operation.delta?.y !== 'number')) errors.push(issue('OPERATION_MOVE_NODES', path, 'moveNodes requires nodeIds and numeric delta.'));
+    if (operation.op === 'moveGroup' && (typeof operation.groupId !== 'string' || typeof operation.delta?.x !== 'number' || typeof operation.delta?.y !== 'number')) errors.push(issue('OPERATION_MOVE_GROUP', path, 'moveGroup requires groupId and numeric delta.'));
+    if (operation.op === 'resizeGroup' && (typeof operation.groupId !== 'string' || typeof operation.size?.width !== 'number' || typeof operation.size?.height !== 'number' || operation.size.width <= 0 || operation.size.height <= 0)) errors.push(issue('OPERATION_RESIZE_GROUP', path, 'resizeGroup requires groupId and a positive numeric size.'));
+    if (operation.op === 'assignNodesToGroup' && ((!Array.isArray(operation.nodeIds) || !operation.nodeIds.length) || operation.groupId !== null && typeof operation.groupId !== 'string')) errors.push(issue('OPERATION_GROUP_MEMBERS', path, 'assignNodesToGroup requires nodeIds and a groupId or null.'));
+    if (operation.op === 'duplicateGroup' && (typeof operation.groupId !== 'string' || operation.offset !== undefined && (typeof operation.offset?.x !== 'number' || typeof operation.offset?.y !== 'number'))) errors.push(issue('OPERATION_DUPLICATE_GROUP', path, 'duplicateGroup requires groupId and an optional numeric offset.'));
+    if (operation.op === 'deleteGroup' && (typeof operation.groupId !== 'string' || operation.policy !== undefined && !['ungroup', 'delete-members'].includes(operation.policy))) errors.push(issue('OPERATION_DELETE_GROUP', path, 'deleteGroup requires groupId and policy ungroup or delete-members.'));
+    if (['alignNodes', 'snapNodes'].includes(operation.op) && (!Array.isArray(operation.nodeIds) || !operation.nodeIds.length)) errors.push(issue('OPERATION_NODE_IDS', path, `${operation.op} requires nodeIds.`));
+    if (operation.op === 'alignNodes' && !['left', 'center', 'right', 'top', 'middle', 'bottom'].includes(operation.alignment)) errors.push(issue('OPERATION_ALIGNMENT', `${path}.alignment`, 'Use left, center, right, top, middle, or bottom.'));
+    if (operation.op === 'resizeNode' && (!operation.size || typeof operation.size.width !== 'number' || typeof operation.size.height !== 'number' || operation.size.width <= 0 || operation.size.height <= 0)) errors.push(issue('OPERATION_SIZE', `${path}.size`, 'resizeNode requires positive numeric width and height.'));
+    if (operation.op === 'moveNodeToLane' && typeof operation.laneId !== 'string') errors.push(issue('OPERATION_LANE', `${path}.laneId`, 'moveNodeToLane requires laneId.'));
+    if (operation.op === 'updateEdge' && (!operation.changes || typeof operation.changes !== 'object')) errors.push(issue('OPERATION_CHANGES', `${path}.changes`, 'updateEdge requires changes.'));
+    if (operation.op === 'toggleGroupCollapse' && typeof operation.groupId !== 'string') errors.push(issue('OPERATION_GROUP', `${path}.groupId`, 'toggleGroupCollapse requires groupId.'));
+    if (operation.op === 'addEdge') {
+      if (typeof operation.from !== 'string' || typeof operation.to !== 'string') errors.push(issue('OPERATION_EDGE_ENDPOINT', path, 'addEdge requires from and to node IDs.'));
+      if (operation.id !== undefined && typeof operation.id !== 'string') errors.push(issue('OPERATION_EDGE_ID', `${path}.id`, 'Edge id must be a string when provided.'));
+      if (operation.fromPort !== undefined && typeof operation.fromPort !== 'string') errors.push(issue('OPERATION_EDGE_PORT', `${path}.fromPort`, 'fromPort must be a string.'));
+      if (operation.toPort !== undefined && typeof operation.toPort !== 'string') errors.push(issue('OPERATION_EDGE_PORT', `${path}.toPort`, 'toPort must be a string.'));
+    }
+    if (operation.op === 'duplicateSelection' && (!Array.isArray(operation.nodeIds) || !operation.nodeIds.length)) errors.push(issue('OPERATION_NODE_IDS', path, 'duplicateSelection requires nodeIds.'));
+    if (operation.op === 'pasteSelection') {
+      if (!Array.isArray(operation.nodes) || !operation.nodes.length) errors.push(issue('OPERATION_CLIPBOARD', `${path}.nodes`, 'pasteSelection requires copied nodes.'));
+      if (operation.edges !== undefined && !Array.isArray(operation.edges)) errors.push(issue('OPERATION_CLIPBOARD', `${path}.edges`, 'pasteSelection edges must be an array when provided.'));
+      if (operation.offset !== undefined && (typeof operation.offset?.x !== 'number' || typeof operation.offset?.y !== 'number')) errors.push(issue('OPERATION_POSITION', `${path}.offset`, 'pasteSelection offset requires numeric x and y.'));
+    }
+  });
+  return { valid: errors.length === 0, errors, command: value };
+}
+
+export function commandCapabilities(schema) {
+  const fields = schema?.fields || {};
+  const can = name => fields[name]?.editable !== false && fields[name]?.agentEditable !== false;
+  const flowNode = schema?.name === 'flow-node';
+  const flowEdge = schema?.name === 'flow-edge';
+  return {
+    updateField: Object.keys(fields).filter(can),
+    updateRecord: true,
+    updateTask: schema?.name === 'project-task',
+    shiftTask: schema?.name === 'project-task' && can('start') && can('end'),
+    updateProgress: schema?.name === 'project-task' && can('progress'),
+    addDependency: schema?.name === 'project-task' && can('dependencies'),
+    removeDependency: schema?.name === 'project-task' && can('dependencies'),
+    updateMilestone: schema?.name === 'milestone',
+    moveNode: flowNode && can('position'),
+    moveNodes: flowNode && can('position'),
+    alignNodes: flowNode && can('position'),
+    snapNodes: flowNode && can('position'),
+    moveGroup: flowNode && can('position'),
+    resizeGroup: flowNode && can('position') && can('size'),
+    assignNodesToGroup: flowNode,
+    duplicateGroup: flowNode,
+    deleteGroup: flowNode,
+    moveNodeToLane: flowNode && can('laneId'),
+    resizeNode: flowNode && can('size'),
+    toggleGroupCollapse: flowNode,
+    duplicateSelection: flowNode,
+    pasteSelection: flowNode,
+    updateEdge: flowEdge,
+    addEdge: flowEdge
+  };
+}