semiotic 3.7.5 → 3.8.1

package/agent-skill/semiotic-charts/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: semiotic-charts
+description: Generate trustworthy, accessible, agent-legible charts with Semiotic. Use whenever you produce a data visualization in a React/TypeScript app, stream a chart as generative UI, or pick a chart type for a dataset. Emit a validated config and run the trust loop — never hand-write chart JSX that breaks on first paint.
+---
+
+# Generating charts with Semiotic
+
+Semiotic is a React data-visualization library whose differentiator is **trust**:
+generation is cheap, but a chart that renders, that a screen-reader user can
+receive, and that carries its own provenance is scarce. This skill is the
+workflow for producing one.
+
+The cardinal rule: **do not hand-write chart JSX and hope it paints.** Emit a
+`{ component, props }` proposal and run it through the trust loop, which is
+validated and diagnosed; when a renderer is available, proven to paint. Otherwise it returns reasons and ranked alternatives to retry with.
+
+## The trust loop — generate → validate → diagnose → repair → prove
+
+`prepareChart` (from `semiotic/ai`) composes the whole loop. Call it on every
+proposal before you show or stream a chart:
+
+```ts
+import { prepareChart } from "semiotic/ai"
+
+const result = prepareChart(
+  { component: "BarChart", props: { data, categoryAccessor: "region", valueAccessor: "revenue" } },
+  { data } // supply the data so a poor chart→data fit is caught and alternatives ranked
+)
+
+if (result.ok) {
+  // result.jsx is a ready JSX string; result.config is the serializable ChartConfig
+} else {
+  // result.reasons explains why; result.repair.alternatives ranks better charts.
+  // Retry with a fixed prop or a suggested component — do NOT paint.
+}
+```
+
+`result` carries `{ ok, config, jsx, validation, diagnostics, repair?, reasons }`.
+In a server/SSR context you can inject `render: renderChartWithEvidence` (from
+`semiotic/server`) so the loop also *proves the scene is non-empty* and reads back
+render evidence (mark count, domains, ARIA label) — the first-try oracle.
+
+### As an agent tool
+
+`chartGenerationTool()` returns a framework-agnostic JSON-Schema tool definition;
+`toAnthropicTool`, `toOpenAITool` (Chat Completions), and
+`toOpenAIResponsesTool` (Responses API) shape it for provider APIs. Vercel AI SDK
+and LangChain accept the same JSON Schema. `createChartToolHandler(optionsFor)` is
+the execute step. No vendor SDK is required. For backend-only use, import these
+helpers from `semiotic/ai/core` to avoid the chart-HOC catalog.
+
+### Picking a chart for a dataset
+
+When you don't know which chart fits, ask the data, not your priors:
+
+```ts
+import { suggestCharts } from "semiotic/ai"
+const ranked = suggestCharts(data, { intent: "trend", maxResults: 3, audience })
+// ranked[0].props is spreadable straight into the component.
+```
+
+`intent` is one of: `trend`, `compare-series`, `compare-categories`, `rank`,
+`part-to-whole`, `distribution`, `correlation`, `flow`, `hierarchy`, `geo`,
+`outlier-detection`, `composition-over-time`, `change-detection`.
+
+## Hard rules (the behavior contracts)
+
+These are enforced by validation and the `npx semiotic-ai --doctor` gate. Honor
+them in every proposal:
+
+1. **Sub-path imports.** Import from the family entry point, not the barrel:
+   `semiotic/xy`, `semiotic/ordinal`, `semiotic/network`, `semiotic/geo`,
+   `semiotic/realtime`, `semiotic/ai`. The full `semiotic` is large; a family
+   entry point is a fraction of it.
+2. **Static usage requires data in props.** `renderChart`, SSR snapshots, and any
+   copy-paste example need `data` (or `nodes`/`edges`) present.
+3. **Push (live) mode omits `data` entirely.** Create a ref, do NOT pass
+   `data={[]}` (that clears the chart on every render), then call
+   `ref.current.push(row)` / `pushMany(rows)`. `remove(id)` / `update(id, fn)`
+   require a stable id accessor (`pointIdAccessor` for XY, `dataIdAccessor` for
+   ordinal, `nodeIDAccessor`/`edgeIdAccessor` for network).
+4. **Required prop combinations.** Beyond data, some families need a semantic
+   prop, in static *and* push mode: StackedAreaChart→`areaBy`,
+   StackedBarChart→`stackBy`, GroupedBarChart→`groupBy`, BubbleChart→`sizeBy`,
+   SwimlaneChart→`subcategoryAccessor`, GaugeChart→`value` (value-only, no push),
+   ForceDirectedGraph→materialized `nodes` + `edges` (don't infer nodes from edge
+   endpoints).
+5. **Categorical color via `colorBy`** (a field name), shared across charts with
+   `CategoryColorProvider` / `LinkedCharts`; fall back to `colorScheme`. Don't
+   reach for `frameProps` style functions to color by category.
+6. **`renderChart` (MCP / `semiotic/server`) is a single static snapshot.** It
+   can't push later. For live behavior, return React code with a ref.
+
+## What good output looks like
+
+```tsx
+import { LineChart } from "semiotic/xy"
+
+<LineChart
+  data={series}
+  xAccessor="date"
+  yAccessor="value"
+  xScaleType="time"
+  title="Weekly active users"
+  showPoints
+/>
+```
+
+Annotations carry provenance and lifecycle — when you mark a point, say who/why:
+
+```ts
+import { withProvenance } from "semiotic/ai"
+const note = withProvenance(
+  { type: "callout", x: "2026-W14", y: 9, label: "Deploy-correlated spike" },
+  { provenance: { authorKind: "agent", basis: "statistical-test", confidence: 0.78 },
+    lifecycle: { ttlHint: "P7D", status: "proposed" } }
+)
+```
+
+## Tooling
+
+- **MCP server:** `npx semiotic-mcp` — tools for `renderChart` (SVG + render
+  evidence), `suggestCharts`, `groundChart`, `diagnoseConfig`, `repairChartConfig`,
+  `proposeChartVariants`, and more. Prefer these over guessing.
+- **Public app profile:** `npx semiotic-mcp --profile public` exposes the five
+  task-oriented tools `createChart`, `improveChart`, `explainChart`,
+  `auditChart`, and `getChartSchema`; use it when tool discovery matters more
+  than expert-level control.
+- **CLI gate:** `npx semiotic-ai --doctor` validates a `{ component, props }` JSON
+  (`--audit-a11y` for an accessibility audit). Run it before shipping generated code.
+- **Machine-readable docs:** the published `llms.txt` is the chart catalog with
+  per-chart communicative-act labels; read it for the full surface rather than
+  guessing component names.
+- **Portable install:** `npx semiotic-ai --skill` prints this packaged skill so a
+  compatible agent host can install it at its documented skill location. The
+  npm package includes `agent-skill/semiotic-charts/SKILL.md` for offline use.
+
+## Don't
+
+- Don't hand-write chart JSX without running `prepareChart` or `--doctor`.
+- Don't import charts from the bare `semiotic` barrel in production code.
+- Don't pass `data={[]}` for live charts (use push mode — omit `data`).
+- Don't promise live/interactive behavior from `renderChart` — it's a static snapshot.
+- Don't invent a component name; if no chart fits, say so and surface alternatives
+  (`suggestCharts` / `repairChartConfig`) — a wrong chart deceives the reader who
+  can least afford it.

