@taylorwong/ichartjs 2.0.1

package/docs/agent/runtime-contract.md

@@ -0,0 +1,132 @@
+# Runtime Contract
+
+Shared iChart.js 2.0 Runtime rules used by all three scenarios.
+
+## Standard Flow
+
+```text
+getCapabilities → inspectData → planChart → create Spec → validateSpec → createChart → explain and inspect state
+```
+
+Agents should use `getCapabilities()` first instead of hard-coding undeclared types or operations.
+
+Iteration 8 adds per-chart profiles through `getChartCapability(type)`. Each profile declares required data roles, supported interactions, renderers, feature status, exports, and practical limits. Unsupported behavior must be handled from this profile or from validation diagnostics rather than guessed.
+
+`planChart(data, { intent, renderer })` returns a versioned planning result with a primary chart, alternatives, confidence, reasons, required fields, suggested encodings, assumptions, warnings, unsupported requests, safe next actions, and the selected capability profile. Planning never invents business meaning, units, dates, or missing fields.
+
+## Spec Rules
+
+- Specs must be JSON-serializable.
+- Call `validateSpec()` before rendering.
+- Chart layout and data semantics are renderer-independent.
+- `flow` and `swimlane` use `nodes/edges/lanes`; generic charts use `data.values`.
+
+## Renderer
+
+- Use `svg` for DOM-level interaction, accessibility, and Diagram editing.
+- Use `canvas` for many marks and lower DOM overhead.
+
+## Branding (Signature)
+
+iChart.js ships with a low-contrast brand signature (`Powered by iChart.js`) in the bottom-right corner of every chart by default.
+
+### Configuration
+
+Control via the `branding` field on Spec or Theme:
+- `branding: true` (default): signature enabled.
+- `branding: false`: signature disabled.
+- `branding: { enabled: true }`: explicit object form for fine-grained control.
+
+### Consistency Guarantee
+
+The on/off decision is resolved once inside `buildScene()` via a single gate, so these four surfaces are always synchronized:
+1. Browser Canvas / SVG live rendering.
+2. `chart.export({ type:'png|jpeg' })` raster output.
+3. `chart.export({ type:'svg' })` vector output.
+4. `chart.export({ type:'json' })` persisted `spec.branding` + `state`.
+
+When `branding:false`, no signature text appears on the chart or any exported artifact, and the extra bottom padding is not reserved.
+
+## Exports and Downloads
+
+iChart.js exports use a **dual-engine single-source architecture**. Every artifact shares the same Scene Graph produced by `buildScene()`, and the on-screen renderer is fully decoupled from the export backend:
+1. **PNG / JPEG (raster)**: always drawn by a `CanvasRenderer` replaying the shared Scene Graph synchronously. In headless Node, install the optional `canvas` npm package to enable.
+2. **SVG (vector)**: serialized from an `SVGRenderer` DOM tree (browser) or assembled as a pure string with zero dependencies (headless). Includes XML 1.0 header, expanded font properties, and accessibility attributes.
+3. **JSON (reconstructable)**: serializes the current `spec` plus `getState()`, used for persistence, agent self-check, and cross-environment rebuild.
+
+### Branding Consistency
+
+The signature gate inside `buildScene()` guarantees that live rendering, SVG export, PNG export, and JSON state are 100% aligned.
+
+### Headless Support Matrix
+
+| Type        | Browser (any renderer) | Node headless, zero deps | Node headless + `canvas` dep |
+|-------------|------------------------|--------------------------|------------------------------|
+| JSON        | ✅                      | ✅                        | ✅                            |
+| SVG         | ✅                      | ✅                        | ✅                            |
+| PNG / JPEG  | ✅ true raster, sync    | ❌ structured `HEADLESS_EXPORT_UNSUPPORTED` | ✅ |
+
+### Public Export APIs
+
+- `chart.toDataURL(type='image/png')` → data URL string or structured ExportError.
+- `chart.toBlob(type='image/png')` → Blob or ExportError (headless returns `BLOB_HEADLESS`).
+- `chart.export({ type, as })` → sync string / JSON object / Blob / ExportError. `as` accepts `string`, `dataurl`, `blob`, `object` (JSON only).
+- `chart.exportAsync({ type, as })` → Promise wrapper for future async scenarios.
+- `chart.download({ type })` / `downloadPNG()` / `downloadSVG()` / `downloadJSON()` → triggers a browser save-as. In headless, falls back to returning the raw string or structured error.
+
+### Structured Error Shape
+
+All export/download methods return a stable `{ valid:false, code, message?, suggestion?, rasterCode? }` object on failure for reliable agent automation. Common `code` values:
+- `HEADLESS_EXPORT_UNSUPPORTED`: raster export requested in headless without the optional `canvas` package.
+- `BLOB_HEADLESS`: `toBlob` or `as=blob` used in headless (Blob requires a browser runtime).
+- `DOWNLOAD_HEADLESS`: `chart.download*()` in headless; use `chart.export()` instead.
+- `EXPORT_TYPE_UNSUPPORTED`: unrecognized export type.
+
+## Common APIs
+
+```text
+inspectData(data)
+normalizeData(data)
+recommend(data, options)
+planChart(data, options)
+validateSpec(spec)
+createChart(spec)
+getCapabilities()
+getChartCapability(type)
+chart.describe()
+chart.explain()
+chart.getState()
+chart.getSelectedData()
+chart.export(options)
+chart.exportAsync(options)
+chart.toDataURL(type)
+chart.toBlob(type)
+chart.download(options)
+chart.downloadPNG()
+chart.downloadSVG()
+chart.downloadJSON()
+```
+
+Validation results contain separate `errors`, `warnings`, and `normalizations`. Diagnostics use stable codes, JSON-oriented paths, expected values where useful, and actionable suggestions. `chart.explain()` returns encodings, transforms, interactions, assumptions, warnings, stable record lineage, and an accessibility summary.
+
+## Interaction
+
+Common interactions include Tooltip, Hover, Click, Selection, Zoom, Pan, Drag, Touch, and Keyboard; each chart's enabled interactions are controlled by its Spec and capability declaration.
+
+## Implementation Map
+
+- Public runtime: `src/index.mjs`
+- Spec: `src/spec.mjs`
+- Scene: `src/scene.mjs`
+- Renderers: `src/renderer.mjs`
+- Charts: `src/charts.mjs`
+- Capabilities: `src/capabilities.mjs`
+- Plugins: `src/plugin.mjs`
+- Scales: `src/scale.mjs`
+
+## Acceptance
+
+- The Gallery covers every `getCapabilities().chartTypes` entry.
+- Canvas and SVG use the same Scene data structure.
+- Invalid Specs return structured errors with `code`, `path`, `message`, and `suggestion`.
+- Branding visibility is 100% synchronized between on-screen rendering and every export format (PNG/SVG/JSON).

