semiotic 3.6.0 → 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 42 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` | **86 KB** | LineChart, AreaChart, Scatterplot, Heatmap, + 8 more XY charts |
-| `semiotic/ordinal` | **70 KB** | BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts |
-| `semiotic/network` | **64 KB** | ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4 more |
-| `semiotic/geo` | **52 KB** | ChoroplethMap, FlowMap, DistanceCartogram, ProportionalSymbolMap |
-| `semiotic/realtime` | **91 KB** | RealtimeLineChart, RealtimeHistogram, + 4 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` | **211 KB** | All 42 HOCs + validation — optimized for LLM code generation |
-| `semiotic` | **190 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,7 +418,7 @@ 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 46 chart schemas. Components marked `[renderable]` are available through `renderChart`; realtime charts require a browser/live environment. |
+| **`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. |
@@ -509,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 (46 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
@@ -519,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,
   }
 }

package/ai/dist/mcp-server.js

@@ -6890,7 +6890,7 @@ var require_dist = __commonJS({
 var require_componentMetadata = __commonJS({
   "ai/componentMetadata.cjs"(exports2, module2) {
     "use strict";
-    var CATEGORY_ORDER = ["xy", "ordinal", "network", "geo", "realtime"];
+    var CATEGORY_ORDER = ["xy", "ordinal", "network", "geo", "realtime", "value"];
     var COMPONENTS_BY_CATEGORY = {
       xy: [
         "LineChart",
@@ -6947,6 +6947,9 @@ var require_componentMetadata = __commonJS({
         "RealtimeSwarmChart",
         "RealtimeWaterfallChart",
         "RealtimeHeatmap"
+      ],
+      value: [
+        "BigNumber"
       ]
     };
     var COMPONENT_TO_CATEGORY = /* @__PURE__ */ new Map();
@@ -6972,11 +6975,12 @@ var require_componentMetadata = __commonJS({
       const name = typeof entryOrName === "string" ? entryOrName : entryOrName.name;
       const category = categoryForComponent(name);
       const isPushOnly = category === "realtime" && name.startsWith("Realtime");
+      const isValueCategory = category === "value";
       return {
         name,
         category,
         importPath: importPathForCategory(category),
-        renderable: !isPushOnly,
+        renderable: !isPushOnly && !isValueCategory,
         description: typeof entryOrName === "string" ? void 0 : entryOrName.description
       };
     }
@@ -32643,6 +32647,22 @@ ${contracts}` : msg}` }] };
     isError: true
   };
 }
+async function auditAccessibilityHandler(args) {
+  const component = args.component;
+  const props = args.props ?? {};
+  if (!component) {
+    return {
+      content: [{ type: "text", text: "Missing 'component' field. Provide { component: 'LineChart', props: { ... } }." }],
+      isError: true
+    };
+  }
+  const result = (0, import_ai3.auditAccessibility)(component, props, { inChartContainer: args.inChartContainer === true, describe: args.describe === true, navigable: args.navigable === true });
+  return {
+    content: [{ type: "text", text: (0, import_ai3.formatAccessibilityAudit)(result) }],
+    // Only block on provable critical failures; warnings/manual items are advisory.
+    isError: !result.ok
+  };
+}
 async function reportIssueHandler(args) {
   const title = args.title;
   const body = args.body;
@@ -32743,6 +32763,99 @@ Dark-mode presets: ${THEME_PRESET_NAMES.filter((n) => n.includes("dark")).join("
     content: [{ type: "text", text: usage.join("\n") }]
   };
 }
+function profileInputFromVariantArgs(args) {
+  const props = args.props ?? {};
+  if (Array.isArray(args.data)) {
+    return { data: args.data };
+  }
+  if (Array.isArray(props.data)) {
+    return { data: props.data };
+  }
+  if (Array.isArray(props.nodes) && (Array.isArray(props.edges) || Array.isArray(props.links))) {
+    return {
+      data: [],
+      rawInput: {
+        nodes: props.nodes,
+        edges: props.edges ?? props.links
+      }
+    };
+  }
+  if (props.data && typeof props.data === "object" && !Array.isArray(props.data)) {
+    return { data: [], rawInput: props.data };
+  }
+  return { data: [] };
+}
+function buildVariantProposalProps(proposal, profile, audience) {
+  if (proposal.buildProps) return proposal.buildProps(profile, audience);
+  const capability = (0, import_ai3.getCapability)(proposal.baseComponent);
+  const variant = proposal.variantKey ? capability?.variants?.find((v) => v.key === proposal.variantKey) : void 0;
+  return capability ? capability.buildProps(profile, variant) : {};
+}
+async function proposeChartVariantsHandler(args) {
+  const { component, intent, maxResults, audience } = args;
+  const capability = (0, import_ai3.getCapability)(component);
+  if (!capability) {
+    return {
+      content: [{ type: "text", text: `No chart capability registered for "${component}". Call suggestCharts first to pick from known capability components.` }],
+      isError: true
+    };
+  }
+  const { data, rawInput } = profileInputFromVariantArgs(args);
+  const profile = (0, import_ai3.profileData)(data, { rawInput });
+  const intentArg = Array.isArray(intent) ? intent : intent ? [intent] : void 0;
+  const fitReason = capability.fits(profile);
+  const proposals = (0, import_ai3.proposeVariant)(component, capability, {
+    profile,
+    audience,
+    intent: intentArg,
+    existingVariants: capability.variants
+  });
+  const ranked = proposals.map((proposal) => {
+    const score = (0, import_ai3.evaluateVariantProposal)(proposal, profile, audience, {
+      intent: intentArg,
+      baselineComponent: component
+    });
+    const { buildProps: _buildProps, ...proposalMeta } = proposal;
+    return {
+      proposal: proposalMeta,
+      score,
+      props: buildVariantProposalProps(proposal, profile, audience)
+    };
+  }).sort((a, b) => {
+    if (b.score.fit !== a.score.fit) return b.score.fit - a.score.fit;
+    if (a.score.risk !== b.score.risk) return a.score.risk - b.score.risk;
+    return b.score.novelty - a.score.novelty;
+  }).slice(0, maxResults ?? 8);
+  const lines = [
+    `${ranked.length} variant proposal${ranked.length === 1 ? "" : "s"} for ${component}${intentArg ? ` (intent: ${intentArg.join(", ")})` : ""}:`,
+    ...fitReason ? [`Base chart fit warning: ${fitReason}`] : [],
+    "",
+    ...ranked.map((entry, i) => {
+      const label = entry.proposal.label ?? entry.proposal.variantKey ?? entry.proposal.id;
+      const tags = entry.proposal.tags?.length ? ` [${entry.proposal.tags.join(", ")}]` : "";
+      const reasons = entry.score.reasons.length ? `
+   ${entry.score.reasons.join("; ")}` : "";
+      return `${i + 1}. ${entry.proposal.baseComponent} / ${label}${tags} (fit ${entry.score.fit.toFixed(1)}/5, novelty ${entry.score.novelty.toFixed(2)}, risk ${entry.score.risk.toFixed(2)})${reasons}`;
+    })
+  ];
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+    structuredContent: {
+      component,
+      profile: {
+        rowCount: profile.rowCount,
+        primary: profile.primary,
+        categoryCount: profile.categoryCount ?? null,
+        seriesCount: profile.seriesCount ?? null,
+        hasHierarchy: profile.hasHierarchy,
+        hasNetwork: profile.hasNetwork,
+        hasGeo: profile.hasGeo
+      },
+      fitReason,
+      proposals: ranked
+    }
+  };
+}
 async function suggestChartsHandler(args) {
   const { data, intent, maxResults, allow, deny, audience } = args;
   const intentArg = Array.isArray(intent) ? intent : intent ? [intent] : void 0;
@@ -32903,6 +33016,34 @@ Contextual instructions:
   }
   return { content, structuredContent: { summary, component, props } };
 }
+async function groundChartHandler(args) {
+  const component = args.component;
+  const props = args.props ?? {};
+  if (!component) {
+    return {
+      content: [{ type: "text", text: "Missing 'component' field. Provide { component: 'LineChart', props: { ... } }." }],
+      isError: true
+    };
+  }
+  const capability = (0, import_ai3.getCapability)(component);
+  const grounding = (0, import_ai3.buildReaderGrounding)(component, props, { capability });
+  const nodeCount = grounding.structure ? (0, import_ai3.countNodes)(grounding.structure) : 0;
+  const lines = [
+    `Reader grounding for ${component} \u2014 the payload an agent reads to interpret this chart without seeing it:`,
+    "",
+    `L1\u2013L3 (description): ${grounding.description.text}`,
+    grounding.intent ? `L4 (intent \xB7 ${grounding.intent.act}): ${grounding.intent.sentence}` : "L4 (intent): not resolved (no capability for this component).",
+    "",
+    `Structure: ${nodeCount} navigable node(s) (chart \u2192 axes/series \u2192 datum) in structuredContent.structure.`,
+    "",
+    "Combined text:",
+    grounding.text
+  ];
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+    structuredContent: grounding
+  };
+}
 function createServer2() {
   const srv = new McpServer({
     name: "semiotic",
@@ -33069,6 +33210,18 @@ function createServer2() {
     },
     diagnoseConfigHandler
   );
+  srv.tool(
+    "auditAccessibility",
+    "Audit a Semiotic chart configuration against the Chartability (POUR-CAF) accessibility framework \u2014 Perceivable, Operable, Understandable, Robust, Compromising, Assistive, Flexible. Statically grades the config (no DOM/AT): credits the built-ins every HOC ships (keyboard nav, focus ring, skip link, screen-reader data table, reduced-motion + forced-colors, shareable state), flags author-actionable gaps (missing title/description/summary, low contrast, small text, color-only encoding, undescribed trends, data density), and routes everything that needs real assistive-technology testing to a 'manual' item. Returns a per-principle report with the 14 critical heuristics marked. Pass inChartContainer=true to credit data-download/share affordances. Pair with manual NVDA/JAWS/VoiceOver testing \u2014 Chartability is not a pass/fail certification.",
+    {
+      component: external_exports3.string().describe("Chart component name, e.g. 'LineChart'"),
+      props: external_exports3.record(external_exports3.string(), external_exports3.unknown()).optional().describe("Chart props object, e.g. { data: [...], xAccessor: 'x', title: '...' }."),
+      inChartContainer: external_exports3.boolean().optional().describe("True if the chart is (or will be) wrapped in a ChartContainer exposing data-download/copy-config actions."),
+      describe: external_exports3.boolean().optional().describe("True if ChartContainer's describe option (auto-generated L1\u2013L3 description via describeChart) is enabled \u2014 passes the 'features described' heuristic."),
+      navigable: external_exports3.boolean().optional().describe("True if ChartContainer's navigable option (structured navigation tree via buildNavigationTree) is enabled \u2014 passes the 'navigable structure' heuristic.")
+    },
+    auditAccessibilityHandler
+  );
   srv.tool(
     "reportIssue",
     "Generate a GitHub issue URL for Semiotic bug reports or feature requests. Returns a URL the user can open to submit. For rendering bugs, include the component name, props summary, and any diagnoseConfig output in the body.",
@@ -33097,6 +33250,15 @@ function createServer2() {
     },
     interrogateChartHandler
   );
+  srv.tool(
+    "groundChart",
+    "Build the agent-reader grounding payload for a Semiotic chart: the layered L1\u2013L3 natural-language description, the L4 communicative-act sentence (what the chart is asking the reader to do \u2014 'this is an alerting chart; the spike warrants a closer look'), and a structured navigation tree (chart \u2192 axes/series \u2192 datum). This is the documented thing an LLM reads to interpret a chart faithfully without seeing the pixels \u2014 the reader-side complement to a capability descriptor. The L4 act is resolved from the chart's registered capability. Returns prose plus the full structured payload (description/intent/structure/text).",
+    {
+      component: external_exports3.string().describe("Chart component name, e.g. 'LineChart'"),
+      props: external_exports3.record(external_exports3.string(), external_exports3.unknown()).describe("The full chart props including data")
+    },
+    groundChartHandler
+  );
   srv.tool(
     "suggestStreamCharts",
     "Recommend realtime/streaming Semiotic charts for a schema (not row data). Pass a schema describing field types plus optional throughput ('low'|'medium'|'high') and retention ('windowed'|'cumulative') hints; the engine ranks realtime charts (RealtimeLineChart, RealtimeHistogram, RealtimeHeatmap, RealtimeWaterfallChart, RealtimeSwarmChart, TemporalHistogram) by their fit. Use when the user is wiring up a live dashboard or monitoring view rather than visualizing a bounded dataset.",
@@ -33144,8 +33306,9 @@ function createServer2() {
             reason: external_exports3.string().optional()
           })
         ).optional(),
-        exposureLevel: external_exports3.union([external_exports3.literal(0), external_exports3.literal(1), external_exports3.literal(2)]).optional()
-      }).describe("Audience profile \u2014 familiarity, targets, exposure level."),
+        exposureLevel: external_exports3.union([external_exports3.literal(0), external_exports3.literal(1), external_exports3.literal(2)]).optional(),
+        receptionModality: external_exports3.enum(["visual", "screen-reader", "sonified", "agent"]).optional().describe("Reception channel \u2014 see suggestCharts.")
+      }).describe("Audience profile \u2014 familiarity, targets, exposure level, reception modality."),
       intent: external_exports3.union([external_exports3.string(), external_exports3.array(external_exports3.string())]).optional(),
       maxResults: external_exports3.number().int().min(1).max(20).optional()
     },
@@ -33162,6 +33325,32 @@ function createServer2() {
     },
     repairChartConfigHandler
   );
+  srv.tool(
+    "proposeChartVariants",
+    "Propose and score chart variants for a selected Semiotic component. Uses the capability registry plus heuristic variant discovery: registered variants, conservative transforms, and same-intent cross-family alternatives. Returns ranked proposals with fit/novelty/risk scores, rationale, and ready-to-use props. Use after suggestCharts when an agent wants to actively explore variants rather than stop at the first chart recommendation.",
+    {
+      component: external_exports3.string().describe("Base chart component to vary, e.g. 'LineChart', 'BarChart', or 'BoxPlot'."),
+      props: external_exports3.record(external_exports3.string(), external_exports3.unknown()).optional().describe("Existing chart props. If props.data is present it is profiled; network/hierarchy/geo object data can be passed here as raw input."),
+      data: external_exports3.array(external_exports3.record(external_exports3.string(), external_exports3.unknown())).optional().describe("Row data to profile. Overrides props.data when present."),
+      intent: external_exports3.union([external_exports3.string(), external_exports3.array(external_exports3.string())]).optional().describe("Ranking intent(s), e.g. trend, distribution, rank, compare-categories, composition-over-time."),
+      maxResults: external_exports3.number().int().min(1).max(20).optional().describe("Cap on proposals returned (default 8)."),
+      audience: external_exports3.object({
+        name: external_exports3.string().optional(),
+        familiarity: external_exports3.record(external_exports3.string(), external_exports3.number()).optional(),
+        targets: external_exports3.record(
+          external_exports3.string(),
+          external_exports3.object({
+            direction: external_exports3.enum(["increase", "decrease"]),
+            weight: external_exports3.number().int().min(1).max(3).optional(),
+            reason: external_exports3.string().optional()
+          })
+        ).optional(),
+        exposureLevel: external_exports3.union([external_exports3.literal(0), external_exports3.literal(1), external_exports3.literal(2)]).optional(),
+        receptionModality: external_exports3.enum(["visual", "screen-reader", "sonified", "agent"]).optional().describe("Reception channel \u2014 see suggestCharts.")
+      }).optional().describe("Audience profile \u2014 familiarity, adoption targets, exposure level, and reception modality.")
+    },
+    proposeChartVariantsHandler
+  );
   srv.tool(
     "suggestCharts",
     "Recommend Semiotic charts for a dataset using heuristic capability descriptors. Each chart declares which data shapes it serves and which intents (trend, compare-categories, distribution, correlation, part-to-whole, etc.) it answers \u2014 the engine returns a ranked list with scores, reasons, caveats, and ready-to-use props. Heuristic only; no LLM call. Use the result as structured context when answering 'what chart should I use?' or generating chart code.",
@@ -33170,7 +33359,21 @@ function createServer2() {
       intent: external_exports3.union([external_exports3.string(), external_exports3.array(external_exports3.string())]).optional().describe("Ranking intent. One of: trend, compare-series, compare-categories, rank, part-to-whole, distribution, correlation, flow, hierarchy, geo, outlier-detection, composition-over-time, change-detection. Custom intents accepted."),
       maxResults: external_exports3.number().int().min(1).max(40).optional().describe("Cap on suggestions returned (default 8)."),
       allow: external_exports3.array(external_exports3.string()).optional().describe("Restrict to these component names."),
-      deny: external_exports3.array(external_exports3.string()).optional().describe("Exclude these component names.")
+      deny: external_exports3.array(external_exports3.string()).optional().describe("Exclude these component names."),
+      audience: external_exports3.object({
+        name: external_exports3.string().optional(),
+        familiarity: external_exports3.record(external_exports3.string(), external_exports3.number()).optional(),
+        targets: external_exports3.record(
+          external_exports3.string(),
+          external_exports3.object({
+            direction: external_exports3.enum(["increase", "decrease"]),
+            weight: external_exports3.number().int().min(1).max(3).optional(),
+            reason: external_exports3.string().optional()
+          })
+        ).optional(),
+        exposureLevel: external_exports3.union([external_exports3.literal(0), external_exports3.literal(1), external_exports3.literal(2)]).optional(),
+        receptionModality: external_exports3.enum(["visual", "screen-reader", "sonified", "agent"]).optional().describe("Reception channel. A non-visual value down-ranks charts the audience can't receive in that channel (e.g. a many-slice pie for a screen reader) and adds receivability caveats.")
+      }).optional().describe("Audience profile \u2014 familiarity, adoption targets, exposure level, and reception modality.")
     },
     suggestChartsHandler
   );
@@ -33220,7 +33423,7 @@ async function main() {
     });
     httpServer.listen(port, () => {
       console.error(`Semiotic MCP server (HTTP) listening on http://localhost:${port}`);
