@taylorwong/ichartjs 2.0.1

package/src/data.mjs

@@ -0,0 +1,75 @@
+/**
+ * Data inspection, normalization, and immutable transformation pipeline.
+ * Provides the common row model consumed by chart and Agent APIs.
+ */
+import { binData } from './transforms.mjs';
+export { binData, applyTransforms } from './transforms.mjs';
+function typeOf(values) {
+  const usable = values.filter(value => value !== null && value !== undefined && value !== '');
+  if (!usable.length) return 'unknown';
+  if (usable.every(value => typeof value === 'number' || (typeof value === 'string' && value.trim() !== '' && Number.isFinite(Number(value))))) return 'quantitative';
+  if (usable.every(value => !Number.isNaN(Date.parse(value)) && typeof value === 'string')) return 'temporal';
+  return 'category';
+}
+
+function inferUnit(name, values) {
+  const key = String(name).toLowerCase();
+  if (/(percent|percentage|rate|ratio|progress|utilization)/.test(key)) return 'percentage';
+  if (/(date|time|day|month|year|created|updated|start|end)/.test(key) && values.some(value => typeof value === 'string' && !Number.isNaN(Date.parse(value)))) return 'date';
+  if (/(price|cost|revenue|amount|sales)/.test(key)) return 'currency-unknown';
+  if (/(duration|days|hours|minutes)/.test(key)) return 'duration-unknown';
+  return null;
+}
+
+export function normalizeData(input) {
+  let values = [];
+  if (Array.isArray(input)) {
+    if (input.every(row => Array.isArray(row))) values = input.map(row => ({ name: row[0], value: row[1] }));
+    else values = input.map(row => ({ ...row }));
+  } else if (input && Array.isArray(input.values)) {
+    values = input.values.map(row => ({ ...row }));
+  } else if (input && Array.isArray(input.categories) && Array.isArray(input.series)) {
+    input.series.forEach(series => input.categories.forEach((category, index) => values.push({ name: category, series: series.name, value: series.data[index] })));
+  }
+  const fields = [];
+  values.forEach(row => Object.keys(row).forEach(field => { if (!fields.includes(field)) fields.push(field); }));
+  const warnings = [];
+  const normalized = values.map((row, rowIndex) => {
+    const copy = { ...row };
+    fields.forEach(field => {
+      if (copy[field] !== null && copy[field] !== undefined && copy[field] !== '' && typeof copy[field] === 'string' && Number.isFinite(Number(copy[field]))) copy[field] = Number(copy[field]);
+    });
+    if (Object.values(copy).some(value => value === null || value === undefined || value === '')) warnings.push({ code: 'MISSING_VALUE', row: rowIndex, message: 'Row contains a missing value.' });
+    return copy;
+  });
+  const fieldInfo = fields.map(name => {
+    const valuesForField = normalized.map(row => row[name]);
+    const numbers = valuesForField.filter(value => typeof value === 'number' && Number.isFinite(value));
+    const usable = valuesForField.filter(value => value !== null && value !== undefined && value !== '');
+    const type = typeOf(valuesForField), dates = type === 'temporal' ? usable.map(value => Date.parse(value)).filter(Number.isFinite) : [], cardinality = new Set(usable.map(value => String(value))).size, identifier = /(^id$|[_-]id$|^key$|[_-]key$)/i.test(name);
+    return { name, type, role: identifier ? 'identifier' : type === 'quantitative' ? 'measure' : type === 'temporal' ? 'temporal-dimension' : 'dimension', unit: inferUnit(name, usable), cardinality, validCount: usable.length, nullCount: valuesForField.length - usable.length, min: numbers.length ? Math.min(...numbers) : undefined, max: numbers.length ? Math.max(...numbers) : undefined, temporalMin: dates.length ? new Date(Math.min(...dates)).toISOString() : undefined, temporalMax: dates.length ? new Date(Math.max(...dates)).toISOString() : undefined };
+  });
+  return { rows: normalized, fields: fieldInfo, warnings };
+}
+
+export function inspectData(input) {
+  const data = normalizeData(input);
+  const dimensions = data.fields.filter(field => field.role === 'dimension' || field.role === 'temporal-dimension').map(field => field.name);
+  const measures = data.fields.filter(field => field.type === 'quantitative').map(field => field.name);
+  return { version: '1.0', rows: data.rows.length, fields: data.fields, dimensions, measures, temporalFields: data.fields.filter(field => field.type === 'temporal').map(field => field.name), missingValueCount: data.fields.reduce((sum, field) => sum + field.nullCount, 0), warnings: data.warnings };
+}
+
+export class DataPipeline {
+  constructor(input) { this._rows = normalizeData(input).rows; }
+  filter(predicate) { this._rows = this._rows.filter(predicate); return this; }
+  sortBy(field, direction = 'asc') { this._rows = [...this._rows].sort((a, b) => { const left = a[field], right = b[field]; const result = left === right ? 0 : left > right ? 1 : -1; return direction === 'desc' ? -result : result; }); return this; }
+  groupBy(field) { this._groupField = field; return this; }
+  sum(field, output = field) { if (!this._groupField) return this; const groups = new Map(); this._rows.forEach(row => { const key = row[this._groupField]; const item = groups.get(key) || { [this._groupField]: key, [output]: 0 }; item[output] += Number(row[field]) || 0; groups.set(key, item); }); this._rows = [...groups.values()]; return this; }
+  average(field, output = field) { if (!this._groupField) return this; const groups = new Map(); this._rows.forEach(row => { const key = row[this._groupField]; const item = groups.get(key) || { [this._groupField]: key, [output]: 0, __count: 0 }; item[output] += Number(row[field]) || 0; item.__count += 1; groups.set(key, item); }); this._rows = [...groups.values()].map(row => { row[output] /= row.__count; delete row.__count; return row; }); return this; }
+  topN(field, count) { this._rows = [...this._rows].sort((a, b) => (Number(b[field]) || 0) - (Number(a[field]) || 0)).slice(0, count); return this; }
+  percentage(field, output = field) { const total = this._rows.reduce((sum, row) => sum + (Number(row[field]) || 0), 0) || 1; this._rows = this._rows.map(row => ({ ...row, [output]: (Number(row[field]) || 0) / total })); return this; }
+  bin(field, options = {}) { this._rows = binData(this._rows, { ...options, field }).rows; return this; }
+  toArray() { return this._rows.map(row => ({ ...row })); }
+}
+
+export function data(input) { return new DataPipeline(input); }

