semiotic 3.7.0 → 3.7.2

package/CLAUDE.md

@@ -4,7 +4,7 @@
 - Install: `npm install semiotic`
 <!-- semiotic-bundle-sizes:start -->
 <!-- Auto-generated by scripts/sync-bundle-sizes.mjs — do not edit by hand. -->
-- **Use sub-path imports** — `semiotic/xy` (90KB gz), `semiotic/ordinal` (74KB gz), `semiotic/network` (68KB gz), `semiotic/geo` (55KB gz), `semiotic/realtime` (95KB gz), `semiotic/server` (127KB gz), `semiotic/utils` (37KB gz), `semiotic/recipes` (9KB gz), `semiotic/themes` (4KB gz), `semiotic/data` (3KB gz), `semiotic/value` (6KB gz), `semiotic/ai` (246KB gz). Full `semiotic` is 203KB gz.
+- **Use sub-path imports** — `semiotic/xy` (90KB gz), `semiotic/ordinal` (74KB gz), `semiotic/network` (68KB gz), `semiotic/geo` (55KB gz), `semiotic/realtime` (95KB gz), `semiotic/server` (128KB gz), `semiotic/utils` (38KB gz), `semiotic/recipes` (9KB gz), `semiotic/themes` (4KB gz), `semiotic/data` (3KB gz), `semiotic/value` (6KB gz), `semiotic/ai` (250KB gz). Full `semiotic` is 203KB gz.
 <!-- semiotic-bundle-sizes:end -->
 - CLI: `npx semiotic-ai [--schema|--compact|--examples|--doctor|--audit-a11y]` · MCP: `npx semiotic-mcp`
 
@@ -160,9 +160,10 @@ Also: **ScatterplotMatrix**, **ChartContainer** (`title`, `subtitle`, `actions`)
 HOC charts render SVG automatically in server environments. For standalone generation:
 
 ```ts
-import { renderChart, renderToImage, renderToAnimatedGif, renderDashboard } from "semiotic/server"
+import { renderChart, renderChartWithEvidence, renderToImage, renderToAnimatedGif, renderDashboard } from "semiotic/server"
 
 const svg = renderChart("BarChart", { data, categoryAccessor, valueAccessor, theme: "tufte", showLegend, showGrid, annotations })
+const { svg: svg2, evidence } = renderChartWithEvidence("BarChart", { data, categoryAccessor, valueAccessor })  // evidence: { markCount, markCountByType, empty, xDomain?, yDomain?, categories?, nodeCount?, edgeCount?, annotationCount, ariaLabel, warnings } — ground truth from the rendered scene; check `evidence.empty`/`markCount` instead of parsing SVG. MCP renderChart returns the same block.
 const png = await renderToImage("LineChart", { ... }, { format: "png", scale: 2 })  // requires sharp
 const gif = await renderToAnimatedGif("line", data, { xAccessor, yAccessor, theme: "dark" }, { fps: 12, transitionFrames: 4, decay: { type: "linear" } })  // requires sharp + gifenc
 const dashboard = renderDashboard([{ component: "BarChart", props }, { component: "PieChart", colSpan: 2, props }], { title, theme, layout: { columns: 2 } })

package/README.md

@@ -12,6 +12,18 @@ Simple charts in 5 lines. Network graphs, streaming data, and coordinated
 dashboards when you need them. Structured schemas and an MCP server so
 AI coding assistants generate correct chart code on the first try.
 
+## What's New in 3.7.2
+
+3.7.2 is a deployment and docs-polish patch release:
+
+- `semiotic-mcp --http` now runs in stateless Streamable HTTP mode, with JSON responses,
+  health endpoints, optional `MCP_ALLOWED_HOSTS` host-header protection, and serverless-friendly
+  request teardown.
+- `deploy/cloud-run` contains a minimal Google Cloud Run wrapper for publishing the MCP server as a
+  public read-only connector for ChatGPT, Claude, and other MCP clients.
+- The Accessibility docs' visible navigation tree and bidirectional BarChart examples now honor
+  dark mode, and the contested-annotations blog demo renders its editorial-status callouts reliably.
+
 ```jsx
 import { LineChart } from "semiotic/xy"
 
