@taylorwong/ichartjs 2.0.1

package/docs/agent/development-guide.md

@@ -0,0 +1,60 @@
+# Development Guide
+
+Unified workflow for Coding Agents developing iChart.js 2.0.
+
+## Select a Scenario
+
+| Requirement | Guide | Main source |
+| --- | --- | --- |
+| 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` |
+
+## Standard Change Flow
+
+1. Read `README.md`, this guide, and the relevant scenario guide.
+2. Read the current `development/iteration-X.md` to confirm scope and boundaries.
+3. Check module comments under `src/` and identify the smallest change surface.
+4. Add or adjust tests before implementing; avoid unrelated fixes.
+5. Synchronize the Manifest, scenario guide, Recipe, and Gallery.
+6. Run `npm test`, `npm run check`, and `git diff --check`.
+7. Provide the HTTP Demo URL and acceptance steps as soon as a viewable result exists.
+
+Run `npm run agent:check` after changes. It checks the declared chart and command lists, schema model coverage, document presence, Chinese text in English core documents, and Gallery type coverage, then runs syntax checks and tests. It does not verify prose equivalence or browser behavior.
+
+## Change Map
+
+### Add a Generic Chart
+
+- Update `src/spec.mjs` and `src/charts.mjs`.
+- Add data and Scene tests.
+- Update `charting-scenario.md`, `capabilities.json`, and the Gallery.
+
+### Add a Project Feature
+
+- Update `src/project.mjs` and, when needed, `src/schema.mjs`.
+- Add tests for analytics, tooltips, and boundary conditions.
+- Update `project-scenario.md`, `schemas.json`, and the Gallery.
+
+### Add a Diagram Feature
+
+- Update `src/diagram.mjs` or `src/diagram-interaction.mjs`.
+- Update command validation and edit history tests.
+- Update `diagram-scenario.md`, `commands.json`, and the Diagram Demo.
+
+## Documentation Rules
+
+- Every active `src/*.mjs` module must have a short file-level comment.
+- Add focused JSDoc for public APIs and complex algorithms; avoid line-by-line noise comments.
+- Documentation describes behavior and contracts; code executes and validates them.
+- Core documents directly under `docs/agent/` use English. Chinese companions belong in `docs/agent/zh-CN/`. Update both when technical contracts change.
+- Development records live in `docs/agent/development/` and are not part of the default Agent context. Their existing language may be retained.
+
+## Completion Checklist
+
+- Code implementation is complete.
+- Unit tests are complete.
+- The Manifest is synchronized.
+- The scenario guide is synchronized.
+- The Gallery or a focused Demo is reviewable.
+- `npm run rc:check` passes.

package/docs/agent/diagram-scenario.md

@@ -0,0 +1,82 @@
+# Scenario: Interactive Diagrams
+
+Agent usage and development guide for process modeling, responsibility mapping, and editable diagrams.
+
+## Supported Types
+
+- `flow`: a process graph made of nodes and edges.
+- `swimlane`: a process graph organized by responsibility lanes.
+
+## Data Model
+
+```js
+{
+  type: 'flow',
+  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'
+  }],
+  edges: [{ from: 'start', to: 'review', toPort: 'in' }],
+  groups: [{ id: 'delivery', label: 'Delivery' }]
+}
+```
+
+## Current Capabilities
+
+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.
+- 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.
+- Group collapse/expand with collapsed group summary rendering.
+
+Current limitations:
+
+- Groups are flat; nested groups are not supported.
+- Group bounds are derived from member geometry and configurable `group.padding`; `resizeGroup` scales member positions and sizes rather than persisting a second group rectangle.
+- `deleteGroup` defaults to `ungroup`; use `delete-members` only after explicit host confirmation.
+- Canvas keeps basic accessibility text, while SVG exposes richer diagram semantics.
+- Cross-browser matrix and physical-device validation remain acceptance work, not runtime guarantees.
+
+## Agent Workflow
+
+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.
+5. Follow the preview/confirm/commit flow for all business-data changes.
+
+## Implementation Map
+
+- Diagram model, validation, layout, and routing: `src/diagram.mjs`
+- Interaction: `src/diagram-interaction.mjs`
+- Diagram Scene: `src/project.mjs`
+- Commands and transactions: `src/command.mjs`, `src/edit-controller.mjs`
+- Editor demo: `playground/diagram-editor.html`
+- Full gallery: `playground/project-gallery.html`
+- Keyboard port connection: Tab focuses nodes/groups/ports, Enter starts or completes a port connection, and Escape cancels it.
+
+## Development Checklist
+
+- Update Diagram data rules and `validateDiagram()`.
+- Update command validation and preview/commit/history tests.
+- Ensure edge arrows, labels, and ports are recomputed after node movement.
+- Verify collapsed groups hide member nodes from the rendered Scene while preserving normalized Spec data.
+- Check Canvas and SVG Scene structures together.
+- Update `diagram-editor.html` and the Gallery.
+
+## Acceptance
+
+- Edges, arrows, and labels follow nodes after movement.
+- Multi-selection alignment and snapping are visible in state output.
+- Keyboard edits create undoable history entries.
+- 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.

package/docs/agent/editing-contract.md

@@ -0,0 +1,71 @@
+# Editing Contract
+
+Safe editing contract for business and Diagram data used by Agents.
+
+## Required Flow
+
+```text
+Read Schema → Build Command → Validate → Preview → Confirm → Commit → ChangeSet
+```
+
+Do not mutate business data objects directly; use the Chart editing API so the Runtime performs validation and history management.
+
+## APIs
+
+```js
+const preview = chart.previewEdit(command);
+if (!preview.valid) return preview.errors;
+
+const result = chart.applyEdit(command, {
+  preview,
+  confirmed: true,
+  source: 'agent'
+});
+```
+
+Core APIs:
+
+- `getBusinessSchema(name)`
+- `inspectDataSchema(schema)`
+- `validateEdit(command)`
+- `previewEdit(command)`
+- `applyEdit(command, options)`
+- `getChangeSet()`
+- `undo()` / `redo()`
+
+## Command Rules
+
+- The command version is currently `1.0`.
+- Targets use stable `id` values; array positions are not business identities.
+- 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.
+
+## Supported Models
+
+- `project-task`
+- `timeline-event`
+- `milestone`
+- `burndown-sample`
+- `flow-node`
+- `flow-edge`
+- `swimlane`
+
+## History and Revision
+
+Successful commits produce a ChangeSet, audit information, a revision, and an undo history entry. A preview based on an old revision must fail on commit with `STALE_PREVIEW`.
+
+## Implementation Map
+
+- Schema: `src/schema.mjs`
+- Commands: `src/command.mjs`
+- Preview/commit: `src/edit.mjs`
+- Transaction lifecycle: `src/edit-controller.mjs`
+- History: `src/history.mjs`
+- Tests: `tests/core.test.mjs`
+
+## Acceptance
+
+- Invalid commands do not modify data.
+- Preview and commit commands must match.
+- Confirmation, revisions, audit records, and undo/redo are verifiable.

package/docs/agent/frontend-integration.md

@@ -0,0 +1,66 @@
+# Frontend Integration
+
+Use iChart.js as an ordinary JavaScript UI component inside a browser application. The host application owns data loading, authentication, persistence, routing, and any assistant or natural-language interface.
+
+## Install
+
+```bash
+npm install @taylorwong/ichartjs@^2
+```
+
+For environments without npm registry access, install from GitHub as a fallback: `npm install github:wanghetommy/ichartjs#v2.0.1`.
+
+Use the package through a bundler or another environment that resolves npm ESM imports:
+
+```js
+import { createChart } from '@taylorwong/ichartjs';
+
+const chart = createChart({
+  container: '#chart',
+  type: 'bar',
+  renderer: 'svg',
+  data: { values: rows },
+  encoding: {
+    x: { field: 'category' },
+    y: { field: 'value' }
+  },
+  interaction: { tooltip: true, keyboard: true },
+  accessibility: { enabled: true }
+});
+```
+
+## Component Lifecycle
+
+- Create the chart after the container exists.
+- Call `setData()` when only rows change.
+- Call `update()` when Spec options change.
+- Call `resize()` when the host controls dimensions.
+- Call `destroy()` before replacing the component or removing its container.
+
+## Optional Agent-Assisted UI
+
+A host web application may let a user enter an intent such as “show the sales trend.” Keep the integration in JavaScript:
+
+1. Convert application data to JSON-friendly rows.
+2. Call `inspectData()` and `planChart()` in the browser or Node.js host.
+3. Build and validate a candidate Spec.
+4. Render with `createChart()`.
+5. Show reasons, assumptions, warnings, and unsupported requests in the host UI.
+
+If a daily-use assistant cannot execute or generate JavaScript, it cannot directly consume a JavaScript UI component. Its host application must perform the integration; iChart.js does not need a separate service protocol.
+
+## Out of Scope
+
+The core package does not provide:
+
+- an HTTP service;
+- an MCP server;
+- a command-line application;
+- a Python runtime;
+- file upload, authentication, storage, or sharing infrastructure.
+
+Add these only in an application that has a demonstrated requirement. Do not duplicate chart planning or rendering outside the JavaScript runtime.
+
+## Preview
+
+Within this repository, run `npm run playground` and open `http://localhost:3000/playground/project-gallery.html` to inspect every public chart type.

package/docs/agent/project-scenario.md

@@ -0,0 +1,89 @@
+# Scenario: Project Management
+
+Agent usage and development guide for project planning, delivery tracking, and project status reporting.
+
+## Chart Selection
+
+| Type | Typical use | Core data |
+| --- | --- | --- |
+| `gantt` | Task schedules, dependencies, critical paths | `id/name/start/end` |
+| `timeline` | Event timelines | `id/title/date` |
+| `milestone` | Key delivery points | `id/title/date` |
+| `burndown` | Remaining Sprint work | `date/remaining` |
+
+## Project Intelligence
+
+- Prefer existing primitives for analytics views:
+  - `gantt` for schedule variance, baseline vs actual, slack, and critical path
+  - `column` for capacity and velocity
+  - `area` for cumulative flow
+  - `burndown` for release forecasting
+  - `scatter` for risk matrix
+  - `bar` for issue aging
+- Declare calendar assumptions explicitly with timezone, working weekdays, holidays, and non-working-day policy. Iteration 6 calculations support deterministic `UTC`; other timezone values warn and fall back to `UTC`.
+- Keep derived values separate from source rows. State and tooltips may expose variance, float, warnings, and assumptions, but transforms must not mutate source data.
+- Linked filters and linked selection must use stable record IDs, not array positions.
+- Forecasts, risk scores, and aging buckets are inspectable heuristics. They are not commitments, causal claims, or hidden inference.
+
+## Agent Workflow
+
+1. Confirm the task, event, or Sprint data model.
+2. Check dates, progress, dependencies, and missing values.
+3. Select a project chart and create its Spec.
+4. Validate Gantt dependencies; missing and cyclic dependencies are invalid.
+5. For intelligence views, surface assumptions, warnings, and linked-filter state in the delivery output.
+6. Use project tooltips, critical paths, scope changes, forecasts, and variance to explain results.
+
+## Data Rules
+
+- Gantt `start` and `end` must be valid dates, and `end` cannot precede `start`.
+- `progress` uses the `0–100` percentage convention.
+- `dependencies` use stable task IDs, either as strings or `{ id, type, lag, lead }` objects, and must form an acyclic graph.
+- Issue aging requires an explicit ISO `today` reference; missing or invalid dates produce warnings instead of guessed buckets.
+- Calendar-aware scheduling may also use dependency objects with explicit `type`, `lag`, and `lead`.
+- `baselineStart`/`baselineEnd` and `actualStart`/`actualEnd` should be treated as explicit source inputs, not inferred values.
+- Burndown `scopeChange` represents scope movement, not completed work.
+- A forecast is an estimate derived from current samples, not a commitment or fact.
+- Capacity warnings, risk quadrants, and aging buckets should stay explainable from source fields.
+
+## Editing
+
+Project data edits follow `editing-contract.md`:
+
+```text
+Schema → Command → Validate → Preview → Confirm → Commit → ChangeSet
+```
+
+Typical operations:
+
+- `updateProgress`
+- `shiftTask`
+- `addDependency`
+- `removeDependency`
+- `updateMilestone`
+
+## Implementation Map
+
+- Project Scenes and tooltips: `src/project.mjs`
+- Project analytics and adapters: `src/project-analytics.mjs`
+- Linked filters and selection helpers: `src/project-linking.mjs`
+- Project schemas: `src/schema.mjs`
+- Commands and editing: `src/command.mjs`, `src/edit.mjs`
+- Tests: `tests/core.test.mjs`
+- Full gallery: `playground/project-gallery.html`
+- Project intelligence demo: `playground/project-intelligence.html`
+
+## Development Checklist
+
+- Update project data rules and the Manifest before adding a capability.
+- Add tests for analytics and tooltip content.
+- Cover missing dates, cyclic dependencies, weekends/holidays, lag/lead, scope changes, and insufficient forecast data.
+- Synchronize the Gallery and this guide's limitations.
+
+## Acceptance
+
+- All four project chart types initialize in the Gallery.
+- Gantt dependencies, critical-path results, and variance overlays are explainable.
+- Burndown scope changes and forecasts have dedicated tests.
+- Capacity, risk, and aging analytics preserve stable record IDs.
+- Editing commands support preview, commit, undo, and redo.

package/docs/agent/quickstart.md

@@ -0,0 +1,205 @@
+# Agent Quickstart
+
+Use this guide when an Agent needs to turn user data or project information into an iChart.js visualization. Use public contracts only; do not inspect renderer or chart implementation files to guess behavior.
+
+## Import Surface
+
+```js
+import {
+  createChart,
+  getCapabilities,
+  getChartCapability,
+  inspectData,
+  planChart,
+  validateSpec
+} from '@taylorwong/ichartjs';
+```
+
+Agents and developers use the same `ichartjs` ESM entry. Agent behavior comes from the public planning APIs and optional Skill, not from a second runtime.
+
+Additional package resources:
+
+- `ichartjs/capabilities.json`: machine-readable catalog, including per-chart exports, branding, and interaction declarations.
+- `ichartjs/recipes/foundational-analysis`: foundational chart recipes.
+- `ichartjs/recipes/project-management`: project intelligence recipes.
+- `ichartjs/recipes/diagrams/workflow`: diagram editing recipe.
+- `skills/ichartjs/SKILL.md`: optional workflow adapter for Codex, WorkBuddy, and other Agent Skills-compatible hosts.
+
+The Skill is not the runtime. Install or register it only when the Agent host supports Skills; it must still call the package's public APIs and capability contract.
+
+For coding environments such as Codex, read [Coding Agent Integration](coding-agent-integration.md). For application integration, read [Frontend Integration](frontend-integration.md).
+
+## Standard Workflow
+
+```text
+discover → inspect → plan → build → validate → render → explain, export, self-check
+```
+
+### 1. Discover
+
+Call `getCapabilities()` before choosing a chart. Use `getChartCapability(type)` to verify required roles, interactions, renderers, feature status, exports, and practical limits for a candidate type.
+
+### 2. Inspect
+
+Call `inspectData(rows)` and review:
+
+- field roles and inferred types;
+- stable identifier fields;
+- dimensions, measures, and temporal coverage;
+- cardinality, missing values, and invalid values;
+- warnings that must remain visible to the user.
+
+Inferred roles and units are suggestions. Do not convert them into business facts without user-provided semantics.
+
+### 3. Plan
+
+Call `planChart(rows, { intent, renderer })`. Read the full result rather than only `primary`:
+
+- `alternatives` and `confidence`;
+- `reasons` and `suggestedEncodings`;
+- `requiredFields`;
+- `assumptions` and `warnings`;
+- `unsupportedRequests` and `nextActions`;
+- the selected per-chart capability profile;
+- `styleRecommendation`, including the resolved preset, mode, palette, reasons, and warnings.
+
+Stop before rendering when `requiredFields` is not empty. Ask for the missing information or choose a supported alternative without fabricating data.
+
+### 4. Build a JSON-Friendly Spec
+
+For a trend or comparison with one dimension and one or more measures:
+
+```js
+const y = [plan.suggestedEncodings.measure, plan.suggestedEncodings.secondaryMeasure]
+  .filter(Boolean)
+  .map(field => ({ field, type: 'quantitative' }));
+
+const spec = {
+  type: plan.primary,
+  renderer: 'svg',
+  data: { values: rows },
+  encoding: {
+    x: { field: plan.suggestedEncodings.dimension },
+    y: y.length === 1 ? y[0] : y
+  },
+  interaction: { tooltip: true, hover: true, keyboard: true },
+  accessibility: { enabled: true },
+  // branding: true is the default; set explicitly branding: false to disable signature + extra bottom padding
+  theme: {
+    mode: 'auto',
+    preset: plan.styleRecommendation.preset,
+    palette: plan.styleRecommendation.palette
+  }
+};
+```
+
+Use the selected capability and recipes for Pie, Gauge, Heatmap, Radar, project views, and diagrams because their required encodings differ.
+
+### 5. Validate
+
+```js
+const validation = validateSpec(spec);
+if (!validation.valid) {
+  return {
+    status: 'needs-repair',
+    errors: validation.errors,
+    warnings: validation.warnings,
+    normalizations: validation.normalizations
+  };
+}
+```
+
+Do not silently discard diagnostics. Preserve stable `code`, `path`, `message`, `expected`, and `suggestion` fields in Agent output and automated repair loops.
+
+### 6. Render
+
+Browser rendering:
+
+```js
+const chart = createChart({ ...validation.spec, container: '#chart' });
+```
+
+Headless planning and scene creation:
+
+```js
+const chart = createChart(validation.spec);
+```
+
+Headless environment capabilities:
+- JSON and SVG string export work with zero dependencies.
+- PNG/JPEG raster export requires the optional `canvas` npm package; otherwise a structured `HEADLESS_EXPORT_UNSUPPORTED` error is returned.
+- The on-screen renderer is decoupled from the export backend; any mounted renderer can export any supported format.
+
+### 7. Explain, Export, and Self-Check
+
+```js
+// JSON export (zero-dependency, all environments)
+const jsonPayload = chart.export({ type: 'json', as: 'object' });
+const jsonString = chart.export({ type: 'json' });
+
+// SVG vector export (zero-dependency, browser + headless)
+const svgString = chart.export({ type: 'svg' });
+
+// PNG raster (browser always works; headless requires the canvas package)
+const pngDataUrl = typeof document !== 'undefined'
+  ? chart.toDataURL('image/png')
+  : null;
+
+// Browser-only convenience downloads
+if (typeof document !== 'undefined') {
+  chart.downloadPNG();
+  chart.downloadSVG();
+  chart.downloadJSON();
+}
+
+const result = {
+  plan,
+  explanation: chart.explain(),
+  state: chart.getState(),
+  json: jsonPayload,
+  svg: svgString,
+  png: pngDataUrl
+};
+
+chart.destroy();
+```
+
+Before returning a result, verify:
+
+- the selected type exists in capabilities;
+- validation passed;
+- source record IDs remain present in explanation lineage;
+- warnings and assumptions are visible;
+- requested interactions are supported;
+- the branding on/off state is documented so live view and exports stay consistent;
+- the preview URL or output artifact (JSON/SVG/PNG/JPEG) is provided to the user.
+
+## Branding (Signature) Defaults
+
+- Default `branding: true`: a low-contrast `Powered by iChart.js` signature appears in the bottom-right corner, synchronized across live rendering, PNG/SVG raster export, and JSON state persistence.
+- Disable explicitly with `branding: false` on the Spec or Theme: the signature text is removed from all surfaces, and the reserved bottom padding is released.
+- Consistency is enforced by a single gate inside `buildScene()`; live view and every export format remain 100% aligned.
+
+## Complete Executable Example
+
+Run:
+
+```bash
+npm run example:agent
+```
+
+Read [`../../examples/agent-workflow.mjs`](../../examples/agent-workflow.mjs) for a complete inspect, plan, build, validate, render, explain, export, and destroy workflow.
+
+For interactive verification, start `npm run playground` and open `http://localhost:3000/playground/agent-workbench.html`. The top-right Export buttons on every Gallery page exercise the PNG, SVG, and JSON download flows.
+
+For visual style selection and live switching, read [Visual Style and Themes](theme-guide.md) and open `http://localhost:3000/playground/theme-gallery.html`.
+
+## Guardrails
+
+- Prefer Bar over Pie when category cardinality is high.
+- Require explicit indicator domains for Radar, especially with mixed units.
+- Distinguish missing Heatmap cells from zero values.
+- Do not infer schedule dates, dependencies, working calendars, or forecast confidence.
+- Do not enable interactions that the chart capability does not declare.
+- Do not generate Map or 3D Specs; those types are outside the current contract.
+- Treat structured export errors (valid=false, code=...) as first-class diagnostics; do not silently fall back to a different format.