@taylorwong/ichartjs 2.0.6 → 2.0.8

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 2.0.8 - 2026-09-20
+
+- Hardened chart-specific encoding and field validation, including explicit Swimlane requirements and actionable diagnostics for Agents.
+- Added Gauge domain contracts and clamping diagnostics, Heatmap label rendering, locale-aware temporal formatting, semantic Pie labels, and runtime health checkpoints.
+- Added intent fallback suggestions, locale capability metadata, a complete minimal Spec catalog, and synchronized Agent guidance and capability manifests.
+
+## 2.0.7 - 2026-09-20
+
+- Added Architecture and Mindmap chart types with shared diagram contracts, layers, boundaries, parent-child validation, deterministic tree/radial layouts, and Agent-readable schemas and capabilities.
+- Added renderer-parity edge selection and editing, persistent manual waypoints, obstacle-aware routing, and true cubic-Bezier Mindmap edges while keeping navigation and editing disabled by default.
+- Improved chart layout reflow, diagram connection routing, label spacing, legend and branding controls, and compact chart preference behavior.
+- Fixed chart settings placement so scrolling preserves the selected side without viewport snapping and closes the menu directly after its anchor leaves the viewport.
+
 ## 2.0.6 - 2026-09-18
 
 - Added compact per-chart visual settings with explicit default font sizing, capability-aware visibility toggles, bilingual labels, and theme-aware hamburger icon contrast.

package/README.md

@@ -40,7 +40,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.6`.
+As a fallback for environments without npm access, install directly from GitHub: `npm install github:wanghetommy/ichartjs#v2.0.8`.
 
 ### Optional Agent Skill
 
@@ -62,7 +62,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.6/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.8/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/agent-recipes/minimal-specs.json

@@ -0,0 +1,25 @@
+{
+  "version": "2.0",
+  "name": "minimal-specs",
+  "description": "Small validated starting Specs for every public iChart.js chart type.",
+  "examples": {
+    "line": { "type": "line", "renderer": "svg", "data": [{ "id": "jan", "month": "Jan", "value": 12 }], "encoding": { "x": { "field": "month" }, "y": { "field": "value" } } },
+    "area": { "type": "area", "renderer": "svg", "data": [{ "id": "jan", "month": "Jan", "value": 12 }], "encoding": { "x": { "field": "month" }, "y": { "field": "value" } } },
+    "bar": { "type": "bar", "renderer": "svg", "data": [{ "id": "a", "name": "A", "value": 12 }], "encoding": { "x": { "field": "name" }, "y": { "field": "value" } } },
+    "column": { "type": "column", "renderer": "svg", "data": [{ "id": "a", "name": "A", "value": 12 }], "encoding": { "x": { "field": "name" }, "y": { "field": "value" } } },
+    "pie": { "type": "pie", "renderer": "svg", "data": [{ "id": "a", "name": "A", "value": 12 }] },
+    "scatter": { "type": "scatter", "renderer": "svg", "data": [{ "id": "a", "x": 1, "y": 12 }], "encoding": { "x": { "field": "x" }, "y": { "field": "y" } } },
+    "funnel": { "type": "funnel", "renderer": "svg", "data": [{ "id": "visit", "name": "Visit", "value": 100 }] },
+    "gauge": { "type": "gauge", "renderer": "svg", "domain": [0, 100], "data": [{ "id": "completion", "name": "Completion", "value": 72 }] },
+    "heatmap": { "type": "heatmap", "renderer": "svg", "data": [{ "id": "a", "x": "Mon", "y": "AM", "value": 12 }], "encoding": { "x": { "field": "x" }, "y": { "field": "y" }, "color": { "field": "value" } } },
+    "radar": { "type": "radar", "renderer": "svg", "indicators": [{ "name": "Quality", "field": "quality", "min": 0, "max": 100 }, { "name": "Speed", "field": "speed", "min": 0, "max": 100 }, { "name": "Coverage", "field": "coverage", "min": 0, "max": 100 }], "data": [{ "id": "team-a", "quality": 80, "speed": 70, "coverage": 90 }] },
+    "gantt": { "type": "gantt", "renderer": "svg", "data": [{ "id": "task-a", "name": "Task A", "start": "2026-09-01", "end": "2026-09-03" }] },
+    "timeline": { "type": "timeline", "renderer": "svg", "data": [{ "id": "event-a", "date": "2026-09-01", "title": "Kickoff" }] },
+    "milestone": { "type": "milestone", "renderer": "svg", "data": [{ "id": "release", "date": "2026-09-19", "title": "Release" }] },
+    "burndown": { "type": "burndown", "renderer": "svg", "data": [{ "id": "day-1", "date": "2026-09-01", "remaining": 10 }, { "id": "day-2", "date": "2026-09-02", "remaining": 0 }] },
+    "flow": { "type": "flow", "renderer": "svg", "nodes": [{ "id": "start", "label": "Start" }, { "id": "done", "label": "Done" }], "edges": [{ "id": "start-done", "from": "start", "to": "done" }] },
+    "swimlane": { "type": "swimlane", "renderer": "svg", "lanes": [{ "id": "team", "label": "Team" }], "nodes": [{ "id": "task", "label": "Task", "laneId": "team" }], "edges": [] },
+    "architecture": { "type": "architecture", "renderer": "svg", "nodes": [{ "id": "api", "label": "API" }, { "id": "db", "label": "Database" }], "edges": [{ "id": "api-db", "from": "api", "to": "db" }] },
+    "mindmap": { "type": "mindmap", "renderer": "svg", "nodes": [{ "id": "root", "label": "Goal" }, { "id": "child", "label": "Next step", "parentId": "root" }], "edges": [] }
+  }
+}