package/docs/agent/theme-guide.md

@@ -0,0 +1,59 @@
+# Visual Style and Theme Guide
+
+iChart.js 2.0 includes a lightweight renderer-neutral style system. Agents should request semantic style intent and let the runtime resolve concrete tokens instead of inventing colors, font sizes, or spacing per chart.
+
+## Style Model
+
+The system composes three independent choices:
+
+- `mode`: `auto`, `light`, `dark`, or `contrast`.
+- `preset`: `auto`, `analysis`, `dashboard`, `report`, `presentation`, `project`, or `diagram`.
+- `palette`: `auto`, `categorical`, `sequential`, `diverging`, or `status`.
+
+`auto` is the recommended default. It uses chart family, intent, data semantics, and the host color scheme. Resolution is deterministic and exposed through `planStyle()`, `planChart().styleRecommendation`, `chart.getTheme()`, `chart.getState().style`, and `chart.explain().style`.
+
+## Agent Workflow
+
+```js
+import { createChart, planChart, planStyle, validateSpec } from '@taylorwong/ichartjs';
+
+const plan = planChart(rows, { intent: 'comparison', context: 'dashboard' });
+const style = planStyle({ type: plan.primary, data: rows }, { context: 'dashboard' });
+const spec = {
+  type: plan.primary,
+  data: { values: rows },
+  theme: { mode: 'auto', preset: style.preset, palette: style.palette }
+};
+
+const validation = validateSpec(spec);
+if (!validation.valid) throw new Error(JSON.stringify(validation.errors));
+const chart = createChart(validation.spec);
+```
+
+Use explicit values only when the user requests a mode, presentation context, or semantic palette. A user override always wins over automatic matching.
+
+## Runtime Switching
+
+Switch styles without recreating the chart:
+
+```js
+chart.setTheme({ mode: 'dark', preset: 'dashboard', palette: 'categorical' });
+const resolved = chart.getTheme();
+```
+
+When `mode` is `auto`, mounted charts follow `prefers-color-scheme` changes. Explicit `colors`, `background`, and `padding` on the chart Spec remain preserved across theme changes.
+
+## Palette Rules
+
+- Use `categorical` for distinct series or groups; prefer six or fewer simultaneous comparison colors.
+- Use `sequential` for ordered magnitude such as Heatmap intensity.
+- Use `diverging` when values have a meaningful midpoint and extend in both directions.
+- Use `status` for named business states such as success, warning, danger, and information.
+- Do not use color as the only carrier of meaning. Keep labels, shapes, line patterns, or text status where applicable.
+
+## Accessibility
+
+Built-in modes expose text, muted text, axis, grid, focus, selection, missing-value, and status tokens. Call `validateThemeContrast(theme)` for custom token overrides. Do not suppress contrast warnings in Agent output.
+
+Preview and acceptance: `http://localhost:3000/playground/theme-gallery.html`.
+

