semiotic 3.4.1 → 3.5.0

package/CLAUDE.md

@@ -2,7 +2,7 @@
 
 ## Quick Start
 - Install: `npm install semiotic`
-- **Use sub-path imports** — `semiotic/xy` (78KB gz), `semiotic/ordinal` (65KB), `semiotic/network` (54KB), `semiotic/geo` (53KB), `semiotic/realtime` (77KB), `semiotic/server` (58KB), `semiotic/utils` (19KB), `semiotic/themes` (3KB), `semiotic/data` (3KB). Full `semiotic` is 158KB gz.
+- **Use sub-path imports** — `semiotic/xy` (77KB gz), `semiotic/ordinal` (64KB), `semiotic/network` (51KB), `semiotic/geo` (49KB), `semiotic/realtime` (84KB), `semiotic/server` (64KB), `semiotic/recipes` (4KB), `semiotic/utils` (20KB), `semiotic/themes` (4KB), `semiotic/data` (3KB). Full `semiotic` is 165KB gz.
 - CLI: `npx semiotic-ai [--schema|--compact|--examples|--doctor]`
 - MCP: `npx semiotic-mcp`
 
@@ -20,9 +20,9 @@
 
 ## XY Charts (`semiotic/xy`)
 
-**LineChart** — `data`, `xAccessor` ("x"), `yAccessor` ("y"), `lineBy`, `lineDataAccessor`, `colorBy`, `colorScheme`, `curve`, `lineWidth` (2), `showPoints`, `pointRadius` (3), `fillArea` (boolean|string[]), `areaOpacity` (0.3), `lineGradient`, `anomaly`, `forecast`, `directLabel`, `gapStrategy`, `xScaleType`/`yScaleType` ("linear"|"log"|"time")
-**AreaChart** — LineChart props + `areaBy`, `y0Accessor`, `gradientFill`, `areaOpacity` (0.7), `showLine` (true)
-**StackedAreaChart** — flat array + `areaBy` (required), `colorBy`, `normalize`. No `lineBy`/`lineDataAccessor`.
+**LineChart** — `data`, `xAccessor` ("x"), `yAccessor` ("y"), `lineBy`, `lineDataAccessor`, `colorBy`, `colorScheme`, `curve`, `lineWidth` (2), `showPoints`, `pointRadius` (3), `fillArea` (boolean|string[]), `areaOpacity` (0.3), `lineGradient`, `anomaly`, `forecast`, `directLabel`, `gapStrategy`, `xScaleType`/`yScaleType` ("linear"|"log"|"time"), `tooltip="multi"` for hover-anywhere series comparison
+**AreaChart** — LineChart props + `areaBy`, `y0Accessor`, `gradientFill`, `areaOpacity` (0.7), `showLine` (true), `tooltip="multi"` for hover-anywhere area comparison
+**StackedAreaChart** — flat array + `areaBy` (required), `colorBy`, `normalize`, `baseline` (`"zero"` default | `"wiggle"` for streamgraph | `"silhouette"` for centered), `stackOrder` (`"key"` default alpha | `"insideOut"` largest-in-middle | `"asc"`/`"desc"` by total). For canonical streamgraph aesthetic: `baseline="wiggle"` + `stackOrder="insideOut"` puts the largest series in the middle as a central anchor with smaller series wrapping outward. `baseline` is mutually exclusive with `normalize`. No `lineBy`/`lineDataAccessor`. Pass `tooltip="multi"` for hover-anywhere mode: a single tooltip lists every stacked series at the hovered x, with values interpolated between rendered path samples.
 **Scatterplot** — `data`, `xAccessor`, `yAccessor`, `colorBy`, `sizeBy`, `sizeRange`, `pointRadius` (5), `pointOpacity` (0.8), `marginalGraphics`
 **BubbleChart** — Scatterplot + `sizeBy` (required), `sizeRange` ([5,40])
 **ConnectedScatterplot** — + `orderAccessor`
@@ -101,6 +101,88 @@ ref.current.getScales()                            // returns {o, r, projection}
 `remove()` and `update()` require an ID accessor: `pointIdAccessor` on XY/realtime charts, `dataIdAccessor` on ordinal charts. `replace()` is ordinal-only and routes through a bounded-ingest path that preserves category insertion-order memory and the transition position snapshot — what aggregator HOCs like LikertChart use under the hood to re-aggregate streaming input without shuffling categories or losing animations. Network HOC refs also use `remove(id)`/`update(id, updater)` (operates on nodes). For edge-level operations, use `StreamNetworkFrameHandle` directly: `removeNode(id)`, `removeEdge(sourceId, targetId)` or `removeEdge(edgeId)` (requires `edgeIdAccessor`), `updateNode(id, updater)`, `updateEdge(sourceId, targetId, updater)`.
 Not supported: Tree, Treemap, CirclePack, Orbit, ChoroplethMap, FlowMap, ScatterplotMatrix.
 
