ggaction 0.0.13 → 0.0.16

package/CHANGELOG.md

@@ -4,6 +4,152 @@ All notable changes to `ggaction` are recorded in this file.
 
 ## Unreleased
 
+## [0.0.16] - 2026-09-14
+
+### Added
+
+- Added `reviseData` for immutable original-data revisions that update dependent
+  transforms, chart owners, scales, guides, labels, selections, and retained facets.
+- Added `applyTextMetrics` and `removeTextMetrics` for host-measured text layout
+  with immutable exact-font profiles, deterministic fallback, composition
+  propagation, and wrapped typography rematerialization.
+- Added browser-safe `ggaction/persistence` with versioned editable-program and
+  graphic-only snapshots, tagged value preservation, and strict restoration.
+- Added browser-safe `ggaction/accessibility` with immutable final visual data,
+  component roles, aggregate/bin/interval values, series, and composition hierarchy.
+- Added `ggaction/diagnostics` to read structured error codes and resource details
+  while preserving the original Error, TypeError, or RangeError identity.
+- Added `renderToPNGBuffer` and `renderToPDFBuffer` for Node memory output.
+  PNG encoding is asynchronous; Canvas drawing remains synchronous.
+- Added `release:prepare` for reviewable version, changelog, release-contract,
+  provenance, and generated-documentation updates without publishing side effects.
+- Added reproducible runtime benchmarks, exhaustive direct-action negative-input
+  contracts, semantic authoring evaluations, and cross-platform/browser checks.
+
+### Changed
+
+- **Installation:** Node rendering and MCP dependencies are now optional peers.
+  Canvas/SVG users can install only `ggaction`. Node PNG/PDF users must also install
+  `@napi-rs/canvas`; MCP users must also install `@modelcontextprotocol/sdk`.
+  Missing backends report the required install command and never auto-install.
+- MCP task packets now use schema version 5. Required options are separate from
+  example/configured options, exact calls preserve explicit user choices, and
+  unresolved request fragments remain visible. Consumers must check packet versions.
+- Reused owned immutable subtrees, avoided unrelated theme traversal, shared
+  persistent trace tails, and cached immutable SVG resource hashes. Mutable
+  renderer inputs still recompute their hashes.
+- Reduced Basic browser bundle size through built-in factory tree shaking and
+  shared validation/materialization code. Existing browser gzip limits remain.
+- Release verification now distributes one canonical candidate artifact across
+  independent source, coverage, package, documentation, platform, browser, and
+  weighted realistic-test jobs, then requires a strict successful aggregate.
+- Added a strict realistic-test aggregate check and bounded failure evidence for
+  test logs, render differences, and browser screenshots. Verification errors
+  retain their original failing status.
+- Consolidated architecture prose around ownership and state flow, with exact
+  action behavior linked to current contracts and shared metadata owners.
+
+### Fixed
+
+- Rejected callable, mutable class-instance, cyclic, and sparse source inputs
+  before they could escape immutable ownership or fail during materialization.
+  TypeScript source-row declarations now match the runtime data boundary.
+- Rejected unknown options consistently in extension primitives and renderers,
+  including PNG, and validated axis coordinate/channel assertions before changes.
+- Corrected padding units for focused scale editors using one canonical registry.
+- Corrected MCP required-option inference, explicit style/scale choices, derived
+  owner references, and false-completion reporting for partially understood tasks.
+- Preserved nested facet trace closure and prototype-named keys during snapshot
+  round trips, and distinguished live dependencies from reserved optional IDs.
+- Distinguished data and mark identity when revising statistical-reference inputs.
+  Inferred grids now follow explicit tick changes without disrupting orientation
+  changes that must rematerialize guides in dependency order.
+- Applied the same interval-statistics merge during simultaneous role edits,
+  clearing inherited confidence-interval parameters when changing extent.
+- Reused the exact release artifact in installed-package consumers instead of
+  silently repacking it, and made development npm/TypeScript invocation portable
+  across supported operating systems.
+- Bounded long CSV description memory in realistic test fixtures and synchronized
+  their direct action coverage and coordinate options with current contracts.
+
+## [0.0.15] - 2026-09-14
+
+### Added
+
+- Added independent field-driven stroke color for Point, Line, Area, Bar, Rect,
+  Arc, Rule, and Tick marks, including categorical and continuous scales,
+  focused scale editing, legends, selections, facets, and renderer parity.
+- Added logarithmic, square-root, power, quantize, quantile, and threshold
+  point-size scales with equal-area geometry, focused scale editing, complete
+  interval legends, source replay, strict types, and installed-package support.
+
+- Added normalization and missing-data workflows with `createNormalizedData`,
+  `createCompleteData`, and `createImputedData`. Computed expressions now support
+  typed scalar/null results, comparisons, conditions, and short-circuit logic;
+  calendar buckets and windows have explicit time and ordering policies.
+- Added immutable derived revision editing: `editDerivedData`, `editComputedData`,
+  `editFilteredData`, `editFoldData`, `editSummaryData`, `editBinData`,
+  `editTimeUnitData`, `editWindowData`, `editDensityData`, `editStackData`,
+  `editRegressionData`, `editIntervalData`, `editECDFData`, `editNormalizedData`,
+  `editCompleteData`, and `editImputedData`. An existing descendant rejects an
+  edit by default; `dependents: "recompute"` rebuilds the full affected closure.
+- Added focused scale editing with `editXScale`, `editYScale`, `editThetaScale`,
+  `editRScale`, `editColorScale`, `editStrokeScale`, `editSizeScale`,
+  `editOpacityScale`, `editShapeScale`, `editStrokeWidthScale`,
+  `editStrokeDashScale`, `editXOffsetScale`, `editYOffsetScale`, and
+  `editParallelScale`. These select the channel owner and replay its consumers.
+- Added `encodeChannels` for atomic multi-channel reassignment; `editCoordinate`
+  for Cartesian aspect and Polar frame changes; and `editLegendBlock` for one
+  identified block of a composite legend.
+- Added `editMarkLabelSelection`, `editMarkLabelPlacement`, and `removeMarkLabels`.
+  Label selection now works on final aggregated items; semantic placement follows
+  directed boundaries through source, scale, and layout changes.
+- Added explicit safe removal with `removeData`, `removeScale`, and
+  `removeCoordinate`. A live dependency produces an ownership-path error; remove
+  or rebind consumers before removing the resource.
+- Added weighted summaries, bins, histogram/KDE authoring and revisions; dynamic
+  statistical reference lines/bands; exact sampled legend values; typed display
+  label maps; facet-header role/side/alignment controls; custom theme tokens;
+  detailed stroke styles, rounded rectangles, and expanded Polar/Parallel facets.
+
+### Changed
+
+- Clarified the action/program grammar, relative action hierarchy, and
+  decision-level atomicity. Catalog role tags are distinguished from action
+  delegation and package exposure.
+- Resource removal actions now record their semantic deletions as `editSemantic`
+  children. The full extension primitive accepts whole unused source datasets
+  and coordinates while retaining dependency guards and immutable snapshots.
+- Point-size ranges represent area across continuous and discrete families.
+  Entering a discrete size family requires a destination domain and range;
+  repeated field assignments preserve compatible scale settings.
+- Axis, legend, and facet display labels preserve raw category identity. Mapping
+  `"KR"` to `"South Korea"` changes visible text while grouping, selection, and
+  domain lookup still use `"KR"`. Numeric and UTC formats must match field type.
+- Custom themes supply defaults while explicit mark styles retain precedence.
+  Removing a theme restores baseline defaults and retains explicit overrides.
+- Complete guides can be created progressively without duplicating existing
+  compatible components. Polar/Parallel repetition retains source recipes and
+  rejects unsupported role substitutions explicitly.
+- Documentation now distinguishes released API snapshots from later development,
+  provides an exact address and declaration for every action, and executes every
+  maintained tutorial and recipe against the packaged module. See
+  [migration notes](https://ggaction.github.io/ggaction/version/#migration-from-v0013).
+
+### Fixed
+
+- Prevented typing immediately after a failed search-index prefetch from sending
+  an implicit retry. Each explicit retry now sends one request even when the
+  first failure arrives before the input event.
+- Corrected the README's canvas margins for its complete 406-row example and
+  documented regression defaults beside the example. The hierarchy tutorial now
+  refines its high-level chart and demonstrates a subsequent style revision.
+- Corrected default dumbbell axis titles, direct Rose radius refinement, and stale
+  current-guide pointers after removal.
+- Corrected executable examples, API defaults and compatibility descriptions,
+  missing gallery/tutorial entries, exact-action search, initial ArrowUp selection,
+  filter/TOC synchronization, search retries, and narrow-screen type references.
+
 ## [0.0.13] - 2026-09-07
 
 ### Added

package/README.md

@@ -16,15 +16,14 @@ Every frame is rendered from an immutable `ChartProgram`. The final R² label is
 
 ## A grammar of graphical action
 
-Actions are verbs:
+An action expresses a design operation on a chart element. In
+`editLineMark({ strokeWidth: 4 })`, `edit` is the operation, `LineMark` names
+the target concept, and the option supplies the design choice.
 
-`create · transform · encode · edit · select · compose`
-
-Chart resources are nouns:
-
-`data · marks · scales · coordinates · guides`
-
-A `ChartProgram` is the immutable sentence they produce.
+The grammar has two units: **graphical actions** and **chart programs**.
+A program composes action calls in authoring order and retains their resulting
+immutable state. Authors read a linear sequence of decisions; an action may
+delegate to smaller actions recorded in its nested execution trace.
 
 The following fragment assumes `cars` is an array of row objects:
 
@@ -32,7 +31,11 @@ The following fragment assumes `cars` is an array of row objects:
 import { chart } from "ggaction";
 
 const program = chart()
-  .createCanvas()
+  .createCanvas({
+    width: 760,
+    height: 480,
+    margin: { top: 40, right: 190, bottom: 70, left: 80 }
+  })
   .createData({ values: cars })
   .createScatterPlot({
     id: "points",
@@ -45,6 +48,12 @@ const program = chart()
   .createGuides();
 ```
 
+Here `createRegression()` infers groups from the point layer, uses a linear
+model, and includes a 95% mean-response interval band. The right margin reserves
+space for the resulting legend. The [regression recipe](https://ggaction.github.io/ggaction/recipes/regression-scatterplot/)
+provides data and rendering setup; [regression options](https://ggaction.github.io/ggaction/api/regression/)
+control grouping, model, interval, and whether a band is drawn.
+
 ## Why actions?
 
 - **Progressive** — build and revise a chart one meaningful operation at a time.
@@ -80,6 +89,10 @@ Install the current public release:
 npm install ggaction
 ```
 
+For Node PNG/PDF output, also install `@napi-rs/canvas`. For the MCP server,
+also install `@modelcontextprotocol/sdk`. These are optional peer dependencies;
+browser Canvas/SVG users do not need either package.
+
 Add the Canvas element that the rendering code targets. Its accessible name and
 fallback text summarize the chart for contexts where Canvas pixels are not
 available:
@@ -157,7 +170,7 @@ automatic undo stack; the application chooses which to retain or render.
 
 Use `createLinePlot`, `createBarPlot`, `createHistogram`, and `createHeatmap` for
 the other basic Cartesian charts. The `ggaction/basic` entry keeps this common
-creation path at or below the current 153,000-byte gzip regression ceiling while
+creation path at or below the current 175,000-byte gzip regression ceiling while
 each facade still records its mark, encoding, and guide actions as trace
 children. Import from
 `ggaction` when you need editing, selection, composition, alternative
@@ -202,11 +215,14 @@ The package is ESM-only and requires Node.js 20 or later.
 | `ggaction/extension` | Author and register wrapped actions with public low-level primitives |
 | `ggaction/png` | Render a completed program to a PNG file in Node.js |
 | `ggaction/pdf` | Render a completed program to a single-page vector PDF file in Node.js |
+| `ggaction/persistence` | Save and restore editable programs or graphic snapshots in Browser or Node |
+| `ggaction/accessibility` | Export final visual data for host-provided accessible tables and descriptions |
+| `ggaction/diagnostics` | Read structured error codes and resource details in Browser or Node |
 | `ggaction/svg` | Serialize a completed program to browser-safe SVG |
 | `ggaction-mcp` | Run the local read-only MCP authoring server over stdio in Node.js |
 
 All module entries include TypeScript declarations. The default, basic,
-extension, and SVG entries are browser-safe; the PNG and PDF adapters are
+extension, diagnostics, accessibility, and SVG entries are browser-safe; the PNG and PDF adapters are
 Node-only.
 
 The installed package also includes the Node-only `ggaction-mcp` executable. It
@@ -231,7 +247,7 @@ the extra discussion required before public API or architecture changes.
 
 ## Status and development
 
-> **Status:** `0.0.13` is the current experimental public release. APIs may change before `1.0.0`; changes are recorded in the [changelog](./CHANGELOG.md).
+> **Status:** `0.0.16` is the current experimental public release. APIs may change before `1.0.0`; changes are recorded in the [changelog](./CHANGELOG.md).
 
 ```bash
 npm install
@@ -244,3 +260,16 @@ npm run test:docs
 ## Related Links
 
 - Action-trace demo: [Link](https://ggactionbot.github.io/action-trace-demo/)
+
+### Prepare a release
+
+Record changes under `Unreleased` in `CHANGELOG.md` and commit the reviewed work.
+Run `npm run release:prepare -- 0.0.16 --dry-run` to preview version updates.
+Omit `--dry-run` to update versions, promote notes, and generate the release
+contract, documentation, and local notes. Review the Git diff. After committing
+runtime changes, rerun the command to refresh source provenance; existing notes
+and their date are preserved.
+
+Preparation does not commit, push, tag, publish, or deploy. Integration and required
+PR checks precede an annotated tag. The protected workflow verifies and publishes
+one candidate from that tag. Generation failures leave an unfinished diff to review.