package/docs/agent/zh-CN/README.md

@@ -0,0 +1,26 @@
+# iChart.js 2.0 Agent 指南（中文）
+
+这是 iChart.js 2.0 面向用户 Agent 的中文使用入口。默认先读取本文件，再按任务读取一份场景文档。
+
+## 选择场景
+
+- [Agent 快速上手](quickstart.md)
+- [编码 Agent 集成](coding-agent-integration.md)
+- [前端项目集成](frontend-integration.md)
+- [视觉样式与主题](theme-guide.md)
+- [数据分析图表](charting-scenario.md)
+- [项目管理图表](project-scenario.md)
+- [交互式 Diagram](diagram-scenario.md)
+- [Runtime 契约](runtime-contract.md)
+- [编辑契约](editing-contract.md)
+- 机器可读能力清单位于 `docs/manifests/`，供 Agent 按需读取。
+
+## 标准流程
+
+```text
+getCapabilities → inspectData → planChart → 生成 Spec → validateSpec → createChart → explain/getState
+```
+
+API 名称、字段名、命令名、错误码和 JSON Manifest 统一使用英文标识符；其语义以英文技术契约为标准，本文提供中文辅助说明。
+
+全部已支持图表的浏览入口：`playground/project-gallery.html`；主题样式验收入口：`playground/theme-gallery.html`。

package/docs/agent/zh-CN/charting-scenario.md

@@ -0,0 +1,62 @@
+# 场景：数据分析图表
+
+用于通用指标分析和数据展示的 Agent 使用与开发指南。
+
+## 图表选择
+
+| 类型 | 适用场景 | 推荐 Renderer |
+| --- | --- | --- |
+| `line` | 趋势、时间变化 | `svg` |
+| `area` | 趋势和累计量 | `svg` |
+| `bar` | 分类对比、长标签 | `svg` |
+| `column` | 紧凑分类对比 | `canvas` 或 `svg` |
+| `pie` | 少量类别占比 | `svg` |
+| `scatter` | 两个数值变量关系 | `canvas` |
+| `funnel` | 转化阶段 | `svg` |
+| `gauge` | 单指标完成度 | `canvas` |
+| `heatmap` | 矩阵强度与日历模式 | `canvas` 或 `svg` |
+| `radar` | 多维指标对比 | `svg` |
+
+## 基础模式
+
+- Bar、Column、Area 使用 `stack: "stacked"` 或 `stack: "percent"`，不新增堆叠类型。
+- Donut 使用 `type: "pie"` 配合 `innerRadius`。
+- Combo 使用每个系列的 `mark: "column"` 或 `mark: "line"`，并可设置 `axis: "right"`。
+- Histogram 使用 `transform: { type: "bin", field, thresholds | step, extent }`。
+- Heatmap 通过 `colorScale.missing` 区分缺失值和数值零。
+- Radar 应为每个指标声明 `min` 和 `max`；缺失域或混合单位会产生告警。
+
+## Agent 流程
+
+1. 使用 `inspectData(data)` 检查字段和缺失值。
+2. 根据意图选择图表，可使用 `recommend(data, { intent })`。
+3. 生成 JSON-serializable Chart Spec。
+4. 先调用 `validateSpec(spec)`，再调用 `createChart(spec)`。
+5. 使用 `chart.describe()` 和 `chart.getState()` 检查结果。
+
+## 最小 Spec
+
+```js
+{
+  type: 'line',
+  renderer: 'svg',
+  data: { values: [{ month: 'Jan', sales: 120 }] },
+  encoding: {
+    x: { field: 'month', type: 'category' },
+    y: { field: 'sales', type: 'quantitative' }
+  }
+}
+```
+
+## 开发位置与验收
+
+- Spec：`src/spec.mjs`
+- 数据：`src/data.mjs`
+- Scene：`src/charts.mjs`
+- Scale：`src/scale.mjs`
+- Renderer：`src/renderer.mjs`
+- 测试：`tests/core.test.mjs`
+- 验收：`playground/project-gallery.html`
+- Iteration 7 验收：`playground/foundational-gallery.html`
+
+新增图表必须同步更新代码、测试、Gallery、`docs/manifests/capabilities.json` 和本文件。

