@taylorwong/ichartjs 2.0.1

package/docs/agent/zh-CN/theme-guide.md

@@ -0,0 +1,50 @@
+# 视觉样式与主题指南
+
+iChart.js 2.0 内置轻量、与 Renderer 无关的样式系统。Agent 应表达场景和数据语义，由 Runtime 解析颜色、字号、间距和标记样式，不应为每张图随意生成一套视觉配置。
+
+## 三层样式模型
+
+- `mode`：`auto`、`light`、`dark`、`contrast`。
+- `preset`：`auto`、`analysis`、`dashboard`、`report`、`presentation`、`project`、`diagram`。
+- `palette`：`auto`、`categorical`、`sequential`、`diverging`、`status`。
+
+推荐默认使用 `auto`。系统根据图表家族、用户意图、数据语义和宿主明暗模式进行确定性匹配。解析结果可通过 `planStyle()`、`planChart().styleRecommendation`、`chart.getTheme()`、`chart.getState().style` 和 `chart.explain().style` 查看。
+
+## Agent 使用方式
+
+```js
+const plan = planChart(rows, { intent: 'comparison', context: 'dashboard' });
+const spec = {
+  type: plan.primary,
+  data: { values: rows },
+  theme: {
+    mode: 'auto',
+    preset: plan.styleRecommendation.preset,
+    palette: plan.styleRecommendation.palette
+  }
+};
+```
+
+仅在用户明确要求明暗模式、展示场景或语义配色时提供显式值；用户选择始终高于自动匹配。
+
+## 实时切换
+
+```js
+chart.setTheme({ mode: 'dark', preset: 'dashboard', palette: 'categorical' });
+const resolved = chart.getTheme();
+```
+
+切换不会重建图表。`mode: 'auto'` 会跟随宿主的 `prefers-color-scheme`。Spec 中显式提供的 `colors`、`background` 和 `padding` 在切换时保持不变。
+
+## 配色原则
+
+- `categorical`：不同系列或分组，同时比较建议不超过 6 色。
+- `sequential`：有序数值强度，例如 Heatmap。
+- `diverging`：存在有意义的中点，且数据向两侧变化。
+- `status`：成功、警告、危险、信息等业务状态。
+- 不只依赖颜色传达含义，应保留标签、形状、线型或文字状态。
+
+自定义 token 后调用 `validateThemeContrast()`；Agent 不应隐藏对比度警告。
+
+预览与验收：`http://localhost:3000/playground/theme-gallery.html`。
+

package/docs/manifests/capabilities.json

@@ -0,0 +1,79 @@
+{
+  "version": "2.0",
+  "contractVersion": "1.0",
+  "source": "src/index.mjs#getCapabilities",
+  "perChartProfiles": "src/index.mjs#getChartCapability",
+  "agentPlanning": "src/index.mjs#planChart",
+  "agentExplanation": "Chart#explain",
+  "agentQuickstart": "docs/agent/quickstart.md",
+  "agentWorkflowExample": "examples/agent-workflow.mjs",
+  "officialSkill": "skills/ichartjs/SKILL.md",
+  "scenarios": {
+    "charting": ["line", "area", "bar", "column", "pie", "scatter", "funnel", "gauge", "heatmap", "radar"],
+    "project": ["gantt", "timeline", "milestone", "burndown"],
+    "diagram": ["flow", "swimlane"]
+  },
+  "projectIntelligence": ["variance", "capacity", "release", "risk", "aging"],
+  "chartModes": ["stacked", "percent-stacked", "donut", "mixed-line-column", "bin"],
+  "renderers": ["canvas", "svg"],
+  "excluded": ["map", "3d"],
+  "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": {
+    "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."
+  },
+  "gallery": "playground/project-gallery.html",
+  "playgroundHome": "playground/index.html",
+  "agentWorkbench": "playground/agent-workbench.html",
+  "interactionLab": "playground/interaction-lab.html",
+  "accessibilityLab": "playground/accessibility-lab.html",
+  "performanceLab": "playground/performance-lab.html",
+  "businessEditingDemo": "playground/editing.html",
+  "diagramEditor": "playground/diagram-editor.html",
+  "projectIntelligenceDemo": "playground/project-intelligence.html",
+  "foundationalGallery": "playground/foundational-gallery.html",
+  "themeGallery": "playground/theme-gallery.html",
+  "themeGuide": "docs/agent/theme-guide.md",
+  "styleSystem": {
+    "modes": ["auto", "light", "dark", "contrast"],
+    "presets": ["auto", "analysis", "dashboard", "report", "presentation", "project", "diagram"],
+    "palettes": ["auto", "categorical", "sequential", "diverging", "status"]
+  },
+  "branding": {
+    "defaultEnabled": true,
+    "signature": "Powered by iChart.js",
+    "options": [
+      { "name": "enabled", "type": "boolean", "default": true }
+    ],
+    "notes": [
+      "Default signature rendered in the bottom-right corner inside the chart safe padding, 10px / font-weight 500, theme.muted color with ~0.42 opacity, decorative and non-interactive.",
+      "Agents MUST keep branding enabled by default; only disable when the user explicitly requests a white-label / no-brand output or already provides their own signature.",
+      "Short form `branding: false` and object form `branding: { enabled: false }` are both supported. Custom text, link, position, or font are intentionally NOT exposed in the current iteration."
+    ]
+  }
+}

