ggaction 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to `ggaction` are recorded in this file.
+
+## [0.0.1] - 2026-07-17
+
+### Added
+
+- Immutable, traceable `ChartProgram` authoring with user-facing chart actions.
+- Point, line, area, bar, rule, error-bar, error-band, regression, density, and box-plot workflows.
+- Position, appearance, scale, axis, grid, legend, title, selection, and highlighting actions.
+- Browser Canvas rendering through `ggaction` and Node PNG output through `ggaction/png`.
+- Public extension authoring through `ggaction/extension`.
+- TypeScript declarations for every public package entry.
+- Runnable documentation, chart examples, generated images, and packed-package consumer qualification.
+
+### Known limitations
+
+- This is an experimental pre-1.0 release; public APIs may change in later minor or patch releases.
+- Rendering targets Browser Canvas and Node PNG. SVG rendering, animation, facets, and program composition are not yet
+  supported.
+- A semantic specification is never compiled automatically. Domain actions must materialize the concrete graphics they
+  change before rendering.
+- Cartesian charts are the complete current path. Polar semantic tokens exist only where explicitly documented and do
+  not imply complete polar rendering.
+
+[0.0.1]: https://github.com/hj-n/ggaction/releases/tag/v0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hyeon Jeon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# ggaction
+
+`ggaction` is a JavaScript library for building charts through immutable,
+traceable actions.
+
+```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 program = chart()
+  .createCanvas({
+    width: 640,
+    height: 400,
+    margin: { top: 30, right: 30, 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" } }
+    }
+  });
+
+render(program, document.querySelector("#chart").getContext("2d"));
+```
+
+The renderer reads only fully materialized, backend-neutral graphics. Semantic
+state is never automatically compiled during rendering.
+
+> **Status:** `0.0.1` is the first experimental public release. APIs may change
+> before `1.0.0`; changes are recorded in the [changelog](./CHANGELOG.md).
+
+## Install
+
+```bash
+npm install ggaction
+```
+
+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.
+
+| Entry | Purpose |
+| --- | --- |
+| `ggaction` | Create chart programs and render them to Browser Canvas |
+| `ggaction/extension` | Author wrapped actions and use 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.
+
+## 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.
+Completed programs can also be exported through
+[`ggaction/png`](https://hyeonword.com/ggaction/api/rendering/#png-output).
+
+## Development
+
+```bash
+npm install
+npm test
+npm run test:render
+```

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "ggaction",
+  "version": "0.0.1",
+  "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"
+  },
+  "homepage": "https://hyeonword.com/ggaction/",
+  "bugs": {
+    "url": "https://github.com/hj-n/ggaction/issues"
+  },
+  "keywords": [
+    "visualization",
+    "charts",
+    "graphics",
+    "canvas",
+    "data-visualization"
+  ],
+  "type": "module",
+  "files": [
+    "src/",
+    "types/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./extension": {
+      "types": "./types/extension.d.ts",
+      "default": "./src/extension.js"
+    },
+    "./png": {
+      "types": "./types/png.d.ts",
+      "default": "./src/renderers/png.js"
+    }
+  },
+  "scripts": {
+    "test": "node scripts/run-tests.js all",
+    "test:unit": "node scripts/run-tests.js unit",
+    "test:contracts": "node scripts/run-tests.js contracts",
+    "test:charts": "node scripts/run-tests.js charts",
+    "test:gates": "node scripts/run-tests.js gates",
+    "test:docs": "node scripts/run-tests.js docs",
+    "test:browser": "node scripts/run-tests.js browser",
+    "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",
+    "docs:images": "node scripts/generate-doc-images.js",
+    "docs:llms": "node scripts/generate-llm-docs.js",
+    "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",
+    "package:pack": "node scripts/package-artifact.js --pack",
+    "test:package": "node scripts/package-consumer.js",
+    "release:notes": "node scripts/release-notes.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest"
+  },
+  "dependencies": {
+    "@napi-rs/canvas": "^1.0.2"
+  },
+  "devDependencies": {
+    "es-module-lexer": "^1.7.0",
+    "playwright": "^1.61.1",
+    "typescript": "^7.0.2"
+  }
+}

package/src/AGENTS.md

