semiotic 3.5.4 → 3.7.0

package/README.md

@@ -35,7 +35,7 @@ generate correct code without examples.
 Semiotic ships with everything an AI coding assistant needs to generate
 correct visualizations without trial and error:
 
-- **`semiotic/ai`** — a single import with 41 HOC charts (XY, ordinal, network, realtime), optimized for LLM code generation. Geo charts are in `semiotic/geo` to keep d3-geo out of non-geo bundles.
+- **`semiotic/ai`** — a single import with the 47-chart capability catalog (XY, ordinal, network, realtime, geo, value), optimized for LLM code generation. Prefer family subpaths such as `semiotic/xy`, `semiotic/geo`, and `semiotic/value` when bundle size matters.
 - **`ai/schema.json`** — machine-readable prop schemas for every component
 - **`npx semiotic-mcp`** — an MCP server for tool-based chart rendering in any MCP client
 - **`npx semiotic-ai --doctor`** — validate component + props JSON from the command line with typo suggestions and anti-pattern detection
@@ -71,6 +71,13 @@ with d3-geo projections, zoom/pan, tile basemaps, and drag-rotate globe spinning
 LOESS smoothing, forecast with confidence envelopes, and anomaly detection.
 Marginal distribution graphics on scatterplot axes with a single prop.
 
+**First-class annotations.** Annotations are data-bound objects, not post-hoc
+artwork. Labels, callouts, thresholds, enclosures, statistical overlays, and
+React widgets move with the chart and render through browser, SSR, and export
+paths. Opt into placement, hierarchy, density, progressive disclosure,
+audience-aware amount, provenance, and editorial lifecycle when the chart
+needs to communicate more than its encoding alone.
+
 ### Start simple, go deep
 
 | Layer | For | Example |
@@ -278,6 +285,27 @@ configToJSX(config)
 Supports bar, line, area, point, rect, arc, tick marks with encoding translation
 for color, size, aggregation, and binning.
 
+### Conversation Arc Telemetry
+
+Capture and replay the path an AI-assisted chart session took:
+
+```ts
+import {
+  createLocalStorageConversationArcSink,
+  enableConversationArc,
+  getConversationArcStore,
+  loadConversationArc,
+  registerConversationArcSink,
+} from "semiotic/ai"
+
+const sink = createLocalStorageConversationArcSink({ key: "my-app:arc" })
+registerConversationArcSink(sink)
+enableConversationArc({ sessionId: "session-abc" })
+
+getConversationArcStore().record({ type: "chart-rendered", component: "LineChart" })
+loadConversationArc(sink.load(), { enabled: false })
+```
+
 ## Bundle Sizes
 
 Semiotic ships 12 entry points. **Don't import from `"semiotic"` unless you need everything** — use the sub-path that matches your chart type:
@@ -287,18 +315,19 @@ Semiotic ships 12 entry points. **Don't import from `"semiotic"` unless you need
 
 | Entry Point | gzip | What's inside |
 |---|---|---|
-| `semiotic/xy` | **85 KB** | LineChart, AreaChart, Scatterplot, Heatmap, + 8 more XY charts |
-| `semiotic/ordinal` | **69 KB** | BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts |
-| `semiotic/network` | **63 KB** | ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4 more |
-| `semiotic/geo` | **52 KB** | ChoroplethMap, FlowMap, DistanceCartogram, ProportionalSymbolMap |
-| `semiotic/realtime` | **90 KB** | RealtimeLineChart, RealtimeHistogram, + 3 streaming charts |
-| `semiotic/server` | **122 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
-| `semiotic/utils` | **22 KB** | ThemeProvider, validators, serialization — no chart components |
-| `semiotic/recipes` | **5 KB** | Pure layout functions (waffle, marimekko, flextree, dagre, …) |
+| `semiotic/xy` | **90 KB** | LineChart, AreaChart, Scatterplot, Heatmap, + 8 more XY charts |
+| `semiotic/ordinal` | **74 KB** | BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts |
+| `semiotic/network` | **68 KB** | ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4 more |
+| `semiotic/geo` | **55 KB** | ChoroplethMap, FlowMap, DistanceCartogram, ProportionalSymbolMap |
+| `semiotic/realtime` | **95 KB** | RealtimeLineChart, RealtimeHistogram, + 4 streaming charts |
+| `semiotic/server` | **127 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
+| `semiotic/utils` | **37 KB** | ThemeProvider, validators, serialization — no chart components |
+| `semiotic/recipes` | **9 KB** | Pure layout functions (waffle, marimekko, flextree, dagre, …) |
 | `semiotic/themes` | **4 KB** | Theme presets only (tufte, carbon, etc.) |
 | `semiotic/data` | **3 KB** | bin, rollup, groupBy, pivot, fromVegaLite |