package/ai/cli.js

@@ -28,6 +28,7 @@ const FILES = {
   "--schema": path.join(__dirname, "schema.json"),
   "--compact": path.join(__dirname, "system-prompt.md"),
   "--examples": path.join(__dirname, "examples.md"),
+  "--skill": path.join(pkgRoot, "agent-skill", "semiotic-charts", "SKILL.md"),
 }
 
 function errorMessage(err) {
@@ -47,8 +48,11 @@ Usage:
   npx semiotic-ai --suggest     Recommend charts from { data, intent? } JSON
   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 --skill      Print the portable Semiotic Agent Skill
   npx semiotic-ai --doctor     Validate { component, props, usageMode? } JSON from stdin
+                                (exits nonzero on errors; add --json for a machine-readable report)
   npx semiotic-ai --audit-a11y Audit { component, props, inChartContainer?, describe?, navigable? }
+  npx semiotic-ai --audit-mobile Audit { component, props, viewportWidth?, targetSize?, inChartContainer? }
                                 JSON against Chartability (POUR-CAF) accessibility heuristics
   npx semiotic-ai --help       Show this help message
 `.trim()
@@ -186,8 +190,15 @@ function validatePropsWithSchema(componentName, props, usageMode = "static") {
       continue
     }
 
-    if (propSchema.type && !schemaTypeMatches(value, propSchema.type)) {
-      const expected = Array.isArray(propSchema.type) ? propSchema.type.join(" | ") : propSchema.type
+    // Prefer the full runtime type surface (`x-semiotic-runtime-types`, e.g.
+    // ["string","function"]) over the wire-only `type` ("string"), so a valid
+    // function value for a prop like `colorBy`/`onBrush` is still accepted. The
+    // wire `type` keyword is standards-valid JSON Schema and never lists
+    // "function"; the runtime extension carries it. Falls back to `type` for
+    // props with no runtime-only alternatives.
+    const effectiveType = propSchema["x-semiotic-runtime-types"] || propSchema.type
+    if (effectiveType && !schemaTypeMatches(value, effectiveType)) {
+      const expected = Array.isArray(effectiveType) ? effectiveType.join(" | ") : effectiveType
       errors.push(`"${propName}" should be ${expected}, got ${describeActualType(value)}.`)
     }
 
@@ -202,6 +213,8 @@ function validatePropsWithSchema(componentName, props, usageMode = "static") {
   }
 }
 
+// Returns true when the schema-only validation passed, so the caller can set
+// the process exit code (nonzero on failure — this is a CI gate).
 function printSchemaOnlyDoctorResult(component, props, usageMode) {
   const result = validatePropsWithSchema(component, props, usageMode)
   if (usageMode === "push") {
@@ -216,6 +229,7 @@ function printSchemaOnlyDoctorResult(component, props, usageMode) {
     }
   }
   printDoctorBehaviorContracts(component, props)
+  return result.valid
 }
 
 function printDoctorBehaviorContracts(component, props) {
@@ -229,8 +243,11 @@ function printDoctorBehaviorContracts(component, props) {
 }
 
 function readJSONInput(usage) {
-  if (process.argv[3]) {
-    return process.argv.slice(3).join(" ")
+  // Skip flag tokens (e.g. `--json`) so `--doctor --json` still reads the JSON
+  // from stdin rather than trying to parse the flag as the input.
+  const positional = process.argv.slice(3).filter((arg) => !arg.startsWith("--"))
+  if (positional.length > 0) {
+    return positional.join(" ")
   }
   if (!process.stdin.isTTY) {
     return fs.readFileSync(0, "utf-8")
@@ -255,6 +272,11 @@ if (flag === "--schema" && process.argv[3]) {
   process.exit(0)
 }
 
+if (flag === "--skill") {
+  console.log(fs.readFileSync(FILES["--skill"], "utf-8"))
+  process.exit(0)
+}
+
 if (flag === "--suggest") {
   const input = readJSONInput("Usage: npx semiotic-ai --suggest '{\"data\":[{\"category\":\"A\",\"value\":10}],\"intent\":\"comparison\"}'")
   try {
@@ -272,10 +294,15 @@ if (flag === "--suggest") {
 if (flag === "--doctor") {
   const input = readJSONInput("Usage: npx semiotic-ai --doctor '{\"component\":\"LineChart\",\"props\":{\"data\":[...]},\"usageMode\":\"static\"}'\n       echo '{\"component\":\"LineChart\",\"props\":{\"xAccessor\":\"x\",\"yAccessor\":\"y\"},\"usageMode\":\"push\"}' | npx semiotic-ai --doctor")
 
+  // `--json` emits a stable machine-readable report instead of the human text.
+  const asJson = process.argv.includes("--json")
+
   try {
     const { component, props, usageMode: rawUsageMode } = JSON.parse(input)
     if (!component || !props) {
-      console.error("Input must be JSON with { component, props } fields.")
+      const msg = "Input must be JSON with { component, props } fields."
+      if (asJson) console.log(JSON.stringify({ ok: false, error: msg }, null, 2))
+      else console.error(msg)
       process.exit(1)
     }
     const usageMode = normalizeUsageMode(rawUsageMode)
@@ -294,68 +321,88 @@ if (flag === "--doctor") {
       // packaged schema so the CLI still catches basic agent mistakes.
     }
 
-    if (!diagnoseConfig && !validateProps) {
-      printSchemaOnlyDoctorResult(component, props, usageMode)
-      process.exit(0)
-    }
+    // Tracks whether the doctor found any error-level problem. The process
+    // MUST exit nonzero when this is false so CI/agents can gate on it.
+    let ok
 
-    if (diagnoseConfig) {
+    if (!diagnoseConfig && !validateProps) {
+      if (asJson) {
+        const result = validatePropsWithSchema(component, props, usageMode)
+        ok = result.valid
+        console.log(JSON.stringify({ component, usageMode, mode: "schema-only", ok, errors: result.errors }, null, 2))
+      } else {
+        ok = printSchemaOnlyDoctorResult(component, props, usageMode)
+      }
+    } else if (diagnoseConfig) {
       // Use the full anti-pattern detector
       const result = diagnoseConfig(component, props)
       const diagnoses = usageMode === "push"
         ? result.diagnoses.filter((d) => d.code !== "VALIDATION" || !shouldSkipMissingRequiredProp(component, "data", usageMode) || d.message !== `"data" is required for ${component}.`)
         : result.diagnoses
-      const ok = diagnoses.every((d) => d.severity === "warning")
-
-      if (usageMode === "push") {
-        console.log(`  Usage mode: push (data prop may be omitted; use a ref to push data)`)
-      }
+      ok = diagnoses.every((d) => d.severity === "warning")
 
-      // Show data shape summary
-      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 (asJson) {
+        console.log(JSON.stringify({ component, usageMode, mode: "diagnose", ok, diagnoses }, null, 2))
+      } else {
+        if (usageMode === "push") {
+          console.log(`  Usage mode: push (data prop may be omitted; use a ref to push data)`)
+        }
 
-      if (ok && diagnoses.length === 0) {
-        console.log(`✓ ${component}: configuration looks good.`)
-      } else if (ok) {
-        console.log(`✓ ${component}: configuration OK with warnings:`)
-        for (const d of diagnoses) {
-          console.log(`  ⚠ [${d.code}] ${d.message}`)
-          if (d.fix) console.log(`    Fix: ${d.fix}`)
+        // Show data shape summary
+        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(", ")}]`)
         }