@@ -0,0 +1,119 @@
+# Source Instructions
+
+Apply these instructions to library source, public package entry points, and source-facing declarations in addition to the repository root instructions.
+
+## Source Ownership and Module Boundaries
+
+- Organize directories by stable responsibility and reusable capability rather than by the chart example or implementation phase that first required the code.
+- Give each cross-cutting contract one canonical owner. Shared defaults, closed vocabularies, resource lookup rules, validation rules, and dispatch tables must be defined once and consumed by actions rather than re-declared in multiple feature modules.
+- Route ID-based lookup, existence checks, and required-resource errors for named semantic datasets, layers, scales, and coordinates through shared selectors. Keep capability queries local only when they select by semantic behavior rather than by resource identity.
+- Use one shared concrete-graphic schema for graphical editing and rendering. Renderers may add completeness checks required to draw a node, but they must not redefine a conflicting property or value contract.
+- Namespace every repeatable generated internal dataset, layer, scale, guide, and graphic ID from its owning user-defined resource ID and semantic role. Stable system IDs are reserved for structurally singular slots such as the canvas or one supported guide per channel; do not use global generated IDs where the same aggregate action can create more than one resource.
+- Store each piece of program state in one canonical representation. Convenience aliases must be derived read-only accessors, and internal counters or bookkeeping must remain non-enumerable or private rather than becoming duplicate serialized state.
+- Organize source code by reusable semantic capability and separate wrapped action orchestration from pure grammar, resolution, layout, and materialization calculations. Pure modules must not mutate a program or create trace nodes; meaningful authoring steps must remain wrapped actions.
+- Keep semantic computation, concrete graphical materialization, and renderer execution as explicit boundaries. Do not let renderers infer chart semantics or let pure semantic modules author backend operations.
+- Extract logic shared by multiple actions into the smallest responsible capability module instead of duplicating it or creating a chart-specific utility bucket.
+- Express cross-cutting rematerialization as deterministic plans of wrapped action calls, deduplicate equivalent plan steps while preserving order, and register new consumers with the responsible materialization policy instead of scattering ad hoc rematerialization calls across unrelated actions.
+- Keep every public JavaScript entry point synchronized with its TypeScript declaration, package export-map entry, and package-boundary tests. Keep Node-only adapters out of browser-safe entry points.
+- Respect package boundaries in internal imports as well as public exports. Cross-package consumers must use the owning package's supported entry point rather than reaching through to private implementation files.
+
+## User-Facing API Design
+
+- Maintain three clear layers: the default Chart Authoring API, the public Action Authoring API, and private library internals.
+- Assign every public action an explicit lifecycle in the action catalog: immutable create-only, mutable resource, assignment, aggregate create-only, stable resource with an edit gap, or primitive. Do not infer that every `create*` action mechanically requires an `edit*` counterpart.
+- A stable independently addressable resource must either have a supported edit path or an explicit cataloged gap. Define editable properties, rematerialization ownership, and conflict behavior before adding its edit action; aggregate actions remain create-only and delegate updates to child actions.
+- Treat resources whose type or attachment changes invalidate multiple semantic and graphical dependencies as structural create-only resources unless an approved resource-specific edit contract owns complete compatibility preflight and deterministic rematerialization. Scale is the explicit exception: `editScale` may atomically change its type only after validating the complete resulting definition and every connected consumer, then rematerializing all dependent marks and guides.
+- Validate a scale edit against the complete proposed definition—type, domain, range, type-specific options, mapping policies, and every connected consumer—before applying any state change. Shared marks, axes, grids, and legends must either all accept the result and rematerialize deterministically or all remain unchanged.
+- When a scale has no attached consumer, validate only the channel-independent definition. Defer channel-, field-, mark-, and item-grain-specific validation until attachment, and reject the attachment if the stored definition is incompatible.
+- Do not treat a guide recipe change as ordinary rematerialization. When an edit would require replacing one structural guide family with another, require an explicit approved replacement action or reject the edit before changing semantic or graphical state.
+- Keep sibling component actions behind the same public facade unless a distinct direct authoring use case justifies exposing one. Internal wrapped components remain visible in traces, but do not expose one sibling merely because implementation staging made it convenient.
+- The default `ggaction` entry point serves chart authors through domain-specific actions and rendering.
+- The `ggaction/extension` entry point serves action authors through `ChartProgram`, `action()`, primitive actions, and trace inspection.
+- The Node-only `ggaction/png` entry point exports completed programs without adding Node dependencies to the browser entry point.
+- Encourage extension authors to subclass `ChartProgram` instead of modifying the shared base prototype, so independently authored extensions do not collide.
+- Do not expose private path-parsing, structural-copy, validation, or rendering-dispatch helpers through public entry points.
+- Do not expose raw graphical IDs or raw graphical property paths when a meaningful domain action can represent the operation.
+- Name chart-authoring actions after semantic concepts such as `createPointMark`; keep concrete realizations such as `circle` inside action implementations and `graphicSpec`.
+- Public actions accept meaningful option objects, such as `editXAxisLine({ lineWidth: 3 })`.
+- Every public action accepts one parameter object and returns a new `ChartProgram`.
+- Require only inputs that the user must decide and that cannot be inferred safely. User-facing actions should infer or default the remaining options whenever the stored program state determines them unambiguously.
+- Ordinary chart-authoring create actions may omit a user resource ID only when one documented deterministic role ID is unambiguous. Persist that resolved ID in semantic state, never invent numbered public-resource IDs, and require an explicit ID when the same role already exists. Advanced resource-assembly actions keep explicit IDs unless their own approved contract says otherwise.
+- Resolve omitted options in this order: an explicit option, a unique inference from stored semantic state, a documented library default, then an error when no safe decision remains. Never choose arbitrarily among multiple candidates.
+- For an action that derives a new layer from an existing encoded layer, infer omitted data, coordinate, position encodings, compatible scale IDs, and explicit semantic grouping from that source layer. Select the source by explicit target, then the current eligible layer, then a unique eligible layer; reject ambiguous candidates or ambiguous channel roles. Apply this rule by semantic capability rather than by the source mark type so layered composition remains consistent across marks.
+- When an ordinary mark is added as a new layer, infer omitted data, coordinate, and compatible `x`/`y` encodings from the current eligible layer, then from one unique eligible layer. Persist the inferred encodings on the new layer, keep mark-specific policies such as aggregate, bin, and stack out of a different mark recipe unless that recipe explicitly supports them, and reject ambiguity instead of choosing a source arbitrarily. Explicit authoring always takes precedence.
+- Make mark-dependent authoring order-independent whenever the final semantic state is unambiguous. Ordinary marks may remain graphically incomplete until their required encodings arrive; derived and composite mark actions must likewise support both compatible encodings before creation and compatible encodings after creation. Register the owning materialization intent when prerequisites are incomplete, rematerialize when later data or encoding actions complete them, and require an explicit target instead of choosing among ambiguous consumers.
+- Treat documented defaults and inference behavior as part of the public API contract. Cover them in user documentation and tests, and persist inferred semantic decisions in `semanticSpec`.
+- Use omission, an empty object, and `false` consistently in aggregate APIs: omission requests automatic applicability and inference, `{}` explicitly selects the component with inferred details, and `false` explicitly disables it.
+- Define option-state semantics explicitly and consistently: omission preserves existing state, `"auto"` resets a supported inferred value, and an explicitly supported `undefined` removes an existing optional property. Do not conflate these states inside create, edit, or rematerialization code.
+- Keep create and edit contracts consistent. A create action requires a missing resource, may treat an equivalent repeated definition as idempotent when explicitly intended, and must reject conflicting definitions. An edit action requires an existing resource and must reject an empty edit.
+- Validate library-defined closed vocabularies such as channels and types.
+- Treat user-defined IDs as names: validate their basic form, uniqueness when creating, and existence when referencing rather than checking them against a library vocabulary.
+- Infer layout coordinates from Canvas or plot bounds when possible instead of requiring raw x/y values. Do not make non-overlap a global invariant; individual actions and explicit user options may intentionally produce overlapping graphics.
+- Do not create placeholder resources for optional content. Create an optional dataset, semantic component, materialization config, graphic, or wrapped trace child only when the option is enabled and the component is semantically applicable with non-empty output; disabling or inapplicability must leave the entire optional branch absent.
+- Validate every mark-specific appearance option against the resolved mark recipe before changing state. Reject inapplicable options with a clear error instead of silently ignoring them or partially applying a highlight.
+
+## Actions and Trace
+
+- Define every authoring action through the shared `action()` wrapper.
+- Treat every `materialize*` and `rematerialize*` method as an internal wrapped action, not as a public direct-call API or an authoring primitive. The public domain action that owns the affected semantic resource must invoke it, and the resulting operation must remain visible in the trace.
+- Provide an atomic domain action when multiple semantic operations are interdependent and separately authoring them would leave an incomplete or misleading chart state.
+- When one public encoding choice requires a companion encoding, let the representative domain action create that companion through a wrapped child action. Keep the companion action available only as an advanced API when ordinary chart authors should not need to coordinate the pair manually.
+- Implement an atomic action by orchestrating the existing wrapped child actions that own the relevant validation, inference, and materialization; do not duplicate their behavior inside the aggregate.
+- Component actions invoked by higher-level actions must also be wrapped actions when they represent meaningful authoring steps.
+- Aggregate actions must orchestrate wrapped child actions instead of duplicating their behavior or hiding meaningful authoring steps inside untraced helpers.
+- Keep aggregate actions thin: they may decide child applicability and call order, but inference and validation owned by a child action must remain in that child rather than being reimplemented by the aggregate.
+- Before an aggregate action invokes its first state-changing child, use the canonical child-owned validators and resolvers to preflight the complete option object, inferred ownership, applicability, and conflicts without duplicating their logic. A rejected aggregate call must not leave partial datasets, layers, graphics, configs, or trace branches.
+- Do not hide meaningful action decomposition inside untraced helpers.
+- Every trace has a virtual `program` root, and nested wrapped calls form its action hierarchy.
+- Context updates are part of successful immutable state transitions; they are not separate actions or trace nodes.
+- Treat context only as transient convenience for interpreting the next action. Completed semantic meaning and renderable output must be persisted in `semanticSpec` or `graphicSpec`, never only in context.
+- Update context through a private immutable helper rather than a public or wrapped `setContext` action.
+- When `editSemantic` can infer the current semantic resource from its validated path, high-level actions must rely on that transition instead of duplicating it with `_withContext`.
+- Keep trace arguments lightweight. Do not copy large datasets or fully materialized value arrays into the trace.
+- When a transform creates a derived dataset for a mark, rebind that mark through an explicit wrapped semantic action so the dependency is visible in the trace. Do not make consumers switch datasets implicitly through context or untraced mutation.
+
+## Semantic and Graphical Boundary
+
+- `semanticSpec` records what the chart means; `graphicSpec` records the concrete graphical result.
+- The action that first introduces a semantic concept owns its inference, validation, and storage. Downstream actions must read the stored decision rather than silently creating, repairing, or re-inferring missing semantic state.
+- Persist every inferred semantic decision, including resolved resource IDs and types, in `semanticSpec`; do not leave a resolved decision only in context or an implementation-local value.
+- A semantic point mark may be realized by a graphical `circle` primitive.
+- Compute aggregate scale domains at the final visual grouping grain. For example, grouped bars use one aggregate per x/category cell rather than an earlier aggregate that ignores the grouping field.
+- A constant point shape is graphical appearance, while a field-driven shape is semantic encoding that must be explicitly materialized.
+- User-specified scale domains and ranges are semantic. Resolved primitive values such as x, y, radius, and color are graphical.
+- Give scale mapping one pure grammar owner. Point, line, area, bar, rule, guides, and future consumers must call the shared mapping policy rather than reimplementing transformations, clamping, reversal, discretization, or fallback behavior in mark-specific materializers.
+- Decide missing and invalid value behavior at the final semantic item grain, not from the channel name alone. A fallback may preserve a row-owned item, but must be rejected when it could change path, series, aggregate, interval, group, or other compound topology unless that grain has an explicit topology-safe policy.
+- Dataset values are immutable after creation; filtering, aggregation, and other data changes must create transforms or derived datasets rather than replace source values.
+- Editing a stored transform parameter must create a new deterministic namespaced derived-dataset revision and explicitly rebind its consumers; never overwrite an existing dataset's values. An unreferenced old derived revision may be released from the new program through a visible internal wrapped action, while earlier programs retain it unchanged.
+- Canvas properties, themes, fonts, strokes, and other appearance-only values are graphical.
+- Keep appearance-only materialization settings such as a grouped-bar band fraction outside `semanticSpec`; store them in immutable graphical configuration and materialize their concrete results into `graphicSpec`.
+- Keep mark-selector value sources explicit and non-overlapping: `field` reads data values, `channel` reads resolved pre-scale semantic encoding values, and `property` reads concrete `graphicSpec` values. Never expose a pixel dimension under a semantic channel name or overwrite a source field with an aggregate result.
+- Represent bar measure geometry semantically with endpoint channels: `y`/`x` is the start endpoint and `y2`/`x2` is the end endpoint. Concrete rectangles continue to use top-left `x`/`y` plus `width`/`height`. A selector grain that groups multiple concrete children must retain every attachment ID and expose the union bounds only as graphical properties.
+- Define selection over final materialized mark items rather than raw source rows. Reuse row identity only when one row corresponds deterministically to one final item; aggregated, grouped, stacked, path, area, and composite marks require identities at their actual visual grain.
+- Give every selectable mark recipe an explicit semantic item model. Keep semantic endpoints and grouping roles distinct from derived concrete properties such as top-left position, width, height, radius, or union bounds, and never introduce ambiguous aliases between them.
+- For marks with multiple meaningful grains, expose the grain explicitly and evaluate each grain independently. For example, one stacked-bar segment and the complete stack that contains it are different selectable items and must not be conflated by inference.
+- Implement highlighting as an appearance operation over the canonical normalized selection result. `highlightMarks` must reuse `selectMarks` selection semantics rather than introducing a second selector grammar or resolving a different item set.
+- Rematerialize highlights from the unhighlighted concrete baseline, then reevaluate stable item identities and apply the current selected/complement recipes. Never accumulate new highlight edits on previously highlighted graphics or treat stale child graphic IDs as authoritative.
+- When a legend represents a selected or highlighted mark domain, synchronize the applicable legend symbol appearance with that domain state while preserving label readability. Do not dim or restyle legend text unless an explicit text option requests it.
+- Output density such as PNG `pixelRatio` is a renderer option and must not rewrite logical values in `graphicSpec`.
+- When a semantic change affects existing concrete output, the responsible domain action must explicitly rematerialize every affected graphical consumer.
+- Positional encoding actions own coordinate inference and layer attachment. Guide actions read stored coordinates and must not create or repair them.
+- Once scale consumers exist, canvas width, height, or margin edits must explicitly invoke wrapped rematerialization actions for every affected scale, mark, and guide; never leave stale concrete coordinates or rely on automatic compilation.
+- Treat concrete rendering order as explicit graphical state rather than an accidental consequence of action call order. Use graphic placement to preserve relationships such as grids behind marks and axes or legends above them.
+- Do not synthesize missing categorical combinations as zero values or placeholder graphics unless an explicit semantic completion policy requests them. Materialize only observed groups by default.
+- Use one resolved ordinal domain order and its band geometry as the shared source of truth for marks, offsets, ticks, labels, and other positional consumers.
+- When one composite component depends on another component's realized geometry, derive it from the concrete owner geometry instead of duplicating scale, band, width, or endpoint calculations. Rematerialize the owner before its dependents so Canvas and scale edits preserve alignment.
+- Design shared guides around their semantic role, such as a categorical legend, and express mark-specific symbols through graphical recipes instead of forking the complete guide implementation by mark type.
+- Give each guide type one chart-independent documented default, such as a right-side legend. Alternate placement must come from an explicit public option rather than a different hidden default for each chart type.
+- Generic aggregate actions must select only semantic combinations that their child actions currently support. Determine applicability from persisted mark, encoding, scale, and coordinate state rather than from resource presence alone.
+- Statistical transforms must record enough provenance to reproduce and interpret their results: the source dataset, transform type, input and output fields, grouping, method, and every resolved parameter or default that affects the derived values.
+- When one statistical policy controls multiple coupled outputs, normalize it once and pass the same immutable resolved decision to every derived dataset and component. Do not independently recompute classifications such as summaries, bounds, and excluded rows in separate consumers.
+- Derived-data output order must be deterministic and documented. Unless a transform defines another semantic order, preserve group order by first appearance in the source and use a stable, explicit order within each group.
+- Keep statistical computation, semantic data authoring, and graphical materialization separate. Pure grammar modules compute derived values, data actions own transform provenance and derived datasets, and mark actions turn those values into concrete graphics.
+- User-facing guide text must not expose generated internal field names when transform provenance can recover the original meaning. Infer titles from source fields and semantic roles such as `Density` rather than names such as `Acceleration_density`.
+- Layers that jointly express one visual relationship, such as points, fitted lines, confidence bands, density curves, and their baselines, must use compatible coordinates and shared scales. Convert baselines and bounds through those scales rather than treating semantic values as raw graphical coordinates.
+- Layout actions that share reserved space must compute and validate occupied bounds from the actual concrete realization, including rotation, stroke extents, and every collection child rather than a nominal component box. When the requested title, legend, or similar block does not fit, report a clear layout error instead of silently expanding the Canvas or changing the user's margins.
+- Validate same-edge title, axis, legend, and similar reserved-block collisions symmetrically from the final graphical state. Create, edit, Canvas rematerialization, and reversed authoring order must accept or reject an equivalent final layout identically.
+- Resolve text measurement, word or character wrapping, Unicode code-point boundaries, and concrete line positions deterministically during materialization. Store the resolved text children in `graphicSpec`; renderers must not measure, wrap, or infer line placement again.
+- When an edit changes a stable graphic between a single node and a collection, changes collection cardinality, or otherwise changes its concrete representation, reconcile it under the same stable resource ID and rendering placement. Remove stale children or incompatible properties instead of retaining mixed old and new state.
+- Layout-resource edits and Canvas edits must converge: equivalent final options must produce the same concrete `graphicSpec` regardless of whether the layout edit or Canvas edit happened first.

