@taylorwong/ichartjs 2.0.13 → 2.0.14

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2.0.14 - 2026-09-23
+
+- Added a canonical contract registry with synchronized runtime capabilities, offline chart profiles, export declarations, command metadata, business models, and Mindmap edge metadata.
+- Added atomic Spec/data/style mutation validation with structured `ChartValidationError` diagnostics, row-complete project validation, deterministic Burndown date warnings, and idempotent chart destruction.
+- Added complete public Chart declarations, a strict TypeScript consumer fixture, module-cycle checks, executable Agent workflow checks, focused Iteration 13 regression tests, and package dry-run verification.
+- Fixed horizontal Bar y-axis titles so they use the shared vertical, centered layout with reserved left-side space instead of a narrow top-left truncation path.
+
 ## 2.0.13 - 2026-09-22
 
 - Made legend, axis, and project-label layout Unicode-aware, added collision-safe y-axis titles, and restored right-axis title rendering.

package/README.md

@@ -44,7 +44,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.13`.
+As a fallback for environments without npm access, install directly from GitHub: `npm install github:wanghetommy/ichartjs#v2.0.14`.
 
 ### Optional Agent Skill
 
@@ -66,7 +66,7 @@ For a non-interactive global Codex installation:
 npx skills add wanghetommy/ichartjs --skill ichartjs --agent codex --global --yes
 ```
 
-For a release-pinned installation, use `npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.13/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.
+For a release-pinned installation, use `npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.14/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/charting-scenario.md

@@ -42,7 +42,7 @@ Agent usage and development guide for generic data analysis and metric visualiza
 
 Do not put `title`, `format`, `labels`, or `legend` under `encoding`; `validateSpec()` reports those placements as warnings. Numeric y-axes use readable domains by default (`nice: true`, `ticks: "auto"`). Use `yAxis.domain: [min, max]` for an explicit range, or `yAxis.nice: false` to retain the raw boundary. `xAxis.min/max` and `xAxis.domain` are unsupported for categorical/time layouts and produce a structured warning.
 
-Layout is deterministic and renderer-independent. Legend items use Unicode-aware text estimates for spacing and automatically wrap when a row is full; a single label that cannot fit is truncated and reports `LEGEND_OVERFLOW`. Numeric left and right y-axis titles are centered beside their tick columns, while Bar keeps its categorical y-axis title horizontal above the category-label column. Axis and project-label reserves are computed before the plot rectangle, so Canvas, SVG, headless rendering, and exports share the same geometry.
+Layout is deterministic and renderer-independent. Legend items use Unicode-aware text estimates for spacing and automatically wrap when a row is full; a single label that cannot fit is truncated and reports `LEGEND_OVERFLOW`. Y-axis titles are centered beside their tick columns; Bar also places its categorical y-axis title vertically and centered on the left, with space reserved before the plot rectangle. If the chart is physically too short for a title, the renderer truncates it and reports `TITLE_TRUNCATED`. Axis and project-label reserves are computed before the plot rectangle, so Canvas, SVG, headless rendering, and exports share the same geometry.
 
 ## Encoding Contracts
 

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

@@ -33,7 +33,7 @@ Install the official Skill with the standard Agent Skills CLI:
 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.13/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.
+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.14/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`.
 

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

@@ -38,6 +38,10 @@ iChart.js 2.0 is a new Agent-first product line. Compatibility with 1.x and a 1.
 1. **Final commit and tag.** Commit the consistent `2.0.0` package, runtime, Playground, documentation, and changelog versions, then create `v2.0.0` from that exact commit.
 2. **Default branch cutover.** GitHub still uses `master`, which currently points to the archived 1.x project and its legacy development dependencies. Fast-forward `master` to the final 2.0 commit before creating the GitHub Release.
 
+## Iteration 13 Addendum — 2026-09-23
+
+The historical 2.0.0 release decision remains unchanged. Release `v2.0.14` includes Iteration 13 contract hardening without adding a chart type: 18 chart profiles, 25 commands, 11 schemas, contract version `1.1`, atomic mutation validation, Mindmap edge discovery, strict TypeScript consumer compilation, no active source cycles, 96 Node tests, Chromium browser acceptance, and package dry-run verification. It also corrects Bar y-axis title layout and exposes `TITLE_TRUNCATED` when physical chart height forces truncation.
+
 ## Deferred npm Publication
 
 The public npm name `ichartjs` currently resolves to an npm security holding package, and this machine has no authenticated publisher. Per the release decision, npm publication is deferred and does not block the GitHub source release.

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