-      } else {
-        console.log(`✗ ${component}: issues detected.`)
-        for (const d of diagnoses) {
-          const icon = d.severity === "error" ? "✗" : "⚠"
-          console.log(`  ${icon} [${d.code}] ${d.message}`)
-          if (d.fix) console.log(`    Fix: ${d.fix}`)
+
+        if (ok && diagnoses.length === 0) {
+          console.log(`✓ ${component}: configuration looks good.`)
+        } else if (ok) {
+          console.log(`✓ ${component}: configuration OK with warnings:`)
+          for (const d of diagnoses) {
+            console.log(`  ⚠ [${d.code}] ${d.message}`)
+            if (d.fix) console.log(`    Fix: ${d.fix}`)
+          }
+        } else {
+          console.log(`✗ ${component}: issues detected.`)
+          for (const d of diagnoses) {
+            const icon = d.severity === "error" ? "✗" : "⚠"
+            console.log(`  ${icon} [${d.code}] ${d.message}`)
+            if (d.fix) console.log(`    Fix: ${d.fix}`)
+          }
         }
+        printDoctorBehaviorContracts(component, props)
       }
-      printDoctorBehaviorContracts(component, props)
     } else {
       // Fallback to validateProps only
       const result = validateProps(component, props)
       const errors = filterUsageModeErrors(component, result.errors, usageMode)
-      if (usageMode === "push") {
-        console.log(`  Usage mode: push (data prop may be omitted; use a ref to push data)`)
-      }
-      if (errors.length === 0) {
-        console.log(`✓ ${component}: props are valid.`)
+      ok = errors.length === 0
+      if (asJson) {
+        console.log(JSON.stringify({ component, usageMode, mode: "validate", ok, errors }, null, 2))
       } else {
-        console.log(`✗ ${component}: validation failed.`)
-        for (const err of errors) {
-          console.log(`  • ${err}`)
+        if (usageMode === "push") {
+          console.log(`  Usage mode: push (data prop may be omitted; use a ref to push data)`)
         }
+        if (ok) {
+          console.log(`✓ ${component}: props are valid.`)
+        } else {
+          console.log(`✗ ${component}: validation failed.`)
+          for (const err of errors) {
+            console.log(`  • ${err}`)
+          }
+        }
+        printDoctorBehaviorContracts(component, props)
       }
-      printDoctorBehaviorContracts(component, props)
     }
+
+    // Exit nonzero when an error-level problem was found (warnings still exit 0).
+    process.exit(ok ? 0 : 1)
   } catch (err) {
-    console.error(`Failed to parse input: ${errorMessage(err)}`)
+    const msg = `Failed to parse input: ${errorMessage(err)}`
+    if (asJson) console.log(JSON.stringify({ ok: false, error: msg }, null, 2))
+    else console.error(msg)
     process.exit(1)
   }
-  process.exit(0)
 }
 
 // --audit-a11y: grade component + props against Chartability heuristics
