@taylorwong/ichartjs 2.0.1

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

@@ -0,0 +1,261 @@
+# Iteration 4 — Agent Data Contract and Business Editing
+
+## Delivery status
+
+4A, 4B, 4C, 4D, and 4E are implemented in the local runtime. The viewable acceptance demo is available at `http://localhost:3000/playground/editing`.
+
+- 4C: guarded local commit, exact preview/revision checks, change set, audit metadata, and edit events.
+- 4D: undo/redo history, recipe validation, capability discovery, and TypeScript declarations.
+- 4E: unit coverage and a browser-facing preview/commit/undo/redo flow. External persistence and authorization remain host responsibilities.
+
+## Goal
+
+Upgrade iChart.js 2.0 from an Agent-capable visualization runtime into a safe, explainable, and production-ready business-data editing runtime.
+
+An Agent must be able to inspect a business data contract, generate a typed edit command, preview its impact, validate the change, request confirmation when required, commit the change, and undo it. Direct arbitrary mutation is not the primary Agent interface.
+
+Geographic charts and 3D rendering remain outside this iteration.
+
+Status: 4A–4E implemented for the local runtime. External persistence, authorization, true-device touch testing, and host application release controls remain outside the runtime.
+
+## Core Concepts
+
+```text
+Chart Spec
+  → describes how data is displayed
+Business Data Schema
+  → describes fields, types, permissions, and business rules
+Edit Command
+  → describes the intended business operation
+Validation and Diff
+  → explains whether and how data will change
+Data Store / JSON Patch
+  → applies the normalized mutation
+Scene Graph
+  → re-renders the result
+```
+
+## Task List
+
+### A. Business Data Schema
+
+1. Add a versioned `BusinessDataSchema` contract.
+2. Define field types: `string`, `number`, `boolean`, `date`, `enum`, `array`, and `object`.
+3. Support `required`, `default`, `nullable`, `min`, `max`, `pattern`, and enum values.
+4. Define primary keys, foreign keys, and references between records.
+5. Define field edit permissions: editable, read-only, Agent-editable, and user-only.
+6. Define data-to-chart encoding mappings for project and diagram views.
+7. Define cross-field business rules with stable rule IDs and messages.
+8. Validate dates, intervals, dependencies, node IDs, lane IDs, and status transitions.
+9. Return structured errors with `code`, `path`, `rule`, `message`, and `suggestion`.
+10. Add schema version compatibility and migration hooks.
+
+### B. Business Data Models
+
+11. Add the `project-task` model for Gantt and schedule data.
+12. Add the `timeline-event` and `milestone` models.
+13. Add the `burndown-sample` model, including scope changes and forecast fields.
+14. Add the `flow-node`, `flow-edge`, and `swimlane` models.
+15. Normalize dates, IDs, statuses, percentages, and dependency arrays.
+16. Preserve original source values and normalized values where conversion occurs.
+17. Add data-quality warnings for missing, ambiguous, or inferred values.
+
+### C. Typed Edit Commands
+
+18. Define a versioned `EditCommand` envelope.
+19. Add `updateField` for a single field change.
+20. Add `updateRecord` for validated multi-field changes.
+21. Add `addRecord` and `removeRecord`, disabled by default.
+22. Add `updateTask` for project-task changes.
+23. Add `shiftTask` for date movement with dependency policies.
+24. Add `updateProgress` for progress and status changes.
+25. Add `addDependency` and `removeDependency` with cycle checks.
+26. Add `updateMilestone` for event date and status changes.
+27. Add `moveNode` for diagram layout changes.
+28. Add `moveNodeToLane` for responsibility changes.
+29. Add `updateEdge` for controlled process relationship changes.
+30. Keep layout edits separate from business-data edits.
+
+### D. Validation and Preview
+
+31. Implement `inspectDataSchema()`.
+32. Implement `validateData()`.
+33. Implement `validateEdit(command)` without mutating the source.
+34. Implement `previewEdit(command)` with before/after values.
+35. Calculate affected records and dependent tasks.
+36. Report warnings for critical-path, completed-task, and destructive changes.
+37. Report dependency shifts and schedule conflicts.
+38. Support policies for shifting dependents, allowing negative slack, and requiring confirmation.
+39. Produce normalized JSON Patch only after command validation.
+40. Make preview output deterministic and JSON serializable.
+
+### E. Commit, History, and Audit
+
+41. Implement `applyEdit(command)`.
+42. Require confirmation by default for destructive or structural changes.
+43. Implement `getChangeSet()`.
+44. Implement `undo()` and `redo()`.
+45. Store operation IDs, actor, timestamp, reason, source, and affected records.
+46. Support optimistic version checks to prevent stale updates.
+47. Emit `beforeedit`, `edit`, `editerror`, and `undoredo` events.
+48. Ensure failed edits leave the original data unchanged.
+49. Ensure chart re-rendering occurs only after a successful commit.
+50. Keep an audit record separate from user-visible chart data.
+
+### F. Agent Contract and Capability Discovery
+
+51. Extend `getCapabilities()` with schema and editing capabilities.
+52. Add `getEditCapabilities(schema)` for field and operation permissions.
+53. Add Agent response fields for selected model, assumptions, warnings, diff, and confirmation requirement.
+54. Add Recipe examples for schedule changes, progress updates, dependency changes, and workflow ownership.
+55. Add a Recipe validator for both Chart Spec and Business Data Schema.
+56. Document that arbitrary `applyPatch()` is a low-level API, not the preferred Agent API.
+57. Add safe defaults: confirmation required, delete disabled, structural edits disabled.
+
+### G. TypeScript, Runtime, and Demos
+
+58. Add TypeScript declarations for schemas, commands, policies, diffs, and audit records.
+59. Add framework-neutral data-store adapters.
+60. Add headless preview and export of change sets.
+61. Add a browser demo for preview → confirm → commit → undo.
+62. Add a Gantt demo for shifting a task and optionally shifting dependents.
+63. Add a Flow demo for moving a node and persisting layout only.
+64. Add invalid-command and rollback demonstrations.
+65. Add mobile-safe confirmation and edit controls.
+
+### H. Production Release Gates
+
+66. Stabilize public APIs and document RC compatibility rules; release `2.0.0-rc.1` only after all gates pass.
+67. Establish core/renderer/plugin/recipe module boundaries without duplicating implementations; assess package splitting separately from introducing mandatory dependencies.
+68. Add renderer/export capability negotiation, explicit unsupported results, and deterministic SVG/PNG/JSON export tests, including headless output.
+69. Complete keyboard focus, ARIA relationships, and reduced-motion behavior in editing and viewing modes.
+70. Define reproducible small/medium/large data benchmarks with documented dataset sizes, hardware, and acceptance budgets before measuring.
+71. Test event, observer, tooltip, plugin, resize, and destroy lifecycles for leaks and stale state.
+72. Re-audit Iteration 2/3 feature claims and record actual functional/browser acceptance gaps; passing unit tests or matching node IDs alone does not establish mobile or renderer interaction parity.
+
+## Execution Order and Checkpoints
+
+| Phase | Tasks | Dependency | Viewable or inspectable result |
+| --- | --- | --- | --- |
+| 4A — Contracts | 1–17, 66 | Audit existing data conventions | Schema, normalized fixtures, structured validation reports |
+| 4B — Command preview | 18–40 | 4A | Gantt change preview with before/after values and affected tasks |
+| 4C — Safe commit | 41–50, 57 | 4B | Trusted confirmation, atomic commit, conflict rejection, undo/redo |
+| 4D — Agent integration | 51–56, 58–65 | 4C | Agent recipes plus Gantt/Flow editing demo |
+| 4E — Release acceptance | 67–72 | 4A–4D | Reproducible acceptance report; RC only if all gates pass |
+
+Notify the user whenever an HTTP-served demo reaches an acceptance checkpoint. Report untested physical-device gestures separately from synthetic event tests and desktop mobile-viewport tests.
+
+## Authority and Data Boundaries
+
+- Editing is opt-in. Viewing/panning must not silently mutate business values. Keep `view-edit`, `layout-edit`, `data-edit`, and `structure-edit` distinct.
+- The chart library previews and edits local normalized data. Writing to an external business system requires a separately configured host adapter; this plan does not grant database access or promise built-in integrations.
+- The host/server enforces authentication, authorization, and confirmation. Schema field flags and Agent-supplied actor/confirmation fields are not security boundaries.
+- Confirmation must bind to the exact preview, data revision, and affected records. Revalidate permissions and revision at commit; reject a changed command or stale preview. Do not automatically apply a preview merely because it requires confirmation.
+- Use declarative rule objects and registered trusted validators. Do not evaluate arbitrary rule strings from data or Agent output using `eval` or `Function`.
+- Resolve records by stable IDs, not mutable array offsets. Commit batches atomically; external persistence must succeed before reporting persisted success. Undo against a changed revision must fail or require a new preview.
+- Task progress is canonical `0–100`; converting legacy `0–1` values requires an explicit source-unit setting. Define date-only values, timestamps, timezone, and exclusive interval ends separately. `shiftTask.days` uses explicit calendar-day rules; work calendars, holidays, and lead/lag remain Iteration 6 scope.
+- Derived critical-path and forecast values are read-only and recomputed. Business actor identity comes from the host; audit records in local memory are not durable or tamper-proof server audit logs.
+- Reuse the Iteration 4 history/command engine in Iteration 5 instead of creating another undo/redo implementation.
+
+## Recommended Public API
+
+```js
+const chart = createChart({
+  type: 'gantt',
+  data: { values: tasks, schema: taskSchema },
+  editing: {
+    enabled: true,
+    mode: 'command',
+    requireConfirmation: true,
+    allowDelete: false,
+    allowStructuralChanges: false
+  }
+});
+
+chart.inspectDataSchema();
+chart.validateData();
+const preview = chart.previewEdit({
+  type: 'edit',
+  target: 'project-task',
+  operations: [{
+    op: 'shiftTask',
+    taskId: 'development',
+    days: 2,
+    shiftDependents: true
+  }]
+});
+
+if (preview.valid) {
+  const approval = await host.requestEditApproval(preview);
+  if (approval.approved) {
+    await chart.applyEdit(preview.command, {
+      previewId: preview.id,
+      expectedRevision: preview.revision,
+      approval: approval.receipt
+    });
+  }
+}
+```
+
+`host.requestEditApproval()` is an application-owned integration point, not an existing iChart API. Its receipt must be checked by the host commit adapter, not trusted merely because an Agent supplied it.
+
+## Acceptance Criteria
+
+### Functional
+
+- A schema describes fields, types, editability, relationships, and business rules.
+- Invalid data and invalid commands return structured errors without partial mutation.
+- Typed commands support task updates, schedule shifts, progress changes, dependency changes, node movement, and lane movement.
+- `previewEdit()` returns deterministic before/after values, warnings, affected records, and confirmation requirements.
+- Successful commits update data and re-render the chart.
+- Undo and redo restore both data and layout edits.
+
+### Safety and Explainability
+
+- Deletes and structural changes require explicit confirmation.
+- Read-only fields cannot be changed by Agent commands.
+- Critical-path and completed-task changes produce warnings.
+- Every committed edit includes audit metadata.
+- Stale-version edits are rejected instead of overwriting newer data.
+- `applyPatch()` remains available only as a low-level escape hatch.
+
+### Rendering and Interaction
+
+- Gantt date edits update task bars and dependencies.
+- Flow node movement updates connected arrows and persists `node.position`.
+- SVG and Canvas reflect the same normalized data after an edit.
+- Mobile editing controls remain usable and do not conflict with pan/zoom.
+- Preview and confirmation UI is available in a viewable HTTP-served demo.
+
+### Quality Gate
+
+- `npm test` passes.
+- `npm run check` passes.
+- `git diff --check` passes.
+- Schema, command, validation, history, and audit tests pass.
+- Agent Recipes validate against the declared capabilities.
+- Browser acceptance covers preview, confirmation, commit, rollback, undo, SVG, Canvas, and mobile behavior.
+
+## Deliverables
+
+- `src/schema.mjs`
+- `src/validation.mjs`
+- `src/command.mjs`
+- `src/edit.mjs`
+- `src/history.mjs`
+- `types/`
+- `agent-recipes/editing/`
+- `playground/editing.html`
+- `docs/agent/editing-guide.md`
+- `2.0.0-rc.1`
+
+## Current Implementation Checkpoint
+
+- Available modules: `src/schema.mjs`, `src/validation.mjs`, `src/command.mjs`, and `src/edit.mjs`.
+- Available APIs: `getBusinessSchema()`, `inspectDataSchema()`, `validateData()`, `getEditCapabilities()`, `validateEdit()`, `previewEdit()`, `applyEdit()`, `getChangeSet()`, `undo()`, and `redo()`.
+- Viewable demo route: `http://localhost:3000/playground/editing` (source page: `playground/editing.html`) shows a Gantt change preview and confirms that source data remains unchanged.
+- The preview result is local and deterministic; it is not an authorization receipt and does not persist to an external system.
+
+## Completion Definition
+
+Iteration 4 is complete when an Agent can safely modify a validated business dataset through typed commands, preview a deterministic diff, obtain required confirmation, commit or roll back the change, and observe the result consistently in SVG and Canvas views.

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