package/docs/agent/README.md

@@ -17,7 +17,7 @@ This is the user-facing Agent entry point for iChart.js 2.0. Read this file firs
 - [Visual Style and Themes](theme-guide.md): automatic matching, presets, palettes, switching, and contrast checks.
 - [Data Charting](charting-scenario.md): generic data analysis charts.
 - [Project Management](project-scenario.md): Gantt, Timeline, Milestone, and Burndown.
-- [Interactive Diagrams](diagram-scenario.md): Flow, Swimlane, Groups, Ports, and editing.
+- [Interactive Diagrams](diagram-scenario.md): Flow, Swimlane, Architecture, Mindmap, Groups, Ports, and editing.
 - [Runtime Contract](runtime-contract.md): shared Spec, renderer, interaction, and export rules.
 - [Editing Contract](editing-contract.md): schemas, commands, preview, commit, and undo/redo.
 - Machine-readable capability manifests are in `docs/manifests/` and should be loaded on demand.
@@ -56,6 +56,8 @@ For a visual overview of all supported chart types, open `playground/project-gal
 - Prefer `canvas` when rendering many marks or targeting lower-power devices.
 - Use `gantt`, `timeline`, `milestone`, or `burndown` for project delivery views.
 - Use `flow` or `swimlane` for process, ownership, and responsibility views.
+- Use `architecture` for business, data, and technical system structures with declared layers and boundaries.
+- Use `mindmap` for hierarchical ideas, with stable `parentId` references and tree or radial layout.
 - Do not generate `map` or `3d` Specs unless `getCapabilities()` declares them.
 
 ## Error handling

package/docs/agent/charting-scenario.md

@@ -26,6 +26,47 @@ Agent usage and development guide for generic data analysis and metric visualiza
 - Heatmap treats missing values separately from numeric zero through `colorScale.missing`.
 - Radar should declare `min` and `max` for every indicator; omitted or mixed-unit domains produce warnings.
 
+## Configuration Placement
+
+`encoding` describes field roles and series semantics. Keep these options at the Spec level:
+
+| Concern | Correct location | Applies to |
+| --- | --- | --- |
+| Axis title and format | `xAxis.title/format`, `yAxis.title/format` | Line, Area, Bar, Column, Scatter |
+| Readable numeric domain | `yAxis.nice`, `yAxis.ticks`, `yAxis.domain` | Line, Area, Bar, Column, Scatter |
+| Data labels | `labels.enabled/format` | Charts that declare `labels` in capabilities |
+| Legend | `legend.visible/position` | Multi-series Cartesian, Pie, and Radar |
+| Gauge domain | `domain: [min, max]` | Gauge |
+| Heatmap color domain | `colorScale.domain` | Heatmap |
+| Radar indicator domain | `indicators[].min/max` | Radar |
+
+Do not put `title`, `format`, `labels`, or `legend` under `encoding`; `validateSpec()` reports those placements as warnings. Numeric y-axes use readable domains by default (`nice: true`, `ticks: "auto"`). Use `yAxis.domain: [min, max]` for an explicit range, or `yAxis.nice: false` to retain the raw boundary. `xAxis.min/max` and `xAxis.domain` are unsupported for categorical/time layouts and produce a structured warning.
+
+## Encoding Contracts
+
+Use only the channels declared for the selected chart: Cartesian charts use `encoding.x` and `encoding.y`; Pie, Funnel, and Gauge use `encoding.category` and `encoding.value`; Heatmap uses `encoding.x`, `encoding.y`, and `encoding.color`; Radar uses `indicators[].field`. `validateSpec()` reports `UNSUPPORTED_ENCODING_CHANNEL` for an unused channel and `MISSING_ENCODING_FIELD` when a referenced field is absent. Gauge additionally requires `domain: [min, max]`; values outside the domain are clamped for the rendered arc and report `VALUE_CLAMPED`.
+
+The complete set of small starting Specs is available at `@taylorwong/ichartjs/recipes/minimal-specs`.
+
+## Intent Vocabulary
+
+Pass an exact value from `getCapabilities().intents` to `planChart()`. Common mappings are:
+
+| User need | Registered intent | Primary chart |
+| --- | --- | --- |
+| Trend over time | `trend` or `time-series` | Line |
+| Compare categories | `comparison` | Bar |
+| Rank categories | `ranking` | Bar |
+| Distribution or histogram | `distribution` | Column with `bin` transform |
+| Relationship or correlation | `relationship` or `correlation` | Scatter |
+| Composition | `composition` | Column or Area |
+| Matrix intensity | `matrix` or `correlation-grid` | Heatmap |
+| Profile across measures | `multidimensional` or `profile` | Radar |
+
+Natural-language prose such as `trend over time` is not an intent token. Map it to `trend` first. An unknown token returns `UNKNOWN_INTENT` plus a fallback plan; never ignore that warning.
+
+Unknown intent plans expose `intentKnown: false`, `fallbackUsed: true`, and deterministic `intentSuggestions`. Use those fields to remap the request or ask for confirmation instead of silently accepting the fallback chart.
+
 ## Agent Workflow
 
 1. Call `inspectData(data)` to identify fields and missing values.
@@ -33,6 +74,10 @@ Agent usage and development guide for generic data analysis and metric visualiza
 3. Create a JSON-serializable Chart Spec.
 4. Call `validateSpec(spec)` before `createChart(spec)`.
 5. Inspect the result with `chart.describe()` and `chart.getState()`.
+6. Add stable string `id` values to rows when lineage checks, linked selection, or later updates matter.
+7. Check `chart.getState().health.renderable`, `health.status`, and `warnings` before presenting the result. `ready` means no material diagnostic is active; `degraded` means the chart rendered with a material warning; `empty` means it has no meaningful result.
+
+`locale` defaults to `en-US` and controls axis, label, tooltip, and export formatting. Set `locale: "zh-CN"` for Chinese output. Input dates should remain ISO-8601 strings; natural-language date parsing is not part of the runtime contract.
 
 ## Minimal Spec
 
@@ -41,7 +86,7 @@ Agent usage and development guide for generic data analysis and metric visualiza
   type: 'line',
   renderer: 'svg',
   container: '#chart',
-  data: { values: [{ month: 'Jan', sales: 120 }] },
+  data: { values: [{ id: 'jan', month: 'Jan', sales: 120 }] },
   encoding: {
     x: { field: 'month', type: 'category' },
     y: { field: 'sales', type: 'quantitative' }

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.6/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.8/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/iteration-12.md

@@ -0,0 +1,101 @@
+# Iteration 12 — Structured Diagrams: Architecture and Mindmap
+
+Release status: Iteration 12A–12G is included in `v2.0.7`.
+
+Iteration 12 extends the existing Flow/Swimlane diagram runtime with two structured-diagram modes. Architecture diagrams and mindmaps share the same JSON-safe nodes, edges, layout, interaction, export, and Agent contracts; they are not separate renderer implementations.
+
+## 12A — Shared Structured Diagram Model
+
+- Reuse stable node IDs, edges, groups, ports, positions, sizes, routing, selection, keyboard navigation, history, Canvas/SVG rendering, and JSON/SVG/PNG export.
+- Normalize `diagram.mode` as `process`, `architecture`, or `mindmap`.
+- Derive mindmap parent-child edges from `node.parentId` while preserving explicit edges.
+- Validate missing parents, self-parenting, duplicate IDs, layer references, and mindmap cycles.
+- Keep `validateDiagram()` as the Agent-facing validation entry point.
+
+## 12B — Architecture Diagram Mode
+
+- Add `type: 'architecture'` for business, data, and technical architecture views.
+- Support `layers` for stable vertical or horizontal architectural strata.
+- Support `boundaries` with `nodeIds`, labels, padding, and color for bounded contexts, domains, systems, or platform boundaries.
+- Keep regular edges for dependencies, realizes, persists, publishes, and other declared relationships; the runtime does not infer business semantics.
+- Preserve manual positions when supplied and use deterministic layered placement otherwise.
+
+## 12C — Mindmap Mode
+
+- Add `type: 'mindmap'` with `parentId` as the compact Agent-friendly hierarchy contract.
+- Support deterministic `tree` and `radial` layouts through the existing diagram layout modes.
+- Render root and branch emphasis without introducing a new renderer or a separate editing model.
+- Keep explicit IDs and parent references so Agents can update one branch without replacing the whole mindmap.
+
+## 12D — Agent Contract and Schemas
+
+- Expose `architecture` and `mindmap` in `getCapabilities()`, `planChart()`, chart profiles, TypeScript declarations, and manifests.
+- Add `architecture-node`, `architecture-edge`, and `mindmap-node` business schemas.
+- Return assumptions and structured validation diagnostics instead of silently guessing layer, boundary, or parent semantics.
+- Keep architecture and mindmap in the `diagram` family and recommend them only for `architecture`, `hierarchy`, `brainstorm`, and related intents.
+
+## 12E — Playground and Documentation
+
+- Add Architecture and Mindmap examples to `playground/project-gallery.html`.
+- Document the distinction: architecture is a domain/system structure; a mindmap is a hierarchy of ideas. Both are structured diagrams, but a mindmap is not an architecture diagram by default.
+- Use `npm run playground` and preview `http://localhost:3000/playground/project-gallery.html`, then search `Architecture` or `Mindmap`.
+
+## 12F — Renderer-Parity Edge Editing
+
+Direct edge editing must remain a renderer-independent Diagram capability. SVG may be used to validate the interaction first, but Canvas and SVG must expose the same public operations, editing semantics, persisted data, keyboard behavior, and final acceptance status. The feature is not complete while either renderer is read-only or has reduced editing behavior.
+
+The default runtime state must be static and safe, with no unexpected viewport or structural changes. Zoom, pan, brush selection, node dragging, edge dragging, port connection, and structural commands are disabled by default and must be explicitly enabled by the host. Agent-driven edits continue to use the validated preview/commit contract and do not implicitly enable pointer editing in the UI.
+
+### Phase 1 — Edge Hit Testing and Selection
+
+- Add geometry-aware edge hit testing with a forgiving interaction tolerance instead of relying on rectangular scene bounds.
+- Make diagram edges selectable in Flow, Swimlane, Architecture, and Mindmap without changing chart-series line behavior.
+- Support selected, hover, focus, delete, Escape, and keyboard traversal states consistently in Canvas and SVG.
+- Keep hit testing in the shared Scene Graph; SVG transparent strokes may optimize DOM interaction but must not become the source of truth.
+- Expose explicit edge-selection and edge-editing support through `getCapabilities()`.
+- Keep navigation and editing disabled in default chart specs; Gallery and read-only embeds must not enable them implicitly.
+
+### Phase 2 — Waypoint and Segment Handles
+
+- Show bend-point and segment-midpoint handles only after an edge is selected in editing mode.
+- Dragging a bend point updates one waypoint; dragging an orthogonal segment midpoint moves only that horizontal or vertical segment.
+- Use enlarged invisible hit regions and minimum target sizes so thin lines remain usable without visually thickening them.
+- Reuse preview, confirmation, commit, undo, redo, and audit behavior from the shared edit controller.
+- Validate the interaction in SVG first if useful, but do not publish renderer-specific public behavior.
+
+### Phase 3 — Persistent Manual Routing
+
+- Add JSON-safe `waypoints` to the edge contract and preserve stable edge IDs.
+- Apply the same waypoint model to Canvas rendering, SVG rendering, JSON export, SVG/PNG export, copy/paste, duplicate, and Agent edits.
+- Define routing precedence as explicit waypoints first, automatic obstacle-aware routing otherwise.
+- When connected nodes move, preserve valid manual segments, repair invalid endpoint segments, and fall back to deterministic automatic routing when the manual path becomes unusable.
+- Support Agent updates through validated `updateEdge` operations rather than renderer-specific commands.
+
+### 12F Acceptance
+
+- Canvas and SVG pass the same edge hit-testing, selection, handle dragging, persistence, undo/redo, keyboard, and export tests.
+- Flow, Swimlane, Architecture, and Mindmap use the same edge-editing contract and interaction implementation.
+- Thin edges remain easy to select without changing their visible stroke width.
+- Manual waypoints survive rerender, renderer switching, serialization, export, and chart recreation.
+- Node movement never leaves an edge passing through a node; invalid manual routes are repaired or deterministically rerouted.
+- Until all parity criteria pass, capabilities report segment dragging as unavailable rather than advertising SVG-only support.
+- Default charts remain static: zoom, pan, brush, node drag, edge drag, port connection, and structural editing only activate through explicit host configuration.
+
+## 12G — Mindmap Curved Edges
+
+- Mindmap parent-child edges default to `routing: 'curved'`; Flow, Swimlane, and Architecture keep orthogonal defaults.
+- `curved` renders one cubic Bezier segment in both Canvas and SVG instead of a four-point polyline.
+- `diagram.curveTension` and per-edge `curveTension` accept values from `0.2` to `0.8`, with `0.4` as the default.
+- Labels use the Bezier midpoint and arrowheads use the end tangent. Shared Scene Graph hit testing samples the curve so Canvas and SVG selection remain equivalent.
+- Curves that intersect another node fall back deterministically to obstacle-aware orthogonal routing.
+- Explicit `waypoints` retain precedence and render as manual polylines. Bezier control-point editing is intentionally excluded; moving nodes recalculates the curve.
+
+## Acceptance
+
+- `npm run agent:check` passes with 18 public chart types and 10 business schemas.
+- Architecture validates and renders layers, boundaries, nodes, and dependency edges in both SVG and Canvas.
+- Mindmap validates parent references and cycles, derives stable parent-child edges, and renders tree and radial layouts deterministically.
+- Existing Flow and Swimlane tests and previews remain unchanged and pass.
+- Existing export, accessibility, selection, keyboard, and preference behavior remains available through the shared diagram runtime.
+- Iteration 12F is accepted only when Canvas and SVG expose equivalent edge-editing behavior.
+- Iteration 12G is accepted only when Canvas, browser SVG, and headless SVG all emit true cubic Bezier paths and preserve static-by-default interaction behavior.

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.6` is prepared from the completed Iteration 11 visual preference work. Geographic charts and 3D rendering remain out of scope until explicitly reintroduced.
+> Roadmap baseline: 2026-09-14. Current release status: `v2.0.8` includes the completed Iteration 12 structured-diagram work, follow-up chart/menu fixes, and Agent contract hardening. Geographic charts and 3D rendering remain out of scope until explicitly reintroduced.
 
 ## Current Status
 
@@ -14,6 +14,7 @@
 - Iteration 9A–9D implemented the lightweight visual style system, adaptive theme planning, runtime switching, renderer integration, and bilingual Agent guidance without adding a chart type; these capabilities remain in the `2.0.x` line.
 - 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.
 - 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/development-guide.md

@@ -8,7 +8,7 @@ Unified workflow for Coding Agents developing iChart.js 2.0.
 | --- | --- | --- |
 | Generic metrics and data charts | `charting-scenario.md` | `src/charts.mjs` |
 | Schedules, milestones, and progress | `project-scenario.md` | `src/project.mjs` |
-| Processes, swimlanes, and Diagram editing | `diagram-scenario.md` | `src/diagram.mjs`, `src/diagram-interaction.mjs` |
+| Processes, swimlanes, architecture, mindmaps, and Diagram editing | `diagram-scenario.md` | `src/diagram.mjs`, `src/diagram-interaction.mjs` |
 
 ## Standard Change Flow
 

package/docs/agent/diagram-scenario.md

@@ -6,22 +6,36 @@ Agent usage and development guide for process modeling, responsibility mapping,
 
 - `flow`: a process graph made of nodes and edges.
 - `swimlane`: a process graph organized by responsibility lanes.
+- `architecture`: a layered business, data, or technical architecture graph with optional boundaries.
+- `mindmap`: a parent-child hierarchy of ideas rendered as a tree or radial diagram.
+
+Architecture and mindmap are both structured diagrams, but they are not interchangeable: architecture describes declared domain or system relationships, while a mindmap describes an idea hierarchy.
 
 ## Data Model
 
 ```js
 {
-  type: 'flow',
+  type: 'architecture',
+  layers: [{ id: 'business', label: 'Business' }, { id: 'technology', label: 'Technology' }],
+  boundaries: [{ id: 'platform', label: 'Platform', nodeIds: ['api'] }],
   nodes: [{
-    id: 'review',
-    label: 'Review',
-    position: { x: 240, y: 100 },
-    size: { width: 140, height: 44 },
-    ports: [{ id: 'in', side: 'left', offset: 0.5 }],
-    groupId: 'delivery'
+    id: 'api', label: 'Order API', layerId: 'technology', position: { x: 240, y: 100 }
   }],
-  edges: [{ from: 'start', to: 'review', toPort: 'in' }],
-  groups: [{ id: 'delivery', label: 'Delivery' }]
+  edges: [{ id: 'orders-api', from: 'orders', to: 'api', relation: 'realizes', waypoints: [{ x: 220, y: 80 }, { x: 220, y: 160 }] }]
+}
+```
+
+For a mindmap, prefer the compact parent contract:
+
+```js
+{
+  type: 'mindmap',
+  nodes: [
+    { id: 'root', label: 'Release plan' },
+    { id: 'scope', label: 'Scope', parentId: 'root' },
+    { id: 'risk', label: 'Risks', parentId: 'root' }
+  ],
+  diagram: { mode: 'mindmap', layout: 'tree', routing: 'curved', curveTension: 0.4 }
 }
 ```
 
@@ -31,12 +45,25 @@ Supported:
 
 - Nodes, edges, lanes, groups, and ports.
 - `manual`, `layered`, `tree`, and `radial` layouts.
-- `straight`, `orthogonal`, and `curved` routing declarations, with lightweight obstacle-aware orthogonal routing.
+- 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.
 - Node dragging, multi-selection, alignment, and grid snapping.
 - Keyboard movement, copy/paste, duplicate, group collapse/expand, undo/redo, and a shared Canvas/SVG Scene.
 - Port-aware drag-to-connect interaction and typed edge creation.
+- Geometry-aware edge selection, waypoint handles, orthogonal segment handles, persistent manual routing, and edge deletion.
 - Group collapse/expand with collapsed group summary rendering.
 
+Navigation and editing are opt-in. The default chart is static: zoom, pan, brush, node drag, edge drag, port connection, and structural editing are disabled until the host enables them.
+
+```js
+interaction: { zoom: true, pan: true, drag: true, edgeDrag: true, portConnect: true },
+editing: { enabled: true, allowDelete: true, allowStructuralChanges: true }
+```
+
+Canvas and SVG use the same Scene Graph hit testing, `waypoints` contract, commands, history, and interaction behavior.
+
+Mindmap defaults to curved parent-child edges. Set `diagram.curveTension` from `0.2` to `0.8`, override `routing` or `curveTension` on one explicit edge, or use `waypoints` when a persistent manual polyline is required. Bezier control points are not directly editable.
+
 Current limitations:
 
 - Groups are flat; nested groups are not supported.
@@ -50,7 +77,7 @@ Current limitations:
 1. Assign stable IDs to nodes and edges.
 2. Use `validateDiagram(spec)` to check endpoints, ports, groups, lanes, and layout options.
 3. Create the chart with `createChart(spec)`.
-4. Use typed commands such as `moveNodes`, `alignNodes`, `snapNodes`, `addEdge`, `toggleGroupCollapse`, `duplicateSelection`, and `pasteSelection` for edits.
+4. Use typed commands such as `moveNodes`, `alignNodes`, `snapNodes`, `addEdge`, `updateEdge`, `removeEdge`, `toggleGroupCollapse`, `duplicateSelection`, and `pasteSelection` for edits.
 5. Follow the preview/confirm/commit flow for all business-data changes.
 
 ## Implementation Map
@@ -80,3 +107,4 @@ Current limitations:
 - Copy/paste preserves internal edges and produces deterministic new IDs.
 - Group collapse hides member nodes and keeps group-level state visible.
 - Groups, ports, and invalid references produce structured validation results.
+- Canvas and SVG produce equivalent edge selection, handle dragging, persisted waypoints, keyboard behavior, and exports.

package/docs/agent/editing-contract.md

@@ -40,6 +40,8 @@ Core APIs:
 - Command validation does not mutate the input command or source data.
 - Host confirmation is required by default; `confirmed: true` is not an authorization system.
 - External persistence, permissions, and authentication belong to the host application.
+- Pointer navigation and editing are disabled by default. `editing.enabled` authorizes edit transactions; `interaction.drag`, `interaction.edgeDrag`, and `interaction.portConnect` separately expose direct-manipulation UI.
+- Diagram edge routes use JSON-safe `waypoints` and update through `updateEdge`; edge deletion uses `removeEdge` and requires structural-edit permission.
 
 ## Supported Models
 
@@ -50,6 +52,9 @@ Core APIs:
 - `flow-node`
 - `flow-edge`
 - `swimlane`
+- `architecture-node`
+- `architecture-edge`
+- `mindmap-node`
 
 ## History and Revision
 

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

package/docs/agent/project-scenario.md

@@ -24,6 +24,7 @@ Agent usage and development guide for project planning, delivery tracking, and p
 - Keep derived values separate from source rows. State and tooltips may expose variance, float, warnings, and assumptions, but transforms must not mutate source data.
 - Linked filters and linked selection must use stable record IDs, not array positions.
 - Forecasts, risk scores, and aging buckets are inspectable heuristics. They are not commitments, causal claims, or hidden inference.
+- Project chart date axes are derived from `date`, `start`, and `end` records in the current contract; generic `xAxis.title/format` and `xAxis.min/max` settings do not customize them.
 
 ## Agent Workflow
 

package/docs/agent/quickstart.md

@@ -67,6 +67,12 @@ Call `planChart(rows, { intent, renderer })`. Read the full result rather than o
 
 Stop before rendering when `requiredFields` is not empty. Ask for the missing information or choose a supported alternative without fabricating data.
 
+#### Use registered intents only
+
+`intent` is an exact machine token, not a natural-language sentence. Discover the allowlist from `getCapabilities().intents`, then pass values such as `trend`, `time-series`, `comparison`, `ranking`, `distribution`, `relationship`, `matrix`, `multidimensional`, `schedule`, `architecture`, or `mindmap`. Do not pass `trend over time` or `show a sales trend` directly. If an unknown token is passed, `planChart()` returns an `UNKNOWN_INTENT` warning and a safe fallback, which may select the wrong chart if the warning is ignored.
+
+If the user gives prose, map it to a registered token before calling `planChart()` and preserve the original prose separately as user intent.
+
 ### 4. Build a JSON-Friendly Spec
 
 For a trend or comparison with one dimension and one or more measures:
@@ -97,6 +103,28 @@ const spec = {
 
 Use the selected capability and recipes for Pie, Gauge, Heatmap, Radar, project views, and diagrams because their required encodings differ.
 
+#### Put options at the contract level
+
+Keep `encoding` for field roles and series semantics. Put presentation and axis options at the Spec level:
+
+| Need | Correct location | Common mistake |
+| --- | --- | --- |
+| Axis title | `xAxis.title`, `yAxis.title` | `encoding.x.title`, `encoding.y.title` |
+| Axis number/date format | `xAxis.format`, `yAxis.format` | `encoding.x.format`, `encoding.y.format` |
+| Data labels | `labels.enabled`, `labels.format` | `encoding.labels` |
+| Legend | `legend.visible` | `encoding.legend` |
+| Theme and palette | `theme.mode`, `theme.preset`, `theme.palette` | series or encoding color guesses |
+
+`validateSpec()` reports these misplaced options as structured warnings. Repair them before presenting the chart. A single-series Cartesian chart shows the encoded field name in the legend by default; set `legend: { visible: false }` when that label adds no value.
+
+#### Know the domain contract
+
+Numeric Cartesian charts use a readable y-axis domain by default: `yAxis.nice` is `true`, and `yAxis.ticks` is `"auto"`. For an explicit range, use `yAxis.domain: [min, max]`; for example, `{ domain: [0, 2000], ticks: 5 }` produces a stable five-label scale. Set `yAxis.nice: false` to retain the raw data boundary. `yAxis.format` only changes display formatting. `chart.getState().axes` and `chart.explain().axes` expose `rawDomain`, resolved `domain`, `ticks`, `step`, and `policy` for Agent self-checks. `yAxis.right` accepts the same controls for a secondary numeric axis. `xAxis.min/max` and `xAxis.domain` remain unsupported because categorical/time x-axis ranges are derived from records. The other supported domain controls are chart-specific: `gauge.domain`, `heatmap.colorScale.domain`, and `radar.indicators[].min/max`. Project chart date ranges are derived from their records in the current version.
+
+Chart-specific encoding is strict: Cartesian charts use `x`/`y`, Pie/Funnel/Gauge use `category`/`value`, Heatmap uses `x`/`y`/`color`, and Radar uses `indicators[].field`. Missing or unsupported fields are validation errors, not silent fallbacks. Gauge Specs must declare `domain`; inspect `VALUE_CLAMPED` when a value falls outside it. Use the complete minimal catalog at `@taylorwong/ichartjs/recipes/minimal-specs` when starting a new chart.
+
+For Agent self-checks, `chart.getState().health` and `chart.explain().health` expose `ready`, `degraded`, or `empty`, plus warning, suppressed-label, clamped-value, and rendered-mark metrics. `locale` defaults to `en-US`; use `locale: "zh-CN"` for localized number/date output while keeping input dates in ISO-8601 form.
+
 ### 5. Validate
 
 ```js
