@taylorwong/ichartjs 2.0.17 → 2.0.19

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 2.0.19 - 2026-09-29
+
+- Added Iteration 15 adaptive text fitting for Flow, Architecture, Mindmap, and Swimlane nodes, with inline-first edge labels, diagram-only contrast plates, unified diagnostics, and shared SVG/Canvas behavior.
+- Improved diagram readability with vertically centered node labels, bounded compact labels, centered Swimlane nodes, safer edge-label placement, and enlarged-preview re-rendering.
+- Added sector-aware Pie/Donut labels and radius-aware Gauge metrics, including bounded font reduction, explicit `POLAR_LABEL_OVERFLOW` diagnostics, and machine-readable polar layout state.
+
+## 2.0.18 - 2026-09-28
+
+- Added lightweight Flow semantics for start/end, process, decision, input/output, and connector nodes, including explicit decision branches and loop edges with shared SVG/Canvas geometry.
+- Exposed Flow semantic capabilities and validation diagnostics through runtime metadata, TypeScript declarations, Agent Skill guidance, and generated manifests.
+- Updated the full Gallery Flow example to demonstrate all supported semantic node kinds, Yes/No branches, a retry loop, and connector usage.
+
 ## 2.0.17 - 2026-09-25
 
 - Added explicit `FUNNEL_LABEL_TRUNCATED` diagnostics when narrow stages cannot display their full labels.

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.17`.
+As a fallback for environments without npm access, install directly from GitHub: `npm install github:wanghetommy/ichartjs#v2.0.19`.
 
 ### 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.17/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.19/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

@@ -28,6 +28,8 @@ Agent usage and development guide for generic data analysis and metric visualiza
 
 - Use `stack: "stacked"` or `stack: "percent"` with Bar, Column, or Area rather than a separate stacked type.
 - Use `type: "pie"` with `innerRadius` for Donut charts.
+- Pie and Donut labels are positioned on each sector centerline and scale down before allowing overflow on very small sectors. Check `getState().layout.labels.polar` and the `POLAR_LABEL_OVERFLOW` warning when labels are required to be fully readable.
+- Gauge keeps its primary value inside the gauge body and adapts its metric font to the available radius; it does not create per-segment labels.
 - Use per-series `mark: "column"` or `mark: "line"` and optional `axis: "right"` for Combo charts.
 - Use `transform: { type: "bin", field, thresholds | step, extent }` for Histogram workflows.
 - Heatmap treats missing values separately from numeric zero through `colorScale.missing`.

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.17/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.19/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.17` 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, Timeline/Milestone layout hardening, and runtime diagnostics for constrained Funnel labels and Swimlane label aliases. 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.19` includes Iteration 13 contract hardening, Iteration 14 lightweight Flow semantics, and Iteration 15 text-readability 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, Timeline/Milestone layout hardening, renderer-parity Flow semantic shapes, adaptive diagram labels, diagram-only edge-label plates, and polar label layout diagnostics for Pie, Donut, and Gauge.
 
 ## Deferred npm Publication
 

package/docs/agent/development/iteration-14.md

@@ -0,0 +1,58 @@
+# Iteration 14 — Lightweight Flow Semantics
+
+Iteration 14 enhances the existing `flow` chart instead of adding a new chart type. The goal is a small, readable process notation that an Agent can generate from a compact JSON Spec without introducing BPMN-level complexity.
+
+## Scope
+
+### 14A — Semantic nodes
+
+Flow nodes support the following `kind` values:
+
+| Kind | Shape | Meaning |
+| --- | --- | --- |
+| `start` | ellipse | Process start |
+| `end` | ellipse | Process end |
+| `process` | rectangle | Operation or step |
+| `decision` | diamond | Condition with branches |
+| `io` | parallelogram | Input or output |
+| `connector` | circle | Explicit hand-off point for a disconnected flow |
+
+Nodes without `kind` use `process` as the minimal default. Non-Flow diagrams continue to use their existing node visual language.
+
+### 14B — Process structures
+
+- Sequential execution uses ordinary `from` → `to` edges.
+- Decision branches use `edge.label`, normally `yes` / `no` or localized equivalents.
+- Loops are ordinary edges that point to an earlier node; cycles are allowed for Flow.
+- Connectors never use implicit matching. Every connection is explicit in `edges`.
+
+The capability contract exposes these rules through `getCapabilities().diagram.flowNodeKinds`, `flowBranchEdges`, `flowLoops`, and `flowConnectors`.
+
+### 14C — Layout and rendering
+
+- Existing layered, manual, and orthogonal layout/routing remain the source of truth.
+- Semantic shapes share the existing Scene Graph, hit testing, selection, edge routing, export, and accessibility surfaces.
+- SVG and Canvas use the same node geometry and edge path data.
+- Process-only Flow remains concise when `kind` is omitted; this is a convenience default, not a migration compatibility promise. Non-process semantics should use an explicit `kind`.
+
+### 14D — Validation and Agent guidance
+
+- Unknown `nodes[].kind` values are validation errors.
+- A semantic `decision` with fewer than two outgoing edges produces `FLOW_DECISION_BRANCHES`.
+- Semantic Flows without `start` or `end` produce actionable warnings.
+- Unlabeled connectors produce `FLOW_CONNECTOR_LABEL` as a readability warning.
+- Flow schemas, TypeScript declarations, recipes, bilingual guides, manifests, and focused tests stay synchronized.
+
+## Acceptance
+
+- All six node kinds render in both SVG and Canvas.
+- Sequential, branch, and loop structures validate and render.
+- Connector paths remain explicit and inspectable through `explain()` / JSON export.
+- Old rectangle-only Flow examples remain renderable through the `process` default.
+- `npm run contracts:check`, `npm run types:check`, `npm run docs:check`, `npm test`, and browser acceptance pass.
+
+## Non-goals
+
+- No `note` node in this iteration.
+- No BPMN events, gateways, subprocesses, or implicit connector name resolution.
+- No new chart type, CLI, MCP, HTTP, or Python runtime.

package/docs/agent/development/iteration-15.md

@@ -0,0 +1,48 @@
+# Iteration 15 — Text Readability Hardening
+
+Iteration 15 improves text readability without adding a new chart type or a new runtime dependency. The policy is semantic: node labels stay inside nodes, while edge labels remain inline when there is enough space and move only when they collide.
+
+## 15A — Adaptive node labels
+
+Flow, Architecture, Mindmap, and Swimlane node labels use one shared layout policy:
+
+1. Keep the configured theme size when a single line fits.
+2. Wrap to at most two lines when the node can support it.
+3. Reduce the font size to a bounded minimum of `10px`.
+4. Truncate only the final visible line when the label still cannot fit.
+5. Suppress labels in physically tiny nodes such as compact connectors.
+
+The raw label remains available through node data, tooltips, accessibility output, and the Agent state. Nodes use shape-specific inner padding so labels do not touch decision or I/O edges.
+
+## 15B — Semantic edge-label placement
+
+Edge labels use this priority:
+
+1. Place the label inline near the edge midpoint.
+2. Add a small background plate when the edge passes behind the label.
+3. Move the label to one side when it collides with a node or another label.
+4. Suppress only non-core labels when no readable placement exists.
+
+Node labels never move onto edges. Edge routing remains responsible for stopping at node boundaries. The same scene graph is used by SVG and Canvas.
+
+Radar indicator labels use collision-aware placement without background plates. Background plates are reserved for diagram edge labels in Flow, Architecture, Mindmap, and Swimlane; ordinary chart labels retain direct, contrast-aware rendering.
+
+## 15C — Unified label diagnostics
+
+`Chart#getState().layout.labels` exposes family-specific label results, including visible, wrapped, scaled, truncated, suppressed, collision, edge-inline, edge-offset, and backgrounded counts where applicable.
+
+Warnings are emitted for information loss or suppression, including `LABEL_TRUNCATED` and `LABELS_SUPPRESSED`. Agent workflows should inspect `getState()` or `explain()` before assuming that a visible chart contains every original label.
+
+## 15D — Documentation and acceptance
+
+- Shared measurement and fitting helpers live in `src/layout.mjs`.
+- Diagram behavior is implemented in `src/project.mjs`.
+- Generic mark and Radar labels use plate-free collision-aware placement in `src/charts.mjs`.
+- SVG and Canvas use the same scene nodes and label geometry.
+- Acceptance covers CJK and Latin labels, compact nodes, inline edge labels, plate-free Pie/line/Radar labels, and Architecture/Mindmap/Swimlane parity.
+
+Preview pages:
+
+- `playground/project-gallery.html?case=flow`
+- `playground/project-gallery.html?case=architecture`
+- `playground/project-gallery.html?case=radar`

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.17` 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, Timeline/Milestone layout hardening, and chart diagnostic improvements. Geographic charts and 3D rendering remain out of scope until explicitly reintroduced.
+> Roadmap baseline: 2026-09-14. Current release status: `v2.0.19` includes the completed Iteration 12 structured-diagram work, Iteration 13 contract hardening, Iteration 14 lightweight Flow semantics, Iteration 15 text-readability hardening, sector-aware Pie/Donut labels, radius-aware Gauge metrics, and the preceding layout and diagnostic improvements. Geographic charts and 3D rendering remain out of scope until explicitly reintroduced.
 
 ## Current Status
 
@@ -15,7 +15,9 @@
 - 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.17`: 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, Timeline/Milestone layout hardening, and runtime diagnostics for constrained Funnel labels and Swimlane label aliases. No chart type was added.
+- Iteration 13A–13F is complete and included in `v2.0.18`: 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, Timeline/Milestone layout hardening, and runtime diagnostics for constrained Funnel labels and Swimlane label aliases. No chart type was added.
+- Iteration 14A–14D is complete and included in `v2.0.18`: lightweight Flow semantics for start/end, process, decision, input/output, and connector nodes, explicit decision branches and loops, shared SVG/Canvas geometry, capability discovery, validation, and Gallery coverage. No new chart type was added.
+- Iteration 15A–15D is complete and included in `v2.0.19`: adaptive diagram node labels, semantic inline-first edge labels, diagram edge-label background plates, plate-free generic chart labels, shared SVG/Canvas fitting, unified label diagnostics, Agent/diagram documentation, and polar label layout hardening for Pie, Donut, and Gauge.
 - 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

@@ -43,11 +43,42 @@ For a mindmap, prefer the compact parent contract:
 }
 ```
 
+### Lightweight Flow Semantics
+
+`flow` supports a small, unambiguous set of semantic node kinds. Nodes without `kind` use `process` as a convenience default; non-process semantics should be explicit.
+
+```js
+{
+  type: 'flow',
+  nodes: [
+    { id: 'start', kind: 'start', label: 'Start' },
+    { id: 'load', kind: 'process', label: 'Load data' },
+    { id: 'valid', kind: 'decision', label: 'Valid?' },
+    { id: 'output', kind: 'io', label: 'Output result' },
+    { id: 'loop', kind: 'connector', label: 'retry' },
+    { id: 'end', kind: 'end', label: 'End' }
+  ],
+  edges: [
+    { id: 'start-load', from: 'start', to: 'load' },
+    { id: 'load-valid', from: 'load', to: 'valid' },
+    { id: 'valid-yes', from: 'valid', to: 'output', label: 'yes' },
+    { id: 'valid-no', from: 'valid', to: 'loop', label: 'no' },
+    { id: 'loop-load', from: 'loop', to: 'load' },
+    { id: 'output-end', from: 'output', to: 'end' }
+  ]
+}
+```
+
+Supported kinds are `start`, `end`, `process`, `decision`, `io`, and `connector`. A decision should have at least two outgoing labeled edges. Loops are ordinary explicit `from`/`to` edges and are allowed. Connectors are circular hand-off points; they do not use implicit matching, so every connection remains visible in `edges`.
+
+Node labels are centered on the node and use adaptive fitting: they wrap to at most two lines, reduce to a bounded minimum font size, and truncate only as a last resort. Compact nodes such as small connectors suppress their internal label rather than rendering unreadable text; the full label remains in the node data and accessibility surface. Edge labels stay inline when space permits, use a high-opacity background plate when the line would reduce contrast, and move aside only when they collide with nodes or other labels. `getState().layout.labels` and `explain().warnings` expose any wrapping, scaling, truncation, or suppression.
+
 ## Current Capabilities
 
 Supported:
 
 - Nodes, edges, lanes, groups, and ports.
+- Flow semantic shapes: start/end, process, decision, input/output, and connector.
 - `manual`, `layered`, `tree`, and `radial` layouts.
 - Architecture layers and boundaries, plus mindmap parent-child derivation.
 - `straight`, `orthogonal`, and true cubic-Bezier `curved` routing, with adjustable `curveTension` and obstacle-aware orthogonal fallback.

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.17`.
+For environments without npm registry access, install from GitHub as a fallback: `npm install github:wanghetommy/ichartjs#v2.0.19`.
 
 Use the package through a bundler or another environment that resolves npm ESM imports:
 