-| `semiotic/ai` | **189 KB** | All 41 HOCs + validation — optimized for LLM code generation |
-| `semiotic` | **188 KB** | Everything below (full bundle) |
+| `semiotic/value` | **6 KB** | BigNumber — focal-value KPI / scorecard (SingleValueFrame POC) |
+| `semiotic/ai` | **246 KB** | All 47 schema-backed charts + validation — optimized for LLM code generation |
+| `semiotic` | **203 KB** | Everything below (full bundle) |
 
 <!-- semiotic-bundle-sizes:end -->
 
@@ -389,8 +418,14 @@ No API keys or authentication required. The server runs locally via stdio. HTTP
 | 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 45 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. |
+| **`getSchema`** | Return the prop schema for a specific component. Pass `{ component: "LineChart" }` to get its props, or omit `component` to list all 47 chart schemas. Components marked `[renderable]` are available through `renderChart`; realtime charts require a browser/live environment. |
+| **`suggestChart`** | Legacy sample-row recommender. Pass `{ data: [{...}, ...] }` with 1–5 sample objects plus optional broad intent/capability filters. |
+| **`suggestCharts`** | Capability-based recommender for bounded row data. Returns ranked chart suggestions with scores, reasons, caveats, import paths, and ready-to-use props. |
+| **`suggestStreamCharts`** | Recommend realtime charts from a stream schema, throughput, and retention hints. |
+| **`suggestDashboard`** | Build a multi-panel dashboard suggestion that covers distinct analytical intents. |
+| **`suggestStretchCharts`** | Recommend audience-literacy stretch picks from an `AudienceProfile`. |
+| **`repairChartConfig`** | Check whether a requested chart fits a dataset and return ranked alternatives when it does not. |
+| **`interrogateChart`** | Return a statistical summary and chart-aware context for answering natural-language questions with optional annotations. |
 | **`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" }`. |
@@ -401,6 +436,7 @@ No API keys or authentication required. The server runs locally via stdio. HTTP
 |----------|-------------|
 | **`semiotic://schema`** | Full machine-readable component schema JSON. |
 | **`semiotic://components`** | Component index showing renderable/browser-only status and MCP categories. |
+| **`semiotic://behavior-contracts`** | Agent-visible semantic rules for color precedence, required prop combinations, push refs, and renderability. |
 | **`semiotic://system-prompt`** | Compact AI instructions with import rules, chart props, SSR guidance, and pitfalls. |
 | **`semiotic://examples`** | Copy-paste chart examples by data shape. |
 
