semiotic 3.0.0-beta.5 → 3.0.0-beta.7

package/CLAUDE.md

@@ -2,192 +2,122 @@
 
 ## Quick Start
 - Install: `npm install semiotic`
-- Import from `semiotic` or granular: `semiotic/xy`, `semiotic/ordinal`, `semiotic/network`, `semiotic/realtime`, `semiotic/ai`, `semiotic/data`
-- `semiotic/ai` exports HOC charts + TooltipProvider + MultiLineTooltip + ThemeProvider + exportChart + validateProps + useChartObserver + DetailsPanel + ChartContainer
-- `semiotic/data` exports: `bin`, `rollup`, `groupBy`, `pivot`
-- CLI: `npx semiotic-ai [--schema|--compact|--examples]` — dump AI context to stdout
-- MCP: `npx semiotic-mcp` — MCP server rendering charts to static SVG
+- Import: `semiotic`, `semiotic/xy`, `semiotic/ordinal`, `semiotic/network`, `semiotic/realtime`, `semiotic/ai`, `semiotic/data`
+- CLI: `npx semiotic-ai [--schema|--compact|--examples|--doctor]`
+- MCP: `npx semiotic-mcp`
+- Every HOC has a built-in error boundary (never blanks the page) and dev-mode validation warnings
 
 ## Architecture
-- **HOC Charts** (recommended): Simple props, sensible defaults
-- **Stream Frames** (advanced): `StreamXYFrame`, `StreamOrdinalFrame`, `StreamNetworkFrame`
-- Every HOC accepts `frameProps` to pass through to the underlying Stream Frame
-- TypeScript `strict: true`; all charts have `role="img"` + `aria-label`
+- **HOC Charts**: Simple props, sensible defaults. **Stream Frames**: Full control.
+- Every HOC accepts `frameProps` to pass through. TypeScript `strict: true`.
 
-## Component Reference
+## Common Props (all HOCs)
+`title`, `width` (600), `height` (400), `responsiveWidth`, `responsiveHeight`, `margin`, `className`, `enableHover` (true), `tooltip`, `showLegend`, `showGrid` (false), `frameProps`, `onObservation`, `chartId`
 
-### Common props (all HOCs unless noted)
-`title` (string), `width` (number, 600), `height` (number, 400), `responsiveWidth` (boolean, false), `responsiveHeight` (boolean, false), `margin` (object), `className` (string), `enableHover` (boolean, true), `tooltip` (fn), `showLegend` (boolean), `showGrid` (boolean, false), `frameProps` (object), `onObservation` (fn), `chartId` (string)
+## XY Charts (`semiotic/xy`)
 
-### XY Charts (from "semiotic" or "semiotic/xy")
+**LineChart** — `data`, `xAccessor` ("x"), `yAccessor` ("y"), `lineBy`, `lineDataAccessor` ("coordinates"), `colorBy`, `colorScheme`, `curve`, `lineWidth` (2), `showPoints`, `pointRadius` (3), `fillArea`, `areaOpacity` (0.3), `anomaly` (AnomalyConfig), `forecast` (ForecastConfig)
 
-**LineChart** — `data` (required), `xAccessor` ("x"), `yAccessor` ("y"), `lineBy`, `lineDataAccessor` ("coordinates"), `colorBy`, `colorScheme` ("category10"), `curve` ("linear"|"monotoneX"|"monotoneY"|"step"|"stepAfter"|"stepBefore"|"basis"|"cardinal"|"catmullRom"), `lineWidth` (2), `showPoints` (false), `pointRadius` (3), `fillArea` (false), `areaOpacity` (0.3), `xLabel`, `yLabel`, `xFormat`, `yFormat`, `anomaly` (AnomalyConfig), `forecast` (ForecastConfig)
+**AreaChart** — LineChart props + `areaBy`, `y0Accessor` (band/ribbon), `gradientFill` (boolean|{topOpacity,bottomOpacity}), `areaOpacity` (0.7), `showLine` (true)
 
-**AreaChart** — Same as LineChart plus: `areaBy`, `y0Accessor` (per-point lower bound for band/ribbon charts), `gradientFill` (boolean|{topOpacity,bottomOpacity} — fade fill from line to baseline), `areaOpacity` (0.7), `showLine` (true), curve default "monotoneX"
+**StackedAreaChart** — AreaChart + `normalize` (false)
 
