@taylorwong/ichartjs 2.0.6 → 2.0.7

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 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.7`.
 
 ### 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.7/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/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/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.7/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.7` includes the completed Iteration 12 structured-diagram work and follow-up chart/menu fixes. 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.7`.
 
 Use the package through a bundler or another environment that resolves npm ESM imports:
 

package/docs/agent/runtime-contract.md

@@ -10,6 +10,8 @@ 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.
@@ -19,7 +21,7 @@ Iteration 8 adds per-chart profiles through `getChartCapability(type)`. Each pro
 - 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`.
+- `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`.
 
 ## Renderer
 
@@ -93,10 +95,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)

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.7/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 按需读取。

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

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

@@ -6,10 +6,39 @@
 
 - `flow`：节点和边组成的流程图。
 - `swimlane`：带责任泳道的流程图。
+- `architecture`：带可选层和边界的业务、数据或技术架构图。
+- `mindmap`：以树形或放射布局呈现想法层级的思维导图。
+
+架构图和思维导图都属于结构化图，但不能混用：架构图表达明确的领域或系统关系，思维导图表达想法层级。
+
+思维导图建议使用简洁的父子数据：
+
+```js
+{
+  type: 'mindmap',
+  nodes: [
+    { id: 'root', label: '发布计划' },
+    { id: 'scope', label: '范围', parentId: 'root' },
+    { id: 'risk', label: '风险', parentId: 'root' }
+  ],
+  diagram: { mode: 'mindmap', layout: 'tree', routing: 'curved', curveTension: 0.4 }
+}
+```
 
 ## 当前能力
 
-已支持节点、边、泳道、Group、Port、四种布局、三种路由、节点拖动、多选、对齐、网格吸附、键盘移动、Copy/Paste、Group 折叠展开、Port 键盘连线和 Undo/Redo。
+已支持节点、边、泳道、Group、Port、四种布局、三种路由、Mindmap 三次贝塞尔曲线、节点拖动、多选、对齐、网格吸附、键盘移动、Copy/Paste、Group 折叠展开、Port 键盘连线、边选择、折点/正交线段手柄、持久化 `waypoints`、边删除和 Undo/Redo。
+
+导航和编辑能力默认关闭。普通图表保持静态，缩放、平移、框选、节点拖动、线段拖动、Port 连线和结构编辑必须由宿主显式开启：
+
+```js
+interaction: { zoom: true, pan: true, drag: true, edgeDrag: true, portConnect: true },
+editing: { enabled: true, allowDelete: true, allowStructuralChanges: true }
+```
+
+Canvas 与 SVG 共用 Scene Graph 命中、`waypoints`、命令、历史和交互行为，不提供渲染器专属编辑能力。
+
+Mindmap 默认使用曲线父子连线。`diagram.curveTension` 支持 `0.2` 到 `0.8`；显式边可以覆盖 `routing` 或 `curveTension`。存在 `waypoints` 时优先使用人工折线，当前不支持直接拖动贝塞尔控制点。
 
 当前限制：
 
@@ -22,7 +51,7 @@
 1. 为节点和边分配稳定 ID。
 2. 使用 `validateDiagram(spec)` 检查端点、Port、Group、Lane 和布局。
 3. 使用 `createChart(spec)` 创建图表。
-4. 使用 `moveNodes`、`alignNodes`、`snapNodes` 等命令编辑。
+4. 使用 `moveNodes`、`alignNodes`、`snapNodes`、`updateEdge`、`removeEdge` 等命令编辑。
 5. 编辑遵循 `editing-contract.md` 的 Preview/Confirm/Commit 流程。
 
 ## 开发位置与验收
@@ -34,4 +63,4 @@
 - 专用 Demo：`playground/diagram-editor.html`
 - 全量 Gallery：`playground/project-gallery.html`
 
-节点移动后必须验证边、箭头和标签跟随；同时检查 Canvas 与 SVG 的一致性。
+节点移动后必须验证边、箭头和标签跟随；同时检查 Canvas 与 SVG 的边命中、手柄拖动、waypoint 持久化、键盘和导出一致性。

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