package/docs/agent/quickstart.md

@@ -103,6 +103,8 @@ const spec = {
 
 Use the selected capability and recipes for Pie, Gauge, Heatmap, Radar, project views, and diagrams because their required encodings differ.
 
+Use `data: { values: rows }` as the canonical public shape. The runtime also accepts a raw row array for compatibility, and the minimal recipe catalog uses that shorter form; do not mix diagram collections into `data.values`. Diagram inputs such as `nodes`, `edges`, `lanes`, `layers`, and `boundaries` stay at the Spec top level.
+
 #### Put options at the contract level
 
 Keep `encoding` for field roles and series semantics. Put presentation and axis options at the Spec level:
@@ -147,6 +149,8 @@ if (!validation.valid) {
 
 Do not silently discard diagnostics. Preserve stable `code`, `path`, `message`, `expected`, and `suggestion` fields in Agent output and automated repair loops.
 
+Diagnostics have two phases: `validateSpec()` reports preflight contract problems, while layout-dependent warnings can appear only after `createChart()` in `chart.getState().warnings` and `chart.explain().warnings`. Always inspect both before returning a chart, especially for narrow Funnel labels.
+
 ### 6. Render
 
 Browser rendering:
@@ -165,6 +169,7 @@ Headless environment capabilities:
 - JSON and SVG string export work with zero dependencies.
 - PNG/JPEG raster export requires the optional `canvas` npm package; otherwise a structured `HEADLESS_EXPORT_UNSUPPORTED` error is returned.
 - The on-screen renderer is decoupled from the export backend; any mounted renderer can export any supported format.
+- Prefer `svg` for accessibility, DOM inspection, and diagram editing; prefer `canvas` for larger mark counts when lower DOM overhead matters.
 
 ### 7. Explain, Export, and Self-Check
 

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.17/skills/ichartjs \
+npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.19/skills/ichartjs \
   --agent codex --global --yes
 ```
 

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

@@ -28,6 +28,8 @@
 
 - Bar、Column、Area 使用 `stack: "stacked"` 或 `stack: "percent"`，不新增堆叠类型。
 - Donut 使用 `type: "pie"` 配合 `innerRadius`。
+- Pie 和 Donut 标签会沿扇区中线布局，并在扇区过小时先缩小字号，再允许自然溢出。需要检查完整可读性时，读取 `getState().layout.labels.polar` 和 `POLAR_LABEL_OVERFLOW` 告警。
+- Gauge 的主数值会保持在仪表主体内，并根据半径自适应字号；Gauge 不生成每个分段的标签。
 - Combo 使用每个系列的 `mark: "column"` 或 `mark: "line"`，并可设置 `axis: "right"`。
 - Histogram 使用 `transform: { type: "bin", field, thresholds | step, extent }`。
 - Heatmap 通过 `colorScale.missing` 区分缺失值和数值零。

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.17/skills/ichartjs`。WorkBuddy 可通过自身 Skill 界面导入该带 Tag 的目录；只有当前 CLI 明确声明对应适配器时才使用宿主专用 `--agent` 参数。
+Codex 全局无交互安装可追加 `--agent codex --global --yes`。需要固定发布版本时，安装 `https://github.com/wanghetommy/ichartjs/tree/v2.0.19/skills/ichartjs`。WorkBuddy 可通过自身 Skill 界面导入该带 Tag 的目录；只有当前 CLI 明确声明对应适配器时才使用宿主专用 `--agent` 参数。
 
 使用 `npx skills add wanghetommy/ichartjs --list` 验证发现结果，其中应包含 `ichartjs`。
 

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

@@ -42,9 +42,39 @@ Architecture 的 `layers` 是从上到下排列的水平分层。同层自动布
 }
 ```
 
+## 轻量级流程语义
+
+`flow` 支持一组小而明确的节点语义。没有设置 `kind` 的节点默认使用 `process`，这是便捷默认值；其他语义应显式设置 `kind`。
+
+```js
+{
+  type: 'flow',
+  nodes: [
+    { id: 'start', kind: 'start', label: '开始' },
+    { id: 'load', kind: 'process', label: '读取数据' },
+    { id: 'valid', kind: 'decision', label: '是否有效？' },
+    { id: 'output', kind: 'io', label: '输出结果' },
+    { id: 'loop', kind: 'connector', label: '重试' },
+    { id: 'end', kind: 'end', label: '结束' }
+  ],
+  edges: [
+    { id: 'start-load', from: 'start', to: 'load' },
+    { id: 'load-valid', from: 'load', to: 'valid' },
+    { id: 'valid-yes', from: 'valid', to: 'output', label: '是' },
+    { id: 'valid-no', from: 'valid', to: 'loop', label: '否' },
+    { id: 'loop-load', from: 'loop', to: 'load' },
+    { id: 'output-end', from: 'output', to: 'end' }
+  ]
+}
+```
+
+支持的 `kind` 为 `start`、`end`、`process`、`decision`、`io` 和 `connector`。判断节点建议至少有两条带标签的出边；循环就是普通的显式 `from` / `to` 回边。Connector 是圆形的断开连接点，不使用隐式同名匹配，所有连接都必须明确写在 `edges` 中。
+
+节点文字默认在节点内居中，并按自适应规则处理：优先保持字号，必要时最多换成两行，再缩小到有限的最小字号，最后才截断。尺寸过小的节点（例如小型 Connector）会隐藏内部文字，避免显示不全；完整文字仍保留在节点数据和无障碍语义中。连线文字在空间足够时优先贴近连线显示；线条影响对比度时使用高不透明度背景底板，只有与节点或其他文字冲突时才移到连线旁边。`getState().layout.labels` 和 `explain().warnings` 会暴露换行、缩放、截断和隐藏结果。
+
 ## 当前能力
 
-已支持节点、边、泳道、Group、Port、四种布局、三种路由、Mindmap 三次贝塞尔曲线、节点拖动、多选、对齐、网格吸附、键盘移动、Copy/Paste、Group 折叠展开、Port 键盘连线、边选择、折点/正交线段手柄、持久化 `waypoints`、边删除和 Undo/Redo。
+已支持节点、边、泳道、Group、Port、Flow 语义图形、四种布局、三种路由、Mindmap 三次贝塞尔曲线、节点拖动、多选、对齐、网格吸附、键盘移动、Copy/Paste、Group 折叠展开、Port 键盘连线、边选择、折点/正交线段手柄、持久化 `waypoints`、边删除和 Undo/Redo。
 
 导航和编辑能力默认关闭。普通图表保持静态，缩放、平移、框选、节点拖动、线段拖动、Port 连线和结构编辑必须由宿主显式开启：
 

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.17`。
+无法访问 npm Registry 的环境请用 GitHub 源作为后备：`npm install github:wanghetommy/ichartjs#v2.0.19`。
 
 ```js
 import { createChart } from '@taylorwong/ichartjs';

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

@@ -34,7 +34,7 @@ Agent 与开发者使用同一个 ESM 入口。编码 Agent 的完整方式见 [
 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()`。
+7. 用 `chart.explain()`、`chart.getState()`、JSON/SVG/PNG export 完成自检。JSON/SVG 可直接使用同步 `chart.export()`；浏览器 PNG 使用 `chart.toDataURL()` 或 `chart.downloadPNG()`；Node 无头 PNG/JPEG 使用 `chart.exportAsync()`，可选安装 `canvas`。最后调用 `chart.destroy()`。
 
 ### 意图必须使用注册词
 
@@ -70,6 +70,8 @@ const spec = structuredClone(catalog.examples.radar);
 
 Agent 自检使用 `chart.getState().health` 和 `chart.explain().health`，其中包含 `ready`、`degraded`、`empty`、警告数、隐藏标签数、限制值数和已渲染标记数。`locale` 默认 `en-US`，需要中文输出时设置 `locale: "zh-CN"`，输入日期仍使用 ISO-8601。
 
+推荐正式数据写法是 `data: { values: rows }`；Runtime 也兼容直接传入行数组，最小 Recipe 为保持紧凑使用了数组形式。Flow、Swimlane、Architecture、Mindmap 的 `nodes`、`edges`、`lanes`、`layers` 和 `boundaries` 必须放在 Spec 顶层。`validateSpec()` 负责渲染前的契约检查；窄 Funnel 标签等依赖布局的告警要在 `chart.getState().warnings` 或 `chart.explain().warnings` 中检查。需要 DOM 可访问性或 Diagram 编辑时优先 SVG，大量标记且希望降低 DOM 开销时选择 Canvas。
+
 ## 品牌署名（Branding）默认行为
 
 - 默认 `branding: true`：在画面与所有导出产物（PNG/SVG/JSON）右下角同步出现 `Powered by iChart.js` 低对比度署名。

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.17/skills/ichartjs \
+npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.19/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.17",
-  "runtimeVersion": "2.0.17",
+  "packageVersion": "2.0.19",
+  "runtimeVersion": "2.0.19",
   "chartTypes": [
     "line",
     "area",
@@ -1080,7 +1080,9 @@
       "optional": [
         "edges",
         "groups",
-        "ports"
+        "ports",
+        "semantic-node-kinds",
+        "connectors"
       ],
       "interactions": [
         "hover",
@@ -1112,6 +1114,10 @@
         "layout": "supported",
         "groups": "supported",
         "ports": "supported",
+        "semantic-shapes": "supported",
+        "decision-branches": "supported",
+        "connectors": "supported",
+        "loops": "supported",
         "history": "supported",
         "axes": "not-applicable",
         "grid": "not-applicable",

package/docs/manifests/schemas.json

@@ -81,6 +81,7 @@
       ],
       "editable": [
         "label",
+        "kind",
         "position",
         "size",
         "laneId",

package/package.json

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

package/skills/ichartjs/SKILL.md

@@ -21,9 +21,9 @@ 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.17/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.19/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:
+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 npm:
 
 ```bash
 npm install @taylorwong/ichartjs@^2
@@ -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`. Funnel stage text comes from `encoding.category` (default `name`) and `labels.enabled` additionally renders values; narrow stages may report `FUNNEL_LABEL_TRUNCATED`, so increase width or shorten the stage name. 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.
+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 `labels.enabled` additionally renders values; narrow stages may report `FUNNEL_LABEL_TRUNCATED`, so increase width or shorten the stage name. For Flow, use top-level `nodes` and `edges`, `nodes[].kind` from `getCapabilities().diagram.flowNodeKinds`, and edge `label` for decision branches. `connector` uses explicit `from`/`to` edges and loops are allowed. 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`, `ZERO_TOTAL`, `UNKNOWN_INTENT`, misplaced-option, unsupported-axis, and `FUNNEL_LABEL_TRUNCATED` warnings before presenting the chart.
+10. Call `validateSpec()` before rendering and repair its preflight errors, warnings, and normalizations. After `createChart()`, inspect `chart.getState()` or `chart.explain()` for render-time diagnostics such as `FUNNEL_LABEL_TRUNCATED`, `VALUE_CLAMPED`, `LABELS_SUPPRESSED`, `LABEL_TRUNCATED`, `NEGATIVE_VALUE_DROPPED`, and `ZERO_TOTAL`; also inspect `getState().layout.labels` for wrapped, scaled, inline-edge, offset-edge, and diagram edge-label background counts. Ordinary chart labels do not use background plates. Do not assume every layout warning is available during preflight.
 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`, `FUNNEL_LABEL_TRUNCATED`, and `ZERO_TOTAL` as material diagnostics to report.
 13. Provide an exact preview URL or artifact path and report assumptions, warnings, and deferred checks.
@@ -64,6 +64,7 @@ Route by requested output:
 - For standard data analysis, read `references/chart-selection.md` and use foundational recipes.
 - For Gantt, Timeline, Milestone, Burndown, capacity, release, risk, or aging, use project capabilities and `agent-recipes/project-management.json`.
 - For Flow or Swimlane, preserve node, edge, lane, group, and port IDs; use diagram recipes and validated edit commands.
+- For diagram readability, keep node labels inside their shapes; edge labels stay inline when space permits and move aside only after a collision. Use `getState().layout.labels.diagram` to detect wrapping, scaling, truncation, suppression, and edge-label offsets instead of shortening source labels in the Agent.
 - For business edits, preview first, preserve the preview ID and revision, require confirmation when declared, then commit or reject atomically.
 - For browser deliverables, start `npm run playground` and return the exact maintained Playground URL.
 - Release workflow (npm publish + develop→master merge) is **AUTHOR ONLY**. Read the [release SOP](https://github.com/wanghetommy/ichartjs/blob/master/docs/agent/development/release-sop.md). Never initiate any release step unless the author explicitly instructs.

package/src/capabilities.mjs

@@ -4,7 +4,7 @@
 import { inspectData } from './data.mjs';
 import { planStyle, styleCapabilities } from './theme.mjs';
 import { defaultPreferences, preferenceDensities, preferenceMotions, preferenceTriStates } from './preferences.mjs';
-import { businessModels, chartProfiles, chartTypes, commandTypes, contractVersion, diagramEdgeModels, diagramOperations, exportTypes, interactionDefaults, renderers } from './contract-registry.mjs';
+import { businessModels, chartProfiles, chartTypes, commandTypes, contractVersion, diagramEdgeModels, diagramOperations, exportTypes, flowNodeKinds, interactionDefaults, renderers } from './contract-registry.mjs';
 
 export { chartProfiles, chartTypes };
 
@@ -199,7 +199,7 @@ export function getCapabilities() {
     charts: JSON.parse(JSON.stringify(chartProfiles)),
     intents,
     locale: { default: 'en-US', recommended: ['en-US', 'zh-CN'], appliesTo: ['axis', 'labels', 'tooltip', 'export'], inputDates: 'ISO-8601 strings; natural-language date parsing is not supported.' },
-    chartModes: { stack: ['stacked', 'percent'], pie: ['standard', 'donut'], composition: ['multi-series', 'mixed-line-column', 'dual-axis'], transforms: ['bin'], diagrams: ['process', 'architecture', 'mindmap'], mindmapLayouts: ['tree', 'radial'], mindmapEdges: ['curved', 'straight', 'orthogonal'] },
+    chartModes: { stack: ['stacked', 'percent'], pie: ['standard', 'donut'], composition: ['multi-series', 'mixed-line-column', 'dual-axis'], transforms: ['bin'], diagrams: ['process', 'architecture', 'mindmap'], mindmapLayouts: ['tree', 'radial'], mindmapEdges: ['curved', 'straight', 'orthogonal'], flowNodeKinds: [...flowNodeKinds], flowBranchEdges: { label: 'edge.label', minimumOutgoing: 2 }, flowLoops: 'supported', flowConnectors: { kind: 'connector', linking: 'explicit from/to edges' } },
     projectManagement: project,
     projectIntelligence: {
       intents: ['schedule', 'milestone', 'progress', 'variance', 'capacity', 'release', 'risk', 'aging', 'workflow', 'responsibility', 'architecture', 'mindmap'],

package/src/charts.mjs

@@ -8,10 +8,11 @@ import { applyTransforms } from './transforms.mjs';
 import { buildProjectScene } from './project.mjs';
 import { formatValue } from './format.mjs';
 import { contrastRatio, resolveTheme } from './theme.mjs';
-import { axisLabelLayout, boxesOverlap, estimateTextWidth, fontSize, titleLayout, truncateText } from './layout.mjs';
+import { axisLabelLayout, boxesOverlap, estimateTextWidth, fontSize, polarLabelLayout, titleLayout, truncateText } from './layout.mjs';
 
 const pick = (row, encoding, fallback) => row?.[encoding?.field || fallback];
 const font = (spec, role, fallback = '12px system-ui') => spec.theme?.typography?.[role]?.font || fallback;
+function fontAtSize(value, size) { const raw = String(value || '12px system-ui'); return /\d+(?:\.\d+)?px/i.test(raw) ? raw.replace(/\d+(?:\.\d+)?px/i, `${size}px`) : `${size}px ${raw}`; }
 const niceMantissas = [1, 1.2, 1.5, 1.8, 2, 2.5, 3, 4, 5, 6, 7.5, 8, 10];
 
 function nearestNiceMantissa(value) {
@@ -192,7 +193,7 @@ function layout(spec, data, legendEntries = [], layoutOptions = {}) {
   return { plot, chrome, layoutFamily: axisFree ? spec.type : 'cartesian', xLabels, axisTitles, axisTitleWarnings, axisLayout: { size: axisSize, leftLabelWidth, rightLabelWidth }, compact: width < 360 || height < 240, recommendedSize: { minWidth: 280, minHeight: 220 }, xField, xEncoding, temporal, quantitativeX, xMin, xMax, yField, yEncodings, categories, rawMin, rawMax, min, max, rawRightMin, rawRightMax, rightMin, rightMax, yTicks, rightTicks, axes: { y: axisInfo([rawMin, rawMax], [min, max], yTicks, spec.yAxis || {}), right: axisInfo([rawRightMin, rawRightMax], [rightMin, rightMax], rightTicks, spec.yAxis?.right || {}) }, x, y, yRight, axisType, rightType };
 }
 
-function addText(scene, id, text, x, y, style = {}, dataRef = null) { scene.add(new SceneNode({ id, type: 'text', geometry: { text: String(text), x, y }, style, dataRef })); }
+function addText(scene, id, text, x, y, style = {}, dataRef = null) { scene.add(new SceneNode({ id, type: 'text', geometry: { text: String(text), x, y }, style, dataRef, zIndex: 4 })); }
 
 function addAxes(scene, spec, state) {
   const { plot, categories, min, max, x, y, yRight } = state;
@@ -248,6 +249,7 @@ function readableLabelColor(spec, background) {
 
 function addMarkLabel(scene, spec, id, value, x, y, dataRef, bounds = null, anchor = null, formatOverride = null, labelBackground = null) {
   if (!spec.labels?.enabled) return;
+  const labelState = scene._labelLayout || (scene._labelLayout = { visible: 0, wrapped: 0, scaled: 0, truncated: 0, suppressed: 0, collisions: 0, backgrounded: 0 });
   const text = formatValue(value, formatOverride || spec.labels.format, spec.locale), size = fontSize(spec, 'label', 12), width = estimateTextWidth(text, size), height = size * 1.25;
   const baseArea = bounds || scene._labelArea || { x: 0, y: 0, width: spec.width, height: spec.height };
   const area = spec.type === 'column' && !anchor ? { ...baseArea, y: baseArea.y - height - 4, height: baseArea.height + height + 4 } : baseArea;
@@ -262,8 +264,9 @@ function addMarkLabel(scene, spec, id, value, x, y, dataRef, bounds = null, anch
   const shifts = anchor ? [preferred, alternate, preferred - height - 3, alternate + height + 3] : [safeY, safeY - height - 3, safeY + height + 3, safeY - 2 * (height + 3), safeY + 2 * (height + 3)];
   const occupied = scene._labelBoxes || (scene._labelBoxes = []);
   const placement = shifts.map(candidateY => Math.max(area.y + height / 2, Math.min(area.y + area.height - height / 2, candidateY))).map(candidateY => ({ x: safeX, y: candidateY, box: { x: safeX - width / 2, y: candidateY - height / 2, width, height } })).find(candidate => !occupied.some(box => boxesOverlap(candidate.box, box, 2)) && (!anchorBox || !boxesOverlap(candidate.box, anchorBox, 0)));
-  if (!placement) return;
+  if (!placement) { labelState.suppressed += 1; labelState.collisions += 1; return; }
   occupied.push(placement.box);
+  labelState.visible += 1;
   addText(scene, `${id}-label`, text, placement.x, placement.y, { fill: labelBackground || markBackground ? readableLabelColor(spec, labelBackground || markBackground) : spec.labels.color || spec.theme.text, font: spec.labels.font || font(spec, 'label'), textAnchor: 'middle', textBaseline: 'middle', baseline: 'middle' }, dataRef);
 }
 
@@ -400,6 +403,7 @@ export function buildScene(spec) {
     data.viewOffset = start;
   }
   const scene = new Scene(spec.width, spec.height);
+  scene._labelLayout = { visible: 0, wrapped: 0, scaled: 0, truncated: 0, suppressed: 0, collisions: 0, backgrounded: 0 };
   const colors = spec.colors;
   const series = Array.isArray(spec.encoding.y) ? spec.encoding.y : [{ ...spec.encoding.y, name: spec.encoding.y?.name || spec.encoding.y?.field }];
   const entries = legendEntries(spec, data, series, colors);
@@ -425,9 +429,12 @@ export function buildScene(spec) {
     data.rows.forEach((row, index) => { const xValue = Number(row[state.xField]), yValue = Number(row[state.yField]); if (!Number.isFinite(xValue) || !Number.isFinite(yValue)) return; const geometry = { cx: state.x(xValue), cy: state.y(yValue), r: 5 }, dataRef = { seriesIndex: 0, dataIndex: index, field: state.yField }; scene.add(new SceneNode({ id: `series-0-item-${index}`, type: 'circle', geometry, bounds: { x: geometry.cx - 8, y: geometry.cy - 8, width: 16, height: 16 }, style: { fill: colors[0] }, dataRef, interactive: true })); addMarkLabel(scene, spec, `series-0-item-${index}`, yValue, geometry.cx, geometry.cy - 8, dataRef, state.plot, { x: geometry.cx, y: geometry.cy, radius: 5 }); });
   } else if (spec.type === 'pie') {
     const categoryField = spec.encoding.category?.field || 'name', valueField = spec.encoding.value?.field || 'value', values = data.rows.map(row => Number(row[valueField])), total = values.reduce((sum, value) => sum + (Number.isFinite(value) && value > 0 ? value : 0), 0), negativeCount = values.filter(value => Number.isFinite(value) && value < 0).length, cx = state.plot.x + state.plot.width / 2, cy = state.plot.y + state.plot.height / 2, radius = Math.min(state.plot.width, state.plot.height) * 0.46, innerR = radius * Number(spec.innerRadius || 0); let angle = -Math.PI / 2;
+    const polarLabels = { visible: 0, scaled: 0, overflowed: 0, suppressed: 0 };
     if (negativeCount) data.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 (!(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 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, 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 })); if (spec.labels?.enabled) { const label = formatValue(value / total, spec.labels.format || { style: 'percent' }, spec.locale), placement = polarLabelLayout(label, { cx, cy, outerRadius: radius, innerRadius: innerR, startAngle: angle, endAngle: end, size: fontSize(spec, 'label', 12), minSize: 10, padding: 4 }); addText(scene, `series-0-item-${index}-label`, label, placement.x, placement.y, { fill: readableLabelColor(spec, fill), font: fontAtSize(spec.labels.font || font(spec, 'label'), placement.size), textAnchor: 'middle', textBaseline: 'middle', baseline: 'middle' }, dataRef); polarLabels.visible += 1; if (placement.scaled) polarLabels.scaled += 1; if (placement.overflowed) polarLabels.overflowed += 1; } angle = end; });
+    state.labelLayout = { ...(state.labelLayout || {}), polar: polarLabels };
+    if (polarLabels.overflowed) data.warnings.push({ code: 'POLAR_LABEL_OVERFLOW', path: 'labels', count: polarLabels.overflowed, message: `${polarLabels.overflowed} pie label${polarLabels.overflowed === 1 ? '' : 's'} exceeded the available sector space and may overflow its sector.`, suggestion: 'Increase chart size, reduce the number of slices, or rely on the legend for small sectors.' });
   } else if (spec.type === 'funnel') {
     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), availableWidth = Math.max(labelSize * 2, width - 12), label = truncateText(category, availableWidth, labelSize); if (label !== category) data.warnings.push({ code: 'FUNNEL_LABEL_TRUNCATED', path: `data.values[${index}].${categoryField}`, index, rawLabel: category, renderedLabel: label, availableWidth, message: `Funnel stage label "${category}" was truncated to "${label}" because the stage is too narrow.`, suggestion: 'Increase chart width, shorten the stage label, or use a wider stage/value distribution.' }); 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); });
@@ -435,9 +442,14 @@ export function buildScene(spec) {
     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.' });
     if (numericValue < Number(domain[0]) || numericValue > Number(domain[1])) data.warnings.push({ code: 'VALUE_CLAMPED', path: `data.values[0].${valueField}`, count: 1, rawValue: numericValue, domain: [...domain], message: `Gauge value ${numericValue} is outside domain [${domain[0]}, ${domain[1]}] and was clamped for the arc.`, suggestion: 'Choose a domain that covers the value or review the source unit.' });
-    scene.add(new SceneNode({ id: 'gauge-background', type: 'arc', geometry: { cx, cy, r: radius, start: Math.PI, end: Math.PI * 2 }, style: { fill: spec.theme.grid } })); scene.add(new SceneNode({ id: 'gauge-value', type: 'arc', geometry: { cx, cy, r: radius, start, end }, style: { fill: colors[0] }, dataRef: { seriesIndex: 0, dataIndex: 0, value, rawValue: numericValue }, interactive: true })); addText(scene, 'gauge-label', formatValue(numericValue, spec.labels?.format || spec.encoding.value?.format || { maximumFractionDigits: 2 }, spec.locale), cx, cy - 12, { fill: spec.theme.text, font: font(spec, 'metric'), textAnchor: 'middle' });
+    const label = formatValue(numericValue, spec.labels?.format || spec.encoding.value?.format || { maximumFractionDigits: 2 }, spec.locale), placement = polarLabelLayout(label, { position: 'center', cx, cy, outerRadius: radius, size: fontSize(spec, 'metric', 24), minSize: 12, maxWidth: radius * 1.25, padding: 4, offsetRatio: 0.36 });
+    scene.add(new SceneNode({ id: 'gauge-background', type: 'arc', geometry: { cx, cy, r: radius, start: Math.PI, end: Math.PI * 2 }, style: { fill: spec.theme.grid } })); scene.add(new SceneNode({ id: 'gauge-value', type: 'arc', geometry: { cx, cy, r: radius, start, end }, style: { fill: colors[0] }, dataRef: { seriesIndex: 0, dataIndex: 0, value, rawValue: numericValue }, interactive: true })); addText(scene, 'gauge-label', label, placement.x, placement.y, { fill: spec.theme.text, font: fontAtSize(font(spec, 'metric'), placement.size), textAnchor: 'middle', textBaseline: 'middle', baseline: 'middle' });
+    state.labelLayout = { ...(state.labelLayout || {}), polar: { visible: 1, scaled: placement.scaled ? 1 : 0, overflowed: placement.overflowed ? 1 : 0, suppressed: 0 } };
+    if (placement.overflowed) data.warnings.push({ code: 'POLAR_LABEL_OVERFLOW', path: 'labels', count: 1, message: 'The Gauge value label exceeds the available body width.', suggestion: 'Increase chart size or reduce the metric font size.' });
   }
   addLegend(scene, spec, state.chrome.legend);
+  state.labelLayout = { ...(state.labelLayout || {}), marks: scene._labelLayout };
+  if (scene._labelLayout.suppressed) data.warnings.push({ code: 'LABELS_SUPPRESSED', path: 'labels', count: scene._labelLayout.suppressed, message: `${scene._labelLayout.suppressed} data labels were suppressed because there was no collision-free placement.`, suggestion: 'Increase chart size, reduce label density, or disable labels.' });
   addBranding(scene, spec);
   return { scene, data, state };
 }

package/src/contract-registry.mjs

@@ -11,6 +11,7 @@ export const commandTypes = ['updateField', 'updateRecord', 'updateTask', 'shift
 export const diagramOperations = ['moveNode', 'moveNodes', 'resizeNode', 'alignNodes', 'snapNodes', 'moveNodeToLane', 'moveGroup', 'resizeGroup', 'assignNodesToGroup', 'duplicateGroup', 'deleteGroup', 'updateEdge', 'removeEdge', 'addEdge', 'toggleGroupCollapse', 'duplicateSelection', 'pasteSelection'];
 export const businessModels = ['project-task', 'timeline-event', 'milestone', 'burndown-sample', 'flow-node', 'flow-edge', 'swimlane', 'architecture-node', 'architecture-edge', 'mindmap-edge', 'mindmap-node'];
 export const diagramEdgeModels = ['flow-edge', 'architecture-edge', 'mindmap-edge'];
+export const flowNodeKinds = ['start', 'end', 'process', 'decision', 'io', 'connector'];
 
 const status = (supported, notApplicable = []) => Object.fromEntries(supported.map(name => [name, 'supported']).concat(notApplicable.map(name => [name, 'not-applicable'])));
 const commonPresentation = ['title', 'subtitle', 'theme', 'responsive', 'empty-state', 'invalid-data-state', 'export', 'branding'];
@@ -30,7 +31,7 @@ export const chartDefinitions = {
   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']) },
+  flow: { family: 'diagram', intents: ['workflow'], required: ['nodes'], optional: ['edges', 'groups', 'ports', 'semantic-node-kinds', 'connectors'], 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', 'semantic-shapes', 'decision-branches', 'connectors', 'loops', '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']) },
   architecture: { family: 'diagram', intents: ['architecture', 'business-architecture', 'data-architecture', 'technical-architecture'], required: ['nodes'], optional: ['edges', 'layers', 'boundaries', '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', 'layers', 'boundaries', 'groups', 'ports', 'history'], ['axes', 'grid', 'legend']) },
   mindmap: { family: 'diagram', intents: ['mindmap', 'hierarchy', 'brainstorm'], required: ['nodes'], optional: ['parentId', 'edges', 'groups'], interactions: ['hover', 'tooltip', 'selection', 'edge-selection', 'drag', 'edgeDrag', 'zoom', 'pan', 'keyboard', 'keyboard-edit', 'keyboard-port-connect', 'portConnect', 'copy-paste'], features: status([...commonPresentation, 'labels', 'routing', 'cubic-bezier', 'curve-tension', 'obstacle-fallback', 'manual-routing', 'layout', 'tree-layout', 'radial-layout', 'history'], ['axes', 'grid', 'legend']) }
@@ -55,5 +56,6 @@ export const contractRegistry = Object.freeze({
   commandTypes: [...commandTypes],
   diagramOperations: [...diagramOperations],
   businessModels: [...businessModels],
-  diagramEdgeModels: [...diagramEdgeModels]
+  diagramEdgeModels: [...diagramEdgeModels],
+  flowNodeKinds: [...flowNodeKinds]
 });

package/src/diagram.mjs

@@ -4,10 +4,12 @@
  */
 import { copyJSON } from './schema.mjs';
 import { sampleCubicBezier } from './scene.mjs';
+import { flowNodeKinds } from './contract-registry.mjs';
 
 export const diagramLayoutModes = ['manual', 'layered', 'tree', 'radial'];
 export const edgeRoutingModes = ['straight', 'orthogonal', 'curved'];
 export const diagramModes = ['process', 'architecture', 'mindmap'];
+export { flowNodeKinds };
 
 const finite = value => typeof value === 'number' && Number.isFinite(value);
 
@@ -53,6 +55,7 @@ export function validateDiagram(spec = {}) {
     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 (normalized.type === 'flow' && node.kind !== undefined && !flowNodeKinds.includes(node.kind)) errors.push({ code: 'FLOW_NODE_KIND', path: `nodes.${index}.kind`, message: `Unsupported Flow node kind: ${node.kind}.`, expected: flowNodeKinds, suggestion: `Use one of: ${flowNodeKinds.join(', ')}.` });
     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.' });
@@ -88,6 +91,19 @@ export function validateDiagram(spec = {}) {
     if (edge.curveTension !== undefined && (!finite(edge.curveTension) || edge.curveTension < 0.2 || edge.curveTension > 0.8)) errors.push({ code: 'EDGE_CURVE_TENSION', path: `edges.${index}.curveTension`, message: 'Edge curve tension must be a finite number between 0.2 and 0.8.' });
     if (edge.waypoints !== undefined && (!Array.isArray(edge.waypoints) || edge.waypoints.some(point => !point || !finite(point.x) || !finite(point.y)))) errors.push({ code: 'EDGE_WAYPOINTS', path: `edges.${index}.waypoints`, message: 'Edge waypoints must be an array of finite x/y points.' });
   });
+  if (normalized.type === 'flow') {
+    const semanticNodes = nodes.filter(node => node.kind !== undefined), outgoing = new Map(nodes.map(node => [node.id, []]));
+    edges.forEach(edge => { if (outgoing.has(edge.from)) outgoing.get(edge.from).push(edge); });
+    semanticNodes.forEach(node => {
+      const nodeIndex = nodes.indexOf(node), path = `nodes.${nodeIndex}.kind`;
+      if (node.kind === 'decision' && (outgoing.get(node.id) || []).length < 2) warnings.push({ code: 'FLOW_DECISION_BRANCHES', path, message: 'A decision node should have at least two outgoing branches.', suggestion: 'Add labeled edges such as label: "yes" and label: "no".' });
+      if (node.kind === 'connector' && !node.label) warnings.push({ code: 'FLOW_CONNECTOR_LABEL', path, message: 'An unlabeled connector is valid but harder to follow in a detached flow.', suggestion: 'Add a short label when the connector is used to join separated flow sections.' });
+    });
+    if (semanticNodes.length) {
+      if (!semanticNodes.some(node => node.kind === 'start')) warnings.push({ code: 'FLOW_MISSING_START', path: 'nodes', message: 'Semantic Flow has no start node.', suggestion: 'Add one node with kind: "start", or use explicit kind: "process" for a process-only Flow.' });
+      if (!semanticNodes.some(node => node.kind === 'end')) warnings.push({ code: 'FLOW_MISSING_END', path: 'nodes', message: 'Semantic Flow has no end node.', suggestion: 'Add one node with kind: "end", or use explicit kind: "process" for a process-only Flow.' });
+    }
+  }
   if (!diagramLayoutModes.includes(normalized.diagram.layout)) errors.push({ code: 'LAYOUT_MODE', path: 'diagram.layout', message: `Unsupported layout: ${normalized.diagram.layout}.` });
   if (!finite(normalized.diagram.grid) || normalized.diagram.grid <= 0) errors.push({ code: 'DIAGRAM_GRID', path: 'diagram.grid', message: 'Grid must be a positive finite number.' });
   if (!finite(normalized.diagram.curveTension) || normalized.diagram.curveTension < 0.2 || normalized.diagram.curveTension > 0.8) errors.push({ code: 'CURVE_TENSION', path: 'diagram.curveTension', message: 'Curve tension must be a finite number between 0.2 and 0.8.' });

package/src/index.mjs

@@ -23,7 +23,7 @@ import { explainChart, getCapabilities as discoverCapabilities, getChartCapabili
 import { applyPreferencesToSpec, createPreferencesStore, defaultPreferences, mergePreferences, mergeThemePreference, normalizePreferences, validatePreferences } from './preferences.mjs';
 import { mountChartSettings } from './preferences-ui.mjs';
 import { ChartValidationError } from './errors.mjs';
-import { diagramOperations } from './contract-registry.mjs';
+import { diagramOperations, flowNodeKinds } from './contract-registry.mjs';
 import { destroyChart } from './chart-lifecycle.mjs';
 
 import { isDiagram, paintSelection, diagramPointer, diagramKeyboard } from './diagram-interaction.mjs';
@@ -762,7 +762,7 @@ export class Chart {
 
 export function createChart(spec) { return new Chart(spec); }
 export { ChartValidationError } from './errors.mjs';
-export function getCapabilities() { const capabilities = discoverCapabilities(); return { ...capabilities, interactionDefaults: { ...capabilities.interactionDefaults }, diagram: { layoutModes: diagramLayoutModes, routingModes: edgeRoutingModes, entities: ['node', 'edge', 'lane', 'group', 'port', 'waypoint'], operations: [...diagramOperations], curvedEdges: { renderers: ['canvas', 'svg'], type: 'cubic-bezier', tension: { minimum: 0.2, maximum: 0.8, default: 0.4 }, mindmapDefault: true, obstacleFallback: 'orthogonal', controlPointEditing: false }, edgeEditing: { renderers: ['canvas', 'svg'], selection: true, waypointDrag: true, segmentDrag: true, persistentWaypoints: true, enabledByDefault: false, activation: ['editing.enabled', 'interaction.edgeDrag'] }, validation: ['duplicate-ids', 'missing-endpoints', 'missing-ports', 'missing-lanes', 'invalid-waypoints', 'invalid-curve-tension'] }, editing: { modes: ['preview', 'commit', 'undo', 'redo'], operations: [...capabilities.commands], confirmationRequiredByDefault: true, commit: 'local-runtime-host-persistence-required' } }; }
+export function getCapabilities() { const capabilities = discoverCapabilities(); return { ...capabilities, interactionDefaults: { ...capabilities.interactionDefaults }, diagram: { layoutModes: diagramLayoutModes, routingModes: edgeRoutingModes, entities: ['node', 'edge', 'lane', 'group', 'port', 'waypoint'], operations: [...diagramOperations], flowNodeKinds: [...flowNodeKinds], flowBranchEdges: { label: 'edge.label', minimumOutgoing: 2 }, flowLoops: 'supported', flowConnectors: { kind: 'connector', linking: 'explicit from/to edges' }, curvedEdges: { renderers: ['canvas', 'svg'], type: 'cubic-bezier', tension: { minimum: 0.2, maximum: 0.8, default: 0.4 }, mindmapDefault: true, obstacleFallback: 'orthogonal', controlPointEditing: false }, edgeEditing: { renderers: ['canvas', 'svg'], selection: true, waypointDrag: true, segmentDrag: true, persistentWaypoints: true, enabledByDefault: false, activation: ['editing.enabled', 'interaction.edgeDrag'] }, validation: ['duplicate-ids', 'missing-endpoints', 'missing-ports', 'missing-lanes', 'invalid-waypoints', 'invalid-curve-tension'] }, editing: { modes: ['preview', 'commit', 'undo', 'redo'], operations: [...capabilities.commands], confirmationRequiredByDefault: true, commit: 'local-runtime-host-persistence-required' } }; }
 export function recommend(input, options = {}) { const plan = planChart(input, options); return { primary: plan.primary, alternatives: plan.alternatives, reason: plan.reasons.join(' '), reasons: plan.reasons, confidence: plan.confidence, requiredFields: plan.requiredFields, assumptions: plan.assumptions, warnings: plan.warnings, nextActions: plan.nextActions }; }
 export { normalizeSpec, validateSpec, normalizeData, inspectData, binData, applyTransforms, data, getBusinessSchema, inspectDataSchema, validateData, getEditCapabilities, validateEdit, previewEdit, commitPreview, validateRecipe, getChartCapability, getPreferenceCapabilities, planChart, explainChart };
 export { diagramLayoutModes, diagramModes, edgeRoutingModes, normalizeDiagramSpec, validateDiagram, layoutDiagram, routeEdge };
@@ -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.17', 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.19', 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/layout.mjs

@@ -48,6 +48,74 @@ export function truncateText(text, maxWidth, size = 12) {
   return `${characters.slice(0, low).join('')}${suffix}`;
 }
 
+function wrapText(text, maxWidth, size) {
+  const characters = Array.from(String(text ?? ''));
+  if (!characters.length) return [''];
+  const lines = [];
+  let line = '';
+  characters.forEach(character => {
+    const candidate = `${line}${character}`;
+    if (line && estimateTextWidth(candidate, size) > maxWidth) {
+      lines.push(line.trimEnd());
+      line = character.trimStart();
+    } else line = candidate;
+  });
+  if (line || !lines.length) lines.push(line.trimEnd());
+  return lines;
+}
+
+export function fitTextBlock(text, options = {}) {
+  const value = String(text ?? ''), maxWidth = Math.max(1, Number(options.maxWidth) || 1), maxHeight = Math.max(1, Number(options.maxHeight) || 1);
+  const baseSize = Math.max(1, Number(options.size) || 12), minSize = Math.max(1, Math.min(baseSize, Number(options.minSize) || 10));
+  const maxLines = Math.max(1, Math.floor(Number(options.maxLines) || 2)), lineHeightRatio = Math.max(1, Number(options.lineHeight) || 1.2);
+  for (let size = baseSize; size >= minSize; size -= 1) {
+    const lines = wrapText(value, maxWidth, size);
+    if (lines.length <= maxLines && lines.every(line => estimateTextWidth(line, size) <= maxWidth) && lines.length * size * lineHeightRatio <= maxHeight) {
+      return { lines, size, lineHeight: size * lineHeightRatio, width: Math.max(size, ...lines.map(line => estimateTextWidth(line, size))), height: lines.length * size * lineHeightRatio, wrapped: lines.length > 1, scaled: size < baseSize, truncated: false };
+    }
+  }
+  const lines = wrapText(value, maxWidth, minSize).slice(0, maxLines);
+  const visibleHeight = maxLines * minSize * lineHeightRatio;
+  if (visibleHeight > maxHeight) lines.splice(1);
+  const last = lines.length - 1;
+  lines[last] = truncateText(lines[last], maxWidth, minSize);
+  return { lines, size: minSize, lineHeight: minSize * lineHeightRatio, width: Math.max(minSize, ...lines.map(line => estimateTextWidth(line, minSize))), height: Math.min(maxHeight, Math.max(minSize, lines.length * minSize * lineHeightRatio)), wrapped: lines.length > 1, scaled: minSize < baseSize, truncated: lines.join('') !== value };
+}
+
+export function polarLabelLayout(text, options = {}) {
+  const value = String(text ?? ''), baseSize = Math.max(1, Number(options.size) || 12), minSize = Math.max(1, Math.min(baseSize, Number(options.minSize) || 10));
+  const padding = Math.max(0, Number(options.padding) || 4), lineHeight = Math.max(1, Number(options.lineHeight) || 1.2), cx = Number(options.cx) || 0, cy = Number(options.cy) || 0;
+  const outerRadius = Math.max(1, Number(options.outerRadius) || 1), innerRadius = Math.max(0, Math.min(outerRadius, Number(options.innerRadius) || 0));
+  let size = baseSize, width = estimateTextWidth(value, size), maxWidth = Infinity, maxHeight = Infinity, x = cx, y = cy, angle = 0, radius = 0;
+  if (options.position === 'center') {
+    maxWidth = Math.max(1, Number(options.maxWidth) || outerRadius * 1.25);
+    maxHeight = Math.max(1, outerRadius * 0.68);
+    while (size > minSize && (width > maxWidth || size * lineHeight > maxHeight)) {
+      size -= 1;
+      width = estimateTextWidth(value, size);
+    }
+    const height = size * lineHeight;
+    const desiredY = cy - outerRadius * Number(options.offsetRatio ?? 0.36);
+    y = Math.max(cy - outerRadius + height / 2 + padding, Math.min(cy - height / 2 - padding, desiredY));
+    return { x, y, angle: -Math.PI / 2, radius: Math.abs(cy - y), size, width, height, scaled: size < baseSize, overflowed: width > maxWidth || height > maxHeight };
+  }
+  const startAngle = Number(options.startAngle) || 0, endAngle = Number(options.endAngle) || startAngle, sweep = Math.max(0, endAngle - startAngle), halfSweep = Math.min(Math.PI / 2, sweep / 2), centerAngle = startAngle + sweep / 2;
+  const preferredRadius = Number(options.preferredRadius) || (innerRadius > 0 ? (innerRadius + outerRadius) / 2 : outerRadius * 0.68);
+  radius = Math.max(innerRadius + padding + baseSize / 2, Math.min(outerRadius - padding - baseSize / 2, preferredRadius));
+  maxWidth = Math.max(1, 2 * radius * Math.sin(halfSweep) - padding * 2);
+  maxHeight = Math.max(1, outerRadius - innerRadius - padding * 2);
+  while (size > minSize && (width > maxWidth || size * lineHeight > maxHeight)) {
+    size -= 1;
+    width = estimateTextWidth(value, size);
+  }
+  const height = size * lineHeight;
+  radius = Math.max(innerRadius + padding + height / 2, Math.min(outerRadius - padding - height / 2, radius));
+  angle = centerAngle;
+  x = cx + Math.cos(angle) * radius;
+  y = cy + Math.sin(angle) * radius;
+  return { x, y, angle, radius, size, width, height, scaled: size < baseSize, overflowed: width > maxWidth || height > maxHeight };
+}
+
 export function axisLabelLayout(spec, labels = [], availableWidth = 0) {
   const size = fontSize(spec, 'axis', 12), count = Math.max(1, labels.length);
   const slot = Math.max(1, availableWidth / count), maxWidth = Math.max(size, ...labels.map(label => estimateTextWidth(label, size)));

package/src/project.mjs

@@ -8,7 +8,7 @@ import { layoutArchitectureNodes, layoutDiagram, normalizeDiagramData, routeEdge
 import { analyzeBurndownSeries, analyzeSchedule } from './project-analytics.mjs';
 import { createLinkedProjectState, filterProjectRows, linkedRecordId } from './project-linking.mjs';
 import { contrastRatio, resolveTheme } from './theme.mjs';
-import { axisLabelLayout, estimateTextWidth, fontSize, titleLayout, truncateText } from './layout.mjs';
+import { axisLabelLayout, boxesOverlap, estimateTextWidth, fitTextBlock, fontSize, titleLayout, truncateText } from './layout.mjs';
 
 export const projectTypes = ['gantt', 'timeline', 'milestone', 'burndown', 'flow', 'swimlane', 'architecture', 'mindmap'];
 const day = 86400000;
@@ -55,6 +55,34 @@ function projectDateDomain(spec, rows) {
 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;
+const flowNodeKind = node => node?.kind || 'process';
+
+function diagramNodeLabelLayout(row, kind, geometry, spec, font = null) {
+  const size = font ? Number(String(font).match(/(\d+(?:\.\d+)?)px/)?.[1]) || fontSize(spec, 'label', 12) : fontSize(spec, 'label', 12);
+  const minDimension = Math.min(geometry.width, geometry.height);
+  const horizontalPadding = kind === 'decision' ? size * 1.8 : size * 1.25;
+  const maxWidth = Math.max(0, geometry.width - horizontalPadding * 2);
+  if (minDimension < Math.max(24, size * 2) || maxWidth < size * 2.4) return null;
+  return fitTextBlock(row.label || row.id, { maxWidth, maxHeight: Math.max(size, geometry.height - size * 0.45), size, minSize: Math.max(10, Math.min(size, size - 2)), maxLines: 2 });
+}
+
+function flowNodeVisual(kind, box) {
+  const cx = box.x + box.width / 2, cy = box.y + box.height / 2;
+  if (kind === 'start' || kind === 'end') return { type: 'path', geometry: { points: Array.from({ length: 16 }, (_, index) => { const angle = index / 16 * Math.PI * 2; return { x: cx + box.width / 2 * Math.cos(angle), y: cy + box.height / 2 * Math.sin(angle) }; }), closed: true } };
+  if (kind === 'decision') return { type: 'path', geometry: { points: [{ x: cx, y: box.y }, { x: box.x + box.width, y: cy }, { x: cx, y: box.y + box.height }, { x: box.x, y: cy }], closed: true } };
+  if (kind === 'io') {
+    const skew = Math.min(18, box.width * 0.18);
+    return { type: 'path', geometry: { points: [{ x: box.x + skew, y: box.y }, { x: box.x + box.width, y: box.y }, { x: box.x + box.width - skew, y: box.y + box.height }, { x: box.x, y: box.y + box.height }], closed: true } };
+  }
+  if (kind === 'connector') return { type: 'circle', geometry: { cx, cy, r: Math.min(box.width, box.height) / 2 } };
+  return { type: 'rect', geometry: box };
+}
+
+function flowNodeBox(row, generated, fallback) {
+  const kind = flowNodeKind(row), connector = kind === 'connector';
+  const width = Number(row.size?.width) || (connector ? 28 : 112), height = Number(row.size?.height) || (connector ? 28 : 36);
+  return { x: row.position?.x ?? generated?.x ?? fallback.x, y: row.position?.y ?? generated?.y ?? fallback.y, width, height };
+}
 
 function compactRoute(points) {
   return points.filter((point, index) => {
@@ -84,8 +112,56 @@ function routeGanttDependency(dependency, from, to, positions, barOffset, plot)
   return compactRoute([source, { x: sourceStubX, y: source.y }, { x: sourceStubX, y: corridorY }, { x: targetStubX, y: corridorY }, { x: targetStubX, y: target.y }, target]);
 }
 
-function text(scene, id, content, x, y, style = {}) {
-  scene.add({ id, type: 'text', geometry: { text: String(content), x, y }, style: { fill: scene.theme?.text || '#334155', font: scene.theme?.typography?.label?.font || '12px system-ui', ...style }, zIndex: 4 });
+function text(scene, id, content, x, y, style = {}, dataRef = null) {
+  scene.add({ id, type: 'text', geometry: { text: String(content), x, y }, style: { fill: scene.theme?.text || '#334155', font: scene.theme?.typography?.label?.font || '12px system-ui', ...style }, dataRef, zIndex: 4 });
+}
+
+function textBlock(scene, id, block, x, y, style = {}, dataRef = null) {
+  if (!block) return;
+  const start = y - (block.lines.length - 1) * block.lineHeight / 2;
+  block.lines.forEach((line, index) => text(scene, index ? `${id}-${index}` : id, line, x, start + index * block.lineHeight, { textAnchor: 'middle', textBaseline: 'middle', baseline: 'middle', ...style }, dataRef));
+}
+
+function labelPlate(scene, id, box, fill, opacity = 0.94) {
+  scene.add({ id: `${id}-background`, type: 'rect', geometry: { x: box.x - 3, y: box.y - 2, width: box.width + 6, height: box.height + 4 }, style: { fill, opacity, stroke: 'none' }, zIndex: 3 });
+}
+
+function polylineMidpoint(points) {
+  if (!points?.length) return null;
+  if (points.length === 1) return { point: points[0], start: points[0], end: points[0] };
+  const lengths = points.slice(1).map((point, index) => Math.hypot(point.x - points[index].x, point.y - points[index].y));
+  const target = lengths.reduce((sum, value) => sum + value, 0) / 2;
+  let traversed = 0;
+  for (let index = 1; index < points.length; index += 1) {
+    const length = lengths[index - 1];
+    if (traversed + length >= target) {
+      const ratio = length ? (target - traversed) / length : 0;
+      return { point: { x: points[index - 1].x + (points[index].x - points[index - 1].x) * ratio, y: points[index - 1].y + (points[index].y - points[index - 1].y) * ratio }, start: points[index - 1], end: points[index] };
+    }
+    traversed += length;
+  }
+  return { point: points.at(-1), start: points.at(-2), end: points.at(-1) };
+}
+
+function edgeLabelLayout(edge, spec, positions, occupied = []) {
+  const points = edge.points, midpoint = edge.curve === 'cubic' ? { point: cubicBezierPoint(points, 0.5), start: cubicBezierPoint(points, 0.45), end: cubicBezierPoint(points, 0.55) } : polylineMidpoint(points);
+  if (!midpoint) return null;
+  const length = Math.max(1, edge.curve === 'cubic' ? Math.hypot(points.at(-1).x - points[0].x, points.at(-1).y - points[0].y) : Math.hypot(midpoint.end.x - midpoint.start.x, midpoint.end.y - midpoint.start.y));
+  const angle = Math.atan2(midpoint.end.y - midpoint.start.y, midpoint.end.x - midpoint.start.x), normal = { x: -Math.sin(angle), y: Math.cos(angle) }, size = fontSize(spec, 'axis', 12);
+  const block = fitTextBlock(edge.label, { maxWidth: Math.max(size * 3, Math.min(180, length - 10)), maxHeight: size * 2.6, size, minSize: 10, maxLines: 2 });
+  const inlineOffset = 8, candidates = [
+    { x: midpoint.point.x, y: midpoint.point.y - inlineOffset, onLine: true },
+    { x: midpoint.point.x + normal.x * (inlineOffset + block.height + 6), y: midpoint.point.y + normal.y * (inlineOffset + block.height + 6), onLine: false },
+    { x: midpoint.point.x - normal.x * (inlineOffset + block.height + 6), y: midpoint.point.y - normal.y * (inlineOffset + block.height + 6), onLine: false },
+    { x: midpoint.point.x + normal.x * (inlineOffset + 2 * (block.height + 6)), y: midpoint.point.y + normal.y * (inlineOffset + 2 * (block.height + 6)), onLine: false },
+    { x: midpoint.point.x - normal.x * (inlineOffset + 2 * (block.height + 6)), y: midpoint.point.y - normal.y * (inlineOffset + 2 * (block.height + 6)), onLine: false }
+  ];
+  const nodeBoxes = [...positions.values()];
+  for (const candidate of candidates) {
+    const box = { x: candidate.x - block.width / 2, y: candidate.y - block.height / 2, width: block.width, height: block.height };
+    if (!nodeBoxes.some(node => boxesOverlap(box, node, 2)) && !occupied.some(item => boxesOverlap(box, item, 3))) return { ...candidate, anchor: midpoint.point, box, block };
+  }
+  return { ...candidates[0], anchor: midpoint.point, box: { x: candidates[0].x - block.width / 2, y: candidates[0].y - block.height / 2, width: block.width, height: block.height }, block, suppressed: false };
 }
 
 function arrow(scene, id, points, reference, critical = false, curve = null) {
@@ -325,6 +401,9 @@ function diagramScene(scene, spec, rows, state) {
   const columns = Math.max(1, ...[...ranks.values()].map(rank => rank + 1));
   const gapX = Math.max(144, plot.width / columns), laneHeight = Math.max(80, plot.height / Math.max(1, lanes.length));
   const positions = new Map(), slots = new Map();
+  const edgeLabelBoxes = [], labelLayout = { visible: 0, wrapped: 0, scaled: 0, truncated: 0, suppressed: 0, edgeOnLine: 0, edgeOffset: 0, backgrounded: 0 };
+  state.labelLayout = { ...(state.labelLayout || {}), diagram: labelLayout };
+  state.labelWarnings = [];
   lanes.forEach((lane, index) => {
     scene.add({ id: `lane-${index}`, type: 'rect', geometry: { x: plot.x, y: plot.y + index * laneHeight, width: Math.max(plot.width, columns * gapX), height: laneHeight }, style: { fill: index % 2 ? spec.theme.surface : spec.theme.background, stroke: spec.theme.border }, zIndex: -1 });
     text(scene, `lane-label-${index}`, lane.label || lane.id, plot.x - 12, plot.y + index * laneHeight + 20, { textAnchor: 'end' });
@@ -345,17 +424,29 @@ function diagramScene(scene, spec, rows, state) {
       const architectureBox = architectureLayout[row.id];
       const geometry = architectureBox
         ? { ...architectureBox, x: row.position?.x ?? architectureBox.x, y: row.position?.y ?? architectureBox.y }
-        : { x: row.position?.x ?? generated?.x ?? plot.x + rank * gapX + 12, y: row.position?.y ?? generated?.y ?? plot.y + (lanes.length ? lane * laneHeight : 0) + (slot + 0.5) * (lanes.length ? laneHeight : Math.max(plot.height, sameCell * 64)) / sameCell - 18, width: row.size?.width || 112, height: row.size?.height || 36 };
+        : flowNodeBox(row, lanes.length ? { ...generated, y: undefined } : generated, { x: plot.x + rank * gapX + 12, y: plot.y + (lanes.length ? lane * laneHeight : 0) + (slot + 0.5) * (lanes.length ? laneHeight : Math.max(plot.height, sameCell * 64)) / sameCell - (flowNodeKind(row) === 'connector' ? 14 : 18) });
     positions.set(row.id, geometry);
     if (collapsedGroups.has(row.groupId)) return;
     const depth = row.parentId ? (ranks.get(row.id) || 0) : 0;
     const colorIndex = mode === 'mindmap' ? depth % spec.colors.length : lane >= 0 ? lane % spec.colors.length : index % spec.colors.length;
-    scene.add({ id: `node-${row.id}`, type: 'rect', geometry, bounds: { ...geometry }, style: { fill: spec.colors[colorIndex], stroke: row.root || mode === 'mindmap' && !row.parentId ? spec.theme.focus : spec.theme.background, strokeWidth: row.root || mode === 'mindmap' && !row.parentId ? 2 : 1 }, dataRef: { nodeId: row.id, dataIndex: index, datum: row, groupId: row.groupId || null, layerId: row.layerId || null, parentId: row.parentId || null }, interactive: true, zIndex: 2 });
+    const kind = mode === 'process' && spec.type === 'flow' ? flowNodeKind(row) : 'process', visual = flowNodeVisual(kind, geometry);
+    scene.add({ id: `node-${row.id}`, type: visual.type, geometry: visual.geometry, bounds: { ...geometry }, style: { fill: spec.colors[colorIndex], stroke: row.root || mode === 'mindmap' && !row.parentId ? spec.theme.focus : spec.theme.background, strokeWidth: row.root || mode === 'mindmap' && !row.parentId ? 2 : 1 }, dataRef: { nodeId: row.id, kind, dataIndex: index, datum: row, groupId: row.groupId || null, layerId: row.layerId || null, parentId: row.parentId || null }, interactive: true, zIndex: 2 });
     if (spec.editing?.enabled && spec.interaction?.portConnect) (row.ports || []).forEach(port => {
       const point = port.side === 'left' ? { x: geometry.x, y: geometry.y + geometry.height * (port.offset ?? 0.5) } : port.side === 'top' ? { x: geometry.x + geometry.width * (port.offset ?? 0.5), y: geometry.y } : port.side === 'bottom' ? { x: geometry.x + geometry.width * (port.offset ?? 0.5), y: geometry.y + geometry.height } : { x: geometry.x + geometry.width, y: geometry.y + geometry.height * (port.offset ?? 0.5) };
       scene.add({ id: `port-${row.id}-${port.id}`, type: 'circle', geometry: { cx: point.x, cy: point.y, r: 4 }, bounds: { x: point.x - 6, y: point.y - 6, width: 12, height: 12 }, style: { fill: spec.theme.background, stroke: spec.theme.text, strokeWidth: 1.5 }, dataRef: { nodeId: row.id, portId: port.id, groupId: row.groupId || null }, interactive: true, zIndex: 4 });
     });
-    text(scene, `node-label-${row.id}`, row.label || row.id, geometry.x + geometry.width / 2, geometry.y + geometry.height / 2 + (geometry.height < 20 ? 3 : 5), { fill: markText(spec.theme, spec.colors[lane % spec.colors.length]), textAnchor: 'middle', ...(nodeFont ? { font: nodeFont } : {}) });
+    const label = diagramNodeLabelLayout(row, kind, geometry, spec, nodeFont);
+    if (label) {
+      const rawLabel = String(row.label || row.id), labelFont = nodeFont ? nodeFont.replace(/\d+(?:\.\d+)?px/, `${label.size}px`) : `${label.size}px system-ui`;
+      textBlock(scene, `node-label-${row.id}`, label, geometry.x + geometry.width / 2, geometry.y + geometry.height / 2, { fill: markText(spec.theme, spec.colors[lane % spec.colors.length]), font: labelFont }, { nodeId: row.id, rawLabel, renderedLabel: label.lines.join('\n'), truncated: label.truncated });
+      labelLayout.visible += 1;
+      if (label.wrapped) labelLayout.wrapped += 1;
+      if (label.scaled) labelLayout.scaled += 1;
+      if (label.truncated) { labelLayout.truncated += 1; state.labelWarnings.push({ code: 'LABEL_TRUNCATED', path: `nodes.${index}.label`, nodeId: row.id, rawLabel, renderedLabel: label.lines.join('\n'), message: `Node label "${rawLabel}" was truncated to fit its shape.`, suggestion: 'Increase node size or shorten the label.' }); }
+    } else if (kind !== 'connector') {
+      labelLayout.suppressed += 1;
+      state.labelWarnings.push({ code: 'LABELS_SUPPRESSED', path: `nodes.${index}.label`, count: 1, nodeId: row.id, message: `Node label for "${row.label || row.id}" was hidden because the node is too small.`, suggestion: 'Increase node size or use the node tooltip/accessibility text.' });
+    }
   });
   const groupBoxes = new Map();
   groups.forEach(group => {
@@ -394,8 +485,17 @@ function diagramScene(scene, spec, rows, state) {
     const points = path.points;
     arrow(scene, `edge-${index}`, points, { from: edge.from, to: edge.to, edgeId: edge.id || `edge-${index}`, status: edge.status, routing, curveTension: edge.curveTension ?? diagramSpec.diagram.curveTension, waypoints: edge.waypoints || [], fromPortDefinition, toPortDefinition, fromGroupId: fromNode.groupId || null, toGroupId: toNode.groupId || null }, edge.critical === true, path.curve);
     if (edge.label) {
-      const middle = path.curve === 'cubic' ? cubicBezierPoint(points, 0.5) : points[Math.floor(points.length / 2)];
-      text(scene, `edge-label-${index}`, edge.label, middle.x, middle.y - 8, { textAnchor: 'middle', font: spec.theme.typography.axis.font });
+      const placement = edgeLabelLayout({ ...edge, points, curve: path.curve }, spec, positions, edgeLabelBoxes);
+      if (placement) {
+        edgeLabelBoxes.push(placement.box);
+        const rawLabel = String(edge.label), labelFont = `${placement.block.size}px system-ui`;
+        if (placement.onLine) labelLayout.edgeOnLine += 1; else labelLayout.edgeOffset += 1;
+        if (placement.block.wrapped) labelLayout.wrapped += 1;
+        if (placement.block.scaled) labelLayout.scaled += 1;
+        if (placement.block.truncated) { labelLayout.truncated += 1; state.labelWarnings.push({ code: 'LABEL_TRUNCATED', path: `edges.${index}.label`, edgeId: edge.id || `edge-${index}`, rawLabel, renderedLabel: placement.block.lines.join('\n'), message: `Edge label "${rawLabel}" was truncated to fit the available line space.`, suggestion: 'Increase the edge length or shorten the label.' }); }
+        if (placement.onLine) { labelPlate(scene, `edge-label-${index}`, placement.box, spec.theme.background); labelLayout.backgrounded += 1; }
+        textBlock(scene, `edge-label-${index}`, placement.block, placement.x, placement.y, { fill: spec.theme.text, font: labelFont }, { edgeId: edge.id || `edge-${index}`, rawLabel, renderedLabel: placement.block.lines.join('\n'), onLine: placement.onLine, offsetX: placement.x - placement.anchor.x, offsetY: placement.y - placement.anchor.y });
+      }
     }
   });
   state.nodePositions = Object.fromEntries(positions);
@@ -441,7 +541,10 @@ export function buildProjectScene(spec) {
     state.projectAnalytics.warnings = state.schedule.warnings;
   }
   if (!data.rows.length) text(scene, 'empty', sourceRows.length && linked.visibleCount === 0 ? 'No matching data' : spec.emptyText || 'No data', spec.width / 2, spec.height / 2, { textAnchor: 'middle' });
-  else if (diagram) diagramScene(scene, spec, data.rows, state);
+  else if (diagram) {
+    diagramScene(scene, spec, data.rows, state);
+    if (state.labelWarnings?.length) data.warnings.push(...state.labelWarnings);
+  }
   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({
@@ -495,7 +598,7 @@ export function projectTooltip(type, row, locale = 'en-US') {
 
 export function rerouteDiagramScene(scene) {
   const nodeGeometries = new Map();
-  scene.walk(item => { if (item.id.startsWith('node-') && item.dataRef?.nodeId && item.geometry) nodeGeometries.set(item.dataRef.nodeId, item.geometry); });
+  scene.walk(item => { if (item.id.startsWith('node-') && !item.id.startsWith('node-label-') && item.dataRef?.nodeId && item.geometry) nodeGeometries.set(item.dataRef.nodeId, item.geometry); });
   scene.walk(node => {
     if (!node.id.startsWith('edge-') || !node.dataRef?.from || !node.dataRef?.to) return;
     const source = nodeGeometries.get(node.dataRef.from), destination = nodeGeometries.get(node.dataRef.to);
@@ -509,7 +612,13 @@ export function rerouteDiagramScene(scene) {
     const arrowNode = scene.find(`${node.id}-arrow`), beforeTip = node.geometry.points.at(-2);
     if (arrowNode) arrowNode.geometry.points = [end, { x: end.x - 7 * Math.cos(Math.atan2(end.y - beforeTip.y, end.x - beforeTip.x) - Math.PI / 6), y: end.y - 7 * Math.sin(Math.atan2(end.y - beforeTip.y, end.x - beforeTip.x) - Math.PI / 6) }, { x: end.x - 7 * Math.cos(Math.atan2(end.y - beforeTip.y, end.x - beforeTip.x) + Math.PI / 6), y: end.y - 7 * Math.sin(Math.atan2(end.y - beforeTip.y, end.x - beforeTip.x) + Math.PI / 6) }, end];
     const edgeIndex = Number(node.id.slice(5)), label = scene.find(`edge-label-${edgeIndex}`), labelPoint = node.geometry.curve === 'cubic' ? cubicBezierPoint(node.geometry.points, 0.5) : node.geometry.points[Math.floor(node.geometry.points.length / 2)];
-    if (label && labelPoint) { label.geometry.x = labelPoint.x; label.geometry.y = labelPoint.y - 8; }
+    if (label && labelPoint) {
+      const old = { x: label.geometry.x, y: label.geometry.y }, offsetX = Number(label.dataRef?.offsetX) || 0, offsetY = Number(label.dataRef?.offsetY) || 0;
+      label.geometry.x = labelPoint.x + offsetX; label.geometry.y = labelPoint.y + offsetY;
+      const background = scene.find(`edge-label-${edgeIndex}-background`), dx = label.geometry.x - old.x, dy = label.geometry.y - old.y;
+      if (background) { background.geometry.x += dx; background.geometry.y += dy; }
+      for (let lineIndex = 1; ; lineIndex += 1) { const line = scene.find(`edge-label-${edgeIndex}-${lineIndex}`); if (!line) break; line.geometry.x += dx; line.geometry.y += dy; }
+    }
   });
   return scene;
 }

package/src/schema.mjs

@@ -72,7 +72,7 @@ const models = {
   'timeline-event': schema('timeline-event', { title: { type: 'string', required: true, editable: true }, date: { type: 'date', required: true, editable: true }, description: { type: 'string', editable: true }, status }),
   milestone: schema('milestone', { title: { type: 'string', required: true, editable: true }, date: { type: 'date', required: true, editable: true }, status }),
   'burndown-sample': schema('burndown-sample', { date: { type: 'date', required: true, editable: true }, remaining: { type: 'number', min: 0, required: true, editable: true }, scopeChange: { type: 'number', default: 0, editable: true }, forecast: { type: 'date', nullable: true, editable: false } }),
-  'flow-node': schema('flow-node', { label: { type: 'string', required: true, editable: true }, position, size: { type: 'object', editable: true, properties: { width: { type: 'number', required: true, min: 1 }, height: { type: 'number', required: true, min: 1 } } }, laneId: { type: 'string', references: 'swimlane', editable: true }, groupId: { type: 'string', editable: false }, ports: { type: 'array', editable: false, items: { type: 'object', properties: { id: { type: 'string', required: true }, side: { type: 'enum', values: ['left', 'right', 'top', 'bottom'] }, offset: { type: 'number', min: 0, max: 1 } } } }, description: { type: 'string', editable: true }, status }),
+  'flow-node': schema('flow-node', { label: { type: 'string', required: true, editable: true }, kind: { type: 'enum', values: ['start', 'end', 'process', 'decision', 'io', 'connector'], default: 'process', editable: true }, position, size: { type: 'object', editable: true, properties: { width: { type: 'number', required: true, min: 1 }, height: { type: 'number', required: true, min: 1 } } }, laneId: { type: 'string', references: 'swimlane', editable: true }, groupId: { type: 'string', editable: false }, ports: { type: 'array', editable: false, items: { type: 'object', properties: { id: { type: 'string', required: true }, side: { type: 'enum', values: ['left', 'right', 'top', 'bottom'] }, offset: { type: 'number', min: 0, max: 1 } } } }, description: { type: 'string', editable: true }, status }),
   'flow-edge': schema('flow-edge', {
     from: { type: 'string', references: 'flow-node', required: true, editable: true },
     to: { type: 'string', references: 'flow-node', required: true, editable: true },

package/types/index.d.ts

@@ -1,5 +1,6 @@
 export type Renderer = 'canvas' | 'svg' | 'auto';
 export type ChartType = 'line' | 'area' | 'bar' | 'column' | 'pie' | 'scatter' | 'funnel' | 'gauge' | 'heatmap' | 'radar' | 'gantt' | 'timeline' | 'milestone' | 'burndown' | 'flow' | 'swimlane' | 'architecture' | 'mindmap';
+export type FlowNodeKind = 'start' | 'end' | 'process' | 'decision' | 'io' | 'connector';
 export type ThemeMode = 'auto' | 'light' | 'dark' | 'contrast';
 export type ThemePreset = 'auto' | 'analysis' | 'dashboard' | 'report' | 'presentation' | 'project' | 'diagram';
 export type ThemePalette = 'auto' | 'categorical' | 'sequential' | 'diverging' | 'status';
@@ -25,7 +26,7 @@ export class ChartValidationError extends Error { name: 'ChartValidationError';
 export interface DataFieldInfo { name: string; type: 'quantitative' | 'temporal' | 'category' | 'unknown'; role: 'identifier' | 'measure' | 'temporal-dimension' | 'dimension'; unit: string | null; cardinality: number; validCount: number; nullCount: number; min?: number; max?: number; temporalMin?: string; temporalMax?: string; }
 export interface DataInspection { version: '1.0'; rows: number; fields: DataFieldInfo[]; dimensions: string[]; measures: string[]; temporalFields: string[]; missingValueCount: number; warnings: Diagnostic[]; }
 export interface ChartCapability { type: ChartType; family: string; intents: string[]; required: string[]; optional: string[]; dataShapes: string[]; interactions: string[]; features: Record<string, 'supported' | 'not-applicable' | 'degraded'>; renderers: Array<'canvas' | 'svg'>; exports: string[]; limits: Record<string, number>; }
-export interface RuntimeCapabilities { version: '2.0'; contractVersion: '1.1'; chartTypes: ChartType[]; charts: Record<ChartType, ChartCapability>; intents: string[]; locale?: { default: string; recommended: string[]; appliesTo: string[]; inputDates: string }; renderers: Array<'canvas' | 'svg'>; interactions: string[]; exports: Array<'png' | 'svg' | 'json' | 'jpeg'>; styleSystem: { modes: ThemeMode[]; presets: ThemePreset[]; palettes: ThemePalette[]; switchable: boolean; automatic: boolean; [key: string]: unknown }; preferences?: { version: '1.0'; scopes: string[]; persistence: string[]; fields: string[]; agentAdjustable: boolean; interactiveSettingsUI: boolean; precedence: string[]; schema: PreferenceCapabilities }; headless: { preview?: boolean; json: boolean; svg: boolean; png: boolean | string }; export: { types: string[]; mime: Record<string, string>; browser: Record<string, boolean>; headless: Record<string, string | boolean>; methods: string[]; options: Record<string, unknown>; branding: Record<string, unknown> }; branding: { defaultEnabled: boolean; signature: string; options: Record<string, unknown> }; [key: string]: unknown; }
+export interface RuntimeCapabilities { version: '2.0'; contractVersion: '1.1'; chartTypes: ChartType[]; charts: Record<ChartType, ChartCapability>; intents: string[]; locale?: { default: string; recommended: string[]; appliesTo: string[]; inputDates: string }; renderers: Array<'canvas' | 'svg'>; interactions: string[]; exports: Array<'png' | 'svg' | 'json' | 'jpeg'>; chartModes?: Record<string, unknown>; diagram?: { flowNodeKinds?: FlowNodeKind[]; flowBranchEdges?: { label: string; minimumOutgoing: number }; flowLoops?: string; flowConnectors?: { kind: FlowNodeKind; linking: string }; [key: string]: unknown }; styleSystem: { modes: ThemeMode[]; presets: ThemePreset[]; palettes: ThemePalette[]; switchable: boolean; automatic: boolean; [key: string]: unknown }; preferences?: { version: '1.0'; scopes: string[]; persistence: string[]; fields: string[]; agentAdjustable: boolean; interactiveSettingsUI: boolean; precedence: string[]; schema: PreferenceCapabilities }; headless: { preview?: boolean; json: boolean; svg: boolean; png: boolean | string }; export: { types: string[]; mime: Record<string, string>; browser: Record<string, boolean>; headless: Record<string, string | boolean>; methods: string[]; options: Record<string, unknown>; branding: Record<string, unknown> }; branding: { defaultEnabled: boolean; signature: string; options: Record<string, unknown> }; [key: string]: unknown; }
 export interface ChartPlan { version: '1.0'; intent: string; intentKnown?: boolean; intentSuggestions?: string[]; fallbackUsed?: boolean; primary: ChartType; alternatives: ChartType[]; confidence: number; reasons: string[]; requiredFields: string[]; suggestedEncodings: { dimension: string | null; measure: string | null; secondaryMeasure: string | null }; assumptions: string[]; warnings: Diagnostic[]; unsupportedRequests: string[]; nextActions: string[]; capability: ChartCapability; styleRecommendation: StyleRecommendation; data: DataInspection; }
 export interface AxisState { rawDomain: [number, number]; domain: [number, number]; ticks: number[]; step: number | null; policy: 'nice' | 'raw' | 'explicit'; }
 export interface TimeAxisState { orientation: 'horizontal'; field: 'date'; coordinate: 'x'; rowCoordinate: 'y'; domain: [number, number]; domainISO: [string, string]; }
@@ -35,20 +36,76 @@ export interface ChartInteraction { tooltip?: boolean; hover?: boolean; click?:
 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?: 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 ChartPadding { top?: number; right?: number; bottom?: number; left?: number; }
+export interface EncodingSpec { field?: string; type?: string; aggregate?: string; stack?: string | boolean; [key: string]: unknown; }
+export interface ChartData { values?: Array<Record<string, unknown>>; nodes?: DiagramNode[]; edges?: DiagramEdge[]; lanes?: DiagramLane[]; layers?: ArchitectureLayer[]; boundaries?: ArchitectureBoundary[]; groups?: DiagramGroup[]; schema?: BusinessDataSchema; [key: string]: unknown; }
+export interface ChartLegend { visible?: boolean; position?: 'top' | 'bottom' | 'left' | 'right' | string; [key: string]: unknown; }
+export interface ChartLabels { enabled?: boolean; format?: string | Record<string, unknown>; color?: string; font?: string; position?: 'inside' | 'outside' | string; [key: string]: unknown; }
+export interface ColorScaleSpec { domain?: [number, number]; range?: string[]; missing?: string; [key: string]: unknown; }
+export interface StackSpec { mode: 'stacked' | 'percent'; [key: string]: unknown; }
+export interface ChartProjectSpec { calendar?: ProjectCalendarConfig; linked?: { filters?: LinkedFilters; selection?: string[] }; [key: string]: unknown; }
+export interface ChartSpec {
+  version?: string;
+  type: ChartType;
+  renderer?: Renderer;
+  container?: string | Element;
+  chartId?: string;
+  width?: number;
+  height?: number;
+  padding?: ChartPadding;
+  colors?: string[];
+  background?: string;
+  locale?: string;
+  data?: Array<Record<string, unknown>> | ChartData;
+  encoding?: Record<string, EncodingSpec | EncodingSpec[]>;
+  title?: string | ChartTitle;
+  legend?: ChartLegend;
+  grid?: { visible?: boolean; color?: string; [key: string]: unknown };
+  labels?: ChartLabels;
+  xAxis?: AxisSpec;
+  yAxis?: AxisSpec;
+  domain?: [number, number];
+  colorScale?: ColorScaleSpec;
+  indicators?: RadarIndicator[];
+  stack?: 'stacked' | 'percent' | StackSpec;
+  transform?: BinTransform | BinTransform[];
+  criticalPath?: boolean | string[];
+  nodes?: DiagramNode[];
+  edges?: DiagramEdge[];
+  lanes?: DiagramLane[];
+  layers?: ArchitectureLayer[];
+  boundaries?: ArchitectureBoundary[];
+  groups?: DiagramGroup[];
+  diagram?: DiagramConfig;
+  project?: ChartProjectSpec;
+  interaction?: ChartInteraction;
+  editing?: ChartEditing;
+  accessibility?: { enabled?: boolean; description?: string; [key: string]: unknown };
+  branding?: boolean | { enabled?: boolean; [key: string]: unknown };
+  theme?: ThemeMode | ThemePreset | ThemeConfig | ResolvedTheme;
+  preferences?: ChartPreferencesPatch | PreferencesStore;
+  preferencesStore?: PreferencesStore;
+  plugins?: ChartPlugin[];
+  [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; }
+export interface DiagramNode { id: string; label?: string; kind?: FlowNodeKind; position?: { x: number; y: number }; size?: { width: number; height: number }; ports?: Array<{ id: string; side?: 'left' | 'right' | 'top' | 'bottom'; offset?: number }>; groupId?: string; }
 export interface ArchitectureNode extends DiagramNode { layerId?: string; boundaryId?: string; role?: string; description?: string; }
 export interface MindmapNode extends DiagramNode { parentId?: string; branch?: string; description?: string; }
 export interface DiagramPoint { x: number; y: number; }
 export interface DiagramEdge { id?: string; from: string; to: string; fromPort?: string; toPort?: string; label?: string; relation?: string; routing?: 'straight' | 'orthogonal' | 'curved'; curveTension?: number; waypoints?: DiagramPoint[]; }
+export interface DiagramLane { id: string; label?: string; [key: string]: unknown; }
+export interface DiagramGroup { id: string; label?: string; collapsed?: boolean; padding?: number; [key: string]: unknown; }
 export interface DiagramElement { id?: string; type?: string; dataRef?: Record<string, unknown>; geometry?: Record<string, unknown>; [key: string]: unknown; }
 export interface ChartEvent { chart: Chart; type?: string; target?: DiagramElement | null; datum?: Record<string, unknown>; selectedData?: Array<Record<string, unknown>>; [key: string]: unknown; }
 export type ChartListener = (event: ChartEvent) => void;
 export interface ChartPlugin { name?: string; install?(chart: Chart): void; beforeRender?(chart: Chart, model: Record<string, unknown>): void; afterRender?(chart: Chart, model: Record<string, unknown>): void; destroy?(chart: Chart): void; }
 export interface ClipboardState { nodes: DiagramNode[]; edges: DiagramEdge[]; }
-export interface ChartState { renderer: string; width: number; height: number; dataCount: number; selected: unknown[]; revision: number; history: { undo: number; redo: number }; view: Record<string, unknown> | null; timeAxis?: TimeAxisState | null; health: ChartHealth; warnings: Diagnostic[]; preferences: ChartPreferences; clipboard: { nodes: number; edges: number }; [key: string]: unknown; }
+export interface ChartLayoutState { family: string | null; plot: Record<string, unknown>; chrome: Record<string, unknown> | null; labels: Record<string, unknown> | null; }
+export interface ChartAxesState { y?: AxisState; right?: AxisState; [key: string]: unknown; }
+export interface ChartBrandingState { enabled: boolean; signature: string; text: string | null; }
+export interface ChartState { renderer: string; width: number; height: number; dataCount: number; selected: unknown[]; revision: number; history: { undo: number; redo: number }; view: Record<string, unknown> | null; style?: Partial<StyleRecommendation> & { name?: string; mode?: ThemeMode; resolvedMode?: string; palette?: ThemePalette }; layout?: ChartLayoutState | null; timeAxis?: TimeAxisState | null; axes?: ChartAxesState | null; health: ChartHealth; preferences: ChartPreferences; branding?: ChartBrandingState; warnings: Diagnostic[]; assumptions?: string[]; normalizations?: Diagnostic[]; collapsedGroups?: string[]; projectAnalytics?: ProjectAnalyticsState | null; linked?: LinkedState | null; clipboard: { nodes: number; edges: number }; [key: string]: unknown; }
 export interface DiagramConfig { mode?: 'process' | 'architecture' | 'mindmap'; layout?: 'manual' | 'layered' | 'tree' | 'radial'; routing?: 'straight' | 'orthogonal' | 'curved'; curveTension?: number; grid?: number; snap?: boolean; }
 export interface ArchitectureLayer { id: string; label?: string; }
 export interface ArchitectureBoundary { id: string; label?: string; nodeIds?: string[]; padding?: number; color?: string; }