@@ -502,7 +538,7 @@ Semiotic is indexed by AI-coding-agent documentation tools so your assistant (Cl
 
 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 (45 charts); `ai/behaviorContracts.cjs` carries the agent-visible semantic rules (color precedence, push-mode requirements, ID-accessor contracts).
+- **`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 (47 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
@@ -512,7 +548,8 @@ Agent-facing API surface:
 - [Getting Started](https://semiotic.nteract.io/getting-started)
 - [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
+- [Features](https://semiotic.nteract.io/features) — axes, tooltips, interaction, responsive behavior, and composition
+- [Annotations](https://semiotic.nteract.io/annotations) — first-class annotation types, design guidance, provenance, and lifecycle
 - [Cookbook](https://semiotic.nteract.io/cookbook) — advanced patterns and recipes
 - [Playground](https://semiotic.nteract.io/playground) — interactive prop exploration
 

package/ai/cli.js

@@ -48,6 +48,8 @@ Usage:
   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, usageMode? } JSON from stdin
+  npx semiotic-ai --audit-a11y Audit { component, props, inChartContainer?, describe?, navigable? }
+                                JSON against Chartability (POUR-CAF) accessibility heuristics
   npx semiotic-ai --help       Show this help message
 `.trim()
 
@@ -341,6 +343,45 @@ if (flag === "--doctor") {
   process.exit(0)
 }
 
+// --audit-a11y: grade component + props against Chartability heuristics
+if (flag === "--audit-a11y") {
+  const input = readJSONInput("Usage: npx semiotic-ai --audit-a11y '{\"component\":\"LineChart\",\"props\":{\"data\":[...],\"xAccessor\":\"x\",\"yAccessor\":\"y\"}}'\n       echo '{\"component\":\"BarChart\",\"props\":{...},\"inChartContainer\":true}' | npx semiotic-ai --audit-a11y")
+
+  try {
+    const { component, props, inChartContainer, describe, navigable } = JSON.parse(input)
+    if (!component || !props) {
+      console.error("Input must be JSON with { component, props } fields.")
+      process.exit(1)
+    }
+
+    // Load the audit from dist (same strategy as --doctor). It lives in the
+    // semiotic/ai bundle; a clean source checkout without a build can't run it.
+    const distPath = path.join(pkgRoot, "dist", "semiotic-ai.min.js")
+    let auditAccessibility, formatAccessibilityAudit
+    try {
+      if (!process.env.SEMIOTIC_AI_SCHEMA_ONLY) {
+        const mod = require(distPath)
+        auditAccessibility = mod.auditAccessibility
+        formatAccessibilityAudit = mod.formatAccessibilityAudit
+      }
+    } catch (e) {
+      // Dist unavailable.
+    }
+
+    if (!auditAccessibility || !formatAccessibilityAudit) {
+      console.error("Accessibility audit requires the built library. Run `npm run dist` first, or use the MCP `auditAccessibility` tool.")
+      process.exit(2)
+    }
+
+    const result = auditAccessibility(component, props, { inChartContainer: inChartContainer === true, describe: describe === true, navigable: navigable === true })
+    console.log(formatAccessibilityAudit(result))
+    process.exit(result.ok ? 0 : 1)
+  } catch (err) {
+    console.error(`Failed to parse input: ${errorMessage(err)}`)
+    process.exit(1)
+  }
+}
+
 const filePath = flag ? FILES[flag] : FILES.default
 
 if (!filePath) {

package/ai/componentMetadata.cjs

@@ -1,6 +1,6 @@
 "use strict"
 
-const CATEGORY_ORDER = ["xy", "ordinal", "network", "geo", "realtime"]
+const CATEGORY_ORDER = ["xy", "ordinal", "network", "geo", "realtime", "value"]
 
 const COMPONENTS_BY_CATEGORY = {
   xy: [
@@ -24,6 +24,9 @@ const COMPONENTS_BY_CATEGORY = {
     "RealtimeLineChart", "RealtimeHistogram", "TemporalHistogram", "RealtimeSwarmChart",
     "RealtimeWaterfallChart", "RealtimeHeatmap",
   ],
+  value: [
+    "BigNumber",
+  ],
 }
 
 const COMPONENT_TO_CATEGORY = new Map()
@@ -59,11 +62,17 @@ function metadataForComponent(entryOrName) {
   // any other static HOC. Matches the name-prefix exclusion the
   // check-surface-parity script applies.
   const isPushOnly = category === "realtime" && name.startsWith("Realtime")
+  // Value-family charts (BigNumber, future SingleValueFrame HOCs)
+  // render via react-dom/server in a normal React tree, but they do
+  // not route through the frame-driven `renderChart` path in
+  // serverChartConfigs.ts — so they are not MCP-renderable. Mirrors
+  // the `hoc-ssr-only` special feature documented in chartSpecs.ts.
+  const isValueCategory = category === "value"
   return {
     name,
     category,
     importPath: importPathForCategory(category),
-    renderable: !isPushOnly,
+    renderable: !isPushOnly && !isValueCategory,
     description: typeof entryOrName === "string" ? undefined : entryOrName.description,
   }
 }