ggaction 0.0.22 → 0.0.24

package/CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to `ggaction` are recorded in this file.
 
 ## Unreleased
 
+## [0.0.24] - 2026-10-24
+
+- Add independent `subtitleLineHeight` to title creation and editing, preserving shared spacing and omitted defaults through layout replay and saved programs.
+
+- Infer quantitative typing for numeric constant Rule secondary endpoints when `fieldType` is omitted, matching the existing declaration while retaining field-based endpoint validation.
+
+- Fix Canvas replay and complete-axis frame edits comparing new axis labels with a stale numeric sibling title position.
+- Preserve strict nested tick/label validation and numeric-map errors in complete-axis edits before replay planning.
+
+- Add Cartesian axis title `offset: { from: "labels", gap }` with same-owner label-aware replay, preserving numeric and omitted defaults.
+
+- Add explicit `assignment: "step"` for rectangular 2D bins and binned heatmaps, preserving the default strict edge policy and immutable replay.
+
+- Add independent horizontal/vertical facet gaps with closed `{ x, y }` input, immutable replay and unchanged numeric/concat spacing.
+- Preserve a facet parent title when revising its source data without introducing titles in child charts.
+
+- Add optional Cartesian label `flushThreshold` to align only mapped ticks near range edges, preserving full-containment defaults and editable replay.
+
+## [0.0.23] - 2026-10-23
+
+- Add independent full-content facet packing, view-aware headers and per-channel Cartesian axis policies with unclipped shared footer axes.
+- Avoid false title/legend collisions from floating-point roundoff at touching edges.
+
+- Add opt-in `placement: "plot-last"` for regression fits and bands, preserving source attachment by default and retaining placement through edits and restoration.
+
+- Add explicit `monotone-steffen` interpolation for lines, areas and interval boundaries while preserving existing monotone output.
+
+- Preserve null or absent calendar inputs as null buckets with opt-in `missing: "null"`, including immutable edits and saved programs.
+- Preserve locally moved legend title alignment and reserve four-edge facet parent title lanes.
+- Strengthen test oracles, execution receipts, consumer qualification, source coverage, browser evidence and bounded CI runners.
+
+- Correct documentation examples, recovery ordering, conditional defaults, data-refresh guidance, and action-card prerequisites; execute additional examples and pin contextual exceptions.
+- Publish the complete declaration dependency graph, all runtime entry references, and selective LLM page/action/type artifacts with shared identity and hashes.
+- Improve task search, navigation affordances, source editing links, and first-run documentation; replace the README animation with the paper's Nightingale rose sequence.
+
 ## [0.0.22] - 2026-10-23
 
 - Add opt-in plot clipping to supported Cartesian mark layers, with native/SVG/PNG/PDF parity and immutable owner replay.

package/README.md

@@ -9,77 +9,10 @@ Most visualization grammars describe a finished chart. **ggaction** represents c
 Build, inspect, select, and revise charts one meaningful action at a time.
 
 <p align="left">
-  <img src="./docs/assets/images/readme-authoring-sequence.gif" width="960" height="540" loading="eager" alt="A ggaction program progressively creates a scatterplot, adds grouped regression fits and confidence bands, highlights the Japan group across chart layers, and finishes with an R-squared annotation.">
+  <img src="./docs/assets/images/readme-authoring-sequence.gif" width="960" height="540" loading="eager" alt="The paper Nightingale rose plot is built progressively, then its radial mapping, cause colors, sector spacing, title, and palette are revised.">
 </p>
 