@@ -0,0 +1,278 @@
+# Iteration 13 — Contract-Driven Runtime and Agent Reliability
+
+Iteration 13 hardens the architecture that now supports 18 public chart types, 25 edit commands, 11 business schemas, two renderers, project analytics, diagram editing, themes, preferences, and export. It adds no chart type and does not redesign the visual language. The goal is to make every public capability derive from one contract, make every mutation pass the same validation boundary, and make Agent guidance executable rather than advisory.
+
+## Review Baseline
+
+The plan is based on a repository-wide review of the runtime, Agent documentation, manifests, TypeScript declarations, tests, Playground, and package output at `v2.0.13`.
+
+- `npm run agent:check` passes with 95 tests, 18 chart types, 25 commands, and 11 schemas.
+- `npm run test:browser` passes its current Chrome layout scenario.
+- `npm pack --dry-run --json` succeeds with 90 package entries.
+- The dual-renderer, single-Scene-Graph architecture remains the correct foundation.
+- The main risks are contract drift and concentration of responsibilities, not a lack of chart types.
+
+## Review Findings
+
+| Priority | Finding | Evidence | Iteration 13 response |
+| --- | --- | --- | --- |
+| P0 | Construction validates a Spec, but `Chart#update()` and `Chart#setData()` normalize and render without running the same validation. Invalid post-construction state can therefore become live. | `src/index.mjs` constructor versus `update()` and `setData()` | Add one transactional prepare/validate/commit pipeline for creation and mutation. |
+| P0 | Project validation is not consistently row-complete. Gantt, Timeline, and Milestone accept rows missing required dates when another row has a date, and Burndown does not reject invalid dates at the Spec boundary. | `src/spec.mjs` project validation branch | Add chart-family row contracts and precise per-row diagnostics. |
+| P0 | Runtime capabilities, JSON manifests, command/schema metadata, TypeScript declarations, and prose are manually mirrored. Existing checks compare only selected lists and fields. | `src/capabilities.mjs`, `src/index.mjs`, `docs/manifests/`, `types/index.d.ts`, `scripts/check-agent-docs.mjs` | Establish a canonical registry and generate or structurally verify every public projection. |
+| P1 | The runtime supports JPEG through the detailed export contract while the summary export list omits it; the packaged capability manifest points to per-chart profiles but does not contain them. | `getCapabilities().exports`, `getCapabilities().export.types`, `docs/manifests/capabilities.json` | Define one export capability shape and publish complete offline profiles. |
+| P1 | The `Chart` runtime exposes event, inspection, selection, clipboard, diagram, plugin, and low-level methods that are missing from the declared `Chart` interface. There is no TypeScript consumer compilation gate. | `src/index.mjs` and `types/index.d.ts` | Define the supported public surface explicitly and compile representative consumers in CI. |
+| P1 | Mindmap edge editing reuses the Flow edge schema internally, but command capability metadata does not represent Mindmap edges even though Iteration 12 promises a shared diagram edge-editing contract. | `src/edit.mjs`, `src/command.mjs`, `docs/manifests/commands.json` | Introduce an explicit shared diagram-edge model or a declared Mindmap edge model and align edit discovery. |
+| P1 | `src/index.mjs`, chart/project scene construction, and `tests/core.test.mjs` contain many unrelated responsibilities. This raises regression scope and makes ownership boundaries harder for Agents to infer. | Runtime and test module sizes and imports | Extract cohesive runtime controllers and split tests by contract and chart family without changing the root import. |
+| P1 | Agent documentation checks prove presence, links, and selected identifiers, but do not execute examples, validate English/Chinese contract parity, or ensure Skill selection guidance covers all public types. | `scripts/check-agent-docs.mjs`, `skills/ichartjs/references/chart-selection.md` | Add executable documentation fixtures, semantic parity checks, and complete Skill routing coverage. |
+
+## Architectural Intent
+
+The root package remains a single ESM entry. Internal decomposition must not create competing runtimes or renderer-specific business logic.
+
+```mermaid
+flowchart LR
+    A[Canonical contract registry] --> B[Runtime capability API]
+    A --> C[JSON manifests]
+    A --> D[Type declarations]
+    A --> E[Agent docs and Skill fixtures]
+    B --> F[Spec planning and validation]
+    C --> F
+    D --> G[TypeScript consumer checks]
+    E --> H[Executable documentation checks]
+    F --> I[Chart runtime]
+    G --> J[Release gate]
+    H --> J
+    I --> J
+    style A fill:#bbdefb,color:#0d47a1
+    style F fill:#fff3e0,color:#e65100
+    style I fill:#c8e6c9,color:#1a5e20
+    style J fill:#f3e5f5,color:#7b1fa2
+```
+
+All state-changing APIs use the same transaction boundary:
+
+```mermaid
+sequenceDiagram
+    participant Host
+    participant Chart
+    participant Contract as Validation Contract
+    participant Scene as Scene Builder
+    participant Renderer
+    Host->>Chart: create / update / setData / applyEdit
+    Chart->>Contract: normalize candidate and validate
+    alt invalid candidate
+        Contract-->>Chart: structured diagnostics
+        Chart-->>Host: reject; retain previous Spec and Scene
+    else valid candidate
+        Contract-->>Chart: normalized immutable candidate
+        Chart->>Scene: build next Scene Graph
+        Scene-->>Chart: model and state
+        Chart->>Renderer: commit render
+        Chart-->>Host: emit one committed change
+    end
+```
+
+## Design Rules
+
+- Keep `@taylorwong/ichartjs` as the only runtime entry point.
+- Preserve the single normalized Spec and Scene Graph shared by Canvas, SVG, headless export, and browser export.
+- Keep chart selection, validation, capabilities, manifests, types, recipes, and docs consistent by construction.
+- Reject invalid state before mutating the live chart; failed changes leave Spec, Scene, selection, history, and revision unchanged.
+- Keep interaction and editing disabled by default unless the host enables them explicitly.
+- Keep public behavior backward compatible unless the current behavior violates a documented validation or safety invariant.
+- Prefer internal modules with one responsibility over new package-level subpaths.
+- Do not add a runtime dependency solely for code generation or validation.
+
+## Review Adjustments — Reliability Requirements Added
+
+The initial plan is sound, but the following requirements are part of Iteration 13 rather than optional follow-up work. They close the remaining gaps between a structurally consistent API and a runtime that an Agent can safely operate.
+
+### Mutation and error contract
+
+- Successful `update()` and `setData()` remain chainable and return `this`; invalid mutations throw one documented `ChartValidationError` with stable `code`, `details`, `path`, `expected`, `received`, and `suggestion` fields.
+- `applyEdit()` keeps its existing `{ valid, errors }` result contract so edit preview/commit flows do not change shape.
+- A failed mutation emits no change event, does not invalidate history, does not change selection or revision, and does not replace the previous rendered output.
+- `setTheme()` and `setPreferences()` use the same style preparation boundary; `applyPatch()` is either routed through validation or explicitly marked advanced and excluded from the safe mutation guarantee.
+- Plugin installation and renderer replacement must declare whether they are transactional. If they cannot roll back external side effects, they must return a structured failure and be excluded from the atomic mutation claim.
+
+### Determinism, safety, and observability
+
+- Add a separate `contractVersion`, independent of the package semver. Additive contract fields preserve the version; removed, renamed, or reinterpreted fields require a version change and release note.
+- Use explicit policies for stable IDs, duplicate IDs, ISO-8601 dates, date-only values, time zones, duplicate Burndown dates, ordering, locale, rounding, and generated fallback IDs. Fallback IDs are allowed only for read-only visualization and must produce a warning.
+- Define capability limits for rows, nodes, edges, recursion depth, and export size. Exceeding a limit must produce a deterministic diagnostic rather than a browser hang or uncontrolled memory growth.
+- Verify that SVG text, labels, titles, and diagram content are emitted as text-safe values and cannot become executable markup. Canvas and SVG must expose equivalent semantic text and data references.
+- Give every diagnostic a stable code and severity, and document whether it is an error, warning, normalization, or unsupported-option notice. Agent-facing diagnostics must remain locale-aware without changing their codes.
+- Make lifecycle guarantees explicit: `destroy()` is idempotent, failed render preparation releases temporary resources, and listeners, observers, tooltips, and plugins do not leak after destroy.
+
+### Projection and release evidence
+
+- The JavaScript registry is the runtime source of truth; manifests are generated or compared from a normalized JSON-safe projection, not deep-compared against objects containing functions or implementation details.
+- Runtime version synchronization is checked by release tooling against `package.json`; the browser runtime does not dynamically depend on Node-only package metadata.
+- Every release candidate records the contract version, package version, manifest checksum, package entry import, JSON subpath import, recipe import, TypeScript consumer result, and expected unsupported export results.
+
+## 13A — Canonical Public Contract Registry
+
+1. Add a canonical, JSON-safe registry for chart types, families, required data roles, encoding channels, features, interactions, renderers, exports, limits, business models, edit operations, and preference fields.
+2. Make `getCapabilities()`, `getChartCapability()`, `validateSpec()`, command discovery, and schema discovery consume that registry instead of repeating lists.
+3. Generate `docs/manifests/capabilities.json`, `commands.json`, and `schemas.json` from the registry, or make a deterministic check compare their complete structures.
+4. Include complete per-chart profiles in the packaged capability manifest so an offline Agent does not need to inspect source code.
+5. Replace the ambiguous top-level `exports` summary with one canonical export list that includes PNG, JPEG, SVG, and JSON consistently.
+6. Declare a shared `diagram-edge` contract or explicit Flow, Architecture, and Mindmap edge models with identical supported edit operations where behavior is shared.
+7. Add stable contract versioning rules: additive fields retain the current contract version; removed or reinterpreted fields require a version change and migration note.
+8. Keep runtime version metadata sourced from package metadata during release checks rather than requiring unrelated hand-edited literals.
+
+### 13A Checkpoint
+
+- Changing a chart type, command, schema, interaction, export, or preference in one registry updates or fails every dependent projection.
+- `getCapabilities()` and the packaged JSON manifest are deep-equal for their shared contract.
+- Every chart profile is available without executing the runtime.
+- Mindmap edge operations are discoverable and match actual preview/commit behavior.
+
+## 13B — Transactional Validation and Data Integrity
+
+1. Extract a shared `prepareSpec(candidate)` path that performs normalization, validation, theme/preference resolution, and diagnostic collection before commit.
+2. Route the constructor, `update()`, `setData()`, renderer changes, and accepted edit results through the same preparation boundary.
+3. Make failed updates atomic: do not change the live Spec, renderer, Scene, history, selection, revision, subscriptions, or emitted change events.
+4. Preserve the current constructor error shape and define the `ChartValidationError` mutation failure contract described above.
+5. Validate every Gantt row for stable ID, start, end, valid interval, dependency references, and declared dependency semantics.
+6. Validate every Timeline and Milestone row for stable ID, label/title, and valid ISO-8601 date.
+7. Validate every Burndown row for valid date and finite remaining work; validate ordering and duplicate-date policy explicitly.
+8. Reuse business schema rules where possible so Spec validation and edit validation do not disagree.
+9. Add immutable-input tests for creation, update, data replacement, failed validation, edit commit, undo, and redo.
+10. Preserve warnings and normalizations across updates instead of retaining stale constructor diagnostics.
+
+### 13B Checkpoint
+
+- An invalid update returns structured diagnostics and leaves `chart.getSpec()`, `getState()`, revision, and rendered output unchanged.
+- Project charts reject invalid rows with exact paths such as `data.values[3].start`.
+- Constructor, update, and data replacement agree on validity for the same candidate Spec.
+- Valid existing Specs and recipes produce unchanged normalized output and Scene snapshots.
+
+## 13C — Runtime Boundary Refactoring
+
+1. Reduce `src/index.mjs` to public composition and exports by extracting lifecycle, event binding, accessibility, selection, export, and download responsibilities into focused internal modules. Freeze the supported public method allowlist before extraction; do not infer public API from every current class method.
+2. Extract headless/browser export serialization from the `Chart` class while preserving all current method signatures and output representations.
+3. Separate generic chart-family scene builders from shared chrome layout:
+   - Cartesian marks and axes.
+   - Part-to-whole, stage, and indicator marks.
+   - Matrix and radial marks.
+   - Shared title, legend, label, branding, and diagnostic layout.
+4. Keep project chart scene construction separate from diagram scene construction; both continue to return the same Scene Graph contract.
+5. Move renderer-independent interaction state transitions out of DOM event wiring so they can be tested headlessly.
+6. Define internal dependency direction as contracts/data → validation/layout → scene builders → runtime controllers → public entry.
+7. Add a cycle check for active `src/` modules.
+8. Keep each extraction behavior-preserving and land it with focused parity tests before removing the old implementation. Large scene-builder moves are optional for the first Iteration 13 release and must not block the contract and transaction work.
+
+### 13C Checkpoint
+
+- The public root exports and `iChart` compatibility object remain unchanged except for documented contract corrections.
+- Canvas, SVG, and headless SVG consume equivalent Scene Graphs before and after extraction.
+- No active source module has a circular dependency.
+- Lifecycle, export, interaction, and chart-family tests can run independently.
+
+## 13D — Complete Types and Executable Agent Guidance
+
+1. Define an explicit supported `Chart` API allowlist and add declarations for events, plugins, data inspection, selected data, data tables, diagram collections, clipboard operations, connection operations, group collapse, hit testing, and box selection. Do not automatically declare every internal method found on the class.
+2. Mark low-level APIs such as `applyPatch()` explicitly as advanced or deprecated if they cannot uphold the transactional contract.
+3. Replace broad `Record<string, unknown>` return values with named result, state, event, diagnostic, selection, and edit interfaces where the runtime shape is stable.
+4. Add TypeScript consumer fixtures for generic charts, project analytics, diagram editing, preferences, events, and every export representation.
+5. Add an API reference generated from or verified against runtime exports and TypeScript declarations.
+6. Convert canonical Quickstart, Runtime Contract, Editing Contract, and Skill examples into executable fixtures using local package imports.
+7. Add stable section IDs or contract markers to English and Chinese guides, then check required sections, API names, warning codes, and examples in both languages.
+8. Complete Skill chart selection for Architecture and Mindmap and ensure every public chart type maps to at least one supported intent and guardrail.
+9. Keep English as the canonical technical contract and Chinese as an equivalent companion, without requiring literal sentence-by-sentence translation.
+
+### 13D Checkpoint
+
+- A representative TypeScript consumer compiles with no local declaration patches.
+- Every documented public `Chart` method exists at runtime and in `types/index.d.ts`.
+- Canonical documentation code blocks execute or are explicitly marked illustrative.
+- English and Chinese guides expose the same required contract sections and identifiers.
+- The official Skill can route all 18 public chart types using only packaged references and manifests.
+
+## 13E — Test Architecture and Release Evidence
+
+1. Split the monolithic core test into focused suites for Spec/data, capabilities/contracts, generic charts, project charts, diagrams, editing/history, preferences/themes, exports, lifecycle, and package consumers.
+2. Keep shared fixtures for all chart types, renderers, project rows, diagram entities, and diagnostics to avoid diverging test data.
+3. Add contract matrix tests covering every chart type × renderer × export declaration without requiring every combination to use a browser; unsupported combinations must assert their documented structured failure rather than being treated as test omissions.
+4. Expand browser coverage beyond layout to one end-to-end path each for generic interaction, project inspection, diagram editing, preferences, accessibility, and export.
+5. Add mutation rollback tests for invalid update, invalid data replacement, stale edit, failed renderer switch, plugin failure, event suppression, revision stability, and idempotent destroy.
+6. Add manifest regeneration/diff checks, TypeScript compilation, documentation examples, module-cycle checks, and package-consumer tests to CI.
+7. Keep Node 18, 20, and 22 coverage; run browser acceptance once on the primary CI Node version.
+8. Record physical-device touch and release-host performance as environment evidence, not as claims inferred from desktop automation.
+
+### 13E Checkpoint
+
+- A failure identifies one contract or feature suite instead of only `tests/core.test.mjs`.
+- Browser CI exercises behavior, not only geometry.
+- `npm run agent:check` includes contract, type, docs-example, syntax, and core test gates.
+- `npm run test:browser` covers the maintained critical workflows with no uncaught errors.
+- `npm pack --dry-run` contains synchronized manifests, types, Agent guides, Skill references, recipes, and examples.
+
+## Execution Order
+
+1. Freeze the mutation error contract, public API allowlist, contract version, and stable-ID policy before implementation.
+2. Land 13A first so later work consumes one authoritative contract.
+3. Implement 13B before refactoring runtime classes; lock current valid behavior with mutation, project-data, determinism, and safety tests.
+4. Complete 13D against the stabilized registry and public API allowlist.
+5. Execute 13C as small behavior-preserving extractions with parity checks after each move; defer large scene-builder moves if they threaten the release gate.
+6. Promote 13E checks continuously after each phase, then record final acceptance evidence.
+
+Each phase must be independently releasable. Do not combine a behavior correction and a large file move in the same change unless tests prove the old and new paths are equivalent.
+
+## Non-Goals
+
+- No new public chart type.
+- No Map, 3D, Fishbone, Organization Chart, Kanban, or collaborative multi-user editing.
+- No second runtime entry and no framework-specific wrapper.
+- No renderer-specific Spec or edit contract.
+- No visual redesign of existing charts, themes, or Playground pages.
+- No mandatory server, database, AI provider, or native Canvas dependency.
+- No claim of semantic translation quality based only on file presence or matching line counts.
+
+## Acceptance Matrix
+
+| Area | Required evidence |
+| --- | --- |
+| Architecture | No active module cycles; root entry remains stable; extracted controllers pass parity tests. |
+| Contracts | Runtime capabilities, manifests, commands, schemas, preferences, and exports match the canonical registry. |
+| Functionality | Invalid mutations roll back; project rows validate individually; existing valid output remains compatible. |
+| Agent | Offline manifest includes complete profiles; planning, validation, explanation, and Skill routing agree. |
+| Types | TypeScript fixtures compile for lifecycle, events, editing, diagrams, preferences, and exports. |
+| Documentation | Canonical examples execute; local links resolve; English/Chinese contract markers match. |
+| Rendering | Canvas/SVG Scene semantics and headless SVG export remain equivalent. |
+| Browser | Generic, project, diagram, preferences, accessibility, and export workflows pass in maintained browser tests. |
+| Packaging | ESM import, JSON subpaths, recipes, declarations, Skill files, and dry-run tarball checks pass. |
+
+## Verification Commands
+
+- `npm run agent:check`
+- `npm run test:browser`
+- `npm run example:agent`
+- `npm pack --dry-run`
+- `git diff --check`
+
+The implementation may add focused scripts such as `contracts:check`, `types:check`, `docs:examples`, and `deps:check`; `agent:check` must invoke the non-browser gates so local and CI behavior stay aligned.
+
+## Deliverables
+
+- Canonical public contract registry and deterministic manifest generation/checking.
+- Transactional Spec/data mutation pipeline with row-complete project validation.
+- Focused runtime controllers and chart-family scene modules behind the unchanged root entry.
+- Complete public TypeScript surface and compiled consumer fixtures.
+- Executable Agent documentation checks and bilingual semantic parity markers.
+- Complete Architecture/Mindmap Skill routing and diagram-edge capability metadata.
+- Split unit/contract suites and expanded critical browser workflows.
+- Updated `roadmap.md`, Agent guides, manifests, Skill references, changelog, and acceptance record.
+
+## Implementation Evidence
+
+- Contract source: `src/contract-registry.mjs`; generated projection: `docs/manifests/capabilities.json`; synchronized checks: `npm run contracts:check`.
+- Mutation safety: `ChartValidationError`, atomic `update()`/`setData()`/`setTheme()`/preference/patch paths, project row diagnostics, duplicate/out-of-order Burndown warnings, and idempotent `destroy()`.
+- Diagram contract: explicit `mindmap-edge` schema and command discovery aligned with Flow and Architecture edge operations.
+- Agent/type gates: `npm run types:check` compiles `types/consumer-fixture.ts` with TypeScript 5.9; `npm run docs:examples` completes the packaged Agent workflow; `npm run deps:check` reports no source cycles.
+- Acceptance: 95 Node tests, maintained Chromium browser workflow, `git diff --check`, and `npm pack --dry-run` with 94 files passed. The npm dry-run uses a temporary cache to avoid unrelated root-owned cache files.
+
+## Completion Definition
+
+Iteration 13 is complete when one authoritative contract drives runtime discovery and packaged metadata; every chart mutation is validated and atomic; the public TypeScript surface matches the supported runtime; Agent examples and bilingual contract markers are mechanically checked; internal runtime responsibilities are separated without changing valid output; and all automated, browser, package, and documentation gates pass. New chart types remain deferred until this foundation is complete.

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.13` includes the completed Iteration 12 structured-diagram work, follow-up chart/menu fixes, hardened Agent chart contracts, Unicode-aware layout, typed Gantt routing, and horizontal Architecture layers. Geographic charts and 3D rendering remain out of scope until explicitly reintroduced.
+> Roadmap baseline: 2026-09-14. Current release status: `v2.0.14` includes the completed Iteration 12 structured-diagram work, Iteration 13 contract hardening, and the Bar y-axis title layout fix. Geographic charts and 3D rendering remain out of scope until explicitly reintroduced.
 
 ## Current Status
 
@@ -15,6 +15,7 @@
 - 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.
 - Iteration 12A–12G is included in `v2.0.7`: shared structured-diagram contracts, Architecture layers/boundaries, Mindmap parent-child tree/radial layouts with true cubic-Bezier edges, Agent schemas/capabilities, renderer-parity edge hit testing and selection, waypoint/segment handles, persistent manual routing, and Gallery/documentation coverage. Navigation and editing remain disabled by default and require explicit host activation.
+- Iteration 13A–13E is complete and included in `v2.0.14`: canonical contract registry and generated capability projection, atomic Spec/data/style mutations, row-complete project validation, explicit Mindmap edge metadata, complete public TypeScript declarations and consumer fixture, module-cycle and documentation/example gates, browser acceptance, and package dry-run evidence. No 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/editing-contract.md

@@ -54,10 +54,13 @@ Core APIs:
 - `swimlane`
 - `architecture-node`
 - `architecture-edge`
+- `mindmap-edge`
 - `mindmap-node`
 
 ## History and Revision
 
+Spec/data mutations use the same atomic boundary as edits. Catch `ChartValidationError` for invalid `update()`, `setData()`, `setTheme()`, or preference input; the failed call emits no committed change and does not advance the revision.
+
 Successful commits produce a ChangeSet, audit information, a revision, and an undo history entry. A preview based on an old revision must fail on commit with `STALE_PREVIEW`.
 
 ## Implementation Map

package/docs/agent/frontend-integration.md

@@ -10,7 +10,7 @@ This is the production component path. For one-off files or Agent-led repository
 npm install @taylorwong/ichartjs@^2
 ```
 