@@ -0,0 +1,43 @@
+# Iteration 5 — Advanced Diagram Runtime
+
+## Current delivery
+
+The current runtime increment is available for review:
+
+- Diagram normalization for nodes, edges, lanes, groups, and diagram options.
+- Deterministic `manual`, `layered`, `tree`, and `radial` layout modes.
+- `straight`, `orthogonal`, and `curved` edge routing declarations.
+- Node size in scene layout and the typed `resizeNode` edit command.
+- Diagram validation for duplicate IDs, endpoints, lanes, groups, ports, cycles, and unreachable nodes.
+- Shared Iteration 4 preview, confirmation, commit, audit, undo, and redo behavior.
+- Workflow Agent Recipe at `agent-recipes/diagrams/workflow.json`.
+- Iteration 5B group/port visualization, multi-selection, alignment, grid snapping, keyboard movement, and typed layout commands.
+- Iteration 5C group collapse / expand, clipboard-style copy/paste, duplicate selection, and typed edge creation.
+- Iteration 5D typed group movement and batch group membership assignment/removal through shared history.
+- Iteration 5E deterministic group duplication, explicit safe/recursive deletion policies, and keyboard-only port connection flow.
+- Port-aware drag-to-connect interaction and SVG diagram accessibility labels.
+- Lightweight obstacle-aware orthogonal routing for common node-overlap cases.
+- Iteration 5F member-derived group resizing, deterministic multi-obstacle routing channels, visible keyboard focus, and connection-state accessibility descriptions.
+- Viewable HTTP demo at `http://localhost:3000/playground/diagram-editor`.
+
+## Acceptance
+
+- `npm test` and `npm run check` pass.
+- Layout output is deterministic for the same DiagramSpec and bounds.
+- Invalid endpoints, duplicate entity IDs, invalid ports, and illegal group relationships return structured errors.
+- Diagram node resize commits through the shared edit history and can be undone.
+- Demo loads over HTTP and exposes resize, copy/paste, group collapse, typed connection, undo, redo, reset, and normalized state output.
+- Demo exposes multi-select, alignment, snapping, keyboard movement, Group/Port visuals, clipboard state, and collapsed-group state.
+- Copy/paste preserves internal edges and deterministic copied IDs.
+- Collapsed groups hide member nodes from the Scene while keeping normalized Spec state intact.
+- Orthogonal routing avoids common node-body overlaps in deterministic output.
+- Group movement and membership changes commit and restore through shared undo/redo history.
+- Group duplication preserves internal edges; deletion defaults to ungrouping and requires an explicit policy to delete members.
+- Keyboard users can focus ports with Tab, connect with Enter, and cancel with Escape.
+- Group resize scales member geometry and remains undoable without introducing a conflicting persisted group rectangle.
+- Dense orthogonal routes evaluate deterministic horizontal and vertical channels around multiple node obstacles.
+- Workflow, approval process, Agent orchestration, and responsibility mapping recipes are included.
+
+## Local runtime closure
+
+Iteration 5 local runtime scope is complete. The final 2.0 browser matrix passed; physical-device mobile acceptance remains host integration evidence and is not claimed by unit or synthetic interaction tests.

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