package/src/ChartProgram.js

@@ -0,0 +1,10 @@
+import { registerActions } from "./actions/index.js";
+import { ChartProgram as CoreChartProgram } from "./core/ChartProgram.js";
+
+export class ChartProgram extends CoreChartProgram {}
+
+registerActions(ChartProgram);
+
+export function chart() {
+  return new ChartProgram();
+}

package/src/actions/boxPlots/components.js

@@ -0,0 +1,88 @@
+import { action } from "../../core/action.js";
+import { validateKeys } from "../../core/validation.js";
+
+const MEDIAN_OPTIONS = Object.freeze([
+  "id", "owner", "data", "category", "categoryType", "measure",
+  "coordinate", "categoryScale", "measureScale", "orientation", "stroke",
+  "strokeWidth"
+]);
+const OUTLIER_OPTIONS = Object.freeze([
+  "id", "data", "category", "categoryType", "measure", "coordinate",
+  "categoryScale", "measureScale", "orientation", "shape", "radius", "opacity"
+]);
+
+export const createBoxMedian = action(
+  {
+    op: "createBoxMedian",
+    description: "Create a median rule spanning one concrete box body."
+  },
+  function (args = {}) {
+    validateKeys(args, MEDIAN_OPTIONS, "createBoxMedian");
+    if (!["vertical", "horizontal"].includes(args.orientation)) {
+      throw new Error(`Unsupported box median orientation "${args.orientation}".`);
+    }
+    const categoryAction = args.orientation === "vertical" ? "encodeX" : "encodeY";
+    const measureAction = args.orientation === "vertical" ? "encodeY" : "encodeX";
+    let next = this.createRuleMark({ id: args.id, data: args.data });
+    next = next[categoryAction]({
+      target: args.id,
+      field: args.category,
+      fieldType: args.categoryType,
+      coordinate: args.coordinate,
+      scale: { id: args.categoryScale }
+    });
+    next = next[measureAction]({
+      target: args.id,
+      field: args.measure,
+      fieldType: "quantitative",
+      coordinate: args.coordinate,
+      scale: { id: args.measureScale }
+    });
+    next = next
+      .encodeStroke({ target: args.id, value: args.stroke })
+      .encodeStrokeWidth({ target: args.id, value: args.strokeWidth });
+    next = next._withMarkConfig(args.id, {
+      ...next.markConfigs[args.id],
+      boxSpanOwner: args.owner
+    });
+    return next.rematerializeRuleMark({ id: args.id });
+  }
+);
+
+export const createBoxOutliers = action(
+  {
+    op: "createBoxOutliers",
+    description: "Create concrete point symbols for box-plot outlier rows."
+  },
+  function (args = {}) {
+    validateKeys(args, OUTLIER_OPTIONS, "createBoxOutliers");
+    if (!["vertical", "horizontal"].includes(args.orientation)) {
+      throw new Error(`Unsupported box outlier orientation "${args.orientation}".`);
+    }
+    const categoryAction = args.orientation === "vertical" ? "encodeX" : "encodeY";
+    const measureAction = args.orientation === "vertical" ? "encodeY" : "encodeX";
+    let next = this.createPointMark({
+      id: args.id,
+      data: args.data,
+      shape: args.shape
+    });
+    next = next[categoryAction]({
+      target: args.id,
+      field: args.category,
+      fieldType: args.categoryType,
+      coordinate: args.coordinate,
+      scale: { id: args.categoryScale }
+    });
+    next = next[measureAction]({
+      target: args.id,
+      field: args.measure,
+      fieldType: "quantitative",
+      coordinate: args.coordinate,
+      scale: { id: args.measureScale }
+    });
+    return next
+      .encodeRadius({ target: args.id, value: args.radius })
+      .encodeOpacity({ target: args.id, value: args.opacity })
+      .editGraphics({ target: args.id, property: "fill", value: "#111111" });
+  }
+);