package/src/diagram-interaction.mjs

@@ -0,0 +1,195 @@
+/**
+ * Diagram pointer, selection, keyboard, and editing interaction helpers.
+ * Converts user gestures into validated layout and structure edits.
+ */
+import { buildScene } from './charts.mjs';
+
+export const isDiagram = chart => ['flow', 'swimlane'].includes(chart.spec.type);
+
+function focusableNodes(chart) {
+  const items = [];
+  chart.model.scene.walk(node => {
+    if (!node.interactive) return;
+    if (!/^node-|^group-|^port-/.test(node.id)) return;
+    items.push(node);
+  });
+  return items;
+}
+
+function center(node) {
+  if (node.geometry?.cx != null && node.geometry?.cy != null) return { x: node.geometry.cx, y: node.geometry.cy };
+  return { x: node.bounds?.x + node.bounds?.width / 2 || node.geometry?.x || 0, y: node.bounds?.y + node.bounds?.height / 2 || node.geometry?.y || 0 };
+}
+
+function clearConnectPreview(chart) {
+  chart.model.scene.root.children = chart.model.scene.root.children.filter(node => node.id !== 'diagram-connect-preview');
+}
+
+function paintConnectPreview(chart, start, end) {
+  clearConnectPreview(chart);
+  chart.model.scene.add({ id: 'diagram-connect-preview', type: 'path', geometry: { points: [start, end] }, style: { fill: 'none', stroke: '#2563eb', strokeWidth: 2, opacity: 0.65 }, zIndex: 101 });
+  if (chart.renderer.container) chart.renderer.render(chart.model.scene);
+}
+
+export function paintSelection(chart) {
+  for (const [id] of chart._selected) {
+    const node = chart.model.scene.find(id);
+    if (node) { node.selected = true; chart._selected.set(id, node.dataRef); }
+    else chart._selected.delete(id);
+  }
+  chart.model.scene.walk(node => {
+    if (node.id === chart._diagramFocusTarget) node.highlighted = true;
+    if (node.selected && node.id.startsWith('node-')) { node.style.stroke = '#f59e0b'; node.style.strokeWidth = 3; }
+    if (node.selected && node.id.startsWith('group-')) { node.style.stroke = '#2563eb'; node.style.strokeWidth = 2; }
+  });
+}
+
+export function diagramPointer(chart, phase, event, target) {
+  if (!isDiagram(chart)) return false;
+  if (event.type === 'pointerleave') return true;
+  const point = chart._eventPoint(event, target);
+  if (phase === 'start') {
+    if (event.button != null && event.button !== 0) return true;
+    if (chart._diagramGesture) return true;
+    chart._suppressDiagramClick = false;
+    target.focus?.({ preventScroll: true });
+    target.setPointerCapture?.(event.pointerId);
+    const hit = chart.model.scene.hit(point.x, point.y), additive = Boolean(event.shiftKey || event.ctrlKey || event.metaKey);
+    const nodeId = hit?.dataRef?.nodeId, groupId = hit?.dataRef?.groupId, portId = hit?.dataRef?.portId;
+    if (groupId && !nodeId) chart.selectGroup(groupId, { additive });
+    else if (nodeId) {
+      if (additive && chart.getSelectedNodeIds().includes(nodeId)) chart.selectNodes(chart.getSelectedNodeIds().filter(id => id !== nodeId));
+      else if (additive || !chart.getSelectedNodeIds().includes(nodeId)) chart.selectNodes([nodeId], { additive });
+    } else if (!additive) chart.clearSelection();
+    const mode = portId && chart.spec.editing?.enabled ? 'connect' : nodeId && chart.spec.interaction?.drag && chart.spec.editing?.enabled ? 'nodes' : !hit && (additive || chart.spec.interaction?.brush) ? 'box' : !hit && chart.spec.interaction?.pan ? 'pan' : groupId ? 'group' : 'select';
+    const view = chart.model.state.view, positions = {};
+    chart.getSelectedNodeIds().forEach(id => {
+      const geometry = chart.model.scene.find(`node-${id}`)?.geometry;
+      if (!geometry) return;
+      positions[id] = { x: (geometry.x - view.offsetX) / view.scale, y: (geometry.y - view.offsetY) / view.scale };
+    });
+    chart._diagramGesture = { mode, point, previous: point, positions, view: { ...view }, pointerId: event.pointerId, revision: chart._revision, additive, selected: chart.getSelectedNodeIds(), moved: false, hitId: hit?.id, groupId, nodeId, portId };
+    if (mode === 'connect' && hit) paintConnectPreview(chart, center(hit), point);
+    return true;
+  }
+  const gesture = chart._diagramGesture;
+  if (!gesture || gesture.pointerId !== event.pointerId) return true;
+  if (phase === 'move') {
+    if (chart._revision !== gesture.revision) { chart._diagramGesture = null; chart.render(); return true; }
+    if (Math.hypot(point.x - gesture.point.x, point.y - gesture.point.y) < 3 && !gesture.moved) return true;
+    gesture.moved = true;
+    if (gesture.mode === 'connect') {
+      const source = chart.model.scene.find(gesture.hitId);
+      if (source) {
+        paintConnectPreview(chart, center(source), point);
+        chart.emit('connectionpreview', { chart, source: source.dataRef, coordinate: point });
+      }
+    } else if (gesture.mode === 'nodes') {
+      let delta = { x: (point.x - gesture.point.x) / gesture.view.scale, y: (point.y - gesture.point.y) / gesture.view.scale };
+      const anchor = Object.values(gesture.positions)[0], grid = chart.spec.diagram?.grid ?? 8;
+      if (anchor && chart.spec.diagram?.snap !== false && !event.altKey) delta = { x: Math.round((anchor.x + delta.x) / grid) * grid - anchor.x, y: Math.round((anchor.y + delta.y) / grid) * grid - anchor.y };
+      gesture.operations = Object.entries(gesture.positions).map(([nodeId, position]) => ({ op: 'moveNode', nodeId, position: { x: position.x + delta.x, y: position.y + delta.y } }));
+      const positions = new Map(gesture.operations.map(operation => [operation.nodeId, operation.position]));
+      const nodes = (chart.spec.nodes ?? chart.spec.data.nodes).map(node => positions.has(node.id) ? { ...node, position: positions.get(node.id) } : node);
+      chart.model = buildScene({ ...chart.spec, nodes });
+      paintSelection(chart);
+      if (chart.renderer.container) chart.renderer.render(chart.model.scene);
+      chart.emit('drag', { chart, nodeIds: gesture.selected, coordinate: point });
+    } else if (gesture.mode === 'box') {
+      chart.model.scene.root.children = chart.model.scene.root.children.filter(node => node.id !== 'diagram-selection-box');
+      chart.model.scene.add({ id: 'diagram-selection-box', type: 'rect', geometry: { x: Math.min(point.x, gesture.point.x), y: Math.min(point.y, gesture.point.y), width: Math.abs(point.x - gesture.point.x), height: Math.abs(point.y - gesture.point.y) }, style: { fill: '#93c5fd', stroke: '#2563eb', opacity: 0.25 }, zIndex: 100 });
+      if (chart.renderer.container) chart.renderer.render(chart.model.scene);
+    } else if (gesture.mode === 'pan') chart.panBy({ x: point.x - gesture.previous.x, y: point.y - gesture.previous.y });
+    gesture.previous = point;
+    return true;
+  }
+  chart._diagramGesture = null;
+  chart._suppressDiagramClick = gesture.moved;
+  if (target.hasPointerCapture?.(event.pointerId)) target.releasePointerCapture(event.pointerId);
+  const cancelled = event.type === 'pointercancel' || chart._revision !== gesture.revision;
+  if (gesture.mode === 'connect') clearConnectPreview(chart);
+  chart.render();
+  if (!cancelled && gesture.moved && gesture.mode === 'nodes' && gesture.operations?.length) {
+    const preview = chart.previewEdit({ type: 'layout-edit', reason: 'Drag diagram selection', operations: gesture.operations });
+    if (preview.requiresConfirmation) chart.emit('editrequest', { chart, preview, source: 'pointer' });
+    else chart.applyEdit(preview.command, { preview, source: 'pointer', confirmed: true });
+  } else if (!cancelled && gesture.moved && gesture.mode === 'box') {
+    chart.selectBox(gesture.point, point);
+    if (gesture.additive) chart.selectNodes(gesture.selected, { additive: true });
+  } else if (!cancelled && gesture.mode === 'connect') {
+    const hit = chart.model.scene.hit(point.x, point.y), targetNodeId = hit?.dataRef?.nodeId, targetPortId = hit?.dataRef?.portId;
+    if (targetNodeId && targetNodeId !== gesture.nodeId) chart.connectNodes({ from: gesture.nodeId, to: targetNodeId, ...(gesture.portId ? { fromPort: gesture.portId } : {}), ...(targetPortId ? { toPort: targetPortId } : {}) }, { confirmed: true, source: 'pointer' });
+    else chart.emit('connectioncancel', { chart, sourceNodeId: gesture.nodeId, sourcePortId: gesture.portId });
+  } else if (!cancelled && !gesture.moved && gesture.mode === 'group' && gesture.groupId) chart.toggleGroupCollapse(gesture.groupId, { confirmed: true, source: 'pointer' });
+  chart.emit('dragend', { chart, cancelled, nodeIds: gesture.selected });
+  return true;
+}
+
+export function diagramKeyboard(chart, event) {
+  if (!isDiagram(chart)) return false;
+  const modifier = event.ctrlKey || event.metaKey, key = event.key.toLowerCase(), nodes = focusableNodes(chart);
+  if (key === 'escape') {
+    chart._diagramGesture = null;
+    if (chart._keyboardConnection) {
+      const source = chart._keyboardConnection;
+      chart._keyboardConnection = null;
+      clearConnectPreview(chart);
+      chart.render();
+      chart.emit('connectioncancel', { chart, sourceNodeId: source.nodeId, sourcePortId: source.portId, source: 'keyboard' });
+    } else chart.clearSelection();
+    event.preventDefault();
+    return true;
+  }
+  if (modifier && key === 'a') { chart.selectNodes(chart.model.data.rows.map(row => row.id)); event.preventDefault(); return true; }
+  if (modifier && key === 'c') { chart.copySelection(); event.preventDefault(); return true; }
+  if (modifier && key === 'v') { chart.pasteSelection({ confirmed: true, source: 'keyboard' }); event.preventDefault(); return true; }
+  if (modifier && key === 'd') { chart.duplicateSelection({ confirmed: true, source: 'keyboard' }); event.preventDefault(); return true; }
+  if (modifier && ['z', 'y'].includes(key) && chart.spec.editing?.enabled) { chart[key === 'y' || event.shiftKey ? 'redo' : 'undo'](); event.preventDefault(); return true; }
+  if (['tab', 'enter', ' '].includes(key)) {
+    const step = event.shiftKey ? -1 : 1;
+    if (!nodes.length) return true;
+    if (key === 'tab') chart._diagramFocus = ((chart._diagramFocus ?? (step > 0 ? -1 : 0)) + step + nodes.length) % nodes.length;
+    const target = nodes[chart._diagramFocus ?? 0];
+    chart._diagramFocusTarget = target?.id;
+    if (target?.id?.startsWith('node-')) chart.selectNodes([target.dataRef.nodeId], { additive: key === ' ' && event.shiftKey });
+    else if (target?.id?.startsWith('group-')) chart.selectGroup(target.dataRef.groupId, { additive: key === ' ' && event.shiftKey });
+    else if (target?.id?.startsWith('port-') && target.dataRef?.nodeId) chart.selectNodes([target.dataRef.nodeId], { additive: key === ' ' && event.shiftKey });
+    if (chart._keyboardConnection && target) {
+      const source = chart.model.scene.find(chart._keyboardConnection.targetId);
+      if (source) paintConnectPreview(chart, center(source), center(target));
+      chart.emit('connectionpreview', { chart, source: chart._keyboardConnection, target: target.dataRef, sourceType: 'keyboard' });
+    }
+    if (key !== 'tab') {
+      if (target?.id?.startsWith('port-') && chart.spec.editing?.enabled) {
+        if (!chart._keyboardConnection) {
+          chart._keyboardConnection = { nodeId: target.dataRef.nodeId, portId: target.dataRef.portId, targetId: target.id };
+          paintConnectPreview(chart, center(target), center(target));
+          chart.emit('connectionpreview', { chart, source: chart._keyboardConnection, target: null, sourceType: 'keyboard' });
+        } else if (target.dataRef.nodeId !== chart._keyboardConnection.nodeId) {
+          const source = chart._keyboardConnection;
+          chart._keyboardConnection = null;
+          clearConnectPreview(chart);
+          chart.connectNodes({ from: source.nodeId, to: target.dataRef.nodeId, fromPort: source.portId, toPort: target.dataRef.portId }, { confirmed: true, source: 'keyboard' });
+        }
+      } else if (target?.id?.startsWith('group-') && chart.spec.editing?.enabled && !chart._keyboardConnection) chart.toggleGroupCollapse(target.dataRef.groupId, { confirmed: true, source: 'keyboard' });
+      event.preventDefault();
+    }
+    return true;
+  }
+  if (!['arrowright', 'arrowleft', 'arrowup', 'arrowdown'].includes(key)) return false;
+  if (chart.spec.editing?.enabled && chart.getSelectedNodeIds().length) {
+    const step = event.shiftKey ? 10 : 1, delta = { x: key === 'arrowright' ? step : key === 'arrowleft' ? -step : 0, y: key === 'arrowdown' ? step : key === 'arrowup' ? -step : 0 };
+    const preview = chart.previewEdit({ type: 'layout-edit', reason: 'Keyboard move', operations: [{ op: 'moveNodes', nodeIds: chart.getSelectedNodeIds(), delta }] });
+    if (preview.requiresConfirmation) chart.emit('editrequest', { chart, preview, source: 'keyboard' });
+    else chart.applyEdit(preview.command, { preview, source: 'keyboard', confirmed: true });
+  } else if (nodes.length) {
+    const step = ['arrowright', 'arrowdown'].includes(key) ? 1 : -1;
+    chart._diagramFocus = ((chart._diagramFocus ?? -1) + step + nodes.length) % nodes.length;
+    const target = nodes[chart._diagramFocus];
+    chart._diagramFocusTarget = target.id;
+    if (target.id.startsWith('node-')) chart.selectNodes([target.dataRef.nodeId]);
+    else if (target.id.startsWith('group-')) chart.selectGroup(target.dataRef.groupId);
+  }
+  event.preventDefault();
+  return true;
+}