-**StackedAreaChart** — Same as AreaChart plus: `normalize` (false)
+**Scatterplot** — `data`, `xAccessor`, `yAccessor`, `colorBy`, `sizeBy`, `sizeRange`, `pointRadius` (5), `pointOpacity` (0.8), `marginalGraphics`
 
-**Scatterplot** — `data` (required), `xAccessor` ("x"), `yAccessor` ("y"), `colorBy`, `colorScheme`, `sizeBy`, `sizeRange` ([3,15]), `pointRadius` (5), `pointOpacity` (0.8), `xLabel`, `yLabel`, `marginalGraphics` ({top?,bottom?,left?,right?} — "histogram"|"violin"|"ridgeline"|"boxplot" or config object)
+**BubbleChart** — Scatterplot + `sizeBy` (required), `sizeRange` ([5,40]), `bubbleOpacity` (0.6)
 
-**BubbleChart** — Like Scatterplot with `sizeBy` (required), `sizeRange` ([5,40]), `bubbleOpacity` (0.6), `bubbleStrokeWidth` (1), `bubbleStrokeColor` ("white"), `marginalGraphics`
+**ConnectedScatterplot** — `data`, `xAccessor`, `yAccessor`, `orderAccessor` (number|Date field for sequencing), `pointRadius` (4). Viridis colored start→end, line width = point radius, white halo under lines when <100 points.
 
-**Heatmap** — `data` (required), `xAccessor` ("x"), `yAccessor` ("y"), `valueAccessor` ("value"), `colorScheme` ("blues"|"reds"|"greens"|"viridis"|"custom"), `customColorScale`, `showValues` (false), `valueFormat`, `cellBorderColor` ("#fff"), `cellBorderWidth` (1)
+**Heatmap** — `data`, `xAccessor`, `yAccessor`, `valueAccessor`, `colorScheme`, `showValues`, `cellBorderColor`
 
-### Ordinal Charts (from "semiotic" or "semiotic/ordinal")
+## Ordinal Charts (`semiotic/ordinal`)
 
-**BarChart** — `data` (required), `categoryAccessor` ("category"), `valueAccessor` ("value"), `orientation` ("vertical"|"horizontal"), `colorBy`, `colorScheme`, `sort` (boolean|"asc"|"desc"|fn), `barPadding` (5), `categoryLabel`, `valueLabel`, `valueFormat`
+**BarChart** — `data`, `categoryAccessor`, `valueAccessor`, `orientation`, `colorBy`, `sort`, `barPadding`
+**StackedBarChart** — + `stackBy` (required), `normalize`
+**GroupedBarChart** — + `groupBy` (required)
+**SwarmPlot** — `data`, `categoryAccessor`, `valueAccessor`, `colorBy`, `sizeBy`, `pointRadius`, `pointOpacity`
+**BoxPlot** — + `showOutliers`, `outlierRadius`
+**Histogram** — + `bins` (25), `relative`. Always horizontal.
+**ViolinPlot** — + `bins`, `curve`, `showIQR`
+**DotPlot** — + `sort` (true), `dotRadius`, `showGrid` default true
+**PieChart** — `data`, `categoryAccessor`, `valueAccessor`, `colorBy`, `startAngle`, `slicePadding`
+**DonutChart** — PieChart + `innerRadius` (60), `centerContent`
 
-**StackedBarChart** — BarChart props plus `stackBy` (required), `normalize` (false)
+## Network Charts (`semiotic/network`)
 
-**GroupedBarChart** — BarChart props plus `groupBy` (required)
+**ForceDirectedGraph** — `nodes`, `edges`, `nodeIDAccessor`, `sourceAccessor`, `targetAccessor`, `colorBy`, `nodeSize`, `edgeWidth`, `iterations`, `showLabels`
+**SankeyDiagram** — `edges`, `nodes`, `valueAccessor`, `edgeColorBy`, `orientation`, `nodeAlign`, `nodeWidth`, `showLabels`, `edgeOpacity`
+**ChordDiagram** — `edges`, `nodes`, `valueAccessor`, `edgeColorBy`, `padAngle`, `groupWidth`, `showLabels`
+**TreeDiagram** — `data` (root), `layout`, `orientation`, `childrenAccessor`, `colorBy`, `colorByDepth`, `edgeStyle`
+**Treemap** — `data` (root), `childrenAccessor`, `valueAccessor`, `colorBy`, `colorByDepth`, `showLabels`, `labelMode`
+**CirclePack** — `data` (root), `childrenAccessor`, `valueAccessor`, `colorBy`, `colorByDepth`, `circleOpacity`
 