@@ -397,6 +444,47 @@ if (flag === "--audit-a11y") {
   }
 }
 
+// --audit-mobile: grade component + props for mobile visualization risks
+if (flag === "--audit-mobile") {
+  const input = readJSONInput("Usage: npx semiotic-ai --audit-mobile '{\"component\":\"LineChart\",\"props\":{\"data\":[...],\"xAccessor\":\"x\",\"yAccessor\":\"y\"},\"viewportWidth\":390}'\n       echo '{\"component\":\"Scatterplot\",\"props\":{...},\"targetSize\":44}' | npx semiotic-ai --audit-mobile")
+
+  try {
+    const { component, props, viewportWidth, targetSize, inChartContainer } = JSON.parse(input)
+    if (!component || !props) {
+      console.error("Input must be JSON with { component, props } fields.")
+      process.exit(1)
+    }
+
+    const distPath = path.join(pkgRoot, "dist", "semiotic-ai.min.js")
+    let auditMobileVisualization, formatMobileVisualizationAudit
+    try {
+      if (!process.env.SEMIOTIC_AI_SCHEMA_ONLY) {
+        const mod = require(distPath)
+        auditMobileVisualization = mod.auditMobileVisualization
+        formatMobileVisualizationAudit = mod.formatMobileVisualizationAudit
+      }
+    } catch (e) {
+      // Dist unavailable.
+    }
+
+    if (!auditMobileVisualization || !formatMobileVisualizationAudit) {
+      console.error("Mobile visualization audit requires the built library. Run `npm run dist` first, or use the MCP `auditMobileVisualization` tool.")
+      process.exit(2)
+    }
+
+    const result = auditMobileVisualization(component, props, {
+      viewportWidth: typeof viewportWidth === "number" ? viewportWidth : undefined,
+      targetSize: typeof targetSize === "number" ? targetSize : undefined,
+      inChartContainer: inChartContainer === true,
+    })
+    console.log(formatMobileVisualizationAudit(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", "value"]
+const CATEGORY_ORDER = ["xy", "ordinal", "network", "geo", "realtime", "physics", "value"]
 
 const COMPONENTS_BY_CATEGORY = {
   xy: [
@@ -24,6 +24,10 @@ const COMPONENTS_BY_CATEGORY = {
     "RealtimeLineChart", "RealtimeHistogram", "TemporalHistogram", "RealtimeSwarmChart",
     "RealtimeWaterfallChart", "RealtimeHeatmap",
   ],
+  physics: [
+    "GaltonBoardChart", "EventDropChart", "PhysicsPileChart", "CollisionSwarmChart",
+    "PhysicalFlowChart", "ProcessFlowChart", "GauntletChart",
+  ],
   value: [
     "BigNumber",
   ],
@@ -49,6 +53,7 @@ function categoryForComponent(name) {
 }
 
 function importPathForCategory(category) {
+  if (category === "physics") return "semiotic/physics"
   return category === "geo" ? "semiotic/geo" : `semiotic/${category}`
 }