@@ -0,0 +1,130 @@
+# Iteration 6 — Project Intelligence and Business Views
+
+## Goal
+
+Add reproducible project analytics that Agents can generate from task and delivery data without unnecessarily expanding the public chart-type surface.
+
+## Chart Type Policy
+
+- Iteration 6 does not add a public chart type by default.
+- Prefer existing primitives and modes: `gantt`, `timeline`, `milestone`, `burndown`, `bar`, `column`, `area`, and `scatter`.
+- Resource load should first be implemented as a Gantt-related project view.
+- Release burndown should be a `burndown` mode.
+- Velocity should use `column` plus a project-data adapter.
+- Cumulative flow should use stacked `area` plus a status-history transform.
+- Risk matrix should use `scatter` plus risk encodings and quadrant guides.
+- Issue aging should use `bar` or `scatter` plus an aging transform.
+- Promote a view to a new public chart type only when it is high-frequency, has semantics that cannot be expressed cleanly through existing Specs, and has independent interaction, accessibility, export, and testing requirements.
+- Candidate foundational chart types such as Radar, Heatmap, and Treemap remain outside Iteration 6 and require separate demand review.
+
+## 6A — Schedule Intelligence
+
+1. Add critical-path and slack/float visualization controls to Gantt.
+2. Add baseline versus actual task bars and deterministic variance calculations.
+3. Add milestone variance indicators.
+4. Expose schedule assumptions, derived fields, and warnings through chart state and Agent inspection APIs.
+5. Add incomplete-date, inverted-range, missing-dependency, and inconsistent completion warnings.
+
+### Checkpoint
+
+- Gantt can toggle critical path, slack, baseline, and actual overlays.
+- The same task input produces the same variance and slack values.
+- Derived values are clearly separated from source fields.
+
+## 6B — Calendar and Dependency Rules
+
+1. Define explicit timezone and working-calendar configuration.
+2. Support working weekdays, holidays, and non-working-day adjustment policies.
+3. Add dependency types and lag/lead values without breaking existing string dependency IDs.
+4. Recalculate critical path and slack using the selected calendar.
+5. Report unsupported or ambiguous calendar inputs instead of silently guessing.
+
+### Checkpoint
+
+- Schedule calculations are reproducible for a declared calendar and timezone.
+- Legacy dependency arrays remain valid.
+- Lag, lead, holidays, and weekends have focused unit coverage.
+
+## 6C — Capacity and Delivery Views
+
+1. Add owner and resource fields to the project-task contract.
+2. Implement resource load and capacity as a project view backed by existing chart primitives.
+3. Implement cumulative flow as stacked Area output from status-history data.
+4. Implement velocity as Column output from completed work by sprint.
+5. Implement release forecasting as a Burndown mode with explicit assumptions.
+
+### Checkpoint
+
+- Capacity overload and missing-capacity conditions produce structured warnings.
+- Cumulative-flow totals reconcile with input status counts.
+- Velocity and release forecasts expose their aggregation window and assumptions.
+
+## 6D — Risk, Aging, and Linked Analysis
+
+1. Implement risk matrix output with Scatter encodings for probability and impact.
+2. Implement issue-aging output with configurable age buckets.
+3. Add filters for owner, status, priority, sprint, and label.
+4. Add framework-neutral linked-selection and linked-filter state across project views.
+5. Preserve stable record IDs across all derived datasets.
+
+### Checkpoint
+
+- Filters update every linked view consistently.
+- Risk and aging calculations are deterministic and inspectable.
+- Selection links source records rather than array positions.
+
+## 6E — Agent and Release Closure
+
+1. Add natural-language intent recipes for schedule, variance, risk, capacity, and release reporting.
+2. Add Agent documentation for data quality, assumptions, confidence, and unsupported inference.
+3. Add TypeScript declarations for project analytics options and results.
+4. Add lifecycle, performance, SVG, Canvas, and normalized JSON regression coverage.
+5. Complete browser acceptance for desktop and mobile viewports.
+6. Record physical-device and host integration checks separately from local runtime acceptance.
+
+## Verification
+
+- `npm run agent:check` and `git diff --check` pass.
+- Baseline, actual, variance, slack, capacity, and forecast calculations are deterministic.
+- Source rows are never mutated by transforms or analytics.
+- Insufficient or contradictory data produces structured warnings.
+- Existing chart types remain backward compatible.
+- SVG and Canvas use equivalent normalized datasets and semantic record references.
+- Linked filters and selections remain stable across rerenders.
+
+## Preview and Acceptance
+
+- Full gallery: `http://127.0.0.1:3000/playground/project-gallery.html`
+- Project intelligence demo: `http://127.0.0.1:3000/playground/project-intelligence.html`
+- Start the local server from the repository root with `python3 -m http.server 3000 --bind 127.0.0.1`.
+- Every completed checkpoint must update at least one HTTP-served demo and include exact manual acceptance steps in the delivery report.
+
+## Deliverables
+
+- Project analytics functions and adapters under `src/`.
+- `playground/project-intelligence.html`.
+- Project analytics recipes under `agent-recipes/`.
+- Agent data-quality and assumption documentation.
+- Updated TypeScript declarations and capability manifests.
+- Iteration 6 browser and runtime acceptance report.
+
+## Completion Definition
+
+Iteration 6 is complete when schedule, capacity, delivery, risk, and aging insights can be generated through stable existing chart primitives; calculations and assumptions are inspectable; linked filters behave consistently; and the runtime, documentation, recipes, tests, and HTTP demos pass acceptance. Any proposed new chart type requires a separate frequency and API review.
+
+## Current Delivery
+
+- `src/project-analytics.mjs` now hosts calendar normalization, dependency normalization, schedule analysis, capacity, velocity, release forecast, risk matrix, and issue aging adapters.
+- `src/project.mjs` consumes schedule and burndown analytics outputs and exposes linked project state, assumptions, warnings, and schedule overlays through runtime state/tooltips.
+- `src/project-linking.mjs` provides framework-neutral linked filters and linked selection based on stable record IDs.
+- `playground/project-intelligence.html` demonstrates schedule overlays, capacity, release, risk, and aging outputs with visible linked-state diagnostics.
+
+## Acceptance Record
+
+- Dependency strings and `{ id, type, lag, lead }` objects share the same Spec, schema, cycle, and missing-reference validation contract.
+- Finish-to-start successors begin on the next working day at zero lag; weekends and holidays continue to use the declared calendar.
+- Calendar calculations are deterministic in `UTC`; unsupported timezone values emit `UNSUPPORTED_TIMEZONE` and fall back to `UTC`.
+- Linked fallback record IDs retain their source index after filtering.
+- Velocity, risk, and issue-aging adapters exclude invalid values and emit structured warnings; issue aging requires an explicit `today` reference.
+- Automated acceptance: `npm run agent:check` and `git diff --check`.
+- Browser acceptance: open `http://127.0.0.1:3000/playground/project-intelligence.html`, confirm all demo cards render and linked-state diagnostics update; then open `http://127.0.0.1:3000/playground/project-gallery.html` and confirm the project charts render without console errors.

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