-**SwarmPlot** — `data` (required), `categoryAccessor`, `valueAccessor`, `orientation`, `colorBy`, `sizeBy`, `sizeRange` ([3,8]), `pointRadius` (4), `pointOpacity` (0.7), `categoryPadding` (20)
+## Realtime Charts (`semiotic/realtime`)
 
-**BoxPlot** — `data` (required), `categoryAccessor`, `valueAccessor`, `orientation`, `colorBy`, `showOutliers` (true), `outlierRadius` (3), `categoryPadding` (20)
+Push API: `chartRef.current.push({ time, value })`
 
-**Histogram** — `data` (required), `categoryAccessor`, `valueAccessor`, `bins` (25), `relative` (false), `categoryPadding` (20). Always horizontal.
+**RealtimeLineChart** — `size`, `timeAccessor`, `valueAccessor`, `windowSize` (200), `windowMode`, `stroke`, `strokeWidth`
+**RealtimeTemporalHistogram** — + `binSize` (required), `categoryAccessor`, `colors`
+**RealtimeSwarmChart** — + `categoryAccessor`, `radius`, `opacity`
+**RealtimeWaterfallChart** — + `positiveColor`, `negativeColor`
+**RealtimeHeatmap** — + `heatmapXBins`, `heatmapYBins`, `aggregation`
+**Streaming Sankey** — `StreamNetworkFrame` with `chartType="sankey"`, `showParticles`, `particleStyle`, `tensionConfig`, `thresholds`
 
-**ViolinPlot** — `data` (required), `categoryAccessor`, `valueAccessor`, `orientation`, `bins` (25), `curve` ("catmullRom"), `showIQR` (true), `categoryPadding` (20)
+Realtime encoding: `decay`, `pulse`, `transition`, `staleness` — compose freely on all streaming charts.
 
-**DotPlot** — `data` (required), `categoryAccessor`, `valueAccessor`, `orientation` ("horizontal"), `sort` (true), `dotRadius` (5), `categoryPadding` (10), `showGrid` default true
+## Coordinated Views
 
-**PieChart** — `data` (required), `categoryAccessor`, `valueAccessor`, `colorBy`, `startAngle` (0), `slicePadding` (2), width/height default 400
+**LinkedCharts** — wraps charts. Props: `selections` (resolution: "union"|"intersect"|"crossfilter")
+**CategoryColorProvider** — stable category→color mapping. Props: `colors` (map) or `categories` + `colorScheme`
+Chart props: `selection`, `linkedHover`, `linkedBrush`. Hooks: `useSelection`, `useLinkedHover`, `useBrushSelection`, `useFilteredData`
+**ScatterplotMatrix** — `data`, `fields`, `colorBy`, `cellSize`, `hoverMode`, `brushMode`
 
-**DonutChart** — PieChart props plus `innerRadius` (60), `centerContent` (ReactNode)
+## Layout & Composition
 
-### Network Charts (from "semiotic" or "semiotic/network")
+**ChartGrid** — CSS Grid layout. `columns` (number|"auto"), `minCellWidth` (300), `gap` (16)
+**ContextLayout** — primary + context panel. `context` (ReactNode), `position`, `contextSize` (250)
 
