@taylorwong/ichartjs 2.0.15 → 2.0.16

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2.0.16 - 2026-09-25
+
+- Hardened Timeline and Milestone date layouts with proportional positioning, date-aware ticks, edge padding, collision-aware marker staggering, and `TIMELINE_COLLISION` diagnostics for physically constrained charts.
+- Fixed P0–P2 Agent contract issues across Funnel, Radar, Gauge, diagram labels and edges, Gantt dependencies, localized project output, title normalization, and chart-specific diagnostics.
+- Synchronized package, runtime, Playground, documentation, Skill, and capability manifest references for `v2.0.16`.
+
 ## 2.0.15 - 2026-09-24
 
 - Added the Iteration 13F axis-free layout strategy for Pie, Funnel, Gauge, and Radar, prioritizing chart body area and placing supported legends without Cartesian-axis reserves.

package/README.md

@@ -44,7 +44,7 @@ getCapabilities
 npm install @taylorwong/ichartjs@^2
 ```
 
-As a fallback for environments without npm access, install directly from GitHub: `npm install github:wanghetommy/ichartjs#v2.0.15`.
+As a fallback for environments without npm access, install directly from GitHub: `npm install github:wanghetommy/ichartjs#v2.0.16`.
 
 ### Optional Agent Skill
 
@@ -66,7 +66,7 @@ For a non-interactive global Codex installation:
 npx skills add wanghetommy/ichartjs --skill ichartjs --agent codex --global --yes
 ```
 
-For a release-pinned installation, use `npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.15/skills/ichartjs --agent codex --global --yes`. WorkBuddy users can import the same tagged `skills/ichartjs` URL through the host's Skill interface; do not assume a `--agent workbuddy` adapter unless the installed CLI declares it. Package consumers can still copy `node_modules/@taylorwong/ichartjs/skills/ichartjs` as a manual fallback. After installation, invoke `$ichartjs` when named Skill invocation is supported, or select `ichartjs` in the host UI.
+For a release-pinned installation, use `npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.16/skills/ichartjs --agent codex --global --yes`. WorkBuddy users can import the same tagged `skills/ichartjs` URL through the host's Skill interface; do not assume a `--agent workbuddy` adapter unless the installed CLI declares it. Package consumers can still copy `node_modules/@taylorwong/ichartjs/skills/ichartjs` as a manual fallback. After installation, invoke `$ichartjs` when named Skill invocation is supported, or select `ichartjs` in the host UI.
 
 ### Agent workflow
 

package/docs/agent/charting-scenario.md

@@ -2,6 +2,13 @@
 
 Agent usage and development guide for generic data analysis and metric visualization.
 
+## Capability Boundaries
+
+- `scatter` is a single x/y measure pair; it does not provide series or legend encoding.
+- `heatmap` uses matrix row/column labels from `encoding.x` and `encoding.y`; Cartesian `xAxis`/`yAxis` configuration is not supported.
+- `funnel` renders stage names from `encoding.category` (default `name`) and optional values from `labels.enabled`; it has no legend.
+- `area` and `column` accept at most two quantitative `encoding.y` measures.
+
 ## Supported Types
 
 | Type | Typical intent | Recommended renderer |

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

@@ -33,7 +33,7 @@ Install the official Skill with the standard Agent Skills CLI:
 npx skills add wanghetommy/ichartjs --skill ichartjs
 ```
 
-For global non-interactive Codex setup, append `--agent codex --global --yes`. To pin the released workflow, install `https://github.com/wanghetommy/ichartjs/tree/v2.0.15/skills/ichartjs`. WorkBuddy can import that tagged directory through its Skill interface; only use a host-specific `--agent` value when the installed CLI declares it.
+For global non-interactive Codex setup, append `--agent codex --global --yes`. To pin the released workflow, install `https://github.com/wanghetommy/ichartjs/tree/v2.0.16/skills/ichartjs`. WorkBuddy can import that tagged directory through its Skill interface; only use a host-specific `--agent` value when the installed CLI declares it.
 
 Verify discovery with `npx skills add wanghetommy/ichartjs --list`; the result should include `ichartjs`.
 

package/docs/agent/development/2.0-release-readiness.md

@@ -40,7 +40,7 @@ iChart.js 2.0 is a new Agent-first product line. Compatibility with 1.x and a 1.
 
 ## Iteration 13 Addendum — 2026-09-23
 
-The historical 2.0.0 release decision remains unchanged. Release `v2.0.15` includes Iteration 13 contract hardening without adding a chart type: 18 chart profiles, 25 commands, 11 schemas, contract version `1.1`, atomic mutation validation, Mindmap edge discovery, strict TypeScript consumer compilation, no active source cycles, 97 Node tests, Chromium browser acceptance, package dry-run verification, and the 13F axis-free layout strategy. It also corrects Bar y-axis title layout and exposes `TITLE_TRUNCATED` when physical chart height forces truncation.
+The historical 2.0.0 release decision remains unchanged. Release `v2.0.16` includes Iteration 13 contract hardening without adding a chart type: 18 chart profiles, 25 commands, 11 schemas, contract version `1.1`, atomic mutation validation, Mindmap edge discovery, strict TypeScript consumer compilation, no active source cycles, Node tests, Chromium browser acceptance, package dry-run verification, the 13F axis-free layout strategy, and Timeline/Milestone layout hardening. It also corrects Bar y-axis title layout and exposes `TITLE_TRUNCATED` when physical chart height forces truncation.
 
 ## Deferred npm Publication
 

package/docs/agent/development/roadmap.md

@@ -1,6 +1,6 @@
 # iChart.js 2.0 Roadmap
 
-> Roadmap baseline: 2026-09-14. Current release status: `v2.0.15` includes the completed Iteration 12 structured-diagram work, Iteration 13 contract hardening, the Bar y-axis title layout fix, and the 13F axis-free chart layout strategy. Geographic charts and 3D rendering remain out of scope until explicitly reintroduced.
+> Roadmap baseline: 2026-09-14. Current release status: `v2.0.16` includes the completed Iteration 12 structured-diagram work, Iteration 13 contract hardening, the Bar y-axis title layout fix, the 13F axis-free chart layout strategy, and Timeline/Milestone layout hardening. Geographic charts and 3D rendering remain out of scope until explicitly reintroduced.
 
 ## Current Status
 
@@ -15,7 +15,7 @@
 - Iteration 10A Export Contract Hardening was implemented and released in `v2.0.5`: export representations and type errors are deterministic, optional Node raster export uses `exportAsync()`, Canvas/SVG paint semantics are aligned, and the playground server has safer port/path handling. No chart behavior or public chart type was added.
 - Iteration 11 visual preference controls are included in the `v2.0.6` release: compact per-chart settings, capability-aware visibility controls, theme-aware icon contrast, explicit font-size defaults, shared page preferences, and Agent-adjustable global settings.
 - Iteration 12A–12G is included in `v2.0.7`: shared structured-diagram contracts, Architecture layers/boundaries, Mindmap parent-child tree/radial layouts with true cubic-Bezier edges, Agent schemas/capabilities, renderer-parity edge hit testing and selection, waypoint/segment handles, persistent manual routing, and Gallery/documentation coverage. Navigation and editing remain disabled by default and require explicit host activation.
-- Iteration 13A–13F is complete and included in `v2.0.15`: canonical contract registry and generated capability projection, atomic Spec/data/style mutations, row-complete project validation, explicit Mindmap edge metadata, complete public TypeScript declarations and consumer fixture, module-cycle and documentation/example gates, browser acceptance, package dry-run evidence, and an axis-free layout strategy for Pie, Funnel, Gauge, and Radar. No chart type was added.
+- Iteration 13A–13F is complete and included in `v2.0.16`: canonical contract registry and generated capability projection, atomic Spec/data/style mutations, row-complete project validation, explicit Mindmap edge metadata, complete public TypeScript declarations and consumer fixture, module-cycle and documentation/example gates, browser acceptance, package dry-run evidence, an axis-free layout strategy for Pie, Funnel, Gauge, and Radar, and Timeline/Milestone layout hardening. No chart type was added.
 - The original `2.0.0` readiness record is historical and superseded by the published `2.0.x` releases. Current release checks are defined by `docs/agent/development/release-sop.md`.
 
 ## Iteration 4 — Agent Data Contract and Business Editing

package/docs/agent/diagram-scenario.md

@@ -27,6 +27,8 @@ Architecture layers are horizontal bands ordered from top to bottom. Automatic l
 }
 ```
 
+`from` and `to` are the only edge endpoint fields. `source` and `target` are not aliases and return a structured validation error. Display text uses `label` for nodes, lanes, layers, groups, and boundaries; using `name` is diagnosed rather than silently treated as display text.
+
 For a mindmap, prefer the compact parent contract:
 
 ```js

package/docs/agent/frontend-integration.md

@@ -10,7 +10,7 @@ This is the production component path. For one-off files or Agent-led repository
 npm install @taylorwong/ichartjs@^2
 ```
 
-For environments without npm registry access, install from GitHub as a fallback: `npm install github:wanghetommy/ichartjs#v2.0.15`.
+For environments without npm registry access, install from GitHub as a fallback: `npm install github:wanghetommy/ichartjs#v2.0.16`.
 
 Use the package through a bundler or another environment that resolves npm ESM imports:
 

package/docs/agent/project-scenario.md

@@ -24,7 +24,7 @@ Agent usage and development guide for project planning, delivery tracking, and p
 - Keep derived values separate from source rows. State and tooltips may expose variance, float, warnings, and assumptions, but transforms must not mutate source data.
 - Linked filters and linked selection must use stable record IDs, not array positions.
 - Forecasts, risk scores, and aging buckets are inspectable heuristics. They are not commitments, causal claims, or hidden inference.
-- Project chart date axes are derived from `date`, `start`, and `end` records in the current contract; generic `xAxis.title/format` and `xAxis.min/max` settings do not customize them.
+- Project chart date axes are derived from `date`, `start`, and `end` records in the current contract; timeline and milestone use date-proportional horizontal positions while rows remain evenly spaced vertically. Generic `xAxis.title/format` and `xAxis.min/max` settings do not customize them.
 
 ## Agent Workflow
 