package/src/actions/boxPlots/create.js

@@ -0,0 +1,84 @@
+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 {
+  BOX_PLOT_OPTIONS,
+  boxEncodingArgs,
+  resolveBoxAppearance,
+  resolveBoxMedianAppearance,
+  resolveBoxOutlierAppearance,
+  resolveBoxPosition,
+  resolveBoxWhisker,
+  resolveBoxWidth
+} from "./options.js";
+import {
+  resolveBoxOrientation,
+  resolveBoxPlotId,
+  resolveBoxSourceLayer
+} from "./resolve.js";
+
+export const createBoxPlot = action(
+  {
+    op: "createBoxPlot",
+    description: "Create a Tukey box plot from categorical and quantitative positions."
+  },
+  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 x = resolveBoxPosition(args.x, "x") ?? source?.encoding?.x;
+    const y = resolveBoxPosition(args.y, "y") ?? source?.encoding?.y;
+    const whisker = resolveBoxWhisker(args.whisker);
+    const width = resolveBoxWidth(args.width);
+    if (args.outliers !== undefined && typeof args.outliers !== "boolean") {
+      throw new TypeError("createBoxPlot outliers must be a boolean.");
+    }
+    const box = resolveBoxAppearance(args.box);
+    const median = resolveBoxMedianAppearance(args.median);
+    const outlier = resolveBoxOutlierAppearance(args.outlier);
+    if (x !== undefined && y !== undefined && resolveBoxOrientation(x, y) === undefined) {
+      throw new Error(
+        "createBoxPlot requires one categorical axis and one quantitative axis."
+      );
+    }
+    const orientation = resolveBoxOrientation(x, y);
+    const category = orientation === "vertical" ? x : y;
+    const categoryScaleId = typeof category?.scale === "string"
+      ? category.scale
+      : category?.scale?.id;
+    const categoryScale = findSemanticScale(this, categoryScaleId);
+    let next = categoryScale?.type === "point"
+      ? this.editScale({ id: categoryScaleId, type: "band" })
+      : this;
+    next = next.createBarMark({ id, data })._withMarkConfig(id, {
+      boxPlot: {
+        whisker,
+        width,
+        outliers: args.outliers ?? true,
+        box,
+        median,
+        outlier
+      }
+    });
+    if (x !== undefined) {
+      next = next.encodeX({
+        ...boxEncodingArgs(x),
+        target: id,
+        coordinate: args.coordinate ?? source?.coordinate
+      });
+    }
+    if (y !== undefined) {
+      next = next.encodeY({
+        ...boxEncodingArgs(y),
+        target: id,
+        coordinate: args.coordinate ?? source?.coordinate
+      });
+    }
+    return next.materializeBoxPlot({ id });
+  }
+);

package/src/actions/boxPlots/index.js

@@ -0,0 +1,10 @@
+import { createBoxMedian, createBoxOutliers } from "./components.js";
+import { createBoxPlot } from "./create.js";
+import { materializeBoxPlot } from "./materialize.js";
+
+export function registerBoxPlotActions(ProgramClass) {
+  ProgramClass.prototype.createBoxPlot = createBoxPlot;
+  ProgramClass.prototype.materializeBoxPlot = materializeBoxPlot;
+  ProgramClass.prototype.createBoxMedian = createBoxMedian;
+  ProgramClass.prototype.createBoxOutliers = createBoxOutliers;
+}