ggaction 0.0.8 → 0.0.10

package/knowledge/extension-authoring.md

@@ -0,0 +1,248 @@
+# Extension Authoring Knowledge
+
+## Purpose and authority
+
+This is the compact, installed guide for LLM agents that build extension
+packages against this copy of ggaction. It is ordinary package knowledge, not
+an `AGENTS.md` file, so an extension repository must explicitly tell its agent
+to read it.
+
+Use the version in [`package.json`](../package.json) as the compatibility
+baseline. For exact current behavior, the installed runtime and declarations
+take precedence over this guide. Do not substitute behavior from the mutable
+GitHub default branch, a roadmap, or a different installed version.
+
+## Minimum intake
+
+Before proposing or implementing an extension action:
+
+1. Read [`types/extension.d.ts`](../types/extension.d.ts) and
+   [`src/extension.js`](../src/extension.js) to confirm the installed public
+   extension entry point.
+2. Search [`action-cards.json`](./action-cards.json) for actions whose names,
+   intents, owned resources, or prerequisites overlap the requested feature.
+   Read only relevant cards instead of loading the complete catalog into the
+   working context.
+3. Inspect the installed declaration and source for each reuse candidate when
+   the action card does not settle a signature, default, error, ownership, or
+   interaction question.
+4. Record in the extension specification which ggaction actions are reused,
+   which domain behavior remains new, and the installed ggaction version used
+   for that decision.
+
+[`task-resolver.js`](./task-resolver.js) may help decompose a concrete chart
+request into current built-in actions. Its result is chart-authoring guidance,
+not authority for extension APIs or unsupported core behavior.
+
+## Design from the feature, then the actions
+
+Start with the visualization the extension must make possible and its accepted
+data. Derive action boundaries only after that feature contract is clear.
+
+- Reuse a current public action when it already owns the required behavior.
+- Compose public domain actions for existing chart resources instead of
+  recreating their scale, guide, layout, mark, transform, or renderer logic.
+- Add an extension action only for domain behavior that current actions cannot
+  express coherently.
+- Use extension primitives only inside a domain action that owns the resulting
+  semantic and graphical lifecycle. Primitives are not a replacement chart
+  authoring surface.
+- Never call private helpers or internal wrapped actions from an extension.
+- Require an explicit resource ID when existing state does not identify one
+  unique dataset, mark, scale, coordinate, guide, or graphic.
+
+## Freeze the executable design before code
+
+Before implementation, record one complete vertical slice in the extension
+specification:
+
+- the accepted input forms, canonical domain representation, and deterministic
+  conversions between them;
+- the shortest complete public program that demonstrates the feature;
+- an ordered action hierarchy that distinguishes reused public actions from new
+  extension actions and records conditional children;
+- the canonical owner of every semantic value, derived resource, and graphic;
+  and
+- the expected create, repeat, edit, remove, data-change, and relevant
+  Canvas/scale lifecycle.
+
+Do not begin dependent implementation while the slice still requires an
+unresolved core primitive, renderer capability, semantic path, ownership rule,
+or composition mechanism. Keep that requirement as an explicit upstream
+decision instead of inventing a local substitute.
+
+## Composition and ownership
+
+A high-level extension action must call a reusable public action when that
+action owns the required validation, inference, state, or materialization. Do
+not flatten an action hierarchy into copied validators, name matching, or
+parallel state updates. The parent should remain thin and its meaningful child
+calls should appear in deterministic trace order.
+
+Give each capability one canonical resolver and one canonical state owner.
+Store requested, inferred, and default values where downstream consumers can
+trace them; do not duplicate the same semantic fact in several resources.
+Omitted targets may resolve only from an explicit current owner or one unique
+compatible owner. Missing and ambiguous ownership are different errors, and
+neither permits selecting the first candidate.
+
+Type-checking an action hierarchy is not runtime closure. Exercise the complete
+program with representative data so that every prerequisite, target, derived
+resource, guide, and renderer route is real and connected.
+
+## Core model
+
+- `ChartProgram` is immutable. Return a new program and preserve earlier
+  programs and caller-owned input.
+- `semanticSpec` records chart meaning. Fully materialized, backend-neutral
+  `graphicSpec` records concrete output.
+- A semantic edit does not compile into graphics automatically. The owning
+  domain action must invoke every graphical operation required by its semantic
+  change.
+- Renderers consume `graphicSpec`; extension state must not contain
+  renderer-specific objects or commands.
+- A user-visible extension action should form one meaningful trace subtree.
+  Lower-level wrapped calls belong beneath it.
+
+## Lifecycle and atomic failure
+
+Validate a normalized complete candidate and every affected downstream
+consumer before returning the first changed program. A rejected action must
+preserve the earlier program, trace, semantic and graphic state, caller-owned
+options, and source rows.
+
+When a supported semantic revision changes graphical output, the owning action
+must rebind every affected consumer, rematerialize each required resource once,
+and remove only resources that are truly orphaned. Repeated calls must not
+accumulate geometry, duplicate resources, or revive state removed by an earlier
+action. Removal must clear owned semantic, graphic, guide, selection, highlight,
+and convenience context that would otherwise become stale.
+
+If the public extension boundary cannot express a required rebind,
+rematerialization, or safe release, stop at the upstream decision boundary.
+Do not reproduce private lifecycle machinery inside the extension.
+
+## Primitive oracle and visual acceptance
+
+For new visual behavior, first build one readable primitive baseline. Reuse
+existing public data, mark, encoding, scale, guide, layout, and renderer actions;
+use extension primitives only for the behavior that is genuinely missing.
+Keep pure geometry or statistical expectations in an independent literal
+oracle rather than copying the production implementation.
+
+The final public extension program and its primitive baseline must converge on
+the same semantic result, concrete `graphicSpec`, drawing order, and applicable
+renderer calls. For one representative contract, compare decoded pixels when
+the renderer permits deterministic raster evidence. A renderer completing
+without throwing is not sufficient: also assert item cardinality, finite
+geometry, topology, bounds, clipping, and value-to-geometry invariants.
+
+When a feature introduces a new appearance or layout, treat representative
+visual review as a separate acceptance gate. Structural tests cannot decide
+whether spacing, alignment, hierarchy, or readability matches the intended
+visual contract.
+
+## Current action-authoring boundary
+
+Import `action` and `registerExtension` from `ggaction/extension`. An installable
+extension package defines all methods with `action()` and calls
+`registerExtension({ name, actions })` once when its entry module is imported.
+The package must mark that entry as a side effect so bundlers preserve the
+registration import.
+
+Registration adds actions only to the complete `chart()` program from
+`ggaction`; it never changes `ggaction/basic`. Each action key must equal the
+wrapped action's `op`. Extension names, built-in and internal program names, and
+previously registered action names cannot collide. The complete action map is
+validated before any method is installed, and non-conflicting extension
+packages must work in either import order.
+
+Every wrapped action:
+
+- has a stable, non-empty `op` and `description`;
+- accepts one plain options object;
+- runs with the entered immutable program as `this`;
+- returns an instance of the same `ChartProgram` subclass; and
+- leaves a successful result with an empty action stack.
+
+For strict TypeScript, augment `RegisteredExtensionActions` in the
+`ggaction/extension` module with each property typed as its exact wrapped action.
+Confirm the exact generic and return types in the installed
+[`types/extension.d.ts`](../types/extension.d.ts) instead of copying a signature
+from another version.
+
+`ChartProgram` remains available for deliberately isolated local subclasses.
+Do not mutate its shared prototype directly; installable packages use
+`registerExtension()` so registration is checked and composable.
+
+The low-level primitives available through `ChartProgram` are:
+
+- `editSemantic` for a supported semantic path;
+- `createGraphics` for backend-neutral graphic identity and hierarchy; and
+- `editGraphics` for concrete graphic values or removal.
+
+Use the installed declarations and validation behavior to determine supported
+paths, graphic types, properties, and values. Do not invent opaque semantic
+branches, graphic properties, renderer instructions, or automatic
+materialization.
+
+## Upstream decision boundary
+
+Stop extension implementation and propose a ggaction core change when the
+feature requires any of the following:
+
+- a semantic path or persisted value the installed core rejects;
+- a new shared graphic primitive or renderer capability;
+- access to a private or internal action;
+- a change to immutable state, trace, materialization, or renderer boundaries;
+- a change to the public extension registration or composition mechanism; or
+- behavior that would be duplicated inconsistently across extensions.
+
+Keep that core proposal separate from the extension implementation. Do not hide
+the missing core contract behind monkey-patching, source-relative imports,
+renderer-specific state, or copied internal code.
+
+## LLM working discipline
+
+- Read the installed compact knowledge needed for the current feature; do not
+  preload complete documentation or copy rules from historical roadmaps.
+- When using the task resolver, submit only the exact user request. Do not add
+  dataset contents or code scaffolding to the query.
+- Make specifications and examples executable without guesswork: include exact
+  public imports, program construction, data and Canvas prerequisites,
+  immutable chaining or reassignment, and the requested renderer call.
+- Treat a known unsupported capability as terminal. Keep a decision that needs
+  user input or a bounded reference read explicitly unresolved; never hide
+  either case behind a nearby action or silent partial output.
+- Keep failure feedback bounded and actionable. Preserve the original failure
+  category while reporting the smallest public correction path.
+
+## Required evidence
+
+For each new public extension action, verify at least:
+
+- the public package entry works from an installed-package consumer;
+- importing the package registers every declared action on `chart()` but not
+  `ggaction/basic`;
+- registration rejects collisions and invalid batches without partial changes,
+  and non-conflicting packages work in either import order;
+- strict TypeScript sees the exact registered action methods through
+  `RegisteredExtensionActions`;
+- earlier programs and caller-owned input remain unchanged;
+- semantic and graphic state match the feature specification;
+- the trace has the intended root action and wrapped children;
+- the shortest valid call, boundary values, empty or missing input, invalid
+  input, ambiguity, repeated calls, supported lifecycle changes, and recovery
+  after failure behave explicitly;
+- semantic revisions leave no stale binding, graphic, guide, context, or
+  duplicate resource;
+- a primitive baseline and public extension program satisfy their declared
+  semantic, graphic, order, renderer-call, and representative visual parity;
+- failures are deterministic and explain how to correct invalid or ambiguous
+  input; and
+- representative rendering succeeds in every renderer the extension claims to
+  support.
+
+Keep the extension specification, implementation, declarations, package
+exports, tests, examples, and user documentation synchronized as one
+user-facing change.