@@ -0,0 +1,117 @@
+# Iteration 7 — Foundational Chart Coverage
+
+## Goal
+
+Close the highest-frequency foundational chart gaps without creating redundant public chart types. First strengthen reusable composition and transform capabilities, then add `heatmap` and `radar` as independently supported chart types.
+
+## Admission Policy
+
+- Donut remains a `pie` mode configured with `innerRadius`; do not register `donut` as a public type.
+- Stacked and percent-stacked charts remain modes of `bar`, `column`, and `area`.
+- Combo charts use mixed multi-series encodings and optional dual axes; do not register `combo` as a public type.
+- Histograms use a deterministic `bin` transform rendered with `bar` or `column`; do not register `histogram` as a public type.
+- `heatmap` and `radar` become public chart types because they require distinct layout, interaction, accessibility, and rendering semantics.
+- Treemap, box plot, Sankey, waterfall, maps, and 3D remain outside Iteration 7.
+
+## 7A — Composition and Transform Foundations
+
+1. Define normalized stack configuration for `bar`, `column`, and `area`, including grouped, stacked, and percent-stacked modes.
+2. Implement positive and negative stack accumulation with deterministic domains and stable source record references.
+3. Add `pie.innerRadius` with validation, normalized geometry, tooltip behavior, labels, and zero-total handling.
+4. Extend multi-series encodings with explicit per-series mark type so line and column marks can share one coordinate system.
+5. Define combo-axis rules, legend semantics, hit testing, selection, and renderer-equivalent data references.
+6. Add a deterministic `bin` transform with explicit field, thresholds or step, extent, interval closure, and invalid-value warnings.
+7. Ensure transforms never mutate source rows and expose normalized output through inspection and JSON export.
+
+### Checkpoint
+
+- Grouped, stacked, and percent-stacked examples render consistently in SVG and Canvas.
+- Donut output is produced by `type: "pie"` plus `innerRadius`.
+- A column-line combo uses one Spec and preserves per-series tooltip and axis identity.
+- Histogram bins are reproducible and reconcile with the valid numeric input count.
+
+## 7B — Heatmap
+
+1. Register `heatmap` in Spec validation, capabilities, recommendations, recipes, and TypeScript declarations.
+2. Define categorical and temporal x/y matrix encodings plus a quantitative color encoding.
+3. Add continuous and discrete color scales with explicit domain, range, clamp, and missing-value color.
+4. Implement deterministic cell layout, padding, labels, tooltip, hit testing, keyboard navigation, and linked selection.
+5. Preserve empty cells and distinguish missing values from numeric zero.
+6. Support responsive sizing, large-matrix degradation rules, SVG, Canvas, accessibility summaries, and normalized export.
+
+### Checkpoint
+
+- Categorical and calendar-style heatmaps render from the same normalized matrix contract.
+- Missing, zero, minimum, and maximum values have distinguishable semantics.
+- Keyboard navigation identifies row, column, value, and source record.
+
+## 7C — Radar
+
+1. Register `radar` in Spec validation, capabilities, recommendations, recipes, and TypeScript declarations.
+2. Define indicator names, domains, normalization rules, axis order, and multi-series data shape.
+3. Implement polygon grid, radial axes, labels, series lines, points, and optional area fill.
+4. Add explicit handling for mixed units, missing indicators, negative domains, and constant-value domains.
+5. Add tooltip, legend selection, keyboard traversal, responsive label collision handling, and semantic summaries.
+6. Maintain SVG/Canvas parity and stable source record references in normalized JSON export.
+
+### Checkpoint
+
+- Single-series and multi-series radar charts use declared indicator domains reproducibly.
+- Mixed-unit inputs warn unless explicit per-indicator domains are provided.
+- Labels remain readable at desktop and mobile widths.
+
+## 7D — Agent, Gallery, and Release Closure
+
+1. Update the public capability manifest, API reference, chart-selection guidance, and schema examples.
+2. Add Agent recipes for composition comparison, distribution analysis, matrix analysis, and multidimensional comparison.
+3. Add focused unit tests for normalization, geometry, invalid data, source immutability, and stable record IDs.
+4. Add SVG/Canvas semantic parity, lifecycle, accessibility, responsive, and performance regression coverage.
+5. Add a dedicated foundational chart gallery and synchronize the full Gallery count and filters.
+6. Complete desktop and mobile browser acceptance and record deferred physical-device checks separately.
+
+## Verification
+
+- `npm run agent:check` and `git diff --check` pass.
+- Existing Specs remain backward compatible and unchanged defaults preserve current rendering.
+- No new public type is introduced for Donut, Combo, Stacked, or Histogram.
+- Stack totals, percent totals, pie radii, and bin boundaries are deterministic.
+- Heatmap and Radar provide equivalent semantic references in SVG and Canvas.
+- Missing, invalid, ambiguous, and mixed-unit data produce structured warnings rather than silent guesses.
+- Gallery examples remain usable at desktop and mobile viewport widths.
+
+## Preview and Acceptance
+
+- Full gallery: `http://localhost:3000/playground/project-gallery.html`
+- Iteration 7 gallery: `http://localhost:3000/playground/foundational-gallery.html`
+- Start the server from the repository root with `python3 -m http.server 3000 --bind 127.0.0.1`.
+- 7A acceptance must show grouped/stacked/percent charts, Donut, Combo, and Histogram examples.
+- 7B acceptance must show categorical and calendar heatmaps, missing values, tooltips, and keyboard focus.
+- 7C acceptance must show single/multi-series Radar, explicit indicator domains, and mobile label behavior.
+- Every phase delivery report must include its exact preview URL and manual acceptance steps.
+
+## Deliverables
+
+- Stack, mixed-mark series, pie radius, and bin-transform contracts under `src/`.
+- Public `heatmap` and `radar` chart implementations.
+- Updated capability manifests, TypeScript declarations, documentation, and Agent recipes.
+- `playground/foundational-gallery.html` plus synchronized full Gallery coverage.
+- Iteration 7 automated and browser acceptance record.
+
+## Completion Definition
+
+Iteration 7 is complete when stacked charts, Donut, Combo, and Histogram workflows are stable reusable capabilities; Heatmap and Radar are fully supported public chart types; SVG, Canvas, interactions, accessibility, export, recipes, tests, and HTTP demos pass acceptance; and no redundant chart type has been added.
+
+## Current Delivery
+
+- 7A provides stacked and percent-stacked Bar/Column geometry, Donut through `pie.innerRadius`, mixed line-column series, and deterministic bin transforms.
+- 7B registers Heatmap with matrix encodings, continuous colors, explicit missing-value color, stable record references, SVG/Canvas rendering, and keyboard traversal through shared interactive Scene nodes.
+- 7C registers Radar with explicit indicators, polygon grids, multi-series rendering, stable record references, and warnings for ambiguous domains or invalid values.
+- 7D updates capabilities, declarations, recipes, documentation, automated coverage, the full Gallery, and `playground/foundational-gallery.html`.
+
+## Acceptance Record
+
+- `npm run agent:check`: pass, 16 chart types and 42 automated tests.
+- `git diff --check`: pass.
+- Desktop browser, isolated local server: `playground/foundational-gallery.html` renders 8/8 cards with 5 SVG and 3 Canvas charts; no console warnings or errors.
+- Desktop browser, isolated local server: `playground/project-gallery.html` renders 16/16 chart types with 10 SVG and 6 Canvas charts; no console warnings or errors.
+- The browser viewport override was requested at 390 x 844, but the connected browser continued reporting a fixed 1280-pixel viewport. Responsive CSS and chart initialization passed, while true mobile viewport and physical-device acceptance remain a release-environment check.