@@ -177,6 +205,8 @@ Before returning a result, verify:
 - the branding on/off state is documented so live view and exports stay consistent;
 - the preview URL or output artifact (JSON/SVG/PNG/JPEG) is provided to the user.
 
+For deterministic lineage checks and linked updates, give every input row a stable string `id`. Without one, the runtime uses a positional fallback such as `record-0`; that is sufficient for a local render but should not be treated as a durable business identity.
+
 ## Branding (Signature) Defaults
 
 - Default `branding: true`: a low-contrast `Powered by iChart.js` signature appears in the bottom-right corner, synchronized across live rendering, PNG/SVG raster export, and JSON state persistence.

package/docs/agent/runtime-contract.md

@@ -10,16 +10,23 @@ getCapabilities → inspectData → planChart → create Spec → validateSpec
 
 Agents should use `getCapabilities()` first instead of hard-coding undeclared types or operations.
 
+For post-creation visual settings, use `getPreferenceCapabilities(chartType, { locale }) → chart.getPreferences() → validatePreferences(patch) → chart.setPreferences(patch, { source: 'agent' }) → chart.getState().preferences`. This keeps Agent changes on the same allowlisted contract as the built-in settings menu.
+
 Iteration 8 adds per-chart profiles through `getChartCapability(type)`. Each profile declares required data roles, supported interactions, renderers, feature status, exports, and practical limits. Unsupported behavior must be handled from this profile or from validation diagnostics rather than guessed.
 
