@taylorwong/ichartjs 2.0.1

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

@@ -0,0 +1,116 @@
+# Iteration 8 — Chart Completeness and Agent Experience
+
+## Goal
+
+Turn the existing chart catalog into a dependable, commonly complete, and Agent-native product surface. Iteration 8 prioritizes finishing expected chart behavior, making capabilities machine-discoverable and outputs explainable, then closing browser, packaging, performance, and 2.0 release gates.
+
+## Current Delivery
+
+Iteration 8A–8D is complete. The runtime exposes per-chart capability profiles, deterministic Agent planning and explanation, richer data inspection and diagnostics, common chart presentation behavior, corrected chart geometry, dedicated interaction/accessibility/performance labs, and a maintained full Gallery. Automated, Chromium, Firefox, WebKit, native Safari, 390 px responsive, lifecycle, and local performance acceptance passed. Physical iOS/Android checks remain a recorded host/device follow-up. See `docs/agent/development/iteration-8-acceptance.md`.
+
+## Scope Policy
+
+- Do not add public chart types in Iteration 8.
+- Improve the existing 16 public types: Line, Area, Bar, Column, Pie, Scatter, Funnel, Gauge, Heatmap, Radar, Gantt, Timeline, Milestone, Burndown, Flow, and Swimlane.
+- A common feature is required only where its semantics are meaningful. Unsupported behavior must be declared explicitly rather than silently ignored.
+- Prefer reusable runtime, interaction, transform, formatting, and accessibility contracts over chart-specific branches.
+- Preserve deterministic output, stable source record IDs, JSON-safe Specs, and SVG/Canvas semantic parity.
+- Agent recommendations must remain explainable suggestions, not hidden decisions or fabricated data.
+
+## 8A — Existing Chart Feature Completeness
+
+1. Create a chart-by-feature matrix covering title/subtitle, legend, axes, grid, tooltip, labels, formatters, theme, responsive sizing, animation, reduced motion, selection, zoom, pan, keyboard access, empty states, invalid-data states, export, and renderer support.
+2. Audit every public chart type against the matrix and classify each cell as supported, not applicable, degraded, or missing.
+3. Complete common presentation behavior: number/date/category formatting, label placement and collision policy, legend visibility and series toggling, axis domains and ticks, theme tokens, and deterministic layout defaults.
+4. Complete common state behavior: loading, empty data, partial data, invalid values, no-result filters, disabled series, and structured warning display.
+5. Complete chart-family behavior where applicable: positive/negative stacking, percentage totals, dual axes, pie zero totals, heatmap missing cells, radar domain handling, project schedule overlays, and diagram group/port hit policies.
+6. Define large-data degradation rules for marks, labels, tooltips, animation, and renderer selection without changing source data.
+7. Add focused regression tests for every capability newly marked supported.
+
+### Checkpoint
+
+- Every public chart has a reviewed feature profile and no declared capability is a placeholder.
+- Common formatting, legend, tooltip, selection, responsive, empty-state, and export behavior is consistent where applicable.
+- Missing or unsupported options produce structured diagnostics instead of silent no-ops.
+
+## 8B — Interaction, Renderer, and Runtime Correctness
+
+1. Systematically verify hover, tooltip, click, selection, wheel zoom, pinch zoom, zoom out, pan, drag, keyboard traversal, keyboard editing, and port connection across applicable chart families.
+2. Define interaction conflict rules, including drag versus pan, click versus collapse, selection versus background hits, and touch gesture cancellation.
+3. Align SVG and Canvas geometry, hit testing, semantic data references, focus order, and export-visible state.
+4. Complete accessibility behavior: chart summaries, roles and labels, keyboard-only operation, focus visibility, reduced motion, contrast themes, and meaningful fallback descriptions.
+5. Replace ad hoc development cache query keys with one coherent module-version and asset-cache strategy.
+6. Audit public exports, module boundaries, circular dependencies, package entry points, direct browser loading, and destroy-time cleanup.
+7. Add browser regression fixtures for previously observed Gallery and Diagram Editor failures.
+
+### Checkpoint
+
+- Zoom can both enter and return to the full domain, including from boundary windows.
+- Background clicks never trigger unrelated chart or diagram actions.
+- SVG and Canvas expose equivalent record identity and interaction results.
+- Direct HTTP module loading does not depend on manually changing import query strings.
+- Repeated create/destroy cycles do not retain listeners, observers, tooltips, or plugin state.
+
+## 8C — Agent-Native Planning and Diagnostics
+
+1. Expand the machine-readable capability manifest from global lists to per-chart profiles with supported data shapes, required encodings, compatible interactions, renderer constraints, defaults, limits, and export behavior.
+2. Define a versioned Agent planning result that includes recommended chart, alternatives, confidence, reasons, required fields, assumptions, warnings, unsupported requests, and safe next actions.
+3. Improve data inspection so an Agent can identify field roles, units, cardinality, temporal coverage, missingness, invalid values, and ambiguity before producing a Spec.
+4. Improve Spec validation with stable error codes, precise JSON paths, expected values, actionable repair suggestions, and separation of errors, warnings, and normalizations.
+5. Add deterministic chart description and explanation output covering selected chart semantics, encodings, transforms, filters, derived values, data lineage, assumptions, warnings, and accessibility summary.
+6. Add option-level discoverability so an Agent can ask what a chart supports without loading implementation files or guessing configuration names.
+7. Add compact, intent-oriented recipes for comparison, trend, composition, distribution, relationship, matrix, multidimensional profile, schedule, release, risk, workflow, and responsibility scenarios.
+8. Add negative recipes and guardrails for misleading choices, including excessive pie categories, mixed-unit radar without domains, truncated axes, invalid stacking, insufficient forecasting data, and unsupported interactions.
+9. Add Agent contract tests proving capability discovery, recommendation, validation, normalization, explanation, and recipe output are deterministic and mutually consistent.
+
+### Checkpoint
+
+- An Agent can discover, plan, validate, render, explain, and self-check a chart through public contracts alone.
+- Capability profiles match actual runtime behavior for every chart and renderer.
+- Recommendations explain tradeoffs and never invent missing fields, units, dates, domains, or business meaning.
+- Diagnostics are stable enough for automated repair loops and concise enough for tool responses.
+
+## 8D — Compatibility, Performance, and 2.0 Release Closure
+
+1. Run the full Gallery and editor acceptance suite in current Chrome, Safari, and Firefox, recording browser-specific limitations.
+2. Verify responsive layouts at representative 390 px, 768 px, and desktop widths, then perform physical-device touch checks on iOS and Android.
+3. Establish repeatable performance budgets for representative Line, Heatmap, Gantt, and Diagram datasets, including initial render, interaction latency, memory, and export.
+4. Verify lifecycle stability under repeated update, resize, renderer switch, plugin enable/disable, and destroy operations.
+5. Tighten TypeScript declarations for public Specs, chart-specific options, capability profiles, planning results, diagnostics, state, events, and exports.
+6. Complete 2.0 adoption guidance, API reference, bilingual Agent documentation, versioned manifests, visual baselines, changelog, and release checklist. A 1.x-to-2.0 migration guide is intentionally out of scope because 2.0 is a new Agent-first product line rather than a compatible upgrade.
+7. Run final package-consumer smoke tests for ESM import, browser module import, representative Agent workflows, and all exact preview URLs.
+
+## Verification
+
+- `npm run agent:check` and `git diff --check` pass.
+- The chart-by-feature matrix is backed by automated or recorded browser evidence.
+- All 16 chart types render in the full Gallery with no uncaught errors.
+- Capability, recommendation, validation, runtime state, documentation, and TypeScript declarations agree.
+- SVG and Canvas parity is verified for supported common features and semantic record references.
+- Chrome, Safari, Firefox, mobile viewport, physical-device, performance, and lifecycle gates have explicit results.
+- No new public chart type is introduced during Iteration 8.
+
+## Preview and Acceptance
+
+- The target Playground information architecture, page responsibilities, migration decisions, and delivery order are defined in `docs/agent/development/playground-plan.md`.
+- Full chart Gallery: `http://localhost:3000/playground/project-gallery.html`
+- Foundational chart Gallery: `http://localhost:3000/playground/foundational-gallery.html`
+- Project intelligence: `http://localhost:3000/playground/project-intelligence.html`
+- Diagram editor: `http://localhost:3000/playground/diagram-editor.html`
+- Business editing: `http://localhost:3000/playground/editing.html`
+- Start the no-cache server from the repository root with `npm run playground`.
+- Every phase delivery report must state changed capabilities, exact preview URLs, automated results, manual acceptance steps, and deferred environment checks.
+
+## Deliverables
+
+- Audited chart-by-feature capability matrix for all 16 public chart types.
+- Completed common chart behavior and chart-family-specific gap fixes.
+- Per-chart machine-readable capability and option metadata.
+- Agent planning, diagnostics, explanation, and self-check contracts.
+- Expanded positive and negative Agent recipes with deterministic contract tests.
+- Browser, mobile, accessibility, performance, lifecycle, packaging, and release acceptance records.
+- Updated runtime, TypeScript declarations, manifests, bilingual documentation, demos, tests, and 2.0 release checklist.
+
+## Completion Definition
+
+Iteration 8 is complete when all existing chart types provide their applicable common features reliably; unsupported behavior is explicitly discoverable; an Agent can select, configure, validate, render, explain, and verify charts without reading source code; SVG and Canvas semantics are consistent; browser, mobile, accessibility, performance, lifecycle, packaging, and preview gates are recorded; and the repository is ready for a final iChart.js 2.0 release decision without adding new chart types.

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