package/docs/agent/zh-CN/coding-agent-integration.md

@@ -0,0 +1,36 @@
+# 编码 Agent 集成
+
+本指南适用于 Codex、WorkBuddy 等能够读取仓库、编辑 JavaScript、运行测试并打开本地预览的编码 Agent。
+
+## 边界
+
+iChart.js 是 JavaScript UI 图表组件库。编码 Agent 负责修改宿主前端，并调用统一的 `ichartjs` ESM API。Skill 只提供工作流指导，不是第二套 Runtime，也不是服务接口。
+
+普通图表开发不需要 CLI、MCP、HTTP API 或 Python 适配层。
+
+## 使用方式
+
+```bash
+npm install @taylorwong/ichartjs@^2
+```
+
+npm Registry 中无作用域的 `ichartjs` 当前是安全占位包，并非本项目。正式 npm scope 确认前请从 GitHub 安装。
+
+Codex、WorkBuddy 和其他兼容 Agent Skills 的宿主可共同使用 `skills/ichartjs`。从仓库检出目录安装到 Codex：
+
+```bash
+cp -R skills/ichartjs "${CODEX_HOME:-$HOME/.codex}/skills/"
+```
+
+推荐请求：
+
+```text
+使用 $ichartjs 检查这份数据，选择并校验合适图表，加入当前页面，
+运行相关测试，并返回准确预览地址。保留所有假设和数据质量警告。
+```
+
+如果宿主不使用 `$skill-name` 语法，则在其 Skill 界面中选择或指定 `ichartjs`。
+
+Agent 应依次完成：读取项目约束、引用 `ichartjs`、发现能力、检查数据、规划图表、校验 Spec、挂载图表、自检 explanation/state、运行测试并返回预览地址。
+
+验收时确认没有引用 `src/` 内部文件，校验在渲染前通过，稳定 record ID 被保留，警告可见，并且替换页面时调用了 `destroy()`。

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

@@ -0,0 +1,31 @@
+# 开发指南
+
+指导 Coding Agent 开发 iChart.js 2.0。
+
+## 标准流程
+
+1. 判断功能属于数据分析、项目管理还是 Diagram 场景。
+2. 阅读本目录对应场景文档和当前 `development/iteration-X.md`。
+3. 定位最小源码范围，遵守文件级模块注释规则。
+4. 增加测试并实现功能，不修改无关问题。
+5. 同步 Manifest、场景文档、Recipe 和 Gallery。
+6. 运行 `npm run agent:check`。
+7. 有可查看 Demo 时，立即提供 HTTP 地址和验收步骤。
+
+## 修改映射
+
+- 通用图表：`src/spec.mjs`、`src/charts.mjs`、`src/data.mjs`。
+- 项目能力：`src/project.mjs`，必要时更新 `src/schema.mjs`。
+- Diagram 能力：`src/diagram.mjs`、`src/diagram-interaction.mjs`。
+- 公共编辑：`src/command.mjs`、`src/edit.mjs`、`src/edit-controller.mjs`。
+
+## 文档规则
+
+- 活动 `src/*.mjs` 必须有简短文件级注释。
+- 公共 API 和复杂算法增加必要 JSDoc。
+- 代码注释使用英文；中文文档是辅助版本。
+- Manifest 和 API 标识符保持英文且稳定。
+- `docs/agent/` 顶层核心文档统一使用英文，中文辅助版放在 `docs/agent/zh-CN/`；技术契约变更时同步更新两种语言。
+- 开发历史放在 `docs/agent/development/`，不作为普通 Agent 默认上下文。
+
+`npm run agent:check` 检查图表和命令清单、Schema 模型覆盖、双语文件存在性、英文核心文档中的中文残留以及 Gallery 类型覆盖，再运行语法检查和测试。它不证明翻译语义一致或浏览器交互正确；开发历史不受英文检查限制。