package/knowledge/intent-taxonomy.json

@@ -0,0 +1,183 @@
+{
+  "schemaVersion": 2,
+  "constraints": [
+    { "id": "program.canvas", "phrases": ["chart canvas", "create canvas", "plot bounds"] },
+    { "id": "program.data", "phrases": ["create dataset", "load rows", "inline data"] },
+
+    { "id": "chart.scatter", "phrases": ["scatter plot", "scatter chart", "point chart"] },
+    { "id": "chart.line", "phrases": ["line chart", "line plot", "time series chart"] },
+    { "id": "chart.bar", "phrases": ["bar chart", "bar plot", "column chart"] },
+    { "id": "chart.histogram", "phrases": ["histogram", "binned distribution", "frequency distribution", "frequency histogram"] },
+    { "id": "chart.heatmap", "phrases": ["heatmap", "heat map", "two dimensional distribution"] },
+    { "id": "chart.parallel", "phrases": ["parallel coordinates", "parallel coordinate plot"] },
+    { "id": "chart.box", "phrases": ["box plot", "boxplot", "quartile plot"] },
+    { "id": "chart.violin", "phrases": ["violin plot", "violin chart"] },
+    { "id": "chart.gradient", "phrases": ["gradient plot", "density gradient"] },
+    { "id": "chart.density", "phrases": ["density plot", "density curve", "kernel density plot"] },
+
+    { "id": "mark.point", "phrases": ["point mark", "circle marks"] },
+    { "id": "mark.tick", "phrases": ["tick mark", "tick plot", "strip plot"] },
+    { "id": "mark.text", "phrases": ["text mark", "data labels"] },
+    { "id": "mark.line", "phrases": ["line mark", "path mark"] },
+    { "id": "mark.bar", "phrases": ["bar mark", "rectangle bars"] },
+    { "id": "mark.area", "phrases": ["area mark", "filled area"] },
+    { "id": "mark.rule", "phrases": ["rule mark", "reference line mark"], "shadows": ["mark.line"] },
+    { "id": "mark.arc", "phrases": ["arc mark", "polar sectors"] },
+    { "id": "mark.rect", "phrases": ["rect mark", "rectangle cells"] },
+
+    { "id": "transform.filter", "phrases": ["filter data", "filtered dataset", "filter rows"] },
+    { "id": "transform.density", "phrases": ["density data", "kde data", "kernel density data"] },
+    { "id": "transform.regression", "phrases": ["regression data", "fitted rows", "loess data"] },
+    { "id": "transform.window", "phrases": ["moving average", "moving mean", "window transform", "rank rows", "lag values"] },
+    { "id": "transform.timeUnit", "phrases": ["time unit", "date bucket", "month bucket", "year bucket"] },
+    { "id": "transform.bin1d", "phrases": ["bin one field", "one dimensional bins", "histogram bins"] },
+    { "id": "transform.bin2d", "phrases": ["bin two fields", "two dimensional bins", "rectangular bins", "binned heatmap"] },
+    { "id": "transform.interval", "phrases": ["interval data", "confidence interval data", "summary interval"] },
+
+    { "id": "statistics.regression", "phrases": ["regression line", "trend line", "fitted line", "regression fit", "best fit line", "fitted trend"] },
+    { "id": "statistics.errorBar", "phrases": ["error bars", "error bar"] },
+    { "id": "statistics.errorBand", "phrases": ["error band", "uncertainty ribbon", "confidence band"] },
+
+    { "id": "scale.create", "phrases": ["create scale", "named scale", "custom scale"] },
+    { "id": "scale.log", "phrases": ["log scale", "logarithmic scale"] },
+    { "id": "scale.time", "phrases": ["time scale", "temporal scale"] },
+    { "id": "scale.color", "phrases": ["color scale", "colour scale", "palette scale"] },
+
+    { "id": "encoding.x", "phrases": ["x encoding", "encode x", "map to x"] },
+    { "id": "encoding.y", "phrases": ["y encoding", "encode y", "map to y"] },
+    { "id": "encoding.color", "phrases": ["color encoding", "encode color", "map to color", "color legend", "colour legend"] },
+    { "id": "encoding.size", "phrases": ["size encoding", "encode size", "map to size"] },
+    { "id": "encoding.shape", "phrases": ["shape encoding", "encode shape", "map to shape"] },
+    { "id": "encoding.angle", "phrases": ["angle encoding", "encode angle", "rotate ticks", "rotate points"] },
+    { "id": "encoding.opacity", "phrases": ["opacity encoding", "encode opacity", "map to opacity"] },
+    { "id": "encoding.strokeDash", "phrases": ["stroke dash encoding", "dash encoding", "line style encoding"] },
+    { "id": "encoding.strokeWidth", "phrases": ["stroke width encoding", "encode stroke width", "line width encoding"] },
+    { "id": "encoding.text", "phrases": ["text encoding", "encode text", "label field"] },
+    { "id": "encoding.group", "phrases": ["group encoding", "group series", "series grouping"] },
+    { "id": "encoding.theta", "phrases": ["theta encoding", "angular encoding", "encode theta"] },
+    { "id": "encoding.radius", "phrases": ["radius encoding", "radial encoding", "encode radius"] },
+    { "id": "encoding.parallel", "phrases": ["parallel dimensions", "dimension axes"] },
+
+    { "id": "guide.all", "phrases": ["create guides", "automatic guides", "all guides"] },
+    { "id": "guide.axes", "phrases": ["axes", "axis guides", "x and y axes"] },
+    { "id": "guide.xAxis", "phrases": ["x axis", "horizontal axis"] },
+    { "id": "guide.yAxis", "phrases": ["y axis", "vertical axis"] },
+    { "id": "guide.legend", "phrases": ["legend", "encoding key"] },
+    { "id": "guide.grid", "phrases": ["grid lines", "chart grid", "reference grid"] },
+    { "id": "guide.title", "phrases": ["chart title", "add title", "title and subtitle"] },
+    { "id": "guide.subtitle", "phrases": ["subtitle", "title and subtitle"] },
+
+    { "id": "layout.legend.bottom", "phrases": ["legend at bottom", "bottom legend"], "exclusiveGroup": "legend.position" },
+    { "id": "layout.legend.top", "phrases": ["legend at top", "top legend"], "exclusiveGroup": "legend.position" },
+    { "id": "layout.legend.left", "phrases": ["legend at left", "left legend"], "exclusiveGroup": "legend.position" },
+    { "id": "layout.legend.right", "phrases": ["legend at right", "right legend"], "exclusiveGroup": "legend.position" },
+    { "id": "layout.labels", "phrases": ["avoid label overlap", "label collision", "layout labels"] },
+    { "id": "layout.jitter", "phrases": ["jitter points", "point jitter", "reduce overplotting"] },
+    { "id": "layout.categoryOrder", "phrases": ["order categories", "sort categories", "category order"] },
+    { "id": "layout.facet", "phrases": ["facet chart", "small multiples", "repeat chart by field"] },
+
+    { "id": "selection.store", "phrases": ["store selection", "reusable selection", "select marks"] },
+    { "id": "selection.highlight", "phrases": ["highlight marks", "highlight selected", "conditional highlight"] },
+    { "id": "selection.filter", "phrases": ["filter marks", "retain matching marks"] },
+
+    { "id": "composition.horizontal", "phrases": ["horizontal concat", "horizontally concatenate", "charts side by side"] },
+    { "id": "composition.vertical", "phrases": ["vertical concat", "vertically concatenate", "stack charts vertically"] },
+
+    { "id": "renderer.canvas", "phrases": ["render to canvas", "browser canvas", "canvas renderer", "on canvas", "on the chart canvas"] },
+    { "id": "renderer.svg", "phrases": ["render svg", "export svg", "svg output", "as svg", "vector svg", "svg document"] },
+    { "id": "renderer.png", "phrases": ["render png", "export png", "png output", "as png"] },
+    { "id": "renderer.pdf", "phrases": ["render pdf", "export pdf", "pdf output", "as pdf", "vector pdf", "pdf document"] },
+
+    { "id": "unsupported.geo", "phrases": ["map chart", "geographic chart", "geo projection", "choropleth"], "unsupported": "Geographic projections and map marks are outside the current ggaction contract." },
+    { "id": "unsupported.animation", "phrases": ["animate chart", "chart animation", "animated transition"], "unsupported": "Animation is outside the current static-chart contract." },
+    { "id": "unsupported.interaction", "phrases": ["interactive tooltip", "zoom interaction", "pan interaction", "brush interaction"], "unsupported": "Interactive runtime behaviors are outside the current static-chart contract." },
+    { "id": "unsupported.3d", "phrases": ["3d chart", "three dimensional chart", "three dimensional plot"], "unsupported": "Three-dimensional charts are not supported." },
+    { "id": "unsupported.jpg", "phrases": ["export jpg", "render jpeg", "jpeg output", "jpeg image", "jpg image"], "unsupported": "JPEG is not a current renderer; use SVG, PNG, PDF, or Browser Canvas." }
+  ],
+  "providers": [
+    { "id": "action.createCanvas", "kind": "action", "name": "createCanvas", "order": 10, "anchors": ["program.canvas"], "covers": ["program.canvas"], "baseOptions": {} },
+    { "id": "action.createData", "kind": "action", "name": "createData", "order": 20, "anchors": ["program.data"], "covers": ["program.data"], "baseOptions": { "values": "[{ category: \"A\", x: 1, y: 2, value: 3 }]" } },
+
+    { "id": "action.createScatterPlot", "kind": "action", "name": "createScatterPlot", "order": 40, "anchors": ["chart.scatter"], "covers": ["chart.scatter", "encoding.x", "encoding.y", "encoding.color", "encoding.size", "encoding.shape", "guide.axes", "guide.legend"], "baseOptions": { "x": "\"x\"", "y": "\"y\"" }, "optionsByConstraint": { "encoding.color": { "color": "\"category\"" }, "encoding.size": { "size": "\"value\"" }, "encoding.shape": { "shape": "\"category\"" }, "guide.axes": { "guides": "{}" }, "guide.legend": { "guides": "{ legend: {} }" } } },
+    { "id": "action.createLinePlot", "kind": "action", "name": "createLinePlot", "order": 40, "anchors": ["chart.line"], "covers": ["chart.line", "encoding.x", "encoding.y", "encoding.color", "encoding.group", "encoding.strokeDash", "guide.axes", "guide.legend"], "baseOptions": { "x": "\"x\"", "y": "\"y\"" }, "optionsByConstraint": { "encoding.color": { "color": "\"category\"" }, "encoding.group": { "groupBy": "\"category\"" }, "encoding.strokeDash": { "strokeDash": "{ field: \"category\" }" }, "guide.axes": { "guides": "{}" }, "guide.legend": { "guides": "{ legend: {} }" } } },
+    { "id": "action.createBarPlot", "kind": "action", "name": "createBarPlot", "order": 40, "anchors": ["chart.bar"], "covers": ["chart.bar", "encoding.x", "encoding.y", "encoding.color", "guide.axes", "guide.legend"], "baseOptions": { "x": "\"category\"", "y": "\"value\"" }, "optionsByConstraint": { "encoding.color": { "color": "\"category\"" }, "guide.axes": { "guides": "{}" }, "guide.legend": { "guides": "{ legend: {} }" } } },
+    { "id": "action.createHistogram", "kind": "action", "name": "createHistogram", "order": 40, "anchors": ["chart.histogram"], "covers": ["chart.histogram", "transform.bin1d", "encoding.color", "guide.axes", "guide.legend"], "baseOptions": { "field": "\"value\"" }, "optionsByConstraint": { "encoding.color": { "color": "\"category\"" }, "guide.axes": { "guides": "{}" }, "guide.legend": { "guides": "{ legend: {} }" } } },
+    { "id": "action.createHeatmap", "kind": "action", "name": "createHeatmap", "order": 40, "anchors": ["chart.heatmap"], "covers": ["chart.heatmap", "transform.bin2d", "encoding.x", "encoding.y", "encoding.color", "guide.axes", "guide.legend"], "baseOptions": { "x": "\"x\"", "y": "\"y\"", "bin": "{}" }, "optionsByConstraint": { "encoding.color": { "color": "{}" }, "guide.axes": { "guides": "{}" }, "guide.legend": { "guides": "{ legend: {} }" } } },
+    { "id": "action.createParallelCoordinates", "kind": "action", "name": "createParallelCoordinates", "order": 40, "anchors": ["chart.parallel"], "covers": ["chart.parallel", "encoding.parallel", "encoding.color", "encoding.strokeDash", "guide.axes", "guide.legend"], "baseOptions": { "dimensions": "[\"a\", \"b\"]" }, "optionsByConstraint": { "encoding.color": { "color": "\"category\"" }, "encoding.strokeDash": { "strokeDash": "{ field: \"category\" }" }, "guide.axes": { "guides": "{}" }, "guide.legend": { "guides": "{ legend: {} }" } } },
+    { "id": "action.createBoxPlot", "kind": "action", "name": "createBoxPlot", "order": 40, "anchors": ["chart.box"], "covers": ["chart.box", "guide.axes"], "baseOptions": {}, "optionsByConstraint": { "guide.axes": { "guides": "{}" } } },
+    { "id": "action.createViolinPlot", "kind": "action", "name": "createViolinPlot", "order": 40, "anchors": ["chart.violin"], "covers": ["chart.violin", "encoding.color", "guide.axes", "guide.legend"], "baseOptions": { "x": "\"category\"", "y": "\"value\"" }, "optionsByConstraint": { "encoding.color": { "color": "\"category\"" }, "guide.axes": { "guides": "{}" }, "guide.legend": { "guides": "{ legend: {} }" } } },
+    { "id": "action.createGradientPlot", "kind": "action", "name": "createGradientPlot", "order": 40, "anchors": ["chart.gradient"], "covers": ["chart.gradient", "guide.axes"], "baseOptions": {}, "optionsByConstraint": { "guide.axes": { "guides": "{}" } } },
+    { "id": "action.encodeDensity", "kind": "action", "name": "encodeDensity", "order": 50, "anchors": ["chart.density"], "covers": ["chart.density"], "baseOptions": { "field": "\"value\"" } },
+
+    { "id": "action.createPointMark", "kind": "action", "name": "createPointMark", "order": 40, "anchors": ["mark.point"], "covers": ["mark.point"], "baseOptions": {} },
+    { "id": "action.createTickMark", "kind": "action", "name": "createTickMark", "order": 40, "anchors": ["mark.tick"], "covers": ["mark.tick"], "baseOptions": {} },
+    { "id": "action.createTextMark", "kind": "action", "name": "createTextMark", "order": 40, "anchors": ["mark.text"], "covers": ["mark.text"], "baseOptions": {} },
+    { "id": "action.createLineMark", "kind": "action", "name": "createLineMark", "order": 40, "anchors": ["mark.line"], "covers": ["mark.line"], "baseOptions": {} },
+    { "id": "action.createBarMark", "kind": "action", "name": "createBarMark", "order": 40, "anchors": ["mark.bar"], "covers": ["mark.bar"], "baseOptions": {} },
+    { "id": "action.createAreaMark", "kind": "action", "name": "createAreaMark", "order": 40, "anchors": ["mark.area"], "covers": ["mark.area"], "baseOptions": {} },
+    { "id": "action.createRuleMark", "kind": "action", "name": "createRuleMark", "order": 40, "anchors": ["mark.rule"], "covers": ["mark.rule"], "baseOptions": {} },
+    { "id": "action.createArcMark", "kind": "action", "name": "createArcMark", "order": 40, "anchors": ["mark.arc"], "covers": ["mark.arc"], "baseOptions": {} },
+    { "id": "action.createRectMark", "kind": "action", "name": "createRectMark", "order": 40, "anchors": ["mark.rect"], "covers": ["mark.rect"], "baseOptions": {} },
+
+    { "id": "action.filterData", "kind": "action", "name": "filterData", "order": 30, "anchors": ["transform.filter"], "covers": ["transform.filter"], "baseOptions": { "id": "\"filtered\"", "field": "\"value\"", "predicate": "{ op: \"gt\", value: 0 }" } },
+    { "id": "action.createDensityData", "kind": "action", "name": "createDensityData", "order": 30, "anchors": ["transform.density"], "covers": ["transform.density"], "baseOptions": { "id": "\"density\"", "field": "\"value\"" } },
+    { "id": "action.createRegressionData", "kind": "action", "name": "createRegressionData", "order": 30, "anchors": ["transform.regression"], "covers": ["transform.regression"], "baseOptions": { "id": "\"regression\"", "x": "\"x\"", "y": "\"y\"" } },
+    { "id": "action.createWindowData", "kind": "action", "name": "createWindowData", "order": 30, "anchors": ["transform.window"], "covers": ["transform.window"], "baseOptions": { "id": "\"windowed\"", "operations": "[{ op: \"movingMean\", field: \"value\", as: \"movingMean\", frame: { preceding: 2 } }]" } },
+    { "id": "action.createTimeUnitData", "kind": "action", "name": "createTimeUnitData", "order": 30, "anchors": ["transform.timeUnit"], "covers": ["transform.timeUnit"], "baseOptions": { "id": "\"monthly\"", "field": "\"date\"", "unit": "\"month\"", "as": "\"month\"" } },
+    { "id": "action.encodeHistogram", "kind": "action", "name": "encodeHistogram", "order": 50, "anchors": ["transform.bin1d"], "covers": ["transform.bin1d"], "baseOptions": { "field": "\"value\"" } },
+    { "id": "action.createBin2DData", "kind": "action", "name": "createBin2DData", "order": 30, "anchors": ["transform.bin2d"], "covers": ["transform.bin2d"], "baseOptions": { "id": "\"bins\"", "x": "\"x\"", "y": "\"y\"" } },
+    { "id": "action.createIntervalData", "kind": "action", "name": "createIntervalData", "order": 30, "anchors": ["transform.interval"], "covers": ["transform.interval"], "baseOptions": { "id": "\"interval\"", "field": "\"value\"" } },
+
+    { "id": "action.createRegression", "kind": "action", "name": "createRegression", "order": 60, "anchors": ["statistics.regression"], "covers": ["mark.line", "transform.regression", "statistics.regression", "statistics.errorBand"], "baseOptions": {} },
+    { "id": "action.createErrorBar", "kind": "action", "name": "createErrorBar", "order": 60, "anchors": ["statistics.errorBar"], "covers": ["statistics.errorBar"], "baseOptions": {} },
+    { "id": "action.createErrorBand", "kind": "action", "name": "createErrorBand", "order": 61, "anchors": ["statistics.errorBand"], "covers": ["statistics.errorBand"], "baseOptions": {} },
+
+    { "id": "action.createScale", "kind": "action", "name": "createScale", "order": 35, "anchors": ["scale.create"], "covers": ["scale.create"], "baseOptions": { "id": "\"scale-1\"" } },
+    { "id": "action.createLogScale", "kind": "action", "name": "createScale", "order": 35, "anchors": ["scale.log"], "covers": ["scale.log"], "baseOptions": { "id": "\"scale-1\"", "type": "\"log\"" } },
+    { "id": "action.createTimeScale", "kind": "action", "name": "createScale", "order": 35, "anchors": ["scale.time"], "covers": ["scale.time"], "baseOptions": { "id": "\"scale-1\"", "type": "\"time\"" } },
+    { "id": "action.createColorScale", "kind": "action", "name": "createScale", "order": 35, "anchors": ["scale.color"], "covers": ["scale.color"], "baseOptions": { "id": "\"color-scale\"", "type": "\"ordinal\"", "range": "{ palette: \"tableau10\" }" } },
+
+    { "id": "action.encodeX", "kind": "action", "name": "encodeX", "order": 50, "anchors": ["encoding.x"], "covers": ["encoding.x"], "baseOptions": { "field": "\"x\"" } },
+    { "id": "action.encodeY", "kind": "action", "name": "encodeY", "order": 50, "anchors": ["encoding.y"], "covers": ["encoding.y"], "baseOptions": { "field": "\"y\"" } },
+    { "id": "action.encodeColor", "kind": "action", "name": "encodeColor", "order": 55, "anchors": ["encoding.color"], "covers": ["encoding.color"], "baseOptions": { "field": "\"category\"" } },
+    { "id": "action.encodeSize", "kind": "action", "name": "encodeSize", "order": 55, "anchors": ["encoding.size"], "covers": ["encoding.size"], "baseOptions": { "field": "\"value\"" } },
+    { "id": "action.encodeShape", "kind": "action", "name": "encodeShape", "order": 55, "anchors": ["encoding.shape"], "covers": ["encoding.shape"], "baseOptions": { "field": "\"category\"" } },
+    { "id": "action.encodeAngle", "kind": "action", "name": "encodeAngle", "order": 55, "anchors": ["encoding.angle"], "covers": ["encoding.angle"], "baseOptions": { "value": "45" } },
+    { "id": "action.encodeOpacity", "kind": "action", "name": "encodeOpacity", "order": 55, "anchors": ["encoding.opacity"], "covers": ["encoding.opacity"], "baseOptions": { "field": "\"value\"" } },
+    { "id": "action.encodeStrokeDash", "kind": "action", "name": "encodeStrokeDash", "order": 55, "anchors": ["encoding.strokeDash"], "covers": ["encoding.strokeDash"], "baseOptions": { "field": "\"category\"" } },
+    { "id": "action.encodeStrokeWidth", "kind": "action", "name": "encodeStrokeWidth", "order": 55, "anchors": ["encoding.strokeWidth"], "covers": ["encoding.strokeWidth"], "baseOptions": { "value": "2" } },
+    { "id": "action.encodeText", "kind": "action", "name": "encodeText", "order": 55, "anchors": ["encoding.text"], "covers": ["encoding.text"], "baseOptions": { "field": "\"label\"" } },
+    { "id": "action.encodeGroup", "kind": "action", "name": "encodeGroup", "order": 52, "anchors": ["encoding.group"], "covers": ["encoding.group"], "baseOptions": { "field": "\"category\"" } },
+    { "id": "action.encodeTheta", "kind": "action", "name": "encodeTheta", "order": 50, "anchors": ["encoding.theta"], "covers": ["encoding.theta"], "baseOptions": { "field": "\"angle\"" } },
+    { "id": "action.encodeR", "kind": "action", "name": "encodeR", "order": 50, "anchors": ["encoding.radius"], "covers": ["encoding.radius"], "baseOptions": { "field": "\"value\"" } },
+    { "id": "action.encodeParallelCoordinates", "kind": "action", "name": "encodeParallelCoordinates", "order": 50, "anchors": ["encoding.parallel"], "covers": ["encoding.parallel"], "baseOptions": { "dimensions": "[\"a\", \"b\"]" } },
+
+    { "id": "action.createGuides", "kind": "action", "name": "createGuides", "order": 70, "anchors": ["guide.all"], "covers": ["guide.all", "guide.axes", "guide.legend", "guide.grid"], "baseOptions": {} },
+    { "id": "action.createAxes", "kind": "action", "name": "createAxes", "order": 70, "anchors": ["guide.axes"], "covers": ["guide.axes"], "baseOptions": {} },
+    { "id": "action.createXAxis", "kind": "action", "name": "createXAxis", "order": 70, "anchors": ["guide.xAxis"], "covers": ["guide.xAxis"], "baseOptions": {} },
+    { "id": "action.createYAxis", "kind": "action", "name": "createYAxis", "order": 70, "anchors": ["guide.yAxis"], "covers": ["guide.yAxis"], "baseOptions": {} },
+    { "id": "action.createLegend", "kind": "action", "name": "createLegend", "order": 70, "anchors": ["guide.legend"], "covers": ["guide.legend"], "baseOptions": {} },
+    { "id": "action.createGrid", "kind": "action", "name": "createGrid", "order": 70, "anchors": ["guide.grid"], "covers": ["guide.grid"], "baseOptions": {} },
+    { "id": "action.createTitle", "kind": "action", "name": "createTitle", "order": 70, "anchors": ["guide.title", "guide.subtitle"], "covers": ["guide.title", "guide.subtitle"], "baseOptions": { "text": "\"Chart title\"" }, "optionsByConstraint": { "guide.subtitle": { "subtitle": "\"Chart subtitle\"" } } },
+
+    { "id": "action.legendBottom", "kind": "action", "name": "editLegendLayout", "order": 80, "anchors": ["layout.legend.bottom"], "covers": ["layout.legend.bottom"], "baseOptions": { "position": "\"bottom\"" } },
+    { "id": "action.legendTop", "kind": "action", "name": "editLegendLayout", "order": 80, "anchors": ["layout.legend.top"], "covers": ["layout.legend.top"], "baseOptions": { "position": "\"top\"" } },
+    { "id": "action.legendLeft", "kind": "action", "name": "editLegendLayout", "order": 80, "anchors": ["layout.legend.left"], "covers": ["layout.legend.left"], "baseOptions": { "position": "\"left\"" } },
+    { "id": "action.legendRight", "kind": "action", "name": "editLegendLayout", "order": 80, "anchors": ["layout.legend.right"], "covers": ["layout.legend.right"], "baseOptions": { "position": "\"right\"" } },
+    { "id": "action.layoutLabels", "kind": "action", "name": "layoutLabels", "order": 80, "anchors": ["layout.labels"], "covers": ["layout.labels"], "baseOptions": { "axis": "\"y\"" } },
+    { "id": "action.jitterPoints", "kind": "action", "name": "jitterPoints", "order": 80, "anchors": ["layout.jitter"], "covers": ["layout.jitter"], "baseOptions": { "channel": "\"x\"", "maxOffset": "{ pixels: 4 }" } },
+    { "id": "action.orderCategories", "kind": "action", "name": "orderCategories", "order": 80, "anchors": ["layout.categoryOrder"], "covers": ["layout.categoryOrder"], "baseOptions": { "channel": "\"x\"", "by": "\"category\"" } },
+    { "id": "action.facet", "kind": "action", "name": "facet", "order": 80, "anchors": ["layout.facet"], "covers": ["layout.facet", "guide.axes", "guide.legend"], "baseOptions": { "field": "\"category\"" }, "optionsByConstraint": { "guide.axes": { "guides": "{ axes: \"outer\", legend: \"shared\" }" }, "guide.legend": { "guides": "{ axes: \"outer\", legend: \"shared\" }" } } },
+
+    { "id": "action.selectMarks", "kind": "action", "name": "selectMarks", "order": 75, "anchors": ["selection.store"], "covers": ["selection.store"], "baseOptions": { "id": "\"selection-1\"", "field": "\"category\"", "op": "\"eq\"", "value": "\"A\"" } },
+    { "id": "action.highlightMarks", "kind": "action", "name": "highlightMarks", "order": 76, "anchors": ["selection.highlight"], "covers": ["selection.highlight"], "baseOptions": { "select": "{ field: \"category\", op: \"eq\", value: \"A\" }", "color": "\"#f28e2b\"" } },
+    { "id": "action.filterMarks", "kind": "action", "name": "filterMarks", "order": 75, "anchors": ["selection.filter"], "covers": ["selection.filter"], "baseOptions": { "field": "\"value\"", "op": "\"gt\"", "value": "0" } },
+
+    { "id": "runtime.hconcat", "kind": "runtime", "name": "hconcat", "order": 90, "anchors": ["composition.horizontal"], "covers": ["composition.horizontal"], "signature": "hconcat(options: CompositionOptions): ChartProgram;", "call": "hconcat({ programs: [program, program] })", "route": "/reference/runtime/#ggaction" },
+    { "id": "runtime.vconcat", "kind": "runtime", "name": "vconcat", "order": 90, "anchors": ["composition.vertical"], "covers": ["composition.vertical"], "signature": "vconcat(options: CompositionOptions): ChartProgram;", "call": "vconcat({ programs: [program, program] })", "route": "/reference/runtime/#ggaction" },
+    { "id": "runtime.render", "kind": "runtime", "name": "render", "order": 100, "anchors": ["renderer.canvas"], "covers": ["renderer.canvas"], "signature": "render(program: Pick<ChartProgram, \"graphicSpec\">, context: CanvasRenderingContext2D, options?: { pixelRatio?: number }): void;", "call": "render(program, context)", "route": "/reference/runtime/#ggaction" },
+    { "id": "runtime.renderToSVG", "kind": "runtime", "name": "renderToSVG", "order": 100, "anchors": ["renderer.svg"], "covers": ["renderer.svg"], "signature": "renderToSVG(program: Pick<ChartProgram, \"graphicSpec\">, options?: SVGRenderOptions): string;", "call": "renderToSVG(program)", "route": "/reference/runtime/#ggactionsvg" },
+    { "id": "runtime.renderToPNG", "kind": "runtime", "name": "renderToPNG", "order": 100, "anchors": ["renderer.png"], "covers": ["renderer.png"], "signature": "renderToPNG(program: Pick<ChartProgram, \"graphicSpec\">, options: { output: string; pixelRatio?: number }): Promise<PNGRenderResult>;", "call": "await renderToPNG(program, { output: \"chart.png\" })", "route": "/reference/runtime/#ggactionpng" },
+    { "id": "runtime.renderToPDF", "kind": "runtime", "name": "renderToPDF", "order": 100, "anchors": ["renderer.pdf"], "covers": ["renderer.pdf"], "signature": "renderToPDF(program: Pick<ChartProgram, \"graphicSpec\">, options: PDFRenderOptions): Promise<PDFRenderResult>;", "call": "await renderToPDF(program, { output: \"chart.pdf\" })", "route": "/reference/runtime/#ggactionpdf" }
+  ]
+}