@@ -35,11 +47,11 @@ 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 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.
+- **`semiotic/ai`** — a single import with the 47-chart capability catalog (XY, ordinal, network, realtime, geo, value), optimized for LLM code generation. Note: the published entry files are pre-bundled, so importing one chart from `semiotic/ai` still ships most of the bundle — treat it as a codegen/tooling surface and use family subpaths (`semiotic/xy`, `semiotic/geo`, `semiotic/value`, …) in production code, at roughly half the single-chart cost.
 - **`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
-- **`diagnoseConfig(component, props)`** — programmatic anti-pattern detector with 12 checks and actionable fixes
+- **`diagnoseConfig(component, props)`** — programmatic anti-pattern detector with actionable fixes, spanning validation, encoding, accessibility, and misleading-design (deception) checks
 - **`CLAUDE.md`** — instruction files auto-synced for Claude, Cursor, Copilot, Windsurf, and Cline
 - **`llms.txt`** — machine-readable documentation following the emerging standard
 
@@ -320,13 +332,13 @@ Semiotic ships 12 entry points. **Don't import from `"semiotic"` unless you need
 | `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/server` | **128 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
+| `semiotic/utils` | **38 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/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/ai` | **250 KB** | All 47 schema-backed charts + validation — optimized for LLM code generation |
 | `semiotic` | **203 KB** | Everything below (full bundle) |
 
 <!-- semiotic-bundle-sizes:end -->
@@ -411,13 +423,20 @@ Add to your MCP client config (e.g. `claude_desktop_config.json` for Claude Desk
 }
 ```
 
-No API keys or authentication required. The server runs locally via stdio. HTTP mode is also available for inspectors and web clients: `npx semiotic-mcp --http --port 3001`.
+No API keys or authentication required. The server runs locally via stdio. HTTP mode is also available for inspectors, web clients, and ChatGPT Apps SDK experiments: `npx semiotic-mcp --http --port 3001`. In 3.7.2 HTTP mode is stateless: each request gets a fresh read-only MCP server + transport, so it can autoscale on serverless hosts without sticky sessions.
+
+For ChatGPT developer mode, expose the HTTP endpoint over HTTPS with a tunnel and create a connector that points at `https://<your-tunnel>/mcp`. The experimental Apps SDK surface is `renderInteractiveChart`, which returns a `text/html;profile=mcp-app` widget template plus a hidden SVG payload rendered by Semiotic on the MCP server.
+
+For a hosted deployment, see `deploy/cloud-run`. The wrapper runs the published `semiotic-mcp`
+binary, exposes `/mcp` plus health endpoints, and supports `MCP_ALLOWED_HOSTS` for production
+host-header allowlisting.
 
 ### Tools
 
 | 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. |
+| **`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 plus a "Render evidence" JSON block (mark counts by scene type, resolved axis domains, empty flag, annotation count, accessible name) so agents can verify the chart drew data marks, or validation errors with fix suggestions. |
+| **`renderInteractiveChart`** | Render a static-data chart as a ChatGPT Apps widget. Uses the same Semiotic server render path as `renderChart`, then hydrates an iframe UI with fit, zoom, data, hover, and render-evidence controls. |
 | **`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. |
@@ -439,6 +458,7 @@ No API keys or authentication required. The server runs locally via stdio. HTTP
 | **`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. |
+| **`ui://semiotic/chart-widget.html`** | ChatGPT Apps / MCP Apps widget template used by `renderInteractiveChart`. |
 
 ### Prompts
 