-For environments without npm registry access, install from GitHub as a fallback: `npm install github:wanghetommy/ichartjs#v2.0.13`.
+For environments without npm registry access, install from GitHub as a fallback: `npm install github:wanghetommy/ichartjs#v2.0.14`.
 
 Use the package through a bundler or another environment that resolves npm ESM imports:
 

package/docs/agent/runtime-contract.md

@@ -91,6 +91,8 @@ All export/download methods return a stable `{ valid:false, code, message?, sugg
 
 ## Common APIs
 
+State-changing calls use one validation boundary. `update()` and `setData()` return the chart when committed; invalid input throws `ChartValidationError` with stable `code`, `details`, `path`, `expected`, `received`, and `suggestion` fields. The previous Spec, Scene, selection, revision, and history remain unchanged after a rejected mutation. `applyPatch()` is an advanced JSON-pointer API and is validated before commit.
+
 ```text
 inspectData(data)
 normalizeData(data)
@@ -105,6 +107,8 @@ validatePreferences(patch, options)
 chart.describe()
 chart.explain()
 chart.getState()
+chart.getState().health
+chart.explain().health
 chart.getPreferences()
 chart.setPreferences(patch, options)
 chart.resetPreferences(options)

package/docs/agent/usage-scenarios.md

@@ -121,7 +121,7 @@ npx skills add wanghetommy/ichartjs --skill ichartjs --agent codex --global --ye
 For reproducible installation, pin the released Skill directory:
 
 ```bash
-npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.13/skills/ichartjs \
+npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.14/skills/ichartjs \
   --agent codex --global --yes
 ```
 

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