-Every frame is rendered from an immutable `ChartProgram`. The final R² label is a traceable action built from public extension primitives.
-
-## A grammar of graphical action
-
-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.
-
-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:
-
-```javascript
-import { chart } from "ggaction";
-
-const program = chart()
-  .createCanvas({
-    width: 760,
-    height: 480,
-    margin: { top: 40, right: 190, bottom: 70, left: 80 }
-  })
-  .createData({ values: cars })
-  .createScatterPlot({
-    id: "points",
-    x: "Displacement",
-    y: "Acceleration",
-    color: "Origin",
-    guides: false
-  })
-  .createRegression()
-  .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.
-- **Traceable** — retain high-level actions and the wrapped actions they invoke.
-- **Materialized** — actions create concrete backend-neutral graphics; rendering does not perform hidden semantic compilation.
-
-## MCP server for LLM
-
-ggaction includes a local, read-only MCP server that gives coding assistants
-current action names, syntax-valid call templates, explicit placeholders, and
-task-specific authoring steps
-without loading the complete documentation.
-
-<p align="left">
-  <img src="./docs/assets/images/readme-mcp-benefits.svg" width="960" loading="lazy" alt="Across 576 fixed task runs, MCP with bounded fallback improved strict success and reduced tokens and model calls compared with public-documentation browsing for Terra, Luna, and Nano.">
-</p>
-
-Across a fixed 576-run evaluation, MCP-first authoring with bounded fallback
-improved strict task success while using fewer tokens and model calls for all
-three model sizes. The server runs locally over stdio and does not execute chart
-code, access arbitrary files, make network requests, require an account, or
-collect telemetry.
-
-[Set up the local MCP server](https://ggaction.github.io/ggaction/mcp/) ·
-[Inspect the benchmark record](./benchmarks/llm-authoring-v1/) ·
-[Read the complete evaluation report](./agent_docs/impl/roadmap5.4/phase6/ATTEMPT11.md)
+Every frame is rendered from an immutable `ChartProgram`. This is the paper’s Nightingale rose-plot authoring sequence: create the chart, encode mortality and cause, adjust sector spacing, add the title, and change the palette.
 
 ## Quick start
 
@@ -170,28 +103,86 @@ 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 231,000-byte gzip regression ceiling while
+creation path at or below the current 233,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
 coordinates, or statistical layers. See the
 [Basic Charts API](https://ggaction.github.io/ggaction/api/basic-charts/).
 
-Use `createParallelCoordinates({ dimensions })` to connect each source row
-across ordered, dimension-local scales and axes. See the
-[Parallel Coordinates API](https://ggaction.github.io/ggaction/api/parallel-coordinates/)
-or the [runnable Cars example](./examples/cars-parallel-coordinates/).
-
-For an advanced layered example, follow the [regression recipe](https://ggaction.github.io/ggaction/recipes/regression-scatterplot/)
-or open the [runnable regression example](./examples/cars-regression-scatterplot/).
-To compare category distributions with density-filled strips, read the
-[gradient-plot guide](https://ggaction.github.io/ggaction/api/gradient-plots/)
-or open the [runnable example](./examples/cars-gradient-plot/).
-For symmetric or split density shapes centered on categories, use the
-[violin-plot API](https://ggaction.github.io/ggaction/api/violin-plots/) or the
-[runnable Cars example](./examples/cars-acceleration-violins/).
-For compact signed time-series bands, use `encodeHorizon` on an area mark and
-open the [runnable Gapminder example](./examples/gapminder-horizon/).
+Explore [parallel coordinates](https://ggaction.github.io/ggaction/api/parallel-coordinates/),
+[gradient plots](https://ggaction.github.io/ggaction/api/gradient-plots/),
+[violin plots](https://ggaction.github.io/ggaction/api/violin-plots/), and
+[Horizon charts](./examples/gapminder-horizon/) in the [runnable examples](./examples/README.md).
+
+## A grammar of graphical action
+
+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.
+
+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:
+
+```javascript
+import { chart } from "ggaction";
+
+const program = chart()
+  .createCanvas({
+    width: 760,
+    height: 480,
+    margin: { top: 40, right: 190, bottom: 70, left: 80 }
+  })
+  .createData({ values: cars })
+  .createScatterPlot({
+    id: "points",
+    x: "Displacement",
+    y: "Acceleration",
+    color: "Origin",
+    guides: false
+  })
+  .createRegression()
+  .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 ([source](./examples/cars-regression-scatterplot/)); [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.
+- **Traceable** — retain high-level actions and the wrapped actions they invoke.
+- **Materialized** — actions create concrete backend-neutral graphics; rendering does not perform hidden semantic compilation.
+
+## MCP server for LLM
+
+ggaction includes a local, read-only MCP server that gives coding assistants
+current action names, syntax-valid call templates, explicit placeholders, and
+task-specific authoring steps
+without loading the complete documentation.
+
+<p align="left">
+  <img src="./docs/assets/images/readme-mcp-benefits.svg" width="960" loading="lazy" alt="Across 576 fixed task runs, MCP with bounded fallback improved strict success and reduced tokens and model calls compared with public-documentation browsing for Terra, Luna, and Nano.">
+</p>
+
+In the fixed 576-run evaluation completed on 2026-08-10 (24 tasks × 2 repetitions ×
+`gpt-5.6-terra`, `gpt-5.6-luna`, and `gpt-5.4-nano` × 4 conditions;
+product candidate `4e211ba418cd437d7c66c4fb986fcc714cf579ea`), MCP-first authoring with bounded fallback
+improved strict task success while using fewer tokens and model calls for all
+three model sizes. The server runs locally over stdio and does not execute chart
+code, access arbitrary files, make network requests, require an account, or
+collect telemetry.
+
+[Set up the local MCP server](https://ggaction.github.io/ggaction/mcp/) ·
+[Inspect the benchmark record](./benchmarks/llm-authoring-v1/) ·
+[Read the complete evaluation report](./agent_docs/impl/roadmap5.4/phase6/ATTEMPT11.md)
 
 ## What it supports
 
@@ -227,9 +218,6 @@ All module entries include TypeScript declarations. The default, basic,
 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
-provides one local, read-only chart-authoring search tool and stays outside every
-browser entry. See the [local MCP guide](https://ggaction.github.io/ggaction/mcp/).
 
 ## Documentation
 
@@ -249,7 +237,7 @@ the extra discussion required before public API or architecture changes.
 
 ## Status and development
 
-> **Status:** `0.0.22` is the current experimental public release. APIs may change before `1.0.0`; changes are recorded in the [changelog](./CHANGELOG.md).
+> **Status:** `0.0.24` is the current experimental public release. APIs may change before `1.0.0`; changes are recorded in the [changelog](./CHANGELOG.md).
 
 ```bash
 npm install
@@ -263,6 +251,9 @@ The renderer development suite also needs Poppler's `pdftoppm` on `PATH` for
 independent PDF pixel checks. The CI and protected release jobs install
 `poppler-utils` explicitly; this is not a runtime package dependency.
 
+
+For extension authors, the installed package includes `node_modules/ggaction/knowledge/extension-authoring.md`. Read that file alongside the installed declarations; it is a guide file, not an importable package entry.
+
 ## Related Links
 
 - Action-trace demo: [Link](https://ggactionbot.github.io/action-trace-demo/)
@@ -270,7 +261,8 @@ independent PDF pixel checks. The CI and protected release jobs install
 ### 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.
+Set `NEXT_VERSION` to the agreed next release version (at least the current package version).
+Run `npm run release:prepare -- "$NEXT_VERSION" --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

package/knowledge/action-card.schema.json

@@ -1 +1 @@
-{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://ggaction.github.io/ggaction/schemas/action-card.schema.json","title":"ggaction compact action card","type":"object","additionalProperties":false,"required":["schemaVersion","name","layer","domain","summary","signature","intents","lifecycle","resources","authoringRoles","wraps","editableVia","supports","units","inference","completionRequirements","options","callPatterns","snippet","errors","route"],"properties":{"schemaVersion":{"const":3},"name":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9]*$"},"layer":{"enum":["user-facing","advanced","primitive"]},"domain":{"type":"string","minLength":1},"summary":{"type":"string","minLength":20,"maxLength":420},"signature":{"type":"string","minLength":10},"intents":{"type":"array","minItems":3,"maxItems":7,"uniqueItems":true,"items":{"type":"string","minLength":2,"maxLength":80}},"lifecycle":{"type":"string","minLength":3},"resources":{"type":"object","additionalProperties":false,"required":["prerequisites","owns","idOptions"],"properties":{"prerequisites":{"type":"array","maxItems":4,"uniqueItems":true,"items":{"type":"string","minLength":2,"maxLength":100}},"owns":{"type":"array","maxItems":3,"uniqueItems":true,"items":{"type":"string","minLength":2,"maxLength":80}},"idOptions":{"type":"array","maxItems":10,"uniqueItems":true,"items":{"type":"string","minLength":2,"maxLength":30}}}},"authoringRoles":{"type":"array","minItems":1,"maxItems":5,"uniqueItems":true,"items":{"enum":["H0","H1","H2","H3","H4"]}},"wraps":{"type":"array","maxItems":20,"uniqueItems":true,"items":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9]*$"}},"editableVia":{"type":"array","maxItems":20,"uniqueItems":true,"items":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9]*$"}},"supports":{"type":"object","additionalProperties":false,"required":["entryPoints"],"properties":{"entryPoints":{"type":"array","minItems":1,"maxItems":2,"uniqueItems":true,"items":{"enum":["default","basic"]}}}},"units":{"type":"array","maxItems":16,"items":{"type":"object","additionalProperties":false,"required":["path","unit"],"properties":{"path":{"type":"string","minLength":1,"maxLength":80},"unit":{"enum":["logical-pixel","degree","angle","ratio","probability","count","calendar-unit","temporal-input","data-value","band-fraction"]}}}},"inference":{"type":"array","maxItems":20,"items":{"type":"object","additionalProperties":false,"required":["input","strategy"],"properties":{"input":{"type":"string","minLength":1,"maxLength":80},"strategy":{"enum":["explicit","explicit-or-current","explicit-current-unique-or-error","documented-auto","documented-default"]}}}},"completionRequirements":{"type":"object","additionalProperties":false,"required":["state","requires","allowsEmpty"],"properties":{"state":{"enum":["complete","deferred","contextual","not-applicable"]},"requires":{"type":"array","maxItems":4,"uniqueItems":true,"items":{"type":"string","minLength":2,"maxLength":100}},"allowsEmpty":{"type":"boolean"}}},"options":{"type":"array","maxItems":40,"items":{"type":"object","additionalProperties":false,"required":["name","required","type"],"properties":{"name":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9]*$"},"required":{"type":"boolean"},"type":{"type":"string","minLength":1,"maxLength":500}}}},"callPatterns":{"type":"array","minItems":1,"maxItems":3,"uniqueItems":true,"items":{"type":"string","minLength":3,"maxLength":260}},"snippet":{"type":"string","minLength":3,"maxLength":700},"errors":{"type":"array","maxItems":2,"items":{"type":"object","additionalProperties":false,"required":["error","fix"],"properties":{"error":{"type":"string","minLength":5,"maxLength":220},"fix":{"type":"string","minLength":5,"maxLength":220}}}},"route":{"type":"string","pattern":"^/reference/"}}}
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://ggaction.github.io/ggaction/schemas/action-card.schema.json","title":"ggaction compact action card","type":"object","additionalProperties":false,"required":["schemaVersion","name","layer","domain","summary","signature","intents","lifecycle","resources","authoringRoles","wraps","editableVia","supports","units","inference","completionRequirements","options","callPatterns","snippet","errors","route"],"properties":{"schemaVersion":{"const":3},"name":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9]*$"},"layer":{"enum":["user-facing","advanced","primitive"]},"domain":{"type":"string","minLength":1},"summary":{"type":"string","minLength":20,"maxLength":420},"signature":{"type":"string","minLength":10},"intents":{"type":"array","minItems":3,"maxItems":7,"uniqueItems":true,"items":{"type":"string","minLength":2,"maxLength":80}},"lifecycle":{"type":"string","minLength":3},"resources":{"type":"object","additionalProperties":false,"required":["prerequisites","owns","idOptions"],"properties":{"prerequisites":{"type":"array","maxItems":4,"uniqueItems":true,"items":{"type":"string","minLength":2,"maxLength":100}},"owns":{"type":"array","maxItems":3,"uniqueItems":true,"items":{"type":"string","minLength":2,"maxLength":80}},"idOptions":{"type":"array","maxItems":10,"uniqueItems":true,"items":{"type":"string","minLength":2,"maxLength":30}}}},"authoringRoles":{"type":"array","minItems":1,"maxItems":5,"uniqueItems":true,"items":{"enum":["H0","H1","H2","H3","H4"]}},"wraps":{"type":"array","maxItems":20,"uniqueItems":true,"items":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9]*$"}},"editableVia":{"type":"array","maxItems":20,"uniqueItems":true,"items":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9]*$"}},"supports":{"type":"object","additionalProperties":false,"required":["entryPoints"],"properties":{"entryPoints":{"type":"array","minItems":1,"maxItems":2,"uniqueItems":true,"items":{"enum":["default","basic"]}}}},"units":{"type":"array","maxItems":16,"items":{"type":"object","additionalProperties":false,"required":["path","unit"],"properties":{"path":{"type":"string","minLength":1,"maxLength":80},"unit":{"enum":["logical-pixel","degree","angle","ratio","probability","count","calendar-unit","temporal-input","data-value","band-fraction"]}}}},"inference":{"type":"array","maxItems":20,"items":{"type":"object","additionalProperties":false,"required":["input","strategy"],"properties":{"input":{"type":"string","minLength":1,"maxLength":80},"strategy":{"enum":["explicit","explicit-or-current","explicit-current-unique-or-error","documented-auto","documented-default"]}}}},"completionRequirements":{"type":"object","additionalProperties":false,"required":["state","requires","allowsEmpty"],"properties":{"state":{"enum":["complete","deferred","contextual","not-applicable"]},"requires":{"type":"array","maxItems":4,"uniqueItems":true,"items":{"type":"string","minLength":2,"maxLength":100}},"allowsEmpty":{"type":"boolean","description":"Whether this action permits an empty result. This does not promise that subsequent actions can infer domains from empty data or that geometry is complete."}}},"options":{"type":"array","maxItems":40,"items":{"type":"object","additionalProperties":false,"required":["name","required","type"],"properties":{"name":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9]*$"},"required":{"type":"boolean"},"type":{"type":"string","minLength":1,"maxLength":500}}}},"callPatterns":{"type":"array","minItems":1,"maxItems":3,"uniqueItems":true,"items":{"type":"string","minLength":3,"maxLength":260}},"snippet":{"type":"string","minLength":3,"maxLength":700},"errors":{"type":"array","maxItems":2,"items":{"type":"object","additionalProperties":false,"required":["error","fix"],"properties":{"error":{"type":"string","minLength":5,"maxLength":220},"fix":{"type":"string","minLength":5,"maxLength":220}}}},"route":{"type":"string","pattern":"^/reference/"}}}