@taylorwong/ichartjs 2.0.1

package/src/schema.mjs

@@ -0,0 +1,142 @@
+/**
+ * JSON-safe schema utilities and built-in Agent business data contracts.
+ * Defines editable fields, validation constraints, and structured issues.
+ */
+export const schemaVersion = '1.0';
+export const fieldTypes = ['string', 'number', 'boolean', 'date', 'enum', 'array', 'object'];
+const forbiddenKeys = new Set(['__proto__', 'prototype', 'constructor']);
+
+export function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+}
+
+export function copyJSON(value, seen = new Set()) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if ((!Array.isArray(value) && !isRecord(value)) || seen.has(value)) throw new Error('Expected finite, acyclic JSON data.');
+  seen.add(value);
+  const result = Array.isArray(value) ? [] : {};
+  for (const key of Object.keys(value)) {
+    if (forbiddenKeys.has(key)) throw new Error(`Unsafe key: ${key}`);
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!Object.hasOwn(descriptor, 'value')) throw new Error('Accessors are not JSON data.');
+    result[key] = copyJSON(descriptor.value, seen);
+  }
+  seen.delete(value);
+  return result;
+}
+
+export function issue(code, path, message, suggestion = 'Correct the input and validate again.', rule = null) {
+  return { code, path, rule, message, suggestion };
+}
+
+const identifier = { type: 'string', required: true, editable: false };
+const status = { type: 'enum', values: ['todo', 'active', 'blocked', 'done'], default: 'todo', editable: true };
+const position = { type: 'object', editable: true, properties: { x: { type: 'number', required: true }, y: { type: 'number', required: true } } };
+const dependency = { anyOf: [
+  { type: 'string' },
+  { type: 'object', properties: {
+    id: { type: 'string', required: true },
+    type: { type: 'enum', values: ['finish-to-start', 'start-to-start', 'finish-to-finish', 'start-to-finish'] },
+    lag: { type: 'number' },
+    lead: { type: 'number' }
+  } }
+] };
+const schema = (name, fields, rules = []) => ({ name, version: schemaVersion, key: 'id', fields: { id: identifier, ...fields }, rules });
+const models = {
+  'project-task': schema('project-task', {
+    name: { type: 'string', required: true, editable: true },
+    start: { type: 'date', required: true, editable: true },
+    end: { type: 'date', required: true, editable: true },
+    baselineStart: { type: 'date', editable: true },
+    baselineEnd: { type: 'date', editable: true },
+    actualStart: { type: 'date', editable: true },
+    actualEnd: { type: 'date', editable: true },
+    baselineDate: { type: 'date', editable: true },
+    actualDate: { type: 'date', editable: true },
+    progress: { type: 'number', min: 0, max: 100, default: 0, editable: true },
+    status,
+    owner: { type: 'string', editable: true },
+    resource: { type: 'string', editable: true },
+    capacity: { type: 'number', min: 0, editable: true },
+    load: { type: 'number', min: 0, editable: true },
+    points: { type: 'number', min: 0, editable: true },
+    sprint: { type: 'string', editable: true },
+    priority: { type: 'enum', values: ['low', 'medium', 'high', 'critical'], editable: true },
+    labels: { type: 'array', items: { type: 'string' }, default: [], editable: true },
+    dependencies: { type: 'array', items: dependency, default: [], unique: true, references: 'self', acyclic: true, editable: true }
+  }, [
+    { id: 'end-after-start', kind: 'compare', left: 'end', op: 'gte', right: 'start', message: 'End must not precede start.' },
+    { id: 'done-progress', kind: 'implies', if: { field: 'status', equals: 'done' }, then: { field: 'progress', equals: 100 }, message: 'Completed tasks require 100% progress.' }
+  ]),
+  'timeline-event': schema('timeline-event', { title: { type: 'string', required: true, editable: true }, date: { type: 'date', required: true, editable: true }, description: { type: 'string', editable: true }, status }),
+  milestone: schema('milestone', { title: { type: 'string', required: true, editable: true }, date: { type: 'date', required: true, editable: true }, status }),
+  'burndown-sample': schema('burndown-sample', { date: { type: 'date', required: true, editable: true }, remaining: { type: 'number', min: 0, required: true, editable: true }, scopeChange: { type: 'number', default: 0, editable: true }, forecast: { type: 'date', nullable: true, editable: false } }),
+  'flow-node': schema('flow-node', { label: { type: 'string', required: true, editable: true }, position, size: { type: 'object', editable: true, properties: { width: { type: 'number', required: true, min: 1 }, height: { type: 'number', required: true, min: 1 } } }, laneId: { type: 'string', references: 'swimlane', editable: true }, groupId: { type: 'string', editable: false }, ports: { type: 'array', editable: false, items: { type: 'object', properties: { id: { type: 'string', required: true }, side: { type: 'enum', values: ['left', 'right', 'top', 'bottom'] }, offset: { type: 'number', min: 0, max: 1 } } } }, description: { type: 'string', editable: true }, status }),
+  'flow-edge': schema('flow-edge', {
+    from: { type: 'string', references: 'flow-node', required: true, editable: true },
+    to: { type: 'string', references: 'flow-node', required: true, editable: true },
+    fromPort: { type: 'string', editable: true },
+    toPort: { type: 'string', editable: true },
+    label: { type: 'string', editable: true },
+    status,
+    routing: { type: 'enum', values: ['straight', 'orthogonal', 'curved'], editable: true }
+  }),
+  swimlane: schema('swimlane', { label: { type: 'string', required: true, editable: true } })
+};
+
+export function getBusinessSchema(name) {
+  if (!Object.hasOwn(models, name)) throw new Error(`Unknown business model: ${name}`);
+  return copyJSON(models[name]);
+}
+
+export function validateDataSchema(input) {
+  const errors = [];
+  let result;
+  try { result = copyJSON(input); } catch (error) { return { valid: false, errors: [issue('INVALID_JSON', 'schema', error.message)], schema: null }; }
+  if (!isRecord(result)) return { valid: false, errors: [issue('INVALID_SCHEMA', 'schema', 'Schema must be an object.')], schema: null };
+  if (result.version !== schemaVersion) errors.push(issue('SCHEMA_VERSION', 'schema.version', 'Unsupported schema version.', 'Use 1.0; migration is not automatic.'));
+  if (typeof result.name !== 'string' || !result.name) errors.push(issue('SCHEMA_NAME', 'schema.name', 'Schema name is required.'));
+  const fields = isRecord(result.fields) ? result.fields : {};
+  if (typeof result.key !== 'string' || fields[result.key]?.type !== 'string' || !fields[result.key]?.required || fields[result.key]?.editable !== false) errors.push(issue('SCHEMA_KEY', 'schema.key', 'The primary key must be a required read-only string field.'));
+  const allowed = ['type', 'anyOf', 'required', 'editable', 'agentEditable', 'nullable', 'default', 'min', 'max', 'values', 'items', 'properties', 'references', 'acyclic', 'unique'];
+  const checkField = (field, path, depth = 0) => {
+    if (!isRecord(field) || depth > 12) { errors.push(issue('INVALID_FIELD', path, 'Invalid or excessively nested field definition.')); return; }
+    Object.keys(field).filter(key => !allowed.includes(key)).forEach(key => errors.push(issue('UNSUPPORTED_CONSTRAINT', `${path}.${key}`, `Constraint ${key} is not implemented; it will not be ignored.`)));
+    if (field.anyOf !== undefined) {
+      if (!Array.isArray(field.anyOf) || field.anyOf.length < 2) errors.push(issue('FIELD_UNION', path, 'anyOf requires at least two field definitions.'));
+      else field.anyOf.forEach((option, index) => checkField(option, `${path}.anyOf.${index}`, depth + 1));
+    } else if (!fieldTypes.includes(field.type)) errors.push(issue('FIELD_TYPE', path, 'Unsupported field type.'));
+    for (const key of ['required', 'editable', 'agentEditable', 'nullable', 'acyclic', 'unique']) if (field[key] !== undefined && typeof field[key] !== 'boolean') errors.push(issue('FIELD_FLAG', `${path}.${key}`, 'Expected a boolean.'));
+    for (const key of ['min', 'max']) if (field[key] !== undefined && (field.type !== 'number' || typeof field[key] !== 'number')) errors.push(issue('FIELD_RANGE', `${path}.${key}`, 'Numeric limits apply to number fields only.'));
+    if (field.min > field.max) errors.push(issue('FIELD_RANGE', path, 'min exceeds max.'));
+    if (field.type === 'enum' && (!Array.isArray(field.values) || !field.values.length || !field.values.every(value => typeof value === 'string'))) errors.push(issue('ENUM_VALUES', path, 'Enum values must be a nonempty string array.'));
+    if (field.type === 'array') checkField(field.items, `${path}.items`, depth + 1);
+    if (field.type === 'object') {
+      if (!isRecord(field.properties)) errors.push(issue('OBJECT_PROPERTIES', path, 'Object fields need explicit properties.'));
+      else Object.entries(field.properties).forEach(([key, child]) => checkField(child, `${path}.properties.${key}`, depth + 1));
+    }
+    const referenceItem = field.type === 'array' && (field.items?.type === 'string' || field.items?.anyOf?.some(option => option.type === 'string'));
+    if (field.references !== undefined && (typeof field.references !== 'string' || !field.references || !(field.type === 'string' || referenceItem))) errors.push(issue('REFERENCE_SCHEMA', path, 'References require string IDs or arrays containing string IDs.'));
+    if (field.acyclic && (field.type !== 'array' || field.references !== 'self')) errors.push(issue('ACYCLIC_SCHEMA', path, 'Cycle checks require self-referencing arrays.'));
+  };
+  Object.entries(fields).forEach(([name, field]) => checkField(field, `schema.fields.${name}`));
+  const rules = result.rules ?? [], ruleIds = new Set();
+  if (!Array.isArray(rules)) errors.push(issue('INVALID_RULES', 'schema.rules', 'Rules must be declarative objects, not executable expressions.'));
+  else rules.forEach((rule, index) => {
+    const path = `schema.rules.${index}`;
+    if (!isRecord(rule) || typeof rule.id !== 'string' || !rule.id || ruleIds.has(rule.id)) { errors.push(issue('INVALID_RULE', path, 'Each rule requires a unique string ID.')); return; }
+    ruleIds.add(rule.id);
+    if (rule.kind === 'compare') {
+      if (!['gte', 'gt', 'lte', 'lt', 'eq'].includes(rule.op) || !fields[rule.left] || !fields[rule.right] || fields[rule.left].type !== fields[rule.right].type || !['date', 'number'].includes(fields[rule.left].type)) errors.push(issue('INVALID_RULE', path, 'Comparisons need matching number or date fields and a supported operator.'));
+    } else if (rule.kind === 'implies') {
+      if (![rule.if, rule.then].every(term => isRecord(term) && fields[term.field] && Object.hasOwn(term, 'equals'))) errors.push(issue('INVALID_RULE', path, 'Implications require if/then field and equals objects.'));
+    } else errors.push(issue('UNSUPPORTED_RULE', path, 'Only compare and implies rules are implemented.'));
+  });
+  return { valid: errors.length === 0, errors, schema: result };
+}
+
+export function inspectDataSchema(input) {
+  const result = validateDataSchema(input);
+  return { ...result, models: Object.keys(models), fieldTypes: [...fieldTypes], rules: ['compare', 'implies'], normalization: 'explicit-only', progressUnit: 'percent-0-100' };
+}