@@ -42,7 +42,7 @@
 
 不要把 `title`、`format`、`labels` 或 `legend` 放在 `encoding` 中；`validateSpec()` 会报告结构化警告。数值纵轴默认使用易读域（`nice: true`、`ticks: "auto"`）；需要固定范围时使用 `yAxis.domain: [min, max]`，需要保留原始边界时使用 `yAxis.nice: false`。分类/时间横轴的 `min/max` 和 `domain` 不支持。
 
-布局保持确定性且不依赖 Renderer。图例使用 Unicode-aware 文本宽度估算来计算间距，并在单行空间不足时自动换行；单个标签仍无法放入可用宽度时会省略并报告 `LEGEND_OVERFLOW`。左右数值 Y 轴标题在刻度列外侧居中显示，Bar 的分类 Y 轴标题则保持水平并位于分类标签列上方。坐标轴和项目标签空间会在确定绘图区之前完成预留，因此 Canvas、SVG、Headless 和导出共享相同几何。
+布局保持确定性且不依赖 Renderer。图例使用 Unicode-aware 文本宽度估算来计算间距，并在单行空间不足时自动换行；单个标签仍无法放入可用宽度时会省略并报告 `LEGEND_OVERFLOW`。Y 轴标题都在刻度列外侧居中显示；Bar 的分类 Y 轴标题也会在左侧垂直居中，并在确定绘图区之前预留空间。如果图表高度确实不足以容纳标题，渲染器才会截断，并报告 `TITLE_TRUNCATED`。坐标轴和项目标签空间会在确定绘图区之前完成预留，因此 Canvas、SVG、Headless 和导出共享相同几何。
 
 ## Encoding 契约
 

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

