@taylorwong/ichartjs 2.0.1

package/docs/agent/README.md

@@ -0,0 +1,62 @@
+# iChart.js 2.0 Agent Guide
+
+This is the user-facing Agent entry point for iChart.js 2.0. Read this file first, then load one scenario guide as needed.
+
+## Language
+
+- English technical contract: current documents.
+- Chinese companion guide: [`zh-CN/README.md`](zh-CN/README.md).
+- APIs, fields, commands, error codes, and manifests use English identifiers. The English documents define the canonical technical contract; Chinese documents provide equivalent guidance.
+
+## Start Here
+
+- [Agent Quickstart](quickstart.md): install, import, plan, validate, render, explain, and self-check.
+- [Coding Agent Integration](coding-agent-integration.md): use from Codex and similar code-editing Agents.
+- [Frontend Integration](frontend-integration.md): use from ordinary JavaScript applications.
+- [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.
+- [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.
+
+The 2.0 API is Spec-first. Import from `ichartjs`, inspect data, plan a chart, create a JSON-friendly Spec, validate it, render it, and self-check the explanation and runtime state.
+
+## Recommended flow
+
+```js
+const report = ichart.inspectData(data);
+const recommendation = ichart.planChart(data, { intent: 'trend' });
+const spec = {
+  type: recommendation.primary,
+  renderer: 'svg',
+  container: '#chart',
+  data: { values: data },
+  encoding: { x: { field: 'month' }, y: { field: 'sales' } }
+};
+const validation = ichart.validateSpec(spec);
+if (!validation.valid) return validation.errors;
+const chart = ichart.createChart(validation.spec);
+chart.explain();
+```
+
+Use `getCapabilities()` to discover supported chart types, project-management views, diagrams, renderers, interactions, exports, and data operations. Use `chart.getSpec()`, `chart.getState()`, `chart.getSelectedData()`, and `chart.toDataTable()` to inspect a live chart.
+
+For a visual overview of all supported chart types, open `playground/project-gallery.html`. For style-system acceptance, open `playground/theme-gallery.html`.
+
+## Selection rules
+
+- Use `line` or `area` for temporal trends.
+- Use `bar` for category comparison or long labels.
+- Use `column` for compact category comparison.
+- Use `pie` only for a small part-to-whole view.
+- Prefer `svg` when DOM interaction or accessibility is important.
+- 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.
+- Do not generate `map` or `3d` Specs unless `getCapabilities()` declares them.
+
+## Error handling
+
+Always call `validateSpec()` before rendering. Validation errors contain `code`, `path`, `message`, and `suggestion`.

package/docs/agent/charting-scenario.md

@@ -0,0 +1,82 @@
+# Scenario: Data Charting
+
+Agent usage and development guide for generic data analysis and metric visualization.
+
+## Supported Types
+
+| Type | Typical intent | Recommended renderer |
+| --- | --- | --- |
+| `line` | Trends and time changes | `svg` |
+| `area` | Trends and cumulative volume | `svg` |
+| `bar` | Category comparison and long labels | `svg` |
+| `column` | Compact category comparison | `canvas` or `svg` |
+| `pie` | Small part-to-whole views | `svg` |
+| `scatter` | Relationship between two numeric variables | `canvas` |
+| `funnel` | Conversion stages | `svg` |
+| `gauge` | Single-metric completion | `canvas` |
+| `heatmap` | Matrix intensity and calendar patterns | `canvas` or `svg` |
+| `radar` | Multidimensional profile comparison | `svg` |
+
+## Foundational Modes
+
+- Use `stack: "stacked"` or `stack: "percent"` with Bar, Column, or Area rather than a separate stacked type.
+- Use `type: "pie"` with `innerRadius` for Donut charts.
+- Use per-series `mark: "column"` or `mark: "line"` and optional `axis: "right"` for Combo charts.
+- Use `transform: { type: "bin", field, thresholds | step, extent }` for Histogram workflows.
+- Heatmap treats missing values separately from numeric zero through `colorScale.missing`.
+- Radar should declare `min` and `max` for every indicator; omitted or mixed-unit domains produce warnings.
+
+## Agent Workflow
+
+1. Call `inspectData(data)` to identify fields and missing values.
+2. Select a chart type from the business intent; use `recommend(data, { intent })` for automated selection.
+3. Create a JSON-serializable Chart Spec.
+4. Call `validateSpec(spec)` before `createChart(spec)`.
+5. Inspect the result with `chart.describe()` and `chart.getState()`.
+
+## Minimal Spec
+
+```js
+{
+  type: 'line',
+  renderer: 'svg',
+  container: '#chart',
+  data: { values: [{ month: 'Jan', sales: 120 }] },
+  encoding: {
+    x: { field: 'month', type: 'category' },
+    y: { field: 'sales', type: 'quantitative' }
+  }
+}
+```
+
+## Renderer Rules
+
+- Use `svg` for DOM interaction, accessibility, element inspection, or fewer marks.
+- Use `canvas` for many marks and rendering performance when individual DOM elements are unnecessary.
+- Layout and data semantics must remain independent of the renderer.
+
+## Implementation Map
+
+- Spec and chart types: `src/spec.mjs`
+- Data inspection and transforms: `src/data.mjs`
+- Scene construction: `src/charts.mjs`
+- Scales: `src/scale.mjs`
+- Canvas/SVG renderers: `src/renderer.mjs`
+- Tests: `tests/core.test.mjs`
+- Full gallery: `playground/project-gallery.html`
+- Iteration 7 gallery: `playground/foundational-gallery.html`
+
+## Development Checklist
+
+- Update `src/spec.mjs` and `src/charts.mjs`.
+- Add data, Scene, and renderer-independence tests for the new type.
+- Add the chart to `playground/project-gallery.html`.
+- Update `docs/manifests/capabilities.json`.
+- Update this guide's type table and limitations.
+
+## Acceptance
+
+- The Spec passes `validateSpec()`.
+- The Gallery creates the chart with a `ready` status.
+- Canvas and SVG expose the same Scene structure.
+- Declared capabilities such as tooltip, selection, and zoom match actual behavior.

package/docs/agent/coding-agent-integration.md

@@ -0,0 +1,88 @@
+# Coding Agent Integration
+
+Use this guide with Codex, WorkBuddy, and similar Agents that can read a repository, edit JavaScript, execute tests, and open a local browser preview.
+
+## Responsibility Boundary
+
+iChart.js is a JavaScript UI component library. The coding Agent writes or updates the host application and calls the public `ichartjs` ESM API. The optional Skill provides workflow guidance only; it does not introduce a second runtime or service.
+
+Do not add a CLI, MCP server, HTTP API, or Python adapter to complete an ordinary charting task.
+
+## Setup
+
+Inside a consumer project:
+
+```bash
+npm install @taylorwong/ichartjs@^2
+```
+
+Do not install the unscoped npm registry package named `ichartjs`; it is currently an npm security holding package. Use the GitHub source until the project publishes under a confirmed npm scope.
+
+Inside this repository:
+
+```bash
+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:
+
+```bash
+cp -R skills/ichartjs "${CODEX_HOME:-$HOME/.codex}/skills/"
+```
+
+## Agent Request Pattern
+
+A useful request is explicit about data, intent, output, and acceptance:
+
+```text
+Use iChart.js to inspect this dataset, choose and validate an appropriate chart,
+add it to the current web page, run the focused tests, and return the exact preview URL.
+Keep assumptions and data-quality warnings visible.
+```
+
+If the host supports named Skill invocation, the request may start with `Use $ichartjs`; otherwise select or name the `ichartjs` Skill through the host interface.
+
+## Required Workflow
+
+1. Inspect existing application structure and local instructions.
+2. Import public APIs from `ichartjs`.
+3. Call `getCapabilities()`, `inspectData()`, and `planChart()`.
+4. Stop or ask for input when required fields are missing.
+5. Build a JSON-friendly Spec and call `validateSpec()`.
+6. Mount the chart through the application's normal component lifecycle.
+7. Verify `chart.explain()`, `chart.getState()`, warnings, and record lineage.
+8. Destroy replaced charts and event handlers.
+9. Run focused tests, then broader checks.
+10. Return the exact local preview URL and manual acceptance actions.
+
+## Minimal Coding-Agent Example
+
+```js
+import { createChart, inspectData, planChart, validateSpec } from '@taylorwong/ichartjs';
+
+const inspection = inspectData(rows);
+const plan = planChart(rows, { intent: 'comparison' });
+const candidate = {
+  type: plan.primary,
+  data: { values: rows },
+  encoding: {
+    x: { field: plan.suggestedEncodings.dimension },
+    y: { field: plan.suggestedEncodings.measure }
+  }
+};
+const validation = validateSpec(candidate);
+if (!validation.valid) throw new Error(JSON.stringify(validation.errors));
+const chart = createChart({ ...validation.spec, container: '#chart' });
+```
+
+Use `examples/agent-workflow.mjs` for the full executable lifecycle.
+
+## Acceptance
+
+- The application imports only `ichartjs`, not source internals.
+- The chosen chart exists in capabilities.
+- Validation passes before rendering.
+- Warnings and assumptions remain visible.
+- Stable source IDs remain in explanation lineage.
+- The user receives a working preview URL.

package/docs/agent/development/2.0-release-readiness.md

@@ -0,0 +1,65 @@
+# iChart.js 2.0 Final Release Readiness
+
+Date: 2026-09-16
+
+## Decision
+
+The repository runtime is accepted for the `2.0.0` GitHub source release. npm publication remains separately deferred.
+
+iChart.js 2.0 is a new Agent-first product line. Compatibility with 1.x and a 1.x-to-2.0 migration guide are intentionally outside the release scope.
+
+## Passed Gates
+
+- `npm run agent:check`: passed.
+- `npm run example:agent`: passed.
+- `npm run rc:check`: passed.
+- Core tests: 51 passed, 0 failed.
+- Agent documentation check: 16 charts, 24 commands, and 7 schemas.
+- Official iChart.js Skill validation: passed.
+- GitHub Actions CI: Node.js 18, 20, and 22 run Agent checks, the executable workflow, and tarball verification.
+- GitHub Actions run `35117247851` completed successfully for release-preparation commit `9df8f14`.
+- Node.js 18.20.8, 20.20.2, and 22.22.2: Agent checks and the executable Agent workflow passed locally.
+- Project governance: contribution and private vulnerability-reporting guidance are present.
+- Markdown local-link audit: passed.
+- Package tarball: 77 files, 129.2 kB packed and 467.7 kB unpacked, with an explicit allowlist and root license.
+- External consumer installation: root ESM import, capability discovery, planning, chart creation, capability manifest, and recipes resolved successfully.
+- TypeScript consumer compilation: passed in strict NodeNext mode against the packed tarball.
+- Package boundary: undeclared subpaths such as `ichartjs/agent` are rejected.
+- Chromium browser regression: Home, Full Gallery, Agent Workbench, Project Intelligence, Diagram Editor, Interaction Lab, Accessibility Lab, and Performance Lab rendered without visible runtime errors.
+- Firefox 144 and WebKit 26 regression: 22/22 desktop and 390 x 844 touch-viewport scenarios passed without page errors or horizontal overflow.
+- Native Safari 26.6.2 regression: 11/11 desktop and 390 x 844 scenarios passed without horizontal overflow.
+- Performance regression: 5,000-row Line and Heatmap, 1,000-task Gantt, 300-node Diagram, SVG/Canvas, and 25-cycle lifecycle samples passed in Firefox and WebKit.
+- Full Gallery: all 16 public chart types rendered across 6 Canvas and 10 SVG examples.
+
+## Remaining Release Actions
+
+1. **Final commit and tag.** Commit the consistent `2.0.0` package, runtime, Playground, documentation, and changelog versions, then create `v2.0.0` from that exact commit.
+2. **Default branch cutover.** GitHub still uses `master`, which currently points to the archived 1.x project and its legacy development dependencies. Fast-forward `master` to the final 2.0 commit before creating the GitHub Release.
+
+## Deferred npm Publication
+
+The public npm name `ichartjs` currently resolves to an npm security holding package, and this machine has no authenticated publisher. Per the release decision, npm publication is deferred and does not block the GitHub source release.
+
+## Finalization Order
+
+1. Re-run all automated and package-consumer gates against `2.0.0`.
+2. Commit the final version and fast-forward `master` to the same commit.
+3. Create and push the `v2.0.0` tag, then create the GitHub Release from that exact commit.
+4. Record physical-device and representative release-host evidence as post-release integration follow-up.
+
+## Preview
+
+Start the no-cache server from the repository root:
+
+```bash
+npm run playground
+```
+
+- Home: `http://localhost:3000/playground/index.html`
+- Full Gallery: `http://localhost:3000/playground/project-gallery.html`
+- Agent Workbench: `http://localhost:3000/playground/agent-workbench.html`
+- Project Intelligence: `http://localhost:3000/playground/project-intelligence.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`

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

@@ -0,0 +1,9 @@
+# Iteration 2 Capabilities
+
+The beta runtime adds category, time, and log scale primitives; data transforms; selection and zoom state APIs; themes; accessibility metadata; plugins; responsive resize; and scatter, funnel, and gauge chart types.
+
+Multi-series encodings may use `encoding.y` as an array. The second encoding is mapped to the right axis, for example `{ field: 'margin', axis: 'right' }`. Temporal x encodings use `type: 'temporal'` and generate adaptive year, month, or day labels.
+
+Use `getCapabilities()` before generating a Spec. Use `inspectData()` before choosing fields. Use `chart.describe()` and `chart.getState()` after rendering to verify the result.
+
+The browser validation page is `playground/iteration-2.html`. It must be served over HTTP because it imports the ESM runtime.

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

@@ -0,0 +1,142 @@
+# Iteration 3 — Project and Business Visualization
+
+## Goal
+
+Extend iChart.js 2.0 from a statistical chart runtime into an Agent-first visualization runtime that can represent project plans, delivery progress, milestones, and business processes.
+
+This iteration explicitly **does not include geographic charts or 3D rendering**. The architecture may be upgraded when needed; compatibility with the legacy 1.x implementation is not a constraint.
+
+## Scope
+
+### P0 — Project management charts
+
+1. **Gantt chart (`gantt`)**
+   - Tasks with `id`, `name`, `start`, `end`, `duration`, `progress`, and `status`.
+   - Task dependencies and dependency validation.
+   - Milestone tasks with zero duration.
+   - Today marker, working-area layout, task labels, and status styling.
+   - Time-axis zoom, horizontal pan, task selection, and tooltip details.
+   - SVG and Canvas rendering where the interaction model is shared.
+
+2. **Timeline / milestone chart (`timeline`, `milestone`)**
+   - Chronological events with dates, titles, descriptions, categories, and status.
+   - Milestone emphasis, event grouping, and compact/mobile layouts.
+   - Click, hover, keyboard navigation, and accessible event descriptions.
+   - ISO-8601 dates are validated before rendering.
+
+3. **Burndown chart (`burndown`)**
+   - Ideal line, actual remaining work, completed work, and scope-change markers.
+   - Sprint or release date range.
+   - Support for story points, task count, or another quantitative measure.
+   - Highlight overdue work and projected completion when data is sufficient.
+   - Scope-change rows may provide `scopeChange`; the runtime renders change markers and keeps actual remaining work separate.
+
+### P1 — Process visualization
+
+4. **Flow chart (`flow`)**
+   - Nodes, directed edges, labels, node kinds, and status.
+   - Automatic layout with deterministic output for the same Spec.
+   - Node/edge hit testing, selection, focus navigation, and viewport pan/zoom.
+   - SVG-first output for semantic DOM interaction, with Canvas fallback for large graphs.
+   - Nodes may be dragged when `interaction.drag` is enabled; `drag` and `dragend` events expose the active node.
+
+5. **Swimlane chart (`swimlane`)**
+   - Lanes representing people, teams, systems, or Agents.
+   - Flow nodes positioned within lanes and cross-lane transitions.
+   - Lane labels, grouping, selection, and accessible relationships.
+
+### P2 — Deferred extensions
+
+The following remain outside the Iteration 3 delivery target:
+
+- Geographic and map charts.
+- 3D and perspective chart variants.
+- Fishbone / Ishikawa diagrams.
+- Organization charts.
+- Dependency networks and resource-load views.
+- Kanban boards.
+
+These can be evaluated after the Diagram Runtime and editing model have stabilized.
+
+## Technical work items
+
+1. Define a common `ProjectSpec` and `DiagramSpec` contract.
+2. Add `gantt`, `timeline`, `milestone`, `burndown`, `flow`, and `swimlane` to capability discovery.
+3. Add validation schemas and actionable validation suggestions for each type.
+4. Add temporal interval, dependency, node, edge, and lane data models.
+5. Add reusable project timeline layout primitives.
+6. Add reusable graph layout and routing primitives.
+7. Render project and diagram scene graphs through the existing renderer abstraction.
+8. Add shared interaction state for selection, focus, pan, zoom, and tooltip.
+9. Add plugin hooks for annotations, labels, data zoom, and accessibility.
+10. Add Agent recommendations based on intents such as `schedule`, `progress`, `milestone`, `workflow`, and `responsibility`.
+11. Add JSON Recipes for every Iteration 3 chart type.
+12. Add a dedicated project-management and process gallery.
+13. Add mobile interaction coverage and responsive layout rules.
+14. Add export and serialization checks for SVG, PNG, and normalized Spec output.
+15. Preserve Flow node positions after drag by writing them to `node.position`.
+
+## Agent API expectations
+
+Capability discovery should expose separate groups:
+
+```json
+{
+  "charts": ["line", "area", "bar", "column", "pie", "donut", "scatter", "bubble", "heatmap", "funnel", "gauge", "waterfall"],
+  "projectManagement": ["gantt", "timeline", "milestone", "burndown"],
+  "diagrams": ["flow", "swimlane"],
+  "excluded": ["map", "3d"]
+}
+```
+
+The Agent guide must include one minimal Spec and one data-shape example for each supported type. The Agent should be able to discover the appropriate type without relying on legacy class names such as `Column2D` or `Column3D`.
+
+## Demo deliverables
+
+The following viewable demos are required before Iteration 3 is considered complete:
+
+- `playground/project-gallery.html` with Gantt, timeline, milestone, burndown, flow, and swimlane examples.
+- At least one SVG and one Canvas scenario where each renderer is appropriate.
+- A responsive/mobile scenario showing timeline or Gantt pan and zoom.
+- A workflow scenario showing lane ownership and cross-lane transitions.
+- Inline links to the corresponding Agent Recipes and normalized Specs.
+
+When a demo is available for acceptance, report the exact HTTP URL and the command used to serve it. These demos must not depend on opening ESM files directly through `file://`.
+
+## Verification criteria
+
+### Functional
+
+- Each P0 and P1 type validates, normalizes, renders, and exposes `describe()` and `getState()`.
+- Invalid dates, intervals, dependencies, node references, and lane references produce structured validation errors.
+- Gantt dependencies render in the correct direction and report missing or cyclic dependencies.
+- Burndown calculations remain correct when scope changes are present.
+- Flow and swimlane layouts are deterministic and do not lose nodes or edges.
+
+### Interaction
+
+- Hover, click, selection, keyboard focus, tooltip, pan, and zoom work consistently across supported types.
+- Project tooltips show task dates/progress, milestone dates, and burndown remaining/scope changes.
+- Dependency arrows use arrowheads; entries on `criticalPath` use emphasized styling.
+- Touch drag and pinch zoom work on timeline-based charts.
+- Single-finger touch drag moves Flow nodes when `interaction.drag` is enabled; two-finger touch remains reserved for pinch zoom.
+- Keyboard users can traverse tasks, milestones, nodes, and lanes with visible focus state.
+
+### Rendering and accessibility
+
+- SVG output exposes meaningful labels and relationships where possible.
+- Canvas output retains equivalent hit testing and accessible chart metadata.
+- Responsive layouts remain usable at desktop and mobile widths.
+- SVG, PNG, and normalized JSON exports are available or explicitly reported unsupported per chart type.
+
+### Quality gate
+
+- `npm test` passes.
+- `npm run check` passes.
+- `git diff --check` passes.
+- Browser acceptance covers every Iteration 3 demo panel through an HTTP-served page.
+- Agent Recipes parse successfully and match capability discovery.
+
+## Completion definition
+
+Iteration 3 is complete when all P0 and P1 types are implemented, tested, documented, discoverable by an Agent, and demonstrated in `playground/project-gallery.html`. P2 items are not blockers for the iteration.