+## Custom Charts (escape hatch)
+
+When the catalog doesn't fit, three HOCs let you supply a layout function that emits scene primitives directly. The frame still owns hit testing, transitions, decay, theme cascade, and SSR — your layout owns geometry only.
+
+- **`XYCustomChart`** (`semiotic/xy`) — XY layouts: waffle, calendar heatmap, custom point/line/area arrangements
+- **`OrdinalCustomChart`** (`semiotic/ordinal`) — category × value layouts: marimekko, parallel coordinates, bullet, fan chart, slope graph
+- **`NetworkCustomChart`** (`semiotic/network`) — graph layouts: flextree, dagre, custom force/radial
+
+All three accept `layout` and `layoutConfig` (your own typed config), but the layout context and return shape differ by chart family:
+
+- **`XYCustomChart` / `OrdinalCustomChart`** — `layout: (ctx) => { nodes, overlays? }`. Context exposes `data`, `scales`, `dimensions` (with plot rect — center-anchored for radial ordinal, top-left otherwise), `theme` (semantic + categorical), `resolveColor(key)`, and `config`. XY scales: `{ x, y }` (linear). Ordinal scales: `{ o, r, projection }` (band + linear).
+- **`NetworkCustomChart`** — `layout: (ctx) => { sceneNodes?, sceneEdges?, labels?, overlays? }`. Context exposes `nodes`, `edges`, `dimensions`, `theme`, `resolveColor(key)`, and `config` — graph data, no `data`/`scales`. Network layouts often run an external positioner (`d3-flextree`, `dagre`) on nodes/edges, then emit network scene primitives (`circle`, `rect`, `arc` for nodes; `line`, `bezier`, `curved` for edges).
+
+XY/ordinal frames render whatever you put in `nodes` (rect, point, area, line, wedge, connector, etc.). Network frames split node-shaped scenes from edge-shaped scenes — give them `sceneNodes` for the round/rect/arc visuals and `sceneEdges` for the connecting paths. All three frames handle painting, hit testing, accessibility, transitions, decay, and SSR for you.
+
+```tsx
+import { XYCustomChart } from "semiotic/xy"
+import { OrdinalCustomChart } from "semiotic/ordinal"
+import { NetworkCustomChart } from "semiotic/network"
+import {
+  waffleLayout, calendarLayout,           // XY recipes
+  marimekkoLayout, bulletLayout, parallelCoordinatesLayout, // ordinal
+  flextreeLayout, dagreLayout,             // network
+} from "semiotic/recipes"
+
+<XYCustomChart data={cells} layout={waffleLayout} layoutConfig={{ rows: 10, columns: 10, ... }} />
+<OrdinalCustomChart data={revenue} layout={marimekkoLayout} layoutConfig={{ ... }} />
+<NetworkCustomChart nodes={nodes} edges={edges} layout={flextreeLayout} layoutConfig={{ ... }} />
+```
+
+**Recipes subpath** (`semiotic/recipes`, 4KB gz) ships pure layout functions. They emit standard SceneNodes — no chart code. BYO heavy deps (`d3-flextree`, `dagre`) live in user code.
+
+### Chrome (labels, axes, legends): the recipe owns it
+
+Custom layouts often need chrome the standard chart axes can't render — variable-width bars, per-row independent value scales, parallel axes, asymmetric tree branches. The unified pattern: **the recipe emits its own labels/axes/ticks via the `overlays` return field** (a ReactNode painted on top of the canvas). Built-in axes (via `showAxes` on the HOC) work for layouts that respect the standard scale; everything else, the recipe handles itself.
+
+Convention across shipped recipes — every recipe takes a consistent set of label/axis toggles in `layoutConfig`:
+
+| Recipe | Toggle | Default | What it draws |
+|---|---|---|---|
+| `marimekkoLayout` | `showCategoryLabels` | `true` | Category names under each variable-width bar |
+| `bulletLayout` | `showLabels` | `true` | Metric name to the left of each row |
+| `bulletLayout` | `showTicks` | `true` | Per-row value-axis ticks (each row independently scaled) |
+| `parallelCoordinatesLayout` | `showAxes` | `true` | Vertical axis line + field name + 5 ticks per axis |
+| `flextreeLayout` / `dagreLayout` | `showLabels` | `true` | Node text rendered inside each rect |
+| `waffleLayout` / `calendarLayout` | — | — | No chrome needed (uniform grid + cell color tells the story) |
+
+Writing your own recipe: prefer `showXxx` boolean toggles for chrome opt-out, `xxxFormat` callbacks for custom number/string formatting, and reserve plot-rect padding (`labelWidth`, `labelPadding`, `axisLabelPadding`) when chrome eats space.
+
+### Interaction (hover, brush, selection): the parent component owns it
+
+Recipes are pure functions, so they can't carry interactive state (hover, brush ranges, selection). The pattern: recipes accept a **predicate prop** (e.g. `parallelCoordinatesLayout`'s `highlightFn?: (d) => boolean`) and the parent component manages state. Wire `onObservation` (`{ type: "hover" | "hover-end" | ... }`) on `OrdinalCustomChart` / `XYCustomChart` / `NetworkCustomChart` to update parent state, then feed a derived predicate back into `layoutConfig`. Matching rows render at full opacity; non-matching dim. Highlighted rows z-order on top so neighbors don't cover them.
+
+```tsx
+const [hovered, setHovered] = useState(null)
+<OrdinalCustomChart
+  data={rows}
+  layout={parallelCoordinatesLayout}
+  layoutConfig={{
+    fields: ["mpg", "hp", "weight"],
+    highlightFn: hovered ? (d) => d.name === hovered : undefined,
+  }}
+  onObservation={(obs) => {
+    if (obs.type === "hover") setHovered(obs.datum?.data?.name ?? obs.datum?.name)
+    else if (obs.type === "hover-end") setHovered(null)
+  }}
+/>
+```
+
+The same predicate hook is the integration point for richer interactions on the roadmap: a future `<ParallelCoordinatesBrushes>` overlay that drag-brushes per-axis ranges, and `useBrushSelection`-style linked brushing across coordinated charts (selection store would carry per-field range constraints, downstream charts consume them via the same hook).
+
+### Built-in chrome works when the layout uses standard scales
+
+Layouts that draw *within* the frame's standard scales can just use the HOC's chrome. Pass `showAxes` on `XYCustomChart` / `OrdinalCustomChart` and the frame will render the same x/y or o/r axes the built-in HOCs do — useful for custom XY layouts that overlay points/lines on regular axes. The recipe-managed chrome is for the cases where standard axes can't help (variable-width bars under a band scale, per-row independent scales, etc.).
+
+**Notes:**
+- Coords are plot-relative (the frame translates the canvas/SVG group by `margin`). Read `ctx.dimensions.plot` for the drawing rect. Radial ordinal projection is the one exception: `plot.x = -width/2`, `plot.y = -height/2` because the canvas ctx is center-translated.
+- Layouts that need axis domains: pass `xExtent`/`yExtent` (XY) or `oExtent`/`rExtent` (ordinal) — those flow through scale construction *before* the layout runs.
+- Streaming layouts: ingest data via the chart's ref (`push`/`pushMany`); the layout re-runs on each ingest. Custom overlays update on data-change paths, NOT on per-frame animation rebuilds (intentional — would force a React re-render per frame).
+- Custom layouts own their colors. Always prefer `ctx.resolveColor(key)` over hardcoded literals so `ThemeProvider` / `colorScheme` flow through. `CategoryColorProvider` integration is XY-only; for cross-chart category sync on network/ordinal customLayouts, pass a matching `colorScheme` to each chart.
+- Tooltips: emit datum keys that match the user-visible accessor names (e.g. when `categoryAccessor: "region"` and `valueAccessor: "revenue"` are passed, put `region` and `revenue` on each rect's `datum`). The default tooltip looks them up by accessor name and the user's custom tooltip will read whatever fields they expect. Avoid underscored synthetic keys — the default tooltip filters those out.
+
 ## Coordinated Views
 
 **LinkedCharts** — `selections`, **CategoryColorProvider** — `colors`|`categories` + `colorScheme`
@@ -137,9 +219,9 @@ Server SVGs include `role="img"`, `<title>`, `<desc>`, grid, legend, annotations
 - **GroupedBarChart** — `data`, `categoryAccessor`, `valueAccessor`, `groupBy` (required).
 - **PieChart/DonutChart** — `data`, `categoryAccessor`, `valueAccessor`.
 - **FunnelChart** — `data`, `stepAccessor` ("step"), `valueAccessor` ("value"). Renders with trapezoid connectors, no axes.
-- **GaugeChart** — `value`, `thresholds` (array of `{value, color, label}`). Optional: `min`, `max`, `sweep`, `arcWidth`.
+- **GaugeChart** — `value`. Optional: `thresholds` (array of `{value, color, label}`), `min`, `max`, `sweep`, `arcWidth`.
 - **SwimlaneChart** — `data`, `categoryAccessor`, `subcategoryAccessor` (required), `valueAccessor`.
-- **ForceDirectedGraph** — `edges` (required). `nodes` optional (inferred from edges).
+- **ForceDirectedGraph** — `nodes`, `edges` (both required). If deriving nodes from edge endpoints, materialize `nodes` before returning JSX/renderChart props.
 - **SankeyDiagram** — `edges` (required), `valueAccessor`.
 - **ChoroplethMap** — `areas` (GeoJSON features, pre-resolved).
 
@@ -165,7 +247,7 @@ CSS custom properties: `--semiotic-bg`, `--semiotic-text`, `--semiotic-text-seco
 <ThemeProvider theme={{ mode: "dark", colors: { categorical: [...] } }}> {/* Merge onto dark base */}
 ```
 
-**Color priority** (with `colorBy`): explicit `colorScheme` > ThemeProvider `colors.categorical` > `"category10"`.
+**Color priority** (with `colorBy`): CategoryColorProvider/LinkedCharts category map > explicit `colorScheme` fallback > ThemeProvider `colors.categorical` > `"category10"`.
 Presets: `light`, `dark`, `high-contrast`, `pastels`(-dark), `bi-tool`(-dark), `italian`(-dark), `tufte`(-dark), `journalist`(-dark), `playful`(-dark), `carbon`(-dark).
 Serialization: `themeToCSS(theme, selector)`, `themeToTokens(theme)`, `resolveThemePreset(name)`.
 
@@ -182,11 +264,34 @@ Canvas scene builders read CSS variables via `getComputedStyle` on the canvas DO
 ## AI Features
 `onObservation`/`useChartObserver`, `toConfig`/`fromConfig`/`toURL`/`fromURL`/`copyConfig`/`configToJSX`, `validateProps(component, props)`, `diagnoseConfig(component, props)`, `exportChart(div, { format })`, `npx semiotic-ai --doctor`
 
+
+## AI Behavior Contracts
+
+<!-- semiotic-behavior-contracts:start -->
+
+These rules are generated from `ai/behaviorContracts.cjs` and are consumed by `semiotic-ai --doctor`, MCP resources, and docs checks.
+
+- **Data required by usage mode** (`props.data-required-by-usage-mode`): Static usage (`renderChart`, MCP previews, SSR snapshots, and copy/paste examples with immediate data) requires data in props. React push mode selects live ingestion by omitting data and mutating through a ref.
+  Agent action: Pass usageMode="push" to `semiotic-ai --doctor` when validating ref-based JSX with no data prop. Keep usageMode="static" or omit it for renderChart/MCP/static configs where data must be present.
+- **Categorical color precedence** (`color.category-precedence`): When colorBy is set, CategoryColorProvider/LinkedCharts category maps win for mapped categories. Unmapped categories fall back to explicit colorScheme, then ThemeProvider colors.categorical, then the built-in categorical fallback.
+  Agent action: Use colorBy for categorical encodings. Use CategoryColorProvider or LinkedCharts for cross-chart consistency, colorScheme for per-chart fallback palettes, and avoid frameProps style functions unless intentionally bypassing HOC color resolution.
+- **Required prop combinations** (`props.required-combinations`): Some chart families need semantic props beyond data. These combinations are enforced by validation/schema for static configs and remain required in push mode unless explicitly noted.
+  Agent action: Before returning code, check the selected component against the required combinations list. For push mode, omit data but keep semantic props such as areaBy, sizeBy, stackBy, and groupBy.
+  Required combinations: StackedAreaChart: static data + areaBy; push areaBy. Stacked areas need a flat data array plus areaBy to identify the stacked series. BubbleChart: static data + sizeBy; push sizeBy. Bubbles need sizeBy in addition to x/y accessors so radius encodes data rather than a constant point size. StackedBarChart: static data + stackBy; push stackBy. Stacked bars need stackBy to split each category into stack segments. GroupedBarChart: static data + groupBy; push groupBy. Grouped bars need groupBy to split each category into side-by-side bars. SwimlaneChart: static data + subcategoryAccessor; push subcategoryAccessor. Swimlanes need subcategoryAccessor; colorBy defaults to the same field when not provided. GaugeChart: static value; push not supported. GaugeChart is value-only. thresholds, min, max, sweep, and arcWidth are optional. ForceDirectedGraph: static nodes + edges; push nodes + edges. ForceDirectedGraph schema/rendering requires nodes and edges. If an agent infers nodes from edge endpoints, it must materialize a nodes array before returning code.
+- **Push mode omits data** (`streaming.push-mode-data`): HOC push mode is selected by omitting the data prop entirely. Passing data={[]} is static empty data and can clear/reinitialize the frame on render.
+  Agent action: For live charts, create a ref, omit data, then call ref.current.push() or pushMany(). For static renderChart/MCP snapshots, provide data because renderChart cannot push later.
+- **Ref mutations need stable IDs** (`streaming.ref-mutations-require-id-accessors`): push() and pushMany() can append without IDs, but remove(id) and update(id, updater) require a stable ID accessor: pointIdAccessor for XY/realtime charts, dataIdAccessor for ordinal charts, and nodeIDAccessor/edgeIdAccessor for network operations.
+  Agent action: When generating code that calls remove() or update(), include the matching ID accessor and make sure pushed rows carry that ID field.
+- **renderChart uses static props only** (`rendering.renderchart-static-props`): MCP renderChart and semiotic/server renderChart render a single static SVG/PNG snapshot. Browser-only realtime components and future ref pushes are not renderable through that path.
+  Agent action: Use renderChart only with renderable HOC components and complete static data. For live behavior, return React code with a ref and do not promise MCP-rendered output.
+
+<!-- semiotic-behavior-contracts:end -->
+
 ## Accessibility
 
 `role="group"` (outer) + `role="img"` (inner canvas). Keyboard: arrows navigate points, Enter cycles neighbors, Home/End/PageUp/PageDown. Shape-adaptive focus ring (`--semiotic-focus`). `accessibleTable` (default true) for sr-only data summary. Auto-detects `prefers-reduced-motion` and `forced-colors`. Hooks: `useReducedMotion()`, `useHighContrast()`.
 
-## Known Pitfalls
+## Usage Notes
 
 - **Tooltip datum shape**: HOC tooltips get raw data. Frame `tooltipContent` gets wrapped — use `d.data`.
 - **Legend**: "bottom" expands margin ~80px. MultiAxisLineChart: use `legendPosition="bottom"`.
@@ -201,7 +306,7 @@ Canvas scene builders read CSS variables via `getComputedStyle` on the canvas DO
 - **Geo imports**: Always `semiotic/geo`, never `semiotic`, to avoid d3-geo in non-geo bundles.
 - **fillArea**: `fillArea={["seriesA"]}` fills named series only. Names must match `lineBy`/`colorBy` keys.
 - **hoverHighlight**: Requires `colorBy` as a string field.
-- **tooltip="multi"**: Shows all series at hovered X. Custom fn receives `datum.allSeries`.
+- **tooltip="multi"**: Shows all series at hovered X for LineChart, AreaChart, and StackedAreaChart. Custom fn receives `datum.allSeries`.
 - **Axis config**: `frameProps.axes: [{ orient, includeMax, autoRotate, gridStyle, landmarkTicks }]`
 - **xScaleType: "time"**: Creates `scaleTime`. Required for landmark ticks with timestamps.
 - **scalePadding**: Pixel inset on scale ranges. Pass via `frameProps={{ scalePadding: 12 }}`.

package/README.md

@@ -4,6 +4,7 @@
 [![npm version](https://img.shields.io/npm/v/semiotic.svg)](https://www.npmjs.com/package/semiotic)
 [![TypeScript](https://img.shields.io/badge/TypeScript-built--in-blue.svg)](https://www.typescriptlang.org/)
 [![semiotic MCP server](https://glama.ai/mcp/servers/nteract/semiotic/badges/card.svg)](https://glama.ai/mcp/servers/nteract/semiotic)
+[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/nteract-semiotic-badge.png)](https://mseep.ai/app/nteract-semiotic)
 
 A React data visualization library designed for AI-assisted development.
 
@@ -356,7 +357,9 @@ const gif = await renderToAnimatedGif("line", data, { ... }, { fps: 12 })
 
 ## MCP Server
 
-Semiotic ships with an [MCP server](https://modelcontextprotocol.io) that lets AI coding assistants render charts, diagnose configuration problems, discover schemas, and get chart recommendations via tool calls.
+mcp-name: io.github.nteract/semiotic
+
+Semiotic ships with an [MCP server](https://modelcontextprotocol.io) that lets AI coding assistants render charts, diagnose configuration problems, discover schemas, read packaged AI guidance, and get chart recommendations via tool calls.
 
 ### Setup
 
@@ -373,17 +376,34 @@ Add to your MCP client config (e.g. `claude_desktop_config.json` for Claude Desk
 }
 ```
 
-No API keys or authentication required. The server runs locally via stdio.
+No API keys or authentication required. The server runs locally via stdio. HTTP mode is also available for inspectors and web clients: `npx semiotic-mcp --http --port 3001`.
 
 ### Tools
 
 | Tool | Description |
 |------|-------------|
 | **`renderChart`** | Render a Semiotic chart to static SVG. Supports the components returned by `getSchema` that are marked `[renderable]`. Pass `{ component: "LineChart", props: { data: [...], xAccessor: "x", yAccessor: "y" } }`. Returns SVG string or validation errors with fix suggestions. |
-| **`getSchema`** | Return the prop schema for a specific component. Pass `{ component: "LineChart" }` to get its props, or omit `component` to list all 30 chart types. Use before `renderChart` to look up valid props. |
+| **`getSchema`** | Return the prop schema for a specific component. Pass `{ component: "LineChart" }` to get its props, or omit `component` to list all 43 chart schemas. Components marked `[renderable]` are available through `renderChart`; realtime charts require a browser/live environment. |
 | **`suggestChart`** | Recommend chart types for a data sample. Pass `{ data: [{...}, ...] }` with 1–5 sample objects. Optionally include `intent` (`"comparison"`, `"trend"`, `"distribution"`, `"relationship"`, `"composition"`, `"geographic"`, `"network"`, `"hierarchy"`). Returns ranked suggestions with example props. |
 | **`diagnoseConfig`** | Check a chart configuration for common problems — empty data, bad dimensions, missing accessors, wrong data shape, and more. Returns a human-readable diagnostic report with actionable fixes. |
 | **`reportIssue`** | Generate a pre-filled GitHub issue URL for bug reports or feature requests. Pass `{ title: "...", body: "...", labels: ["bug"] }`. Returns a URL the user can open to submit. |
+| **`applyTheme`** | List named theme presets or return ThemeProvider/CSS/token usage for a preset such as `{ name: "tufte" }`. |
+
+### Resources
+
+| Resource | Description |
+|----------|-------------|
+| **`semiotic://schema`** | Full machine-readable component schema JSON. |
+| **`semiotic://components`** | Component index showing renderable/browser-only status and MCP categories. |
+| **`semiotic://system-prompt`** | Compact AI instructions with import rules, chart props, SSR guidance, and pitfalls. |
+| **`semiotic://examples`** | Copy-paste chart examples by data shape. |
+
+### Prompts
+
+| Prompt | Description |
+|--------|-------------|
+| **`build-semiotic-chart`** | Reusable workflow for choosing a chart, reading schema, diagnosing props, and rendering a preview. |
+| **`debug-semiotic-chart`** | Reusable workflow for debugging invalid props, rendering failures, and issue reports. |
 
 ### Example: get schema for a component
 
@@ -453,17 +473,38 @@ Args: {
 For quick validation without an MCP client:
 
 ```bash
+npx semiotic-ai --list         # list components with import paths and renderability
+npx semiotic-ai --list --json  # machine-readable component index
+npx semiotic-ai --schema GaugeChart
+npx semiotic-ai --suggest '{"data":[{"category":"A","value":10}],"intent":"comparison"}'
 npx semiotic-ai --doctor       # validate component + props JSON
 npx semiotic-ai --schema       # dump all chart schemas
 npx semiotic-ai --compact      # compact schema (fewer tokens)
 ```
 
+`--doctor` uses the full `diagnoseConfig` checks when `dist` is available and falls back to schema-only validation in clean source checkouts.
+
+## Where to find Semiotic for AI assistants
+
+Semiotic is indexed by AI-coding-agent documentation tools so your assistant (Claude Code, Cursor, Cline, Copilot, etc.) can pull current docs and tools without copy-paste:
+
+- **Context7** — [context7.com/nteract/semiotic](https://context7.com/nteract/semiotic) (configured via `context7.json`)
+- **DeepWiki** — [deepwiki.com/nteract/semiotic](https://deepwiki.com/nteract/semiotic)
+- **GitMCP** — [gitmcp.io/nteract/semiotic](https://gitmcp.io/nteract/semiotic) (exposes the repo as an MCP endpoint directly)
+- **Official MCP Registry** — search "semiotic" at [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io)
+- **Smithery** — [smithery.ai/server/nteract/semiotic](https://smithery.ai/server/nteract/semiotic)
+
+Agent-facing API surface:
+
+- **`CLAUDE.md`**, **`ai/schema.json`**, **`ai/behaviorContracts.cjs`** — bundled in the npm tarball (see `package.json#files`); agents that install Semiotic locally read these directly. `CLAUDE.md` is the quick-start cheat sheet (HOC props, push API, theming, usage notes); `ai/schema.json` is the JSON Schema for every chart's prop surface (43 charts); `ai/behaviorContracts.cjs` carries the agent-visible semantic rules (color precedence, push-mode requirements, ID-accessor contracts).
+- [**`semiotic.nteract.io/llms.txt`**](https://semiotic.nteract.io/llms.txt) + [**`/llms-full.txt`**](https://semiotic.nteract.io/llms-full.txt) — deployed at the docs site per the [llms.txt standard](https://llmstxt.org). Agents fetch the navigation map (`llms.txt`) or the full inlined docs (`llms-full.txt`) over HTTP; they're not part of the npm package itself.
+
 ## Documentation
 
 [Interactive docs and examples](https://semiotic.nteract.io)
 
 - [Getting Started](https://semiotic.nteract.io/getting-started)
-- [Charts](https://semiotic.nteract.io/charts) — all 38 chart types with live examples
+- [Charts](https://semiotic.nteract.io/charts) — chart types with live examples
 - [Frames](https://semiotic.nteract.io/frames) — full Frame API reference
 - [Features](https://semiotic.nteract.io/features) — axes, annotations, tooltips, styling, Vega-Lite translator
 - [Cookbook](https://semiotic.nteract.io/cookbook) — advanced patterns and recipes

package/ai/behaviorContracts.cjs

@@ -0,0 +1,311 @@
+"use strict"
+
+// Maintenance note: when you change the agent-facing rules in this
+// file (especially anything in CONTRACTS), update the parallel `rules`
+// array in `context7.json` so the Context7 index stays in sync. The
+// `check:context7` gate validates format (255-char-per-rule limit,
+// folder references, sub-path drift vs `package.json` exports) but
+// can't detect *content* drift between this file and the manifest —
+// keeping them aligned is part of the same edit.
+
+const path = require("path")
+const fs = require("fs")
+
+const DOC_MARKER_START = "<!-- semiotic-behavior-contracts:start -->"
+const DOC_MARKER_END = "<!-- semiotic-behavior-contracts:end -->"
+
+// Components whose static config requires `data` are derived from
+// `ai/schema.json` rather than maintained as a hand-curated list. The schema
+// already declares which components require data — duplicating that here led
+// to drift (Heatmap, FunnelChart, MinimapChart, ScatterplotMatrix, and the
+// hierarchy charts were schema-required but missing from the local list,
+// which made `dataRequiredForUsageMode` incorrectly return `false` and
+// suppressed the "data is required" error in --doctor / MCP diagnoseConfig
+// even when usageMode wasn't `push`).
+//
+// `STATIC_DATA_COMPONENTS` stays exported as a Set for test/legacy callers
+// that probe the surface, and is rebuilt from disk at module load time.
+function loadStaticDataComponentsFromSchema() {
+  // Source layout has this file at `<repo>/ai/behaviorContracts.cjs` and the
+  // schema at `<repo>/ai/schema.json` — `__dirname` works directly.
+  // The MCP server bundles this module into `<repo>/ai/dist/mcp-server.js`
+  // via esbuild, so when invoked from there `__dirname` is `<repo>/ai/dist/`
+  // and the schema lives one directory up. Try both layouts; use whichever
+  // resolves first.
+  const candidates = [
+    path.join(__dirname, "schema.json"),
+    path.join(__dirname, "..", "schema.json"),
+  ]
+  for (const schemaPath of candidates) {
+    try {
+      const schema = JSON.parse(fs.readFileSync(schemaPath, "utf8"))
+      const out = new Set()
+      for (const tool of schema.tools || []) {
+        const required = tool.function?.parameters?.required || []
+        if (required.includes("data")) out.add(tool.function.name)
+      }
+      if (out.size > 0) return out
+    } catch {
+      // try next candidate
+    }
+  }
+  // Defensive fallback: if schema.json is unavailable (e.g. unusual install
+  // layout), fall back to an empty set so callers fail safe — they'll see
+  // "data not required" everywhere, which is permissive but won't crash.
+  return new Set()
+}
+
+const REQUIRED_COMBINATIONS = [
+  {
+    component: "StackedAreaChart",
+    required: ["areaBy"],
+    staticRequired: ["data", "areaBy"],
+    pushRequired: ["areaBy"],
+    summary: "Stacked areas need a flat data array plus areaBy to identify the stacked series.",
+  },
+  {
+    component: "BubbleChart",
+    required: ["sizeBy"],
+    staticRequired: ["data", "sizeBy"],
+    pushRequired: ["sizeBy"],
+    summary: "Bubbles need sizeBy in addition to x/y accessors so radius encodes data rather than a constant point size.",
+  },
+  {
+    component: "StackedBarChart",
+    required: ["stackBy"],
+    staticRequired: ["data", "stackBy"],
+    pushRequired: ["stackBy"],
+    summary: "Stacked bars need stackBy to split each category into stack segments.",
+  },
+  {
+    component: "GroupedBarChart",
+    required: ["groupBy"],
+    staticRequired: ["data", "groupBy"],
+    pushRequired: ["groupBy"],
+    summary: "Grouped bars need groupBy to split each category into side-by-side bars.",
+  },
+  {
+    component: "SwimlaneChart",
+    required: ["subcategoryAccessor"],
+    staticRequired: ["data", "subcategoryAccessor"],
+    pushRequired: ["subcategoryAccessor"],
+    summary: "Swimlanes need subcategoryAccessor; colorBy defaults to the same field when not provided.",
+  },
+  {
+    component: "GaugeChart",
+    required: ["value"],
+    staticRequired: ["value"],
+    pushRequired: [],
+    summary: "GaugeChart is value-only. thresholds, min, max, sweep, and arcWidth are optional.",
+  },
+  {
+    component: "ForceDirectedGraph",
+    required: ["nodes", "edges"],
+    staticRequired: ["nodes", "edges"],
+    pushRequired: ["nodes", "edges"],
+    summary: "ForceDirectedGraph schema/rendering requires nodes and edges. If an agent infers nodes from edge endpoints, it must materialize a nodes array before returning code.",
+  },
+]
+
+const PUSH_MODE_COMPONENTS = [
+  "LineChart",
+  "AreaChart",
+  "StackedAreaChart",
+  "Scatterplot",
+  "BubbleChart",
+  "ConnectedScatterplot",
+  "BarChart",
+  "StackedBarChart",
+  "GroupedBarChart",
+  "SwarmPlot",
+  "BoxPlot",
+  "Histogram",
+  "ViolinPlot",
+  "RidgelinePlot",
+  "DotPlot",
+  "PieChart",
+  "DonutChart",
+  "LikertChart",
+  "SwimlaneChart",
+  "ForceDirectedGraph",
+  "SankeyDiagram",
+  "ChordDiagram",
+  "ProportionalSymbolMap",
+  "DistanceCartogram",
+]
+
+const STATIC_DATA_COMPONENTS = loadStaticDataComponentsFromSchema()
+
+const BEHAVIOR_CONTRACTS = [
+  {
+    id: "props.data-required-by-usage-mode",
+    category: "required-props",
+    title: "Data required by usage mode",
+    severity: "error",
+    appliesTo: {
+      components: PUSH_MODE_COMPONENTS,
+    },
+    summary: "Static usage (`renderChart`, MCP previews, SSR snapshots, and copy/paste examples with immediate data) requires data in props. React push mode selects live ingestion by omitting data and mutating through a ref.",
+    agentAction: "Pass usageMode=\"push\" to `semiotic-ai --doctor` when validating ref-based JSX with no data prop. Keep usageMode=\"static\" or omit it for renderChart/MCP/static configs where data must be present.",
+  },
+  {
+    id: "color.category-precedence",
+    category: "color",
+    title: "Categorical color precedence",
+    severity: "info",
+    appliesTo: {
+      propsAny: ["colorBy", "colorScheme"],
+    },
+    summary: "When colorBy is set, CategoryColorProvider/LinkedCharts category maps win for mapped categories. Unmapped categories fall back to explicit colorScheme, then ThemeProvider colors.categorical, then the built-in categorical fallback.",
+    agentAction: "Use colorBy for categorical encodings. Use CategoryColorProvider or LinkedCharts for cross-chart consistency, colorScheme for per-chart fallback palettes, and avoid frameProps style functions unless intentionally bypassing HOC color resolution.",
+  },
+  {
+    id: "props.required-combinations",
+    category: "required-props",
+    title: "Required prop combinations",
+    severity: "error",
+    appliesTo: {
+      components: REQUIRED_COMBINATIONS.map((entry) => entry.component),
+    },
+    summary: "Some chart families need semantic props beyond data. These combinations are enforced by validation/schema for static configs and remain required in push mode unless explicitly noted.",
+    agentAction: "Before returning code, check the selected component against the required combinations list. For push mode, omit data but keep semantic props such as areaBy, sizeBy, stackBy, and groupBy.",
+    combinations: REQUIRED_COMBINATIONS,
+  },
+  {
+    id: "streaming.push-mode-data",
+    category: "streaming",
+    title: "Push mode omits data",
+    severity: "warning",
+    appliesTo: {
+      components: PUSH_MODE_COMPONENTS,
+    },
+    summary: "HOC push mode is selected by omitting the data prop entirely. Passing data={[]} is static empty data and can clear/reinitialize the frame on render.",
+    agentAction: "For live charts, create a ref, omit data, then call ref.current.push() or pushMany(). For static renderChart/MCP snapshots, provide data because renderChart cannot push later.",
+  },
+  {
+    id: "streaming.ref-mutations-require-id-accessors",
+    category: "streaming",
+    title: "Ref mutations need stable IDs",
+    severity: "warning",
+    appliesTo: {
+      components: PUSH_MODE_COMPONENTS,
+    },
+    summary: "push() and pushMany() can append without IDs, but remove(id) and update(id, updater) require a stable ID accessor: pointIdAccessor for XY/realtime charts, dataIdAccessor for ordinal charts, and nodeIDAccessor/edgeIdAccessor for network operations.",
+    agentAction: "When generating code that calls remove() or update(), include the matching ID accessor and make sure pushed rows carry that ID field.",
+  },
+  {
+    id: "rendering.renderchart-static-props",
+    category: "rendering",
+    title: "renderChart uses static props only",
+    severity: "warning",
+    appliesTo: {},
+    summary: "MCP renderChart and semiotic/server renderChart render a single static SVG/PNG snapshot. Browser-only realtime components and future ref pushes are not renderable through that path.",
+    agentAction: "Use renderChart only with renderable HOC components and complete static data. For live behavior, return React code with a ref and do not promise MCP-rendered output.",
+  },
+]
+
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key)
+}
+
+function normalizeProps(props) {
+  return props && typeof props === "object" && !Array.isArray(props) ? props : {}
+}
+
+function appliesToComponent(contract, component) {
+  if (!component) return !contract.appliesTo?.components
+  const components = contract.appliesTo?.components
+  return !components || components.includes(component)
+}
+
+function appliesToProps(contract, props) {
+  const propsAny = contract.appliesTo?.propsAny
+  if (!propsAny || propsAny.length === 0) return true
+  return propsAny.some((prop) => hasOwn(props, prop) && props[prop] !== undefined)
+}
+
+function behaviorContractsFor({ component, props } = {}) {
+  const normalizedProps = normalizeProps(props)
+  return BEHAVIOR_CONTRACTS.filter((contract) =>
+    appliesToComponent(contract, component) && appliesToProps(contract, normalizedProps)
+  )
+}
+
+function normalizeUsageMode(usageMode) {
+  if (usageMode === "push") return "push"
+  if (usageMode === "static" || usageMode === "renderChart" || usageMode === "server") return "static"
+  return "static"
+}
+
+function dataRequiredForUsageMode(component, usageMode) {
+  if (!STATIC_DATA_COMPONENTS.has(component)) return false
+  if (normalizeUsageMode(usageMode) === "push" && PUSH_MODE_COMPONENTS.includes(component)) return false
+  return true
+}
+
+function requiredCombinationsFor(component) {
+  return REQUIRED_COMBINATIONS.filter((entry) => !component || entry.component === component)
+}
+
+function formatRequiredCombination(entry) {
+  const staticRequired = entry.staticRequired || entry.required
+  const pushRequired = entry.pushRequired || entry.required.filter((prop) => prop !== "data")
+  const pushText = pushRequired.length > 0 ? pushRequired.join(" + ") : "not supported"
+  return `${entry.component}: static ${staticRequired.join(" + ")}; push ${pushText}. ${entry.summary}`
+}
+
+function formatDoctorBehaviorContracts(contracts) {
+  if (!contracts || contracts.length === 0) return ""
+
+  const lines = ["Behavior contracts:"]
+  for (const contract of contracts) {
+    lines.push(`  - [${contract.id}] ${contract.summary}`)
+    if (contract.combinations) {
+      for (const combo of contract.combinations) {
+        lines.push(`    ${formatRequiredCombination(combo)}`)
+      }
+    }
+    lines.push(`    Action: ${contract.agentAction}`)
+  }
+  return lines.join("\n")
+}
+
+function formatBehaviorContractsMarkdown({ compact = false } = {}) {
+  const lines = [
+    compact ? "## Behavior Contracts" : "## AI Behavior Contracts",
+    "",
+    DOC_MARKER_START,
+    "",
+    "These rules are generated from `ai/behaviorContracts.cjs` and are consumed by `semiotic-ai --doctor`, MCP resources, and docs checks.",
+    "",
+  ]
+
+  for (const contract of BEHAVIOR_CONTRACTS) {
+    lines.push(`- **${contract.title}** (\`${contract.id}\`): ${contract.summary}`)
+    if (!compact) {
+      lines.push(`  Agent action: ${contract.agentAction}`)
+    }
+    if (contract.combinations) {
+      const combos = contract.combinations.map(formatRequiredCombination).join(" ")
+      lines.push(`  Required combinations: ${combos}`)
+    }
+  }
+
+  lines.push("", DOC_MARKER_END)
+  return lines.join("\n")
+}
+
+module.exports = {
+  BEHAVIOR_CONTRACTS,
+  DOC_MARKER_END,
+  DOC_MARKER_START,
+  PUSH_MODE_COMPONENTS,
+  REQUIRED_COMBINATIONS,
+  STATIC_DATA_COMPONENTS,
+  behaviorContractsFor,
+  dataRequiredForUsageMode,
+  formatBehaviorContractsMarkdown,
+  formatDoctorBehaviorContracts,
+  normalizeUsageMode,
+  requiredCombinationsFor,
+}