@@ -22,7 +22,7 @@ npm Registry 中无作用域的 `ichartjs` 是安全占位包，并非本项目
 npx skills add wanghetommy/ichartjs --skill ichartjs
 ```
 
-Codex 全局无交互安装可追加 `--agent codex --global --yes`。需要固定发布版本时，安装 `https://github.com/wanghetommy/ichartjs/tree/v2.0.13/skills/ichartjs`。WorkBuddy 可通过自身 Skill 界面导入该带 Tag 的目录；只有当前 CLI 明确声明对应适配器时才使用宿主专用 `--agent` 参数。
+Codex 全局无交互安装可追加 `--agent codex --global --yes`。需要固定发布版本时，安装 `https://github.com/wanghetommy/ichartjs/tree/v2.0.14/skills/ichartjs`。WorkBuddy 可通过自身 Skill 界面导入该带 Tag 的目录；只有当前 CLI 明确声明对应适配器时才使用宿主专用 `--agent` 参数。
 
 使用 `npx skills add wanghetommy/ichartjs --list` 验证发现结果，其中应包含 `ichartjs`。
 

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

@@ -25,5 +25,7 @@ const result = chart.applyEdit(command, { preview, confirmed: true, source: 'age
 - 外部持久化、权限和认证由 Host 应用负责。
 - 指针导航和编辑默认关闭。`editing.enabled` 授权编辑事务；`interaction.drag`、`interaction.edgeDrag`、`interaction.portConnect` 分别控制直接操作 UI。
 - Diagram 边通过 JSON-safe 的 `waypoints` 持久化；路径更新使用 `updateEdge`，删除使用 `removeEdge`，并要求结构编辑权限。
+- Mindmap 边使用独立的 `mindmap-edge` 契约，但与 Flow、Architecture 共享相同的边编辑语义。
+- `update()`、`setData()`、`setTheme()` 和偏好设置输入失败时抛出结构化 `ChartValidationError`，失败不会推进 revision 或破坏历史。
 
 Schema、命令、Preview/Commit、事务和历史的实现分别位于 `src/schema.mjs`、`src/command.mjs`、`src/edit.mjs`、`src/edit-controller.mjs` 和 `src/history.mjs`。

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

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

@@ -86,6 +86,8 @@ iChart.js 导出采用**双底层单源架构**，所有产物共享 `buildScene
 - `DOWNLOAD_HEADLESS`：`chart.download*()` 仅在浏览器有 DOM 时可用，无头用 `export`。
 - `EXPORT_TYPE_UNSUPPORTED`：不支持的导出类型。
 
-公共 API：`inspectData`、`normalizeData`、`planChart`、`recommend`、`validateSpec`、`createChart`、`getCapabilities`、`getChartCapability`、`getPreferenceCapabilities`、`validatePreferences`、`chart.describe`、`chart.explain`、`chart.getState`、`chart.getPreferences`、`chart.setPreferences`、`chart.resetPreferences`、`chart.selectEdges`、`chart.getSelectedEdgeIds`、`chart.deleteSelectedEdges`、`chart.export`、`chart.exportAsync`、`chart.toDataURL`、`chart.toBlob`、`chart.download`、`chart.downloadPNG`、`chart.downloadSVG`、`chart.downloadJSON`。
+所有状态变更都经过同一校验边界。成功的 `update()` 和 `setData()` 返回当前 Chart；无效输入抛出 `ChartValidationError`，包含稳定的 `code`、`details`、`path`、`expected`、`received` 和 `suggestion`。拒绝变更后，原 Spec、Scene、选择状态、revision 和历史记录保持不变。`applyPatch()` 是高级 JSON Pointer 接口，也会在提交前校验。
+
+公共 API：`inspectData`、`normalizeData`、`planChart`、`recommend`、`validateSpec`、`createChart`、`getCapabilities`、`getChartCapability`、`getPreferenceCapabilities`、`validatePreferences`、`chart.describe`、`chart.explain`、`chart.getState`、`chart.getState().health`、`chart.explain().health`、`chart.getPreferences`、`chart.setPreferences`、`chart.resetPreferences`、`chart.selectEdges`、`chart.getSelectedEdgeIds`、`chart.deleteSelectedEdges`、`chart.export`、`chart.exportAsync`、`chart.toDataURL`、`chart.toBlob`、`chart.download`、`chart.downloadPNG`、`chart.downloadSVG`、`chart.downloadJSON`。
 
 实现位置：`src/index.mjs`、`src/spec.mjs`、`src/scene.mjs`、`src/renderer.mjs`、`src/plugin.mjs`、`src/scale.mjs`、`src/charts.mjs`、`src/capabilities.mjs`。

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

@@ -116,7 +116,7 @@ npx skills add wanghetommy/ichartjs --skill ichartjs --agent codex --global --ye
 需要固定发布版本时，直接安装已发布的 Skill 目录：
 
 ```bash
-npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.13/skills/ichartjs \
+npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.14/skills/ichartjs \
   --agent codex --global --yes
 ```