package/docs/agent/zh-CN/diagram-scenario.md

@@ -0,0 +1,37 @@
+# 场景：交互式 Diagram
+
+用于流程建模、责任分工和可编辑 Diagram。
+
+## 类型
+
+- `flow`：节点和边组成的流程图。
+- `swimlane`：带责任泳道的流程图。
+
+## 当前能力
+
+已支持节点、边、泳道、Group、Port、四种布局、三种路由、节点拖动、多选、对齐、网格吸附、键盘移动和 Undo/Redo。
+
+当前限制：
+
+- Group 只支持平级 Group，不支持嵌套。
+- Port 可显示并参与路由，但 Port 拖拽连线尚未完成。
+- Copy/Paste 和 Group 折叠展开尚未完成。
+
+## Agent 流程
+
+1. 为节点和边分配稳定 ID。
+2. 使用 `validateDiagram(spec)` 检查端点、Port、Group、Lane 和布局。
+3. 使用 `createChart(spec)` 创建图表。
+4. 使用 `moveNodes`、`alignNodes`、`snapNodes` 等命令编辑。
+5. 编辑遵循 `editing-contract.md` 的 Preview/Confirm/Commit 流程。
+
+## 开发位置与验收
+
+- 模型、校验、布局、路由：`src/diagram.mjs`
+- 交互：`src/diagram-interaction.mjs`
+- Scene：`src/project.mjs`
+- 命令事务：`src/command.mjs`、`src/edit-controller.mjs`
+- 专用 Demo：`playground/diagram-editor.html`
+- 全量 Gallery：`playground/project-gallery.html`
+
+节点移动后必须验证边、箭头和标签跟随；同时检查 Canvas 与 SVG 的一致性。

package/docs/agent/zh-CN/editing-contract.md

@@ -0,0 +1,27 @@
+# 编辑契约
+
+Agent 对业务数据和 Diagram 数据的安全编辑协议。
+
+## 必须遵循的流程
+
+```text
+读取 Schema → 构造 Command → Validate → Preview → Confirm → Commit → ChangeSet
+```
+
+不要直接修改业务数据对象，使用 Chart 编辑 API。
+
+```js
+const preview = chart.previewEdit(command);
+if (!preview.valid) return preview.errors;
+const result = chart.applyEdit(command, { preview, confirmed: true, source: 'agent' });
+```
+
+## 规则
+
+- 命令版本为 `1.0`，目标使用稳定 ID。
+- Preview 和 Commit 的命令必须一致。
+- 默认需要 Host 确认；确认不等同于授权。
+- 成功提交产生 ChangeSet、审计信息、revision 和 Undo 历史。
+- 外部持久化、权限和认证由 Host 应用负责。
+
+Schema、命令、Preview/Commit、事务和历史的实现分别位于 `src/schema.mjs`、`src/command.mjs`、`src/edit.mjs`、`src/edit-controller.mjs` 和 `src/history.mjs`。

package/docs/agent/zh-CN/frontend-integration.md

@@ -0,0 +1,31 @@
+# 前端项目集成
+
+iChart.js 应作为普通 JavaScript UI 组件运行在浏览器应用中。数据加载、登录、持久化、路由以及自然语言交互都由宿主应用负责。
+
+```bash
+npm install @taylorwong/ichartjs@^2
+```
+
+无法访问 npm Registry 的环境请用 GitHub 源作为后备：`npm install github:wanghetommy/ichartjs#v2.0.1`。
+
+```js
+import { createChart } from '@taylorwong/ichartjs';
+
+const chart = createChart({
+  container: '#chart',
+  type: 'bar',
+  data: { values: rows },
+  encoding: {
+    x: { field: 'category' },
+    y: { field: 'value' }
+  }
+});
+```
+
+容器创建后再实例化图表；数据变化使用 `setData()`；配置变化使用 `update()`；组件卸载前调用 `destroy()`。
+
+如果宿主页面提供“展示销售趋势”之类的 Agent 功能，仍然在 JavaScript 中调用 `inspectData()`、`planChart()`、`validateSpec()` 和 `createChart()`，并在 UI 中展示原因、假设和警告。
+
+不能执行或生成 JavaScript 的日常助手无法直接使用任何 JS UI 组件，其宿主应用应负责集成。iChart.js 核心不提供 CLI、MCP、HTTP 服务、Python Runtime、上传、认证、存储或分享系统。
+
+本仓库可运行 `npm run playground`，然后访问 `http://localhost:3000/playground/project-gallery.html` 验收全部图表。