-**ForceDirectedGraph** — `nodes` (required), `edges` (required), `nodeIDAccessor` ("id"), `sourceAccessor` ("source"), `targetAccessor` ("target"), `nodeLabel`, `colorBy`, `nodeSize` (8), `nodeSizeRange` ([5,20]), `edgeWidth` (1), `edgeColor` ("#999"), `edgeOpacity` (0.6), `iterations` (300), `forceStrength` (0.1), `showLabels` (false). Width/height default 600.
-
-**SankeyDiagram** — `edges` (required), `nodes` (optional), `sourceAccessor`, `targetAccessor`, `valueAccessor` ("value"), `nodeIdAccessor` ("id"), `colorBy`, `edgeColorBy` ("source"|"target"|"gradient"|fn), `orientation` ("horizontal"|"vertical"), `nodeAlign` ("justify"|"left"|"right"|"center"), `nodePaddingRatio` (0.05), `nodeWidth` (15), `nodeLabel`, `showLabels` (true), `edgeOpacity` (0.5), `edgeSort`. Default 800x600.
-
-**ChordDiagram** — `edges` (required), `nodes`, `sourceAccessor`, `targetAccessor`, `valueAccessor`, `nodeIdAccessor`, `colorBy`, `edgeColorBy`, `padAngle` (0.01), `groupWidth` (20), `sortGroups`, `nodeLabel`, `showLabels` (true), `edgeOpacity` (0.5)
-
-**TreeDiagram** — `data` (required, single root with children), `layout` ("tree"|"cluster"|"partition"|"treemap"|"circlepack"), `orientation` ("vertical"|"horizontal"|"radial"), `childrenAccessor` ("children"), `valueAccessor`, `nodeIdAccessor` ("name"), `colorBy`, `colorByDepth` (false), `edgeStyle` ("line"|"curve"), `nodeLabel`, `showLabels` (true), `nodeSize` (5)
-
-**Treemap** — `data` (required, root with children), `childrenAccessor`, `valueAccessor`, `nodeIdAccessor` ("name"), `colorBy`, `colorByDepth` (false), `showLabels` (true), `labelMode` ("leaf"|"parent"|"all"), `nodeLabel`, `padding` (4), `paddingTop` (0, auto 18 for "parent"). Hover shows ancestor breadcrumb.
-
-**CirclePack** — `data` (required), `childrenAccessor`, `valueAccessor`, `nodeIdAccessor`, `colorBy`, `colorByDepth` (false), `showLabels` (true), `nodeLabel`, `circleOpacity` (0.7), `padding` (4). Labels hidden below 15px radius. Hover shows ancestor breadcrumb.
-
-### Realtime Charts (from "semiotic" or "semiotic/realtime")
-
-All use ref-based push API + canvas rendering: `chartRef.current.push({ time, value })`
-
-**RealtimeLineChart** — `size` ([500,300]), `timeAccessor`, `valueAccessor`, `windowSize` (200), `windowMode` ("sliding"|"stepping"), `arrowOfTime` ("left"|"right"), `stroke`, `strokeWidth`, `strokeDasharray`, `timeExtent`, `valueExtent`, `extentPadding`, `showAxes`, `background`, `enableHover`, `tooltipContent`, `onHover`, `annotations`, `svgAnnotationRules`, `tickFormatTime`, `tickFormatValue`
-
-**RealtimeTemporalHistogram** — RealtimeLineChart props plus `binSize` (required), `categoryAccessor`, `colors`, `fill`, `gap`, `decay`, `pulse`, `staleness`, `transition`
-
-**RealtimeSwarmChart** — RealtimeLineChart props plus `categoryAccessor`, `colors`, `radius`, `fill`, `opacity`
-
-**RealtimeWaterfallChart** — RealtimeLineChart props plus `positiveColor`, `negativeColor`, `connectorStroke`, `connectorWidth`, `gap`
-
-**RealtimeHeatmap** — RealtimeLineChart props plus `heatmapXBins` (20), `heatmapYBins` (20), `aggregation` ("count"|"sum"|"mean"), `linkedHover`, `decay`, `pulse`, `staleness`
-
-**Streaming Sankey** — Use `StreamNetworkFrame` with `chartType="sankey"`, `showParticles`, `particleStyle`, `tensionConfig`, `thresholds`, `onTopologyChange`. Ref: `push()`, `pushMany()`, `clear()`, `getTopology()`, `relayout()`, `getTension()`
-
-### Realtime Visual Encoding (all streaming charts)
-- `decay` — older data fades (`{ type, halfLife, minOpacity }`)
-- `pulse` — new data flashes (`{ duration, color, glowRadius }`)
-- `transition` — smooth interpolation (`{ duration, easing }`)
-- `staleness` — stale feed detection (`{ threshold, dimOpacity, showBadge }`)
-
-### Coordinated Views (from "semiotic" or "semiotic/ai")
-
-**LinkedCharts** — Wraps charts for coordination. Props: `selections` (Record with resolution: "union"|"intersect"|"crossfilter")
-
-Chart coordination props (on HOCs inside LinkedCharts):
-- `selection` — consume named selection
-- `linkedHover` — produce hover selections
-- `linkedBrush` — produce brush selections (Scatterplot/BubbleChart only)
-
-Hooks: `useSelection`, `useLinkedHover`, `useBrushSelection`, `useFilteredData`
-
-**ScatterplotMatrix** — `data` (required), `fields` (required), `fieldLabels`, `colorBy`, `cellSize` (150), `cellGap` (4), `pointRadius` (2), `pointOpacity` (0.5), `diagonal` ("histogram"|"density"|"label"), `histogramBins` (20), `hoverMode` (true), `brushMode` ("crossfilter"|"intersect"|false), `unselectedOpacity` (0.1)
-
-## Key Usage Patterns
+## Key Patterns
 
 ```jsx
-// Multi-line data
-<LineChart data={[{ id: "A", coordinates: [{x:0,y:1},{x:1,y:2}] }]} lineBy="id" xAccessor="x" yAccessor="y" />
-
-// Hierarchical data (TreeDiagram, Treemap, CirclePack) — single root with children
-<Treemap data={rootNode} childrenAccessor="children" valueAccessor="value" />
-
-// Network data
-<SankeyDiagram nodes={nodes} edges={edges} valueAccessor="value" />
-
-// Tooltips
-<LineChart ... tooltip={MultiLineTooltip({ title: "name", fields: ["value"] })} />
-
-// Coordinated views
+// Cross-highlighting dashboard
+<CategoryColorProvider categories={["North", "South", "East"]}>
 <LinkedCharts>
-  <Scatterplot data={d} linkedHover={{ name: "hl", fields: ["cat"] }} selection={{ name: "hl" }} />
-  <BarChart data={agg} selection={{ name: "hl" }} />
+  <ChartGrid columns={2}>
+    <LineChart data={d} colorBy="region" linkedHover={{ name: "hl", fields: ["region"] }} selection={{ name: "hl" }} responsiveWidth />
+    <BarChart data={d} colorBy="region" linkedHover={{ name: "hl", fields: ["region"] }} selection={{ name: "hl" }} responsiveWidth />
+  </ChartGrid>
 </LinkedCharts>
-
-// Marginal graphics
-<Scatterplot data={d} marginalGraphics={{ top: "histogram", right: "violin" }} />
-
-// Theming
-<ThemeProvider theme="dark"><LineChart ... /></ThemeProvider>
-
-// Shared category colors across charts
-<CategoryColorProvider colors={{ North: "#e41a1c", South: "#377eb8" }}>
-  <LineChart data={d1} colorBy="region" />
-  <BarChart data={d2} colorBy="region" />  {/* same colors */}
 </CategoryColorProvider>
 
-// Data transforms
-import { bin, rollup, groupBy, pivot } from "semiotic/data"
+// Forecast + anomaly (auto)
+<LineChart data={ts} xAccessor="time" yAccessor="value"
+  forecast={{ trainEnd: 60, steps: 15, confidence: 0.95 }}
+  anomaly={{ threshold: 2 }} />
 
-// Browser export
-await exportChart(el, { format: "png", scale: 2 })
+// Forecast (pre-computed ML bounds)
+<LineChart data={ml} xAccessor="time" yAccessor="value"
+  forecast={{ isTraining: "isTraining", isForecast: "isForecast", isAnomaly: "isAnomaly", upperBounds: "upper", lowerBounds: "lower" }} />
+
+// Gradient area + percentile band
+<AreaChart data={d} xAccessor="x" yAccessor="p95" y0Accessor="p5" gradientFill />
 
 // Realtime
 const ref = useRef()
 ref.current.push({ time: Date.now(), value: 42 })
 <RealtimeLineChart ref={ref} timeAccessor="time" valueAccessor="value" />
-
-// Forecast + anomaly detection (LineChart only)
-// Auto mode: training=dashed, observed=solid, forecast=dotted with confidence envelope
-<LineChart data={timeSeries} xAccessor="time" yAccessor="value"
-  forecast={{ trainEnd: 60, steps: 15, confidence: 0.95 }}
-  anomaly={{ threshold: 2, anomalyColor: "#ef4444" }} />
-
-// Pre-computed mode: bring your own bounds from an ML model
-// Data: { time, value, isTraining?, isForecast?, isAnomaly?, upperBounds?, lowerBounds? }
-// Envelope follows per-point bounds (non-rectilinear)
-<LineChart data={mlOutput} xAccessor="time" yAccessor="value"
-  forecast={{
-    isTraining: "isTraining", isForecast: "isForecast",
-    isAnomaly: "isAnomaly", upperBounds: "upper", lowerBounds: "lower",
-  }} />
 ```
 
 ## AI Features
