semiotic 3.0.0-beta.4 → 3.0.0-beta.6

package/CLAUDE.md

@@ -1,141 +1,106 @@
 # Semiotic — AI Assistant Guide
 
 ## Quick Start
-- Install: `npm install semiotic@3.0.0-beta.4`
-- 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
+- Install: `npm install semiotic`
+- 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), `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`
+**AreaChart** — LineChart props + `areaBy`, `y0Accessor` (band/ribbon), `gradientFill` (boolean|{topOpacity,bottomOpacity}), `areaOpacity` (0.7), `showLine` (true)
 
-**AreaChart** — Same as LineChart plus: `areaBy`, `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>
+</CategoryColorProvider>
 
-// Marginal graphics
-<Scatterplot data={d} marginalGraphics={{ top: "histogram", right: "violin" }} />
+// Forecast + anomaly (auto)
+<LineChart data={ts} xAccessor="time" yAccessor="value"
+  forecast={{ trainEnd: 60, steps: 15, confidence: 0.95 }}
+  anomaly={{ threshold: 2 }} />
 
-// Theming
-<ThemeProvider theme="dark"><LineChart ... /></ThemeProvider>
+// Forecast (pre-computed ML bounds)
+<LineChart data={ml} xAccessor="time" yAccessor="value"
+  forecast={{ isTraining: "isTraining", isForecast: "isForecast", isAnomaly: "isAnomaly", upperBounds: "upper", lowerBounds: "lower" }} />
 
-// Data transforms
-import { bin, rollup, groupBy, pivot } from "semiotic/data"
-
-// Browser export
-await exportChart(el, { format: "png", scale: 2 })
+// Gradient area + percentile band
+<AreaChart data={d} xAccessor="x" yAccessor="p95" y0Accessor="p5" gradientFill />
 
 // Realtime
 const ref = useRef()
@@ -144,25 +109,15 @@ ref.current.push({ time: Date.now(), value: 42 })
 ```
 
 ## 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.