package/docs/agent/development/iteration-8-acceptance.md

@@ -0,0 +1,68 @@
+# Iteration 8 Acceptance Record
+
+Date: 2026-09-16
+
+## Result
+
+Iteration 8A–8D is implemented and accepted for the repository runtime, public Agent contracts, maintained Playground pages, responsive browser viewport, lifecycle checks, and repeatable performance fixtures. Chromium, Firefox 144, WebKit 26, and native Safari 26.6.2 checks pass. Physical iOS/Android checks remain a separately recorded host/device follow-up.
+
+## Automated Evidence
+
+- `npm run agent:check`: passed.
+- `git diff --check`: passed.
+- Core tests: 51 passed, 0 failed.
+- Agent documentation check: 16 charts, 24 commands, and 7 schemas.
+- Syntax check: every `src/*.mjs` file passed `node --check`.
+- Node.js 18.20.8, 20.20.2, and 22.22.2: Agent checks and the executable Agent workflow passed.
+- Package-consumer coverage: public ESM imports, capability discovery, planning, validation, explanation, chart creation, lifecycle, and active Playground entry files are covered by the core suite.
+
+## Browser Evidence
+
+- Environments: Codex in-app Chromium, Playwright Firefox 144, and Playwright WebKit 26 against `npm run playground` on `127.0.0.1:3000`.
+- Full Gallery: all 16 public chart types rendered; 0 error cards and no uncaught page errors.
+- Renderer switch: all Gallery cases rendered with SVG when forced; default mixed SVG/Canvas cases also passed.
+- Responsive checks: desktop and a true 390 x 844 viewport completed without body overflow.
+- Agent Workbench: `id` remained a stable identifier, `month` was selected as the dimension, validation passed, record IDs were preserved, and the expected missing-value warning remained visible.
+- Interaction Lab: zoom in, zoom out to the full window, pan, reset, selection clearing, keyboard behavior, and Canvas switching passed.
+- Accessibility Lab: Line, Pie, Heatmap, Radar, Gantt, and Flow exposed role, accessible label, focusability, and family-specific semantic output.
+- Regression pages: Foundational Gallery, Project Intelligence, Business Editing, and Diagram Editor loaded with ready states and no uncaught page errors.
+- Lifecycle fixture: 25 create/destroy cycles left 0 chart children and 0 tooltips.
+- Firefox/WebKit matrix: 22/22 desktop and 390 x 844 touch-viewport page scenarios passed after fixing Project Intelligence grid shrink behavior and redundant ResizeObserver rendering.
+- Native Safari 26.6.2: 11/11 desktop and 390 x 844 page scenarios passed without horizontal overflow.
+
+## Performance Sample
+
+These are local acceptance samples, not universal device budgets.
+
+| Scenario | Renderer | Create | Resize | JSON export |
+| --- | --- | ---: | ---: | ---: |
+| Line, 100 rows | Canvas | 1.7 ms | 0.6 ms | 0.1 ms |
+| Line, 1,000 rows | Canvas | 6.3 ms | 4.9 ms | 0.3 ms |
+| Line, 5,000 rows, Firefox | Canvas | 110 ms | 96 ms | 3 ms |
+| Line, 5,000 rows, WebKit | Canvas | 81 ms | 75 ms | 2 ms |
+| Heatmap, 5,000 rows, Firefox | Canvas | 19 ms | 15 ms | 2 ms |
+| Heatmap, 5,000 rows, WebKit | Canvas | 15 ms | 10 ms | 2 ms |
+
+The Performance Lab also includes repeatable 5,000-row Line, Heatmap, Gantt, and Diagram scenarios for release-host measurements.
+
+## Preview
+
+Start the no-cache static server from the repository root:
+
+```bash
+npm run playground
+```
+
+- Home: `http://localhost:3000/playground/index.html`
+- Full Gallery: `http://localhost:3000/playground/project-gallery.html`
+- Agent Workbench: `http://localhost:3000/playground/agent-workbench.html`
+- 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`
+
+## Post-release Host/Device Follow-up
+
+- Physical-device touch acceptance on iOS and Android.
+- Release-host performance budgets across representative low-end and high-end devices.
+
+These checks remain important integration evidence, but the three-engine browser matrix, native Safari run, responsive touch viewport, and deterministic local performance fixtures are sufficient for the 2.0 source release.