-
-**onObservation** — callback on all HOCs emitting structured events: hover, hover-end, click, click-end, brush, brush-end, selection, selection-end. Each includes `{ type, datum?, x?, y?, timestamp, chartType, chartId? }`.
-
-**useChartObserver** — aggregates observations across LinkedCharts. Options: `limit` (50), `types`, `chartId`.
-
-**Chart serialization** — `toConfig(name, props)` / `fromConfig(config)` for JSON round-trip. `toURL`/`fromURL` for permalinks. `copyConfig(config, "jsx")` for clipboard. `configToJSX(config)` for code gen. String accessors survive; functions are stripped.
-
-**DetailsPanel** — selection-driven detail panel. Props: `children` (render fn), `position` ("right"|"bottom"|"overlay"), `size` (300), `trigger` ("click"|"hover"), `chartId`, `dismissOnEmpty`, `showClose`. Use inside ChartContainer via `detailsPanel` prop.
-
-**ChartGrid** — responsive grid layout for multiple charts. Props: `columns` (number|"auto"), `minCellWidth` (300), `gap` (16). Works with LinkedCharts.
-
-**ContextLayout** — places a primary chart alongside context chart(s). Props: `context` (ReactNode), `position` ("right"|"left"|"top"|"bottom"), `contextSize` (250), `gap` (12). Context charts use `mode="context"` for compact rendering.
-
-**ChartErrorBoundary** — `fallback` (ReactNode), `onError` (fn)
-
-**validateProps(componentName, props)** — returns `{ valid, errors }`
-
-## What Semiotic Does That Others Don't
-- Network visualization (force, sankey, chord, tree, treemap, circlepack) with same clean API
-- Streaming data (canvas 60fps push API) + streaming Sankey with particles
-- Realtime visual encoding (decay, pulse, transitions, staleness)
-- Coordinated views (LinkedCharts, crossfilter brushing, ScatterplotMatrix)
-- Statistical summaries (box, violin, swarm, histogram, marginal graphics)
-- AI observation hooks + chart state serialization
-- Server-side SVG via `renderToStaticSVG()` (from "semiotic/server")
-- Global theming with ThemeProvider
+- `onObservation` — structured events (hover, click, brush, selection) on all HOCs
+- `useChartObserver` — aggregates observations across LinkedCharts
+- `toConfig`/`fromConfig`/`toURL`/`fromURL`/`copyConfig`/`configToJSX` — chart state serialization
+- `DetailsPanel` — click-driven detail panel inside `ChartContainer`
+- `validateProps(componentName, props)` — prop validation
+- `ChartErrorBoundary` — error boundary
+- `exportChart(el, { format: "png"|"svg" })` — browser export
+- `renderToStaticSVG()` — server-side SVG (from `semiotic/server`)
+- `npx semiotic-ai --doctor` — validate component + props JSON from CLI
+
+## Differentiators
+Network viz, streaming canvas, realtime encoding, coordinated views, statistical summaries, AI hooks, chart serialization, global theming, keyboard navigation