package/docs/manifests/commands.json

@@ -0,0 +1,30 @@
+{
+  "version": "1.0",
+  "source": "src/command.mjs#operationTypes",
+  "commands": {
+    "updateField": { "models": ["project-task", "timeline-event", "milestone", "burndown-sample", "flow-node", "flow-edge", "swimlane"], "previewRequired": true, "undoable": true },
+    "updateRecord": { "models": ["project-task", "timeline-event", "milestone", "burndown-sample", "flow-node", "flow-edge", "swimlane"], "previewRequired": true, "undoable": true },
+    "updateTask": { "models": ["project-task"], "previewRequired": true, "undoable": true },
+    "shiftTask": { "models": ["project-task"], "required": ["taskId", "days"], "previewRequired": true, "undoable": true },
+    "updateProgress": { "models": ["project-task"], "required": ["taskId", "progress"], "previewRequired": true, "undoable": true },
+    "addDependency": { "models": ["project-task"], "required": ["taskId", "dependencyId"], "previewRequired": true, "undoable": true },
+    "removeDependency": { "models": ["project-task"], "required": ["taskId", "dependencyId"], "previewRequired": true, "undoable": true },
+    "updateMilestone": { "models": ["milestone"], "required": ["recordId"], "previewRequired": true, "undoable": true },
+    "moveNode": { "models": ["flow-node"], "required": ["nodeId", "position"], "previewRequired": true, "undoable": true },
+    "moveNodes": { "models": ["flow-node"], "required": ["nodeIds", "delta"], "previewRequired": true, "undoable": true },
+    "moveNodeToLane": { "models": ["flow-node"], "required": ["nodeId", "laneId"], "previewRequired": true, "undoable": true },
+    "resizeNode": { "models": ["flow-node"], "required": ["nodeId", "size"], "previewRequired": true, "undoable": true },
+    "alignNodes": { "models": ["flow-node"], "required": ["nodeIds", "alignment"], "previewRequired": true, "undoable": true },
+    "snapNodes": { "models": ["flow-node"], "required": ["nodeIds"], "previewRequired": true, "undoable": true },
+    "moveGroup": { "models": ["flow-node"], "required": ["groupId", "delta"], "previewRequired": true, "undoable": true },
+    "resizeGroup": { "models": ["flow-node"], "required": ["groupId", "size"], "previewRequired": true, "undoable": true },
+    "assignNodesToGroup": { "models": ["flow-node"], "required": ["nodeIds", "groupId"], "previewRequired": true, "confirmationRequired": true, "undoable": true },
+    "duplicateGroup": { "models": ["flow-node", "flow-edge"], "required": ["groupId"], "previewRequired": true, "confirmationRequired": true, "undoable": true },
+    "deleteGroup": { "models": ["flow-node", "flow-edge"], "required": ["groupId", "policy"], "previewRequired": true, "confirmationRequired": true, "undoable": true },
+    "updateEdge": { "models": ["flow-edge"], "required": ["edgeId", "changes"], "previewRequired": true, "undoable": true },
+    "addEdge": { "models": ["flow-edge"], "required": ["from", "to"], "previewRequired": true, "confirmationRequired": true, "undoable": true },
+    "toggleGroupCollapse": { "models": ["flow-node"], "required": ["groupId"], "previewRequired": true, "confirmationRequired": true, "undoable": true },
+    "duplicateSelection": { "models": ["flow-node", "flow-edge"], "required": ["nodeIds"], "previewRequired": true, "confirmationRequired": true, "undoable": true },
+    "pasteSelection": { "models": ["flow-node", "flow-edge"], "required": ["nodes"], "previewRequired": true, "confirmationRequired": true, "undoable": true }
+  }
+}

package/docs/manifests/schemas.json