package/knowledge/mcp-resources.json

@@ -0,0 +1,95 @@
+{
+  "schemaVersion": 2,
+  "overview": {
+    "title": "ggaction compact authoring overview",
+    "text": "Use search_ggaction once with only the exact user chart request; do not append dataset contents or code scaffolding. The result contains exact authoring imports, chart() initialization, non-duplicated createCanvas and createData prerequisites, immutable executable steps with deterministic runtime dependencies closed, ordered actionPlan entries, exactCalls, required option names, canonical routes, terminal unsupported constraints, and open unresolved decisions. Do not preload the full documentation. Read an action card when one exact action needs more detail. Read only the resource URIs attached to unresolved entries; unsupported entries are terminal and require no documentation read. The server is read-only and never executes chart code."
+  },
+  "recipes": [
+    {
+      "id": "scatter-svg",
+      "title": "Scatterplot with a bottom color legend and SVG output",
+      "summary": "Selects the chart facade, legend layout action, and browser-safe SVG renderer in execution order.",
+      "query": "scatter plot with a color legend at bottom as svg"
+    },
+    {
+      "id": "moving-average-line-png",
+      "title": "Moving-average line chart as PNG",
+      "summary": "Combines a window transform, line facade, guides, and the Node PNG renderer.",
+      "query": "moving average line chart with axes and export png"
+    },
+    {
+      "id": "binned-heatmap",
+      "title": "Binned heatmap with guides",
+      "summary": "Uses the heatmap facade to own 2D binning, position, color, axes, and legend requirements.",
+      "query": "binned heatmap with color legend and axes"
+    },
+    {
+      "id": "regression-scatterplot",
+      "title": "Scatterplot with a regression layer",
+      "summary": "Builds the scatterplot before adding the statistical regression layer.",
+      "query": "scatter plot with a regression line"
+    },
+    {
+      "id": "selection-highlight",
+      "title": "Stored selection and highlight",
+      "summary": "Stores a named mark selection before applying a graphical highlight to that selection.",
+      "query": "store selection then highlight marks"
+    },
+    {
+      "id": "parallel-svg",
+      "title": "Styled parallel coordinates as SVG",
+      "summary": "Combines parallel coordinates, color and dash encodings, guides, and SVG output.",
+      "query": "parallel coordinates with color encoding, stroke dash encoding, axes, and legend as svg"
+    },
+    {
+      "id": "facet-shared-guides",
+      "title": "Small multiples with shared guides",
+      "summary": "Uses the facet action as the owner of the small-multiple layout and shared guides.",
+      "query": "small multiples with shared legend and axes"
+    },
+    {
+      "id": "horizontal-composition-svg",
+      "title": "Horizontal chart composition as SVG",
+      "summary": "Composes complete programs horizontally before serializing the parent program to SVG.",
+      "query": "put charts side by side and export svg"
+    }
+  ],
+  "docs": [
+    {
+      "id": "choose-chart-type",
+      "title": "Choose a chart or mark type",
+      "route": "/api/basic-charts/",
+      "text": "# Choose a chart or mark type\n\nName the intended chart or mark. Common complete chart facades are `createScatterPlot`, `createLinePlot`, `createBarPlot`, `createHistogram`, and `createHeatmap`. For lower-level authoring, choose a mark such as point, line, area, bar, rect, rule, tick, text, or arc, then add its required position encodings. Run `search_ggaction` again with the chosen chart type."
+    },
+    {
+      "id": "choose-renderer",
+      "title": "Choose an output renderer",
+      "route": "/api/rendering/",
+      "text": "# Choose an output renderer\n\nUse `render(program, context)` for Browser Canvas, `renderToSVG(program)` for a browser-safe SVG string, `renderToPNG(program, output)` for Node PNG output, or `renderToPDF(program, output)` for a single-page vector PDF. Run `search_ggaction` again with one explicit format. JPEG output is not currently supported."
+    },
+    {
+      "id": "legend-layout",
+      "title": "Resolve legend layout requirements",
+      "route": "/api/legends/",
+      "text": "# Resolve legend layout requirements\n\nA single legend resource can occupy one position at a time. Choose `top`, `bottom`, `left`, or `right`, or give distinct legends explicit IDs and edit each target separately. Run `search_ggaction` again with one position per legend."
+    },
+    {
+      "id": "unsupported-capabilities",
+      "title": "Current static-chart limitations",
+      "route": "/supported-features/",
+      "text": "# Current static-chart limitations\n\nThe current authoring contract does not provide geographic maps, animation, interactive event handling, 3D charts, or JPEG rendering. The compact resolver reports these requirements explicitly instead of substituting a different chart. Consult the supported-features route before redesigning the task with current static actions."
+    },
+    {
+      "id": "getting-started",
+      "title": "Clarify an unrecognized authoring request",
+      "route": "/getting-started/",
+      "text": "# Clarify an authoring request\n\nDescribe the chart or mark, its data/transform needs, position and appearance encodings, guides or layout, and output format in one request. Exact action names are also accepted. Example: `scatter plot with x and y, a bottom color legend, and SVG output`."
+    },
+    {
+      "id": "action-reference",
+      "title": "Resolve a current action gap",
+      "route": "/reference/actions/",
+      "text": "# Resolve a current action gap\n\nUse the complete action reference only for a constraint that the compact resolver recognized but could not cover. Confirm the exact action signature, required resource ID, and supported options, then rerun `search_ggaction` with the exact action name and complete task request."
+    }
+  ]
+}