@@ -40,14 +40,18 @@ Agent usage and development guide for project planning, delivery tracking, and p
 - Gantt `start` and `end` must be valid dates, and `end` cannot precede `start`.
 - `progress` uses the `0–100` percentage convention.
 - `dependencies` use stable task IDs, either as strings or `{ id, type, lag, lead }` objects, and must form an acyclic graph.
+- `dependsOn` is not an alias; it is diagnosed and ignored. Use the canonical `dependencies` field.
 - Dependency objects support `finish-to-start`, `start-to-start`, `finish-to-finish`, and `start-to-finish`. Rendering uses the matching task endpoints; a clear forward finish-to-start relationship uses a compact three-segment route, while overlapping or reverse relationships use a safe outer route.
 - Issue aging requires an explicit ISO `today` reference; missing or invalid dates produce warnings instead of guessed buckets.
 - Calendar-aware scheduling may also use dependency objects with explicit `type`, `lag`, and `lead`.
 - `baselineStart`/`baselineEnd` and `actualStart`/`actualEnd` should be treated as explicit source inputs, not inferred values.
+- Milestone overlays use `baselineDate` and `actualDate`; timeline and milestone display text is canonically `title` (legacy `name` and `label` remain accepted with the normal project label fallback).
 - Burndown `scopeChange` represents scope movement, not completed work.
 - A forecast is an estimate derived from current samples, not a commitment or fact.
 - Capacity warnings, risk quadrants, and aging buckets should stay explainable from source fields.
 - Gantt, Timeline, and Milestone reserve their left label column from Unicode-aware text widths. Labels wider than the bounded column are truncated by rendered width rather than character count.
+- Timeline and Milestone place events on a date-proportional horizontal domain with a small visual edge padding. Nearby markers are automatically staggered when possible; if the available height is insufficient, the result includes `TIMELINE_COLLISION` and suggests increasing height or reducing events.
+- `locale` also applies to project date ticks, burndown forecast text, and project tooltips. Use `locale: 'zh-CN'` or another BCP 47 locale when those runtime labels must be localized.
 
 ## Editing
 

package/docs/agent/runtime-contract.md

@@ -16,7 +16,7 @@ Iteration 8 adds per-chart profiles through `getChartCapability(type)`. Each pro
 
 `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. `intent` must be one exact token from `getCapabilities().intents`; natural-language prose must be mapped before planning. An unknown token returns `UNKNOWN_INTENT` and a fallback plan, so Agents must inspect warnings before accepting `primary`. Planning never invents business meaning, units, dates, or missing fields.
 
-Unknown intent results also include `intentKnown`, `intentSuggestions`, and `fallbackUsed`. A chart Spec is chart-specific: Cartesian channels are `x`/`y`, Pie/Funnel channels are `category`/`value`, Gauge uses `value`, Heatmap channels are `x`/`y`/`color`, and Radar fields live in `indicators`. `validateSpec()` rejects unsupported channels and missing fields. Gauge requires an explicit `domain` and reports `VALUE_CLAMPED` when the rendered value exceeds it. Pie reports `NEGATIVE_VALUE_DROPPED` for negative input values and `ZERO_TOTAL` when no positive share can render.
+Unknown intent results also include `intentKnown`, `intentSuggestions`, and `fallbackUsed`. A chart Spec is chart-specific: Cartesian channels are `x`/`y`, Pie/Funnel channels are `category`/`value`, Gauge uses `value`, Heatmap channels are `x`/`y`/`color`, and Radar fields live in `indicators`. `validateSpec()` rejects unsupported channels and missing fields. Gauge requires an explicit `domain` and reports `VALUE_CLAMPED` when the rendered value exceeds it. Pie reports `NEGATIVE_VALUE_DROPPED` for negative input values; `ZERO_TOTAL` is a validation error because no positive share can render.
 
 ## Spec Rules
 

package/docs/agent/usage-scenarios.md

@@ -121,7 +121,7 @@ npx skills add wanghetommy/ichartjs --skill ichartjs --agent codex --global --ye
 For reproducible installation, pin the released Skill directory:
 
 ```bash
-npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.15/skills/ichartjs \
+npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.16/skills/ichartjs \
   --agent codex --global --yes
 ```
 

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

@@ -2,6 +2,13 @@
 
 用于通用指标分析和数据展示的 Agent 使用与开发指南。
 
+## 能力边界
+
+- `scatter` 只支持一组 x/y 数值字段，不提供 Series 或 Legend 编码。
+- `heatmap` 使用 `encoding.x` 和 `encoding.y` 的矩阵行列标签，不支持笛卡尔 `xAxis`/`yAxis` 配置。
+- `funnel` 从 `encoding.category`（默认 `name`）渲染阶段名称，`labels.enabled` 决定是否追加数值；不提供 Legend。
+- `area` 和 `column` 的 `encoding.y` 最多接受两个数值度量。
+
 ## 图表选择
 
 | 类型 | 适用场景 | 推荐 Renderer |

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

@@ -22,7 +22,7 @@ npm Registry 中无作用域的 `ichartjs` 是安全占位包，并非本项目
 npx skills add wanghetommy/ichartjs --skill ichartjs
 ```
 
-Codex 全局无交互安装可追加 `--agent codex --global --yes`。需要固定发布版本时，安装 `https://github.com/wanghetommy/ichartjs/tree/v2.0.15/skills/ichartjs`。WorkBuddy 可通过自身 Skill 界面导入该带 Tag 的目录；只有当前 CLI 明确声明对应适配器时才使用宿主专用 `--agent` 参数。
+Codex 全局无交互安装可追加 `--agent codex --global --yes`。需要固定发布版本时，安装 `https://github.com/wanghetommy/ichartjs/tree/v2.0.16/skills/ichartjs`。WorkBuddy 可通过自身 Skill 界面导入该带 Tag 的目录；只有当前 CLI 明确声明对应适配器时才使用宿主专用 `--agent` 参数。
 
 使用 `npx skills add wanghetommy/ichartjs --list` 验证发现结果，其中应包含 `ichartjs`。
 

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

@@ -13,6 +13,8 @@
 
 Architecture 的 `layers` 是从上到下排列的水平分层。同层自动布局节点优先保持同一 Y 坐标并从左到右排列；只有可用宽度不足时才增加下一行。显式 `node.position` 始终优先，包括编辑后的坐标；自动布局不会回写 Spec。
 
+边端点只使用 `from` 和 `to`；`source` 与 `target` 不是别名，会返回结构化校验错误。节点、泳道、层、分组和边界的显示文本使用 `label`；误用 `name` 时运行时会给出诊断，不会静默当成显示文本。
+
 ```js
 {
   type: 'architecture',

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

@@ -6,7 +6,7 @@ iChart.js 应作为普通 JavaScript UI 组件运行在浏览器应用中。数
 npm install @taylorwong/ichartjs@^2
 ```
 
-无法访问 npm Registry 的环境请用 GitHub 源作为后备：`npm install github:wanghetommy/ichartjs#v2.0.15`。
+无法访问 npm Registry 的环境请用 GitHub 源作为后备：`npm install github:wanghetommy/ichartjs#v2.0.16`。
 
 ```js
 import { createChart } from '@taylorwong/ichartjs';

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

@@ -16,10 +16,13 @@
 - 日期必须有效，Gantt 的 `end` 不得早于 `start`。
 - `progress` 使用 `0–100` 百分比。
 - `dependencies` 使用稳定任务 ID，支持字符串或 `{ id, type, lag, lead }` 对象，依赖图不能有环。
+- `dependsOn` 不是别名，会被诊断并忽略；请使用正式字段 `dependencies`。
 - 依赖类型支持 `finish-to-start`、`start-to-start`、`finish-to-finish` 和 `start-to-finish`；连线使用对应任务端点。具有净空的正向 FS 关系使用三段紧凑路径，重叠或反向关系使用外侧绕行。
 - `scopeChange` 表示范围变化，不等于已完成工作量。
 - Forecast 是估计结果，不能描述为承诺或事实。
 - Gantt、Timeline 和 Milestone 根据 Unicode-aware 文本宽度预留左侧标签列；超过列宽的标签按像素省略，不按字符数截断。
+- Timeline 和 Milestone 的横向位置按 `date` 比例计算，纵向行槽位保持均匀，并在时间域边缘保留少量视觉留白；Milestone 覆盖层使用 `baselineDate` 和 `actualDate`，显示文本正式字段为 `title`（`name` 和 `label` 仍由兼容回退逻辑接受）。相邻标记会在可能时自动错位；如果空间不足，结果会返回 `TIMELINE_COLLISION`，建议增大高度或减少事件数量。
+- `locale` 同时作用于项目日期刻度、Burndown 预测文案和项目 Tooltip；需要中文运行时文案时使用 `locale: 'zh-CN'`。
 
 ## 编辑流程
 

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

@@ -16,7 +16,7 @@ Iteration 8 通过 `getChartCapability(type)` 提供逐图表能力档案，包
 
 `planChart(data, { intent, renderer })` 返回版本化规划结果：主选图表、备选项、置信度、原因、缺失字段、建议编码、假设、警告、不支持请求和安全下一步。规划不会虚构业务含义、单位、日期或缺失字段。
 
-未知 intent 还会返回 `intentKnown`、`intentSuggestions` 和 `fallbackUsed`。Spec 的通道按图表类型约束：笛卡尔图表是 `x`/`y`，Pie/Funnel 是 `category`/`value`，Gauge 只使用 `value`，Heatmap 是 `x`/`y`/`color`，Radar 字段位于 `indicators`。`validateSpec()` 会拒绝不支持的通道和缺失字段。Gauge 必须显式声明 `domain`，超出范围时会报告 `VALUE_CLAMPED`；Pie 的负值和空占比分别报告 `NEGATIVE_VALUE_DROPPED`、`ZERO_TOTAL`。
+未知 intent 还会返回 `intentKnown`、`intentSuggestions` 和 `fallbackUsed`。Spec 的通道按图表类型约束：笛卡尔图表是 `x`/`y`，Pie/Funnel 是 `category`/`value`，Gauge 只使用 `value`，Heatmap 是 `x`/`y`/`color`，Radar 字段位于 `indicators`。`validateSpec()` 会拒绝不支持的通道和缺失字段。Gauge 必须显式声明 `domain`，超出范围时会报告 `VALUE_CLAMPED`；Pie 的负值报告 `NEGATIVE_VALUE_DROPPED`，没有正数占比时 `ZERO_TOTAL` 会使校验失败。
 
 `validateSpec()` 分开返回 `errors`、`warnings` 和 `normalizations`；诊断包含稳定代码、JSON 路径、期望值和修复建议。`chart.explain()` 返回编码、转换、交互、假设、警告、稳定记录血缘和无障碍摘要。
 

package/docs/agent/zh-CN/usage-scenarios.md

@@ -116,7 +116,7 @@ npx skills add wanghetommy/ichartjs --skill ichartjs --agent codex --global --ye
 需要固定发布版本时，直接安装已发布的 Skill 目录：
 
 ```bash
-npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.15/skills/ichartjs \
+npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.16/skills/ichartjs \
   --agent codex --global --yes
 ```
 

package/docs/manifests/capabilities.json

@@ -282,8 +282,8 @@
       "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."
     ]
   },
-  "packageVersion": "2.0.15",
-  "runtimeVersion": "2.0.15",
+  "packageVersion": "2.0.16",
+  "runtimeVersion": "2.0.16",
   "chartTypes": [
     "line",
     "area",
@@ -771,11 +771,12 @@
         "invalid-data-state": "supported",
         "export": "supported",
         "branding": "supported",
-        "axes": "supported",
+        "matrix-labels": "supported",
         "labels": "supported",
         "formatting": "supported",
         "color-scale": "supported",
         "missing-values": "supported",
+        "axes": "not-applicable",
         "zoom": "not-applicable",
         "pan": "not-applicable"
       },
@@ -924,7 +925,7 @@
       ],
       "required": [
         "date",
-        "label"
+        "title"
       ],
       "optional": [
         "status"
@@ -972,11 +973,11 @@
       ],
       "required": [
         "date",
-        "label"
+        "title"
       ],
       "optional": [
-        "baseline",
-        "actual"
+        "baselineDate",
+        "actualDate"
       ],
       "interactions": [
         "hover",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taylorwong/ichartjs",
-  "version": "2.0.15",
+  "version": "2.0.16",
   "description": "Agent-first, renderer-independent charting and project visualization runtime",
   "type": "module",
   "main": "./src/index.mjs",

package/skills/ichartjs/SKILL.md

@@ -21,7 +21,7 @@ Recommended installation:
 npx skills add wanghetommy/ichartjs --skill ichartjs
 ```
 
-Use `--agent codex --global --yes` for global non-interactive Codex installation. Use the tagged directory `https://github.com/wanghetommy/ichartjs/tree/v2.0.15/skills/ichartjs` when reproducibility matters. WorkBuddy can import the same directory through its Skill interface; do not assume a `--agent workbuddy` adapter unless the installed CLI declares it.
+Use `--agent codex --global --yes` for global non-interactive Codex installation. Use the tagged directory `https://github.com/wanghetommy/ichartjs/tree/v2.0.16/skills/ichartjs` when reproducibility matters. WorkBuddy can import the same directory through its Skill interface; do not assume a `--agent workbuddy` adapter unless the installed CLI declares it.
 
 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:
 
@@ -40,9 +40,9 @@ Do not install the unscoped npm registry package named `ichartjs`; it is current
 5. Inspect the complete planning result, including `styleRecommendation`, warnings, and fallback status.
 6. Stop when `requiredFields` is non-empty; request data or explain a supported alternative.
 7. Build a JSON-serializable Spec using `suggestedEncodings`, the selected capability, and an applicable recipe.
-8. Use chart-specific channels: Cartesian `x`/`y`, Pie/Funnel `category`/`value`, Gauge `value`, Heatmap `x`/`y`/`color`, and Radar `indicators[].field`. To load a recipe, use `import catalog from '@taylorwong/ichartjs/recipes/minimal-specs' with { type: 'json' }` and select `catalog.examples[type]`.
+8. Use chart-specific channels: Cartesian `x`/`y`, Pie/Funnel `category`/`value`, Gauge `value`, Heatmap `x`/`y`/`color`, and Radar `indicators[].field`. Funnel stage text comes from `encoding.category` (default `name`) and is always rendered; `labels.enabled` additionally renders values. To load a recipe, use `import catalog from '@taylorwong/ichartjs/recipes/minimal-specs' with { type: 'json' }` and select `catalog.examples[type]`; `recipes/` is the public export path backed by the package's `agent-recipes/` directory.
 9. Keep titles/formats under `xAxis`/`yAxis`, labels under `labels`, and legend under `legend`; do not place them inside `encoding`.
-10. Call `validateSpec()` before rendering. Repair `UNSUPPORTED_ENCODING_CHANNEL`, `MISSING_ENCODING_FIELD`, `MISSING_GAUGE_DOMAIN`, `UNKNOWN_INTENT`, misplaced-option, and unsupported-axis warnings before presenting the chart.
+10. Call `validateSpec()` before rendering. Repair `UNSUPPORTED_ENCODING_CHANNEL`, `MISSING_ENCODING_FIELD`, `MISSING_GAUGE_DOMAIN`, `ZERO_TOTAL`, `UNKNOWN_INTENT`, misplaced-option, and unsupported-axis warnings before presenting the chart.
 11. Call `createChart()` only after validation succeeds. Gauge Specs must declare a meaningful `domain`.
 12. Self-check with `chart.explain()`, `chart.getState()`, `health.renderable`, and JSON export. Treat `VALUE_CLAMPED`, `LABELS_SUPPRESSED`, `NEGATIVE_VALUE_DROPPED`, and `ZERO_TOTAL` as material diagnostics to report.
 13. Provide an exact preview URL or artifact path and report assumptions, warnings, and deferred checks.
@@ -75,6 +75,8 @@ Route by requested output:
 - Treat `getCapabilities().intents` as an allowlist; never pass a natural-language sentence as `planChart().intent`.
 - If planning returns `fallbackUsed: true`, use `intentSuggestions` to remap or ask for confirmation; never silently accept the fallback chart.
 - Keep axis titles/formats under `xAxis`/`yAxis`, labels under `labels`, and legend settings under `legend`.
+- Use `title: { text, subtitle }`; string titles and `title.label` are compatibility forms and are reported as normalizations.
+- Use diagram `label`, edge `from`/`to`, and Gantt `dependencies`; do not substitute `name`, `source`/`target`, or `dependsOn`.
 - Repair `UNKNOWN_INTENT`, misplaced-option, and unsupported-axis warnings before presenting a chart. For numeric y-axes, prefer the default readable domain; use `yAxis.domain: [min, max]` for an explicit range, `yAxis.nice: false` for raw boundaries, and `yAxis.ticks` for a stable label count.
 - Add stable string `id` values to tabular rows when lineage or linked updates are part of the deliverable.
 - Avoid Pie for high-cardinality categories; prefer Bar for comparison.

package/src/charts.mjs