@@ -0,0 +1,44 @@
+# Iteration 9 — Visual Style System and Adaptive Theming
+
+Iteration 9 remains part of the `2.0.0` source line. It adds no public chart type and no external runtime dependency.
+
+## Goal
+
+Provide a small, consistent built-in visual language that Agents can select by semantic intent, users can override, and both SVG and Canvas can render without separate theme implementations.
+
+## 9A — Tokens and Presets
+
+- Add shared color, typography, layout, mark, focus, selection, missing-value, and status tokens.
+- Add `analysis`, `dashboard`, `report`, `presentation`, `project`, and `diagram` presets.
+- Add categorical, sequential, diverging, and status palettes.
+- Preserve custom `colors`, `background`, and `padding` overrides.
+
+## 9B — Adaptive Resolution
+
+- Resolve `auto`, `light`, `dark`, and `contrast` modes.
+- Select presets by chart family and host context.
+- Select palettes from data semantics.
+- Expose deterministic reasons and warnings through planning and explanation APIs.
+- Follow host color-scheme changes when mode is automatic.
+
+## 9C — Runtime and Renderer Integration
+
+- Add `planStyle()`, `resolveTheme()`, `validateThemeContrast()`, `Chart#setTheme()`, and `Chart#getTheme()`.
+- Apply tokens to generic charts, Heatmap, Radar, project views, diagrams, tooltips, axes, labels, legends, and empty states.
+- Keep SVG and Canvas on the same resolved Spec and Scene Graph.
+
+## 9D — Agent Guidance and Acceptance
+
+- Add English and Chinese theme guides.
+- Extend README, quickstarts, Skill guidance, capabilities, and TypeScript declarations.
+- Add the Theme Gallery and controls to the Complete Gallery.
+- Add unit, contract, contrast, and switching regression tests.
+
+## Acceptance
+
+- `npm run agent:check` passes without changing package version `2.0.0`.
+- Built-in modes pass the declared contrast checks.
+- Automatic style recommendations are deterministic and explainable.
+- User overrides win and live switching does not recreate charts.
+- Theme behavior is visually inspectable at `http://localhost:3000/playground/theme-gallery.html`.
+