package/docs/agent/zh-CN/project-scenario.md

@@ -0,0 +1,40 @@
+# 场景：项目管理图表
+
+用于项目排期、交付进度和项目状态报告。
+
+## 图表选择
+
+| 类型 | 适用场景 | 核心数据 |
+| --- | --- | --- |
+| `gantt` | 任务排期、依赖、关键路径 | `id/name/start/end` |
+| `timeline` | 事件时间线 | `id/title/date` |
+| `milestone` | 关键节点 | `id/title/date` |
+| `burndown` | Sprint 剩余工作量 | `date/remaining` |
+
+## 业务规则
+
+- 日期必须有效，Gantt 的 `end` 不得早于 `start`。
+- `progress` 使用 `0–100` 百分比。
+- `dependencies` 使用稳定任务 ID，依赖图不能有环。
+- `scopeChange` 表示范围变化，不等于已完成工作量。
+- Forecast 是估计结果，不能描述为承诺或事实。
+
+## 编辑流程
+
+项目编辑统一遵循：
+
+```text
+Schema → Command → Validate → Preview → Confirm → Commit → ChangeSet
+```
+
+常用命令包括 `updateProgress`、`shiftTask`、`addDependency`、`removeDependency` 和 `updateMilestone`。
+
+## 开发位置与验收
+
+- 项目 Scene 和 Tooltip：`src/project.mjs`
+- Schema：`src/schema.mjs`
+- 命令和编辑：`src/command.mjs`、`src/edit.mjs`
+- 测试：`tests/core.test.mjs`
+- 验收：`playground/project-gallery.html`
+
+需要覆盖日期错误、循环依赖、Scope Change、Forecast 和编辑历史。

package/docs/agent/zh-CN/quickstart.md