-`planChart(data, { intent, renderer })` returns a versioned planning result with a primary chart, alternatives, confidence, reasons, required fields, suggested encodings, assumptions, warnings, unsupported requests, safe next actions, and the selected capability profile. Planning never invents business meaning, units, dates, or missing fields.
+`planChart(data, { intent, renderer })` returns a versioned planning result with a primary chart, alternatives, confidence, reasons, required fields, suggested encodings, assumptions, warnings, unsupported requests, safe next actions, and the selected capability profile. `intent` must be one exact token from `getCapabilities().intents`; natural-language prose must be mapped before planning. An unknown token returns `UNKNOWN_INTENT` and a fallback plan, so Agents must inspect warnings before accepting `primary`. Planning never invents business meaning, units, dates, or missing fields.
+
+Unknown intent results also include `intentKnown`, `intentSuggestions`, and `fallbackUsed`. A chart Spec is chart-specific: Cartesian channels are `x`/`y`, Pie/Funnel/Gauge channels are `category`/`value`, Heatmap channels are `x`/`y`/`color`, and Radar fields live in `indicators`. `validateSpec()` rejects unsupported channels and missing fields. Gauge requires an explicit `domain` and reports `VALUE_CLAMPED` when the rendered value exceeds it.
 
 ## Spec Rules
 
 - Specs must be JSON-serializable.
 - Call `validateSpec()` before rendering.
 - Chart layout and data semantics are renderer-independent.
