@ggts-sh/skill 0.43.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Liam O'Dea
+
+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,80 @@
+# @ggts-sh/skill
+
+The ggts agent skill: `SKILL.md` plus deep-dive `references/` that teach a
+coding agent the shared grammar of graphics — TypeScript builders, React
+and Svelte components, PortableSpec JSON, and the `ggts check` /
+`ggts render` feedback loop.
+
+This package is the one published home of the skill. It versions in lock-step
+with [`@ggts-sh/spec`](https://www.npmjs.com/package/@ggts-sh/spec),
+[`@ggts-sh/core`](https://www.npmjs.com/package/@ggts-sh/core),
+[`@ggts-sh/compose`](https://www.npmjs.com/package/@ggts-sh/compose),
+[`@ggts-sh/react`](https://www.npmjs.com/package/@ggts-sh/react),
+[`@ggts-sh/svelte`](https://www.npmjs.com/package/@ggts-sh/svelte), and
+[`@ggts-sh/cli`](https://www.npmjs.com/package/@ggts-sh/cli): a given version
+number describes the spec, the renderers, and this skill as of the same
+release. Pin it like any other dependency and let dependabot (or
+npm-check-updates) tell you when the bundled skill in your repo is stale.
+
+## Install
+
+```sh
+npm install --save-dev --save-exact @ggts-sh/skill @ggts-sh/cli
+```
+
+The package root **is** the skill directory: `SKILL.md` sits next to this
+README. Skill loaders key off the frontmatter (`name: ggts`), not the
+directory name.
+
+## Use
+
+Point your agent at the skill, or copy/symlink it into your agent's skills
+directory under the name `ggts`:
+
+```sh
+# Claude Code
+cp -R node_modules/@ggts-sh/skill .claude/skills/ggts
+
+# pi
+cp -R node_modules/@ggts-sh/skill .pi/agent/skills/ggts
+
+# or reference it in place
+node_modules/@ggts-sh/skill/SKILL.md
+```
+
+Re-run the copy on every version bump (a two-line `postinstall` or a sync
+script works); the dependabot PR is the signal that the skill changed.
+
+The skill assumes the agent can also run
+[`@ggts-sh/cli`](https://www.npmjs.com/package/@ggts-sh/cli)
+(`ggts check` and `ggts render`) for spec validation and headless SVG rendering — install it
+in every sandbox where an agent authors specs.
+
+## Contents
+
+- `SKILL.md` — target selection, shared grammar, authoring workflow.
+- `references/react.md` and `references/svelte.md` — adapter instructions.
+- `references/` — geoms and stats, scales and palettes, themes, interactions,
+  composition surfaces, recipes.
+
+## Guarantees
+
+CI checks the teaching contracts and shipped examples:
+
+1. **Content contracts** (`scripts/skill-content/*.test.ts`,
+   `scripts/skill-package.test.ts`) — inventory completeness for every geom,
+   stat, position, theme, and color scheme; every complete JSON fence
+   normalizes and validates; pack shape and lock-step version. Packed-consumer
+   checks also compile complete TSX and Svelte examples from the installed skill.
+2. **Trigger / disclosure contracts** (`scripts/skill-trigger.test.ts`) —
+   frontmatter description quality (the loader's selection signal), balanced
+   positive/negative trigger fixtures under `evals/trigger-cases.json`,
+   relative-link integrity, and progressive disclosure of every `references/`
+   file from `SKILL.md`.
+3. **Held-out NL→spec evals** (`tests/evals/`, `bun run evals`) — model
+   capability on PortableSpec authoring with deterministic graders. These do
+   **not** load this skill today; agent-in-the-loop skill evals (with/without
+   skill A/B, multi-trial trigger accuracy) are tracked as follow-up work.
+
+`evals/trigger-cases.json` is not packed to npm (`files` is only `SKILL.md` +
+`references/`). It is the living seed for future skill-loaded agent evals.

package/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: ggts
+description: Build data visualizations with ggts, a grammar-of-graphics charting library (ggplot2 semantics, React and Svelte 5 components, TypeScript builders, JSON specs, headless SVG rendering). Use whenever creating, editing, validating, or debugging charts, plots, graphs, scatter plots, bar charts, histograms, line charts, boxplots, density plots, violins, heatmaps, maps, faceted/small-multiple charts, or data visualization in a JavaScript/TypeScript/React/Svelte project; when code imports from "@ggts-sh/react", "@ggts-sh/svelte", "@ggts-sh/spec", or "@ggts-sh/core"; when composing GGPlot with Geom*/Scale*/Theme*/Facet*/Coord*/Guide*/Labs children; when emitting a ggts plot spec JSON; or when rendering charts server-side/headless to SVG.
+---
+
+# ggts
+
+ggplot2’s layered grammar for TypeScript, with headless rendering and React
+and Svelte adapters. A chart spec carries the same grammar between surfaces.
+
+## Choose the target
+
+1. Follow the user’s explicit framework choice. Otherwise inspect the target
+   application’s package.json and imports. In a mixed monorepo, choose the
+   application before generating component code.
+2. For a sandbox or an unspecified framework, author PortableSpec JSON or use
+   the TypeScript builder; run the CLI before shipping the chart.
+3. For React, read [React](references/react.md). For Svelte, read
+   [Svelte](references/svelte.md). Keep framework callbacks and host-only
+   interactions in that adapter; PortableSpec holds the portable grammar.
+4. In every agent sandbox, install `@ggts-sh/cli` and `@ggts-sh/skill`
+   at matching local versions and keep the lockfile. Expose
+   the installed skill to the agent, refreshing any copied skill on upgrades.
+   Run `ggts check chart.json`, apply relevant diagnostics, then
+   `ggts render chart.json > chart.svg` and inspect the output. A local npm
+   install exposes these commands through `npm exec -- ggts`.
+
+## Registration (call these)
+
+The `@ggts-sh/core` barrel is side-effect-free. Call `registerAll()` once
+at startup for every agent-authored JSON, builder, `layers`, or `<GGPlot spec>`
+path. It installs the full grammar; both `ggts render` and `ggts check` do
+this for you. Missing opt-ins throw `not registered in this build` and name
+the required registration. `registerBasic()` alone is insufficient for
+specialty stats and Temporal.
+
+Framework geom children self-register their own geom and default stat;
+stat overrides still need the matching family. Spec-driven temporal options
+need `installTemporal()` or `registerAll()` because there is no Temporal child.
+Use the full default for agents. If the user requests a lean bundle, read the
+[registration reference](references/registration.md) for the exact family,
+color, theme, and headless entry-point rules before selecting imports.
+
+## Mental model
+
+**Everything that composes a plot is a layer in component composition.** Marks _and_ the
+seven grammar families (scale, theme, coord, facet, labs, guides, legend)
+register as `Layer` kinds via `createPlotLayer` / geom factories. Never call
+Scale/Theme/Guide/Labs/Coord/Facet/Legend “non-layers.”
+
+Two serializations of the same grammar:
+
+```text fragment
+# React / Svelte composition
+plot children = mark layers + grammar layers
+  mark    = Geom*  → Layer.kind "mark"
+  grammar = Scale* | Theme* | Coord* | Facet* | Labs | Guide* | Legend
+            → Layer.kind "scale"|"theme"|"coord"|"facet"|"labs"|"guides"|"legend"
+
+# PortableSpec JSON (agent / headless wire format)
+spec = data + aes + layers[]          # layers[] = MARKS ONLY
+       + scales? coord? facet? labs? theme? guides? legend?
+one mark layer = { geom, stat?, position?, positionParams?, aes?, params?, render?, data? }
+```
+
+PortableSpec puts grammar pieces in top-level keys because that is how the
+JSON schema folds them — **not** because they are outside the layer model.
+“Non-mark layer” / “grammar layer” is correct; “non-layer grammar component”
+is wrong and must never appear in issues, docs, or comments.
+
+- **data**: `{"values": [rows]}`, `{"columns": {name: [...]}}`, or
+  `{"name": "dataset"}` (resolved from `spec.datasets` or runtime data).
+- **mark `layers[]`** draw in order — later marks on top (z-order).
+- Geom defaults: bar → count+stack, histogram → bin+stack, col/area →
+  identity+stack, boxplot → boxplot+dodge, violin → ydensity+dodge,
+  jitter → point+jitter, freqpoly → bin, smooth → smooth, count → sum,
+  density → density, hex → bin_hex, everything else identity+identity.
+
+## Aes: JSON specs vs component props
+
+The one rule that differs between the two skins:
+
+| Surface                                     | `x: "displ"` bare string              | canonical                |
+| ------------------------------------------- | ------------------------------------- | ------------------------ |
+| JSON `PortableSpec` (incl. `spec` prop)     | INVALID                               | `{"field": "displ"}`     |
+| React / Svelte `aes` prop (plot or `Geom*`) | valid shorthand, expands to `{field}` | same object form also OK |
+
+Canonical channel forms: `{"field": "col"}` maps a column, `{"value": "red"}`
+is a constant, `{"stat": "count"}` reads a stat output, `null` unsets an
+inherited channel. Layer aes merges over plot aes per channel.
+Channels (25): x, y, color, fill, size, linewidth, alpha, shape, linetype,
+group, label, weight, ymin, ymax, xmin, xmax, xend, yend, width, height, z,
+map_id, angle, radius, sample. Mapped size/linewidth/alpha/shape/linetype work
+only on the geoms in `STYLE_AESTHETIC_GEOMS`.
+
+## The validation contract (use it!)
+
+`validate(spec)` = schema shape. `validate(spec, { profile })` adds data-aware
+checks against a `DataProfile` —
+`{"fields": [{"name": "displ", "type": "quantitative"}], "rowCount": 234}`
+(types: quantitative | temporal | ordinal | nominal). Every error is:
+
+```json fragment
+{
+  "code": "unknown-field",
+  "path": "/layers/0/aes/x",
+  "message": "Unknown field \"dsipl\" (available: displ, hwy). Did you mean \"displ\"?",
+  "allowed": ["displ", "hwy"],
+  "fix": {
+    "description": "Map \"x\" to \"displ\".",
+    "example": { "field": "displ" }
+  }
+}
+```
+
+**Errors include `fix.example` — apply it at `path` and re-validate.**
+`validate(spec, { lint: true })` additionally returns advisories for
+valid-but-questionable specs (line over unordered categories, >10 discrete
+colors, stacked negative areas, discrete×discrete scatter, transform-domain
+mixed-sign data, fractional calendar years on a linear scale); `lintSpec(spec)`
+is the standalone equivalent. Advisories never block; fix them when they match
+intent. `normalize(input)` canonicalizes
+authoring sugar into a `PortableSpec`; `isPortable`/`toPortable` check and
+strip runtime-only fields. CLIs: `ggts render spec.json > out.svg`
+(from `@ggts-sh/cli`; JSON-line diagnostics on stderr — exit 3 means
+validation errors, exit 0 with stderr output means quality warnings worth
+fixing) and `ggts-codemod [--write] src` (ships with `@ggts-sh/svelte`).
+
+**CLI coverage for interaction:** the CLI always covers PortableSpec validation,
+pipeline warnings/advisories, scale diagnostics (`source: "scale"`), and
+spec-lint (`source: "spec-lint"`). Host inspect **mode** is not a PortableSpec
+field — without intent the agent loop never sees inspect×geom bar/col guide
+codes such as `INTERACTION_INSPECT_X_ON_COL`. When the host will enable inspect,
+declare it:
+
+```sh fragment
+ggts render --inspect xy spec.json > out.svg
+# stderr: kind advisory|warning, source "interaction", bar/col x-guide codes
+```
+
+Modes match the host enum (`auto|exact|x|y|xy`). This path covers the pure
+bar/col axis-guide collectors only (same codes as host for that slice).
+High-cardinality discrete and runtime key/lineage/wiring diagnostics still
+require a mounted host's `ondiagnostic`.
+
+## Interactions (host props / children, not PortableSpec fields)
+
+Opt-in host capabilities: `<Inspect />` for tooltips and crosshairs;
+`select` / `zoom` on `<GGPlot>`; legend emphasis and data-changing filter via
+`<GuideLegend channel="color" focus />` / `filter` (per aesthetic; host-only,
+not in `guideLegend()` / PortableSpec). Row identity for selection, legend
+focus, and linked views **defaults** to an `id` column when present, else
+the row index (order-stable only) — ordinary charts omit custom identity.
+Override with `identity` on `<Inspect>`, object-form `select`, or
+`createPlotInteraction` when a non-`id` durable field or accessor is needed
+(for example `<Inspect identity="year" />`). Plot-level `key` is deprecated
+since 0.21. Link plots by sharing one `createPlotInteraction()` controller
+and matching `interactionScope` channels; observe everything through
+`oninteraction` or per-capability handlers.
+
+**Inspect mode and hit hygiene:** prefer `mode="auto"` when library auto matches
+the mark; pin `mode="exact"` (or leave auto) on violin, boxplot, and discrete-axis
+error bars — never freescrolling `x`/`y`/`xy` on those band geoms; use
+`x`/`y`/`xy` only for continuous shared-axis or free 2d hits; set
+`inspect={false}` on decorative layers in multi-layer stories. The CLI SVG
+loop cannot validate host inspect mode — hover/pin in a browser after edits.
+Read [references/interactions.md](references/interactions.md) (Choosing inspect
+mode, Multi-layer hit hygiene) before enabling Inspect or writing interactive
+or linked-view code.
+
+## Pointers
+
+- JSON Schema (constrained decoding): `packages/spec/schema/v0.json` in the
+  repo, `/schema/v0.json` on the docs site, or
+  `import schema from "@ggts-sh/spec/schema/v0.json"`.
+- Full corpus for models: `/llms-full.txt` on the docs site (all guide prose
+  plus every example with spec JSON and Svelte source); index at `/llms.txt`.
+- Error catalog: `/guide/errors`; advisories: `/guide/advisories`;
+  lifecycle/editions: `/guide/lifecycle` (specs are stamped with the current
+  appearance edition, currently 2). Upgrading off deprecated props:
+  `/guide/upgrading`.
+- References in this skill — read the one that matches the task:
+  [geoms-and-stats.md](references/geoms-and-stats.md) (any geom/stat/position
+  beyond the everyday set, annotations),
+  [scales-and-palettes.md](references/scales-and-palettes.md) (scale options,
+  palettes, temporal),
+  [themes.md](references/themes.md) (every product theme name, shells,
+  role overrides),
+  [composition-surfaces.md](references/composition-surfaces.md) (coords,
+  facets, guides, merge semantics),
+  [interactions.md](references/interactions.md) (tooltips, selection, linking),
+  [recipes.md](references/recipes.md) (long-tail chart recipes).
+  Registration calls live in the [registration reference](references/registration.md).
+
+- [Grammar and recipes](references/grammar.md): choose charts, scales, and themes;
+  the same recipes work in every adapter.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@ggts-sh/skill",
+  "version": "0.43.0",
+  "description": "Agent skill for the shared grammar of graphics: TypeScript, React, Svelte, portable JSON, and the ggts check/render feedback loop. Versions with all framework adapters.",
+  "keywords": [
+    "agent-skill",
+    "agents",
+    "charts",
+    "claude-code",
+    "dataviz",
+    "ggplot2",
+    "grammar-of-graphics",
+    "llm",
+    "plot",
+    "react",
+    "skill",
+    "svelte",
+    "typescript",
+    "visualization"
+  ],
+  "homepage": "https://ggts.sh/",
+  "bugs": "https://github.com/ggts-sh/ggts/issues",
+  "license": "MIT",
+  "author": "Liam O'Dea",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ggts-sh/ggts.git",
+    "directory": "packages/skill"
+  },
+  "files": [
+    "SKILL.md",
+    "references"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/references/composition-surfaces.md

@@ -0,0 +1,199 @@
+<!-- Source of truth: packages/svelte/src/lib/index.ts (component exports), packages/svelte/src/lib/plot-props.ts, packages/svelte/src/lib/layers/ (merge semantics, grammar-families). Theme roster lives in themes.md (asserted complete by scripts/skill-content/inventory.test.ts). -->
+
+# Composition surfaces: coords, facets, guides, labs
+
+Every surface here is a **grammar layer** (non-mark `Layer` kind). Each exists
+in three equivalent forms: a key in the JSON `PortableSpec`, a removed
+`<GGPlot>` prop (gone since 0.13.0; codemod rewrites old sources), and a
+declaration-only child component
+(canonical in Svelte). Child components emit no markup, register on init via
+`createPlotLayer` / `registerPlotLayer`, unregister on destroy, and are inert
+without a `<GGPlot>` ancestor.
+
+**Ontology:** scale, theme, coord, facet, labs, guides, and legend **are
+layers**. PortableSpec’s top-level `layers[]` array holds marks only; these
+families fold into sibling keys. That is wire format, not “not a layer.”
+
+## Themes
+
+Full product roster (37 names), shells, and role overrides:
+[themes.md](themes.md). Theme is a REPLACE family (last registration wins) —
+see replace-vs-merge below.
+
+## Coords
+
+Components: `Coord` (escape hatch, `value: CoordSpec | "flip"`), `CoordFlip`,
+`CoordCartesian`, `CoordTransform`, `CoordFixed`, `CoordEqual` (alias of
+`CoordFixed`), `CoordSf`, `CoordRadial`, `CoordPolar` (ggplot2 `coord_polar`
+alias shell — prefer `CoordRadial` for new work). `<CoordCartesian/>`
+registers `{"type":"cartesian"}`, which `normalize()` drops when bare — use
+it to clear an earlier coord under REPLACE. JSON forms:
+
+```json fragment
+"coord": {"type": "flip"}
+```
+
+```json fragment
+"coord": {
+  "type": "transform",
+  "x": {"transform": "log10", "limits": [1, 1000], "reverse": false, "expand": true},
+  "y": {"transform": "sqrt"},
+  "clip": true
+}
+```
+
+```json fragment
+"coord": {
+  "type": "radial",
+  "theta": "y",
+  "innerRadius": 0.4,
+  "expand": false
+}
+```
+
+- Coord transform runs AFTER stats and scale training (scale `transform` runs
+  before stats). It preserves stat inputs; coordinate `limits` are a viewport —
+  they never remove rows or recompute statistics. `expand` (default true) adds
+  a 5% display expansion to explicit limits; `clip` (default true) clips marks
+  to the panel.
+- Non-identity coordinate transforms require continuous, non-temporal
+  position scales on the transformed axes.
+- `{"type": "fixed", "ratio": 1}`: ratio is physical y-unit length divided by
+  physical x-unit length (default 1). Layout fits the largest centered data
+  rectangle after chart chrome. Fixed-aspect coords reject free positional
+  facet scales (`coord-fixed-free-scales` error).
+- `{"type": "sf"}` (`<CoordSf/>`): fixed-aspect coords for already-projected
+  map data; no CRS reprojection in v1. Accepts `ratio` like fixed.
+- `{"type": "radial", …}` (`<CoordRadial/>`, helpers `coordRadial` /
+  `coord_radial`): polar coordinates (ggplot2 `coord_radial`). Maps one
+  aesthetic to angle and the other to radius — pie, coxcomb, polar scatter.
+  Options: `theta` (`"x"` default | `"y"` for pie), `start` / `end` (radians
+  from 12 o'clock; default full circle), `innerRadius` (0–1 fraction, donut
+  hole), `expand` (default true; false for pie/coxcomb), `clip` (default
+  off), `reverse` (`"none"` | `"theta"` | `"r"` | `"thetar"`),
+  `thetaLimits` / `rLimits`. Full-circle panels use a square data rectangle.
+  Equivalent skins: JSON ≡ `coordRadial({…})` ≡ `.coordRadial({…})` ≡
+  `<CoordRadial …/>`.
+- `CoordPolar` / `coordPolar` / `coord_polar`: superseded ggplot2
+  `coord_polar` alias. Emits `{ type: "radial", clip: true, … }`;
+  `direction: -1` maps to `reverse: "theta"`. Prefer `<CoordRadial/>` for
+  partial arcs, inner radius, and reverse.
+
+## Facets
+
+Components: `Facet` (full `FacetInput` surface), `FacetWrap` (`field`,
+`ncol?`, `scales?`, `strip?`), `FacetGrid` (`rows?`, `cols?`, `scales?`,
+`strip?`). `field`/`rows`/`cols` accept a bare string or
+`{ field, levels?, labels? }` for authored panel order and strip text. Wrap
+form is mutually exclusive with rows/cols; a bare `<Facet/>` fails validate
+with `facet-form-missing`.
+
+```json fragment
+"facet": {"wrap": {"field": "region"}, "ncol": 3, "scales": "free_y",
+          "strip": {"position": "top", "show": true}}
+```
+
+- Panels partition the data BEFORE stats and positions run — each panel
+  computes its own counts, bins, and stacks.
+- `scales`: `"fixed"` (default — panels share both positional scales) |
+  `"free"` | `"free_x"` | `"free_y"`. Discrete color/fill assignments are
+  ALWAYS global (one legend), whatever `scales` says.
+- `strip`: `position` `"top"` (default) | `"bottom"` | `"left"` | `"right"`
+  (left/right strips take layout space rather than overlaying the panel);
+  `show` (default true) — set false when direct labels are authored elsewhere.
+
+## Guides, legend, labs
+
+Guides are keyed by aesthetic channel: `x`, `y`, `color`, `fill`, `size`,
+`linewidth`, `alpha`, `shape`, `linetype`. Components: `Guides`
+(escape hatch, `value: GuidesSpec`), plus one shell per guide type carrying a
+`channel` prop — `GuideAxis` (channels `x`/`y` only), `GuideLegend`,
+`GuideColorbar`, `GuideColorsteps` (non-position channels), `GuideNone` (any
+channel). `<GuideLegend channel="color" position="bottom"/>` assembles
+`guides: {"color": {"type": "legend", "position": "bottom"}}`.
+
+- Top-level `guides` override a scale-local `guide`.
+- Shared options: `title`, `theme` (bounded size/gap overrides), `collision`;
+  non-position guides add integer `order` (placement rank), `position`
+  `"auto"|"right"|"bottom"`, `direction` `"auto"|"vertical"|"horizontal"`,
+  and `force` (show a guide suppressed by default, e.g. identity scales).
+- Responsive rule: `auto`-positioned non-position guides move below the panel
+  when the viewport is 480px wide or less, or when a right guide would leave
+  under 320px of panel (after an estimated 80px of other chrome).
+- `<Legend order="stable-domain"|"present-first-seen"|"sorted"/>` is the
+  plot-wide legend ENTRY-SORT enum (default `stable-domain`; ordering never
+  changes color assignments). Distinct from `<GuideLegend order={2}/>`, a
+  per-aesthetic integer placement rank — same word, unrelated concepts.
+- `Labs` takes flat string props: `title`, `subtitle`, `caption`, `x`, `y`,
+  `color`, `fill`, `size`, `linewidth`, `alpha`, `shape`, `linetype`. The
+  spec type is re-exported from `@ggts-sh/svelte` as `LabsSpec`.
+
+```svelte fragment
+<GGPlot
+  data={rows}
+  aes={{ x: "cat", y: "val", fill: "group" }}
+  layers={[{ geom: "col" }]}
+>
+  <CoordFlip />
+  <FacetWrap field="region" ncol={2} />
+  <ThemeMinimal />
+  <Labs title="Sales by category" x="Category" y="Sales" />
+  <GuideLegend channel="fill" position="bottom" />
+  <Legend order="sorted" />
+</GGPlot>
+```
+
+Equivalent complete JSON spec:
+
+```json complete
+{
+  "data": {
+    "values": [
+      { "cat": "a", "val": 3, "group": "g1", "region": "west" },
+      { "cat": "b", "val": 5, "group": "g2", "region": "west" },
+      { "cat": "a", "val": 2, "group": "g1", "region": "east" },
+      { "cat": "b", "val": 4, "group": "g2", "region": "east" }
+    ]
+  },
+  "layers": [
+    {
+      "geom": "col",
+      "aes": {
+        "x": { "field": "cat" },
+        "y": { "field": "val" },
+        "fill": { "field": "group" }
+      }
+    }
+  ],
+  "coord": { "type": "flip" },
+  "facet": { "wrap": { "field": "region" }, "ncol": 2 },
+  "theme": "minimal",
+  "labs": { "title": "Sales by category", "x": "Category", "y": "Sales" },
+  "guides": { "fill": { "type": "legend", "position": "bottom" } },
+  "legend": { "order": "sorted" }
+}
+```
+
+## Replace-vs-merge semantics (child layers)
+
+- The `spec` prop wins over everything — when set, all other props and all
+  children are ignored.
+- Mark layers: the `layers` prop, when set, is used INSTEAD of geom children.
+  Otherwise geom children register in document order, and registration order
+  is z-order (first = bottom).
+- Grammar (non-mark) families fold onto the builder in registration order —
+  later siblings beat earlier ones.
+- REPLACE families — `coord`, `facet`, `theme`: the last registration fully
+  replaces earlier ones (and any matching prop). Two or more children of one
+  kind emit a `DUPLICATE_PLOT_LAYER` advisory.
+- Scales merge per-channel; two scale children configuring the same channel
+  emit `DUPLICATE_SCALE_CHANNEL` (note British/American spellings write the
+  same channel: `<ScaleColorDiscrete/>` and `<ScaleColourContinuous/>` both
+  configure `color`).
+- `labs`, `guides`, `legend` are keyed-MERGE families: siblings touching
+  different keys all survive; a colliding key emits `DUPLICATE_MERGE_KEY` and
+  the later child's value wins. The value at a key is replaced whole — a
+  guide child never field-merges into another guide object for that channel.
+- All three advisory codes arrive through `ondiagnostic` with severity
+  `"advisory"`; the chart still renders.
+- Grammar children emit no markup and are inert without a `<GGPlot>` ancestor.