-      console.error("Tools: getSchema, suggestChart, suggestCharts, suggestStreamCharts, suggestDashboard, suggestStretchCharts, repairChartConfig, renderChart, interrogateChart, diagnoseConfig, reportIssue, applyTheme");
+      console.error("Tools: getSchema, suggestChart, suggestCharts, proposeChartVariants, suggestStreamCharts, suggestDashboard, suggestStretchCharts, repairChartConfig, renderChart, interrogateChart, groundChart, diagnoseConfig, auditAccessibility, reportIssue, applyTheme");
       console.error("Resources: semiotic://schema, semiotic://components, semiotic://behavior-contracts, semiotic://system-prompt, semiotic://examples");
     });
   } else {

package/ai/examples.md

@@ -1181,3 +1181,101 @@ import { BarChart } from "semiotic/ai"
 ```
 
 Key props: `y-threshold` works on vertical ordinal charts. `category-highlight` highlights a category column. `labelPosition` controls label placement.
+
+---
+
+## Value Charts — One Number Is The Visualization
+
+### BigNumber (KPI tile — comparison + target + threshold zones)
+
+```jsx
+import { BigNumber } from "semiotic/value"
+
+<BigNumber
+  value={1284900}
+  label="Q3 Revenue"
+  caption="Year-to-date bookings"
+  format="currency"
+  precision={0}
+  comparison={{ value: 980000, label: "vs Q2" }}
+  target={{ value: 1500000, label: "Q3 plan" }}
+  thresholds={[
+    { at: -Infinity, level: "danger"  },
+    { at: 1000000,   level: "warning" },
+    { at: 1300000,   level: "success" },
+  ]}
+/>
+```
+
+Key props: `value` (the one number), `format` ("number"|"currency"|"percent"|"compact"|"duration"|fn), `comparison` derives a delta with auto-sentiment, `target` renders "X% of goal", `thresholds` map value to a semantic theme role (`--semiotic-{success|warning|danger|info}`). Suppress chrome via `mode="thumbnail"` for dense grids or `mode="inline"` for prose. Stream via `ref.current.push({ value, time })` — pair with `stalenessThreshold` to dim the card when updates stop.
+
+### BigNumber with a Semiotic chart embedded via `trendSlot` (wide / rectangular)
+
+```jsx
+import { BigNumber } from "semiotic/value"
+import { LineChart } from "semiotic/xy"
+
+<BigNumber
+  value={1284900}
+  label="Q3 Revenue"
+  format="currency"
+  comparison={{ value: 980000, label: "vs Q2" }}
+  trendSlot={(ctx) => (
+    <LineChart
+      data={[820000, 870000, 920000, 1010000, 1120000, 1284900].map((y, x) => ({ x, y }))}
+      xAccessor="x"
+      yAccessor="y"
+      mode="sparkline"
+      width={260}
+      height={32}
+      color={ctx.color}
+    />
+  )}
+/>
+```
+
+Key props: BigNumber ships NO built-in chart renderer. `trendSlot` accepts any ReactNode (or `(ctx) => ReactNode`); pass a `LineChart`/`AreaChart` in `mode="sparkline"` for wide / rectangular charts. The slot context exposes `ctx.color` (resolved threshold colour) so the embedded chart picks up the BigNumber's level for cohesive theming.
+
+### BigNumber with a square Semiotic chart via `chartSlot`
+
+```jsx
+import { BigNumber } from "semiotic/value"
+import { DonutChart } from "semiotic/ordinal"
+
+<BigNumber
+  value={1284900}
+  label="Q3 Revenue by region"
+  format="currency"
+  chartSlot={
+    <DonutChart
+      data={[
+        { region: "NA",   revenue: 540000 },
+        { region: "EU",   revenue: 420000 },
+        { region: "APAC", revenue: 324900 },
+      ]}
+      categoryAccessor="region"
+      valueAccessor="revenue"
+      width={120}
+      height={120}
+      innerRadius={32}
+    />
+  }
+/>
+```
+
+Key props: `chartSlot` is the square-aspect counterpart to `trendSlot`. The card splits horizontally — text content on the left, square chart on the right (DonutChart / PieChart / Scatterplot / Treemap / CirclePack). Pass both `trendSlot` and `chartSlot` to get the square chart on the right and the wide sparkline at the bottom.
+
+### BigNumber (inverted direction — lower is better)
+
+```jsx
+import { BigNumber } from "semiotic/value"
+
+<BigNumber
+  value={486}
+  label="P99 latency"
+  suffix=" ms"
+  comparison={{ value: 410, label: "vs last week", direction: "lower-is-better" }}
+/>
+```
+
+Key props: `direction: "lower-is-better"` flips sentiment colouring — a value that went UP now reads as negative (danger). Same pattern for error rate, churn, complaint count, etc.