ggaction 0.0.3 → 0.0.5

package/CHANGELOG.md

@@ -4,6 +4,59 @@ All notable changes to `ggaction` are recorded in this file.
 
 ## Unreleased
 
+## [0.0.5] - 2026-07-21
+
+### Added
+
+- Added complete `createScatterPlot`, `createLinePlot`, `createBarPlot`, `createHistogram`, `createHeatmap`, and
+  `createParallelCoordinates` facades that reuse ordinary mark, encoding, scale, coordinate, and guide actions.
+- Added deterministic point jitter, ordered line paths, collision-aware text labels, field-driven rule widths, and
+  weighted Polar sectors with immutable rematerialization across data, scale, Canvas, selection, and facet changes.
+- Added window and rectangular 2D-bin data actions, binned heatmaps, categorical density and violin plots, Horizon
+  charts, Parallel Coordinates, and density-filled gradient plots with Browser Canvas and Node PNG parity.
+- Added backend-neutral item-local gradient paint, expanded public declarations and action contracts, and runnable
+  chart examples for every new capability.
+
+### Changed
+
+- Aligned Box Plot with the shared facade inference, ambiguity, public option-type, and opt-in guide contracts while
+  preserving its existing omitted-guide behavior.
+- Reorganized source, test, documentation, and internal architecture ownership around explicit policies and capability
+  registries without changing the renderer's concrete `graphicSpec` boundary.
+- Expanded public documentation with task-oriented API routing, generated split action references, improved mobile and
+  no-JavaScript navigation, complete facade discovery, and release-scoped deployment checks.
+
+### Fixed
+
+- Materialized the documented default point radius, made direct quantitative line x/y authoring order-independent, and
+  made layered datum rules resolve to the expected full-span geometry instead of an empty result.
+- Kept sticky documentation deep links below the top bar by sharing one computed fragment offset between CSS and the
+  page table of contents.
+
+## [0.0.4] - 2026-07-19
+
+### Changed
+
+- Transferred the canonical repository to the `ggaction` organization and moved public documentation to
+  `https://ggaction.github.io/ggaction/`.
+- Made public documentation deployment release-scoped so ordinary `main` pushes continue to verify docs without
+  changing the published site.
+- Refactored source ownership and materialization boundaries while preserving the public API, stored specifications,
+  trace hierarchy, and rendered output.
+
+### Fixed
+
+- Normalized numeric Canvas font weights before rendering so valid intermediate values such as `650` retain normal
+  text geometry in both Browser Canvas and Node PNG output.
+- Applied right categorical legend offsets from the plot boundary consistently during creation and focused layout
+  edits, including labels, titles, and optional backgrounds.
+- Accepted `count` on sequential palette descriptors as a concrete gradient-stop count, consistently across
+  top-level palette shorthands, nested ranges, encodings, direct scales, and scale edits.
+- Preserved concrete `ChartProgram` subclasses in the TypeScript signature of wrapped extension actions and added
+  a strict NodeNext declaration-merging authoring pattern.
+- Routed every selective `llms.txt` target to a deployed HTML page, stabilized action fragments, and made built-site
+  checks validate both HTTP targets and DOM IDs.
+
 ## [0.0.3] - 2026-07-19
 
 ### Added
@@ -58,6 +111,8 @@ All notable changes to `ggaction` are recorded in this file.
 - Cartesian charts are the complete current path. Polar semantic tokens exist only where explicitly documented and do
   not imply complete polar rendering.
 
-[0.0.3]: https://github.com/hj-n/ggaction/releases/tag/v0.0.3
-[0.0.2]: https://github.com/hj-n/ggaction/releases/tag/v0.0.2
-[0.0.1]: https://github.com/hj-n/ggaction/releases/tag/v0.0.1
+[0.0.5]: https://github.com/ggaction/ggaction/releases/tag/v0.0.5
+[0.0.4]: https://github.com/ggaction/ggaction/releases/tag/v0.0.4
+[0.0.3]: https://github.com/ggaction/ggaction/releases/tag/v0.0.3
+[0.0.2]: https://github.com/ggaction/ggaction/releases/tag/v0.0.2
+[0.0.1]: https://github.com/ggaction/ggaction/releases/tag/v0.0.1