@@ -23,5 +23,7 @@ const result = chart.applyEdit(command, { preview, confirmed: true, source: 'age
 - 默认需要 Host 确认；确认不等同于授权。
 - 成功提交产生 ChangeSet、审计信息、revision 和 Undo 历史。
 - 外部持久化、权限和认证由 Host 应用负责。
+- 指针导航和编辑默认关闭。`editing.enabled` 授权编辑事务；`interaction.drag`、`interaction.edgeDrag`、`interaction.portConnect` 分别控制直接操作 UI。
+- Diagram 边通过 JSON-safe 的 `waypoints` 持久化；路径更新使用 `updateEdge`，删除使用 `removeEdge`，并要求结构编辑权限。
 
 Schema、命令、Preview/Commit、事务和历史的实现分别位于 `src/schema.mjs`、`src/command.mjs`、`src/edit.mjs`、`src/edit-controller.mjs` 和 `src/history.mjs`。

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

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

package/docs/agent/zh-CN/iteration-12.md

@@ -0,0 +1,98 @@
+# Iteration 12：结构化图——架构图与思维导图
+
+Iteration 12 在 Flow/Swimlane 现有 Diagram Runtime 上增加两种结构化图模式。架构图和思维导图共用节点、边、布局、交互、导出和 Agent 契约，不新增第二套渲染器。
+
+## 12A：共享结构化图模型
+
+- 复用稳定节点 ID、边、Group、Port、位置、尺寸、路由、选择、键盘导航、历史、Canvas/SVG 渲染以及 JSON/SVG/PNG 导出。
+- 将 `diagram.mode` 归一化为 `process`、`architecture` 或 `mindmap`。
+- 思维导图可以从 `node.parentId` 推导父子边，同时保留显式边。
+- 校验缺失父节点、自引用、重复 ID、无效层引用和思维导图循环。
+- Agent 统一使用 `validateDiagram()` 作为校验入口。
+
+## 12B：架构图模式
+
+- 使用 `type: 'architecture'` 表达业务架构、数据架构和技术架构。
+- 使用 `layers` 表达稳定的架构分层。
+- 使用 `boundaries` 表达领域、系统、平台或上下文边界，并支持 `nodeIds`、标签、边距和颜色。
+- 普通边表达依赖、实现、持久化、发布等关系；Runtime 不擅自推断业务语义。
+- 有明确位置时保留手工布局，否则使用确定性的分层布局。
+
+## 12C：思维导图模式
+
+- 使用 `type: 'mindmap'` 和 `parentId` 表达简洁的 Agent 友好层级。
+- 支持确定性的 `tree` 和 `radial` 布局。
+- 使用现有 Diagram 模型表达根节点和分支强调，不新增独立编辑模型。
+- 保留稳定 ID 和父引用，Agent 可以只更新一个分支。
+
+## 12D：Agent 契约与 Schema
+
+- 在 `getCapabilities()`、`planChart()`、图表能力、TypeScript 声明和 manifest 中暴露 `architecture`、`mindmap`。
+- 增加 `architecture-node`、`architecture-edge`、`mindmap-node` Schema。
+- 对层、边界和父节点语义返回 assumptions 与结构化诊断，不静默猜测。
+- 两者都归入 `diagram` 家族，仅在 architecture、hierarchy、brainstorm 等意图下推荐。
+
+## 12E：Playground 与文档
+
+- 在 `playground/project-gallery.html` 增加 Architecture 和 Mindmap 示例。
+- 要区分：架构图表达领域/系统结构，思维导图表达想法层级；思维导图不默认等同于架构图。
+- 执行 `npm run playground`，打开 `http://localhost:3000/playground/project-gallery.html`，搜索 `Architecture` 或 `Mindmap`。
+
+## 12F：Canvas/SVG 一致的线段编辑
+
+线段直接编辑必须是与渲染器无关的 Diagram 能力。可以先用 SVG 验证交互体验，但 Canvas 与 SVG 必须提供相同的公共操作、编辑语义、持久化数据、键盘行为和最终验收状态。只要任一渲染器仍为只读或能力缩水，12F 就不算完成。
+
+Runtime 默认状态必须静态、安全，不产生意外的视图或结构变化。缩放、平移、框选、节点拖动、线段拖动、端口连线和结构命令默认全部关闭，必须由宿主显式开启。Agent 编辑继续使用经过校验的预览/提交契约，不得隐式开启页面中的指针编辑能力。
+
+### 第一阶段：边命中与选择
+
+- 增加基于几何距离的边命中算法和宽容的交互容差，不再依赖 Scene Node 的矩形 `bounds`。
+- Flow、Swimlane、Architecture、Mindmap 中的边都可选择，但不影响普通 Line 等数据图表的折线交互。
+- Canvas 与 SVG 一致支持选中、Hover、焦点、删除、Escape 和键盘遍历状态。
+- 命中检测放在共享 Scene Graph 中；SVG 可以使用透明粗描边优化 DOM 交互，但不能以 SVG DOM 作为唯一事实来源。
+- 通过 `getCapabilities()` 明确暴露边选择和边编辑能力。
+- 默认图表 Spec 必须关闭导航与编辑；Gallery 和只读嵌入页面不能隐式开启这些能力。
+
+### 第二阶段：折点与线段手柄
+
+- 仅在编辑模式选中边后显示折点手柄和线段中点手柄。
+- 拖动折点只更新一个 waypoint；拖动正交线段中点只移动对应的水平或垂直线段。
+- 使用不可见的扩大命中区域和最小触控尺寸，让细线易于操作，同时不改变可见线宽。
+- 复用共享编辑控制器的预览、确认、提交、撤销、重做和审计能力。
+- 可以先在 SVG 中验证交互，但不能发布渲染器特有的公共行为。
+
+### 第三阶段：人工路由持久化
+
+- 在边契约中增加 JSON-safe 的 `waypoints`，继续使用稳定 edge ID。
+- Canvas、SVG、JSON 导出、SVG/PNG 导出、复制粘贴、复制和 Agent 编辑均使用同一 waypoint 模型。
+- 路由优先级定义为：存在显式 waypoints 时优先使用，否则执行自动避障路由。
+- 节点移动后尽量保留有效人工线段，修复无效的端点线段；人工路径不可用时回退到确定性的自动路由。
+- Agent 通过经过校验的 `updateEdge` 操作更新路径，不增加渲染器专属命令。
+
+### 12F 验收
+
+- Canvas 与 SVG 通过同一套边命中、选择、手柄拖动、持久化、撤销/重做、键盘和导出测试。
+- Flow、Swimlane、Architecture、Mindmap 共用同一套边编辑契约和交互实现。
+- 细线在不改变可见宽度的情况下仍容易选择。
+- 人工 waypoints 在重绘、切换渲染器、序列化、导出和重新创建图表后保持不变。
+- 节点移动后边不能穿过节点；无效人工路径必须被修复或确定性地重新路由。
+- 在双渲染器一致性全部通过前，Capabilities 应报告线段拖动不可用，而不是只声明 SVG 支持。
+- 默认图表保持静态：缩放、平移、框选、节点拖动、线段拖动、端口连线和结构编辑只有在宿主显式配置后才启用。
+
+## 12G：Mindmap 贝塞尔曲线
+
+- Mindmap 父子连线默认使用 `routing: 'curved'`；Flow、Swimlane、Architecture 继续默认使用正交路由。
+- `curved` 在 Canvas 与 SVG 中都渲染为一段真实三次贝塞尔曲线，不再是四点折线。
+- `diagram.curveTension` 和单边 `curveTension` 支持 `0.2` 到 `0.8`，默认值为 `0.4`。
+- 标签位于贝塞尔中点，箭头根据终点切线定向；共享 Scene Graph 通过曲线采样保持 Canvas/SVG 命中一致。
+- 曲线穿过其他节点时，确定性回退到具备避障能力的正交路由。
+- 显式 `waypoints` 优先并继续使用人工折线。暂不提供贝塞尔控制点拖动；节点移动后自动重新计算曲线。
+
+## 验收
+
+- `npm run agent:check` 通过，公开图表类型为 18 个，业务 Schema 为 10 个。
+- Architecture 在 SVG 和 Canvas 下均能显示层、边界、节点和依赖边。
+- Mindmap 能校验父引用与循环，生成稳定父子边，并确定性渲染 tree/radial 布局。
+- 既有 Flow、Swimlane 测试和预览不回归。
+- Iteration 12F 只有在 Canvas 与 SVG 具备一致的线段编辑能力后才通过验收。
+- Iteration 12G 只有在 Canvas、浏览器 SVG 与 Headless SVG 都输出真实三次贝塞尔路径，并保持默认静态交互时才通过验收。