package/README.md

@@ -84,8 +84,10 @@ snapshots, or coordinated views across chart types.
 **AI-ready.** Semiotic ships with structured schemas (`ai/schema.json`), an
 `import from "semiotic/ai"` entry point, and an MCP server — all designed for
 LLM code generation. AI coding assistants can generate correct Semiotic code on
-the first try. Run `npx semiotic-ai --help` for CLI options or add `semiotic-mcp`
-to your MCP client config for tool-based chart rendering.
+the first try. Run `npx semiotic-ai --help` for CLI options, `npx semiotic-ai --doctor`
+to validate props from the command line, or add `semiotic-mcp` to your MCP client
+config for tool-based chart rendering. Every HOC chart includes a built-in error
+boundary and dev-mode validation warnings with actionable fix suggestions.
 
 **Vega-Lite compatible.** Have existing Vega-Lite specs? `fromVegaLite(spec)`
 translates them to Semiotic chart configs — instant onboarding from notebooks,
@@ -100,7 +102,7 @@ highlights new services as they appear. Visualization as product navigation.
 ## Install
 
 ```bash
-npm install semiotic@3.0.0-beta.4
+npm install semiotic@3.0.0-beta.7
 ```
 
 Requires React 18.1 or later.
@@ -218,6 +220,7 @@ import { LineChart, BarChart } from "semiotic"
 | **Network** | `ForceDirectedGraph` `ChordDiagram` `SankeyDiagram` `TreeDiagram` `Treemap` `CirclePack` |
 | **Realtime** | `RealtimeLineChart` `RealtimeHistogram` `RealtimeSwarmChart` `RealtimeWaterfallChart` `RealtimeHeatmap` |
 | **Coordination** | `LinkedCharts` `ScatterplotMatrix` |