-- `flow` and `swimlane` use `nodes/edges/lanes`; generic charts use `data.values`.
+- Keep axis titles/formats on `xAxis`/`yAxis`, labels on `labels`, and legend settings on `legend`; misplaced options return structured warnings.
+- Numeric y-axes use readable domains by default (`yAxis.nice: true`, `yAxis.ticks: "auto"`). Use `yAxis.domain: [min, max]` for an explicit range, `yAxis.nice: false` to retain the raw boundary, and `yAxis.right` for a secondary numeric axis. `chart.getState().axes` and `chart.explain().axes` expose the raw domain, resolved domain, ticks, step, and policy for Agent verification. `xAxis.min/max` and `xAxis.domain` remain unsupported for categorical/time layouts. Chart-specific domains remain available through `gauge.domain`, `heatmap.colorScale.domain`, and `radar.indicators[].min/max`.
+- `flow` and `swimlane` use `nodes/edges/lanes`; `architecture` uses `nodes/edges/layers/boundaries`; `mindmap` uses `nodes` with `parentId` and optional `edges`; generic charts use `data.values`.
+- `chart.getState().health` and `chart.explain().health` expose `ready`, `degraded`, or `empty`, with renderability and warning, suppressed-label, clamped-value, and rendered-mark metrics. `locale` defaults to `en-US`; set `locale: "zh-CN"` for output formatting and keep input dates as ISO-8601 strings.
 
 ## Renderer
 