package/docs/agent/development/playground-plan.md

@@ -0,0 +1,143 @@
+# Playground Information Architecture
+
+## Purpose
+
+The `playground/` directory is the browser-visible product and acceptance surface for iChart.js. It must let a human reviewer browse capabilities, let an Agent integration developer exercise public contracts, and let maintainers reproduce interaction and release failures without reading implementation code.
+
+The Playground is not a collection of iteration snapshots. Active pages are organized by stable user task; historical iteration pages should be retired after their unique coverage moves to a maintained page.
+
+## Page Classes
+
+### Entry and Catalog
+
+| Page | Role | Required content |
+| --- | --- | --- |
+| `index.html` | Unified Playground home and acceptance entry point. | Runtime version, available chart count, links grouped by catalog/workbench/lab, server instructions, page readiness status, and exact acceptance URLs. |
+| `project-gallery.html` | Canonical full catalog and first visual smoke test for all 16 public chart types. Keep this URL stable despite the historical filename. | Search and category filters, every public chart type, SVG/Canvas coverage, theme and viewport controls, enlarged preview, visible initialization status, Spec inspection, diagnostics, and links to specialized pages. |
+| `foundational-gallery.html` | Focused regression gallery for reusable foundational features introduced in Iteration 7. | Grouped/stacked/percent charts, Donut, Combo, Histogram/Bin, Heatmap, Radar, renderer coverage, source record identity, and expected warnings. |
+
+### Agent and Business Workbenches
+
+| Page | Role | Required content |
+| --- | --- | --- |
+| `agent-workbench.html` | Primary Agent integration workbench and Iteration 8 Agent acceptance page. | Editable JSON data and intent, `inspectData`, per-chart capabilities, recommendation and alternatives, planning reasons/confidence, generated or editable Spec, validation/repair diagnostics, render result, chart explanation, normalized state, data lineage, and export. |
+| `project-intelligence.html` | Project analytics and linked-view workbench. | Schedule assumptions/warnings, critical path and slack, baseline/actual variance, capacity, velocity, release forecast, risk, issue aging, linked filters, linked selection, and derived output inspection. |
+| `editing.html` | Safe business-data editing workflow. | Schema inspection, typed command, deterministic preview, affected records, warnings, confirmation boundary, commit, undo/redo, revision, audit metadata, and explicit local-only persistence notice. |
+| `diagram-editor.html` | Diagram authoring and editing workbench. | Node/group/lane/port editing, pointer and keyboard connections, routing, multi-select, clipboard, collapse, validation, normalized DiagramSpec, history, and visible interaction state. |
+
+### Acceptance Labs
+
+| Page | Role | Required content |
+| --- | --- | --- |
+| `interaction-lab.html` | Reproduce and verify common interaction behavior independently of Gallery layout. | Hover, tooltip, click, selection, wheel/pinch zoom in and out, pan, drag, keyboard traversal, touch cancellation, event/state log, reset controls, and boundary cases. |
+| `accessibility-lab.html` | Keyboard and semantic acceptance for all applicable chart families. | Focus order, accessible names and summaries, keyboard-only tasks, contrast themes, reduced motion, missing-data descriptions, SVG/Canvas fallback differences, and a visible checklist. |
+| `performance-lab.html` | Repeatable local performance and lifecycle measurements. | Deterministic dataset sizes, renderer switch, render/update/resize/export timing, mark counts, repeated create/destroy cycles, listener/observer status, memory notes, and downloadable result JSON. |
+
+## Existing Page Decisions
+
+| Current page | Decision |
+| --- | --- |
+| `project-gallery.html` | Keep as the stable full-gallery URL and improve it; do not rename during 2.0 release closure. |
+| `foundational-gallery.html` | Keep as a focused foundational regression page; avoid adding unrelated future features. |
+| `project-intelligence.html` | Keep as the project analytics workbench. |
+| `editing.html` | Keep as the business editing workbench. |
+| `diagram-editor.html` | Keep as the diagram editing workbench. |
+| `iteration-2.html` | Migrate any unique examples into the full Gallery or interaction lab, then move out of the active Playground or replace it with a compatibility link. Do not continue extending it. |
+
+## Responsibilities and Boundaries
+
+- `project-gallery.html` answers: "What chart types exist, and do they render?"
+- `foundational-gallery.html` answers: "Do the shared composition and analysis foundations still work?"
+- `agent-workbench.html` answers: "Can an Agent discover, choose, configure, validate, explain, and verify a chart?"
+- Domain workbenches answer: "Can a user complete this business workflow?"
+- Acceptance labs answer: "Does one cross-cutting quality contract work across chart families?"
+- A page must not duplicate another page's full dataset and controls merely to provide navigation; link to the owning page instead.
+- Release-critical behavior must not be demonstrated only in an old iteration page.
+
+## Shared Page Contract
+
+Every active HTML page must:
+
+1. Load directly over HTTP without first visiting another page.
+2. Import public APIs through the single `playground/runtime.mjs` browser entry; per-page ad hoc cache-busting query strings are not part of the final contract.
+3. Include a consistent header with page purpose, runtime version, Home link, and related-page links.
+4. Show initialization, ready, warning, and error states in the page instead of relying on the console.
+5. Provide deterministic fixtures with stable IDs and no required external network requests.
+6. Provide a visible reset action for mutable interactions.
+7. State the exact actions and expected results needed for manual acceptance.
+8. Expose the relevant Spec, normalized state, diagnostics, events, or measurement output.
+9. Work at 390 px, 768 px, and desktop widths, with keyboard-visible focus and reduced-motion support.
+10. Destroy charts and listeners when examples are replaced or the page is unloaded.
+
+## Shared Implementation Direction
+
+- Move repeated styles, navigation, status badges, fixture data, and chart-card setup into small shared Playground modules rather than copying them between pages.
+- Serve Playground assets through `npm run playground`, which sends `Cache-Control: no-store`; keep HTML pages and source-module imports free of cache-busting query keys.
+- Keep page-specific scenarios declarative and JSON-friendly so they can also drive automated browser checks.
+- Support deterministic query parameters where useful, such as `renderer`, `theme`, `case`, `size`, and `seed`; ignore unknown parameters with a visible warning.
+- Assign every scenario a stable ID so browser tests, screenshots, Agent explanations, and acceptance records refer to the same case.
+- Keep test instrumentation optional and visually separated from the chart itself.
+- The full Gallery remains lightweight; expensive stress datasets and lifecycle loops belong only in `performance-lab.html`.
+
+## Navigation Model
+
+```text
+index.html
+├── project-gallery.html
+│   └── foundational-gallery.html
+├── agent-workbench.html
+├── project-intelligence.html
+├── editing.html
+├── diagram-editor.html
+├── interaction-lab.html
+├── accessibility-lab.html
+└── performance-lab.html
+```
+
+All active pages link back to `index.html`. The full Gallery links to relevant focused pages, and focused pages link back to the full Gallery when they display chart output.
+
+## Iteration 8 Delivery Order
+
+### 8A — Catalog Foundation
+
+1. Add `index.html` and shared navigation/status utilities.
+2. Add the chart-by-feature matrix to the full Gallery or link it from the Gallery.
+3. Enhance the full Gallery with renderer, theme, viewport, diagnostics, and deterministic scenario controls.
+4. Migrate unique `iteration-2.html` coverage and freeze the historical page.
+
+### 8B — Interaction and Accessibility Labs
+
+1. Add `interaction-lab.html` with observable events and state.
+2. Add `accessibility-lab.html` with keyboard and semantic checklists.
+3. Convert previously fixed Gallery and Diagram Editor bugs into named regression scenarios.
+
+### 8C — Agent Workbench
+
+1. Add `agent-workbench.html` around the public capability, inspection, planning, validation, rendering, explanation, and export contracts.
+2. Ensure every diagnostic is visible and copyable as structured JSON.
+3. Add representative successful, ambiguous, invalid, and unsupported Agent scenarios.
+
+### 8D — Performance and Release Hub
+
+1. Add `performance-lab.html` with reproducible datasets and downloadable results.
+2. Make `index.html` show automated and manual acceptance status for every active page.
+3. Synchronize README, Agent docs, capability manifests, and release records with exact URLs.
+
+## Exact Target URLs
+
+Start the cache-safe preview server with `npm run playground` before opening these URLs.
+
+- Home: `http://localhost:3000/playground/index.html`
+- Full Gallery: `http://localhost:3000/playground/project-gallery.html`
+- Foundational Gallery: `http://localhost:3000/playground/foundational-gallery.html`
+- Agent Workbench: `http://localhost:3000/playground/agent-workbench.html`
+- Project Intelligence: `http://localhost:3000/playground/project-intelligence.html`
+- Business Editing: `http://localhost:3000/playground/editing.html`
+- Diagram Editor: `http://localhost:3000/playground/diagram-editor.html`
+- Interaction Lab: `http://localhost:3000/playground/interaction-lab.html`
+- Accessibility Lab: `http://localhost:3000/playground/accessibility-lab.html`
+- Performance Lab: `http://localhost:3000/playground/performance-lab.html`
+
+## Completion Definition
+
+The Playground plan is complete when every active page has one clear owner responsibility, all stable URLs are reachable from the Home page, the full catalog and specialized workflows do not conflict, Agent behavior is independently verifiable, cross-cutting quality has dedicated labs, historical iteration pages are no longer release dependencies, and every Iteration 8 delivery report identifies an exact URL and reproducible acceptance procedure.