+| **Layout** | `ChartGrid` `ContextLayout` `CategoryColorProvider` |
 | **Frames** | `StreamXYFrame` `StreamOrdinalFrame` `StreamNetworkFrame` |
 
 ### Vega-Lite Translation

package/ai/cli.js

@@ -21,6 +21,7 @@ Usage:
   npx semiotic-ai --schema     Print ai/schema.json (tool definitions)
   npx semiotic-ai --compact    Print ai/system-prompt.md (compact prompt)
   npx semiotic-ai --examples   Print ai/examples.md (copy-paste examples)
+  npx semiotic-ai --doctor     Validate component + props JSON from stdin
   npx semiotic-ai --help       Show this help message
 `.trim()
 
@@ -31,6 +32,77 @@ if (flag === "--help" || flag === "-h") {
   process.exit(0)
 }
 
+// --doctor: validate component + props from stdin or argv
+if (flag === "--doctor") {
+  let input = ""
+  if (process.argv[3]) {
+    // npx semiotic-ai --doctor '{"component":"LineChart","props":{...}}'
+    input = process.argv.slice(3).join(" ")
+  } else if (!process.stdin.isTTY) {
+    // echo '...' | npx semiotic-ai --doctor
+    input = fs.readFileSync("/dev/stdin", "utf-8")
+  } else {
+    console.error("Usage: npx semiotic-ai --doctor '{\"component\":\"LineChart\",\"props\":{\"data\":[...]}}'")
+    console.error("       echo '{...}' | npx semiotic-ai --doctor")
+    process.exit(1)
+  }
+
+  try {
+    const { component, props } = JSON.parse(input)
+    if (!component || !props) {
+      console.error("Input must be JSON with { component, props } fields.")
+      process.exit(1)
+    }
+
+    // Load validateProps from dist
+    const distPath = path.join(pkgRoot, "dist", "semiotic-ai.min.js")
+    let validateProps
+    try {
+      const mod = require(distPath)
+      validateProps = mod.validateProps
+    } catch (e) {
+      console.error("Could not load semiotic/ai dist. Run 'npm run dist' first.")
+      process.exit(1)
+    }
+
+    if (!validateProps) {
+      console.error("validateProps not found in semiotic/ai exports.")
+      process.exit(1)
+    }
+
+    const result = validateProps(component, props)
+    if (result.valid) {
+      console.log(`✓ ${component}: props are valid.`)
+      // Additional data shape checks
+      if (props.data && Array.isArray(props.data) && props.data.length > 0) {
+        const sample = props.data[0]
+        console.log(`  Data shape: ${props.data.length} items, keys: [${Object.keys(sample).join(", ")}]`)
+        if (props.xAccessor && typeof props.xAccessor === "string" && !(props.xAccessor in sample)) {
+          console.log(`  ⚠ xAccessor "${props.xAccessor}" not in data keys. Available: ${Object.keys(sample).join(", ")}`)
+        }
+        if (props.yAccessor && typeof props.yAccessor === "string" && !(props.yAccessor in sample)) {
+          console.log(`  ⚠ yAccessor "${props.yAccessor}" not in data keys. Available: ${Object.keys(sample).join(", ")}`)
+        }
+        if (props.categoryAccessor && typeof props.categoryAccessor === "string" && !(props.categoryAccessor in sample)) {
+          console.log(`  ⚠ categoryAccessor "${props.categoryAccessor}" not in data keys. Available: ${Object.keys(sample).join(", ")}`)
+        }
+        if (props.valueAccessor && typeof props.valueAccessor === "string" && !(props.valueAccessor in sample)) {
+          console.log(`  ⚠ valueAccessor "${props.valueAccessor}" not in data keys. Available: ${Object.keys(sample).join(", ")}`)
+        }
+      }
+    } else {
+      console.log(`✗ ${component}: validation failed.`)
+      for (const err of result.errors) {
+        console.log(`  • ${err}`)
+      }
+    }
+  } catch (err) {
+    console.error(`Failed to parse input: ${err.message}`)
+    process.exit(1)
+  }
+  process.exit(0)
+}
+
 const filePath = flag ? FILES[flag] : FILES.default
 
 if (!filePath) {

package/dist/charts/index.d.ts

@@ -8,6 +8,8 @@
  */
 export { Scatterplot } from "./xy/Scatterplot";
 export type { ScatterplotProps } from "./xy/Scatterplot";
+export { ConnectedScatterplot } from "./xy/ConnectedScatterplot";
+export type { ConnectedScatterplotProps } from "./xy/ConnectedScatterplot";
 export { LineChart } from "./xy/LineChart";
 export type { LineChartProps } from "./xy/LineChart";
 export { AreaChart } from "./xy/AreaChart";

package/dist/charts/shared/validateChartData.d.ts

@@ -2,6 +2,9 @@
  * Validates chart data and accessors at render time.
  * Returns null if data is valid, or an error message string if not.
  *
+ * Error messages are designed for AI-agent consumption:
+ * they include the problem, the available fields, AND the suggested fix.
+ *
  * Samples first, last, and a middle element to catch common mistakes
  * (wrong field names, missing data) without iterating the entire dataset.
  */

package/dist/charts/shared/withChartWrapper.d.ts

@@ -0,0 +1,18 @@
+import * as React from "react";
+interface SafeRenderProps {
+    componentName: string;
+    width: number;
+    height: number;
+    children: React.ReactNode;
+}
+/**
+ * Wraps a chart's rendered output with an error boundary.
+ * If the chart throws during render, shows a visible error box
+ * with the component name and error message instead of crashing the page.
+ */
+export declare function SafeRender({ componentName, width, height, children }: SafeRenderProps): React.JSX.Element;
+/** Warn if a string accessor isn't found in the first data element */
+export declare function warnMissingField(componentName: string, data: any[] | undefined, accessorName: string, accessorValue: any): void;
+/** Warn if data looks like the wrong shape for this chart type */
+export declare function warnDataShape(componentName: string, data: any[] | undefined, expectedKeys: string[], hint: string): void;
+export {};

package/dist/charts/xy/ConnectedScatterplot.d.ts

@@ -0,0 +1,60 @@
+import * as React from "react";
+import type { StreamXYFrameProps } from "../../stream/types";
+import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+/**
+ * ConnectedScatterplot component props
+ */
+export interface ConnectedScatterplotProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps, AxisConfig {
+    /** Array of data points. Each point needs x and y properties. */
+    data: TDatum[];
+    /** Field name or function to access x values @default "x" */
+    xAccessor?: ChartAccessor<TDatum, number>;
+    /** Field name or function to access y values @default "y" */
+    yAccessor?: ChartAccessor<TDatum, number>;
+    /**
+     * Field name or function that determines point ordering.
+     * Data is sorted by this value (ascending) before connecting.
+     * Supports numbers and Dates. Shown in tooltip. @default undefined (use data array order)
+     */
+    orderAccessor?: string | ((d: TDatum) => number | Date);
+    /** Label for the ordering metric in tooltips @default "Order" or the accessor field name */
+    orderLabel?: string;
+    /** Point radius @default 4 */
+    pointRadius?: number;
+    /** Enable hover annotations @default true */
+    enableHover?: boolean;
+    /** Show grid lines @default false */
+    showGrid?: boolean;
+    /** Tooltip configuration */
+    tooltip?: TooltipProp;
+    /** Accessor for unique point IDs, used by point-anchored annotations */
+    pointIdAccessor?: ChartAccessor<TDatum, string>;
+    /** Annotation objects to render on the chart */
+    annotations?: Record<string, any>[];
+    /** Additional StreamXYFrame props for advanced customization */
+    frameProps?: Partial<Omit<StreamXYFrameProps, "chartType" | "data" | "size">>;
+}
+/**
+ * ConnectedScatterplot — points connected in sequence by lines.
+ *
+ * Points are colored using viridis from start (purple) to end (yellow).
+ * Lines match the color of their source point and have the same width
+ * as the point radius, so the 2×radius circle remains distinctive.
+ * When fewer than 100 points, a 50% transparent white halo is drawn
+ * under each connecting line for legibility.
+ *
+ * @example
+ * ```tsx
+ * <ConnectedScatterplot
+ *   data={trajectory}
+ *   xAccessor="gdp"
+ *   yAccessor="lifeExpectancy"
+ *   pointRadius={4}
+ * />
+ * ```
+ */
+export declare function ConnectedScatterplot<TDatum extends Record<string, any> = Record<string, any>>(props: ConnectedScatterplotProps<TDatum>): React.JSX.Element;
+export declare namespace ConnectedScatterplot {
+    var displayName: string;
+}