@taylorwong/ichartjs 2.0.5 → 2.0.7

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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.
+- Added shared page-level preferences with localStorage persistence and Agent JSON patch support through the Preferences API and Playground settings page.
+- Synchronized Runtime, Playground, package metadata, release-pinned installation guidance, and roadmap status for the `v2.0.6` release.
+
 ## 2.0.5 - 2026-09-18
 
 - Hardened JSON, SVG, PNG, and JPEG export contracts with deterministic type errors, JSON output representations, and an explicit optional Node `canvas` path through `exportAsync()`.

package/README.md

@@ -31,6 +31,7 @@ getCapabilities
 | Coding Agent integration | [`docs/agent/coding-agent-integration.md`](docs/agent/coding-agent-integration.md) |
 | Frontend integration | [`docs/agent/frontend-integration.md`](docs/agent/frontend-integration.md) |
 | Visual style and themes | [`docs/agent/theme-guide.md`](docs/agent/theme-guide.md) |
+| Chart and page preferences | [`docs/agent/theme-guide.md`](docs/agent/theme-guide.md#chart-and-page-preferences) |
 | Official Agent Skill for Codex and WorkBuddy | [`skills/ichartjs/SKILL.md`](skills/ichartjs/SKILL.md) |
 
 ### Install
@@ -39,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.5`.
+As a fallback for environments without npm access, install directly from GitHub: `npm install github:wanghetommy/ichartjs#v2.0.7`.
 
 ### Optional Agent Skill
 
@@ -49,13 +50,19 @@ The runtime API remains the source of truth; the Skill only teaches and orchestr
 https://github.com/wanghetommy/ichartjs/tree/master/skills/ichartjs
 ```
 
-From a repository checkout, install it into Codex with:
+Install the latest Skill with the standard Agent Skills CLI:
 
 ```bash
-cp -R skills/ichartjs "${CODEX_HOME:-$HOME/.codex}/skills/"
+npx skills add wanghetommy/ichartjs --skill ichartjs
 ```
 
-WorkBuddy users can import or register the same `skills/ichartjs` folder through the host's Skill interface. Package consumers can copy it from `node_modules/@taylorwong/ichartjs/skills/ichartjs` into their Agent host's Skill directory. After installation, invoke it as `$ichartjs` when the host supports named Skill invocation, or select the `ichartjs` Skill in the host UI.
+For a non-interactive global Codex installation:
+
+```bash
+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.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

@@ -27,12 +27,16 @@ npm install
 npm run playground
 ```
 
-The same official Skill can be imported by Codex, WorkBuddy, and other Agent Skills-compatible hosts from `skills/ichartjs`. Install it into Codex from a repository checkout with:
+Install the official Skill with the standard Agent Skills CLI:
 
 ```bash
-cp -R skills/ichartjs "${CODEX_HOME:-$HOME/.codex}/skills/"
+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.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`.
+
 ## Agent Request Pattern
 
 A useful request is explicit about data, intent, output, and acceptance:

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

@@ -0,0 +1,44 @@
+# Iteration 11 — Chart Preferences and Agent Adjustments
+
+Iteration 11A–11D adds a small, allowlisted preference layer for visual configuration. It does not add chart types or change data encoding behavior. The same contract powers per-chart settings, page-wide defaults, browser persistence, and Agent conversational adjustments.
+
+## 11A — Preferences Contract
+
+- Add `createPreferencesStore()`, `normalizePreferences()`, `mergePreferences()`, and `validatePreferences()`.
+- Keep the public fields limited to theme mode/preset/palette, typography scale, density, legend/labels/grid visibility, branding, and motion.
+- Resolve precedence as defaults → global page preferences → chart preferences → temporary Agent patch.
+- Keep preference state separate from business data and provide structured change events with `source`, `scope`, and persistence status.
+- Fall back to memory in Node/SSR and support browser `localStorage` or a host storage adapter explicitly.
+
+## 11B — Per-Chart Settings
+
+- Add `Chart#getPreferences()`, `Chart#setPreferences()`, and `Chart#resetPreferences()`.
+- Add the optional `mountChartSettings()` browser UI with an accessible settings button in the chart container's top-right corner.
+- Limit the per-chart menu to high-frequency theme, palette, font-scale, and capability-supported visibility controls; keep advanced and global controls on a dedicated page outside the chart popover.
+- Keep the settings DOM outside SVG/Canvas so it is not included in PNG/SVG exports.
+- Apply changes without recreating the Chart instance and preserve explicit chart colors/background/padding overrides.
+
+## 11C — Global Page Configuration
+
+- Allow one `PreferencesStore` to be shared by all charts on a page.
+- Support global and chart scopes with chart-specific inheritance and reset behavior.
+- Persist only the versioned preference document, never business rows or credentials.
+- Expose the effective preferences in `chart.getState()` and the capabilities manifest.
+
+## 11D — Agent and Playground Integration
+
+- Let an Agent apply a validated visual patch with `chart.setPreferences(patch, { source: 'agent' })`.
+- Keep Agent updates and UI updates on the same `preferenceschange` event path.
+- Add `preferences-lab.html` and settings controls to the Complete Gallery for browser acceptance.
+- Document conversational examples such as “use dashboard style, status colors, larger labels, and hide the grid.”
+
+## Acceptance
+
+- `npm run agent:check` passes.
+- Preferences work in headless memory mode and browser `localStorage` mode.
+- Global updates reach all charts sharing a store; chart updates remain isolated.
+- Invalid preference patches return structured validation details and do not mutate state.
+- Preview pages:
+  - `http://localhost:3000/playground/preferences-lab.html`
+  - `http://localhost:3000/playground/project-gallery.html`
+- No new chart type, data transform, or export format is introduced.

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.4` is published and `v2.0.5` is prepared as the Iteration 10A export-contract and usage-guidance patch release. 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
 
@@ -12,7 +12,9 @@
 - Iteration 7 local runtime and browser acceptance are complete for foundational composition, Heatmap, and Radar; physical-device checks remain host integration evidence.
 - Iteration 8A–8D is complete and accepted in automated tests, Chromium, Firefox 144, WebKit 26, native Safari 26.6.2, and a 390 px touch viewport. Physical iOS/Android and representative release-host measurements remain post-release host/device follow-up. No new public chart type was introduced.
 - 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 is implemented on `develop`: 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 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
@@ -248,6 +250,29 @@ The following remain deferred beyond this roadmap baseline:
 
 They should only be scheduled after the core runtime, diagram model, and project analytics contracts are stable.
 
+## Iteration 11 — Chart Preferences and Agent Adjustments
+
+### Goal
+
+Allow users and Agents to adjust a chart's visual presentation after creation through one small, auditable contract. The detailed 11A–11D plan is in `docs/agent/development/iteration-11.md`.
+
+### Tasks
+
+1. Add allowlisted preferences for theme, typography scale, density, components, branding, and motion.
+2. Support chart-scoped and page-global inheritance through an explicit Preferences Store.
+3. Persist only versioned preference state through browser `localStorage` or a host adapter.
+4. Add an optional accessible settings button outside the SVG/Canvas export surface.
+5. Let Agents apply natural-language intent as a validated preference patch with source and scope metadata.
+6. Add Playground and bilingual guidance for UI and Agent adjustment workflows.
+
+### Verification
+
+- Global changes reach all charts sharing a store; chart overrides remain isolated.
+- UI, Agent, and host code use the same `preferenceschange` event path.
+- Invalid patches do not mutate preferences or business data.
+- Settings UI is excluded from SVG, PNG, and JSON chart exports.
+- `npm run agent:check`, `git diff --check`, and `http://localhost:3000/playground/preferences-lab.html` acceptance pass.
+
 ## Recommended Execution Order
 
 1. Finish Iteration 3 browser acceptance.
@@ -257,4 +282,5 @@ They should only be scheduled after the core runtime, diagram model, and project
 5. Execute Iteration 7 foundations before considering additional specialized chart types.
 6. Execute Iteration 8 to complete existing chart behavior, Agent adaptation, and the 2.0 release gates.
 7. Execute Iteration 9 to standardize adaptive visual styling without expanding chart count.
-8. Re-evaluate geographic and 3D scope only after usage data confirms demand.
+8. Execute Iteration 11 to add post-creation chart and page preferences without expanding chart count.
+9. Re-evaluate geographic and 3D scope only after usage data confirms demand.

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.5`.
+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

@@ -57,3 +57,66 @@ Built-in modes expose text, muted text, axis, grid, focus, selection, missing-va
 
 Preview and acceptance: `http://localhost:3000/playground/theme-gallery.html`.
 
+## Chart and Page Preferences
+
+Use preferences for visual adjustments that a user or Agent may change after the chart has been created. Keep business data, encodings, and chart selection outside this surface.
+
+```js
+import { createChart, createPreferencesStore, mountChartSettings } from '@taylorwong/ichartjs';
+
+const pagePreferences = createPreferencesStore({
+  storage: 'localStorage',
+  storageKey: 'my-app:chart-preferences'
+});
+const chart = createChart({
+  chartId: 'revenue',
+  container: '#revenue',
+  type: 'line',
+  data: { values: rows },
+  preferences: pagePreferences
+});
+const settings = mountChartSettings(chart, {
+  locale: 'en',
+  placement: 'auto',
+  preferredPlacements: ['right', 'top', 'bottom']
+});
+
+// The same operation can come from an Agent conversation.
+chart.setPreferences({
+  theme: { preset: 'dashboard', palette: 'status' },
+  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

@@ -35,6 +35,22 @@ The Skill is not a second renderer or service. A Skill-enabled Agent still needs
 
 JSON is the machine-readable source of truth. SVG and PNG/JPEG are presentation artifacts. Code is the integration artifact. An interactive page is the product artifact.
 
+## Visual Preferences: UI and Agent
+
+For post-creation visual adjustments, share a `createPreferencesStore()` with the page's charts. Use `storage: 'localStorage'` only in a browser when the host wants preferences to survive refreshes. `mountChartSettings(chart)` adds an optional accessible quick-settings button outside the export surface; keep the full page-level settings surface as a separate host route.
+
+The host or Agent can use the same patch contract:
+
+```js
+chart.setPreferences({
+  theme: { preset: 'dashboard', palette: 'status' },
+  typography: { scale: 1.15 },
+  components: { grid: false }
+}, { source: 'agent' });
+```
+
+Keep the quick menu limited to theme, palette, font scale, and capability-supported visibility toggles. Use `scope: 'global'` for a page-wide update, the default chart scope for a single chart, and `chart.getState().preferences` for an auditable effective result. Preview both layers at `http://localhost:3000/playground/project-gallery.html` and `http://localhost:3000/playground/preferences-lab.html`.
+
 ## Scenario 1: Integrate into a Web Project
 
 Install the runtime in the host application:
@@ -90,7 +106,28 @@ For a consumer project, return that project's own development URL.
 
 ## Scenario 3: Use the Official Skill
 
-Install or select `skills/ichartjs` in Codex, WorkBuddy, or another Agent Skills-compatible host. Then ask:
+Install the latest Skill with the standard Agent Skills CLI:
+
+```bash
+npx skills add wanghetommy/ichartjs --skill ichartjs
+```
+
+Install globally for Codex without prompts:
+
+```bash
+npx skills add wanghetommy/ichartjs --skill ichartjs --agent codex --global --yes
+```
+
+For reproducible installation, pin the released Skill directory:
+
+```bash
+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 GitHub directory through the host's Skill interface. Do not assume that `--agent workbuddy` exists unless the installed Skills CLI lists that adapter. A manual copy from `node_modules/@taylorwong/ichartjs/skills/ichartjs` remains a fallback for hosts with custom Skill directories.
+
+After installation or selection, ask:
 
 ```text
 Use the iChart.js Skill. Read this dataset, create a project Burndown,
@@ -122,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

@@ -16,12 +16,16 @@ npm install @taylorwong/ichartjs@^2
 
 npm Registry 中无作用域的 `ichartjs` 是安全占位包，并非本项目。正式包名是 `@taylorwong/ichartjs`，优先从 npm 安装。
 
-Codex、WorkBuddy 和其他兼容 Agent Skills 的宿主可共同使用 `skills/ichartjs`。从仓库检出目录安装到 Codex：
+使用标准 Agent Skills CLI 安装官方 Skill：
 
 ```bash
-cp -R skills/ichartjs "${CODEX_HOME:-$HOME/.codex}/skills/"
+npx skills add wanghetommy/ichartjs --skill ichartjs
 ```
 
+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`。
+
 推荐请求：
 
 ```text