package/src/diagram.mjs

@@ -0,0 +1,135 @@
+/**
+ * Diagram data model, validation, deterministic layout, and edge routing.
+ * Supports nodes, edges, lanes, flat groups, ports, and 2D routing modes.
+ */
+import { copyJSON } from './schema.mjs';
+
+export const diagramLayoutModes = ['manual', 'layered', 'tree', 'radial'];
+export const edgeRoutingModes = ['straight', 'orthogonal', 'curved'];
+
+const finite = value => typeof value === 'number' && Number.isFinite(value);
+
+export function normalizeDiagramSpec(spec = {}) {
+  const data = spec.data || {};
+  const nodes = copyJSON(spec.nodes ?? data.nodes ?? data.values ?? []);
+  const edges = copyJSON(spec.edges ?? data.edges ?? []);
+  const lanes = copyJSON(spec.lanes ?? data.lanes ?? []);
+  return { ...copyJSON(spec), nodes, edges, lanes, groups: copyJSON(spec.groups ?? data.groups ?? []), diagram: { layout: spec.diagram?.layout || 'layered', routing: spec.diagram?.routing || 'orthogonal', snap: spec.diagram?.snap ?? true, grid: spec.diagram?.grid ?? 8 } };
+}
+
+export function validateDiagram(spec = {}) {
+  const errors = [], normalized = normalizeDiagramSpec(spec), nodes = normalized.nodes, edges = normalized.edges, lanes = normalized.lanes;
+  const nodeIds = new Set(), laneIds = new Set(lanes.map(lane => lane.id));
+  const groupIds = new Set();
+  normalized.groups.forEach((group, index) => {
+    if (typeof group?.id !== 'string' || !group.id) errors.push({ code: 'GROUP_ID', path: `groups.${index}.id`, message: 'Groups require stable IDs.' });
+    else if (groupIds.has(group.id)) errors.push({ code: 'DUPLICATE_GROUP_ID', path: `groups.${index}.id`, message: 'Group IDs must be unique.' });
+    else groupIds.add(group.id);
+    if (group?.parentId) errors.push({ code: 'NESTED_GROUP_UNSUPPORTED', path: `groups.${index}.parentId`, message: '5B supports flat groups, not nested groups.' });
+  });
+  nodes.forEach((node, index) => {
+    if (typeof node.id !== 'string' || !node.id) errors.push({ code: 'NODE_ID', path: `nodes.${index}.id`, message: 'Diagram nodes require stable string IDs.' });
+    else if (nodeIds.has(node.id)) errors.push({ code: 'DUPLICATE_NODE_ID', path: `nodes.${index}.id`, message: `Duplicate node ID: ${node.id}.` });
+    else nodeIds.add(node.id);
+    if (node.position && (!finite(node.position.x) || !finite(node.position.y))) errors.push({ code: 'NODE_POSITION', path: `nodes.${index}.position`, message: 'Node positions must contain finite x and y.' });
+    if (node.laneId && lanes.length && !laneIds.has(node.laneId)) errors.push({ code: 'MISSING_LANE', path: `nodes.${index}.laneId`, message: `Unknown lane ID: ${node.laneId}.` });
+    if (node.size && (!finite(node.size.width) || !finite(node.size.height) || node.size.width <= 0 || node.size.height <= 0)) errors.push({ code: 'NODE_SIZE', path: `nodes.${index}.size`, message: 'Node sizes must be finite and positive.' });
+    if (node.groupId && !groupIds.has(node.groupId)) errors.push({ code: 'MISSING_GROUP', path: `nodes.${index}.groupId`, message: `Unknown group ${node.groupId}.` });
+    if (node.ports && (!Array.isArray(node.ports) || node.ports.some(port => !port || typeof port.id !== 'string' || !port.id))) errors.push({ code: 'NODE_PORTS', path: `nodes.${index}.ports`, message: 'Ports must be an array with stable string IDs.' });
+    const portIds = new Set();
+    if (Array.isArray(node.ports)) node.ports.forEach((port, portIndex) => {
+      if (!port) return;
+      const path = `nodes.${index}.ports.${portIndex}`;
+      if (portIds.has(port.id)) errors.push({ code: 'DUPLICATE_PORT_ID', path, message: 'Port IDs must be unique within a node.' });
+      portIds.add(port.id);
+      if (port.side !== undefined && !['left', 'right', 'top', 'bottom'].includes(port.side)) errors.push({ code: 'PORT_SIDE', path, message: 'Use left, right, top, or bottom.' });
+      if (port.offset !== undefined && (!finite(port.offset) || port.offset < 0 || port.offset > 1)) errors.push({ code: 'PORT_OFFSET', path, message: 'Port offset must be within [0, 1].' });
+    });
+  });
+  const edgeIds = new Set();
+  edges.forEach((edge, index) => {
+    if (typeof edge.id === 'string' && edgeIds.has(edge.id)) errors.push({ code: 'DUPLICATE_EDGE_ID', path: `edges.${index}.id`, message: `Duplicate edge ID: ${edge.id}.` });
+    if (edge.id) edgeIds.add(edge.id);
+    if (!nodeIds.has(edge.from) || !nodeIds.has(edge.to)) errors.push({ code: 'EDGE_ENDPOINT', path: `edges.${index}`, message: 'Edges must reference existing node IDs.' });
+    if (edge.from === edge.to) errors.push({ code: 'SELF_EDGE', path: `edges.${index}`, message: 'Self-referencing edges are not allowed by default.' });
+    ['fromPort', 'toPort'].forEach(key => {
+      const node = nodes.find(item => item.id === edge[key === 'fromPort' ? 'from' : 'to']);
+      if (edge[key] && (!Array.isArray(node?.ports) || !node.ports.some(port => port?.id === edge[key]))) errors.push({ code: 'MISSING_PORT', path: `edges.${index}.${key}`, message: `Unknown port ${edge[key]}.` });
+    });
+  });
+  if (!diagramLayoutModes.includes(normalized.diagram.layout)) errors.push({ code: 'LAYOUT_MODE', path: 'diagram.layout', message: `Unsupported layout: ${normalized.diagram.layout}.` });
+  if (!finite(normalized.diagram.grid) || normalized.diagram.grid <= 0) errors.push({ code: 'DIAGRAM_GRID', path: 'diagram.grid', message: 'Grid must be a positive finite number.' });
+  if (!edgeRoutingModes.includes(normalized.diagram.routing)) errors.push({ code: 'ROUTING_MODE', path: 'diagram.routing', message: `Unsupported routing: ${normalized.diagram.routing}.` });
+  return { valid: errors.length === 0, errors, spec: normalized };
+}
+
+export function diagramGraph(spec) {
+  const normalized = normalizeDiagramSpec(spec), nodes = normalized.nodes, edges = normalized.edges;
+  const incoming = new Map(nodes.map(node => [node.id, []])), outgoing = new Map(nodes.map(node => [node.id, []]));
+  edges.forEach(edge => { if (incoming.has(edge.to) && outgoing.has(edge.from)) { incoming.get(edge.to).push(edge); outgoing.get(edge.from).push(edge); } });
+  return { spec: normalized, nodes, edges, incoming, outgoing };
+}
+
+export function layoutDiagram(spec, bounds = { x: 0, y: 0, width: 640, height: 360 }) {
+  const graph = diagramGraph(spec), mode = graph.spec.diagram.layout, positions = new Map(), gapX = Math.max(150, bounds.width / Math.max(1, graph.nodes.length)), gapY = 72;
+  if (mode === 'manual') graph.nodes.forEach(node => positions.set(node.id, { x: node.position?.x ?? bounds.x, y: node.position?.y ?? bounds.y }));
+  else {
+    const rank = new Map(graph.nodes.map(node => [node.id, 0])), queue = graph.nodes.filter(node => graph.incoming.get(node.id).length === 0).map(node => node.id);
+    for (let index = 0; index < queue.length; index += 1) graph.outgoing.get(queue[index]).forEach(edge => { rank.set(edge.to, Math.max(rank.get(edge.to) || 0, (rank.get(edge.from) || 0) + 1)); if (!queue.includes(edge.to) && graph.incoming.get(edge.to).every(item => queue.includes(item.from))) queue.push(edge.to); });
+    graph.nodes.filter(node => !queue.includes(node.id)).forEach(node => queue.push(node.id));
+    const buckets = new Map(); queue.forEach(id => { const key = mode === 'radial' ? 0 : rank.get(id) || 0; if (!buckets.has(key)) buckets.set(key, []); buckets.get(key).push(id); });
+    [...buckets.entries()].forEach(([key, ids]) => ids.forEach((id, index) => { if (mode === 'radial') { const angle = index / Math.max(1, ids.length) * Math.PI * 2; positions.set(id, { x: bounds.x + bounds.width / 2 + Math.cos(angle) * bounds.width * 0.32, y: bounds.y + bounds.height / 2 + Math.sin(angle) * bounds.height * 0.32 }); } else positions.set(id, { x: bounds.x + Number(key) * gapX, y: bounds.y + index * gapY }); }));
+  }
+  const grid = Number(graph.spec.diagram.grid) || 0, snap = value => grid > 0 ? Math.round(value / grid) * grid : value;
+  positions.forEach(position => { position.x = snap(position.x); position.y = snap(position.y); });
+  return Object.fromEntries(positions);
+}
+
+export function routeEdge(edge, from, to, mode = 'orthogonal') {
+  const pointFor = (box, port, fallbackSide) => {
+    if (!port) return fallbackSide === 'left' ? { x: box.x, y: box.y + box.height / 2 } : { x: box.x + box.width, y: box.y + box.height / 2 };
+    const side = port.side || fallbackSide, offset = Math.max(0, Math.min(1, Number(port.offset ?? 0.5)));
+    if (side === 'left') return { x: box.x, y: box.y + box.height * offset };
+    if (side === 'top') return { x: box.x + box.width * offset, y: box.y };
+    if (side === 'bottom') return { x: box.x + box.width * offset, y: box.y + box.height };
+    return { x: box.x + box.width, y: box.y + box.height * offset };
+  };
+  const start = pointFor(from, edge.fromPortDefinition, 'right'), end = pointFor(to, edge.toPortDefinition, 'left');
+  if (mode === 'straight') return [start, end];
+  if (mode === 'curved') { const bend = Math.max(30, Math.abs(end.x - start.x) * 0.4); return [start, { x: start.x + bend, y: start.y }, { x: end.x - bend, y: end.y }, end]; }
+  const obstacles = (edge.obstacles || []).filter(box => box && Number.isFinite(box.x) && Number.isFinite(box.y) && Number.isFinite(box.width) && Number.isFinite(box.height));
+  const padding = Math.max(12, Number(edge.grid) || 8);
+  const segmentIntersects = (first, second, box) => {
+    const expanded = { x: box.x - padding, y: box.y - padding, width: box.width + padding * 2, height: box.height + padding * 2 };
+    if (first.x === second.x) return first.x >= expanded.x && first.x <= expanded.x + expanded.width && Math.max(first.y, second.y) >= expanded.y && Math.min(first.y, second.y) <= expanded.y + expanded.height;
+    if (first.y === second.y) return first.y >= expanded.y && first.y <= expanded.y + expanded.height && Math.max(first.x, second.x) >= expanded.x && Math.min(first.x, second.x) <= expanded.x + expanded.width;
+    return false;
+  };
+  const validPath = points => points.every((point, index) => index === 0 || obstacles.every(box => !segmentIntersects(points[index - 1], point, box)));
+  const snap = value => { const grid = Number(edge.grid) || 8; return Math.round(value / grid) * grid; };
+  const middle = snap((start.x + end.x) / 2), middleY = snap((start.y + end.y) / 2);
+  const candidates = [
+    [start, { x: middle, y: start.y }, { x: middle, y: end.y }, end],
+    [start, { x: start.x, y: middleY }, { x: end.x, y: middleY }, end]
+  ];
+  const xChannels = new Set([start.x, end.x, middle]), yChannels = new Set([start.y, end.y, middleY]);
+  obstacles.forEach(box => {
+    [box.x - padding, box.x + box.width + padding].forEach(x => xChannels.add(snap(x)));
+    [box.y - padding, box.y + box.height + padding].forEach(y => yChannels.add(snap(y)));
+  });
+  xChannels.forEach(x => candidates.push([start, { x, y: start.y }, { x, y: end.y }, end]));
+  yChannels.forEach(y => candidates.push([start, { x: start.x, y }, { x: end.x, y }, end]));
+  xChannels.forEach(x => yChannels.forEach(y => {
+    candidates.push([start, { x, y: start.y }, { x, y }, { x: end.x, y }, end]);
+    candidates.push([start, { x: start.x, y }, { x, y }, { x, y: end.y }, end]);
+  }));
+  const compact = points => points.filter((point, index) => !index || point.x !== points[index - 1].x || point.y !== points[index - 1].y);
+  const length = points => points.slice(1).reduce((sum, point, index) => sum + Math.abs(point.x - points[index].x) + Math.abs(point.y - points[index].y), 0);
+  const valid = candidates.map(compact).filter(validPath).sort((left, right) => length(left) - length(right) || left.length - right.length || JSON.stringify(left).localeCompare(JSON.stringify(right)));
+  return valid[0] || compact(candidates[0]);
+}
+
+export function normalizeDiagramData(spec) {
+  const normalized = normalizeDiagramSpec(spec);
+  return { ...normalized, nodes: normalized.nodes.map(node => ({ ...node })) };
+}