@@ -93,10 +100,18 @@ validateSpec(spec)
 createChart(spec)
 getCapabilities()
 getChartCapability(type)
+getPreferenceCapabilities(type, options)
+validatePreferences(patch, options)
 chart.describe()
 chart.explain()
 chart.getState()
+chart.getPreferences()
+chart.setPreferences(patch, options)
+chart.resetPreferences(options)
 chart.getSelectedData()
+chart.selectEdges(edgeIds, options)
+chart.getSelectedEdgeIds()
+chart.deleteSelectedEdges(options)
 chart.export(options)
 chart.exportAsync(options)
 chart.toDataURL(type)
@@ -109,6 +124,8 @@ chart.downloadJSON()
 
 Validation results contain separate `errors`, `warnings`, and `normalizations`. Diagnostics use stable codes, JSON-oriented paths, expected values where useful, and actionable suggestions. `chart.explain()` returns encodings, transforms, interactions, assumptions, warnings, stable record lineage, and an accessibility summary.
 
+For lineage checks and linked updates, provide stable string `id` values on input rows. Without one, the runtime uses deterministic positional IDs such as `record-0`; these are suitable for a local self-check but not for durable business identity.
+
 ## Interaction
 
 Common interactions include Tooltip, Hover, Click, Selection, Zoom, Pan, Drag, Touch, and Keyboard; each chart's enabled interactions are controlled by its Spec and capability declaration.