package/docs/agent/development/prompt-contract.md

@@ -0,0 +1,22 @@
+# Agent Prompt Contract
+
+## Code and Documentation Contract
+
+- Every active source module under `src/` must begin with a short file-level module comment.
+- The comment states the module responsibility and its important public or behavioral constraints.
+- Public APIs and complex algorithms may add focused JSDoc; line-by-line comments are not required.
+- Agent-facing documentation must describe behavior and contracts, not duplicate implementation details.
+- When a module responsibility changes, update its file-level comment in the same change.
+
+When generating a chart, an Agent must:
+
+1. Inspect the input data.
+2. Identify dimensions and measures.
+3. Match the chart type to the user intent.
+4. Generate a JSON-serializable Chart Spec.
+5. Validate the Spec before rendering.
+6. Report missing or invalid values.
+7. Use `describe()` after rendering.
+8. Treat derived insights as calculations, not source facts.
+9. Preserve the user's data and avoid mutating input rows.
+10. Prefer an accessible renderer and non-color encodings when requested.

package/docs/agent/development/rc-1-acceptance.md

@@ -0,0 +1,43 @@
+# iChart.js 2.0.0-rc.1 Acceptance Report
+
+Date: 2026-09-14
+
+## Runtime gates
+
+| Gate | Result | Evidence |
+| --- | --- | --- |
+| Unit tests | Pass | `npm test`, 33/33 tests |
+| Syntax checks | Pass | `npm run check` |
+| Diff whitespace | Pass | `git diff --check` |
+| Combined RC command | Pass | `npm run rc:check` |
+| Headless JSON export | Pass | `Chart.export({ type: 'json' })` |
+| Headless raster export | Explicit unsupported result | `HEADLESS_EXPORT_UNSUPPORTED` |
+| Guarded edit commit | Pass | Preview, confirmation, revision and audit tests |
+| Undo/redo | Pass | History and stale-history tests |
+| Recipe validation | Pass | `validateRecipe()` regression coverage |
+
+## HTTP demo gates
+
+- `http://localhost:3000/playground/editing` loads over HTTP.
+- Preview shows deterministic before/after values and affected records.
+- Commit requires the exact preview and confirmation.
+- Commit updates local chart state and revision.
+- Undo and redo controls become available after commit.
+- Demo states clearly that external persistence is not performed.
+- `http://127.0.0.1:3000/playground/diagram-editor.html` exposes Iteration 5 group lifecycle, group resize, pointer/keyboard port connection, and shared history behavior.
+- `http://127.0.0.1:3000/playground/project-gallery.html` exposes the Iteration 5 Flow model and links to the editor.
+
+## Deferred host/device gates
+
+These are not claimed as complete by the local runtime:
+
+- Physical-device touch testing across iOS and Android.
+- Full browser matrix testing outside the current in-app browser.
+- Host authentication, authorization, approval, and durable persistence.
+- Durable server-side audit storage.
+- Large-data performance budgets on representative hardware.
+- Full ARIA audit and keyboard-only editing review.
+
+## Release decision
+
+The repository is functionally ready for `2.0.0-rc.1` review. Do not label it a final production release until the deferred host/device gates are accepted by the integrating application.