package/src/edit-controller.mjs

@@ -0,0 +1,192 @@
+/**
+ * Chart-level edit transaction coordinator.
+ * Connects preview, confirmation, commit, revision checks, audit, and history.
+ */
+import { copyJSON, issue } from './schema.mjs';
+import { normalizeCommand } from './command.mjs';
+import { previewEdit, commitPreview } from './edit.mjs';
+
+let chartSequence = 0;
+
+export class EditController {
+  constructor(chart) {
+    this.chart = chart;
+    this.id = ++chartSequence;
+    this.sequence = 0;
+    this.pending = new Map();
+    this.busy = false;
+  }
+
+  invalidate() {
+    if (this.busy) throw new Error('Cannot replace data during an edit transaction.');
+    this.chart._revision += 1;
+    this.chart._history.clear();
+    this.chart._lastChangeSet = null;
+    this.pending.clear();
+  }
+
+  targetEntries(command) {
+    const spec = this.chart.spec;
+    const diagram = ['flow', 'swimlane'].includes(spec.type);
+    if (!diagram) return [{ field: 'values', root: false }];
+    const operations = command.operations || [];
+    const wantsGroups = operations.some(operation => ['toggleGroupCollapse', 'duplicateGroup', 'deleteGroup'].includes(operation?.op));
+    const wantsEdges = operations.some(operation => ['updateEdge', 'addEdge', 'duplicateSelection', 'pasteSelection', 'duplicateGroup'].includes(operation?.op) || operation?.op === 'deleteGroup' && operation.policy === 'delete-members');
+    const wantsNodes = operations.some(operation => ['moveNode', 'moveNodes', 'moveNodeToLane', 'resizeNode', 'alignNodes', 'snapNodes', 'moveGroup', 'resizeGroup', 'assignNodesToGroup', 'duplicateGroup', 'deleteGroup', 'duplicateSelection', 'pasteSelection'].includes(operation?.op));
+    const entries = [];
+    if (wantsNodes || !wantsEdges && !wantsGroups) entries.push({ field: 'nodes', root: spec.nodes !== undefined });
+    if (wantsEdges) entries.push({ field: 'edges', root: spec.edges !== undefined });
+    if (wantsGroups) entries.push({ field: 'groups', root: spec.groups !== undefined });
+    return entries;
+  }
+
+  context(command) {
+    const spec = this.chart.spec;
+    const diagram = ['flow', 'swimlane'].includes(spec.type);
+    const entries = this.targetEntries(command);
+    const primary = entries[0];
+    const nodes = spec.nodes ?? spec.data.nodes ?? [];
+    const edges = spec.edges ?? spec.data.edges ?? [];
+    const groups = spec.groups ?? spec.data.groups ?? [];
+    const lanes = spec.lanes ?? spec.data.lanes ?? [];
+    const options = {
+      values: primary ? (primary.root ? spec[primary.field] : spec.data[primary.field]) ?? [] : [],
+      nodes,
+      edges,
+      groups,
+      lanes,
+      nodeSchema: spec.data.schema ?? spec.schema,
+      schema: primary?.field === 'edges' ? spec.data.edgeSchema : spec.data.schema ?? spec.schema,
+      edgeSchema: spec.data.edgeSchema,
+      validationOptions: { ...spec.validationOptions, references: { ...spec.validationOptions?.references, ...(diagram ? { 'flow-node': nodes.map(row => row.id), swimlane: lanes.map(row => row.id) } : {}) } },
+      requireConfirmation: spec.editing?.requireConfirmation,
+      grid: spec.diagram?.grid || 8,
+      diagram: spec.diagram,
+      allowStructuralChanges: spec.editing?.allowStructuralChanges === true
+    };
+    return { options, entries, signature: JSON.stringify([options, spec.editing, spec.type]) };
+  }
+
+  preview(input) {
+    let command;
+    try { command = normalizeCommand(input); } catch { return previewEdit(input); }
+    const context = this.context(command);
+    const preview = previewEdit(command, context.options);
+    preview.revision = this.chart._revision;
+    if (preview.valid) {
+      preview.id = `chart-${this.id}-preview-${++this.sequence}`;
+      this.pending.set(preview.id, { command: copyJSON(command), revision: preview.revision, signature: context.signature });
+      if (this.pending.size > 50) this.pending.delete(this.pending.keys().next().value);
+    }
+    return preview;
+  }
+
+  failure(code, message) {
+    const result = { valid: false, errors: [issue(code, 'editing', message)], warnings: [] };
+    this.notify('editerror', { chart: this.chart, result });
+    return result;
+  }
+
+  notify(type, event) {
+    try { this.chart.emit(type, event); } catch (error) { return issue('EDIT_LISTENER', type, error.message); }
+    return null;
+  }
+
+  apply(input, options = {}) {
+    const chart = this.chart;
+    if (this.busy) return { valid: false, errors: [issue('EDIT_IN_PROGRESS', 'editing', 'An edit transaction is already running.')], warnings: [] };
+    if (chart.spec.editing?.enabled !== true) return this.failure('EDITING_DISABLED', 'Business editing is disabled for this chart.');
+    let command;
+    try { command = normalizeCommand(input); } catch (error) { return this.failure('INVALID_COMMAND', error.message); }
+    const context = this.context(command);
+    const preview = previewEdit(command, context.options);
+    preview.revision = chart._revision;
+    if (!preview.valid) { this.notify('editerror', { chart, result: preview }); return preview; }
+    if (preview.requiresConfirmation && options.confirmed !== true) return this.failure('CONFIRMATION_REQUIRED', 'Host confirmation is required; an Agent flag is not authorization.');
+    const previewId = options.previewId ?? options.preview?.id;
+    const expectedRevision = options.expectedRevision ?? options.preview?.revision;
+    if (expectedRevision !== undefined && expectedRevision !== chart._revision) return this.failure('STALE_PREVIEW', 'The data revision changed after preview.');
+    if (preview.requiresConfirmation && !previewId) return this.failure('PREVIEW_REQUIRED', 'Confirm a preview issued by this chart before committing.');
+    if (preview.requiresConfirmation && !options.preview) return this.failure('PREVIEW_REQUIRED', 'Pass the exact preview returned by chart.previewEdit() before committing.');
+    if (previewId) {
+      const stored = this.pending.get(previewId);
+      if (!stored || stored.revision !== chart._revision || stored.signature !== context.signature) return this.failure('STALE_PREVIEW', 'The preview expired or its source data or policy changed.');
+      if (JSON.stringify(stored.command) !== JSON.stringify(command)) return this.failure('PREVIEW_MISMATCH', 'The command does not match the confirmed preview.');
+      preview.id = previewId;
+    }
+    const committed = commitPreview(preview, { ...options, expectedRevision: chart._revision, previewId: preview.id });
+    if (!committed.valid) return committed;
+    this.busy = true;
+    try {
+      let cancelled = false;
+      const listenerError = this.notify('beforeedit', { chart, command: copyJSON(command), preview: copyJSON(preview), preventDefault: () => { cancelled = true; } });
+      if (cancelled || listenerError) return this.failure('EDIT_CANCELLED', listenerError?.message || 'The host cancelled this edit.');
+      if (this.context(command).signature !== context.signature) return this.failure('STALE_PREVIEW', 'Source data changed during confirmation.');
+      const snapshots = context.entries.map(entry => ({ ...entry, before: copyJSON(entry.root ? chart.spec[entry.field] : chart.spec.data[entry.field]) }));
+      const error = this.publish(committed.targets || {}, context.entries);
+      if (error) return this.failure('EDIT_RENDER_FAILED', error.message);
+      chart._revision += 1;
+      committed.revision = chart._revision;
+      committed.target = context.entries.map(entry => entry.root ? entry.field : `data.${entry.field}`).join(',');
+      committed.audit.operationId = `chart-${this.id}-operation-${chart._revision}`;
+      committed.audit.affectedRecords = [...committed.affectedRecords];
+      chart._history.push({
+        targets: context.entries.map(entry => ({
+          field: entry.field,
+          root: entry.root,
+          before: snapshots.find(snapshot => snapshot.field === entry.field && snapshot.root === entry.root)?.before,
+          after: copyJSON(entry.root ? chart.spec[entry.field] : chart.spec.data[entry.field])
+        })),
+        changeSet: committed
+      });
+      chart._lastChangeSet = copyJSON(committed);
+      this.pending.clear();
+      this.notify('edit', { chart, changeSet: copyJSON(committed) });
+      return copyJSON(committed);
+    } finally { this.busy = false; }
+  }
+
+  publish(targets, entries) {
+    const chart = this.chart, previousSpec = chart.spec, previousModel = chart.model;
+    let nextSpec = chart.spec;
+    entries.forEach(entry => {
+      const rows = targets[entry.field];
+      if (!rows) return;
+      nextSpec = entry.root ? { ...nextSpec, [entry.field]: copyJSON(rows) } : { ...nextSpec, data: { ...nextSpec.data, [entry.field]: copyJSON(rows) } };
+    });
+    chart.spec = nextSpec;
+    try { chart.render(); return null; } catch (error) {
+      chart.spec = previousSpec;
+      chart.model = previousModel;
+      try { if (chart.renderer.container) chart.renderer.render(previousModel.scene); } catch {}
+      return error;
+    }
+  }
+
+  restore(direction, options = {}) {
+    const chart = this.chart;
+    if (this.busy) return { valid: false, errors: [issue('EDIT_IN_PROGRESS', 'editing', 'An edit transaction is already running.')], warnings: [] };
+    if (chart.spec.editing?.enabled !== true) return this.failure('EDITING_DISABLED', 'Business editing is disabled for this chart.');
+    if (options.expectedRevision !== undefined && options.expectedRevision !== chart._revision) return this.failure('STALE_PREVIEW', 'The history revision changed.');
+    const entry = chart._history[`${direction}Stack`].at(-1);
+    if (!entry) return this.failure(`NO_${direction.toUpperCase()}`, `There is no edit to ${direction}.`);
+    const stale = entry.targets.some(target => {
+      const current = target.root ? chart.spec[target.field] : chart.spec.data[target.field];
+      return JSON.stringify(current) !== JSON.stringify(direction === 'undo' ? target.after : target.before);
+    });
+    if (stale) return this.failure('STALE_HISTORY', 'Data changed outside the edit history.');
+    this.busy = true;
+    try {
+      const targets = Object.fromEntries(entry.targets.map(target => [target.field, direction === 'undo' ? target.before : target.after]));
+      const error = this.publish(targets, entry.targets);
+      if (error) return this.failure('EDIT_RENDER_FAILED', error.message);
+      chart._history[direction]();
+      chart._revision += 1;
+      const result = { valid: true, direction, revision: chart._revision, rows: copyJSON(targets[entry.targets[0]?.field]), targets: copyJSON(targets), target: entry.changeSet.target, affectedRecords: entry.changeSet.affectedRecords, audit: { operationId: `chart-${this.id}-operation-${chart._revision}`, originalOperationId: entry.changeSet.audit.operationId, actor: options.actor || 'host', source: 'history', timestamp: new Date().toISOString(), reason: direction, affectedRecords: entry.changeSet.affectedRecords } };
+      chart._lastChangeSet = copyJSON(result);
+      this.pending.clear();
+      this.notify('undoredo', { chart, ...copyJSON(result) });
+      return copyJSON(result);
+    } finally { this.busy = false; }
+  }
+}