@@ -0,0 +1,84 @@
+# Agent 快速上手
+
+当 Agent 需要把业务数据、项目数据或流程数据转换为 iChart.js 可视化时，使用本指南。只依赖公开契约，不读取渲染器或图表内部实现来猜测能力。
+
+## 引用入口
+
+```js
+import {
+  createChart,
+  getCapabilities,
+  getChartCapability,
+  inspectData,
+  planChart,
+  validateSpec
+} from '@taylorwong/ichartjs';
+```
+
+- `ichartjs`：统一的 Agent 规划与 Runtime API。
+- `ichartjs/capabilities.json`：机器可读能力清单，包含逐图表导出、署名和交互声明。
+- `ichartjs/recipes/*`：基础分析、项目管理和 Diagram Recipes。
+- `skills/ichartjs/SKILL.md`：适用于 Codex、WorkBuddy 等 Agent Skills 兼容宿主的可选编排层。
+
+Agent 与开发者使用同一个 ESM 入口。编码 Agent 的完整方式见 [编码 Agent 集成](coding-agent-integration.md)，普通应用集成见 [前端项目集成](frontend-integration.md)。
+
+## 标准流程
+
+```text
+发现能力 → 检查数据 → 规划图表 → 构建 Spec → 校验 → 渲染 → 解释、导出和自检
+```
+
+1. 调用 `getCapabilities()`，不要自行创造图表类型或配置项。
+2. 调用 `inspectData()`，检查字段角色、标识符、维度、度量、时间范围、缺失值和警告。
+3. 调用 `planChart()`，同时读取主推荐、备选方案、置信度、缺失字段、假设、警告、不支持请求和 `styleRecommendation`。
+4. 当 `requiredFields` 非空时停止渲染，向用户请求数据或选择有依据的备选方案。
+5. 构建 JSON 可序列化的 Spec，并调用 `validateSpec()`。Spec 可通过 `branding: false` 显式关闭品牌署名；默认保留署名以提升项目可见性。
+6. 仅在 `validation.valid` 为 `true` 时调用 `createChart()`。
+7. 用 `chart.explain()`、`chart.getState()`、JSON/SVG/PNG export 完成自检。需要持久化或附件生成时使用 `chart.export({type:'json'|'svg'|'png'})`，在浏览器环境可调用 `chart.downloadPNG()` / `chart.downloadSVG()` / `chart.downloadJSON()` 触发保存，最后调用 `chart.destroy()`。
+
+## 品牌署名（Branding）默认行为
+
+- 默认 `branding: true`：在画面与所有导出产物（PNG/SVG/JSON）右下角同步出现 `Powered by iChart.js` 低对比度署名。
+- 关闭：在 Spec 或 Theme 中显式设置 `branding: false`，此时画面和所有导出产物都不会出现署名，同时不再额外预留底部 padding。
+- 一致性：署名开关由 Scene Graph 总闸统一判定，画面渲染与导出 100% 同步。
+
+## 导出用例速览
+
+```js
+// 1. JSON：可跨端重建 + agent 自检（全环境零依赖）
+const json = chart.export({ type: 'json' });
+const obj = chart.export({ type: 'json', as: 'object' });
+
+// 2. SVG：矢量保真，浏览器 + 无头零依赖
+const svg = chart.export({ type: 'svg' });
+const svgDataUrl = chart.export({ type: 'svg', as: 'dataurl' });
+
+// 3. PNG / JPEG：同步真光栅
+//    浏览器：任意 renderer 均可
+//    无头：需安装 npm i canvas，否则返回结构化错误 code=HEADLESS_EXPORT_UNSUPPORTED
+const png = typeof document !== 'undefined' ? chart.toDataURL('image/png') : null;
+```
+
+## Agent 输出要求
+
+最终结果应包含：
+
+- 选择的图表及原因；
+- 使用的字段和转换；
+- 假设、警告和不支持能力；
+- 校验结果；
+- 稳定 record ID 的 lineage；
+- 品牌署名（Branding）开关状态，避免可见与导出不一致；
+- 可访问的预览 URL 或导出产物（JSON/SVG/PNG/JPEG）路径。
+
+不要虚构字段、单位、日期、依赖关系、日历规则或预测置信度。Radar 使用混合单位时必须提供显式 domain；Heatmap 必须区分缺失值和零；高基数占比数据优先使用 Bar 而不是 Pie。
+
+## 完整示例
+
+```bash
+npm run example:agent
+```
+
+完整代码位于 [`../../../examples/agent-workflow.mjs`](../../../examples/agent-workflow.mjs)，包含 inspect→plan→validate→create→explain→export→destroy 的完整链路。交互验收可运行 `npm run playground`，然后打开 `http://localhost:3000/playground/agent-workbench.html`。在所有 Gallery 页面点击右上角导出按钮可验证 PNG / SVG / JSON 下载行为。
+
+样式自动匹配与用户切换见[视觉样式与主题](theme-guide.md)，可在 `http://localhost:3000/playground/theme-gallery.html` 验收。

package/docs/agent/zh-CN/runtime-contract.md