package/docs/agent/theme-guide.md

@@ -75,7 +75,11 @@ const chart = createChart({
   data: { values: rows },
   preferences: pagePreferences
 });
-mountChartSettings(chart, { locale: 'en' });
+const settings = mountChartSettings(chart, {
+  locale: 'en',
+  placement: 'auto',
+  preferredPlacements: ['right', 'top', 'bottom']
+});
 
 // The same operation can come from an Agent conversation.
 chart.setPreferences({
@@ -83,8 +87,36 @@ chart.setPreferences({
   typography: { scale: 1.15 },
   components: { grid: false }
 }, { source: 'agent' });
+
+// Call this when the host permanently removes the chart.
+settings.destroy();
+```
+
+The quick-settings panel is portaled outside the clipped chart surface. Automatic placement prefers the button's right side, then the top, then the bottom, and finally constrains the panel inside the browser viewport. On scroll it preserves the selected placement and follows the anchor without viewport snapping; it closes directly when the chart or anchor leaves the viewport. Resize and content changes may recompute placement.
+
+### Agent Discovery and Validation
+
+Agents should discover the allowlisted surface instead of hard-coding menu options. `getPreferenceCapabilities(chartType, { locale })` returns every preference field with its type, default value, options, scopes, chart applicability, and `menu.visible` status. Use the same contract for conversational changes and custom settings pages.
+
+```js
+import { getPreferenceCapabilities, validatePreferences } from '@taylorwong/ichartjs';
+
+const capabilities = getPreferenceCapabilities(chart.getSpec().type, { locale: 'en' });
+const menuFields = capabilities.fields.filter(field => field.menu.visible);
+const current = chart.getPreferences();
+const patch = {
+  theme: { preset: 'dashboard', palette: 'status' },
+  typography: { scale: 1.15 },
+  components: { grid: false }
+};
+const checked = validatePreferences(patch, { partial: true });
+if (!checked.valid) throw new Error(JSON.stringify(checked.errors));
+chart.setPreferences(checked.value, { scope: 'chart', source: 'agent' });
+const applied = chart.getState().preferences;
 ```
 
+The quick menu fields are `theme.mode`, `theme.palette`, `typography.scale`, and capability-supported `components.legend`, `components.labels`, and `components.grid`. The full allowlist additionally includes `theme.preset`, `density`, `branding.enabled`, and `motion`. Unknown locales fall back to English.
+
 The optional per-chart menu uses a compact hamburger icon and intentionally exposes only high-frequency controls: theme mode, palette, font scale, and supported legend/label/grid visibility. Capability checks hide controls that do not apply to the current chart. Changes apply immediately and the UI supports `en`, `zh-CN`, and automatic document-language detection.
 
 Keep low-frequency and page-wide controls in a dedicated settings surface outside the chart popover. Share one store across the page, and call `store.setGlobal()` or `chart.setPreferences(patch, { scope: 'global' })`. The full surface may expose preset, density, branding, and other allowlisted preferences without overloading every chart. The store uses memory in Node/SSR unless `localStorage` or a host adapter is explicitly selected. Preview the quick menu in `http://localhost:3000/playground/project-gallery.html` and the full page at `http://localhost:3000/playground/preferences-lab.html`.

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.6/skills/ichartjs \
+npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.8/skills/ichartjs \
   --agent codex --global --yes
 ```
 
@@ -159,6 +159,8 @@ Use the project and diagram contracts when the data has project semantics rather
 - `gantt`, `timeline`, `milestone`, and `burndown` for delivery schedules;
 - project analytics for capacity, velocity, release forecast, risk, and issue aging;
 - `flow` and `swimlane` for process, ownership, responsibility, groups, ports, and controlled editing.
+- `architecture` for business, data, or technical architecture with explicit layers, boundaries, and relationships.
+- `mindmap` for idea hierarchies where `parentId` is the source of truth and a tree or radial layout is preferred.
 
 Preserve stable record, node, edge, lane, group, and port IDs. For business edits, return a preview before commit and include the audit result.
 

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

@@ -11,7 +11,7 @@
 - [视觉样式与主题](theme-guide.md)
 - [数据分析图表](charting-scenario.md)
 - [项目管理图表](project-scenario.md)
-- [交互式 Diagram](diagram-scenario.md)
+- [交互式 Diagram](diagram-scenario.md)：Flow、Swimlane、Architecture、Mindmap 与编辑。
 - [Runtime 契约](runtime-contract.md)
 - [编辑契约](editing-contract.md)
 - 机器可读能力清单位于 `docs/manifests/`，供 Agent 按需读取。