package/README.md

@@ -1,119 +1,153 @@
 # ggaction
 
-`ggaction` is a JavaScript library for building charts through immutable,
-traceable actions.
+[![npm version](https://img.shields.io/npm/v/ggaction.svg)](https://www.npmjs.com/package/ggaction) [![license](https://img.shields.io/npm/l/ggaction.svg)](./LICENSE) [![documentation](https://img.shields.io/badge/docs-ggaction.github.io-2563eb)](https://ggaction.github.io/ggaction/)
+
+### A grammar for how charts are made.
+
+Most visualization grammars describe a finished chart. **ggaction** represents chart authoring itself as an immutable, traceable sequence of graphical actions.
+
+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.">
+</p>
+
+Every frame is rendered from an immutable `ChartProgram`. The final R² label is a custom traceable action composed from ggaction's public extension primitives.
+
+```bash
+npm install ggaction
+```
+
+## A grammar of graphical action
+
+Actions are verbs:
+
+`create · transform · encode · edit · select · compose`
+
+Chart resources are nouns:
+
+`data · marks · scales · coordinates · guides`
+
+A `ChartProgram` is the immutable sentence they produce.
+
+The following fragment assumes `cars` is an array of row objects:
+
+```javascript
+import { chart } from "ggaction";
+
+const program = chart()
+  .createCanvas()
+  .createData({ values: cars })
+  .createScatterPlot({
+    id: "points",
+    x: "Displacement",
+    y: "Acceleration",
+    color: "Origin",
+    guides: false
+  })
+  .createRegression()
+  .createGuides();
+```
+
+## 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.
+
+## Quick start
+
+```bash
+npm install ggaction
+```
 
 ```javascript
 import { chart, render } from "ggaction";
 
-const cars = [
-  { horsepower: 88, mpg: 27, origin: "USA" },
-  { horsepower: 70, mpg: 36, origin: "Japan" },
-  { horsepower: 110, mpg: 24, origin: "Europe" }
+const observations = [
+  { displacement: 97, acceleration: 14.5, origin: "Japan" },
+  { displacement: 140, acceleration: 15.5, origin: "USA" },
+  { displacement: 86, acceleration: 16.4, origin: "Japan" }
 ];
 
 const program = chart()
   .createCanvas({
     width: 640,
     height: 400,
-    margin: { top: 30, right: 30, bottom: 60, left: 70 }
+    margin: { top: 30, right: 130, bottom: 60, left: 70 }
   })
-  .createData({ values: cars })
-  .createPointMark()
-  .encodeX({ field: "horsepower" })
-  .encodeY({ field: "mpg" })
-  .encodeColor({ field: "origin" })
-  .encodeRadius({ value: 3 })
-  .createGuides({
-    axes: {
-      x: { title: { text: "Horsepower" } },
-      y: { title: { text: "Miles per Gallon" } }
-    }
+  .createData({ values: observations })
+  .createScatterPlot({
+    x: "displacement",
+    y: "acceleration",
+    color: "origin"
   });
 
-render(program, document.querySelector("#chart").getContext("2d"));
+const context = document.querySelector("#chart").getContext("2d");
+render(program, context);
 ```
 
-The renderer reads only fully materialized, backend-neutral graphics. Semantic
-state is never automatically compiled during rendering.
+Use `createLinePlot`, `createBarPlot`, `createHistogram`, and `createHeatmap` for
+the other basic Cartesian charts. Each facade records the regular mark,
+encoding, and guide actions as trace children, and the same resource-specific
+actions remain available for later edits. See the
+[Basic Charts API](https://ggaction.github.io/ggaction/api/basic-charts/).
 
-> **Status:** `0.0.3` is the current experimental public release. APIs may change
-> before `1.0.0`; changes are recorded in the [changelog](./CHANGELOG.md).
+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/).
 
-## Install
+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/).
 
-```bash
-npm install ggaction
-```
+## What it supports
+
+- Cartesian, Polar, and Parallel-coordinate charts
+- Statistical layers and intervals
+- Faceting and program composition
+- Mark selection and coordinated highlighting
+- Browser Canvas and Node PNG output
+- TypeScript declarations and traceable extension actions
 
-The package is ESM-only and supports Node.js 20 or later. The default `ggaction`
-entry works with modern browser build tools and Canvas. `ggaction/png` is
-Node-only and uses a native Canvas dependency.
+See the current [supported features](https://ggaction.github.io/ggaction/supported-features/), [tutorials and examples](https://ggaction.github.io/ggaction/tutorials/), and [action reference](https://ggaction.github.io/ggaction/reference/actions/) for exact coverage. Runnable programs are collected in [`examples/`](./examples/README.md).
+
+## Package entries
+
+The package is ESM-only and requires Node.js 20 or later.
 
 | Entry | Purpose |
 | --- | --- |
 | `ggaction` | Create chart programs and render them to Browser Canvas |
-| `ggaction/extension` | Author wrapped actions and use public low-level primitives |
+| `ggaction/extension` | Author wrapped actions with public low-level primitives |
 | `ggaction/png` | Render a completed program to a PNG file in Node.js |
 
-All three entries include TypeScript declarations. See [Getting
-Started](https://hyeonword.com/ggaction/getting-started/) for a complete browser
-setup and [Rendering](https://hyeonword.com/ggaction/api/rendering/) for Node PNG
-output.
+All entries include TypeScript declarations. The default entry is browser-safe; the PNG adapter is Node-only.
 
 ## Documentation
 
-- [npm package](https://www.npmjs.com/package/ggaction)
-- [Getting started](https://hyeonword.com/ggaction/getting-started/)
-- [Cars scatterplot tutorial](https://hyeonword.com/ggaction/tutorials/scatterplot/)
-- [Cars line chart tutorial](https://hyeonword.com/ggaction/tutorials/line-chart/)
-- [Cars histogram tutorial](https://hyeonword.com/ggaction/tutorials/histogram/)
-- [Bar chart tutorial](https://hyeonword.com/ggaction/tutorials/grouped-bar/)
-- [Regression scatterplot tutorial](https://hyeonword.com/ggaction/tutorials/regression-scatterplot/)
-- [Density area chart tutorial](https://hyeonword.com/ggaction/tutorials/density-area/)
-- [Error-bar chart tutorial](https://hyeonword.com/ggaction/tutorials/error-bar/)
-- [Error-band chart tutorial](https://hyeonword.com/ggaction/tutorials/error-band/)
-- [Mark selection and highlighting tutorial](https://hyeonword.com/ggaction/tutorials/mark-selection/)
-- [Box-plot API](https://hyeonword.com/ggaction/api/box-plots/)
-- [Chart concepts](https://hyeonword.com/ggaction/concepts/chart-program/)
-- [Complete action reference](https://hyeonword.com/ggaction/reference/actions/)
-- [Supported features](https://hyeonword.com/ggaction/supported-features/)
-- [Documentation index](https://hyeonword.com/ggaction/)
-
-The runnable [cars scatterplot](https://github.com/hj-n/ggaction/tree/main/examples/cars-scatterplot/),
-[aggregate line chart](https://github.com/hj-n/ggaction/tree/main/examples/cars-line-chart/), and
-[stacked histogram](https://github.com/hj-n/ggaction/tree/main/examples/cars-histogram/) use `data/cars.json`. The
-[regression scatterplot](https://github.com/hj-n/ggaction/tree/main/examples/cars-regression-scatterplot/) also uses the
-cars data and layers grouped fits with confidence bands. The [grouped bar
-chart](https://github.com/hj-n/ggaction/tree/main/examples/jobs-grouped-bar/) uses `data/jobs.json`. The [density area
-chart](https://github.com/hj-n/ggaction/tree/main/examples/cars-density-area/) derives grouped Acceleration
-distributions from the cars data. The [error-bar chart](https://github.com/hj-n/ggaction/tree/main/examples/cars-error-bar/)
-summarizes mean Acceleration with 95% confidence intervals. The
-[error-band chart](https://github.com/hj-n/ggaction/tree/main/examples/gapminder-error-band/) summarizes grouped
-confidence intervals as closed area paths over time.
-The [box plot](https://github.com/hj-n/ggaction/tree/main/examples/cars-box-plot/) supports vertical or horizontal
-Tukey/min–max ranges, configurable factor and component appearance, and
-optional outlier rendering from categorical and quantitative field pairs.
-The [mark-selection example](https://github.com/hj-n/ggaction/tree/main/examples/mark-selection/) compares grouped point,
-complete stacked-bar, and line-series highlighting through one selector grammar.
-The [program-composition example](https://github.com/hj-n/ggaction/tree/main/examples/program-composition/) combines
-complete child programs, edits their inferred layout, and replaces one stable slot.
-The [facet example](https://github.com/hj-n/ggaction/tree/main/examples/cars-origin-scatterplot-facet/)
-repeats one chart with `.facet({ field: "Origin" })`, channel-level shared or
-independent scales, per-cell or occupied-outer axes, and an optional compatible
-parent-owned legend. Regression, density, interval, and box-derived data are
-recomputed independently inside each cell.
-Complete Cartesian and Polar programs can be nested with `hconcat` and
-`vconcat`; the [cross-feature dashboard](https://github.com/hj-n/ggaction/tree/main/examples/cross-feature-dashboard/)
-shows a Polar child replacement beside a Cartesian facet. Polar sources cannot
-currently be faceted and fail before partial child state is created.
-Completed programs can also be exported through
-[`ggaction/png`](https://hyeonword.com/ggaction/api/rendering/#png-output).
-
-## Development
+- [Getting Started](https://ggaction.github.io/ggaction/getting-started/)
+- [Tutorials and Examples](https://ggaction.github.io/ggaction/tutorials/)
+- [Action Reference](https://ggaction.github.io/ggaction/reference/actions/)
+- [Concepts](https://ggaction.github.io/ggaction/concepts/chart-program/)
+- [Supported Features](https://ggaction.github.io/ggaction/supported-features/)
+
+## Status and development
+
+> **Status:** `0.0.5` is the current experimental public release. APIs may change before `1.0.0`; changes are recorded in the [changelog](./CHANGELOG.md).
 
 ```bash
 npm install
+npm run assets:readme
 npm test
 npm run test:render
+npm run test:docs
 ```

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "ggaction",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Build charts through immutable, traceable graphical actions.",
   "license": "MIT",
   "author": "Hyeon Jeon",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/hj-n/ggaction.git"
+    "url": "git+https://github.com/ggaction/ggaction.git"
   },
-  "homepage": "https://hyeonword.com/ggaction/",
+  "homepage": "https://ggaction.github.io/ggaction/",
   "bugs": {
-    "url": "https://github.com/hj-n/ggaction/issues"
+    "url": "https://github.com/ggaction/ggaction/issues"
   },
   "keywords": [
     "visualization",
@@ -22,7 +22,7 @@
   "type": "module",
   "files": [
     "src/",
-    "!src/AGENTS.md",
+    "!src/**/AGENTS.md",
     "types/",
     "README.md",
     "CHANGELOG.md",
@@ -54,16 +54,29 @@
     "test:docs:built": "node scripts/check-built-docs.js _site",
     "test:docs:browser": "node scripts/test-built-docs.js _site",
     "test:coverage": "node scripts/run-tests.js coverage",
-    "test:render": "node test/support/artifacts.js && node scripts/run-tests.js render && node scripts/generate-roadmap-gallery.js && node scripts/test-roadmap-gallery.js",
-    "artifacts:gallery": "node scripts/generate-roadmap-gallery.js",
-    "artifacts:gallery:test": "node scripts/test-roadmap-gallery.js",
+    "test:render": "node scripts/run-render-tests.js",
+    "assets:readme": "node scripts/generate-readme-demo.js",
+    "artifacts:clean": "node test/support/artifacts.js",
+    "artifacts:gallery": "node scripts/generate-artifact-gallery.js",
+    "artifacts:gallery:test": "node scripts/test-artifact-gallery.js",
     "docs:images": "node scripts/generate-doc-images.js",
     "docs:llms": "node scripts/generate-llm-docs.js",
+    "docs:capabilities": "node scripts/generate-doc-capabilities.js",
+    "docs:capabilities:check": "node scripts/generate-doc-capabilities.js --check",
+    "docs:actions": "node scripts/generate-doc-action-metadata.js",
+    "docs:actions:check": "node scripts/generate-doc-action-metadata.js --check",
+    "docs:search": "node scripts/generate-doc-search-index.js",
+    "docs:search:check": "node scripts/generate-doc-search-index.js --check",
+    "docs:reference": "node scripts/generate-doc-action-reference.js",
+    "docs:reference:check": "node scripts/generate-doc-action-reference.js --check",
+    "docs:metadata": "node scripts/generate-doc-page-metadata.js",
+    "docs:metadata:check": "node scripts/generate-doc-page-metadata.js --check",
+    "docs:preflight": "node scripts/check-docs-environment.js",
     "docs:signatures": "node scripts/generate-doc-signatures.js",
     "docs:signatures:check": "node scripts/generate-doc-signatures.js --check",
-    "docs:generate": "npm run docs:signatures && npm run docs:images && npm run docs:llms",
+    "docs:generate": "npm run docs:signatures && npm run docs:capabilities && npm run docs:actions && npm run docs:reference && npm run docs:metadata && npm run docs:search && npm run docs:images && npm run docs:llms",
     "docs:build": "bundle exec jekyll build --source docs --destination _site --baseurl /ggaction",
-    "docs:verify": "npm run docs:generate && npm run test:docs && npm run docs:build && npm run test:docs:built && npm run test:docs:browser",
+    "docs:verify": "npm run docs:preflight && npm run docs:generate && npm run test:docs && npm run docs:build && npm run test:docs:built && npm run test:docs:browser",
     "contracts:catalog": "node scripts/generate-action-catalog.js",
     "contracts:catalog:check": "node scripts/generate-action-catalog.js --check",
     "package:check": "node scripts/package-artifact.js --check",
@@ -83,8 +96,11 @@
     "@napi-rs/canvas": "^1.0.2"
   },
   "devDependencies": {
+    "@axe-core/playwright": "^4.12.1",
     "es-module-lexer": "^1.7.0",
+    "gifenc": "^1.0.3",
     "playwright": "^1.61.1",
-    "typescript": "^7.0.2"
+    "typescript": "^7.0.2",
+    "vite": "^6.4.3"
   }
 }

package/src/actions/boxPlots/create.js

@@ -1,7 +1,7 @@
 import { action } from "../../core/action.js";
 import { validateKeys } from "../../core/validation.js";
-import { findDataset } from "../../selectors/datasets.js";
 import { findSemanticScale } from "../../selectors/scales.js";
+import { resolveFacadeData } from "../charts/shared.js";
 import {
   BOX_PLOT_OPTIONS,
   boxEncodingArgs,
@@ -9,6 +9,7 @@ import {
   resolveBoxMedianAppearance,
   resolveBoxOutlierAppearance,
   resolveBoxPosition,
+  resolveBoxGuides,
   resolveBoxWhisker,
   resolveBoxWidth
 } from "./options.js";
@@ -26,11 +27,14 @@ export const createBoxPlot = action(
   function (args = {}) {
     validateKeys(args, BOX_PLOT_OPTIONS, "createBoxPlot");
     const id = resolveBoxPlotId(this, args.id);
-    const source = resolveBoxSourceLayer(this, args.target);
-    const data = args.data ?? source?.data ?? this.context.currentData;
-    if (findDataset(this, data) === undefined) {
-      throw new Error("createBoxPlot requires data or one inferable dataset.");
-    }
+    const source = resolveBoxSourceLayer(this, args.target, {
+      requiresInference: args.x === undefined || args.y === undefined
+    });
+    const data = resolveFacadeData(
+      this,
+      args.data ?? source?.data,
+      "createBoxPlot"
+    );
     const x = resolveBoxPosition(args.x, "x") ?? source?.encoding?.x;
     const y = resolveBoxPosition(args.y, "y") ?? source?.encoding?.y;
     const whisker = resolveBoxWhisker(args.whisker);
@@ -41,6 +45,7 @@ export const createBoxPlot = action(
     const box = resolveBoxAppearance(args.box);
     const median = resolveBoxMedianAppearance(args.median);
     const outlier = resolveBoxOutlierAppearance(args.outlier);
+    const guides = resolveBoxGuides(args.guides);
     if (x !== undefined && y !== undefined && resolveBoxOrientation(x, y) === undefined) {
       throw new Error(
         "createBoxPlot requires one categorical axis and one quantitative axis."
@@ -62,7 +67,8 @@ export const createBoxPlot = action(
         outliers: args.outliers ?? true,
         box,
         median,
-        outlier
+        outlier,
+        guides
       }
     });
     if (x !== undefined) {

package/src/actions/boxPlots/edit.js

@@ -4,7 +4,8 @@ import { validateUserId } from "../../core/identifiers.js";
 import { validateKeys } from "../../core/validation.js";
 import { BOX_FIELDS, deriveBoxData, normalizeBoxTransform } from
   "../../grammar/boxPlot.js";
-import { hasDataset } from "../../selectors/index.js";
+import { planDerivedDataRevision } from
+  "../../materialization/dataProvenance.js";
 import { findDataset } from "../../selectors/datasets.js";
 import { findLayer } from "../../selectors/layers.js";
 import {
@@ -61,14 +62,6 @@ function resolveEditedWhisker(current, value) {
   return resolveBoxWhisker(candidate, "editBoxPlot");
 }
 
-function nextRevisionId(program, ownerId, kind) {
-  let revision = 1;
-  while (hasDataset(program, `${ownerId}${kind}Revision${revision}`)) {
-    revision += 1;
-  }
-  return `${ownerId}${kind}Revision${revision}`;
-}
-
 function removeOwnedMark(program, id) {
   return program
     .editSemantic({ property: `layer[${id}]`, remove: true })
@@ -76,10 +69,6 @@ function removeOwnedMark(program, id) {
     ._withoutMaterializationConfig(["marks", id]);
 }
 
-function rebindRuleData(program, id, data) {
-  return program.editSemantic({ property: `layer[${id}].data`, value: data });
-}
-
 export const editBoxPlot = action(
   {
     op: "editBoxPlot",
@@ -156,7 +145,18 @@ export const editBoxPlot = action(
       derived.outliers.length > 0;
 
     if (revisesData) {
-      summaryId = nextRevisionId(this, owner.id, "SummaryData");
+      const whiskerConfig = next.markConfigs[current.whiskerId];
+      const capIds = [
+        whiskerConfig.errorBar.lowerCapId,
+        whiskerConfig.errorBar.upperCapId
+      ].filter(id => id !== undefined);
+      const summaryRevision = planDerivedDataRevision(this, {
+        owner: owner.id,
+        role: "SummaryData",
+        previous: current.summaryId,
+        consumers: [owner.id, current.whiskerId, ...capIds, current.medianId]
+      });
+      summaryId = summaryRevision.id;
       next = next.createBoxSummaryData({
         id: summaryId,
         source: current.source,
@@ -166,7 +166,16 @@ export const editBoxPlot = action(
         ...(whisker.factor === undefined ? {} : { factor: whisker.factor })
       });
       if (hasOutliers) {
-        outlierDataId = nextRevisionId(this, owner.id, "OutlierData");
+        const hadOutlierLayer = findLayer(next, current.outlierId) !== undefined;
+        const outlierRevision = planDerivedDataRevision(this, {
+          owner: owner.id,
+          role: "OutlierData",
+          ...(current.outlierDataId === undefined
+            ? {}
+            : { previous: current.outlierDataId }),
+          consumers: hadOutlierLayer ? [current.outlierId] : []
+        });
+        outlierDataId = outlierRevision.id;
         next = next.createBoxOutlierData({
           id: outlierDataId,
           source: current.source,
@@ -175,37 +184,24 @@ export const editBoxPlot = action(
           whisker: whisker.type,
           factor: whisker.factor
         });
+        for (const rebind of outlierRevision.rebinds) {
+          next = next.rebindLayerData(rebind);
+        }
       } else {
         outlierDataId = undefined;
       }
 
-      next = next.editSemantic({
-        property: `layer[${owner.id}].data`,
-        value: summaryId
-      });
-      const whiskerConfig = next.markConfigs[current.whiskerId];
-      const capIds = [
-        whiskerConfig.errorBar.lowerCapId,
-        whiskerConfig.errorBar.upperCapId
-      ].filter(id => id !== undefined);
-      next = rebindRuleData(next, current.whiskerId, summaryId)
-        ._withMarkConfig(current.whiskerId, {
+      for (const rebind of summaryRevision.rebinds) {
+        next = next.rebindLayerData(rebind);
+      }
+      next = next._withMarkConfig(current.whiskerId, {
           ...whiskerConfig,
           errorBar: { ...whiskerConfig.errorBar, data: summaryId }
         });
-      for (const capId of capIds) {
-        next = rebindRuleData(next, capId, summaryId);
-      }
-      next = rebindRuleData(next, current.medianId, summaryId);
 
       const hadOutlierLayer = findLayer(next, current.outlierId) !== undefined;
       if (hadOutlierLayer && !hasOutliers) {
         next = removeOwnedMark(next, current.outlierId);
-      } else if (hadOutlierLayer && hasOutliers) {
-        next = next.editSemantic({
-          property: `layer[${current.outlierId}].data`,
-          value: outlierDataId
-        });
       } else if (!hadOutlierLayer && hasOutliers) {
         next = next.createBoxOutliers({
           id: current.outlierId,

package/src/actions/boxPlots/materialize.js

@@ -189,6 +189,9 @@ export const materializeBoxPlot = action(
         outlierDataId: hasOutliers ? outlierDataId : undefined
       }
     });
+    if (config.guides !== false) {
+      next = next.createGuides(config.guides);
+    }
     return next._withContext({ currentMark: ownerId, currentData: source });
   }
 );

package/src/actions/boxPlots/options.js

@@ -8,10 +8,11 @@ import {
 } from "../../core/validation.js";
 import { validatePointShape } from "../../grammar/pointShapes.js";
 import { DEFAULT_COLORS } from "../../theme/defaults.js";
+import { normalizeGuides } from "../charts/shared.js";
 
 export const BOX_PLOT_OPTIONS = Object.freeze([
   "id", "target", "data", "x", "y", "coordinate", "whisker",
-  "width", "outliers", "box", "median", "outlier"
+  "width", "outliers", "box", "median", "outlier", "guides"
 ]);
 
 const DEFAULT_BOX = Object.freeze({
@@ -52,6 +53,12 @@ export function boxEncodingArgs(value) {
   };
 }
 
+export function resolveBoxGuides(value) {
+  return value === undefined
+    ? false
+    : normalizeGuides(value, "createBoxPlot");
+}
+
 export function resolveBoxWhisker(value, operation = "createBoxPlot") {
   if (value === undefined) return Object.freeze({ type: "tukey", factor: 1.5 });
   if (!isPlainObject(value)) {

package/src/actions/boxPlots/resolve.js

@@ -11,7 +11,9 @@ export function resolveBoxOrientation(x, y) {
   return undefined;
 }
 
-export function resolveBoxSourceLayer(program, target) {
+export function resolveBoxSourceLayer(program, target, {
+  requiresInference = true
+} = {}) {
   if (target !== undefined) {
     const layer = findLayer(program, validateUserId(target, "Box source layer id"));
     if (layer === undefined) throw new Error(`Unknown box source layer "${target}".`);
@@ -24,7 +26,13 @@ export function resolveBoxSourceLayer(program, target) {
   const eligible = program.semanticSpec.layers.filter(
     layer => layer.encoding?.x !== undefined && layer.encoding?.y !== undefined
   );
-  return eligible.length === 1 ? eligible[0] : undefined;
+  if (eligible.length === 1) return eligible[0];
+  if (eligible.length > 1 && requiresInference) {
+    throw new Error(
+      "createBoxPlot target is ambiguous; provide target or explicit x and y."
+    );
+  }
+  return undefined;
 }
 
 export function resolveBoxPlotId(program, requested) {