@@ -0,0 +1,85 @@
+# Runtime 契约
+
+三个开发场景共用的 Runtime 规则。
+
+## 标准流程
+
+```text
+getCapabilities → inspectData → planChart → 创建 Spec → validateSpec → createChart → 解释并检查状态
+```
+
+Agent 应优先使用 `getCapabilities()`，不要硬编码未声明的图表类型或操作。
+
+Iteration 8 通过 `getChartCapability(type)` 提供逐图表能力档案，包括必需数据角色、支持的交互、Renderer、功能状态、导出和建议限制。Agent 不应猜测未声明能力。
+
+`planChart(data, { intent, renderer })` 返回版本化规划结果：主选图表、备选项、置信度、原因、缺失字段、建议编码、假设、警告、不支持请求和安全下一步。规划不会虚构业务含义、单位、日期或缺失字段。
+
+`validateSpec()` 分开返回 `errors`、`warnings` 和 `normalizations`；诊断包含稳定代码、JSON 路径、期望值和修复建议。`chart.explain()` 返回编码、转换、交互、假设、警告、稳定记录血缘和无障碍摘要。
+
+## 关键规则
+
+- Spec 必须是 JSON-serializable。
+- 渲染前调用 `validateSpec()`。
+- 布局和数据语义不依赖 Renderer。
+- 通用图表使用 `data.values`；Flow/Swimlane 使用 `nodes/edges/lanes`。
+- `svg` 适合 DOM 交互和可访问性；`canvas` 适合大量图元和绘制性能。
+
+## 品牌署名（Branding）
+
+iChart.js 默认在所有图表右下角显示低对比度的品牌署名（`Powered by iChart.js`），用于提升项目可见性。
+
+### 配置项
+
+- 在 Spec 或 Theme 中通过 `branding` 字段控制：
+  - `branding: true`（默认）：开启署名。
+  - `branding: false`：关闭署名。
+  - `branding: { enabled: true }`：细粒度配置形式。
+
+### 一致性保证
+
+署名开关由 `buildScene()` 内统一总闸判定，以下四个面必然同步：
+1. 浏览器 Canvas/SVG 画面渲染。
+2. `chart.export({ type:'png|jpeg' })` 光栅导出。
+3. `chart.export({ type:'svg' })` 矢量导出。
+4. `chart.export({ type:'json' })` 中 `spec.branding` + `state` 持久化状态。
+
+关闭 `branding:false` 时，画面和所有导出产物都不会出现署名文字，同时不会再额外预留底部 padding。
+
+## 导出与下载
+
+iChart.js 导出采用**双底层单源架构**，所有产物共享 `buildScene()` 生成的同一份 Scene Graph，**画面显示用的 renderer 和导出底层完全解耦**：
+1. **PNG/JPEG（光栅）**：底层用 `CanvasRenderer` 重绘 Scene Graph，同步输出真光栅文件；无头环境安装 `canvas` npm 包即可支持。
+2. **SVG（矢量）**：底层用 `SVGRenderer` DOM 序列化（浏览器）或纯字符串拼装（无头零依赖），支持 XML 1.0 头部、字体拆分、无障碍属性。
+3. **JSON（可重建）**：序列化当前 `spec` + `getState()` 结果，用于持久化、Agent 自检和跨端重建。
+
+### Branding 一致性
+
+开关由 `buildScene()` 内统一总闸判定，画面渲染 / SVG 导出 / PNG 导出 / JSON state 必然同步。
+
+### Headless 支持矩阵
+
+| 类型       | 浏览器环境（任意 renderer） | Node 无头零依赖 | Node 无头 + `canvas` 依赖 |
+|------------|----------------------------|----------------|--------------------------|
+| JSON       | ✅                          | ✅              | ✅                        |
+| SVG        | ✅                          | ✅              | ✅                        |
+| PNG / JPEG | ✅ 同步真光栅               | ❌ 返回结构化 `HEADLESS_EXPORT_UNSUPPORTED` | ✅ |
+
+### 公共导出 API
+
+- `chart.toDataURL(type='image/png')` → data URL 字符串或结构化 ExportError。
+- `chart.toBlob(type='image/png')` → Blob 或 ExportError（无头返回 `BLOB_HEADLESS`）。
+- `chart.export({ type, as })` → 同步返回字符串 / JSON 对象 / Blob / ExportError，`as` 支持 `string`、`dataurl`、`blob`、`object`（仅 JSON）。
+- `chart.exportAsync({ type, as })` → Promise 包装，适配未来异步场景。
+- `chart.download({ type })` / `downloadPNG()` / `downloadSVG()` / `downloadJSON()` → 触发浏览器保存（无头回落到返回字符串或结构化错误）。
+
+### 错误结构
+
+所有导出/下载方法失败时统一返回 `{ valid:false, code, message?, suggestion?, rasterCode? }` 稳定结构，便于 Agent 自动化判断，常见 `code`：
+- `HEADLESS_EXPORT_UNSUPPORTED`：当前无头环境缺少光栅所需依赖（`canvas`）。
+- `BLOB_HEADLESS`：`toBlob` / `as=blob` 需要浏览器 Blob。
+- `DOWNLOAD_HEADLESS`：`chart.download*()` 仅在浏览器有 DOM 时可用，无头用 `export`。
+- `EXPORT_TYPE_UNSUPPORTED`：不支持的导出类型。
+
+公共 API：`inspectData`、`normalizeData`、`planChart`、`recommend`、`validateSpec`、`createChart`、`getCapabilities`、`getChartCapability`、`chart.describe`、`chart.explain`、`chart.getState`、`chart.export`、`chart.exportAsync`、`chart.toDataURL`、`chart.toBlob`、`chart.download`、`chart.downloadPNG`、`chart.downloadSVG`、`chart.downloadJSON`。
+
+实现位置：`src/index.mjs`、`src/spec.mjs`、`src/scene.mjs`、`src/renderer.mjs`、`src/plugin.mjs`、`src/scale.mjs`、`src/charts.mjs`、`src/capabilities.mjs`。