@taylorwong/ichartjs 2.0.3 → 2.0.5

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 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()`.
+- Aligned Canvas and SVG background, fill, stroke, and transparent-paint behavior; normalized `theme.branding` into the shared branding contract.
+- Hardened the Playground server's port detection, path containment, malformed URI handling, and escaped 404 responses.
+- Added bilingual usage-scenario guidance for Runtime integration, Coding Agents, the official Skill, one-off artifacts, project/diagram workflows, and CI reports.
+- Expanded export, headless Canvas, branding, documentation, and package regression coverage.
+
+## 2.0.4 - 2026-09-18
+
+- Synchronized current Agent documentation, scoped package paths, GitHub fallback instructions, Skill links, Playground links, and release status.
+- Corrected Runtime and Playground version displays to `2.0.4`.
+- Marked the original `2.0.0` release-readiness document as historical and added stronger documentation consistency checks.
+
+## 2.0.3 - 2026-09-17
+
+- Completed Iteration 8 acceptance documentation and added the author-only release SOP.
+- Added README and official Skill release guardrails for the scoped npm package and controlled publishing workflow.
+
+## 2.0.2 - 2026-09-17
+
+- Fixed Line and Area rendering so `fill: 'none'` does not create an unintended filled area.
+
+## 2.0.1 - 2026-09-17
+
+- Added dual-engine raster export, branding signature support, and synchronized documentation and TypeScript declarations.
+
 ## 2.0.0 - 2026-09-16
 
 - Added Iteration 9's lightweight visual style system with adaptive modes, semantic presets and palettes, live switching, contrast diagnostics, Agent recommendations, bilingual guidance, and Theme Gallery while retaining version `2.0.0`.

package/README.md

@@ -2,6 +2,8 @@
 
 iChart.js is an Agent-first, renderer-independent visualization runtime. An Agent can inspect data, choose an appropriate chart, generate and validate a JSON-friendly Spec, render it with SVG or Canvas, and explain the result through public APIs.
 
+Use it in one of three ways: integrate the Runtime into a web project, let a Coding Agent modify a project, or install the official Skill so an Agent can orchestrate chart selection and delivery. The Runtime produces interactive pages, SVG/PNG/JPEG artifacts, JSON checkpoints, and integration code; the Skill does not replace the Runtime.
+
 ## For AI Agents
 
 Do not guess chart types or configuration fields from source code. Use the public planning contract:
@@ -20,10 +22,11 @@ getCapabilities
 
 | Need | Entry point |
 | --- | --- |
-| Runtime and Agent planning APIs | `ichartjs` |
-| Machine-readable capability manifest | `ichartjs/capabilities.json` |
-| Intent and chart recipes | `ichartjs/recipes/*` |
+| Runtime and Agent planning APIs | `@taylorwong/ichartjs` |
+| Machine-readable capability manifest | `@taylorwong/ichartjs/capabilities.json` |
+| Intent and chart recipes | `@taylorwong/ichartjs/recipes/*` |
 | Agent quickstart | [`docs/agent/quickstart.md`](docs/agent/quickstart.md) |
+| Usage scenarios and output formats | [`docs/agent/usage-scenarios.md`](docs/agent/usage-scenarios.md) |
 | Chinese quickstart | [`docs/agent/zh-CN/quickstart.md`](docs/agent/zh-CN/quickstart.md) |
 | 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) |
@@ -36,7 +39,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.1`.
+As a fallback for environments without npm access, install directly from GitHub: `npm install github:wanghetommy/ichartjs#v2.0.5`.
 
 ### Optional Agent Skill
 
@@ -52,7 +55,7 @@ From a repository checkout, install it into Codex with:
 cp -R skills/ichartjs "${CODEX_HOME:-$HOME/.codex}/skills/"
 ```
 
-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/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.
+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.
 
 ### Agent workflow
 
@@ -140,9 +143,14 @@ npm run playground
 - Playground Home: `http://localhost:3000/playground/index.html`
 - Agent Workbench: `http://localhost:3000/playground/agent-workbench.html`
 - Complete Gallery: `http://localhost:3000/playground/project-gallery.html`
+- Foundational Gallery: `http://localhost:3000/playground/foundational-gallery.html`
 - Theme Gallery: `http://localhost:3000/playground/theme-gallery.html`
+- Business Editing: `http://localhost:3000/playground/editing.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`
 
 ## For Developers
 
@@ -199,7 +207,7 @@ Contributors should:
 1. Open PRs / commit only to `develop`
 2. Ensure `npm run agent:check` and `npm test` are green
 
-Full author-only release SOP (exact 13-step sequence + must-not rules + rollback procedure):
+Full author-only release SOP (preconditions, release sequence, must-not rules, and rollback procedure):
 👉 [`docs/agent/development/release-sop.md`](docs/agent/development/release-sop.md)
 
 Start with [`docs/agent/quickstart.md`](docs/agent/quickstart.md). Detailed runtime, charting, project, diagram, and editing contracts live in [`docs/agent/`](docs/agent/).

package/docs/agent/README.md

@@ -11,6 +11,7 @@ This is the user-facing Agent entry point for iChart.js 2.0. Read this file firs
 ## Start Here
 
 - [Agent Quickstart](quickstart.md): install, import, plan, validate, render, explain, and self-check.
+- [Usage Scenarios](usage-scenarios.md): choose Runtime, Coding Agent, Skill, one-off artifact, project, diagram, or CI usage and select the right output.
 - [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.
@@ -21,7 +22,7 @@ This is the user-facing Agent entry point for iChart.js 2.0. Read this file firs
 - [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.
+The 2.0 API is Spec-first. Import from `@taylorwong/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
 

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

@@ -2,9 +2,11 @@
 
 Use this guide with Codex, WorkBuddy, and similar Agents that can read a repository, edit JavaScript, execute tests, and open a local browser preview.
 
+For the complete choice between project integration, one-off artifacts, Skill orchestration, and CI output, read [Usage Scenarios](usage-scenarios.md).
+
 ## 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.
+iChart.js is a JavaScript UI component library. The coding Agent writes or updates the host application and calls the public `@taylorwong/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.
 
@@ -16,7 +18,7 @@ Inside a consumer project:
 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.
+Do not install the unscoped npm registry package named `ichartjs`; it is an npm security holding package and is not this project. The published package is `@taylorwong/ichartjs`.
 
 Inside this repository:
 
@@ -46,7 +48,7 @@ If the host supports named Skill invocation, the request may start with `Use $ic
 ## Required Workflow
 
 1. Inspect existing application structure and local instructions.
-2. Import public APIs from `ichartjs`.
+2. Import public APIs from `@taylorwong/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()`.
@@ -80,9 +82,11 @@ Use `examples/agent-workflow.mjs` for the full executable lifecycle.
 
 ## Acceptance
 
-- The application imports only `ichartjs`, not source internals.
+- The application imports only `@taylorwong/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.
+
+The final Agent response should also state whether the deliverable is a live component, code change, SVG/PNG/JPEG artifact, JSON checkpoint, or a combination of these.

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

@@ -1,5 +1,7 @@
 # iChart.js 2.0 Final Release Readiness
 
+> Historical record. This document describes the original `2.0.0` source-release decision and is superseded by the published `2.0.x` release line. Use `release-sop.md` for current releases.
+
 Date: 2026-09-16
 
 ## Decision

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

@@ -0,0 +1,32 @@
+# Iteration 10 — Export Contract Hardening
+
+Iteration 10A hardens the v2.0 export contract without adding chart types or changing chart behavior. The work targets `v2.0.5`, stays on the `2.0.x` line, and keeps the existing dual-engine, single-Scene-Graph architecture.
+
+## 10A — Export Contract Hardening
+
+- Keep JSON, SVG, PNG, and JPEG export type detection deterministic.
+- Return stable structured errors for unknown formats and unavailable headless raster paths.
+- Support JSON `string`, `object`, `dataurl`, and `blob` representations.
+- Provide an explicit `exportAsync()` path for optional Node `canvas` raster export.
+- Prevent headless Canvas calls from throwing when no canvas surface is mounted.
+- Keep Canvas and SVG fill, stroke, background, and transparent-paint semantics aligned.
+- Resolve `theme.branding` into the normalized top-level branding contract.
+- Fix playground port detection, path traversal checks, malformed URI handling, and escaped 404 paths.
+- Add regression coverage for export representations, unsupported types, headless Canvas, and theme branding.
+
+## Acceptance
+
+- `npm run agent:check` passes.
+- `npm run example:agent` passes.
+- `git diff --check` passes.
+- Browser preview remains available at `http://localhost:3000/playground/project-gallery.html` through `npm run playground`.
+- No new public chart type or chart behavior is introduced by 10A.
+
+## v2.0.5 Release Readiness
+
+- Package, Runtime, Playground, documentation home, GitHub fallback instructions, Changelog, and Roadmap identify `2.0.5` consistently.
+- `npm run agent:check` passes with 61 tests, 16 chart types, 24 edit commands, and 7 business schemas.
+- `npm run example:agent` and `git diff --check` pass.
+- `npm pack --dry-run` reports `@taylorwong/ichartjs@2.0.5`, 83 package entries, and includes the English/Chinese usage guides plus this Iteration 10 record.
+- npm identity is `taylorwong`, Registry is `https://registry.npmjs.org/`, and the currently published package remains `2.0.4` before release.
+- Author-only commit, tag, push, npm publish, and `develop` to `master` merge remain pending under `release-sop.md`.

package/docs/agent/development/release-sop.md

@@ -8,13 +8,13 @@
 >
 > **Agent Policy:** An Agent MUST NOT initiate any step in this SOP on its own.
 > It MAY execute the sequence **only when explicitly instructed** by the author
-> (e.g. "publish v2.0.3", "commit and release patch", or equivalent intent).
+> (e.g. "publish vX.Y.Z", "commit and release patch", or equivalent intent).
 
 ## 0. Preconditions (MUST ALL be green)
 
 0.  `git status -sb` → on `develop`, working tree clean
 1.  `npm run check` → exit 0
-2.  `npm test` → exit 0 (60/60)
+2.  `npm test` → exit 0 (all current tests pass)
 3.  `npm run docs:check` → exit 0
 4.  `npm run agent:check` → exit 0
 5.  `npm whoami` → output = `taylorwong`

package/docs/agent/development/roadmap.md

@@ -1,6 +1,6 @@
 # iChart.js 2.0 Roadmap
 
-> Roadmap baseline: 2026-09-14. Geographic charts and 3D rendering remain out of scope until explicitly reintroduced.
+> 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.
 
 ## Current Status
 
@@ -11,8 +11,9 @@
 - 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 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.
+- The original `2.0.0` readiness record is historical and superseded by the published `2.0.x` releases. Current release checks are defined by `docs/agent/development/release-sop.md`.
 
 ## Iteration 4 — Agent Data Contract and Business Editing
 

package/docs/agent/frontend-integration.md

@@ -2,13 +2,15 @@
 
 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.
 
+This is the production component path. For one-off files or Agent-led repository changes, use [Usage Scenarios](usage-scenarios.md) and the [Coding Agent Integration](coding-agent-integration.md) guide instead.
+
 ## 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`.
+For environments without npm registry access, install from GitHub as a fallback: `npm install github:wanghetommy/ichartjs#v2.0.5`.
 
 Use the package through a bundler or another environment that resolves npm ESM imports:
 
@@ -64,3 +66,5 @@ Add these only in an application that has a demonstrated requirement. Do not dup
 ## Preview
 
 Within this repository, run `npm run playground` and open `http://localhost:3000/playground/project-gallery.html` to inspect every public chart type.
+
+In a consumer application, use that application's own development server and return its URL. The Playground is an example and acceptance surface, not a required production dependency.

package/docs/agent/quickstart.md

@@ -4,6 +4,8 @@ Use this guide when an Agent needs to turn user data or project information into
 
 ## Import Surface
 
+Choose the integration mode before starting: use the Runtime for a product component, the Coding Agent guide when modifying a repository, or the official Skill when an Agent must repeatedly plan and deliver charts. See [Usage Scenarios](usage-scenarios.md) for the input/output contract.
+
 ```js
 import {
   createChart,
@@ -15,14 +17,14 @@ import {
 } 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.
+Agents and developers use the same `@taylorwong/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.
+- `@taylorwong/ichartjs/capabilities.json`: machine-readable catalog, including per-chart exports, branding, and interaction declarations.
+- `@taylorwong/ichartjs/recipes/foundational-analysis`: foundational chart recipes.
+- `@taylorwong/ichartjs/recipes/project-management`: project intelligence recipes.
+- `@taylorwong/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.
@@ -140,10 +142,11 @@ 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)
+// PNG raster (browser sync; Node headless uses the optional canvas package)
 const pngDataUrl = typeof document !== 'undefined'
   ? chart.toDataURL('image/png')
   : null;
+const headlessPng = await chart.exportAsync({ type: 'png' });
 
 // Browser-only convenience downloads
 if (typeof document !== 'undefined') {

package/docs/agent/runtime-contract.md

@@ -50,7 +50,7 @@ When `branding:false`, no signature text appears on the chart or any exported ar
 ## Exports and Downloads
 
 iChart.js exports use a **dual-engine single-source architecture**. Every artifact shares the same Scene Graph produced by `buildScene()`, and the on-screen renderer is fully decoupled from the export backend:
-1. **PNG / JPEG (raster)**: always drawn by a `CanvasRenderer` replaying the shared Scene Graph synchronously. In headless Node, install the optional `canvas` npm package to enable.
+1. **PNG / JPEG (raster)**: always drawn by a `CanvasRenderer` replaying the shared Scene Graph. Browser export is synchronous; Node headless export uses `exportAsync()` with the optional `canvas` npm package.
 2. **SVG (vector)**: serialized from an `SVGRenderer` DOM tree (browser) or assembled as a pure string with zero dependencies (headless). Includes XML 1.0 header, expanded font properties, and accessibility attributes.
 3. **JSON (reconstructable)**: serializes the current `spec` plus `getState()`, used for persistence, agent self-check, and cross-environment rebuild.
 
@@ -64,21 +64,21 @@ The signature gate inside `buildScene()` guarantees that live rendering, SVG exp
 |-------------|------------------------|--------------------------|------------------------------|
 | JSON        | ✅                      | ✅                        | ✅                            |
 | SVG         | ✅                      | ✅                        | ✅                            |
-| PNG / JPEG  | ✅ true raster, sync    | ❌ structured `HEADLESS_EXPORT_UNSUPPORTED` | ✅ |
+| PNG / JPEG  | ✅ true raster, sync    | ❌ structured `HEADLESS_EXPORT_UNSUPPORTED` | ✅ via `exportAsync()` |
 
 ### Public Export APIs
 
 - `chart.toDataURL(type='image/png')` → data URL string or structured ExportError.
 - `chart.toBlob(type='image/png')` → Blob or ExportError (headless returns `BLOB_HEADLESS`).
 - `chart.export({ type, as })` → sync string / JSON object / Blob / ExportError. `as` accepts `string`, `dataurl`, `blob`, `object` (JSON only).
-- `chart.exportAsync({ type, as })` → Promise wrapper for future async scenarios.
+- `chart.exportAsync({ type, as })` → Promise export path; enables optional Node `canvas` raster output.
 - `chart.download({ type })` / `downloadPNG()` / `downloadSVG()` / `downloadJSON()` → triggers a browser save-as. In headless, falls back to returning the raw string or structured error.
 
 ### Structured Error Shape
 
 All export/download methods return a stable `{ valid:false, code, message?, suggestion?, rasterCode? }` object on failure for reliable agent automation. Common `code` values:
-- `HEADLESS_EXPORT_UNSUPPORTED`: raster export requested in headless without the optional `canvas` package.
-- `BLOB_HEADLESS`: `toBlob` or `as=blob` used in headless (Blob requires a browser runtime).
+- `HEADLESS_EXPORT_UNSUPPORTED`: synchronous raster export in headless, or raster export without a usable canvas adapter.
+- `BLOB_HEADLESS`: synchronous `toBlob` or headless SVG `as=blob` has no mounted/browser serialization surface; use `exportAsync()` for Node raster or `as=dataurl`/`as=string`.
 - `DOWNLOAD_HEADLESS`: `chart.download*()` in headless; use `chart.export()` instead.
 - `EXPORT_TYPE_UNSUPPORTED`: unrecognized export type.
 

package/docs/agent/usage-scenarios.md

@@ -0,0 +1,161 @@
+# iChart.js Usage Scenarios
+
+iChart.js has three layers:
+
+1. **Runtime** — `@taylorwong/ichartjs` executes planning, validation, rendering, interaction, editing, and export.
+2. **Skill** — `skills/ichartjs/SKILL.md` teaches an Agent how to choose a chart, preserve data lineage, validate a Spec, and report the result.
+3. **Host project** — the user's web app, Node script, CI job, or Agent workspace provides data, lifecycle, routing, storage, and delivery.
+
+The Skill is not a second renderer or service. A Skill-enabled Agent still needs a JavaScript host to render an interactive chart or create a file.
+
+## Choose a Scenario
+
+| Need | Use | Runtime location | Typical output |
+| --- | --- | --- | --- |
+| Add a chart to a product | Frontend integration | User's browser app | Interactive SVG or Canvas chart |
+| Ask Codex to change an existing app | Coding Agent + Runtime | Repository and app dev server | Code changes, Spec, tests, preview URL |
+| Reuse charting guidance across Agents | Skill + Runtime | Agent workspace and target project | Validated code, artifacts, explanation |
+| Create a one-off visualization | Node script or standalone HTML | Node.js or browser | SVG, PNG/JPEG, JSON, or HTML |
+| Build project or delivery views | Project scenario + Runtime | Project dashboard | Gantt, Burndown, Timeline, analytics |
+| Build a process or architecture view | Diagram scenario + Runtime | Web app or document workflow | Flow/Swimlane UI, SVG, JSON |
+| Generate scheduled reports | Node script + Runtime | CI or report job | SVG/PNG files and JSON checkpoints |
+
+## Output Contract
+
+| Output | Best for | API or delivery |
+| --- | --- | --- |
+| Interactive page | Product dashboards, editors, analysis screens | `createChart()` mounted into a DOM container |
+| SVG DOM | Accessibility, keyboard interaction, diagrams, printing | `renderer: 'svg'` |
+| SVG file/string | Documents, email, vector handoff, zero-dependency headless output | `chart.export({ type: 'svg' })` |
+| PNG/JPEG | Presentations, chat attachments, image reports | Browser `toDataURL()` or Node `exportAsync()` with optional `canvas` |
+| JSON Spec/state | Persistence, Agent checkpoints, cross-environment rebuild | `chart.export({ type: 'json' })` |
+| Data URL or Blob | Embedding or browser download | `as: 'dataurl'` or browser download APIs |
+| Code snippet | Developer handoff or generated page | `createChart()` integration code |
+| Explanation/state | Agent self-check and user-facing audit | `chart.explain()` and `chart.getState()` |
+
+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.
+
+## Scenario 1: Integrate into a Web Project
+
+Install the runtime in the host application:
+
+```bash
+npm install @taylorwong/ichartjs@^2
+```
+
+Use the normal component lifecycle:
+
+```js
+import { createChart } from '@taylorwong/ichartjs';
+
+const chart = createChart({
+  container: '#chart',
+  type: 'line',
+  renderer: 'svg',
+  data: { values: rows },
+  encoding: {
+    x: { field: 'month', type: 'category' },
+    y: { field: 'sales', type: 'quantitative' }
+  },
+  accessibility: { enabled: true }
+});
+```
+
+The host application owns data loading, authentication, routing, persistence, and state management. Call `setData()` for row changes, `update()` for Spec changes, and `destroy()` before replacing the component.
+
+Use this scenario for dashboards, admin pages, project management products, editors, and embedded analytics.
+
+## Scenario 2: Ask a Coding Agent to Modify a Project
+
+Give the Agent the intent, data source, desired output, and acceptance requirement:
+
+```text
+Use @taylorwong/ichartjs in the current project. Inspect the order data,
+choose and validate a monthly sales chart, add it to the existing analysis
+page, run focused tests, and return the exact preview URL. Keep assumptions,
+warnings, record lineage, and unsupported requests visible.
+```
+
+The Agent should return:
+
+- changed files and the validated Spec;
+- field mappings and chart-selection reasons;
+- assumptions, warnings, and unsupported requests;
+- focused test results and self-check state;
+- the host project's exact preview URL and manual acceptance steps.
+
+The repository Playground is only for iChart.js examples:
+`npm run playground` → `http://localhost:3000/playground/project-gallery.html`.
+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:
+
+```text
+Use the iChart.js Skill. Read this dataset, create a project Burndown,
+validate the Spec, generate a browser preview, and also export SVG and JSON.
+Return the preview URL, artifact paths, warnings, assumptions, and lineage.
+```
+
+The Skill routes the task to the public Runtime API and scenario guides. It does not replace the package, add a service endpoint, or create a second chart-selection implementation.
+
+If the host can edit and run a JavaScript project, the output can be an interactive page. If it cannot run JavaScript, request an SVG, JSON, or code artifact instead.
+
+## Scenario 4: Create a One-Off Artifact
+
+For a single chart, an Agent can create a small ESM script or standalone HTML page.
+
+Recommended outputs:
+
+- `chart.svg` for vector documents and zero-dependency headless generation;
+- `chart.json` for a reproducible Spec and runtime checkpoint;
+- `chart.png` or `chart.jpeg` for presentations and image sharing;
+- `index.html` plus JavaScript when the recipient needs interaction.
+
+Headless SVG and JSON work without an extra production dependency. Headless PNG/JPEG uses `chart.exportAsync()` and the optional `canvas` package. Do not add Python, MCP, HTTP, or a CLI merely to create one chart.
+
+## Scenario 5: Project and Diagram Workflows
+
+Use the project and diagram contracts when the data has project semantics rather than generic numeric series:
+
+- `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.
+
+Preserve stable record, node, edge, lane, group, and port IDs. For business edits, return a preview before commit and include the audit result.
+
+## Scenario 6: CI and Scheduled Reports
+
+Use a Node ESM script in the report job:
+
+```js
+const svg = chart.export({ type: 'svg' });
+const json = chart.export({ type: 'json' });
+const png = await chart.exportAsync({ type: 'png' });
+```
+
+Store JSON as the reproducible checkpoint and SVG/PNG as presentation artifacts. Report export errors as structured results instead of silently substituting another format.
+
+## Boundaries
+
+- iChart.js is a JavaScript UI/runtime package, not a data service.
+- A Skill gives Agents workflow instructions; it does not render without a JavaScript host.
+- The host application owns authentication, storage, sharing, and application routing.
+- There is no need for a core CLI, MCP server, HTTP service, or Python API for ordinary usage.
+- If data is prepared in Python, export JSON/CSV and let a JavaScript process render the chart.
+- Do not generate maps or 3D charts unless `getCapabilities()` explicitly declares them.
+
+## Agent Delivery Checklist
+
+Every Agent response should state:
+
+1. selected chart/view and the reason;
+2. input fields, transforms, and stable IDs;
+3. validated Spec or structured repair request;
+4. assumptions, warnings, unsupported requests, and accessibility choices;
+5. explanation/state self-check results;
+6. exact preview URL, code files, or artifact paths;
+7. export format and any optional dependency required.
+
+Related guides: [Quickstart](quickstart.md), [Frontend Integration](frontend-integration.md), [Coding Agent Integration](coding-agent-integration.md), [Runtime Contract](runtime-contract.md), [Project Scenario](project-scenario.md), and [Diagram Scenario](diagram-scenario.md).

package/docs/agent/zh-CN/README.md

@@ -4,6 +4,7 @@
 
 ## 选择场景
 
+- [使用场景与输出](usage-scenarios.md)
 - [Agent 快速上手](quickstart.md)
 - [编码 Agent 集成](coding-agent-integration.md)
 - [前端项目集成](frontend-integration.md)

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

@@ -14,7 +14,7 @@ iChart.js 是 JavaScript UI 图表组件库。编码 Agent 负责修改宿主前
 npm install @taylorwong/ichartjs@^2
 ```
 
-npm Registry 中无作用域的 `ichartjs` 当前是安全占位包，并非本项目。正式 npm scope 确认前请从 GitHub 安装。
+npm Registry 中无作用域的 `ichartjs` 是安全占位包，并非本项目。正式包名是 `@taylorwong/ichartjs`，优先从 npm 安装。
 
 Codex、WorkBuddy 和其他兼容 Agent Skills 的宿主可共同使用 `skills/ichartjs`。从仓库检出目录安装到 Codex：
 

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

@@ -9,13 +9,13 @@
 
 ## 当前能力
 
-已支持节点、边、泳道、Group、Port、四种布局、三种路由、节点拖动、多选、对齐、网格吸附、键盘移动和 Undo/Redo。
+已支持节点、边、泳道、Group、Port、四种布局、三种路由、节点拖动、多选、对齐、网格吸附、键盘移动、Copy/Paste、Group 折叠展开、Port 键盘连线和 Undo/Redo。
 
 当前限制：
 
 - Group 只支持平级 Group，不支持嵌套。
-- Port 可显示并参与路由，但 Port 拖拽连线尚未完成。
-- Copy/Paste 和 Group 折叠展开尚未完成。
+- Group bounds 由成员几何和 `group.padding` 推导；`resizeGroup` 会缩放成员位置和尺寸，不持久化第二个 Group 矩形。
+- Canvas 提供基础无障碍文本，SVG 提供更丰富的 Diagram 语义。
 
 ## Agent 流程
 

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

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

package/docs/agent/zh-CN/quickstart.md

@@ -15,9 +15,9 @@ import {
 } from '@taylorwong/ichartjs';
 ```
 
-- `ichartjs`：统一的 Agent 规划与 Runtime API。
-- `ichartjs/capabilities.json`：机器可读能力清单，包含逐图表导出、署名和交互声明。
-- `ichartjs/recipes/*`：基础分析、项目管理和 Diagram Recipes。
+- `@taylorwong/ichartjs`：统一的 Agent 规划与 Runtime API。
+- `@taylorwong/ichartjs/capabilities.json`：机器可读能力清单，包含逐图表导出、署名和交互声明。
+- `@taylorwong/ichartjs/recipes/*`：基础分析、项目管理和 Diagram Recipes。
 - `skills/ichartjs/SKILL.md`：适用于 Codex、WorkBuddy 等 Agent Skills 兼容宿主的可选编排层。
 
 Agent 与开发者使用同一个 ESM 入口。编码 Agent 的完整方式见 [编码 Agent 集成](coding-agent-integration.md)，普通应用集成见 [前端项目集成](frontend-integration.md)。
@@ -53,10 +53,10 @@ const obj = chart.export({ type: 'json', as: 'object' });
 const svg = chart.export({ type: 'svg' });
 const svgDataUrl = chart.export({ type: 'svg', as: 'dataurl' });
 
-// 3. PNG / JPEG：同步真光栅
-//    浏览器：任意 renderer 均可
-//    无头：需安装 npm i canvas，否则返回结构化错误 code=HEADLESS_EXPORT_UNSUPPORTED
+// 3. PNG / JPEG：浏览器同步真光栅；Node 无头使用异步导出
+//    Node 无头：安装 npm i canvas 后，exportAsync() 可生成真光栅
 const png = typeof document !== 'undefined' ? chart.toDataURL('image/png') : null;
+const headlessPng = await chart.exportAsync({ type: 'png' });
 ```
 
 ## Agent 输出要求

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

@@ -48,7 +48,7 @@ iChart.js 默认在所有图表右下角显示低对比度的品牌署名（`Pow
 ## 导出与下载
 
 iChart.js 导出采用**双底层单源架构**，所有产物共享 `buildScene()` 生成的同一份 Scene Graph，**画面显示用的 renderer 和导出底层完全解耦**：
-1. **PNG/JPEG（光栅）**：底层用 `CanvasRenderer` 重绘 Scene Graph，同步输出真光栅文件；无头环境安装 `canvas` npm 包即可支持。
+1. **PNG/JPEG（光栅）**：底层用 `CanvasRenderer` 重绘 Scene Graph；浏览器同步输出真光栅文件，无头环境通过 `exportAsync()` 加载可选的 `canvas` npm 包。
 2. **SVG（矢量）**：底层用 `SVGRenderer` DOM 序列化（浏览器）或纯字符串拼装（无头零依赖），支持 XML 1.0 头部、字体拆分、无障碍属性。
 3. **JSON（可重建）**：序列化当前 `spec` + `getState()` 结果，用于持久化、Agent 自检和跨端重建。
 
@@ -62,21 +62,21 @@ iChart.js 导出采用**双底层单源架构**，所有产物共享 `buildScene
 |------------|----------------------------|----------------|--------------------------|
 | JSON       | ✅                          | ✅              | ✅                        |
 | SVG        | ✅                          | ✅              | ✅                        |
-| PNG / JPEG | ✅ 同步真光栅               | ❌ 返回结构化 `HEADLESS_EXPORT_UNSUPPORTED` | ✅ |
+| PNG / JPEG | ✅ 同步真光栅               | ❌ 返回结构化 `HEADLESS_EXPORT_UNSUPPORTED` | ✅ 通过 `exportAsync()` |
 
 ### 公共导出 API
 
 - `chart.toDataURL(type='image/png')` → data URL 字符串或结构化 ExportError。
-- `chart.toBlob(type='image/png')` → Blob 或 ExportError（无头返回 `BLOB_HEADLESS`）。
+- `chart.toBlob(type='image/png')` → Blob 或 ExportError（无头同步路径不提供光栅 Blob）。
 - `chart.export({ type, as })` → 同步返回字符串 / JSON 对象 / Blob / ExportError，`as` 支持 `string`、`dataurl`、`blob`、`object`（仅 JSON）。
-- `chart.exportAsync({ type, as })` → Promise 包装，适配未来异步场景。
+- `chart.exportAsync({ type, as })` → Promise 导出路径；Node 无头环境可通过可选 `canvas` 依赖生成 PNG/JPEG。
 - `chart.download({ type })` / `downloadPNG()` / `downloadSVG()` / `downloadJSON()` → 触发浏览器保存（无头回落到返回字符串或结构化错误）。
 
 ### 错误结构
 
 所有导出/下载方法失败时统一返回 `{ valid:false, code, message?, suggestion?, rasterCode? }` 稳定结构，便于 Agent 自动化判断，常见 `code`：
 - `HEADLESS_EXPORT_UNSUPPORTED`：当前无头环境缺少光栅所需依赖（`canvas`）。
-- `BLOB_HEADLESS`：`toBlob` / `as=blob` 需要浏览器 Blob。
+- `BLOB_HEADLESS`：同步 `toBlob` 无法在当前无头 renderer 上生成光栅 Blob；Node 光栅场景改用 `exportAsync()`。
 - `DOWNLOAD_HEADLESS`：`chart.download*()` 仅在浏览器有 DOM 时可用，无头用 `export`。
 - `EXPORT_TYPE_UNSUPPORTED`：不支持的导出类型。
 

package/docs/agent/zh-CN/usage-scenarios.md

@@ -0,0 +1,152 @@
+# iChart.js 使用场景
+
+iChart.js 可以分成三层：
+
+1. **Runtime**：`@taylorwong/ichartjs`，负责规划、校验、渲染、交互、编辑和导出。
+2. **Skill**：`skills/ichartjs/SKILL.md`，负责指导 Agent 选择图表、保留数据 lineage、校验 Spec 和交付结果。
+3. **宿主项目**：用户自己的 Web 项目、Node 脚本、CI 任务或 Agent 工作区，负责数据、生命周期、路由、存储和交付。
+
+Skill 不是第二套渲染器，也不是服务端。使用 Skill 的 Agent 仍然需要 JavaScript 宿主，才能生成交互页面或文件。
+
+## 场景选择
+
+| 需求 | 使用方式 | 运行位置 | 常见输出 |
+| --- | --- | --- | --- |
+| 在产品中增加图表 | 前端项目集成 | 用户自己的浏览器应用 | 交互式 SVG 或 Canvas 图表 |
+| 让 Codex 修改已有项目 | Coding Agent + Runtime | 代码仓库和项目开发服务器 | 代码、Spec、测试结果、预览地址 |
+| 让多个 Agent 复用图表能力 | Skill + Runtime | Agent 工作区和目标项目 | 校验后的代码、文件、解释结果 |
+| 一次性生成可视化 | Node 脚本或独立 HTML | Node.js 或浏览器 | SVG、PNG/JPEG、JSON、HTML |
+| 项目进度和交付分析 | 项目场景 + Runtime | 项目看板 | Gantt、Burndown、Timeline、分析结果 |
+| 流程或架构图 | Diagram 场景 + Runtime | Web 应用或文档流程 | Flow/Swimlane 页面、SVG、JSON |
+| 定时生成报告 | Node 脚本 + Runtime | CI 或报表任务 | SVG/PNG 文件和 JSON 快照 |
+
+## 输出契约
+
+| 输出 | 适用场景 | API 或交付方式 |
+| --- | --- | --- |
+| 交互式页面 | 产品看板、编辑器、分析页面 | `createChart()` 挂载到 DOM |
+| SVG DOM | 无障碍、键盘交互、Diagram、打印 | `renderer: 'svg'` |
+| SVG 文件/字符串 | 文档、邮件、矢量交付、无头环境 | `chart.export({ type: 'svg' })` |
+| PNG/JPEG | 汇报、聊天附件、图片报告 | 浏览器 `toDataURL()`，或 Node `exportAsync()` + 可选 `canvas` |
+| JSON Spec/state | 持久化、Agent 快照、跨环境重建 | `chart.export({ type: 'json' })` |
+| Data URL/Blob | 页面嵌入或浏览器下载 | `as: 'dataurl'` 或浏览器下载 API |
+| 代码片段 | 开发者集成或生成页面 | `createChart()` 集成代码 |
+| 解释和状态 | Agent 自检和用户审计 | `chart.explain()`、`chart.getState()` |
+
+JSON 是机器可读的事实来源；SVG 和 PNG/JPEG 是视觉交付物；代码是集成交付物；交互页面是产品交付物。
+
+## 场景一：集成到 Web 项目
+
+在宿主项目中安装 Runtime：
+
+```bash
+npm install @taylorwong/ichartjs@^2
+```
+
+```js
+import { createChart } from '@taylorwong/ichartjs';
+
+const chart = createChart({
+  container: '#chart',
+  type: 'line',
+  renderer: 'svg',
+  data: { values: rows },
+  encoding: {
+    x: { field: 'month', type: 'category' },
+    y: { field: 'sales', type: 'quantitative' }
+  },
+  accessibility: { enabled: true }
+});
+```
+
+宿主项目负责数据加载、认证、路由、持久化和状态管理。数据变化使用 `setData()`，Spec 变化使用 `update()`，替换组件前调用 `destroy()`。
+
+适用于管理后台、数据看板、项目管理、流程编辑和嵌入式分析页面。
+
+## 场景二：让 Coding Agent 修改项目
+
+可以这样向 Codex 提需求：
+
+```text
+在当前项目中使用 @taylorwong/ichartjs。检查订单数据，选择并校验月度销售图表，
+把它加入现有分析页面，运行相关测试，并返回准确的预览地址。保留假设、警告、
+record lineage 和不支持请求。
+```
+
+Agent 应返回：
+
+- 修改文件和已校验的 Spec；
+- 字段映射和选图原因；
+- 假设、警告和不支持请求；
+- 测试结果和运行时自检；
+- 宿主项目的准确预览地址和人工验收步骤。
+
+仓库内的 Playground 只用于 iChart.js 示例：`npm run playground` → `http://localhost:3000/playground/project-gallery.html`。如果修改的是其他项目，应返回其他项目自己的开发地址。
+
+## 场景三：作为官方 Skill 使用
+
+在 Codex、WorkBuddy 或其他支持 Agent Skills 的宿主中安装或选择 `skills/ichartjs`：
+
+```text
+使用 iChart.js Skill。读取这份数据，生成项目 Burndown，校验 Spec，
+生成浏览器预览，并额外导出 SVG 和 JSON。返回预览地址、文件路径、
+警告、假设和 lineage。
+```
+
+Skill 会把任务路由到公开 Runtime API 和场景文档。它不会替代 npm 包、增加服务端点，也不会维护第二套选图逻辑。
+
+如果宿主可以编辑并运行 JavaScript 项目，输出可以是交互页面；如果不能运行 JavaScript，应要求输出 SVG、JSON 或代码文件。
+
+## 场景四：一次性生成文件
+
+Agent 可以创建一个 ESM 脚本或独立 HTML 页面，输出：
+
+- `chart.svg`：矢量文档和零额外依赖的无头输出；
+- `chart.json`：可复现的 Spec 和运行时快照；
+- `chart.png` 或 `chart.jpeg`：汇报和图片分享；
+- `index.html` 加 JavaScript：需要交互时使用。
+
+无头 SVG 和 JSON 不需要额外生产依赖；无头 PNG/JPEG 使用 `chart.exportAsync()`，并安装可选 `canvas`。一次性制图不应额外引入 Python、MCP、HTTP 服务或 CLI。
+
+## 场景五：项目和 Diagram
+
+- `gantt`、`timeline`、`milestone`、`burndown`：项目进度和交付计划；
+- 项目分析：capacity、velocity、release forecast、risk、issue aging；
+- `flow`、`swimlane`：流程、责任、分组、Port 和受控编辑。
+
+保留稳定的 record、node、edge、lane、group、port ID。业务编辑先返回 preview，确认后再 commit，并返回审计结果。
+
+## 场景六：CI 和定时报表
+
+在 Node ESM 脚本中生成：
+
+```js
+const svg = chart.export({ type: 'svg' });
+const json = chart.export({ type: 'json' });
+const png = await chart.exportAsync({ type: 'png' });
+```
+
+建议把 JSON 作为可复现快照，把 SVG/PNG 作为视觉交付物。导出失败时返回结构化错误，不要静默替换格式。
+
+## 边界
+
+- iChart.js 是 JavaScript UI/Runtime，不是数据服务。
+- Skill 只提供 Agent 工作流指导；没有 JavaScript 宿主时不能直接渲染。
+- 宿主项目负责认证、存储、分享和应用路由。
+- 普通使用不需要核心 CLI、MCP、HTTP 服务或 Python API。
+- 如果数据在 Python 中准备，输出 JSON/CSV，再由 JavaScript 进程渲染。
+- 除非 `getCapabilities()` 明确声明，否则不要生成地图或 3D 图表。
+
+## Agent 交付清单
+
+每次 Agent 返回结果都应包含：
+
+1. 选择的图表/视图及原因；
+2. 输入字段、转换和稳定 ID；
+3. 已校验 Spec 或结构化修复请求；
+4. 假设、警告、不支持请求和无障碍选择；
+5. `explain/state` 自检结果；
+6. 准确预览地址、代码文件或产物路径；
+7. 导出格式和可选依赖。
+
+相关文档：[快速上手](quickstart.md)、[前端集成](frontend-integration.md)、[Coding Agent 集成](coding-agent-integration.md)、[Runtime 契约](runtime-contract.md)、[项目场景](project-scenario.md)、[Diagram 场景](diagram-scenario.md)。

package/docs/manifests/capabilities.json

@@ -6,6 +6,7 @@
   "agentPlanning": "src/index.mjs#planChart",
   "agentExplanation": "Chart#explain",
   "agentQuickstart": "docs/agent/quickstart.md",
+  "usageScenarios": "docs/agent/usage-scenarios.md",
   "agentWorkflowExample": "examples/agent-workflow.mjs",
   "officialSkill": "skills/ichartjs/SKILL.md",
   "scenarios": {
@@ -22,22 +23,22 @@
     "preview": true,
     "json": true,
     "svg": true,
-    "png": "Node headless PNG requires the optional `canvas` npm package (createCanvas). Otherwise use chart.export({type:\"svg\"})."
+    "png": "Node headless PNG requires the optional `canvas` npm package and chart.exportAsync({type:\"png\"}). Otherwise use chart.export({type:\"svg\"})."
   },
   "export": {
     "types": ["png", "jpeg", "svg", "json"],
     "mime": { "png": "image/png", "jpeg": "image/jpeg", "svg": "image/svg+xml", "json": "application/json" },
     "browser": { "png": true, "jpeg": true, "svg": true, "json": true },
     "headless": {
-      "png": "optional: install the `canvas` npm package for createCanvas",
+      "png": "optional: install the `canvas` npm package for createCanvas and use exportAsync",
       "jpeg": "same as png",
       "svg": true,
       "json": true
     },
     "methods": {
-      "exportPNG": "chart.export({ type:\"png\" }) returns base64 data URL (browser); pass as:\"blob\" for a Blob. In Node headless either install the canvas package or fall back to SVG.",
+      "exportPNG": "chart.export({ type:\"png\" }) returns a browser data URL. In Node headless use chart.exportAsync({ type:\"png\" }) after installing the optional canvas package, or fall back to SVG.",
       "exportSVG": "chart.export({ type:\"svg\" }) returns the SVG string in both browser and headless; as:\"dataurl\" for embeds, as:\"blob\" for a Blob (browser).",
-      "exportJSON": "chart.export({ type:\"json\" }) returns pretty JSON; use as:\"object\" to get the parsed {version,spec,state}.",
+      "exportJSON": "chart.export({ type:\"json\" }) returns pretty JSON; use as:\"object\", as:\"dataurl\", or as:\"blob\" for the corresponding representation.",
       "downloadPNG": "chart.downloadPNG() triggers a browser save-as dialog (filename derived from title + timestamp).",
       "downloadSVG": "chart.downloadSVG() same semantics as downloadPNG but for SVG.",
       "downloadJSON": "chart.downloadJSON() saves {version,spec,state} as a .json document.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taylorwong/ichartjs",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "Agent-first, renderer-independent charting and project visualization runtime",
   "type": "module",
   "main": "./src/index.mjs",

package/skills/ichartjs/SKILL.md

@@ -7,6 +7,8 @@ description: Plan, validate, render, explain, and safely edit iChart.js visualiz
 
 Use the public Agent contract as the source of truth. Do not infer capabilities from renderer internals or duplicate chart-selection logic in generated code.
 
+Read [`docs/agent/usage-scenarios.md`](../../docs/agent/usage-scenarios.md) when the request is ambiguous about whether the output should be a live project component, a Coding Agent change, a Skill-generated artifact, or a scheduled report.
+
 ## Source and Runtime Setup
 
 - Official repository: `https://github.com/wanghetommy/ichartjs`
@@ -35,16 +37,24 @@ Do not install the unscoped npm registry package named `ichartjs`; it is current
 10. Provide an exact preview URL or artifact path and report assumptions, warnings, and deferred checks.
 11. Prefer `theme: { mode: 'auto', preset, palette }`; preserve explicit user style choices and use `chart.setTheme()` for live switching.
 
-Use `ichartjs` for package imports. Use `examples/agent-workflow.mjs` as the executable baseline when working in the repository.
+Use `@taylorwong/ichartjs` for package imports. Use `examples/agent-workflow.mjs` as the executable baseline when working in the repository.
 
 ## Task Routing
 
+Route by requested output:
+
+- **Live product component**: modify the host JavaScript project and mount `createChart()`; return changed files and the host preview URL.
+- **Coding Agent change**: inspect the repository, use the Runtime, run focused checks, and return the validated Spec plus changed files.
+- **One-off artifact**: generate SVG/JSON directly; use browser PNG export or `exportAsync()` with optional `canvas` for Node PNG/JPEG.
+- **Project or Diagram workflow**: load the matching scenario guide and preserve all stable IDs.
+- **CI/report output**: keep JSON as the reproducible checkpoint and SVG/PNG as presentation artifacts.
+
 - For standard data analysis, read `references/chart-selection.md` and use foundational recipes.
 - For Gantt, Timeline, Milestone, Burndown, capacity, release, risk, or aging, use project capabilities and `agent-recipes/project-management.json`.
 - For Flow or Swimlane, preserve node, edge, lane, group, and port IDs; use diagram recipes and validated edit commands.
 - For business edits, preview first, preserve the preview ID and revision, require confirmation when declared, then commit or reject atomically.
 - For browser deliverables, start `npm run playground` and return the exact maintained Playground URL.
-- Release workflow (npm publish + develop→master merge) is **AUTHOR ONLY**. Read the 13-step SOP in [`docs/agent/development/release-sop.md`](../../../docs/agent/development/release-sop.md). Never initiate any release step unless the author explicitly instructs.
+- Release workflow (npm publish + develop→master merge) is **AUTHOR ONLY**. Read the release SOP in [`docs/agent/development/release-sop.md`](../../docs/agent/development/release-sop.md). Never initiate any release step unless the author explicitly instructs.
 
 ## Guardrails
 

package/src/capabilities.mjs

@@ -137,15 +137,15 @@ export function getCapabilities() {
     mime: { png: 'image/png', jpeg: 'image/jpeg', svg: 'image/svg+xml', json: 'application/json' },
     browser: { png: true, jpeg: true, svg: true, json: true },
     headless: {
-      png: 'optional: install the `canvas` npm package for createCanvas',
+      png: 'optional: install the `canvas` npm package for createCanvas and use exportAsync',
       jpeg: 'same as png',
       svg: true,
       json: true,
     },
     methods: {
-      exportPNG: 'chart.export({ type:"png" }) returns base64 data URL (browser); pass as:"blob" for a Blob. In Node headless either install the canvas package or fall back to SVG.',
+      exportPNG: 'chart.export({ type:"png" }) returns a browser data URL. In Node headless use chart.exportAsync({ type:"png" }) after installing the optional canvas package, or fall back to SVG.',
       exportSVG: 'chart.export({ type:"svg" }) returns the SVG string in both browser and headless; as:"dataurl" for embeds, as:"blob" for a Blob (browser).',
-      exportJSON: 'chart.export({ type:"json" }) returns pretty JSON; use as:"object" to get the parsed {version,spec,state}.',
+      exportJSON: 'chart.export({ type:"json" }) returns pretty JSON; use as:"object", as:"dataurl", or as:"blob" for the corresponding representation.',
       downloadPNG: 'chart.downloadPNG() triggers a browser save-as dialog (filename derived from title + timestamp).',
       downloadSVG: 'chart.downloadSVG() same semantics as downloadPNG but for SVG.',
       downloadJSON: 'chart.downloadJSON() saves {version,spec,state} as a .json document.',

package/src/index.mjs

@@ -54,6 +54,12 @@ function _svgStyleFontParts(raw = '') {
     .trim();
   return { size, weight, family };
 }
+const NO_PAINT_TOKENS = new Set(['none', 'transparent', '']);
+function hasPaint(style, key) {
+  const value = style?.[key];
+  if (value == null) return false;
+  return typeof value !== 'string' || !NO_PAINT_TOKENS.has(value.trim().toLowerCase());
+}
 function sceneToSvgString(scene, spec = {}) {
   const w = Number(scene?.width ?? spec?.width ?? 640);
   const h = Number(scene?.height ?? spec?.height ?? 360);
@@ -114,9 +120,10 @@ function sceneToSvgString(scene, spec = {}) {
     } else {
       tag = 'g';
     }
-    if (node.type === 'path' && !s.fill) attrs.push(`fill="none"`);
-    else if (s.fill) attrs.push(`fill="${_svgEscape(s.fill, 'attr')}"`);
-    if (s.stroke) attrs.push(`stroke="${_svgEscape(s.stroke, 'attr')}"`);
+    if (['path', 'circle', 'rect', 'arc'].includes(node.type)) attrs.push(`fill="${hasPaint(s, 'fill') ? _svgEscape(s.fill, 'attr') : 'none'}"`);
+    else if (node.type === 'text') attrs.push(`fill="${hasPaint(s, 'fill') ? _svgEscape(s.fill, 'attr') : '#0f172a'}"`);
+    if (hasPaint(s, 'stroke')) attrs.push(`stroke="${_svgEscape(s.stroke, 'attr')}"`);
+    else if (s.stroke != null) attrs.push('stroke="none"');
     if (s.strokeWidth) attrs.push(`stroke-width="${s.strokeWidth}"`);
     if (s.opacity != null) {
       const opacity = (node.highlighted || node.selected) ? 1 : s.opacity;
@@ -145,6 +152,29 @@ function sceneToSvgString(scene, spec = {}) {
   lines.push(`</svg>`);
   return lines.join('\n');
 }
+function exportError(code, message, suggestion, extra = {}) { return { valid: false, code, message, suggestion, ...extra }; }
+function dataUrlToBlob(dataUrl, mime) {
+  if (typeof Blob === 'undefined') return exportError('BLOB_HEADLESS', 'Blob is not available in this runtime.', 'Use as=dataurl or as=string.');
+  const comma = dataUrl.indexOf(',');
+  if (comma < 0) return exportError('EXPORT_UNSUPPORTED', 'The renderer returned an invalid data URL.', 'Use chart.export({ type: "svg" }) and inspect the returned string.');
+  const header = dataUrl.slice(0, comma), payload = dataUrl.slice(comma + 1);
+  const bytes = /;base64$/i.test(header)
+    ? Uint8Array.from(atob(payload), value => value.charCodeAt(0))
+    : new TextEncoder().encode(decodeURIComponent(payload));
+  return new Blob([bytes], { type: mime });
+}
+function canvasFactoryFromModule(module) { return module?.createCanvas || module?.default?.createCanvas || null; }
+function renderRasterWithCanvas(createCanvas, spec, scene, rasterType, as) {
+  const canvas = createCanvas(spec.width, spec.height), renderer = new CanvasRenderer({ ...spec });
+  renderer.canvas = canvas;
+  renderer.ctx = canvas.getContext('2d');
+  if (!renderer.ctx) return exportError('HEADLESS_EXPORT_UNSUPPORTED', 'The optional canvas package did not provide a 2D context.', 'Install a supported canvas implementation or use SVG export.');
+  renderer.resize(spec.width, spec.height);
+  renderer.render(scene);
+  const dataUrl = renderer.exportImage(rasterType);
+  if (as === 'blob') return dataUrlToBlob(dataUrl, rasterType);
+  return dataUrl;
+}
 
 export class Chart {
   constructor(input = {}) {
@@ -368,7 +398,11 @@ export class Chart {
     if (this.renderer instanceof SVGRenderer) {
       if (wantsSvg) {
         const headlessEnv = typeof document === 'undefined' || typeof XMLSerializer === 'undefined';
-        const string = headlessEnv ? sceneToSvgString(this.model.scene, this.spec) : this.renderer.exportString();
+        const string = headlessEnv
+          ? sceneToSvgString(this.model.scene, this.spec)
+          : this.renderer.container
+            ? this.renderer.exportString()
+            : (() => { const renderer = new SVGRenderer(this.spec); renderer.resize(this.spec.width, this.spec.height); renderer.render(this.model.scene); return renderer.exportString(); })();
         return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(string)}`;
       }
       if (typeof document !== 'undefined') {
@@ -382,19 +416,17 @@ export class Chart {
       }
       return { valid: false, code: 'HEADLESS_EXPORT_UNSUPPORTED', rasterCode: 'RASTER_EXPORT_UNSUPPORTED', message: `SVG renderer raster ('${type}') in headless requires npm i canvas, or fall back to chart.export({type:"svg"}).`, suggestion: 'Use chart.export({type:"svg"}) for headless, or render with { renderer: "canvas" }.' };
     }
-    if (this.renderer instanceof CanvasRenderer && typeof this.renderer.exportImage === 'function') return this.renderer.exportImage(type);
-    return { valid: false, code: 'EXPORT_UNSUPPORTED', message: `toDataURL('${type}') is not supported with renderer ${this.renderer?.constructor?.name || 'unknown'}.`, suggestion: 'Mount the chart to a DOM container, or switch renderer=canvas for PNG export.' };
+    if (this.renderer instanceof CanvasRenderer && typeof this.renderer.exportImage === 'function' && this.renderer.canvas) return this.renderer.exportImage(type);
+    return exportError(typeof document === 'undefined' ? 'HEADLESS_EXPORT_UNSUPPORTED' : 'EXPORT_UNSUPPORTED', `toDataURL('${type}') is not available because the renderer has no canvas surface.`, 'Mount the chart in a browser or use chart.export({ type: "svg" }).');
   }
   toBlob(type = 'image/png') {
     if (typeof document === 'undefined') return { valid: false, code: 'BLOB_HEADLESS', message: 'toBlob() requires a browser document. Use toDataURL() or export({type:"svg"}) in headless.', suggestion: 'Use chart.export({type:"svg"}) or chart.toDataURL() which both return strings usable in headless.' };
-    const url = this.toDataURL(type);
+    let url;
+    try { url = this.toDataURL(type); } catch (error) { return exportError('EXPORT_UNSUPPORTED', String(error?.message || error), 'Use chart.export({ type: "svg" }) or mount a supported renderer.'); }
     if (!url || typeof url !== 'string') return { valid: false, code: 'EXPORT_UNSUPPORTED', message: "Couldn't produce a data URL for export.", suggestion: (url && url.message) || url };
-    const mime = type.includes('svg') ? 'image/svg+xml' : /^image\//i.test(type) ? type : 'image/png';
-    const comma = url.indexOf(',');
-    const base64 = comma >= 0 && /;base64$/i.test(url.slice(0, comma));
-    const payload = comma >= 0 ? url.slice(comma + 1) : url;
-    const bytes = base64 ? Uint8Array.from(atob(payload), c => c.charCodeAt(0)) : (new TextEncoder()).encode(decodeURIComponent(payload));
-    return new Blob([bytes], { type: mime });
+    const normalizedType = String(type).toLowerCase();
+    const mime = normalizedType.includes('svg') ? 'image/svg+xml' : /^image\//i.test(normalizedType) ? normalizedType : 'image/png';
+    return dataUrlToBlob(url, mime);
   }
   export(options = {}) {
     const rawType = String(options.type || (this.renderer instanceof CanvasRenderer ? 'image/png' : 'image/svg+xml')).toLowerCase();
@@ -406,9 +438,15 @@ export class Chart {
       return 'auto';
     };
     const kind = normalizeType(rawType);
+    if (kind === 'auto') return exportError('EXPORT_TYPE_UNSUPPORTED', `Unknown export type: ${rawType}`, 'Use png, svg, jpeg, or json.');
     if (kind === 'json') {
       const payload = { version: '2.0', spec: this.getSpec(), state: this.getState() };
-      return options.as === 'object' ? payload : JSON.stringify(payload, null, 2);
+      const json = JSON.stringify(payload, null, 2);
+      if (!options.as || options.as === 'string') return json;
+      if (options.as === 'object') return payload;
+      if (options.as === 'dataurl') return `data:application/json;charset=utf-8,${encodeURIComponent(json)}`;
+      if (options.as === 'blob') return dataUrlToBlob(`data:application/json;charset=utf-8,${encodeURIComponent(json)}`, 'application/json');
+      return exportError('EXPORT_TYPE_UNSUPPORTED', `Unsupported JSON export format: ${options.as}`, 'Use string, dataurl, blob, or object.');
     }
     if (kind === 'svg') {
       const svgRendererReady = this.renderer instanceof SVGRenderer && this.renderer.container;
@@ -457,34 +495,7 @@ export class Chart {
       }
       return dataUrl;
     }
-    if (this.renderer instanceof SVGRenderer) {
-      try {
-        const c = require('canvas');
-        if (c && c.createCanvas) {
-          const cv = c.createCanvas(this.spec.width, this.spec.height);
-          const r = new CanvasRenderer({ ...this.spec });
-          r.canvas = cv; r.ctx = cv.getContext('2d'); r.resize(this.spec.width, this.spec.height); r.render(this.model.scene);
-          const out = r.exportImage(rasterType);
-          return options.as === 'blob' ? (typeof Blob !== 'undefined' ? new Blob([Uint8Array.from(atob(out.slice(out.indexOf(',') + 1)), x => x.charCodeAt(0))], { type: rasterType }) : out) : out;
-        }
-      } catch (_) { /* ignore */ }
-      return { valid: false, code: 'HEADLESS_EXPORT_UNSUPPORTED', rasterCode: 'RASTER_EXPORT_UNSUPPORTED', message: `Raster export (${rasterType}) with SVG renderer in headless requires npm i canvas.`, suggestion: 'Install the `canvas` package, or fall back to chart.export({type:"svg"}) which works browser+headless with zero dependencies.' };
-    }
-    const canvasUnavailable = { valid: false, code: 'HEADLESS_EXPORT_UNSUPPORTED', rasterCode: 'RASTER_EXPORT_UNSUPPORTED', message: `Raster export (${rasterType}) requires a mounted CanvasRenderer with a real canvas element.`, suggestion: 'Mount the chart with { renderer: "canvas", container: "#id" } in a browser, or fall back to chart.export({type:"svg"}) which works browser+headless.' };
-    if (typeof document === 'undefined') {
-      try {
-        const c = require('canvas');
-        if (c && c.createCanvas) {
-          const cv = c.createCanvas(this.spec.width, this.spec.height);
-          const r = new CanvasRenderer({ ...this.spec });
-          r.canvas = cv; r.ctx = cv.getContext('2d'); r.resize(this.spec.width, this.spec.height); r.render(this.model.scene);
-          const out = r.exportImage(rasterType);
-          return options.as === 'blob' ? (typeof Blob !== 'undefined' ? new Blob([Uint8Array.from(atob(out.slice(out.indexOf(',') + 1)), x => x.charCodeAt(0))], { type: rasterType }) : out) : out;
-        }
-      } catch (_) { /* ignore: continue to structured error */ }
-      return { ...canvasUnavailable, headless: true, note: 'In Node headless, run `npm i canvas` and ensure createCanvas() is available, or use chart.export({type:"svg"}).' };
-    }
-    return canvasUnavailable;
+    return exportError('HEADLESS_EXPORT_UNSUPPORTED', `Raster export (${rasterType}) requires a mounted CanvasRenderer or the async optional canvas adapter.`, 'Use chart.exportAsync({ type: "png" }) with the optional canvas package, or fall back to chart.export({ type: "svg" }).', { rasterCode: 'RASTER_EXPORT_UNSUPPORTED' });
   }
   async exportAsync(options = {}) {
     const rawType = String(options.type || (this.renderer instanceof CanvasRenderer ? 'image/png' : 'image/svg+xml')).toLowerCase();
@@ -496,12 +507,21 @@ export class Chart {
       return 'auto';
     };
     const kind = normalizeType(rawType);
-    if (kind === 'json' || kind === 'svg' || kind === 'png' || kind === 'jpeg') {
-      const out = this.export(options);
-      if (out && typeof out === 'object' && out.valid === false) return Promise.reject(out);
-      return Promise.resolve(out);
+    if (kind === 'auto') return exportError('EXPORT_TYPE_UNSUPPORTED', `Unknown export type: ${rawType}`, 'Use png, svg, jpeg, or json.');
+    if (kind === 'png' || kind === 'jpeg') {
+      const direct = this.export(options);
+      if (!(direct && typeof direct === 'object' && direct.code === 'HEADLESS_EXPORT_UNSUPPORTED')) return direct;
+      try {
+        const moduleName = 'canvas';
+        const module = await import(moduleName);
+        const createCanvas = canvasFactoryFromModule(module);
+        if (!createCanvas) return direct;
+        return renderRasterWithCanvas(createCanvas, this.spec, this.model.scene, kind === 'jpeg' ? 'image/jpeg' : 'image/png', options.as);
+      } catch {
+        return direct;
+      }
     }
-    return Promise.reject({ valid: false, code: 'EXPORT_TYPE_UNSUPPORTED', message: `Unknown export type: ${rawType}`, suggestion: 'Use png, svg, jpeg, or json.' });
+    return this.export(options);
   }
   _safeFilename(prefix = 'ichart') {
     const sanitize = s => String(s == null ? '' : s).replace(/[\\/:*?"<>|\s]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || prefix;
@@ -559,4 +579,4 @@ export { normalizeProjectCalendar, applyWorkingCalendar, normalizeDependencies,
 export { normalizeLinkedFilters, normalizeLinkedSelection, filterProjectRows, createLinkedProjectState, linkedRecordId };
 
 export { contrastRatio, planStyle, resolveTheme, styleCapabilities, themeModes, themePalettes, themePresets, validateThemeContrast, annotationPlugin, dataZoomPlugin, dataLabelsPlugin, accessibilityPlugin };
-export const iChart = { version: '2.0.0', createChart, inspectData, normalizeData, binData, applyTransforms, normalizeSpec, validateSpec, data, getCapabilities, getChartCapability, planChart, recommend, explainChart, contrastRatio, planStyle, resolveTheme, styleCapabilities, themeModes, themePalettes, themePresets, validateThemeContrast, annotationPlugin, dataZoomPlugin, dataLabelsPlugin, accessibilityPlugin, getBusinessSchema, inspectDataSchema, validateData, getEditCapabilities, validateEdit, previewEdit, commitPreview, validateRecipe, normalizeProjectCalendar, applyWorkingCalendar, normalizeDependencies, analyzeSchedule, analyzeBurndownSeries, analyzeCapacity, buildCapacityView, buildCumulativeFlowSeries, buildVelocitySeries, buildReleaseForecast, buildRiskMatrixSeries, buildIssueAgingSeries, normalizeLinkedFilters, normalizeLinkedSelection, filterProjectRows, createLinkedProjectState, linkedRecordId };
+export const iChart = { version: '2.0.5', createChart, inspectData, normalizeData, binData, applyTransforms, normalizeSpec, validateSpec, data, getCapabilities, getChartCapability, planChart, recommend, explainChart, contrastRatio, planStyle, resolveTheme, styleCapabilities, themeModes, themePalettes, themePresets, validateThemeContrast, annotationPlugin, dataZoomPlugin, dataLabelsPlugin, accessibilityPlugin, getBusinessSchema, inspectDataSchema, validateData, getEditCapabilities, validateEdit, previewEdit, commitPreview, validateRecipe, normalizeProjectCalendar, applyWorkingCalendar, normalizeDependencies, analyzeSchedule, analyzeBurndownSeries, analyzeCapacity, buildCapacityView, buildCumulativeFlowSeries, buildVelocitySeries, buildReleaseForecast, buildRiskMatrixSeries, buildIssueAgingSeries, normalizeLinkedFilters, normalizeLinkedSelection, filterProjectRows, createLinkedProjectState, linkedRecordId };

package/src/renderer.mjs

@@ -29,9 +29,9 @@ export class BaseRenderer {
 
 export class CanvasRenderer extends BaseRenderer {
   mount(container) { super.mount(container); this.canvas = this.container.tagName === 'CANVAS' ? this.container : document.createElement('canvas'); if (this.canvas !== this.container) { this.container.innerHTML = ''; this.container.appendChild(this.canvas); } this.canvas.style.background = this.options.background || '#ffffff'; this.ctx = this.canvas.getContext('2d'); return this; }
-  resize(width, height, pixelRatio = window.devicePixelRatio || 1) { this.width = width; this.height = height; this.pixelRatio = pixelRatio; this.canvas.width = Math.round(width * pixelRatio); this.canvas.height = Math.round(height * pixelRatio); this.canvas.style.width = `${width}px`; this.canvas.style.height = `${height}px`; this.ctx.setTransform(pixelRatio, 0, 0, pixelRatio, 0, 0); }
+  resize(width, height, pixelRatio = globalThis.devicePixelRatio || 1) { this.width = width; this.height = height; this.pixelRatio = pixelRatio; this.canvas.width = Math.round(width * pixelRatio); this.canvas.height = Math.round(height * pixelRatio); if (this.canvas.style) { this.canvas.style.width = `${width}px`; this.canvas.style.height = `${height}px`; } this.ctx.setTransform(pixelRatio, 0, 0, pixelRatio, 0, 0); }
   clear() { if (this.ctx) this.ctx.clearRect(0, 0, this.width, this.height); }
-  render(scene) { this.clear(); const ctx = this.ctx; const draw = node => { if (!node.visible) return; const g = node.geometry || {}; const s = node.style || {}; ctx.save(); ctx.globalAlpha = s.opacity == null ? 1 : s.opacity; ctx.fillStyle = hasFill(s) ? color(s, 'fill', node.highlighted || node.selected ? '#1d4ed8' : '#2563eb') : 'rgba(0,0,0,0)'; ctx.strokeStyle = hasStroke(s) ? color(s, 'stroke', '#0f172a') : 'rgba(0,0,0,0)'; ctx.lineWidth = s.strokeWidth || 1; if (node.type === 'rect') { if (hasFill(s)) ctx.fillRect(g.x, g.y, g.width, g.height); if (hasStroke(s)) ctx.strokeRect(g.x, g.y, g.width, g.height); } else if (node.type === 'line') { ctx.beginPath(); ctx.moveTo(g.x1, g.y1); ctx.lineTo(g.x2, g.y2); if (hasStroke(s)) ctx.stroke(); } else if (node.type === 'path') { ctx.beginPath(); g.points.forEach((point, index) => index ? ctx.lineTo(point.x, point.y) : ctx.moveTo(point.x, point.y)); if (g.closed) ctx.closePath(); if (hasFill(s)) ctx.fill(); if (hasStroke(s)) ctx.stroke(); } else if (node.type === 'circle') { ctx.beginPath(); ctx.arc(g.cx, g.cy, g.r, 0, Math.PI * 2); if (hasFill(s)) ctx.fill(); if (hasStroke(s)) ctx.stroke(); } else if (node.type === 'arc') { ctx.beginPath(); ctx.arc(g.cx, g.cy, g.r, g.start, g.end); if (g.innerR > 0) { ctx.arc(g.cx, g.cy, g.innerR, g.end, g.start, true); } else ctx.lineTo(g.cx, g.cy); ctx.closePath(); if (hasFill(s)) ctx.fill(); if (hasStroke(s)) ctx.stroke(); } else if (node.type === 'text') { if (!hasFill(s)) ctx.fillStyle = color(s, 'fill', '#0f172a'); ctx.font = s.font || '12px system-ui'; const align = s.textAlign || (s.textAnchor === 'end' ? 'end' : s.textAnchor === 'middle' || s.textAnchor === 'center' ? 'center' : s.textAnchor === 'start' ? 'start' : 'left'); ctx.textAlign = align; ctx.textBaseline = s.textBaseline || s.baseline || 'alphabetic'; ctx.fillText(g.text, g.x, g.y); } node.children.slice().sort((a, b) => a.zIndex - b.zIndex).forEach(draw); ctx.restore(); }; draw(scene.root); }
+  render(scene) { this.clear(); const ctx = this.ctx; if (hasFill({ fill: this.options?.background })) { ctx.save(); ctx.fillStyle = this.options.background; ctx.fillRect(0, 0, this.width, this.height); ctx.restore(); } const draw = node => { if (!node.visible) return; const g = node.geometry || {}; const s = node.style || {}; ctx.save(); ctx.globalAlpha = s.opacity == null ? 1 : s.opacity; ctx.fillStyle = hasFill(s) ? color(s, 'fill', node.highlighted || node.selected ? '#1d4ed8' : '#2563eb') : 'rgba(0,0,0,0)'; ctx.strokeStyle = hasStroke(s) ? color(s, 'stroke', '#0f172a') : 'rgba(0,0,0,0)'; ctx.lineWidth = s.strokeWidth || 1; if (node.type === 'rect') { if (hasFill(s)) ctx.fillRect(g.x, g.y, g.width, g.height); if (hasStroke(s)) ctx.strokeRect(g.x, g.y, g.width, g.height); } else if (node.type === 'line') { ctx.beginPath(); ctx.moveTo(g.x1, g.y1); ctx.lineTo(g.x2, g.y2); if (hasStroke(s)) ctx.stroke(); } else if (node.type === 'path') { ctx.beginPath(); g.points.forEach((point, index) => index ? ctx.lineTo(point.x, point.y) : ctx.moveTo(point.x, point.y)); if (g.closed) ctx.closePath(); if (hasFill(s)) ctx.fill(); if (hasStroke(s)) ctx.stroke(); } else if (node.type === 'circle') { ctx.beginPath(); ctx.arc(g.cx, g.cy, g.r, 0, Math.PI * 2); if (hasFill(s)) ctx.fill(); if (hasStroke(s)) ctx.stroke(); } else if (node.type === 'arc') { ctx.beginPath(); ctx.arc(g.cx, g.cy, g.r, g.start, g.end); if (g.innerR > 0) { ctx.arc(g.cx, g.cy, g.innerR, g.end, g.start, true); } else ctx.lineTo(g.cx, g.cy); ctx.closePath(); if (hasFill(s)) ctx.fill(); if (hasStroke(s)) ctx.stroke(); } else if (node.type === 'text') { ctx.fillStyle = hasFill(s) ? s.fill : '#0f172a'; ctx.font = s.font || '12px system-ui'; const align = s.textAlign || (s.textAnchor === 'end' ? 'end' : s.textAnchor === 'middle' || s.textAnchor === 'center' ? 'center' : s.textAnchor === 'start' ? 'start' : 'left'); ctx.textAlign = align; ctx.textBaseline = s.textBaseline || s.baseline || 'alphabetic'; ctx.fillText(g.text, g.x, g.y); } node.children.slice().sort((a, b) => a.zIndex - b.zIndex).forEach(draw); ctx.restore(); }; draw(scene.root); }
   exportImage(type = 'image/png') { return this.canvas.toDataURL(type); }
 }
 
@@ -86,6 +86,6 @@ export class SVGRenderer extends BaseRenderer {
       this.svg.setAttribute('viewBox', `0 0 ${w} ${h}`);
       this.width = w; this.height = h;
     }
-    this.clear(); const renderNode = node => { if (!node.visible || node.type === 'root') { node.children.slice().sort((a, b) => a.zIndex - b.zIndex).forEach(renderNode); return; } const g = node.geometry || {}, s = node.style || {}; const element = document.createElementNS('http://www.w3.org/2000/svg', node.type === 'path' || node.type === 'arc' ? 'path' : node.type === 'text' ? 'text' : node.type); element.setAttribute('id', node.id); element.setAttribute('data-node-id', node.id); if (node.dataRef) element.dataset.dataRef = JSON.stringify(node.dataRef); if (node.type === 'rect') { element.setAttribute('x', g.x); element.setAttribute('y', g.y); element.setAttribute('width', g.width); element.setAttribute('height', g.height); } else if (node.type === 'line') { ['x1', 'y1', 'x2', 'y2'].forEach(key => element.setAttribute(key, g[key])); } else if (node.type === 'circle') { element.setAttribute('cx', g.cx); element.setAttribute('cy', g.cy); element.setAttribute('r', g.r); } else if (node.type === 'arc') { const large = g.end - g.start > Math.PI ? 1 : 0, outerStart = `${g.cx + g.r * Math.cos(g.start)} ${g.cy + g.r * Math.sin(g.start)}`, outerEnd = `${g.cx + g.r * Math.cos(g.end)} ${g.cy + g.r * Math.sin(g.end)}`; const p = g.innerR > 0 ? [`M ${outerStart}`, `A ${g.r} ${g.r} 0 ${large} 1 ${outerEnd}`, `L ${g.cx + g.innerR * Math.cos(g.end)} ${g.cy + g.innerR * Math.sin(g.end)}`, `A ${g.innerR} ${g.innerR} 0 ${large} 0 ${g.cx + g.innerR * Math.cos(g.start)} ${g.cy + g.innerR * Math.sin(g.start)}`, 'Z'] : [`M ${g.cx} ${g.cy}`, `L ${outerStart}`, `A ${g.r} ${g.r} 0 ${large} 1 ${outerEnd}`, 'Z']; element.setAttribute('d', p.join(' ')); } else if (node.type === 'path') element.setAttribute('d', `${g.points.map((p, i) => `${i ? 'L' : 'M'} ${p.x} ${p.y}`).join(' ')}${g.closed ? ' Z' : ''}`); else if (node.type === 'text') { element.setAttribute('x', g.x); element.setAttribute('y', g.y); element.textContent = g.text; const anchor = s.textAnchor || (s.textAlign === 'end' ? 'end' : s.textAlign === 'center' ? 'middle' : s.textAlign === 'right' ? 'end' : s.textAlign === 'left' ? 'start' : 'start'); if (anchor) element.setAttribute('text-anchor', anchor); const baseline = s.textBaseline || s.baseline || 'alphabetic'; if (baseline === 'top') { element.setAttribute('dominant-baseline', 'text-before-edge'); element.setAttribute('alignment-baseline', 'before-edge'); } else if (baseline === 'middle' || baseline === 'central') { element.setAttribute('dominant-baseline', 'middle'); element.setAttribute('alignment-baseline', 'middle'); } else if (baseline === 'bottom' || baseline === 'hanging') { element.setAttribute('dominant-baseline', 'text-after-edge'); element.setAttribute('alignment-baseline', 'after-edge'); } else { element.setAttribute('dominant-baseline', 'alphabetic'); element.setAttribute('alignment-baseline', 'alphabetic'); } if (s.font) { const raw = String(s.font).trim(); element.setAttribute('font', raw); const sizeMatch = raw.match(/\b(\d+(?:\.\d+)?)\s*(px|em|rem|pt|%)/i); const size = sizeMatch ? `${sizeMatch[1]}${sizeMatch[2].toLowerCase()}` : ''; if (size) element.style.fontSize = size; const weightMatch = raw.match(/^\s*(\d{3}|normal|bold|lighter|bolder)\b/i); if (weightMatch) element.style.fontWeight = weightMatch[1]; const family = raw.replace(/^\s*(?:(?:normal|italic|oblique)(?:\s+[^0-9\s]+)?\s+)?(?:\d{3}|normal|bold|lighter|bolder)\s+/i, '').replace(/\b\d+(?:\.\d+)?\s*(?:px|em|rem|pt|%)(?:\s*\/\s*\S+)?\s*/i, '').trim(); if (family) element.style.fontFamily = family; } } if (node.type === 'path' || node.type === 'circle' || node.type === 'rect' || node.type === 'arc') { if (hasFill(s)) element.setAttribute('fill', s.fill); else element.setAttribute('fill', node.type === 'path' ? 'none' : 'black'); } else if (node.type === 'text') { element.setAttribute('fill', hasFill(s) ? s.fill : color(s, 'fill', '#0f172a')); } if (hasStroke(s)) element.setAttribute('stroke', s.stroke); else if (s.stroke != null && typeof s.stroke === 'string' && NO_FILL_TOKENS.has(s.stroke.trim().toLowerCase())) element.setAttribute('stroke', 'none'); if (s.strokeWidth != null) element.setAttribute('stroke-width', s.strokeWidth); if (s.opacity != null) element.setAttribute('opacity', node.highlighted || node.selected ? 1 : s.opacity); if (node.highlighted || node.selected) element.setAttribute('filter', 'brightness(1.2)'); if (node.interactive) element.style.cursor = 'pointer'; if (s.pointerEvents === 'none') element.style.pointerEvents = 'none'; if (s.ariaHidden === 'true') element.setAttribute('aria-hidden', 'true'); if (s.role === 'presentation') element.setAttribute('role', 'presentation'); if (node.decorative) { element.setAttribute('aria-hidden', 'true'); element.setAttribute('role', 'presentation'); element.style.pointerEvents = 'none'; element.style.userSelect = 'none'; } this.svg.appendChild(element); node.children.slice().sort((a, b) => a.zIndex - b.zIndex).forEach(renderNode); }; scene.root.children.slice().sort((a, b) => a.zIndex - b.zIndex).forEach(renderNode); }
+    this.clear(); const renderNode = node => { if (!node.visible || node.type === 'root') { node.children.slice().sort((a, b) => a.zIndex - b.zIndex).forEach(renderNode); return; } const g = node.geometry || {}, s = node.style || {}; const element = document.createElementNS('http://www.w3.org/2000/svg', node.type === 'path' || node.type === 'arc' ? 'path' : node.type === 'text' ? 'text' : node.type); element.setAttribute('id', node.id); element.setAttribute('data-node-id', node.id); if (node.dataRef) element.dataset.dataRef = JSON.stringify(node.dataRef); if (node.type === 'rect') { element.setAttribute('x', g.x); element.setAttribute('y', g.y); element.setAttribute('width', g.width); element.setAttribute('height', g.height); } else if (node.type === 'line') { ['x1', 'y1', 'x2', 'y2'].forEach(key => element.setAttribute(key, g[key])); } else if (node.type === 'circle') { element.setAttribute('cx', g.cx); element.setAttribute('cy', g.cy); element.setAttribute('r', g.r); } else if (node.type === 'arc') { const large = g.end - g.start > Math.PI ? 1 : 0, outerStart = `${g.cx + g.r * Math.cos(g.start)} ${g.cy + g.r * Math.sin(g.start)}`, outerEnd = `${g.cx + g.r * Math.cos(g.end)} ${g.cy + g.r * Math.sin(g.end)}`; const p = g.innerR > 0 ? [`M ${outerStart}`, `A ${g.r} ${g.r} 0 ${large} 1 ${outerEnd}`, `L ${g.cx + g.innerR * Math.cos(g.end)} ${g.cy + g.innerR * Math.sin(g.end)}`, `A ${g.innerR} ${g.innerR} 0 ${large} 0 ${g.cx + g.innerR * Math.cos(g.start)} ${g.cy + g.innerR * Math.sin(g.start)}`, 'Z'] : [`M ${g.cx} ${g.cy}`, `L ${outerStart}`, `A ${g.r} ${g.r} 0 ${large} 1 ${outerEnd}`, 'Z']; element.setAttribute('d', p.join(' ')); } else if (node.type === 'path') element.setAttribute('d', `${g.points.map((p, i) => `${i ? 'L' : 'M'} ${p.x} ${p.y}`).join(' ')}${g.closed ? ' Z' : ''}`); else if (node.type === 'text') { element.setAttribute('x', g.x); element.setAttribute('y', g.y); element.textContent = g.text; const anchor = s.textAnchor || (s.textAlign === 'end' ? 'end' : s.textAlign === 'center' ? 'middle' : s.textAlign === 'right' ? 'end' : s.textAlign === 'left' ? 'start' : 'start'); if (anchor) element.setAttribute('text-anchor', anchor); const baseline = s.textBaseline || s.baseline || 'alphabetic'; if (baseline === 'top') { element.setAttribute('dominant-baseline', 'text-before-edge'); element.setAttribute('alignment-baseline', 'before-edge'); } else if (baseline === 'middle' || baseline === 'central') { element.setAttribute('dominant-baseline', 'middle'); element.setAttribute('alignment-baseline', 'middle'); } else if (baseline === 'bottom' || baseline === 'hanging') { element.setAttribute('dominant-baseline', 'text-after-edge'); element.setAttribute('alignment-baseline', 'after-edge'); } else { element.setAttribute('dominant-baseline', 'alphabetic'); element.setAttribute('alignment-baseline', 'alphabetic'); } if (s.font) { const raw = String(s.font).trim(); element.setAttribute('font', raw); const sizeMatch = raw.match(/\b(\d+(?:\.\d+)?)\s*(px|em|rem|pt|%)/i); const size = sizeMatch ? `${sizeMatch[1]}${sizeMatch[2].toLowerCase()}` : ''; if (size) element.style.fontSize = size; const weightMatch = raw.match(/^\s*(\d{3}|normal|bold|lighter|bolder)\b/i); if (weightMatch) element.style.fontWeight = weightMatch[1]; const family = raw.replace(/^\s*(?:(?:normal|italic|oblique)(?:\s+[^0-9\s]+)?\s+)?(?:\d{3}|normal|bold|lighter|bolder)\s+/i, '').replace(/\b\d+(?:\.\d+)?\s*(?:px|em|rem|pt|%)(?:\s*\/\s*\S+)?\s*/i, '').trim(); if (family) element.style.fontFamily = family; } } if (node.type === 'path' || node.type === 'circle' || node.type === 'rect' || node.type === 'arc') { element.setAttribute('fill', hasFill(s) ? s.fill : 'none'); } else if (node.type === 'text') { element.setAttribute('fill', hasFill(s) ? s.fill : '#0f172a'); } if (hasStroke(s)) element.setAttribute('stroke', s.stroke); else if (s.stroke != null && typeof s.stroke === 'string' && NO_FILL_TOKENS.has(s.stroke.trim().toLowerCase())) element.setAttribute('stroke', 'none'); if (s.strokeWidth != null) element.setAttribute('stroke-width', s.strokeWidth); if (s.opacity != null) element.setAttribute('opacity', node.highlighted || node.selected ? 1 : s.opacity); if (node.highlighted || node.selected) element.setAttribute('filter', 'brightness(1.2)'); if (node.interactive) element.style.cursor = 'pointer'; if (s.pointerEvents === 'none') element.style.pointerEvents = 'none'; if (s.ariaHidden === 'true') element.setAttribute('aria-hidden', 'true'); if (s.role === 'presentation') element.setAttribute('role', 'presentation'); if (node.decorative) { element.setAttribute('aria-hidden', 'true'); element.setAttribute('role', 'presentation'); element.style.pointerEvents = 'none'; element.style.userSelect = 'none'; } this.svg.appendChild(element); node.children.slice().sort((a, b) => a.zIndex - b.zIndex).forEach(renderNode); }; scene.root.children.slice().sort((a, b) => a.zIndex - b.zIndex).forEach(renderNode); }
   exportString() { if (!this.svg) return ''; return new XMLSerializer().serializeToString(this.svg); }
 }

package/src/spec.mjs

@@ -60,6 +60,7 @@ function dependencyErrors(rows) {
 
 export function normalizeSpec(input = {}) {
   const spec = merge(defaults, input);
+  if (input.branding === undefined && input.theme && typeof input.theme === 'object' && input.theme.branding !== undefined) spec.branding = clone(input.theme.branding);
   if (spec.branding === false) spec.branding = { enabled: false };
   else if (spec.branding === true) spec.branding = { enabled: true };
   else if (spec.branding == null) spec.branding = { enabled: true };
@@ -92,6 +93,8 @@ export function validateSpec(input) {
     if (spec.theme.mode && !themeModes.includes(spec.theme.mode)) errors.push({ code: 'INVALID_THEME_MODE', path: 'theme.mode', message: `Unsupported theme mode: ${spec.theme.mode}`, suggestion: `Use ${themeModes.join(', ')}.` });
     if (spec.theme.preset && !themePresets.includes(spec.theme.preset)) errors.push({ code: 'INVALID_THEME_PRESET', path: 'theme.preset', message: `Unsupported theme preset: ${spec.theme.preset}`, suggestion: `Use ${themePresets.join(', ')}.` });
     if (spec.theme.palette && !themePalettes.includes(spec.theme.palette)) errors.push({ code: 'INVALID_THEME_PALETTE', path: 'theme.palette', message: `Unsupported theme palette: ${spec.theme.palette}`, suggestion: `Use ${themePalettes.join(', ')}.` });
+    if (spec.theme.branding != null && typeof spec.theme.branding !== 'boolean' && !(spec.theme.branding && typeof spec.theme.branding === 'object')) errors.push({ code: 'INVALID_BRANDING', path: 'theme.branding', message: 'theme.branding must be a boolean or a { enabled: boolean } object.', suggestion: 'Use theme: { branding: false } or theme: { branding: { enabled: false } }.' });
+    else if (spec.theme.branding && typeof spec.theme.branding === 'object' && (Object.keys(spec.theme.branding).some(key => key !== 'enabled') || typeof spec.theme.branding.enabled !== 'boolean')) errors.push({ code: 'INVALID_BRANDING', path: 'theme.branding', message: 'theme.branding objects only support a boolean enabled property.', suggestion: 'Use theme: { branding: { enabled: false } }.' });
   }
   if (Array.isArray(spec.encoding.y) && spec.encoding.y.length > 2) errors.push({ code: 'TOO_MANY_AXES', path: 'encoding.y', message: 'Only two quantitative axes are supported in this iteration.', suggestion: 'Use at most two y encodings.' });
   if (spec.stack && !['bar', 'column', 'area'].includes(spec.type)) errors.push({ code: 'INVALID_STACK', path: 'stack', message: 'Stacking is supported by bar, column, and area charts.', suggestion: 'Remove stack or use a supported chart type.' });

package/types/index.d.ts

@@ -16,7 +16,7 @@ export interface ChartCapability { type: ChartType; family: string; intents: str
 export interface RuntimeCapabilities { version: '2.0'; contractVersion: '1.0'; chartTypes: ChartType[]; charts: Record<ChartType, ChartCapability>; intents: string[]; renderers: Array<'canvas' | 'svg'>; interactions: string[]; exports: Array<'png' | 'svg' | 'json' | 'jpeg'>; styleSystem: { modes: ThemeMode[]; presets: ThemePreset[]; palettes: ThemePalette[]; switchable: boolean; automatic: boolean; [key: string]: unknown }; headless: { preview?: boolean; json: boolean; svg: boolean; png: boolean | string }; export: { types: string[]; mime: Record<string, string>; browser: Record<string, boolean>; headless: Record<string, string | boolean>; methods: string[]; options: Record<string, unknown>; branding: Record<string, unknown> }; branding: { defaultEnabled: boolean; signature: string; options: Record<string, unknown> }; [key: string]: unknown; }
 export interface ChartPlan { version: '1.0'; intent: string; primary: ChartType; alternatives: ChartType[]; confidence: number; reasons: string[]; requiredFields: string[]; suggestedEncodings: { dimension: string | null; measure: string | null; secondaryMeasure: string | null }; assumptions: string[]; warnings: Diagnostic[]; unsupportedRequests: string[]; nextActions: string[]; capability: ChartCapability; styleRecommendation: StyleRecommendation; data: DataInspection; }
 export interface ChartExplanation { version: '1.0'; type: ChartType; family: string; purpose: string; renderer: Renderer; dataCount: number; encodings: Record<string, string | string[]>; transforms: string[]; interactions: string[]; assumptions: string[]; warnings: Diagnostic[]; style: Partial<StyleRecommendation> & { name?: string }; lineage: { recordIds: string[]; sourcePreserved: boolean }; accessibility: { enabled: boolean; summary: string }; }
-export interface ChartSpec { type: ChartType; renderer?: Renderer; container?: string | Element; width?: number; height?: number; data?: Array<Record<string, unknown>> | { values?: Array<Record<string, unknown>>; [key: string]: unknown }; encoding?: Record<string, unknown>; title?: { text?: string; subtitle?: string }; legend?: { visible?: boolean; position?: string }; grid?: { visible?: boolean; color?: string }; labels?: { enabled?: boolean; format?: string | Record<string, unknown>; color?: string; font?: string }; interaction?: Record<string, boolean>; accessibility?: { enabled?: boolean; description?: string }; theme?: ThemeMode | ThemePreset | ThemeConfig | ResolvedTheme; [key: string]: unknown; }
+export interface ChartSpec { type: ChartType; renderer?: Renderer; container?: string | Element; width?: number; height?: number; data?: Array<Record<string, unknown>> | { values?: Array<Record<string, unknown>>; [key: string]: unknown }; encoding?: Record<string, unknown>; title?: { text?: string; subtitle?: string }; legend?: { visible?: boolean; position?: string }; grid?: { visible?: boolean; color?: string }; labels?: { enabled?: boolean; format?: string | Record<string, unknown>; color?: string; font?: string }; interaction?: Record<string, boolean>; accessibility?: { enabled?: boolean; description?: string }; branding?: boolean | { enabled?: boolean }; theme?: ThemeMode | ThemePreset | ThemeConfig | ResolvedTheme; [key: string]: unknown; }
 export interface BinTransform { type: 'bin'; field: string; output?: string; thresholds?: number; step?: number; extent?: [number, number]; }
 export interface RadarIndicator { name: string; field: string; min?: number; max?: number; }
 export type BusinessFieldType = 'string' | 'number' | 'boolean' | 'date' | 'enum' | 'array' | 'object';
@@ -54,7 +54,7 @@ export interface Chart {
   toDataURL(type?: 'image/png' | 'image/jpeg' | 'image/svg+xml'): string | ExportError;
   toBlob(type?: 'image/png' | 'image/jpeg' | 'image/svg+xml'): Blob | ExportError;
   export(options?: { type?: ExportKind; as?: ExportAs }): string | { version: string; spec: unknown; state: unknown } | Blob | ExportError;
-  exportAsync(options?: { type?: ExportKind; as?: ExportAs }): Promise<string | { version: string; spec: unknown; state: unknown } | Blob>;
+  exportAsync(options?: { type?: ExportKind; as?: ExportAs }): Promise<string | { version: string; spec: unknown; state: unknown } | Blob | ExportError>;
   download(options?: { type?: ExportKind | 'json' }): { valid: boolean; filename?: string; size?: number; type?: string; code?: string; message?: string } | ExportError | string;
   downloadPNG(): ReturnType<Chart['download']>;
   downloadSVG(): ReturnType<Chart['download']>;