package/docs/agent/development/roadmap.md

@@ -0,0 +1,259 @@
+# iChart.js 2.0 Roadmap
+
+> Roadmap baseline: 2026-09-14. Geographic charts and 3D rendering remain out of scope until explicitly reintroduced.
+
+## Current Status
+
+- Iteration 1: Agent-first core, Chart Spec, Scene Graph, Canvas/SVG renderers, basic chart types.
+- Iteration 2: Data transforms, scales, multi-series axes, plugins, responsive behavior, touch basics, and chart gallery foundations.
+- Iteration 3: Project management and process visualization foundations, including Gantt, timeline, milestone, burndown, flow, and swimlane.
+- Iteration 3 core functionality is complete; browser/mobile gesture verification remains a release acceptance item.
+- Iteration 6 project intelligence local runtime and browser acceptance are complete.
+- 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 implements the lightweight visual style system, adaptive theme planning, runtime switching, renderer integration, and bilingual Agent guidance without adding a chart type or changing version `2.0.0`.
+- Final `2.0.0` readiness is tracked in `docs/agent/development/2.0-release-readiness.md`; strict TypeScript, Node.js 18/20/22, GitHub Actions, package-consumer, browser, performance, and lifecycle checks pass. Only the final commit, `master` cutover, tag, and GitHub Release remain. npm publication is tracked separately.
+
+## Iteration 4 — Agent Data Contract and Business Editing
+
+### Current status
+
+4A–4E local runtime implementation is complete and included in `2.0.0`. See `docs/agent/development/rc-1-acceptance.md` for the historical RC evidence and `docs/agent/development/2.0-release-readiness.md` for final acceptance.
+
+### Goal
+
+Make the runtime reliable for production Agent integrations and allow safe, explainable business-data edits. The complete task list is in `docs/agent/development/iteration-4.md`.
+
+### Tasks
+
+1. Define versioned Business Data Schema and project/diagram data models.
+2. Add field types, edit permissions, relationships, and cross-field business rules.
+3. Add typed commands for field, record, task, dependency, progress, node, and lane edits.
+4. Implement schema validation, data validation, command validation, and deterministic diff preview.
+5. Add affected-record analysis, dependency policy, critical-path warnings, and confirmation rules.
+6. Implement commit, rollback, undo, redo, optimistic version checks, and audit records.
+7. Add editing capability discovery, Agent response contract, and Recipe validation.
+8. Add TypeScript declarations and framework-neutral data-store adapters.
+9. Add headless preview/export and deterministic SVG, PNG, and JSON checks.
+10. Complete keyboard, ARIA, reduced-motion, and mobile editing behavior.
+11. Add preview/confirm/commit/undo demos for Gantt and Flow.
+12. Complete real-browser acceptance for desktop, mobile viewport, SVG, and Canvas.
+13. Retain public API stability, module boundaries, performance benchmarks, and lifecycle leak checks as RC release gates; track them as tasks 66–72 in the detailed plan.
+
+### Verification
+
+- `npm test`, `npm run check`, and `git diff --check` pass.
+- Type declarations compile against representative Agent editing examples.
+- Headless preview and export work without a browser DOM.
+- A schema and typed command can preview, confirm, commit, and undo a business edit.
+- Failed or stale edits do not partially mutate source data.
+- SVG and Canvas produce equivalent semantic node/data references.
+- No listener, observer, tooltip, or plugin leak remains after `destroy()`.
+- All public capabilities are discoverable and recipe validation is deterministic.
+- Browser acceptance covers the full gallery and mobile gestures.
+
+### Deliverables
+
+- `types/`
+- `docs/agent/api-reference.md`
+- `docs/agent/development/iteration-4.md`
+- `http://localhost:3000/playground/editing` (source page: `playground/editing.html`)
+- `agent-recipes/manifest.json`
+
+## Iteration 5 — Advanced Diagram and Editing Runtime
+
+### Current status
+
+Iteration 5 local runtime scope is complete: normalized models, deterministic layouts, routing modes, node and member-derived group resizing, validation, capability discovery, shared history, group lifecycle operations, clipboard editing, pointer and keyboard port connections, typed edges, deterministic multi-obstacle orthogonal routing, recipes, and a viewable editor demo at `http://localhost:3000/playground/diagram-editor.html`. Cross-browser acceptance passed; physical-device behavior remains host integration evidence.
+
+### Goal
+
+Turn Flow and Swimlane into a reusable diagram runtime with controlled editing, persistence, and collaboration-friendly patches.
+
+### Tasks
+
+1. Introduce a graph model with node, edge, lane, group, and port entities.
+2. Add orthogonal, straight, and curved edge routing modes.
+3. Add arrowhead, label, condition, and edge-status rendering.
+4. Add node drag, resize, alignment, snapping, and lane reassignment.
+5. Extend Iteration 4's command/history engine to advanced diagram operations; do not build a separate undo/redo stack.
+6. Add expand/collapse for groups and subprocesses.
+7. Add layout modes: layered, tree, radial, and manual.
+8. Add diagram validation for unreachable nodes, duplicate IDs, invalid ports, and cycles by policy.
+9. Add selection rectangle, multi-select, copy/paste, and keyboard shortcuts.
+10. Add diagram-specific SVG accessibility relationships.
+11. Add import/export of normalized DiagramSpec.
+12. Add recipes for workflow, approval process, Agent orchestration, and responsibility mapping.
+
+### Verification
+
+- Same input graph produces stable layout output.
+- Dragging and lane reassignment persist in normalized Spec.
+- Undo/redo restores both geometry and relationships.
+- Edge routing avoids node bodies in supported routing modes.
+- Keyboard-only editing covers selection, movement, and deletion.
+- Flow and Swimlane remain usable at mobile widths.
+
+### Deliverables
+
+- Diagram Runtime package.
+- `playground/diagram-editor.html`.
+- Diagram API and editing guide.
+- Flow/Swimlane recipe collection.
+
+## Iteration 6 — Project Intelligence and Business Views
+
+### Goal
+
+Add higher-level project analytics that Agents can generate from task and delivery data. The phased plan and chart-type admission policy are defined in `docs/agent/development/iteration-6.md`.
+
+### Tasks
+
+1. Add critical-path and slack visualization controls to Gantt.
+2. Add baseline versus actual schedule comparison.
+3. Add dependency lag/lead and working-calendar support.
+4. Add resource load and capacity views.
+5. Add cumulative-flow diagram.
+6. Add velocity and release burndown views.
+7. Add risk matrix and issue aging views.
+8. Add milestone variance and forecast confidence indicators.
+9. Add filtering by owner, status, priority, sprint, and label.
+10. Add linked brushing between project views.
+11. Add natural-language intent recipes for schedule, risk, capacity, and release reporting.
+12. Add data quality warnings for incomplete dates, inconsistent status, and scope anomalies.
+
+### Verification
+
+- Schedule calculations use explicit calendar and timezone rules.
+- Baseline/actual variance is numerically reproducible.
+- Forecasts expose assumptions and confidence limitations.
+- Filters update all linked views consistently.
+- Agent output includes warnings when source data is insufficient.
+- All analytics have SVG and Canvas fallback behavior where applicable.
+
+### Deliverables
+
+- Project Intelligence module.
+- `playground/project-intelligence.html`.
+- Project analytics recipes.
+- Agent data-quality and assumption documentation.
+
+## Iteration 7 — Foundational Chart Coverage
+
+### Goal
+
+Complete high-frequency foundational composition modes, then add Heatmap and Radar as fully supported public chart types. The phased implementation and admission policy are defined in `docs/agent/development/iteration-7.md`.
+
+### Tasks
+
+1. Add grouped, stacked, and percent-stacked modes to Bar, Column, and Area.
+2. Add Donut as `pie.innerRadius`, without creating a separate public type.
+3. Add mixed line/column multi-series composition and dual-axis rules.
+4. Add deterministic bin transforms for Histogram workflows.
+5. Add Heatmap with matrix encodings, color scales, missing-value semantics, and keyboard navigation.
+6. Add Radar with explicit indicator domains, multi-series comparison, and mixed-unit warnings.
+7. Complete SVG/Canvas parity, accessibility, responsive behavior, export, recipes, tests, and Gallery coverage.
+
+### Verification
+
+- Composition modes preserve backward compatibility and stable source record references.
+- Stack totals, percentage normalization, pie radii, and bin boundaries are deterministic.
+- Heatmap distinguishes missing values from zero and supports semantic keyboard navigation.
+- Radar requires explicit domains when inputs use mixed units.
+- `npm run agent:check`, `git diff --check`, and browser acceptance pass.
+
+### Deliverables
+
+- Reusable stack, mixed-mark, Donut, and bin-transform contracts.
+- Public `heatmap` and `radar` chart types.
+- `playground/foundational-gallery.html`.
+- Updated capabilities, types, recipes, documentation, tests, and acceptance record.
+
+## Iteration 8 — Chart Completeness and Agent Experience
+
+### Goal
+
+Finish the commonly expected behavior of the existing 16 chart types, improve machine-discoverable planning and diagnostics for Agents, and close the runtime, browser, packaging, performance, and 2.0 release gates. The phased plan is defined in `docs/agent/development/iteration-8.md`; the browser demo and acceptance-page architecture is defined in `docs/agent/development/playground-plan.md`.
+
+### Tasks
+
+1. Build and audit a per-chart feature matrix for common presentation, interaction, accessibility, responsive, state, export, and renderer behavior.
+2. Complete missing applicable behavior across existing charts without adding public chart types.
+3. Align interaction correctness, SVG/Canvas semantics, hit testing, keyboard behavior, lifecycle cleanup, and module loading.
+4. Expand capability discovery to per-chart data, option, interaction, renderer, limit, and export profiles.
+5. Add explainable Agent planning with alternatives, confidence, reasons, assumptions, warnings, unsupported requests, and safe next actions.
+6. Improve inspection, validation, repair diagnostics, chart descriptions, data lineage, recipes, and Agent self-check contracts.
+7. Complete cross-browser, mobile-device, accessibility, performance, package-consumer, documentation, and release acceptance.
+
+### Verification
+
+- Every declared chart feature has automated or recorded browser evidence.
+- An Agent can discover, plan, validate, render, explain, and self-check through public contracts alone.
+- Capability manifests, runtime behavior, documentation, recipes, and TypeScript declarations agree.
+- All 16 chart types pass full Gallery acceptance without uncaught errors.
+- `npm run agent:check`, `git diff --check`, browser, mobile, lifecycle, and performance gates have explicit results.
+
+### Deliverables
+
+- Chart-by-feature capability matrix and completed feature-gap fixes.
+- Per-chart Agent capability and option metadata.
+- Agent planning, diagnostics, explanation, recipes, and contract tests.
+- Browser, mobile, accessibility, performance, lifecycle, packaging, and 2.0 release records.
+- Updated full Gallery and exact preview acceptance instructions.
+
+## Iteration 9 — Visual Style System and Adaptive Theming
+
+### Goal
+
+Give all existing chart families a consistent, accessible built-in visual language that Agents can select semantically and users can switch without chart recreation. The detailed 9A–9D plan is in `docs/agent/development/iteration-9.md`.
+
+### Tasks
+
+1. Define shared visual tokens, typography roles, layout density, mark styling, and semantic colors.
+2. Add automatic, light, dark, and contrast modes.
+3. Add analysis, dashboard, report, presentation, project, and diagram presets.
+4. Add categorical, sequential, diverging, and status palettes.
+5. Add deterministic Agent style planning, reasons, warnings, and capability discovery.
+6. Add live theme switching, host color-scheme following, and explicit override preservation.
+7. Apply resolved tokens across SVG, Canvas, charts, project views, diagrams, and tooltips.
+8. Add bilingual guidance, TypeScript declarations, regression tests, and Theme Gallery acceptance.
+
+### Verification
+
+- Built-in modes satisfy declared contrast thresholds.
+- Automatic choices are deterministic and visible in plan, state, and explanation output.
+- User mode, preset, palette, and custom token overrides take precedence.
+- Theme switching does not recreate a chart or lose explicit Spec overrides.
+- `npm run agent:check`, `git diff --check`, and Theme Gallery acceptance pass.
+
+### Deliverables
+
+- Lightweight style engine in `src/theme.mjs`.
+- Public style-planning and runtime-switching APIs.
+- English and Chinese theme guides.
+- `playground/theme-gallery.html` and enhanced full Gallery controls.
+- Iteration 9 remains within version `2.0.0` and adds no chart type.
+
+## Deferred Scope
+
+The following remain deferred beyond this roadmap baseline:
+
+- Geographic and map charts.
+- 3D and perspective rendering.
+- Fishbone / Ishikawa diagrams.
+- Organization charts.
+- Kanban boards.
+- Full collaborative multi-user editing.
+
+They should only be scheduled after the core runtime, diagram model, and project analytics contracts are stable.
+
+## Recommended Execution Order
+
+1. Finish Iteration 3 browser acceptance.
+2. Execute Iteration 4 before adding more chart types.
+3. Execute Iteration 5 if diagram editing is a primary product direction.
+4. Execute Iteration 6 if project analytics and Agent reporting are primary use cases.
+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.