@taylorwong/ichartjs 2.0.4 → 2.0.6

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 2.0.6 - 2026-09-18
+
+- Added compact per-chart visual settings with explicit default font sizing, capability-aware visibility toggles, bilingual labels, and theme-aware hamburger icon contrast.
+- Added shared page-level preferences with localStorage persistence and Agent JSON patch support through the Preferences API and Playground settings page.
+- Synchronized Runtime, Playground, package metadata, release-pinned installation guidance, and roadmap status for the `v2.0.6` release.
+
+## 2.0.5 - 2026-09-18
+
+- Hardened JSON, SVG, PNG, and JPEG export contracts with deterministic type errors, JSON output representations, and an explicit optional Node `canvas` path through `exportAsync()`.
+- 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.

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:
@@ -24,10 +26,12 @@ getCapabilities
 | 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) |
 | Visual style and themes | [`docs/agent/theme-guide.md`](docs/agent/theme-guide.md) |
+| Chart and page preferences | [`docs/agent/theme-guide.md`](docs/agent/theme-guide.md#chart-and-page-preferences) |
 | Official Agent Skill for Codex and WorkBuddy | [`skills/ichartjs/SKILL.md`](skills/ichartjs/SKILL.md) |
 
 ### Install
@@ -36,7 +40,7 @@ getCapabilities
 npm install @taylorwong/ichartjs@^2
 ```
 
-As a fallback for environments without npm access, install directly from GitHub: `npm install github:wanghetommy/ichartjs#v2.0.4`.
+As a fallback for environments without npm access, install directly from GitHub: `npm install github:wanghetommy/ichartjs#v2.0.6`.
 
 ### Optional Agent Skill
 
@@ -46,13 +50,19 @@ The runtime API remains the source of truth; the Skill only teaches and orchestr
 https://github.com/wanghetommy/ichartjs/tree/master/skills/ichartjs
 ```
 
-From a repository checkout, install it into Codex with:
+Install the latest Skill with the standard Agent Skills CLI:
+
+```bash
+npx skills add wanghetommy/ichartjs --skill ichartjs
+```
+
+For a non-interactive global Codex installation:
 
 ```bash
-cp -R skills/ichartjs "${CODEX_HOME:-$HOME/.codex}/skills/"
+npx skills add wanghetommy/ichartjs --skill ichartjs --agent codex --global --yes
 ```
 
-WorkBuddy users can import or register the same `skills/ichartjs` folder through the host's Skill interface. Package consumers can copy it from `node_modules/@taylorwong/ichartjs/skills/ichartjs` into their Agent host's Skill directory. After installation, invoke it as `$ichartjs` when the host supports named Skill invocation, or select the `ichartjs` Skill in the host UI.
+For a release-pinned installation, use `npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.6/skills/ichartjs --agent codex --global --yes`. WorkBuddy users can import the same tagged `skills/ichartjs` URL through the host's Skill interface; do not assume a `--agent workbuddy` adapter unless the installed CLI declares it. Package consumers can still copy `node_modules/@taylorwong/ichartjs/skills/ichartjs` as a manual fallback. After installation, invoke `$ichartjs` when named Skill invocation is supported, or select `ichartjs` in the host UI.
 
 ### Agent workflow
 

package/docs/agent/README.md

@@ -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.

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

@@ -2,6 +2,8 @@
 
 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 `@taylorwong/ichartjs` ESM API. The optional Skill provides workflow guidance only; it does not introduce a second runtime or service.
@@ -25,12 +27,16 @@ npm install
 npm run playground
 ```
 
-The same official Skill can be imported by Codex, WorkBuddy, and other Agent Skills-compatible hosts from `skills/ichartjs`. Install it into Codex from a repository checkout with:
+Install the official Skill with the standard Agent Skills CLI:
 
 ```bash
-cp -R skills/ichartjs "${CODEX_HOME:-$HOME/.codex}/skills/"
+npx skills add wanghetommy/ichartjs --skill ichartjs
 ```
 
+For global non-interactive Codex setup, append `--agent codex --global --yes`. To pin the released workflow, install `https://github.com/wanghetommy/ichartjs/tree/v2.0.6/skills/ichartjs`. WorkBuddy can import that tagged directory through its Skill interface; only use a host-specific `--agent` value when the installed CLI declares it.
+
+Verify discovery with `npx skills add wanghetommy/ichartjs --list`; the result should include `ichartjs`.
+
 ## Agent Request Pattern
 
 A useful request is explicit about data, intent, output, and acceptance:
@@ -86,3 +92,5 @@ Use `examples/agent-workflow.mjs` for the full executable lifecycle.
 - 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/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/iteration-11.md

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

package/docs/agent/development/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.4", "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. Current release status: `v2.0.3` is published and `v2.0.4` is the documentation/version-consistency patch release. Geographic charts and 3D rendering remain out of scope until explicitly reintroduced.
+> Roadmap baseline: 2026-09-14. Current release status: `v2.0.6` is prepared from the completed Iteration 11 visual preference work. Geographic charts and 3D rendering remain out of scope until explicitly reintroduced.
 
 ## Current Status
 
@@ -12,6 +12,8 @@
 - Iteration 7 local runtime and browser acceptance are complete for foundational composition, Heatmap, and Radar; physical-device checks remain host integration evidence.
 - Iteration 8A–8D is complete and accepted in automated tests, Chromium, Firefox 144, WebKit 26, native Safari 26.6.2, and a 390 px touch viewport. Physical iOS/Android and representative release-host measurements remain post-release host/device follow-up. No new public chart type was introduced.
 - Iteration 9A–9D implemented the lightweight visual style system, adaptive theme planning, runtime switching, renderer integration, and bilingual Agent guidance without adding a chart type; these capabilities remain in the `2.0.x` line.
+- Iteration 10A Export Contract Hardening was implemented and released in `v2.0.5`: export representations and type errors are deterministic, optional Node raster export uses `exportAsync()`, Canvas/SVG paint semantics are aligned, and the playground server has safer port/path handling. No chart behavior or public chart type was added.
+- Iteration 11 visual preference controls are included in the `v2.0.6` release: compact per-chart settings, capability-aware visibility controls, theme-aware icon contrast, explicit font-size defaults, shared page preferences, and Agent-adjustable global settings.
 - 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
@@ -247,6 +249,29 @@ The following remain deferred beyond this roadmap baseline:
 
 They should only be scheduled after the core runtime, diagram model, and project analytics contracts are stable.
 
+## Iteration 11 — Chart Preferences and Agent Adjustments
+
+### Goal
+
+Allow users and Agents to adjust a chart's visual presentation after creation through one small, auditable contract. The detailed 11A–11D plan is in `docs/agent/development/iteration-11.md`.
+
+### Tasks
+
+1. Add allowlisted preferences for theme, typography scale, density, components, branding, and motion.
+2. Support chart-scoped and page-global inheritance through an explicit Preferences Store.
+3. Persist only versioned preference state through browser `localStorage` or a host adapter.
+4. Add an optional accessible settings button outside the SVG/Canvas export surface.
+5. Let Agents apply natural-language intent as a validated preference patch with source and scope metadata.
+6. Add Playground and bilingual guidance for UI and Agent adjustment workflows.
+
+### Verification
+
+- Global changes reach all charts sharing a store; chart overrides remain isolated.
+- UI, Agent, and host code use the same `preferenceschange` event path.
+- Invalid patches do not mutate preferences or business data.
+- Settings UI is excluded from SVG, PNG, and JSON chart exports.
+- `npm run agent:check`, `git diff --check`, and `http://localhost:3000/playground/preferences-lab.html` acceptance pass.
+
 ## Recommended Execution Order
 
 1. Finish Iteration 3 browser acceptance.
@@ -256,4 +281,5 @@ They should only be scheduled after the core runtime, diagram model, and project
 5. Execute Iteration 7 foundations before considering additional specialized chart types.
 6. Execute Iteration 8 to complete existing chart behavior, Agent adaptation, and the 2.0 release gates.
 7. Execute Iteration 9 to standardize adaptive visual styling without expanding chart count.
-8. Re-evaluate geographic and 3D scope only after usage data confirms demand.
+8. Execute Iteration 11 to add post-creation chart and page preferences without expanding chart count.
+9. Re-evaluate geographic and 3D scope only after usage data confirms demand.

package/docs/agent/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.4`.
+For environments without npm registry access, install from GitHub as a fallback: `npm install github:wanghetommy/ichartjs#v2.0.6`.
 
 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,
@@ -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/theme-guide.md

@@ -57,3 +57,34 @@ Built-in modes expose text, muted text, axis, grid, focus, selection, missing-va
 
 Preview and acceptance: `http://localhost:3000/playground/theme-gallery.html`.
 
+## Chart and Page Preferences
+
+Use preferences for visual adjustments that a user or Agent may change after the chart has been created. Keep business data, encodings, and chart selection outside this surface.
+
+```js
+import { createChart, createPreferencesStore, mountChartSettings } from '@taylorwong/ichartjs';
+
+const pagePreferences = createPreferencesStore({
+  storage: 'localStorage',
+  storageKey: 'my-app:chart-preferences'
+});
+const chart = createChart({
+  chartId: 'revenue',
+  container: '#revenue',
+  type: 'line',
+  data: { values: rows },
+  preferences: pagePreferences
+});
+mountChartSettings(chart, { locale: 'en' });
+
+// The same operation can come from an Agent conversation.
+chart.setPreferences({
+  theme: { preset: 'dashboard', palette: 'status' },
+  typography: { scale: 1.15 },
+  components: { grid: false }
+}, { source: 'agent' });
+```
+
+The optional per-chart menu uses a compact hamburger icon and intentionally exposes only high-frequency controls: theme mode, palette, font scale, and supported legend/label/grid visibility. Capability checks hide controls that do not apply to the current chart. Changes apply immediately and the UI supports `en`, `zh-CN`, and automatic document-language detection.
+
+Keep low-frequency and page-wide controls in a dedicated settings surface outside the chart popover. Share one store across the page, and call `store.setGlobal()` or `chart.setPreferences(patch, { scope: 'global' })`. The full surface may expose preset, density, branding, and other allowlisted preferences without overloading every chart. The store uses memory in Node/SSR unless `localStorage` or a host adapter is explicitly selected. Preview the quick menu in `http://localhost:3000/playground/project-gallery.html` and the full page at `http://localhost:3000/playground/preferences-lab.html`.

package/docs/agent/usage-scenarios.md

@@ -0,0 +1,198 @@
+# 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.
+
+## Visual Preferences: UI and Agent
+
+For post-creation visual adjustments, share a `createPreferencesStore()` with the page's charts. Use `storage: 'localStorage'` only in a browser when the host wants preferences to survive refreshes. `mountChartSettings(chart)` adds an optional accessible quick-settings button outside the export surface; keep the full page-level settings surface as a separate host route.
+
+The host or Agent can use the same patch contract:
+
+```js
+chart.setPreferences({
+  theme: { preset: 'dashboard', palette: 'status' },
+  typography: { scale: 1.15 },
+  components: { grid: false }
+}, { source: 'agent' });
+```
+
+Keep the quick menu limited to theme, palette, font scale, and capability-supported visibility toggles. Use `scope: 'global'` for a page-wide update, the default chart scope for a single chart, and `chart.getState().preferences` for an auditable effective result. Preview both layers at `http://localhost:3000/playground/project-gallery.html` and `http://localhost:3000/playground/preferences-lab.html`.
+
+## Scenario 1: Integrate into a Web Project
+
+Install the runtime in the host application:
+
+```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 the latest Skill with the standard Agent Skills CLI:
+
+```bash
+npx skills add wanghetommy/ichartjs --skill ichartjs
+```
+
+Install globally for Codex without prompts:
+
+```bash
+npx skills add wanghetommy/ichartjs --skill ichartjs --agent codex --global --yes
+```
+
+For reproducible installation, pin the released Skill directory:
+
+```bash
+npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.6/skills/ichartjs \
+  --agent codex --global --yes
+```
+
+WorkBuddy users can import the same tagged GitHub directory through the host's Skill interface. Do not assume that `--agent workbuddy` exists unless the installed Skills CLI lists that adapter. A manual copy from `node_modules/@taylorwong/ichartjs/skills/ichartjs` remains a fallback for hosts with custom Skill directories.
+
+After installation or selection, ask:
+
+```text
+Use the iChart.js Skill. Read this dataset, create a project Burndown,
+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

@@ -16,12 +16,16 @@ npm install @taylorwong/ichartjs@^2
 
 npm Registry 中无作用域的 `ichartjs` 是安全占位包，并非本项目。正式包名是 `@taylorwong/ichartjs`，优先从 npm 安装。
 
-Codex、WorkBuddy 和其他兼容 Agent Skills 的宿主可共同使用 `skills/ichartjs`。从仓库检出目录安装到 Codex：
+使用标准 Agent Skills CLI 安装官方 Skill：
 
 ```bash
-cp -R skills/ichartjs "${CODEX_HOME:-$HOME/.codex}/skills/"
+npx skills add wanghetommy/ichartjs --skill ichartjs
 ```
 
+Codex 全局无交互安装可追加 `--agent codex --global --yes`。需要固定发布版本时，安装 `https://github.com/wanghetommy/ichartjs/tree/v2.0.6/skills/ichartjs`。WorkBuddy 可通过自身 Skill 界面导入该带 Tag 的目录；只有当前 CLI 明确声明对应适配器时才使用宿主专用 `--agent` 参数。
+
+使用 `npx skills add wanghetommy/ichartjs --list` 验证发现结果，其中应包含 `ichartjs`。
+
 推荐请求：
 
 ```text

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.4`。
+无法访问 npm Registry 的环境请用 GitHub 源作为后备：`npm install github:wanghetommy/ichartjs#v2.0.6`。
 
 ```js
 import { createChart } from '@taylorwong/ichartjs';

package/docs/agent/zh-CN/quickstart.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 输出要求