@@ -490,6 +510,25 @@ Args: {
 → Returns: <svg>...</svg>
 ```
 
+### Example: render a ChatGPT Apps widget
+
+```
+Tool: renderInteractiveChart
+Args: {
+  "component": "BarChart",
+  "props": {
+    "title": "Revenue by Quarter",
+    "data": [
+      { "quarter": "Q1", "revenue": 120 },
+      { "quarter": "Q2", "revenue": 180 }
+    ],
+    "categoryAccessor": "quarter",
+    "valueAccessor": "revenue"
+  }
+}
+→ Returns: structured chart summary for the model + hidden SVG/widget metadata for ChatGPT.
+```
+
 ### Example: diagnose a broken config
 
 ```

package/ai/behaviorContracts.cjs

@@ -15,13 +15,17 @@ const DOC_MARKER_START = "<!-- semiotic-behavior-contracts:start -->"
 const DOC_MARKER_END = "<!-- semiotic-behavior-contracts:end -->"
 
 // Components whose static config requires `data` are derived from
-// `ai/schema.json` rather than maintained as a hand-curated list. The schema
-// already declares which components require data — duplicating that here led
-// to drift (Heatmap, FunnelChart, MinimapChart, ScatterplotMatrix, and the
-// hierarchy charts were schema-required but missing from the local list,
-// which made `dataRequiredForUsageMode` incorrectly return `false` and
-// suppressed the "data is required" error in --doctor / MCP diagnoseConfig
-// even when usageMode wasn't `push`).
+// `ai/schema.json` rather than maintained as a hand-curated list.
+//
+// A component needs data in STATIC usage if its schema declares a `data` input
+// prop — NOT merely if `data` is in the `required` array. `required` lists the
+// semantic accessors a chart needs (highAccessor, subcategoryAccessor, series,
+// …), and several data-driven charts don't put `data` itself there:
+// CandlestickChart, MultiAxisLineChart, QuadrantChart, DifferenceChart,
+// LikertChart, and SwimlaneChart. Keying off `required.includes("data")` missed
+// exactly those — they'd render blank with no data yet passed --doctor / MCP
+// diagnoseConfig as "OK" in static mode. Keying off the presence of a `data`
+// property catches them (and still includes the charts that DO list `data`).
 //
 // `STATIC_DATA_COMPONENTS` stays exported as a Set for test/legacy callers
 // that probe the surface, and is rebuilt from disk at module load time.
@@ -41,8 +45,10 @@ function loadStaticDataComponentsFromSchema() {
       const schema = JSON.parse(fs.readFileSync(schemaPath, "utf8"))
       const out = new Set()
       for (const tool of schema.tools || []) {
-        const required = tool.function?.parameters?.required || []
-        if (required.includes("data")) out.add(tool.function.name)
+        const properties = tool.function?.parameters?.properties || {}
+        // Data-driven if the schema declares a `data` input prop, regardless of
+        // whether `data` appears in `required` (see note above).
+        if ("data" in properties) out.add(tool.function.name)
       }
       if (out.size > 0) return out
     } catch {
@@ -114,6 +120,10 @@ const PUSH_MODE_COMPONENTS = [
   "Scatterplot",
   "BubbleChart",
   "ConnectedScatterplot",
+  "CandlestickChart",
+  "MultiAxisLineChart",
+  "QuadrantChart",
+  "DifferenceChart",
   "BarChart",
   "StackedBarChart",
   "GroupedBarChart",

package/ai/cli.js

@@ -163,6 +163,21 @@ function validatePropsWithSchema(componentName, props, usageMode = "static") {
     }
   }
 
+  // Array-shape charts that declare a `data` schema prop need it in static
+  // usage even when "data" isn't in `required` (those lists hold semantic
+  // accessors). Without this, --doctor passed dataless static CandlestickChart /
+  // MultiAxisLineChart / QuadrantChart / DifferenceChart / SwimlaneChart /
+  // LikertChart configs that render blank. dataRequiredForUsageMode is true for
+  // them in static and false in push, mirroring the MCP diagnoseConfig path.
+  if (
+    "data" in properties &&
+    !required.includes("data") &&
+    dataRequiredForUsageMode(component.name, usageMode) &&
+    (props.data === undefined || props.data === null)
+  ) {
+    errors.push(`"data" is required for ${component.name}.`)
+  }
+
   for (const [propName, value] of Object.entries(props)) {
     if (value === undefined || value === null) continue
     const propSchema = properties[propName]