-
-**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.6
 ```
 
 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/CategoryColors.d.ts

@@ -0,0 +1,48 @@
+import * as React from "react";
+/**
+ * Category→color mapping. Maps category values (like "North", "error", "active")
+ * to fixed color strings. Charts inside a CategoryColorProvider will use these
+ * colors consistently regardless of what subset of categories each chart displays.
+ */
+export type CategoryColorMap = Record<string, string>;
+export interface CategoryColorProviderProps {
+    /** Explicit category→color mapping */
+    colors?: CategoryColorMap;
+    /**
+     * Category values to auto-assign colors from a scheme.
+     * Use when you want consistent colors but don't need specific assignments.
+     */
+    categories?: string[];
+    /** Color scheme to use for auto-assignment. Default: "category10" */
+    colorScheme?: string | string[];
+    children: React.ReactNode;
+}
+/**
+ * CategoryColorProvider — assigns stable colors to category values
+ * shared across all Semiotic charts within its subtree.
+ *
+ * Two modes:
+ * - **Explicit**: pass a `colors` map of category→color
+ * - **Auto**: pass a `categories` array and optional `colorScheme`
+ *
+ * Charts with `colorBy` inside this provider will use the mapped colors
+ * instead of computing their own color scale per-chart.
+ *
+ * ```tsx
+ * <CategoryColorProvider colors={{ North: "#e41a1c", South: "#377eb8", East: "#4daf4a" }}>
+ *   <ChartGrid columns={2}>
+ *     <LineChart data={d1} colorBy="region" responsiveWidth />
+ *     <BarChart data={d2} colorBy="region" responsiveWidth />
+ *   </ChartGrid>
+ * </CategoryColorProvider>
+ * ```
+ */
+export declare function CategoryColorProvider({ colors, categories, colorScheme, children, }: CategoryColorProviderProps): React.JSX.Element;
+export declare namespace CategoryColorProvider {
+    var displayName: string;
+}
+/**
+ * Hook to access the category color map from the nearest provider.
+ * Returns null if no provider is present.
+ */
+export declare function useCategoryColors(): CategoryColorMap | null;

package/dist/ChartGrid.d.ts

@@ -0,0 +1,37 @@
+import * as React from "react";
+export interface ChartGridProps {
+    /** Chart components to arrange in the grid */
+    children: React.ReactNode;
+    /** Number of columns. Default: "auto" (auto-fill based on minCellWidth) */
+    columns?: number | "auto";
+    /** Minimum cell width for auto columns. Default: 300 */
+    minCellWidth?: number;
+    /** Gap between cells in pixels. Default: 16 */
+    gap?: number;
+    /** CSS class for the grid container */
+    className?: string;
+    /** Inline style overrides */
+    style?: React.CSSProperties;
+}
+/**
+ * ChartGrid — responsive grid layout for multiple Semiotic charts.
+ *
+ * Arranges child charts in a CSS Grid that reflows based on available space.
+ * Each cell automatically gets `responsiveWidth` behavior since the grid
+ * manages the cell dimensions.
+ *
+ * Works naturally with `LinkedCharts` for coordinated views:
+ *
+ * ```tsx
+ * <LinkedCharts>
+ *   <ChartGrid columns={2}>
+ *     <LineChart data={d} xAccessor="x" yAccessor="y" responsiveWidth />
+ *     <BarChart data={d} categoryAccessor="cat" valueAccessor="val" responsiveWidth />
+ *   </ChartGrid>
+ * </LinkedCharts>
+ * ```
+ */
+export declare function ChartGrid({ children, columns, minCellWidth, gap, className, style, }: ChartGridProps): React.JSX.Element;
+export declare namespace ChartGrid {
+    var displayName: string;
+}

package/dist/ContextLayout.d.ts

@@ -0,0 +1,38 @@
+import * as React from "react";
+export interface ContextLayoutProps {
+    /** The main chart (renders at full size in the primary slot) */
+    children: React.ReactNode;
+    /** Context chart(s) displayed alongside the primary chart */
+    context: React.ReactNode;
+    /** Position of the context panel. Default: "right" */
+    position?: "right" | "left" | "bottom" | "top";
+    /** Size of the context panel in pixels. Default: 250 */
+    contextSize?: number;
+    /** Gap between primary and context panels in pixels. Default: 12 */
+    gap?: number;
+    /** CSS class for the layout container */
+    className?: string;
+    /** Inline style overrides */
+    style?: React.CSSProperties;
+}
+/**
+ * ContextLayout — places a primary chart alongside one or more context charts.
+ *
+ * The primary chart fills available space while the context panel has a fixed
+ * width (or height for top/bottom). Context charts should use `mode="context"`
+ * for compact rendering without axes or labels.
+ *
+ * ```tsx
+ * <ContextLayout
+ *   context={<Treemap data={hierarchy} mode="context" responsiveWidth colorByDepth />}
+ *   position="right"
+ *   contextSize={250}
+ * >
+ *   <LineChart data={timeSeries} xAccessor="time" yAccessor="value" responsiveWidth />
+ * </ContextLayout>
+ * ```
+ */
+export declare function ContextLayout({ children, context, position, contextSize, gap, className, style, }: ContextLayoutProps): React.JSX.Element;
+export declare namespace ContextLayout {
+    var displayName: string;
+}

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/statisticalOverlays.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Statistical overlay processing for LineChart.
+ *
+ * Two modes:
+ *   **Auto mode** — provide `trainEnd` + optional `steps`/`confidence`.
+ *     The module computes regression, generates forecast points, and builds
+ *     annotations (envelope, anomaly band, boundary line).
+ *
+ *   **Pre-computed mode** — provide field accessors (`isTraining`, `isForecast`,
+ *     `isAnomaly`, `upperBounds`, `lowerBounds`). The module reads segment/bounds
+ *     from the data and generates annotations without any statistical computation.
+ *     Use this when bounds come from an external ML model.
+ */
+export interface AnomalyConfig {
+    /** Standard deviation multiplier for anomaly bounds. Default: 2 */
+    threshold?: number;
+    /** Show shaded anomaly band. Default: true */
+    showBand?: boolean;
+    /** Band fill color. Default: "#6366f1" */
+    bandColor?: string;
+    /** Band fill opacity. Default: 0.1 */
+    bandOpacity?: number;
+    /** Outlier dot color. Default: "#ef4444" */
+    anomalyColor?: string;
+    /** Outlier dot radius. Default: 6 */
+    anomalyRadius?: number;
+    /** Label for the band */
+    label?: string;
+}
+export interface ForecastConfig {
+    /** X-value where training data ends. Required for auto mode. */
+    trainEnd?: number;
+    /** Number of forecast steps beyond last data point. Default: 10 */
+    steps?: number;
+    /** Regression method. Default: "linear" */
+    method?: "linear" | "loess";
+    /** LOESS bandwidth (only for method="loess"). Default: 0.3 */
+    bandwidth?: number;
+    /** Confidence level for prediction interval (0-1). Default: 0.95 */
+    confidence?: number;
+    /** Field or function marking training data points */
+    isTraining?: string | ((d: Record<string, any>) => boolean);
+    /** Field or function marking forecast data points */
+    isForecast?: string | ((d: Record<string, any>) => boolean);
+    /** Field or function marking anomalous data points */
+    isAnomaly?: string | ((d: Record<string, any>) => boolean);
+    /** Field or function for upper envelope bound per data point */
+    upperBounds?: string | ((d: Record<string, any>) => number);
+    /** Field or function for lower envelope bound per data point */
+    lowerBounds?: string | ((d: Record<string, any>) => number);
+    /** Color for forecast line and envelope. Default: "#6366f1" */
+    color?: string;
+    /** Envelope fill opacity. Default: 0.15 */
+    bandOpacity?: number;
+    /** Dash pattern for training line segment. Default: "8,4" */
+    trainDasharray?: string;
+    /** Dash pattern for forecast line segment. Default: "4,4" */
+    forecastDasharray?: string;
+    /** Outlier dot color (pre-computed mode). Default: "#ef4444" */
+    anomalyColor?: string;
+    /** Outlier dot radius (pre-computed mode). Default: 6 */
+    anomalyRadius?: number;
+    /** Label for the forecast/envelope region */
+    label?: string;
+}
+/** Internal segment marker added to each datum */
+export declare const SEGMENT_FIELD: "__forecastSegment";
+export type SegmentType = "training" | "observed" | "forecast";
+export declare function buildAnomalyAnnotations(config: AnomalyConfig): Record<string, any>[];
+interface ForecastResult {
+    processedData: Record<string, any>[];
+    annotations: Record<string, any>[];
+}
+export declare function buildForecast(data: Record<string, any>[], xAccessor: string, yAccessor: string, forecastConfig: ForecastConfig, anomalyConfig?: AnomalyConfig): ForecastResult;
+export declare function createSegmentLineStyle(baseStyle: (d: Record<string, any>) => Record<string, any>, forecastConfig: ForecastConfig): (d: Record<string, any>) => Record<string, any>;
+export {};

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

@@ -50,6 +50,10 @@ export interface BaseChartProps {
     height?: number;
     /** Margin around the chart. Can be number (same on all sides) or object specifying each side */
     margin?: MarginType;
+    /** Auto-match width to parent container. Default: false */
+    responsiveWidth?: boolean;
+    /** Auto-match height to parent container (requires parent with explicit height). Default: false */
+    responsiveHeight?: boolean;
     /** CSS class name for the chart container */
     className?: string;
     /** Chart title displayed at the top */

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 {};