@@ -0,0 +1,13 @@
+{
+  "version": "1.0",
+  "source": "src/schema.mjs#getBusinessSchema",
+  "models": {
+    "project-task": { "key": "id", "required": ["id", "name", "start", "end"], "editable": ["name", "start", "end", "progress", "status", "dependencies"] },
+    "timeline-event": { "key": "id", "required": ["id", "title", "date"], "editable": ["title", "date", "description", "status"] },
+    "milestone": { "key": "id", "required": ["id", "title", "date"], "editable": ["title", "date", "status"] },
+    "burndown-sample": { "key": "id", "required": ["id", "date", "remaining"], "editable": ["date", "remaining", "scopeChange"] },
+    "flow-node": { "key": "id", "required": ["id", "label"], "editable": ["label", "position", "size", "laneId", "description", "status"] },
+    "flow-edge": { "key": "id", "required": ["id", "from", "to"], "editable": ["from", "to", "label"] },
+    "swimlane": { "key": "id", "required": ["id", "label"], "editable": ["label"] }
+  }
+}

package/examples/agent-workflow.mjs

@@ -0,0 +1,94 @@
+import { pathToFileURL } from 'node:url';
+import {
+  createChart,
+  getCapabilities,
+  getChartCapability,
+  inspectData,
+  planChart,
+  recommend,
+  validateSpec
+} from '@taylorwong/ichartjs';
+export const sampleRows = [
+  { id: 'jan', month: 'Jan', revenue: 120, cost: 82 },
+  { id: 'feb', month: 'Feb', revenue: 148, cost: 91 },
+  { id: 'mar', month: 'Mar', revenue: 136, cost: 88 },
+  { id: 'apr', month: 'Apr', revenue: 176, cost: 105 }
+];
+
+function buildCandidate(rows, plan, renderer) {
+  const measureFields = [plan.suggestedEncodings.measure, plan.suggestedEncodings.secondaryMeasure].filter(Boolean);
+  return {
+    type: plan.primary,
+    renderer,
+    data: { values: rows },
+    title: { text: `Agent plan: ${plan.intent}`, subtitle: `confidence ${plan.confidence}` },
+    encoding: {
+      x: { field: plan.suggestedEncodings.dimension, type: 'category' },
+      y: measureFields.length === 1 ? { field: measureFields[0], type: 'quantitative' } : measureFields.map(field => ({ field, type: 'quantitative' }))
+    },
+    interaction: { tooltip: true, hover: true, keyboard: true },
+    accessibility: { enabled: true },
+    theme: {
+      mode: 'auto',
+      preset: plan.styleRecommendation.preset,
+      palette: plan.styleRecommendation.palette
+    }
+  };
+}
+
+export function runAgentWorkflow(rows, options = {}) {
+  const intent = options.intent || 'trend';
+  const renderer = options.renderer || 'svg';
+  const capabilities = getCapabilities();
+  const inspection = inspectData(rows);
+  const plan = planChart(rows, { intent, renderer, context: options.context || 'analysis' });
+
+  if (plan.requiredFields.length) {
+    return { ok: false, stage: 'planning', capabilitiesContract: capabilities.contractVersion, inspection, plan };
+  }
+
+  const candidate = buildCandidate(rows, plan, renderer);
+  const validation = validateSpec(candidate);
+  if (!validation.valid) {
+    return { ok: false, stage: 'validation', capabilitiesContract: capabilities.contractVersion, inspection, plan, candidate, validation };
+  }
+
+  const chart = createChart(validation.spec);
+  try {
+    const explanation = chart.explain();
+    const state = chart.getState();
+    return {
+      ok: true,
+      stage: 'complete',
+      capabilitiesContract: capabilities.contractVersion,
+      inspection,
+      plan,
+      capability: getChartCapability(plan.primary),
+      validation,
+      explanation,
+      state,
+      selfCheck: {
+        chartDeclared: capabilities.chartTypes.includes(plan.primary),
+        recordIdsPreserved: rows.every(row => explanation.lineage.recordIds.includes(row.id)),
+        warningsVisible: plan.warnings.every(warning => state.warnings.some(item => item.code === warning.code)),
+        styleExplained: explanation.style?.preset === plan.styleRecommendation.preset
+      },
+      export: JSON.parse(chart.export({ type: 'json' }))
+    };
+  } finally {
+    chart.destroy();
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const result = runAgentWorkflow(sampleRows);
+  console.log(JSON.stringify({
+    ok: result.ok,
+    stage: result.stage,
+    chartType: result.plan.primary,
+    confidence: result.plan.confidence,
+    encodings: result.explanation?.encodings,
+    warnings: result.state?.warnings || result.plan.warnings,
+    selfCheck: result.selfCheck
+  }, null, 2));
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@taylorwong/ichartjs",
+  "version": "2.0.1",
+  "description": "Agent-first, renderer-independent charting and project visualization runtime",
+  "type": "module",
+  "main": "./src/index.mjs",
+  "module": "./src/index.mjs",
+  "browser": "./src/index.mjs",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/index.mjs",
+      "default": "./src/index.mjs"
+    },
+    "./capabilities.json": "./docs/manifests/capabilities.json",
+    "./recipes/*": "./agent-recipes/*.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src/",
+    "types/",
+    "docs/agent/",
+    "docs/manifests/",
+    "agent-recipes/",
+    "examples/",
+    "skills/ichartjs/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "check": "for file in src/*.mjs; do node --check \"$file\" || exit 1; done",
+    "docs:check": "node scripts/check-agent-docs.mjs",
+    "example:agent": "node examples/agent-workflow.mjs",
+    "playground": "node scripts/serve-playground.mjs",
+    "agent:check": "npm run docs:check && npm run check && npm test",
+    "rc:check": "npm test && npm run check && git diff --check"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wanghetommy/ichartjs.git"
+  },
+  "homepage": "https://github.com/wanghetommy/ichartjs#readme",
+  "bugs": "https://github.com/wanghetommy/ichartjs/issues",
+  "keywords": ["chart", "visualization", "agent", "svg", "canvas", "gantt", "diagram"],
+  "engines": { "node": ">=18" },
+  "author": "taylorwong <wanghetommy@gmail.com>",
+  "license": "Apache-2.0"
+}

package/skills/ichartjs/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: ichartjs
+description: Plan, validate, render, explain, and safely edit iChart.js visualizations from tabular, project, or diagram data. Use when Codex needs to choose a chart, create or repair an iChart.js Spec, build a browser preview, produce Gantt or project analytics, create Flow or Swimlane diagrams, or verify visualization accessibility, diagnostics, lineage, and runtime state.
+---
+
+# iChart.js
+
+Use the public Agent contract as the source of truth. Do not infer capabilities from renderer internals or duplicate chart-selection logic in generated code.
+
+## Source and Runtime Setup
+
+- Official repository: `https://github.com/wanghetommy/ichartjs`
+- Official Skill source: `https://github.com/wanghetommy/ichartjs/tree/master/skills/ichartjs`
+- Supported Skill hosts include Codex, WorkBuddy, and other Agent Skills-compatible environments.
+
+The Skill is a workflow adapter, not the chart runtime. If the current JavaScript or TypeScript project does not already depend on iChart.js, install the matching runtime from GitHub:
+
+```bash
+npm install @taylorwong/ichartjs@^2
+```
+
+Do not install the unscoped npm registry package named `ichartjs`; it is currently a security holding package and is not this project.
+
+## Workflow
+
+1. Locate the package or repository root. Read `docs/agent/quickstart.md` when available.
+2. Call `getCapabilities()` before selecting a chart or interaction.
+3. Call `inspectData()` and preserve stable record IDs.
+4. Call `planChart(data, { intent, renderer, context })` and inspect the complete result, including `styleRecommendation`.
+5. Stop when `requiredFields` is non-empty; request data or explain a supported alternative.
+6. Build a JSON-serializable Spec using `suggestedEncodings`, the selected capability, and an applicable recipe.
+7. Call `validateSpec()` before rendering. Repair only from structured diagnostics.
+8. Call `createChart()` only after validation succeeds.
+9. Self-check with `chart.explain()`, `chart.getState()`, and JSON export.
+10. Provide an exact preview URL or artifact path and report assumptions, warnings, and deferred checks.
+11. Prefer `theme: { mode: 'auto', preset, palette }`; preserve explicit user style choices and use `chart.setTheme()` for live switching.
+
+Use `ichartjs` for package imports. Use `examples/agent-workflow.mjs` as the executable baseline when working in the repository.
+
+## Task Routing
+
+- For standard data analysis, read `references/chart-selection.md` and use foundational recipes.
+- For Gantt, Timeline, Milestone, Burndown, capacity, release, risk, or aging, use project capabilities and `agent-recipes/project-management.json`.
+- For Flow or Swimlane, preserve node, edge, lane, group, and port IDs; use diagram recipes and validated edit commands.
+- For business edits, preview first, preserve the preview ID and revision, require confirmation when declared, then commit or reject atomically.
+- For browser deliverables, start `npm run playground` and return the exact maintained Playground URL.
+
+## Guardrails
+
+- Never invent fields, units, dates, dependencies, calendar rules, domains, or forecast confidence.
+- Never silently drop validation errors, warnings, assumptions, normalizations, or unsupported requests.
+- Avoid Pie for high-cardinality categories; prefer Bar for comparison.
+- Require explicit Radar domains when units differ.
+- Distinguish missing Heatmap values from zero.
+- Use categorical, sequential, diverging, or status palettes by data semantics; do not invent arbitrary color sets or rely on color alone.
+- Surface theme contrast diagnostics and high-cardinality color warnings.
+- Do not generate Map or 3D Specs unless capabilities explicitly add them.
+- Prefer SVG for accessibility, DOM interaction, and diagram editing; prefer Canvas for larger mark counts when supported.
+- Destroy replaced charts and verify lifecycle cleanup.
+
+## Deliverable
+
+Return:
+
+- the selected chart and reasons;
+- the validated Spec or structured repair request;
+- assumptions, warnings, and unsupported requests;
+- explanation lineage and runtime self-check;
+- changed files when coding;
+- the exact preview URL and acceptance actions.
+
+Read `references/agent-contract.md` for the required API sequence and response checklist. Read `references/chart-selection.md` only when selecting or challenging a chart type.

package/skills/ichartjs/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "iChart.js Agent Charting"
+  short_description: "Plan, validate, render, and explain iChart.js charts"
+  default_prompt: "Use $ichartjs to inspect this dataset, choose a chart, validate the Spec, and provide a preview path."

package/skills/ichartjs/references/agent-contract.md

@@ -0,0 +1,39 @@
+# Agent Contract
+
+## Required sequence
+
+```text
+getCapabilities → inspectData → planChart → build Spec → validateSpec → createChart → explain/getState/export → destroy
+```
+
+## Public APIs
+
+- `getCapabilities()`: global and per-chart discoverability.
+- `getChartCapability(type)`: required roles, interactions, renderers, features, exports, and limits.
+- `inspectData(input)`: field roles, identifiers, cardinality, missingness, temporal coverage, and warnings.
+- `planChart(input, options)`: primary type, alternatives, confidence, reasons, required fields, suggested encodings, assumptions, warnings, unsupported requests, and next actions.
+- `validateSpec(spec)`: errors, warnings, normalizations, and normalized Spec.
+- `createChart(spec)`: headless or mounted chart lifecycle.
+- `chart.explain()`: semantics, encodings, interactions, lineage, warnings, and accessibility summary.
+- `chart.getState()`: renderer, dimensions, warnings, assumptions, selection, view, project analytics, and linked state.
+- `chart.export({ type: 'json' })`: JSON-safe Spec and state.
+
+## Stop conditions
+
+Do not render when:
+
+- `plan.requiredFields` is non-empty;
+- `validateSpec().valid` is false;
+- the requested chart, renderer, interaction, or export is not declared;
+- required project dates, diagram endpoints, ports, lanes, or business schema rules are invalid.
+
+## Self-check
+
+Verify that:
+
+- the chosen type exists in `getCapabilities().chartTypes`;
+- validation passed without ignored errors;
+- explanation lineage preserves stable source IDs;
+- warnings and assumptions are visible in the response;
+- the preview uses a maintained URL;
+- replaced charts are destroyed.

package/skills/ichartjs/references/chart-selection.md

@@ -0,0 +1,22 @@
+# Chart Selection
+
+| Intent | Preferred type | Important guardrail |
+| --- | --- | --- |
+| Trend or time series | Line | Require an ordered or temporal dimension. |
+| Cumulative trend | Area | Use stacking only for meaningful additive measures. |
+| Category comparison or ranking | Bar | Prefer for long labels and negative values. |
+| Compact comparison or histogram | Column | Use the bin transform for histogram workflows. |
+| Part-to-whole | Pie with optional `innerRadius` | Keep category count low and require a positive total. |
+| Relationship | Scatter | Require two quantitative measures. |
+| Conversion stages | Funnel | Preserve stage order. |
+| Single bounded KPI | Gauge | Declare the domain. |
+| Matrix | Heatmap | Distinguish missing cells from zero. |
+| Multidimensional profile | Radar | Require at least three explicit indicator domains. |
+| Schedule and dependency analysis | Gantt | Require stable IDs, dates, and explicit calendar assumptions. |
+| Events | Timeline | Require valid dates and labels. |
+| Delivery checkpoints | Milestone | Keep baseline and actual dates distinct. |
+| Remaining work | Burndown | Surface scope changes and forecast assumptions. |
+| Process | Flow | Preserve node and edge IDs; validate endpoints and ports. |
+| Responsibility | Swimlane | Require valid lane membership. |
+
+Always prefer `planChart()` over this table when runtime capability output is available. Treat alternatives as tradeoffs, not automatic fallbacks.