package/src/spec.mjs

@@ -0,0 +1,127 @@
+/**
+ * Chart Spec defaults, normalization, and top-level validation.
+ * The normalized Spec is the stable contract shared by all renderers.
+ */
+import { chartProfiles } from './capabilities.mjs';
+import { themeModes, themePalettes, themePresets } from './theme.mjs';
+
+const chartTypes = new Set(Object.keys(chartProfiles));
+
+const defaults = {
+  version: '2.0',
+  renderer: 'canvas',
+  width: 640,
+  height: 360,
+  padding: { top: 48, right: 24, bottom: 48, left: 56 },
+  colors: ['#2563eb', '#16a34a', '#f59e0b', '#dc2626', '#7c3aed', '#0891b2'],
+  background: '#ffffff',
+  theme: 'auto',
+  title: { text: '', subtitle: '' },
+  legend: { visible: true, position: 'top' },
+  grid: { visible: true },
+  labels: { enabled: false },
+  branding: { enabled: true },
+  interaction: { tooltip: true, hover: true, click: true, crosshair: false, zoom: false, brush: false, keyboard: true }
+  ,responsive: [], accessibility: { enabled: false }, editing: { enabled: false, mode: 'command', requireConfirmation: true, allowDelete: false, allowStructuralChanges: false }, xAxis: {}, yAxis: {}
+};
+
+function clone(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+function merge(base, extra) {
+  const result = clone(base);
+  Object.keys(extra || {}).forEach(key => {
+    if (extra[key] && typeof extra[key] === 'object' && !Array.isArray(extra[key]) && result[key] && typeof result[key] === 'object') {
+      result[key] = merge(result[key], extra[key]);
+    } else if (extra[key] !== undefined) {
+      result[key] = clone(extra[key]);
+    }
+  });
+  return result;
+}
+
+function dependencyId(dependency) {
+  return typeof dependency === 'string' ? dependency : dependency && typeof dependency === 'object' && typeof dependency.id === 'string' ? dependency.id : null;
+}
+
+function dependencyErrors(rows) {
+  const errors = [], ids = new Set(rows.map(row => row.id).filter(Boolean)), graph = new Map(rows.map(row => [row.id, (row.dependencies || []).map(dependencyId).filter(Boolean)]));
+  rows.forEach((row, index) => (row.dependencies || []).forEach((dependency, dependencyIndex) => {
+    const id = dependencyId(dependency);
+    if (!id) errors.push({ code: 'INVALID_DEPENDENCY', path: `data.values[${index}].dependencies[${dependencyIndex}]`, message: 'Dependency must be a task id or an object with an id.', suggestion: 'Use a string id or { id, type, lag, lead }.' });
+    else if (!ids.has(id)) errors.push({ code: 'MISSING_DEPENDENCY', path: `data.values[${index}].dependencies`, message: `Task ${row.id || index} references missing task ${id}.`, suggestion: 'Use an existing task id.' });
+  }));
+  const visiting = new Set(), visited = new Set();
+  function visit(id) { if (visiting.has(id)) return true; if (visited.has(id)) return false; visiting.add(id); const cycle = (graph.get(id) || []).some(visit); visiting.delete(id); visited.add(id); return cycle; }
+  graph.forEach((_, id) => { if (visit(id)) errors.push({ code: 'CYCLIC_DEPENDENCY', path: 'data.values', message: 'Gantt dependencies contain a cycle.', suggestion: 'Dependencies must form a directed acyclic graph.' }); });
+  return errors;
+}
+
+export function normalizeSpec(input = {}) {
+  const spec = merge(defaults, input);
+  if (spec.branding === false) spec.branding = { enabled: false };
+  else if (spec.branding === true) spec.branding = { enabled: true };
+  else if (spec.branding == null) spec.branding = { enabled: true };
+  else if (typeof spec.branding === 'object' && !Array.isArray(spec.branding)) {
+    if (spec.branding.enabled === undefined) spec.branding = { ...spec.branding, enabled: true };
+  }
+  if (!spec.data) spec.data = { values: [] };
+  if (['flow', 'swimlane'].includes(spec.type) && spec.nodes && !spec.data.values) spec.data.values = [];
+  if (Array.isArray(spec.data)) spec.data = { values: spec.data };
+  if (!spec.encoding) spec.encoding = {};
+  if (['pie', 'funnel', 'gauge'].includes(spec.type) && !spec.encoding.category) spec.encoding.category = { field: 'name', type: 'category' };
+  if (['pie', 'funnel', 'gauge'].includes(spec.type) && !spec.encoding.value) spec.encoding.value = { field: 'value', type: 'quantitative' };
+  if (spec.type === 'scatter' && !input.encoding?.x) spec.encoding.x = { field: 'x', type: 'quantitative' };
+  if (spec.type === 'scatter' && !input.encoding?.y) spec.encoding.y = { field: 'y', type: 'quantitative' };
+  if (spec.type === 'heatmap') { spec.encoding.x ||= { field: 'x', type: 'category' }; spec.encoding.y ||= { field: 'y', type: 'category' }; spec.encoding.color ||= { field: 'value', type: 'quantitative' }; }
+  if (!['pie', 'funnel', 'gauge', 'gantt', 'timeline', 'milestone', 'burndown', 'flow', 'swimlane'].includes(spec.type)) {
+    spec.encoding.x = spec.encoding.x || { field: 'name', type: 'category' };
+    spec.encoding.y = spec.encoding.y || { field: 'value', type: 'quantitative' };
+  }
+  return spec;
+}
+
+export function validateSpec(input) {
+  const spec = normalizeSpec(input);
+  const errors = [], warnings = [], normalizations = [];
+  if (!chartTypes.has(spec.type)) errors.push({ code: 'INVALID_TYPE', path: 'type', message: `Unsupported chart type: ${spec.type}`, suggestion: 'Use a type returned by getCapabilities().' });
+  if (!['canvas', 'svg', 'auto'].includes(spec.renderer)) errors.push({ code: 'INVALID_RENDERER', path: 'renderer', message: `Unsupported renderer: ${spec.renderer}`, suggestion: 'Use canvas, svg, or auto.' });
+  if (typeof spec.theme === 'string' && !themeModes.includes(spec.theme) && !themePresets.includes(spec.theme)) errors.push({ code: 'INVALID_THEME', path: 'theme', message: `Unsupported theme: ${spec.theme}`, suggestion: 'Use auto, light, dark, contrast, or a named style preset.' });
+  if (spec.theme && typeof spec.theme === 'object') {
+    if (spec.theme.mode && !themeModes.includes(spec.theme.mode)) errors.push({ code: 'INVALID_THEME_MODE', path: 'theme.mode', message: `Unsupported theme mode: ${spec.theme.mode}`, suggestion: `Use ${themeModes.join(', ')}.` });
+    if (spec.theme.preset && !themePresets.includes(spec.theme.preset)) errors.push({ code: 'INVALID_THEME_PRESET', path: 'theme.preset', message: `Unsupported theme preset: ${spec.theme.preset}`, suggestion: `Use ${themePresets.join(', ')}.` });
+    if (spec.theme.palette && !themePalettes.includes(spec.theme.palette)) errors.push({ code: 'INVALID_THEME_PALETTE', path: 'theme.palette', message: `Unsupported theme palette: ${spec.theme.palette}`, suggestion: `Use ${themePalettes.join(', ')}.` });
+  }
+  if (Array.isArray(spec.encoding.y) && spec.encoding.y.length > 2) errors.push({ code: 'TOO_MANY_AXES', path: 'encoding.y', message: 'Only two quantitative axes are supported in this iteration.', suggestion: 'Use at most two y encodings.' });
+  if (spec.stack && !['bar', 'column', 'area'].includes(spec.type)) errors.push({ code: 'INVALID_STACK', path: 'stack', message: 'Stacking is supported by bar, column, and area charts.', suggestion: 'Remove stack or use a supported chart type.' });
+  if (spec.stack && !['stacked', 'percent'].includes(typeof spec.stack === 'string' ? spec.stack : spec.stack.mode)) errors.push({ code: 'INVALID_STACK_MODE', path: 'stack', message: 'Stack mode must be stacked or percent.', suggestion: 'Use stack: "stacked" or stack: "percent".' });
+  if (spec.type === 'pie' && spec.innerRadius != null && (!(Number(spec.innerRadius) >= 0) || Number(spec.innerRadius) >= 1)) errors.push({ code: 'INVALID_INNER_RADIUS', path: 'innerRadius', message: 'Pie innerRadius must be a ratio from 0 up to, but not including, 1.', suggestion: 'Use a value such as 0.55.' });
+  if (spec.type === 'radar' && (!Array.isArray(spec.indicators) || spec.indicators.length < 3)) errors.push({ code: 'INVALID_INDICATORS', path: 'indicators', message: 'Radar requires at least three indicators.', suggestion: 'Declare indicator name, field, min, and max.' });
+  if (!spec.data || !Array.isArray(spec.data.values)) errors.push({ code: 'INVALID_DATA', path: 'data.values', message: 'data.values must be an array.', suggestion: 'Pass an array of row objects.' });
+  if (['flow', 'swimlane'].includes(spec.type) && !Array.isArray(spec.nodes) && !Array.isArray(spec.data?.nodes)) errors.push({ code: 'INVALID_NODES', path: 'nodes', message: 'Flow and swimlane charts require nodes.', suggestion: 'Pass nodes on the Spec or in data.nodes.' });
+  if (['gantt', 'timeline', 'milestone'].includes(spec.type)) {
+    const rows = spec.data.values, dateKey = spec.type === 'gantt' ? 'start/end' : 'date';
+    if (!rows.some(row => row.start || row.end || row.date)) errors.push({ code: 'INVALID_INTERVALS', path: 'data.values', message: `${spec.type} rows require ${dateKey} dates.`, suggestion: 'Add ISO date values to each row.' });
+    rows.forEach((row, index) => { const values = spec.type === 'gantt' ? [row.start, row.end] : [row.date]; if (values.some(value => value != null && Number.isNaN(Date.parse(value)))) errors.push({ code: 'INVALID_DATE', path: `data.values[${index}]`, message: `${spec.type} contains an invalid date.`, suggestion: 'Use an ISO-8601 date such as 2026-09-14.' }); });
+  }
+  if (spec.type === 'gantt') errors.push(...dependencyErrors(spec.data.values));
+  if (spec.type === 'pie' && spec.data.values.length > 8) warnings.push({ code: 'HIGH_CARDINALITY_PIE', path: 'data.values', message: `Pie contains ${spec.data.values.length} categories.`, expected: '8 or fewer categories', suggestion: 'Use bar/column or group smaller categories.' });
+  if (spec.type === 'radar' && Array.isArray(spec.indicators) && spec.indicators.some(indicator => !Number.isFinite(Number(indicator.min)) || !Number.isFinite(Number(indicator.max)))) warnings.push({ code: 'AMBIGUOUS_RADAR_DOMAIN', path: 'indicators', message: 'Radar indicator domains are incomplete.', expected: 'finite min and max for every indicator', suggestion: 'Declare explicit domains, especially for mixed units.' });
+  const supportedInteractions = chartProfiles[spec.type]?.interactions || [];
+  Object.entries(spec.interaction || {}).forEach(([name, enabled]) => { if (enabled && !supportedInteractions.includes(name) && !['hover', 'click'].includes(name)) warnings.push({ code: 'UNSUPPORTED_INTERACTION', path: `interaction.${name}`, message: `${name} is not declared for ${spec.type}.`, expected: supportedInteractions, suggestion: 'Disable the interaction or use a compatible chart type.' }); });
+  if (spec.branding != null && typeof spec.branding !== 'boolean' && !(spec.branding && typeof spec.branding === 'object')) {
+    errors.push({ code: 'INVALID_BRANDING', path: 'branding', message: 'branding must be a boolean or a { enabled: boolean } object.', suggestion: 'Use branding: true, branding: false, or branding: { enabled: false }.' });
+  } else if (spec.branding && typeof spec.branding === 'object') {
+    const keys = new Set(Object.keys(spec.branding));
+    if (keys.size > 1 || !keys.has('enabled')) {
+      errors.push({ code: 'UNSUPPORTED_BRANDING_OPTIONS', path: 'branding', message: 'This iteration of branding only supports the enabled option.', expected: ['enabled'], suggestion: 'Custom text, links, position, and font are intentionally not exposed in the current version.' });
+    } else if (typeof spec.branding.enabled !== 'boolean') {
+      errors.push({ code: 'INVALID_BRANDING_ENABLED', path: 'branding.enabled', message: 'branding.enabled must be a boolean.', suggestion: 'Use true to show the Powered by iChart.js signature or false to hide.' });
+    }
+  }
+  ['width', 'height'].forEach(key => { if (!(Number(spec[key]) > 0)) errors.push({ code: 'INVALID_DIMENSION', path: key, message: `${key} must be greater than zero.`, suggestion: `Set a positive ${key}.` }); });
+  return { valid: errors.length === 0, errors, warnings, normalizations, spec };
+}
+
+export { chartTypes };

package/src/theme.mjs

@@ -0,0 +1,232 @@
+/**
+ * Renderer-neutral visual style presets, palettes, and resolution helpers.
+ */
+
+export const themeModes = ['auto', 'light', 'dark', 'contrast'];
+export const themePresets = ['auto', 'analysis', 'dashboard', 'report', 'presentation', 'project', 'diagram'];
+export const themePalettes = ['auto', 'categorical', 'sequential', 'diverging', 'status'];
+
+const fontFamily = 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif';
+
+const modes = {
+  light: {
+    background: '#ffffff', surface: '#ffffff', text: '#172033', muted: '#536274', axis: '#667085', grid: '#d9e0ea', border: '#c5cfdb', focus: '#1d4ed8', selection: '#1d4ed8', missing: '#d7dee8',
+    categorical: ['#6929c4', '#0072c3', '#007d79', '#9f1853', '#a2191f', '#198038', '#002d9c', '#8a3800'],
+    sequential: ['#edf5ff', '#d0e2ff', '#a6c8ff', '#78a9ff', '#4589ff', '#0f62fe', '#0043ce', '#002d9c'],
+    diverging: ['#491d8b', '#8a3ffc', '#be95ff', '#e8daff', '#f8fafc', '#d9fbfb', '#3ddbd9', '#009d9a', '#005d5d'],
+    status: { success: '#198038', warning: '#b28600', danger: '#da1e28', info: '#0072c3', neutral: '#697586' }
+  },
+  dark: {
+    background: '#0f172a', surface: '#172033', text: '#f8fafc', muted: '#cbd5e1', axis: '#c2cad6', grid: '#344054', border: '#475467', focus: '#84adff', selection: '#84adff', missing: '#475467',
+    categorical: ['#be95ff', '#33b1ff', '#3ddbd9', '#ff7eb6', '#fa4d56', '#6fdc8c', '#78a9ff', '#ffb784'],
+    sequential: ['#001141', '#001d6c', '#002d9c', '#0043ce', '#0f62fe', '#4589ff', '#78a9ff', '#d0e2ff'],
+    diverging: ['#be95ff', '#a56eff', '#8a3ffc', '#6929c4', '#344054', '#007d79', '#009d9a', '#3ddbd9', '#9ef0f0'],
+    status: { success: '#42be65', warning: '#f1c21b', danger: '#ff8389', info: '#33b1ff', neutral: '#98a2b3' }
+  },
+  contrast: {
+    background: '#000000', surface: '#000000', text: '#ffffff', muted: '#ffffff', axis: '#ffffff', grid: '#8c8c8c', border: '#ffffff', focus: '#ffff00', selection: '#ffff00', missing: '#666666',
+    categorical: ['#ffff00', '#00ffff', '#ff7eb6', '#ffffff', '#7fff00', '#ff8c00'],
+    sequential: ['#1a1a1a', '#4d4d4d', '#808080', '#b3b3b3', '#e6e6e6', '#ffffff'],
+    diverging: ['#ff00ff', '#ff7eb6', '#ffffff', '#00ffff', '#007fff'],
+    status: { success: '#7fff00', warning: '#ffff00', danger: '#ff4d4d', info: '#00ffff', neutral: '#ffffff' }
+  }
+};
+
+const presets = {
+  analysis: {
+    typography: { title: [16, 600, 1.25], subtitle: [13, 400, 1.4], axis: [12, 400, 1.4], legend: [12, 500, 1.4], label: [12, 500, 1.35], tooltip: [12, 400, 1.45], metric: [24, 600, 1.15] },
+    layout: { padding: { top: 48, right: 24, bottom: 48, left: 56 }, spacing: 8, legendGap: 12, axisGap: 10, density: 'comfortable', minimumTargetSize: 24 },
+    marks: { lineWidth: 2, selectedLineWidth: 3, radius: 5, opacity: 1, gridWidth: 1, dashPatterns: [[], [6, 4], [2, 3]] }
+  },
+  dashboard: {
+    typography: { title: [15, 600, 1.25], subtitle: [12, 400, 1.4], axis: [12, 400, 1.35], legend: [12, 500, 1.35], label: [12, 500, 1.3], tooltip: [12, 400, 1.4], metric: [24, 650, 1.1] },
+    layout: { padding: { top: 42, right: 18, bottom: 42, left: 50 }, spacing: 6, legendGap: 8, axisGap: 8, density: 'compact', minimumTargetSize: 24 },
+    marks: { lineWidth: 2, selectedLineWidth: 3, radius: 4, opacity: 1, gridWidth: 1, dashPatterns: [[], [5, 3], [2, 2]] }
+  },
+  report: {
+    typography: { title: [17, 650, 1.25], subtitle: [13, 400, 1.45], axis: [12, 400, 1.45], legend: [12, 500, 1.4], label: [12, 500, 1.4], tooltip: [12, 400, 1.45], metric: [24, 650, 1.15] },
+    layout: { padding: { top: 54, right: 28, bottom: 52, left: 60 }, spacing: 8, legendGap: 14, axisGap: 12, density: 'comfortable', minimumTargetSize: 24 },
+    marks: { lineWidth: 2, selectedLineWidth: 3, radius: 4, opacity: 1, gridWidth: 1, dashPatterns: [[], [7, 4], [2, 3]] }
+  },
+  presentation: {
+    typography: { title: [20, 650, 1.2], subtitle: [14, 400, 1.45], axis: [13, 450, 1.4], legend: [13, 550, 1.4], label: [13, 550, 1.35], tooltip: [13, 400, 1.45], metric: [28, 650, 1.1] },
+    layout: { padding: { top: 62, right: 34, bottom: 58, left: 66 }, spacing: 10, legendGap: 16, axisGap: 14, density: 'spacious', minimumTargetSize: 28 },
+    marks: { lineWidth: 3, selectedLineWidth: 4, radius: 6, opacity: 1, gridWidth: 1, dashPatterns: [[], [8, 5], [3, 4]] }
+  },
+  project: {
+    typography: { title: [16, 650, 1.25], subtitle: [13, 400, 1.4], axis: [12, 450, 1.4], legend: [12, 550, 1.4], label: [12, 500, 1.35], tooltip: [12, 400, 1.45], metric: [24, 650, 1.15] },
+    layout: { padding: { top: 50, right: 26, bottom: 52, left: 64 }, spacing: 8, legendGap: 12, axisGap: 10, density: 'comfortable', minimumTargetSize: 24 },
+    marks: { lineWidth: 2, selectedLineWidth: 3, radius: 5, opacity: 1, gridWidth: 1, dashPatterns: [[], [6, 4], [2, 3]] }
+  },
+  diagram: {
+    typography: { title: [16, 650, 1.25], subtitle: [13, 400, 1.4], axis: [12, 400, 1.4], legend: [12, 500, 1.4], label: [12, 550, 1.35], tooltip: [12, 400, 1.45], metric: [24, 650, 1.15] },
+    layout: { padding: { top: 50, right: 28, bottom: 44, left: 58 }, spacing: 8, legendGap: 12, axisGap: 10, density: 'comfortable', minimumTargetSize: 24 },
+    marks: { lineWidth: 1.75, selectedLineWidth: 3, radius: 6, opacity: 1, gridWidth: 1, dashPatterns: [[], [6, 4], [2, 3]] }
+  }
+};
+
+const projectTypes = new Set(['gantt', 'timeline', 'milestone', 'burndown']);
+const diagramTypes = new Set(['flow', 'swimlane']);
+const structuredKeys = new Set(['preset', 'mode', 'palette', 'tokens']);
+
+function clone(value) { return value == null ? value : JSON.parse(JSON.stringify(value)); }
+
+function merge(base, extra) {
+  const result = clone(base) || {};
+  Object.entries(extra || {}).forEach(([key, value]) => {
+    if (value && typeof value === 'object' && !Array.isArray(value) && result[key] && typeof result[key] === 'object' && !Array.isArray(result[key])) result[key] = merge(result[key], value);
+    else if (value !== undefined) result[key] = clone(value);
+  });
+  return result;
+}
+
+function role(values) {
+  const [size, weight, lineHeight] = values;
+  return { size, weight, lineHeight, font: `${weight} ${size}px ${fontFamily}` };
+}
+
+function requestedTheme(theme) {
+  if (typeof theme === 'string') {
+    if (themeModes.includes(theme)) return { mode: theme, preset: 'auto', palette: 'auto', overrides: {} };
+    if (themePresets.includes(theme)) return { mode: 'auto', preset: theme, palette: 'auto', overrides: {} };
+  }
+  if (theme && typeof theme === 'object') {
+    const overrides = Object.fromEntries(Object.entries(theme).filter(([key]) => !structuredKeys.has(key)));
+    return { mode: theme.mode || 'auto', preset: theme.preset || 'auto', palette: theme.palette || 'auto', overrides: merge(overrides, theme.tokens || {}) };
+  }
+  return { mode: 'auto', preset: 'auto', palette: 'auto', overrides: {} };
+}
+
+function preferredMode(mode, options = {}) {
+  if (mode !== 'auto') return themeModes.includes(mode) ? mode : 'light';
+  if (options.preferredColorScheme === 'dark') return 'dark';
+  if (options.preferredColorScheme === 'light') return 'light';
+  if (typeof matchMedia === 'function' && matchMedia('(prefers-color-scheme: dark)').matches) return 'dark';
+  return 'light';
+}
+
+function sourceRows(spec = {}) {
+  const data = Array.isArray(spec.data) ? spec.data : spec.data?.values;
+  return Array.isArray(data) ? data : Array.isArray(spec.nodes) ? spec.nodes : [];
+}
+
+function automaticPreset(spec = {}, options = {}) {
+  const context = options.context || spec.context || spec.intent;
+  if (themePresets.includes(context) && context !== 'auto') return context;
+  if (['print', 'export', 'weekly-report', 'reporting'].includes(context)) return 'report';
+  if (['slides', 'story', 'presentation'].includes(context)) return 'presentation';
+  if (['monitoring', 'dashboard'].includes(context)) return 'dashboard';
+  if (projectTypes.has(spec.type)) return 'project';
+  if (diagramTypes.has(spec.type)) return 'diagram';
+  return 'analysis';
+}
+
+function automaticPalette(spec = {}) {
+  const rows = sourceRows(spec);
+  const fields = new Set(rows.flatMap(row => Object.keys(row || {})).map(field => field.toLowerCase()));
+  if (['status', 'risk', 'priority', 'severity', 'health'].some(field => fields.has(field))) return 'status';
+  if (spec.type === 'heatmap' || spec.encoding?.color?.type === 'quantitative') return 'sequential';
+  const inferredMeasures = Object.keys(rows[0] || {}).filter(field => rows.some(row => row?.[field] != null && row?.[field] !== '' && Number.isFinite(Number(row[field])))).map(field => ({ field }));
+  const measures = Array.isArray(spec.encoding?.y) ? spec.encoding.y : [spec.encoding?.y || spec.encoding?.value].filter(Boolean);
+  if (!measures.length) measures.push(...inferredMeasures);
+  const values = rows.flatMap(row => measures.map(encoding => Number(row?.[encoding?.field])).filter(Number.isFinite));
+  if (values.some(value => value < 0) && values.some(value => value > 0)) return 'diverging';
+  return 'categorical';
+}
+
+function categoryCount(spec = {}) {
+  const rows = sourceRows(spec);
+  const field = spec.encoding?.x?.field || spec.encoding?.category?.field || 'name';
+  return new Set(rows.map(row => row?.[field]).filter(value => value != null)).size;
+}
+
+export function planStyle(spec = {}, options = {}) {
+  const request = requestedTheme(options.theme ?? spec.theme);
+  const preset = request.preset === 'auto' ? automaticPreset(spec, options) : request.preset;
+  const palette = request.palette === 'auto' ? automaticPalette(spec) : request.palette;
+  const mode = themeModes.includes(request.mode) ? request.mode : 'auto';
+  const resolvedMode = preferredMode(mode, options);
+  const reasons = [`${preset} matches the ${spec.type || 'general'} visualization context.`, `${palette} matches the detected data semantics.`, `${resolvedMode} is the resolved color mode.`];
+  const warnings = [];
+  const categories = categoryCount(spec);
+  if (palette === 'categorical' && categories > 6) warnings.push({ code: 'HIGH_CARDINALITY_COLOR', path: 'theme.palette', message: `${categories} categories exceed the recommended six-color comparison set.`, suggestion: 'Group categories or add labels, shapes, or line patterns.' });
+  return { version: '1.0', preset, mode, resolvedMode, palette, reasons, warnings, userOverride: request.preset !== 'auto' || request.mode !== 'auto' || request.palette !== 'auto' };
+}
+
+function channel(value) {
+  const text = String(value || '').replace('#', '');
+  if (!/^[0-9a-f]{6}$/i.test(text)) return null;
+  return [0, 2, 4].map(index => parseInt(text.slice(index, index + 2), 16) / 255).map(value => value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4);
+}
+
+function luminance(value) {
+  const rgb = channel(value);
+  return rgb ? 0.2126 * rgb[0] + 0.7152 * rgb[1] + 0.0722 * rgb[2] : null;
+}
+
+export function contrastRatio(foreground, background) {
+  const first = luminance(foreground), second = luminance(background);
+  if (first == null || second == null) return null;
+  return (Math.max(first, second) + 0.05) / (Math.min(first, second) + 0.05);
+}
+
+export function validateThemeContrast(theme) {
+  const checks = [['text', theme.text, 4.5], ['muted', theme.muted, 4.5], ['axis', theme.axis, 3], ['focus', theme.focus, 3]];
+  return checks.flatMap(([token, color, minimum]) => {
+    const ratio = contrastRatio(color, theme.background);
+    return ratio != null && ratio < minimum ? [{ code: 'INSUFFICIENT_THEME_CONTRAST', path: `theme.${token}`, message: `${token} contrast ${ratio.toFixed(2)}:1 is below ${minimum}:1.`, expected: minimum }] : [];
+  });
+}
+
+export function resolveTheme(theme, options = {}) {
+  const request = requestedTheme(theme);
+  const plan = planStyle({ ...options, theme }, { ...options, theme });
+  const mode = modes[plan.resolvedMode] || modes.light;
+  const preset = presets[plan.preset] || presets.analysis;
+  const typography = Object.fromEntries(Object.entries(preset.typography).map(([key, value]) => [key, role(value)]));
+  const colors = plan.palette === 'sequential' ? mode.sequential : plan.palette === 'diverging' ? mode.diverging : plan.palette === 'status' ? Object.values(mode.status) : mode.categorical;
+  const resolved = {
+    name: `${plan.preset}-${plan.resolvedMode}`,
+    mode: plan.mode,
+    resolvedMode: plan.resolvedMode,
+    preset: plan.preset,
+    palette: plan.palette,
+    background: mode.background,
+    surface: mode.surface,
+    text: mode.text,
+    muted: mode.muted,
+    axis: mode.axis,
+    grid: mode.grid,
+    border: mode.border,
+    focus: mode.focus,
+    selection: mode.selection,
+    colors: [...colors],
+    palettes: { categorical: [...mode.categorical], sequential: [...mode.sequential], diverging: [...mode.diverging], status: { ...mode.status }, missing: mode.missing },
+    status: { ...mode.status },
+    typography,
+    layout: clone(preset.layout),
+    marks: clone(preset.marks),
+    reasons: [...plan.reasons],
+    warnings: [...plan.warnings]
+  };
+  const output = merge(resolved, request.overrides);
+  output.warnings = [...(output.warnings || []), ...validateThemeContrast(output)];
+  return output;
+}
+
+export const themes = {
+  light: resolveTheme('light'),
+  dark: resolveTheme('dark'),
+  contrast: resolveTheme('contrast')
+};
+
+export const styleCapabilities = {
+  modes: [...themeModes],
+  presets: [...themePresets],
+  palettes: [...themePalettes],
+  switchable: true,
+  automatic: true,
+  contrast: { normalText: 4.5, largeText: 3, essentialGraphics: 3 },
+  minimumTextSize: 12,
+  recommendedCategoricalColors: 6
+};

package/src/transforms.mjs

@@ -0,0 +1,34 @@
+/**
+ * Deterministic standalone transforms used by Specs and data pipelines.
+ */
+function rowsFrom(input) {
+  if (Array.isArray(input)) return input.map(row => ({ ...row }));
+  if (input && Array.isArray(input.values)) return input.values.map(row => ({ ...row }));
+  return [];
+}
+
+export function binData(input, options = {}) {
+  const rows = rowsFrom(input), field = options.field || 'value', output = options.output || 'count';
+  const valid = [], warnings = [];
+  rows.forEach((row, index) => { const value = Number(row[field]); if (Number.isFinite(value)) valid.push({ value, index }); else warnings.push({ code: 'INVALID_BIN_VALUE', path: `rows.${index}.${field}`, message: 'Bin input must be numeric.' }); });
+  if (!valid.length) return { rows: [], warnings, assumptions: ['Bins include the lower bound and exclude the upper bound, except the final bin.'] };
+  const sourceMin = Math.min(...valid.map(item => item.value)), sourceMax = Math.max(...valid.map(item => item.value));
+  const extent = Array.isArray(options.extent) && options.extent.length === 2 ? options.extent.map(Number) : [sourceMin, sourceMax];
+  const min = extent[0], max = extent[1];
+  const thresholdCount = Math.max(1, Math.round(Number(options.thresholds) || Math.ceil(Math.sqrt(valid.length))));
+  const step = Number(options.step) > 0 ? Number(options.step) : (max - min || 1) / thresholdCount;
+  const count = Math.max(1, Math.ceil((max - min || step) / step));
+  const bins = Array.from({ length: count }, (_, index) => ({ binStart: min + index * step, binEnd: index === count - 1 ? max : min + (index + 1) * step, [output]: 0, sourceIndices: [] }));
+  valid.forEach(item => { if (item.value < min || item.value > max) return; const index = Math.min(count - 1, Math.max(0, Math.floor((item.value - min) / step))); bins[index][output] += 1; bins[index].sourceIndices.push(item.index); });
+  return { rows: bins.map(bin => ({ ...bin, name: `${Number(bin.binStart.toFixed(6))}–${Number(bin.binEnd.toFixed(6))}`, value: bin[output] })), warnings, assumptions: ['Bins include the lower bound and exclude the upper bound, except the final bin.'] };
+}
+
+export function applyTransforms(input, transforms = []) {
+  let rows = rowsFrom(input), warnings = [], assumptions = [];
+  for (const transform of Array.isArray(transforms) ? transforms : [transforms]) {
+    if (transform?.type !== 'bin') continue;
+    const result = binData(rows, transform);
+    rows = result.rows; warnings = warnings.concat(result.warnings); assumptions = assumptions.concat(result.assumptions);
+  }
+  return { rows, warnings, assumptions };
+}