@@ -429,8 +429,8 @@ export function buildScene(spec) {
     if (!(total > 0)) { data.warnings.push({ code: 'ZERO_TOTAL', path: 'encoding.value', message: 'Pie requires a positive total.', suggestion: 'Provide at least one positive value or render an explicit empty state.' }); addText(scene, 'pie-zero-total', spec.emptyText || 'No positive values', cx, cy, { fill: spec.theme.muted, font: font(spec, 'subtitle'), textAnchor: 'middle' }); }
     else data.rows.forEach((row, index) => { const rawValue = values[index], value = Number.isFinite(rawValue) ? Math.max(0, rawValue) : 0, end = angle + value / total * Math.PI * 2, middle = angle + (end - angle) / 2, fill = colors[index % colors.length], dataRef = { seriesIndex: 0, dataIndex: index, category: row[categoryField], value, rawValue }; scene.add(new SceneNode({ id: `series-0-item-${index}`, type: 'arc', geometry: { cx, cy, r: radius, innerR, start: angle, end }, bounds: { x: cx - radius, y: cy - radius, width: radius * 2, height: radius * 2 }, style: { fill, stroke: spec.theme.background, strokeWidth: 1 }, dataRef, interactive: true })); addMarkLabel(scene, spec, `series-0-item-${index}`, value / total, cx + Math.cos(middle) * radius * .72, cy + Math.sin(middle) * radius * .72, dataRef, state.plot, null, spec.labels?.format || { style: 'percent' }, fill); angle = end; });
   } else if (spec.type === 'funnel') {
-    const valueField = spec.encoding.value?.field || 'value'; const maxValue = Math.max(...data.rows.map(row => Number(row[valueField]) || 0), 1); const segmentHeight = state.plot.height / data.rows.length;
-    data.rows.forEach((row, index) => { const value = Number(row[valueField]) || 0, ratio = Math.max(0.1, value / maxValue), fill = colors[index % colors.length]; const width = state.plot.width * ratio; const geometry = { x: state.plot.x + (state.plot.width - width) / 2, y: state.plot.y + index * segmentHeight, width, height: Math.max(2, segmentHeight - 3) }, dataRef = { seriesIndex: 0, dataIndex: index, field: valueField }; scene.add(new SceneNode({ id: `series-0-item-${index}`, type: 'rect', geometry, bounds: geometry, style: { fill }, dataRef, interactive: true })); addMarkLabel(scene, spec, `series-0-item-${index}`, value, geometry.x + geometry.width / 2, geometry.y + geometry.height / 2 + 4, dataRef, state.plot, null, null, fill); });
+    const categoryField = spec.encoding.category?.field || 'name', valueField = spec.encoding.value?.field || 'value'; const maxValue = Math.max(...data.rows.map(row => Number(row[valueField]) || 0), 1); const segmentHeight = state.plot.height / data.rows.length;
+    data.rows.forEach((row, index) => { const value = Number(row[valueField]) || 0, category = String(row[categoryField] ?? row.name ?? row.id ?? `Stage ${index + 1}`), ratio = Math.max(0.1, value / maxValue), fill = colors[index % colors.length]; const width = state.plot.width * ratio; const geometry = { x: state.plot.x + (state.plot.width - width) / 2, y: state.plot.y + index * segmentHeight, width, height: Math.max(2, segmentHeight - 3) }, dataRef = { seriesIndex: 0, dataIndex: index, field: valueField, category, value }; scene.add(new SceneNode({ id: `series-0-item-${index}`, type: 'rect', geometry, bounds: geometry, style: { fill }, dataRef, interactive: true })); const labelSize = fontSize(spec, 'label', 12), textColor = readableLabelColor(spec, fill), label = truncateText(category, Math.max(labelSize * 2, width - 12), labelSize); addText(scene, `funnel-category-${index}`, label, geometry.x + geometry.width / 2, geometry.y + geometry.height / 2 - (spec.labels?.enabled ? labelSize * 0.6 : 0), { fill: textColor, font: spec.labels?.font || font(spec, 'label'), textAnchor: 'middle', textBaseline: 'middle', baseline: 'middle' }, dataRef); if (spec.labels?.enabled) addText(scene, `funnel-value-${index}`, formatValue(value, spec.labels.format, spec.locale), geometry.x + geometry.width / 2, geometry.y + geometry.height / 2 + labelSize * 0.65, { fill: textColor, font: spec.labels?.font || font(spec, 'label'), textAnchor: 'middle', textBaseline: 'middle', baseline: 'middle' }, dataRef); });
   } else if (spec.type === 'gauge') {
     const valueField = spec.encoding.value?.field || 'value', domain = Array.isArray(spec.domain) ? spec.domain : [0, 100], rawValue = Number(data.rows[0]?.[valueField]), numericValue = Number.isFinite(rawValue) ? rawValue : 0, value = Math.max(Number(domain[0]), Math.min(Number(domain[1]), numericValue)), ratio = (value - Number(domain[0])) / (Number(domain[1]) - Number(domain[0]) || 1), cx = state.plot.x + state.plot.width / 2, cy = state.plot.y + state.plot.height * 0.68, radius = Math.min(state.plot.width * 0.42, state.plot.height * 0.62), start = Math.PI, end = start + Math.PI * ratio;
     if (!Array.isArray(spec.domain)) data.warnings.push({ code: 'MISSING_GAUGE_DOMAIN', path: 'domain', message: 'Gauge rendered with a compatibility fallback; provide an explicit domain to make the value meaningful.' });

package/src/contract-registry.mjs

@@ -24,11 +24,11 @@ export const chartDefinitions = {
   scatter: { family: 'cartesian', intents: ['relationship', 'correlation'], required: ['measure', 'measure'], optional: ['dimension'], interactions: ['hover', 'tooltip', 'selection', 'brush', 'zoom', 'pan', 'keyboard'], features: status([...commonPresentation, 'axes', 'grid', 'labels', 'formatting'], ['stacked']) },
   funnel: { family: 'stage', intents: ['funnel', 'conversion'], required: ['dimension', 'measure'], optional: [], interactions: ['hover', 'tooltip', 'selection', 'keyboard'], features: status([...commonPresentation, 'labels', 'formatting'], ['axes', 'grid', 'zoom', 'pan']) },
   gauge: { family: 'indicator', intents: ['progress', 'single-value'], required: ['measure'], optional: [], interactions: ['hover', 'tooltip', 'selection', 'keyboard'], features: status([...commonPresentation, 'labels', 'formatting', 'domain'], ['axes', 'grid', 'legend', 'zoom', 'pan']) },
-  heatmap: { family: 'matrix', intents: ['matrix', 'correlation-grid'], required: ['dimension', 'dimension', 'measure'], optional: [], interactions: ['hover', 'tooltip', 'selection', 'keyboard'], features: status([...commonPresentation, 'axes', 'labels', 'formatting', 'color-scale', 'missing-values'], ['zoom', 'pan']) },
+  heatmap: { family: 'matrix', intents: ['matrix', 'correlation-grid'], required: ['dimension', 'dimension', 'measure'], optional: [], interactions: ['hover', 'tooltip', 'selection', 'keyboard'], features: status([...commonPresentation, 'matrix-labels', 'labels', 'formatting', 'color-scale', 'missing-values'], ['axes', 'zoom', 'pan']) },
   radar: { family: 'radial', intents: ['multidimensional', 'profile'], required: ['three-or-more-measures'], optional: ['series'], interactions: ['hover', 'tooltip', 'selection', 'keyboard'], features: status([...commonPresentation, 'legend', 'labels', 'formatting', 'multi-series', 'indicator-domains', 'mixed-unit-warning'], ['axes', 'grid', 'zoom', 'pan']) },
   gantt: { family: 'project', intents: ['schedule', 'variance'], required: ['id', 'start', 'end'], optional: ['dependencies', 'progress', 'baseline', 'actual'], interactions: ['hover', 'tooltip', 'selection', 'zoom', 'pan', 'keyboard', 'linked-filter', 'linked-selection'], features: status([...commonPresentation, 'labels', 'formatting', 'critical-path', 'slack', 'baseline-actual-variance', 'working-calendar', 'dependencies']) },
-  timeline: { family: 'project', intents: ['timeline', 'milestone'], required: ['date', 'label'], optional: ['status'], interactions: ['hover', 'tooltip', 'selection', 'zoom', 'pan', 'keyboard'], features: status([...commonPresentation, 'labels', 'formatting']) },
-  milestone: { family: 'project', intents: ['milestone'], required: ['date', 'label'], optional: ['baseline', 'actual'], interactions: ['hover', 'tooltip', 'selection', 'zoom', 'pan', 'keyboard'], features: status([...commonPresentation, 'labels', 'formatting', 'baseline-actual-variance']) },
+  timeline: { family: 'project', intents: ['timeline', 'milestone'], required: ['date', 'title'], optional: ['status'], interactions: ['hover', 'tooltip', 'selection', 'zoom', 'pan', 'keyboard'], features: status([...commonPresentation, 'labels', 'formatting']) },
+  milestone: { family: 'project', intents: ['milestone'], required: ['date', 'title'], optional: ['baselineDate', 'actualDate'], interactions: ['hover', 'tooltip', 'selection', 'zoom', 'pan', 'keyboard'], features: status([...commonPresentation, 'labels', 'formatting', 'baseline-actual-variance']) },
   burndown: { family: 'project', intents: ['progress', 'release'], required: ['date', 'remaining'], optional: ['ideal', 'scopeChange'], interactions: ['hover', 'tooltip', 'selection', 'zoom', 'pan', 'keyboard'], features: status([...commonPresentation, 'axes', 'labels', 'formatting', 'scope-change', 'release-forecast']) },
   flow: { family: 'diagram', intents: ['workflow'], required: ['nodes'], optional: ['edges', 'groups', 'ports'], interactions: ['hover', 'tooltip', 'selection', 'edge-selection', 'drag', 'edgeDrag', 'zoom', 'pan', 'keyboard', 'keyboard-edit', 'keyboard-port-connect', 'portConnect', 'copy-paste'], features: status([...commonPresentation, 'labels', 'routing', 'manual-routing', 'layout', 'groups', 'ports', 'history'], ['axes', 'grid', 'legend']) },
   swimlane: { family: 'diagram', intents: ['responsibility'], required: ['nodes', 'lanes'], optional: ['edges', 'groups', 'ports'], interactions: ['hover', 'tooltip', 'selection', 'edge-selection', 'drag', 'edgeDrag', 'zoom', 'pan', 'keyboard', 'keyboard-edit', 'keyboard-port-connect', 'portConnect', 'copy-paste'], features: status([...commonPresentation, 'labels', 'routing', 'manual-routing', 'layout', 'groups', 'ports', 'lanes', 'history'], ['axes', 'grid', 'legend']) },

package/src/diagram.mjs

@@ -28,14 +28,17 @@ export function normalizeDiagramSpec(spec = {}) {
 }
 
 export function validateDiagram(spec = {}) {
-  const errors = [], normalized = normalizeDiagramSpec(spec), nodes = normalized.nodes, edges = normalized.edges, lanes = normalized.lanes, layers = normalized.layers;
+  const errors = [], warnings = [], normalized = normalizeDiagramSpec(spec), nodes = normalized.nodes, edges = normalized.edges, lanes = normalized.lanes, layers = normalized.layers;
   const nodeIds = new Set(), laneIds = new Set(lanes.map(lane => lane.id));
   const groupIds = new Set();
   const layerIds = new Set(layers.map(layer => layer.id));
   if (!diagramModes.includes(normalized.diagram.mode)) errors.push({ code: 'DIAGRAM_MODE', path: 'diagram.mode', message: `Unsupported diagram mode: ${normalized.diagram.mode}.`, suggestion: `Use ${diagramModes.join(', ')}.` });
   layers.forEach((layer, index) => {
     if (typeof layer?.id !== 'string' || !layer.id) errors.push({ code: 'LAYER_ID', path: `layers.${index}.id`, message: 'Architecture layers require stable IDs.' });
+    if (layer?.name !== undefined && layer?.label === undefined) warnings.push({ code: 'UNSUPPORTED_DIAGRAM_LABEL_FIELD', path: `layers.${index}.name`, message: 'Architecture layer display text uses label, not name.', suggestion: 'Rename layers[].name to layers[].label.' });
   });
+  normalized.groups.forEach((group, index) => { if (group?.name !== undefined && group?.label === undefined) warnings.push({ code: 'UNSUPPORTED_DIAGRAM_LABEL_FIELD', path: `groups.${index}.name`, message: 'Group display text uses label, not name.', suggestion: 'Rename groups[].name to groups[].label.' }); });
+  normalized.boundaries.forEach((boundary, index) => { if (boundary?.name !== undefined && boundary?.label === undefined) warnings.push({ code: 'UNSUPPORTED_DIAGRAM_LABEL_FIELD', path: `boundaries.${index}.name`, message: 'Boundary display text uses label, not name.', suggestion: 'Rename boundaries[].name to boundaries[].label.' }); });
   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.' });
@@ -46,6 +49,7 @@ export function validateDiagram(spec = {}) {
     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?.name !== undefined && node?.label === undefined) warnings.push({ code: 'UNSUPPORTED_DIAGRAM_LABEL_FIELD', path: `nodes.${index}.name`, message: 'Node display text uses label, not name.', suggestion: 'Rename nodes[].name to nodes[].label.' });
     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.' });
@@ -68,8 +72,12 @@ export function validateDiagram(spec = {}) {
   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.' });
+    const usesUnsupportedEndpointNames = (edge.from === undefined || edge.to === undefined) && (edge.source !== undefined || edge.target !== undefined);
+    if (usesUnsupportedEndpointNames) errors.push({ code: 'UNSUPPORTED_EDGE_ENDPOINT_FIELDS', path: `edges.${index}`, message: 'Diagram edges use from and to, not source and target.', suggestion: 'Rename edge.source to edge.from and edge.target to edge.to.' });
+    else {
+      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]}.` });
@@ -85,7 +93,7 @@ export function validateDiagram(spec = {}) {
     const parents = new Map(nodes.map(node => [node.id, node.parentId]).filter(([, parentId]) => parentId));
     nodes.forEach(node => { const seen = new Set([node.id]); let current = node.parentId; while (current) { if (seen.has(current)) { errors.push({ code: 'MINDMAP_CYCLE', path: `nodes.${node.id}.parentId`, message: 'Mindmap parent relationships must be acyclic.' }); break; } seen.add(current); current = parents.get(current); } });
   }
-  return { valid: errors.length === 0, errors, spec: normalized };
+  return { valid: errors.length === 0, errors, warnings, spec: normalized };
 }
 
 export function diagramGraph(spec) {

package/src/index.mjs

@@ -334,7 +334,7 @@ export class Chart {
   _touchDistance(event) { if (!event.touches || event.touches.length < 2) return null; const [first, second] = event.touches; return Math.hypot(second.clientX - first.clientX, second.clientY - first.clientY); }
   _eventPoint(event, target) { const rect = target.getBoundingClientRect(); return { x: (event.clientX - rect.left) * this.spec.width / (rect.width || this.spec.width), y: (event.clientY - rect.top) * this.spec.height / (rect.height || this.spec.height) }; }
   _updateCrosshair(x, y) { const vertical = this.model.scene.find('crosshair-x'), horizontal = this.model.scene.find('crosshair-y'); if (!vertical || !horizontal) return; vertical.geometry.x1 = vertical.geometry.x2 = x; vertical.style.opacity = 0.7; horizontal.geometry.y1 = horizontal.geometry.y2 = y; horizontal.style.opacity = 0.7; this.renderer.render(this.model.scene); }
-  _showTooltip(payload) { if (typeof document === 'undefined' || !this.container || !payload.datum) return; let tip = this._tooltip; if (!tip) { tip = this._tooltip = document.createElement('div'); tip.className = 'ichart-v2-tooltip'; Object.assign(tip.style, { position: 'fixed', pointerEvents: 'none', zIndex: 9999, padding: '8px 10px', borderRadius: '6px', maxWidth: 'min(320px, calc(100vw - 24px))', whiteSpace: 'pre-line' }); document.body.appendChild(tip); } Object.assign(tip.style, { background: this.spec.theme.surface, color: this.spec.theme.text, border: `1px solid ${this.spec.theme.border}`, font: this.spec.theme.typography.tooltip.font, boxShadow: `0 4px 12px ${this.spec.theme.border}88` }); const text = ['gantt', 'timeline', 'milestone', 'burndown', 'flow', 'swimlane', 'architecture', 'mindmap'].includes(this.spec.type) ? projectTooltip(this.spec.type, payload.datum) : Object.entries(payload.datum).map(([key, value]) => `${key}: ${value}`).join(' · '); tip.textContent = text; const left = Math.min((payload.nativeEvent.clientX || 0) + 12, window.innerWidth - tip.offsetWidth - 12); const top = Math.min((payload.nativeEvent.clientY || 0) + 12, window.innerHeight - tip.offsetHeight - 12); tip.style.left = `${Math.max(12, left)}px`; tip.style.top = `${Math.max(12, top)}px`; }
+  _showTooltip(payload) { if (typeof document === 'undefined' || !this.container || !payload.datum) return; let tip = this._tooltip; if (!tip) { tip = this._tooltip = document.createElement('div'); tip.className = 'ichart-v2-tooltip'; Object.assign(tip.style, { position: 'fixed', pointerEvents: 'none', zIndex: 9999, padding: '8px 10px', borderRadius: '6px', maxWidth: 'min(320px, calc(100vw - 24px))', whiteSpace: 'pre-line' }); document.body.appendChild(tip); } Object.assign(tip.style, { background: this.spec.theme.surface, color: this.spec.theme.text, border: `1px solid ${this.spec.theme.border}`, font: this.spec.theme.typography.tooltip.font, boxShadow: `0 4px 12px ${this.spec.theme.border}88` }); const text = ['gantt', 'timeline', 'milestone', 'burndown', 'flow', 'swimlane', 'architecture', 'mindmap'].includes(this.spec.type) ? projectTooltip(this.spec.type, payload.datum, this.spec.locale) : Object.entries(payload.datum).map(([key, value]) => `${key}: ${value}`).join(' · '); tip.textContent = text; const left = Math.min((payload.nativeEvent.clientX || 0) + 12, window.innerWidth - tip.offsetWidth - 12); const top = Math.min((payload.nativeEvent.clientY || 0) + 12, window.innerHeight - tip.offsetHeight - 12); tip.style.left = `${Math.max(12, left)}px`; tip.style.top = `${Math.max(12, top)}px`; }
   _hideTooltip() { if (this._tooltip) this._tooltip.style.left = '-10000px'; }
   _validateMutation(operation, input) {
     const result = validateSpec(input);
@@ -771,4 +771,4 @@ export { normalizeLinkedFilters, normalizeLinkedSelection, filterProjectRows, cr
 
 export { contrastRatio, planStyle, resolveTheme, styleCapabilities, themeModes, themePalettes, themePresets, validateThemeContrast, annotationPlugin, dataZoomPlugin, dataLabelsPlugin, accessibilityPlugin };
 export { applyPreferencesToSpec, createPreferencesStore, defaultPreferences, mergePreferences, mergeThemePreference, mountChartSettings, normalizePreferences, validatePreferences };
-export const iChart = { version: '2.0.15', createChart, ChartValidationError, inspectData, normalizeData, binData, applyTransforms, data, getCapabilities, getChartCapability, getPreferenceCapabilities, planChart, recommend, explainChart, contrastRatio, planStyle, resolveTheme, styleCapabilities, themeModes, themePalettes, themePresets, validateThemeContrast, createPreferencesStore, defaultPreferences, normalizePreferences, mergePreferences, validatePreferences, applyPreferencesToSpec, mountChartSettings, annotationPlugin, dataZoomPlugin, dataLabelsPlugin, accessibilityPlugin, getBusinessSchema, inspectDataSchema, validateData, getEditCapabilities, validateEdit, previewEdit, commitPreview, validateRecipe, normalizeProjectCalendar, applyWorkingCalendar, normalizeDependencies, analyzeSchedule, analyzeBurndownSeries, analyzeCapacity, buildCapacityView, buildCumulativeFlowSeries, buildVelocitySeries, buildReleaseForecast, buildRiskMatrixSeries, buildIssueAgingSeries, normalizeLinkedFilters, normalizeLinkedSelection, filterProjectRows, createLinkedProjectState, linkedRecordId };
+export const iChart = { version: '2.0.16', createChart, ChartValidationError, inspectData, normalizeData, binData, applyTransforms, data, getCapabilities, getChartCapability, getPreferenceCapabilities, planChart, recommend, explainChart, contrastRatio, planStyle, resolveTheme, styleCapabilities, themeModes, themePalettes, themePresets, validateThemeContrast, createPreferencesStore, defaultPreferences, normalizePreferences, mergePreferences, validatePreferences, applyPreferencesToSpec, mountChartSettings, annotationPlugin, dataZoomPlugin, dataLabelsPlugin, accessibilityPlugin, getBusinessSchema, inspectDataSchema, validateData, getEditCapabilities, validateEdit, previewEdit, commitPreview, validateRecipe, normalizeProjectCalendar, applyWorkingCalendar, normalizeDependencies, analyzeSchedule, analyzeBurndownSeries, analyzeCapacity, buildCapacityView, buildCumulativeFlowSeries, buildVelocitySeries, buildReleaseForecast, buildRiskMatrixSeries, buildIssueAgingSeries, normalizeLinkedFilters, normalizeLinkedSelection, filterProjectRows, createLinkedProjectState, linkedRecordId };

package/src/project.mjs

@@ -13,7 +13,45 @@ import { axisLabelLayout, estimateTextWidth, fontSize, titleLayout, truncateText
 export const projectTypes = ['gantt', 'timeline', 'milestone', 'burndown', 'flow', 'swimlane', 'architecture', 'mindmap'];
 const day = 86400000;
 export const timestamp = value => value == null || value === '' ? NaN : new Date(value).getTime();
-const dateLabel = value => new Date(value).toISOString().slice(0, 10);
+const projectMessages = locale => String(locale || 'en-US').toLowerCase().startsWith('zh') ? {
+  estimatedFinish: '预计完成',
+  forecastUnavailable: '无法预测',
+  date: '日期', remaining: '剩余', scopeChange: '范围变更', totalScope: '范围总量', completed: '已完成',
+  forecast: '预测', parent: '父主题', rootTopic: '根主题', branch: '分支', layer: '层', boundary: '边界', role: '角色',
+  progress: '进度', status: '状态', owner: '负责人', dependsOn: '依赖', critical: '关键路径', float: '浮动时间', variance: '偏差', lane: '泳道', days: '天', yes: '是', no: '否', unavailable: '不可用'
+} : {
+  estimatedFinish: 'Estimated finish',
+  forecastUnavailable: 'Forecast unavailable',
+  date: 'Date', remaining: 'Remaining', scopeChange: 'Scope change', totalScope: 'Total scope', completed: 'Completed',
+  forecast: 'Forecast', parent: 'Parent', rootTopic: 'Root topic', branch: 'Branch', layer: 'Layer', boundary: 'Boundary', role: 'Role',
+  progress: 'Progress', status: 'Status', owner: 'Owner', dependsOn: 'Depends on', critical: 'Critical', float: 'Float', variance: 'Variance', lane: 'Lane', days: 'days', yes: 'yes', no: 'no', unavailable: 'unavailable'
+};
+const dateLabel = (value, locale = 'en-US') => {
+  try {
+    return new Intl.DateTimeFormat(locale, { timeZone: 'UTC', year: 'numeric', month: '2-digit', day: '2-digit' }).format(new Date(value));
+  } catch {
+    return new Date(value).toISOString().slice(0, 10);
+  }
+};
+const projectTickCount = width => Math.max(2, Math.min(6, Math.floor(width / 100)));
+function projectTickValues(min, max, count = 5) {
+  return Array.from({ length: count }, (_, index) => min + (max - min) * index / Math.max(1, count - 1));
+}
+function projectTickLabels(min, max, width, locale = 'en-US') {
+  return projectTickValues(min, max, projectTickCount(width)).map(value => dateLabel(value, locale));
+}
+
+function projectDateDomain(spec, rows) {
+  const values = spec.type === 'gantt' ? rows.flatMap(rowWindow) : rows.map(row => timestamp(row?.date ?? row?.start ?? row?.end)).filter(Number.isFinite);
+  let min = Math.min(...(values.length ? values : [Date.now()])), max = Math.max(...(values.length ? values : [Date.now() + day]));
+  if (min === max) { min -= day; max += day; }
+  if (['timeline', 'milestone'].includes(spec.type)) {
+    const padding = Math.max(day, (max - min) * 0.03);
+    min -= padding;
+    max += padding;
+  }
+  return [min, max];
+}
 const dependencyId = dependency => typeof dependency === 'string' ? dependency : dependency?.id || null;
 const dependencyType = dependency => typeof dependency === 'object' && dependency?.type ? dependency.type : 'finish-to-start';
 const markText = (theme, background) => (contrastRatio(theme.text, background) || 0) >= (contrastRatio(theme.background, background) || 0) ? theme.text : theme.background;
@@ -58,15 +96,16 @@ function arrow(scene, id, points, reference, critical = false, curve = null) {
   scene.add({ id: id.startsWith('dependency-') ? id.replace('dependency-', 'dependency-arrow-') : `${id}-arrow`, type: 'path', geometry: { points: [tip, { x: tip.x - size * Math.cos(angle - Math.PI / 6), y: tip.y - size * Math.sin(angle - Math.PI / 6) }, { x: tip.x - size * Math.cos(angle + Math.PI / 6), y: tip.y - size * Math.sin(angle + Math.PI / 6) }, tip] }, style: { fill: color, stroke: color }, zIndex: 3 });
 }
 
-function timeAxis(scene, plot, min, max) {
+function timeAxis(scene, plot, min, max, locale = 'en-US') {
   const map = value => plot.x + (timestamp(value) - min) / (max - min || day) * plot.width;
-  const ticks = Math.max(2, Math.min(5, Math.floor(plot.width / 100)));
-  const labelLayout = scene.xLabelLayout || axisLabelLayout({ theme: scene.theme }, Array(ticks).fill('2000-00-00'), plot.width);
-  for (let index = 0; index < ticks; index += 1) {
-    const time = min + (max - min) * index / (ticks - 1), x = map(time);
+  const ticks = projectTickCount(plot.width), values = projectTickValues(min, max, ticks), labels = values.map(value => dateLabel(value, locale));
+  const labelLayout = scene.xLabelLayout || axisLabelLayout({ theme: scene.theme }, labels, plot.width);
+  scene.xLabelLayout = labelLayout;
+  values.forEach((time, index) => {
+    const x = map(time);
     scene.add({ id: `project-grid-${index}`, type: 'line', geometry: { x1: x, y1: plot.y, x2: x, y2: plot.y + plot.height }, style: { stroke: scene.theme?.grid || '#e2e8f0' } });
-    text(scene, `project-tick-${index}`, dateLabel(time), x, plot.y + plot.height + (labelLayout.rotation ? 10 : 22), { fill: scene.theme?.muted, textAnchor: labelLayout.rotation ? 'end' : index === 0 ? 'start' : index === ticks - 1 ? 'end' : 'middle', textBaseline: labelLayout.rotation ? 'middle' : 'alphabetic', rotation: labelLayout.rotation, font: scene.theme?.typography?.axis?.font || '11px system-ui' });
-  }
+    text(scene, `project-tick-${index}`, dateLabel(time, locale), x, plot.y + plot.height + (labelLayout.rotation ? 10 : 22), { fill: scene.theme?.muted, textAnchor: labelLayout.rotation ? 'end' : index === 0 ? 'start' : index === ticks - 1 ? 'end' : 'middle', textBaseline: labelLayout.rotation ? 'middle' : 'alphabetic', rotation: labelLayout.rotation, font: scene.theme?.typography?.axis?.font || '11px system-ui' });
+  });
   return map;
 }
 
@@ -161,14 +200,13 @@ export function analyzeBurndown(rows, options = {}) {
 function tasksScene(scene, spec, rows, state) {
   const plot = state.plot;
   const overlays = projectOverlays(spec);
-  const values = rows.flatMap(rowWindow);
-  let min = Math.min(...(values.length ? values : [Date.now()])), max = Math.max(...(values.length ? values : [Date.now() + day]));
-  if (min === max) { min -= day; max += day; }
-  const map = timeAxis(scene, plot, min, max), positions = new Map();
+  const [min, max] = projectDateDomain(spec, rows);
+  const map = timeAxis(scene, plot, min, max, spec.locale), positions = new Map();
   const analyticsMap = new Map((state.schedule?.tasks || []).map(task => [task.id, task]));
   const highlighted = new Set(spec.criticalPath === false || !overlays.criticalPath ? [] : Array.isArray(spec.criticalPath) ? spec.criticalPath : state.schedule?.criticalIds || []);
   const selected = projectSelection(spec, state);
-  const rowHeight = plot.height / Math.max(1, rows.length), barHeight = Math.min(20, Math.max(10, rowHeight * 0.62)), barOffset = barHeight / 2;
+  const rowHeight = plot.height / Math.max(1, rows.length), barHeight = Math.min(20, Math.max(10, rowHeight * 0.62)), barOffset = barHeight / 2, isEventTimeline = ['timeline', 'milestone'].includes(spec.type), eventRadius = Math.min(7, Math.max(3, rowHeight * 0.28)), placedEvents = [];
+  let collisionsResolved = 0, collisionsUnresolved = 0;
   rows.forEach((row, index) => {
     const analytics = analyticsMap.get(row.id);
     const recordId = linkedRecordId(row, index);
@@ -179,7 +217,14 @@ function tasksScene(scene, spec, rows, state) {
     const actualStart = row.actualStart || row.actualDate || null;
     const actualEnd = row.actualEnd || row.actualDate || actualStart;
     const start = map(startValue), end = map(endValue);
-    const y = plot.y + (index + 0.5) * rowHeight;
+    const baseY = plot.y + (index + 0.5) * rowHeight;
+    const markerX = map(startValue);
+    const eventOffsets = [0, eventRadius * 1.5, -eventRadius * 1.5, eventRadius * 3, -eventRadius * 3];
+    const eventY = isEventTimeline ? eventOffsets.map(offset => Math.max(plot.y + eventRadius, Math.min(plot.y + plot.height - eventRadius, baseY + offset))).find(candidate => !placedEvents.some(event => Math.abs(event.x - markerX) < eventRadius * 2 + 4 && Math.abs(event.y - candidate) < eventRadius * 2 + 4)) : null;
+    if (isEventTimeline && eventY == null) collisionsUnresolved += 1;
+    const y = isEventTimeline ? eventY ?? baseY : baseY;
+    if (isEventTimeline && y !== baseY) collisionsResolved += 1;
+    if (isEventTimeline) placedEvents.push({ x: markerX, y });
     const milestone = spec.type === 'milestone' || row.milestone || start === end;
     if (overlays.baseline && baselineStart) {
       const baselineStartX = map(baselineStart), baselineEndX = map(baselineEnd || baselineStart);
@@ -191,7 +236,7 @@ function tasksScene(scene, spec, rows, state) {
       if (milestone) scene.add({ id: `project-actual-${index}`, type: 'circle', geometry: { cx: actualStartX, cy: y, r: 3 }, bounds: { x: actualStartX - 3, y: y - 3, width: 6, height: 6 }, style: { fill: spec.theme.text }, zIndex: 3 });
       else scene.add({ id: `project-actual-${index}`, type: 'rect', geometry: { x: actualStartX, y: y + barOffset + 2, width: Math.max(2, actualEndX - actualStartX), height: 3 }, style: { fill: spec.theme.text, opacity: 0.35 }, zIndex: 3 });
     }
-    const geometry = milestone ? { cx: start, cy: y, r: Math.min(7, barOffset) } : { x: start, y: y - barOffset, width: Math.max(2, end - start), height: barHeight };
+    const geometry = milestone ? { cx: start, cy: y, r: eventRadius } : { x: start, y: y - barOffset, width: Math.max(2, end - start), height: barHeight };
     const bounds = milestone ? { x: start - 8, y: y - 8, width: 16, height: 16 } : { ...geometry };
     const datum = taskDatum(row, analytics, recordId);
     scene.add({
@@ -210,7 +255,8 @@ function tasksScene(scene, spec, rows, state) {
     });
     positions.set(row.id || recordId, { start, end, y });
     const label = row.name || row.title || row.label || row.id || `Item ${index + 1}`;
-    text(scene, `project-label-${index}`, truncateText(label, Math.max(12, plot.x - 20), fontSize(spec, 'axis', 12)), plot.x - 12, y + 4, { textAnchor: 'end' });
+    const labelSize = Math.max(9, Math.min(fontSize(spec, 'axis', 12), rowHeight * 0.45));
+    text(scene, `project-label-${index}`, truncateText(label, Math.max(labelSize, plot.x - 20), labelSize), plot.x - 12, y + 4, { textAnchor: 'end', font: `${labelSize}px system-ui` });
     if (row.progress != null && !milestone) scene.add({ id: `project-progress-${index}`, type: 'rect', geometry: { ...geometry, width: geometry.width * (row.progress > 1 ? row.progress / 100 : row.progress) }, style: { fill: spec.theme.text, opacity: 0.25 }, zIndex: 3 });
     if (overlays.slack && analytics?.latestFinish && !milestone) {
       const latestEnd = map(analytics.latestFinish);
@@ -221,6 +267,7 @@ function tasksScene(scene, spec, rows, state) {
       if (variance != null) text(scene, `project-variance-${index}`, `${variance > 0 ? '+' : ''}${variance}d`, milestone ? start + 12 : end + 8, y - 12, { font: spec.theme.typography.axis.font, fill: variance > 0 ? spec.theme.status.danger : variance < 0 ? spec.theme.status.info : spec.theme.muted });
     }
   });
+  if (isEventTimeline) state.eventLayout = { collisionsResolved, collisionsUnresolved, rows: rows.length };
   rows.forEach((row, index) => (row.dependencies || []).forEach((dependency, dependencyIndex) => {
     const fromId = dependencyId(dependency), toId = row.id;
     const from = positions.get(fromId), to = positions.get(toId);
@@ -239,7 +286,7 @@ function burndownScene(scene, spec, rows, state) {
   state.projectAnalytics = { ...(state.projectAnalytics || {}), burndown: analysis };
   const min = Math.min(analysis.start, samples[0]?.time || analysis.start || Date.now());
   const max = Math.max(analysis.end, samples.at(-1)?.time || analysis.end || min + day, forecast.time || 0, min + day);
-  const map = timeAxis(scene, plot, min, max);
+  const map = timeAxis(scene, plot, min, max, spec.locale);
   const maxValue = Math.max(1, ...samples.flatMap(sample => [sample.remaining, sample.ideal, sample.scope]));
   const mapY = value => plot.y + plot.height - value / maxValue * plot.height;
   const selected = projectSelection(spec, state);
@@ -256,7 +303,8 @@ function burndownScene(scene, spec, rows, state) {
     const last = samples.at(-1);
     scene.add({ id: 'burndown-forecast', type: 'path', geometry: { points: [{ x: map(last.time), y: mapY(last.remaining) }, { x: map(forecast.time), y: mapY(0) }] }, style: { fill: 'none', stroke: spec.theme.status.danger, strokeWidth: 2 } });
   }
-  text(scene, 'burndown-projected', forecast.date ? `Estimated finish: ${forecast.date}` : `Forecast unavailable: ${forecast.reason}`, plot.x, plot.y - 16, { font: spec.theme.typography.axis.font });
+  const messages = projectMessages(spec.locale);
+  text(scene, 'burndown-projected', forecast.date ? `${messages.estimatedFinish}: ${forecast.date}` : `${messages.forecastUnavailable}: ${forecast.reason}`, plot.x, plot.y - 16, { font: spec.theme.typography.axis.font });
 }
 
 function diagramScene(scene, spec, rows, state) {
@@ -373,7 +421,7 @@ export function buildProjectScene(spec) {
   const left = spec.type === 'architecture' ? architectureLabelReserve(spec) : ['gantt', 'timeline', 'milestone', 'swimlane'].includes(spec.type) ? projectLabelReserve(spec, sourceRows) : spec.padding.left;
   const title = titleLayout(spec);
   const plotTop = Math.max(spec.padding.top, title.bottom + (title.bottom ? 12 : 0)) + (spec.type === 'burndown' ? 16 : 0);
-  const plotWidth = Math.max(1, spec.width - left - spec.padding.right), xLabels = axisLabelLayout(spec, Array(Math.max(2, Math.min(5, Math.floor(plotWidth / 100)))).fill('2000-00-00'), plotWidth);
+  const plotWidth = Math.max(1, spec.width - left - spec.padding.right), dateDomain = projectDateDomain(spec, sourceRows), xLabels = axisLabelLayout(spec, projectTickLabels(dateDomain[0], dateDomain[1], plotWidth, spec.locale), plotWidth);
   const bottomReserve = Math.max(spec.padding.bottom + 16, Math.ceil(16 + xLabels.projectedHeight));
   const state = { plot: { x: left, y: plotTop, width: plotWidth, height: Math.max(1, spec.height - plotTop - bottomReserve) }, xLabels, compact: spec.width < 360 || spec.height < 240, recommendedSize: { minWidth: 280, minHeight: 220 }, linked, projectAnalytics: { linked } };
   scene.xLabelLayout = xLabels;
@@ -387,6 +435,11 @@ export function buildProjectScene(spec) {
   else if (diagram) diagramScene(scene, spec, data.rows, state);
   else if (spec.type === 'burndown') burndownScene(scene, spec, data.rows, state);
   else tasksScene(scene, spec, data.rows, state);
+  if (state.eventLayout?.collisionsUnresolved) data.warnings.push({
+    code: 'TIMELINE_COLLISION',
+    message: 'Timeline or milestone markers could not be fully separated in the available space.',
+    suggestion: 'Increase the chart height or reduce the number of events.'
+  });
   const view = projectView(spec), mapX = value => value * view.scale + view.offsetX, mapY = value => value * view.scale + view.offsetY;
   scene.walk(node => {
     const geometry = node.geometry;
@@ -402,30 +455,31 @@ export function buildProjectScene(spec) {
   return { scene, data, state };
 }
 
-export function projectTooltip(type, row) {
+export function projectTooltip(type, row, locale = 'en-US') {
   if (!row) return '';
+  const messages = projectMessages(locale);
   if (type === 'burndown') return [
-    `Date: ${row.date}`,
-    `Remaining: ${row.remaining ?? row.actual ?? row.value}`,
-    `Scope change: ${row.scopeChange || 0}`,
-    row.scope != null ? `Total scope: ${row.scope}` : null,
-    row.completed != null ? `Completed: ${row.completed}` : null,
-    row.forecast ? `Estimated finish: ${row.forecast}` : `Forecast: ${row.forecastReason || 'unavailable'}`
+    `${messages.date}: ${row.date}`,
+    `${messages.remaining}: ${row.remaining ?? row.actual ?? row.value}`,
+    `${messages.scopeChange}: ${row.scopeChange || 0}`,
+    row.scope != null ? `${messages.totalScope}: ${row.scope}` : null,
+    row.completed != null ? `${messages.completed}: ${row.completed}` : null,
+    row.forecast ? `${messages.estimatedFinish}: ${row.forecast}` : `${messages.forecast}: ${row.forecastReason || messages.unavailable}`
   ].filter(Boolean).join('\n');
   const dependencies = (row.dependencies || []).map(dependencyId).filter(Boolean);
   const variance = row.endVarianceDays ?? row.baselineVarianceDays ?? null;
-  if (type === 'mindmap') return [row.label || row.id, row.parentId ? `Parent: ${row.parentId}` : 'Root topic', row.branch ? `Branch: ${row.branch}` : null, row.description].filter(value => value != null && value !== '').join('\n');
-  if (type === 'architecture') return [row.label || row.id, row.layerId ? `Layer: ${row.layerId}` : null, row.boundaryId ? `Boundary: ${row.boundaryId}` : null, row.role ? `Role: ${row.role}` : null, row.description].filter(value => value != null && value !== '').join('\n');
+  if (type === 'mindmap') return [row.label || row.id, row.parentId ? `${messages.parent}: ${row.parentId}` : messages.rootTopic, row.branch ? `${messages.branch}: ${row.branch}` : null, row.description].filter(value => value != null && value !== '').join('\n');
+  if (type === 'architecture') return [row.label || row.id, row.layerId ? `${messages.layer}: ${row.layerId}` : null, row.boundaryId ? `${messages.boundary}: ${row.boundaryId}` : null, row.role ? `${messages.role}: ${row.role}` : null, row.description].filter(value => value != null && value !== '').join('\n');
   return [
     row.name || row.title || row.label || row.id,
     row.start ? `${row.start} → ${row.end || row.start}` : row.date,
-    row.progress != null ? `Progress: ${row.progress <= 1 ? Math.round(row.progress * 100) : row.progress}%` : null,
-    row.status ? `Status: ${row.status}` : null,
-    row.owner || row.resource ? `Owner: ${row.owner || row.resource}` : null,
-    dependencies.length ? `Depends on: ${dependencies.join(', ')}` : null,
-    row.critical != null ? `Critical: ${row.critical ? 'yes' : 'no'} · Float: ${row.float ?? row.slack ?? 0} days` : null,
-    variance != null ? `Variance: ${variance > 0 ? '+' : ''}${variance} days` : null,
-    row.laneId ? `Lane: ${row.laneId}` : null,
+    row.progress != null ? `${messages.progress}: ${row.progress <= 1 ? Math.round(row.progress * 100) : row.progress}%` : null,
+    row.status ? `${messages.status}: ${row.status}` : null,
+    row.owner || row.resource ? `${messages.owner}: ${row.owner || row.resource}` : null,
+    dependencies.length ? `${messages.dependsOn}: ${dependencies.join(', ')}` : null,
+    row.critical != null ? `${messages.critical}: ${row.critical ? messages.yes : messages.no} · ${messages.float}: ${row.float ?? row.slack ?? 0} ${messages.days}` : null,
+    variance != null ? `${messages.variance}: ${variance > 0 ? '+' : ''}${variance} ${messages.days}` : null,
+    row.laneId ? `${messages.lane}: ${row.laneId}` : null,
     row.description
   ].filter(value => value != null && value !== '').join('\n');
 }

package/src/spec.mjs

@@ -43,17 +43,31 @@ function merge(base, extra) {
   return result;
 }
 
+function normalizeTitle(title) {
+  if (typeof title === 'string') return { text: title };
+  if (title && typeof title === 'object' && !Array.isArray(title) && !title.text && typeof title.label === 'string') {
+    const normalized = clone(title);
+    normalized.text = normalized.label;
+    delete normalized.label;
+    return normalized;
+  }
+  return title;
+}
+
 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 errors = [], ids = new Set(rows.map(row => row.id).filter(Boolean)), graph = new Map(rows.map(row => [row.id, (Array.isArray(row.dependencies) ? row.dependencies : []).map(dependencyId).filter(Boolean)]));
+  rows.forEach((row, index) => {
+    if (row?.dependencies !== undefined && !Array.isArray(row.dependencies)) errors.push({ code: 'INVALID_DEPENDENCY_LIST', path: `data.values[${index}].dependencies`, message: 'Dependencies must be an array of task IDs or dependency objects.', suggestion: 'Use dependencies: ["task-id"] or [{ id, type, lag, lead }].' });
+    (Array.isArray(row?.dependencies) ? 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.' }); });
@@ -134,6 +148,7 @@ function validateEncodingContract(input, spec, errors) {
 
 export function normalizeSpec(input = {}) {
   const spec = merge(defaults, input);
+  spec.title = normalizeTitle(spec.title);
   if (input.branding === undefined && input.theme && typeof input.theme === 'object' && input.theme.branding !== undefined) spec.branding = clone(input.theme.branding);
   if (spec.branding === false) spec.branding = { enabled: false };
   else if (spec.branding === true) spec.branding = { enabled: true };
@@ -164,6 +179,15 @@ export function normalizeSpec(input = {}) {
 export function validateSpec(input = {}) {
   const spec = normalizeSpec(input);
   const errors = [], warnings = [], normalizations = [];
+  if (typeof input.title === 'string') {
+    normalizations.push({ path: 'title', from: 'string', to: 'title.text' });
+    warnings.push({ code: 'NORMALIZED_TITLE', path: 'title', message: 'String titles are normalized to title.text.', suggestion: 'Prefer title: { text: "..." } for an explicit title contract.' });
+  } else if (input.title && typeof input.title === 'object' && !Array.isArray(input.title) && input.title.text === undefined && typeof input.title.label === 'string') {
+    normalizations.push({ path: 'title.label', from: 'title.label', to: 'title.text' });
+    warnings.push({ code: 'NORMALIZED_TITLE', path: 'title.label', message: 'title.label is normalized to title.text.', suggestion: 'Use title: { text: "..." }.' });
+  } else if (input.title !== undefined && (!input.title || typeof input.title !== 'object' || Array.isArray(input.title) || (input.title.text === undefined && input.title.subtitle === undefined))) {
+    warnings.push({ code: 'INVALID_TITLE', path: 'title', message: 'Title must be a string or an object with text and/or subtitle.', suggestion: 'Use title: { text: "...", subtitle: "..." }.' });
+  }
   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.' });
@@ -221,6 +245,7 @@ export function validateSpec(input = {}) {
     const diagramInput = { type: spec.type, ...(Array.isArray(spec.nodes) ? { nodes: spec.nodes } : {}), ...(Array.isArray(spec.edges) ? { edges: spec.edges } : {}), ...(Array.isArray(spec.lanes) ? { lanes: spec.lanes } : {}), ...(Array.isArray(spec.groups) ? { groups: spec.groups } : {}), ...(Array.isArray(spec.layers) ? { layers: spec.layers } : {}), ...(Array.isArray(spec.boundaries) ? { boundaries: spec.boundaries } : {}), ...(spec.diagram ? { diagram: spec.diagram } : {}) };
     const diagramValidation = validateDiagram(diagramInput);
     diagramValidation.errors.forEach(error => errors.push({ ...error, path: error.path || 'diagram' }));
+    diagramValidation.warnings?.forEach(warning => warnings.push({ ...warning, path: warning.path || 'diagram' }));
   }
   if (['gantt', 'timeline', 'milestone', 'burndown'].includes(spec.type)) {
     const rows = spec.data.values, dateKey = spec.type === 'gantt' ? 'start/end' : 'date';
@@ -236,12 +261,16 @@ export function validateSpec(input = {}) {
     }
   }
   if (spec.type === 'gantt') errors.push(...dependencyErrors(spec.data.values));
+  if (spec.type === 'gantt') spec.data.values.forEach((row, index) => {
+    if (row && row.dependsOn !== undefined && row.dependencies === undefined) warnings.push({ code: 'UNSUPPORTED_DEPENDENCY_FIELD', path: `data.values[${index}].dependsOn`, message: 'dependsOn is not a recognized Gantt dependency field and will be ignored.', suggestion: 'Rename dependsOn to dependencies.' });
+  });
+  if (spec.type === 'scatter' && (Array.isArray(spec.encoding?.x) || Array.isArray(spec.encoding?.y)) && (Array.isArray(spec.encoding?.x) && spec.encoding.x.length > 1 || Array.isArray(spec.encoding?.y) && spec.encoding.y.length > 1)) errors.push({ code: 'UNSUPPORTED_SCATTER_SERIES', path: 'encoding', message: 'Scatter supports one x/y measure pair; multi-series encoding is not supported.', suggestion: 'Use one x and one y field, or choose line, area, bar, or column for series.' });
   const rows = Array.isArray(spec.data?.values) ? spec.data.values : [];
   if (spec.type === 'pie' && rows.length > 8) warnings.push({ code: 'HIGH_CARDINALITY_PIE', path: 'data.values', message: `Pie contains ${rows.length} categories.`, expected: '8 or fewer categories', suggestion: 'Use bar/column or group smaller categories.' });
   if (spec.type === 'pie') {
     const valueField = spec.encoding.value?.field || 'value', values = rows.map(row => Number(row?.[valueField])), negativeCount = values.filter(value => Number.isFinite(value) && value < 0).length, positiveTotal = values.reduce((sum, value) => sum + (Number.isFinite(value) && value > 0 ? value : 0), 0);
     if (negativeCount) warnings.push({ code: 'NEGATIVE_VALUE_DROPPED', path: 'encoding.value', count: negativeCount, message: `Pie ignores ${negativeCount} negative value${negativeCount === 1 ? '' : 's'} when calculating shares.`, suggestion: 'Use non-negative part-to-whole values or choose a Cartesian chart for signed measures.' });
-    if (!(positiveTotal > 0)) warnings.push({ code: 'ZERO_TOTAL', path: 'encoding.value', message: 'Pie requires a positive total.', suggestion: 'Provide at least one positive value or render an explicit empty state.' });
+    if (!(positiveTotal > 0)) errors.push({ code: 'ZERO_TOTAL', path: 'encoding.value', message: 'Pie requires a positive total.', suggestion: 'Provide at least one positive value or render an explicit empty state.' });
   }
   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 profile = chartProfiles[spec.type], inputOptions = input && typeof input === 'object' ? input : {};

package/types/index.d.ts

@@ -32,8 +32,9 @@ export interface ChartHealth { version: '1.0'; status: 'ready' | 'degraded' | 'e
 export interface ChartExplanation { version: '1.0'; type: ChartType; family: string; purpose: string; renderer: Renderer; dataCount: number; encodings: Record<string, string | string[]>; transforms: string[]; interactions: string[]; assumptions: string[]; warnings: Diagnostic[]; axes?: { y?: AxisState; right?: AxisState } | null; health?: ChartHealth; style: Partial<StyleRecommendation> & { name?: string }; lineage: { recordIds: string[]; sourcePreserved: boolean }; accessibility: { enabled: boolean; summary: string }; }
 export interface ChartInteraction { tooltip?: boolean; hover?: boolean; click?: boolean; crosshair?: boolean; zoom?: boolean; pan?: boolean; brush?: boolean; drag?: boolean; edgeDrag?: boolean; portConnect?: boolean; keyboard?: boolean; [key: string]: boolean | undefined; }
 export interface ChartEditing { enabled?: boolean; mode?: 'command' | string; requireConfirmation?: boolean; allowDelete?: boolean; allowStructuralChanges?: boolean; }
+export interface ChartTitle { text?: string; subtitle?: string; label?: string; }
 export interface AxisSpec { type?: 'linear' | 'log' | 'quantitative' | 'temporal' | 'time' | string; title?: string; format?: string | Record<string, unknown>; domain?: [number, number]; nice?: boolean; ticks?: 'auto' | number; right?: AxisSpec; [key: string]: unknown; }
-export interface ChartSpec { type: ChartType; renderer?: Renderer; container?: string | Element; chartId?: string; width?: number; height?: number; locale?: string; data?: Array<Record<string, unknown>> | { values?: Array<Record<string, unknown>>; [key: string]: unknown }; encoding?: Record<string, unknown>; title?: { text?: string; subtitle?: string }; legend?: { visible?: boolean; position?: string }; grid?: { visible?: boolean; color?: string }; labels?: { enabled?: boolean; format?: string | Record<string, unknown>; color?: string; font?: string }; xAxis?: AxisSpec; yAxis?: AxisSpec; diagram?: DiagramConfig; interaction?: ChartInteraction; editing?: ChartEditing; accessibility?: { enabled?: boolean; description?: string }; branding?: boolean | { enabled?: boolean }; theme?: ThemeMode | ThemePreset | ThemeConfig | ResolvedTheme; preferences?: ChartPreferencesPatch | PreferencesStore; preferencesStore?: PreferencesStore; [key: string]: unknown; }
+export interface ChartSpec { type: ChartType; renderer?: Renderer; container?: string | Element; chartId?: string; width?: number; height?: number; locale?: string; data?: Array<Record<string, unknown>> | { values?: Array<Record<string, unknown>>; [key: string]: unknown }; encoding?: Record<string, unknown>; title?: string | ChartTitle; legend?: { visible?: boolean; position?: string }; grid?: { visible?: boolean; color?: string }; labels?: { enabled?: boolean; format?: string | Record<string, unknown>; color?: string; font?: string }; xAxis?: AxisSpec; yAxis?: AxisSpec; diagram?: DiagramConfig; interaction?: ChartInteraction; editing?: ChartEditing; accessibility?: { enabled?: boolean; description?: string }; branding?: boolean | { enabled?: boolean }; theme?: ThemeMode | ThemePreset | ThemeConfig | ResolvedTheme; preferences?: ChartPreferencesPatch | PreferencesStore; preferencesStore?: PreferencesStore; [key: string]: unknown; }
 export interface BinTransform { type: 'bin'; field: string; output?: string; thresholds?: number; step?: number; extent?: [number, number]; }
 export interface RadarIndicator { name: string; field: string; min?: number; max?: number; }
 export interface DiagramNode { id: string; label: string; position?: { x: number; y: number }; size?: { width: number; height: number }; ports?: Array<{ id: string; side?: 'left' | 'right' | 'top' | 'bottom'; offset?: number }>; groupId?: string; }