semiotic 3.7.4 → 3.7.5

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` (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.
+- **Use sub-path imports** — `semiotic/xy` (96KB gz), `semiotic/ordinal` (78KB gz), `semiotic/network` (73KB gz), `semiotic/geo` (57KB gz), `semiotic/realtime` (104KB gz), `semiotic/server` (132KB gz), `semiotic/utils` (39KB gz), `semiotic/recipes` (19KB gz), `semiotic/themes` (6KB gz), `semiotic/data` (4KB gz), `semiotic/value` (6KB gz), `semiotic/ai` (269KB gz). Full `semiotic` is 216KB gz.
 <!-- semiotic-bundle-sizes:end -->
 - CLI: `npx semiotic-ai [--schema|--compact|--examples|--doctor|--audit-a11y]` · MCP: `npx semiotic-mcp`
 
@@ -24,7 +24,7 @@ HOC Charts (simple, default) → Stream Frames (full control). Use HOCs unless y
 **AreaChart** — LineChart props + `areaBy`, `y0Accessor`, `gradientFill`, `areaOpacity` (0.7), `showLine` (true), `band`, `tooltip="multi"`
 **DifferenceChart** — Two-series A/B. Fills between with `seriesAColor` where A>B, `seriesBColor` where B>A; crossovers interpolated. `data`, `xAccessor`, `seriesAAccessor` ("a"), `seriesBAccessor` ("b"), `seriesALabel`/`seriesBLabel`, `seriesAColor` (var(--semiotic-danger))/`seriesBColor` (var(--semiotic-info)), `showLines` (true), `lineWidth` (1.5), `showPoints` (false), `pointRadius` (3), `curve` ("linear"), `areaOpacity` (0.6), `gradientFill`, `xExtent`/`yExtent`, `pointIdAccessor`, `windowSize`. Push via `ref.push({x,a,b})`. Accessor outputs coerce through `toNumber`.
 **StackedAreaChart** — flat array + `areaBy` (required), `colorBy`, `normalize`, `baseline` ("zero"|"wiggle" streamgraph|"silhouette" centered), `stackOrder` ("key"|"insideOut"|"asc"|"desc"). Streamgraph: `baseline="wiggle"` + `stackOrder="insideOut"`. `baseline` ⊥ `normalize`. No `lineBy`. `tooltip="multi"` interpolates between samples.
-**Scatterplot** — `xAccessor`, `yAccessor`, `colorBy`, `sizeBy`, `sizeRange`, `pointRadius` (5), `pointOpacity` (0.8), `marginalGraphics`, `regression` (boolean | "linear"|"polynomial"|"loess" | RegressionConfig — sugar for trend overlay)
+**Scatterplot** — `xAccessor`, `yAccessor`, `colorBy`, `sizeBy`, `sizeRange`, `symbolBy` (categorical field → glyph **shape**: each mark becomes a d3-shape glyph; size still tracks `sizeBy`/`pointRadius`), `symbolMap` ({category → shape}; unmapped auto-assign — pass it for legend-matchable shapes), `pointRadius` (5), `pointOpacity` (0.8), `marginalGraphics`, `regression` (boolean | "linear"|"polynomial"|"loess" | RegressionConfig — sugar for trend overlay)
 **BubbleChart** — Scatterplot + `sizeBy` (required), `sizeRange` ([5,40]), `regression`
 **ConnectedScatterplot** — + `orderAccessor`, `regression`
 **QuadrantChart** — Scatterplot + `quadrants`, `xCenter`, `yCenter`
@@ -39,7 +39,7 @@ HOC Charts (simple, default) → Stream Frames (full control). Use HOCs unless y
 **BarChart** — `categoryAccessor`, `valueAccessor`, `orientation`, `colorBy`, `sort`, `barPadding` (40), `roundedTop`, `gradientFill` (true | {topOpacity, bottomOpacity} | {colorStops}; tip→base), `regression`
 **StackedBarChart** — + `stackBy` (required), `normalize`, `sort` (false default — insertion order)
 **GroupedBarChart** — + `groupBy` (required), `barPadding` (60), `sort` (false default)
-**SwarmPlot** — `colorBy`, `sizeBy`, `pointRadius`, `pointOpacity`
+**SwarmPlot** — `colorBy`, `sizeBy`, `symbolBy` (categorical field → glyph shape, like Scatterplot), `symbolMap`, `pointRadius`, `pointOpacity`
 **BoxPlot** — + `showOutliers`, `outlierRadius`
 **Histogram** — + `bins` (25), `relative`. Always horizontal.
 **ViolinPlot** — + `bins`, `curve`, `showIQR`
@@ -127,13 +127,14 @@ When the catalog doesn't fit, three HOCs take a layout function emitting scene p
 
 - **`XYCustomChart`** (`semiotic/xy`) — waffle, calendar heatmap, custom point/line/area
 - **`OrdinalCustomChart`** (`semiotic/ordinal`) — marimekko, parallel coords, bullet, fan, slope
-- **`NetworkCustomChart`** (`semiotic/network`) — flextree, dagre, custom force/radial
+- **`NetworkCustomChart`** (`semiotic/network`) — flextree, dagre, custom force/radial, packed-cluster beeswarm matrix
 
 Layout signature differs by family:
 - **XY/Ordinal**: `layout: (ctx) => { nodes, overlays? }`. `ctx`: `data`, `scales` ({x,y} XY | {o,r,projection} ordinal), `dimensions` (plot rect — center-anchored for radial ordinal, top-left otherwise), `theme`, `resolveColor(key)`, `config`.
-- **Network**: `layout: (ctx) => { sceneNodes?, sceneEdges?, labels?, overlays? }`. `ctx`: `nodes`, `edges`, `dimensions`, `theme`, `resolveColor(key)`, `config`, `selection` (shared-selection predicate `{ isActive, predicate(datum) }` from `LinkedCharts`, `null` when unwired — dim/highlight by it). Run external positioners (`d3-flextree`, `dagre`) then emit network scene primitives (circle/rect/arc nodes; line/bezier/curved edges).
+- **Network**: `layout: (ctx) => { sceneNodes?, sceneEdges?, labels?, overlays?, htmlMarks? }`. `ctx`: `nodes`, `edges`, `dimensions`, `theme`, `resolveColor(key)`, `config`, `selection` (shared-selection predicate `{ isActive, predicate(datum) }` from `LinkedCharts`, `null` when unwired — dim/highlight by it). Run external positioners (`d3-flextree`, `dagre`) then emit network scene primitives (circle/rect/arc/**symbol** nodes; line/bezier/curved edges). The `symbol` node is the per-datum **shape** channel — a `d3-shape` glyph (`circle`/`square`/`triangle`/`diamond`/`star`/`cross`/`wye`/`chevron`, or a custom `path`) sized by `size` (area), rendered on canvas + SVG/SSR and hit-tested + keyboard-navigated as a unit. **The `symbol` mark is cross-pipeline**: XY and ordinal custom layouts emit it too (`{type:"symbol", x, y, size, symbolType}` — note `x`/`y`, vs the network variant's `cx`/`cy`), and Scatterplot/SwarmPlot expose it as the `symbolBy` encoding. One shared `symbolPath` implementation backs canvas/SVG/hit-test across all three families.
+  - **`htmlMarks`** (network only): `NetworkHtmlMark[]` = `{ id, x, y, width, height, content: ReactNode }`, positioned in the **same plot space as `sceneNodes`** and rendered into one real-DOM layer the framework places **above the canvas and SVG `overlays`** (stack: canvas → `overlays` → `htmlMarks`). Reach for it over an SVG `<foreignObject>` when a mark is **text-heavy/rich and dims or animates on hover** — a real `<div>` composites `opacity`/`transform`/`visibility` changes instead of re-rasterizing text (the `foreignObject` stall on large graphs). Framework owns the margin (and future zoom/pan) transform so marks stay pixel-aligned; each mark is its own element, keyed by `id` (position-only re-runs reposition without remounting). `pointer-events: none` by default — keep a transparent hit-rect `sceneNode` per mark so canvas hit-testing/`onObservation` stays authoritative. Mark `content` can read `useCustomLayoutSelection()` to dim on shared selection without a relayout. Additive: omit it and no extra DOM renders. Class hooks: `.semiotic-network-html-marks` (layer) / `.semiotic-network-html-mark` (each).
 
-`semiotic/recipes` ships pure layout functions (`waffleLayout`, `calendarLayout`, `marimekkoLayout`, `bulletLayout`, `parallelCoordinatesLayout`, `flextreeLayout`, `dagreLayout`, `lineageDagLayout`). BYO heavy deps (`d3-flextree`, `dagre`) in user code. `lineageDagLayout` renders a pre-positioned **layered lineage/DAG** (reads logical layer/row coords, no re-layout) with composite node glyphs (one hit-rect per node + icon/label/store-chip chrome in `overlays`), level-of-detail collapse (full→compact→icon→dot), distinct dashed back-edges, and host-driven reach-dimming (`layoutConfig.reachableIds`) + selection (`layoutConfig.selectedId` / shared `ctx.selection`).
+`semiotic/recipes` ships pure layout functions (`waffleLayout`, `calendarLayout`, `marimekkoLayout`, `bulletLayout`, `parallelCoordinatesLayout`, `flextreeLayout`, `dagreLayout`, `lineageDagLayout`, `packedClusterMatrix`). BYO heavy deps (`d3-flextree`, `dagre`) in user code. `packedClusterMatrix` (network) bins records into a column×row matrix of **densely-packed beeswarm clusters** (deterministic self-contained packing, geometry cached) and emits **multi-channel glyphs** — hue (`colorAccessor`/`colorMap`), size (`sizeAccessor`, area), shade (`shadeAccessor`, CIELAB lightness), plus EITHER shape-encoding (`symbolAccessor`/`symbolMap` — the base mark becomes that shape) OR the **composite-glyph** model (`iconAccessor`/`iconMap` — base is a filled circle, only mapped values get a stroked inner icon). `rowMode:"banded"` (default) gives aligned global orbit-bands (row labels align, one enclosure spans the columns per band, columns vary in height) vs `"stacked"` (per-column cell heights ∝ count). `callouts:[{field,value,label}]` draws leader lines to named marks. `cellSizing:"proportional"` makes area ∝ count. **Recipe chrome kit** (exported from `semiotic/recipes`, for any custom-layout's `overlays`): `roundedEnclosure`/`boundsOf` (group/band borders), `bandLabel` (overflow-aware axis/band labels), `markCallout` (leader-line callout to a mark), `readField` (`node.data`-wrapper reader), `groupBy`, `dimFor` (the highlight/dim opacity rule — `{predicate?, highlight?, baseOpacity?, dimOpacity?, brighten?}`; `matchesHighlight` is its `{field,value}[]` matcher), `signatureKey`/`LayoutCache` (content-signature geometry cache so re-styling never re-runs an expensive layout — key by *content*, never by `ctx.nodes` identity), `legendGroupsFrom` (`{colorMap|keys, symbolMap?, sizeStops?}` → `LegendGroup[]` for `frameProps.legend`), `shade`/`makeShade`, `symbolPathString`/`symbolRadius`/`symbolExtent`/`SYMBOL_SEQUENCE`. (`bandLabel`/`dimFor` are adopted by marimekko/bullet/parallelCoordinates/packedClusterMatrix.) `lineageDagLayout` renders a pre-positioned **layered lineage/DAG** (reads logical layer/row coords, no re-layout) with composite node glyphs (one hit-rect per node + icon/label/store-chip chrome in `overlays`), level-of-detail collapse (full→compact→icon→dot), distinct dashed back-edges, and host-driven reach-dimming (`layoutConfig.reachableIds`) + selection (`layoutConfig.selectedId` / shared `ctx.selection`).
 
 **Chrome (labels/axes/legends): the recipe owns it.** Recipes emit own chrome via `overlays` return field (ReactNode painted on top). Built-in axes via `showAxes` on the HOC work for layouts respecting the standard scale. Recipe convention: `showXxx` boolean toggles, `xxxFormat` callbacks. Shipped recipes' toggles: marimekko `showCategoryLabels`, bullet `showLabels`+`showTicks`, parallelCoordinates `showAxes`, flextree/dagre `showLabels`, waffle/calendar none.
 
@@ -145,7 +146,9 @@ Layout signature differs by family:
 - Streaming layouts: ingest via ref (`push`/`pushMany`); layout re-runs on each ingest. Overlays update on data-change paths, NOT per-frame.
 - **On `NetworkCustomChart`, a `layoutConfig` change re-runs the layout (`buildScene`) WITHOUT re-ingesting the node/edge topology** — so drive interaction state, styling, or animation progress through `layoutConfig` for cheap per-frame updates; swapping `nodes`/`edges` (or the chart `width`/`height`) is the heavier path that re-ingests. Custom overlays are read straight from the store at render time (the frame's repaint re-reads them), so a recipe returning fresh JSX every layout call needs no per-frame `setState`.
 - Custom layouts own their colors — always prefer `ctx.resolveColor(key)` over hardcoded literals. `CategoryColorProvider` integration is XY-only; for cross-chart sync on network/ordinal customLayouts, pass matching `colorScheme` to each.
-- `NetworkCustomChart` accepts `selection` / `linkedHover` / `chartId` like the built-in network HOCs: hover/click emit into the shared selection store, and the resolved predicate arrives as `ctx.selection` so the layout can dim/highlight by a cross-chart selection. Host-owned per-render dimming (e.g. a graph-reachability set) is orthogonal — pass it through `layoutConfig` and read `ctx.config`.
+- All three custom HOCs accept `selection` / `linkedHover` / `chartId` like the built-in HOCs: hover/click emit into the shared selection store, and the resolved predicate arrives as `ctx.selection` so the layout can dim/highlight by a cross-chart selection. Host-owned per-render dimming (e.g. a graph-reachability set) is orthogonal — pass it through `layoutConfig` and read `ctx.config`.
+- **Selection restyle without a relayout** (the cheap hover path): by default a `ctx.selection` change re-runs the layout (rebuilds sceneNodes + repaints + rebuilds the quadtree). To restyle on hover/selection *without* re-positioning, opt in two ways: (1) return a **`restyle(node, selection)`** (network also `restyleEdge`) from the layout result — its presence makes a selection change re-apply styles to the existing scene **off each mark's base style** and just repaint (no relayout, no quadtree rebuild); compute geometry once in the layout body, express dimming in `restyle`. (2) For the React **`overlays`**, call **`useCustomLayoutSelection()`** (from `semiotic`/`semiotic/recipes` or the family entry) → `{ isActive, predicate }`; the frame swaps only the context value on selection change, so subscribing overlay components re-render while the canvas/quadtree stay untouched. Express selection/highlight through the selection store (not `layoutConfig`) to ride this path.
+- **Annotation-to-mark anchoring**: all three custom HOCs accept `annotations`. A custom layout's marks anchor by id — emit a scene node with `id: "<foo>"` and an annotation `{ pointId: "<foo>", … }` resolves to that mark's center (XY/ordinal point+symbol nodes and every network node are harvested as anchor points). Data-coordinate anchoring still works for XY/ordinal; network has no data scales, so anchor by `pointId` (or draw a `markCallout` directly).
 - Tooltips: emit datum keys matching user-visible accessor names. Avoid underscored synthetic keys (default tooltip filters those out).
 
 ## Coordinated Views

package/README.md

@@ -12,15 +12,15 @@ 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.4
+## What's New in 3.7.5
 
-3.7.4 is a network-chart and maintenance patch release:
+3.7.5 is a chart-correctness and responsive-layout patch release:
 
-- `semiotic/recipes` adds lineage DAG helpers for laying out data-flow and KStreams-style network
-  diagrams.
-- Network custom layouts now preserve selection metadata through streaming layout and render paths.
-- Docs add the KStreams DAG recipe and expand custom network chart guidance, alongside
-  dependency updates for Prettier, TypeScript ESLint, Rollup, and Sharp.
+- ForceDirectedGraph string `edgeWidth` accessors now read the underlying edge data, and server
+  rendering handles `edgeWidth`, `edgeColor`, and `edgeOpacity` for SSR parity.
+- Crowded ordinal category axes now thin tick labels to avoid overlapping temporal-histogram bins.
+- XY custom-layout overlays now re-run on responsive size changes, keeping SVG chrome aligned with
+  canvas scene nodes after first measurement.
 
 ```jsx
 import { LineChart } from "semiotic/xy"
@@ -105,6 +105,23 @@ Charts serialize to JSON and back: `toConfig`, `fromConfig`, `toURL`,
 translates them to Semiotic configs — works with `configToJSX()` for
 full round-trip from notebooks and AI-generated specs.
 
+Need an external pitfall review? `toDataPitfallsChain()` builds a
+dependency-free chain input for [`datapitfalls`](https://github.com/bjonesdataliteracy/datapitfalls),
+combining the Semiotic config, JSX, reader grounding, diagnostics,
+accessibility audit, and optional rendered SVG/image evidence:
+
+```ts
+import { toDataPitfallsChain } from "semiotic/ai"
+import { detectPitfalls } from "datapitfalls"
+
+const input = toDataPitfallsChain("LineChart", props, {
+  narrative: "Monthly sales are accelerating.",
+  rendered: { svg, evidence },
+})
+
+const report = await detectPitfalls(input, { apiKey: process.env.ANTHROPIC_API_KEY })
+```
+
 ### When to use something else
 
 Need a standard bar or line chart for a dashboard you'll never need to
@@ -325,19 +342,19 @@ Semiotic ships 12 entry points. **Don't import from `"semiotic"` unless you need
 
 | Entry Point | gzip | What's inside |
 |---|---|---|
-| `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` | **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/xy` | **96 KB** | LineChart, AreaChart, Scatterplot, Heatmap, + 8 more XY charts |
+| `semiotic/ordinal` | **78 KB** | BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts |
+| `semiotic/network` | **73 KB** | ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4 more |
+| `semiotic/geo` | **57 KB** | ChoroplethMap, FlowMap, DistanceCartogram, ProportionalSymbolMap |
+| `semiotic/realtime` | **104 KB** | RealtimeLineChart, RealtimeHistogram, + 4 streaming charts |
+| `semiotic/server` | **132 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
+| `semiotic/utils` | **39 KB** | ThemeProvider, validators, serialization — no chart components |
+| `semiotic/recipes` | **19 KB** | Pure layout functions (waffle, marimekko, flextree, dagre, …) |
+| `semiotic/themes` | **6 KB** | Theme presets only (tufte, carbon, etc.) |
+| `semiotic/data` | **4 KB** | bin, rollup, groupBy, pivot, fromVegaLite |
 | `semiotic/value` | **6 KB** | BigNumber — focal-value KPI / scorecard (SingleValueFrame POC) |
-| `semiotic/ai` | **250 KB** | All 47 schema-backed charts + validation — optimized for LLM code generation |
-| `semiotic` | **203 KB** | Everything below (full bundle) |
+| `semiotic/ai` | **269 KB** | All 47 schema-backed charts + validation — optimized for LLM code generation |
+| `semiotic` | **216 KB** | Everything below (full bundle) |
 
 <!-- semiotic-bundle-sizes:end -->
 

package/ai/schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "name": "semiotic",
-  "version": "3.7.4",
+  "version": "3.7.5",
   "description": "React data visualization library for charts, networks, and beyond",
   "tools": [
     {
@@ -117,6 +117,24 @@
             "yLabel": {
               "type": "string"
             },
+            "xScaleType": {
+              "type": "string",
+              "enum": [
+                "linear",
+                "log",
+                "time"
+              ],
+              "description": "x scale type. \"time\" builds a scaleTime (required for landmark ticks on timestamps)."
+            },
+            "yScaleType": {
+              "type": "string",
+              "enum": [
+                "linear",
+                "log",
+                "time"
+              ],
+              "description": "y scale type."
+            },
             "data": {
               "type": "array",
               "description": "Array of data objects"
@@ -325,6 +343,24 @@
             "yLabel": {
               "type": "string"
             },
+            "xScaleType": {
+              "type": "string",
+              "enum": [
+                "linear",
+                "log",
+                "time"
+              ],
+              "description": "x scale type. \"time\" builds a scaleTime (required for landmark ticks on timestamps)."
+            },
+            "yScaleType": {
+              "type": "string",
+              "enum": [
+                "linear",
+                "log",
+                "time"
+              ],
+              "description": "y scale type."
+            },
             "data": {
               "type": "array",
               "description": "Array of data objects"
@@ -532,6 +568,24 @@
             "yLabel": {
               "type": "string"
             },
+            "xScaleType": {
+              "type": "string",
+              "enum": [
+                "linear",
+                "log",
+                "time"
+              ],
+              "description": "x scale type. \"time\" builds a scaleTime (required for landmark ticks on timestamps)."
+            },
+            "yScaleType": {
+              "type": "string",
+              "enum": [
+                "linear",
+                "log",
+                "time"
+              ],
+              "description": "y scale type."
+            },
             "data": {
               "type": "array",
               "description": "Array of data objects"
@@ -714,6 +768,24 @@
             "yLabel": {
               "type": "string"
             },
+            "xScaleType": {
+              "type": "string",
+              "enum": [
+                "linear",
+                "log",
+                "time"
+              ],
+              "description": "x scale type. \"time\" builds a scaleTime (required for landmark ticks on timestamps)."
+            },
+            "yScaleType": {
+              "type": "string",
+              "enum": [
+                "linear",
+                "log",
+                "time"
+              ],
+              "description": "y scale type."
+            },
             "data": {
               "type": "array",
               "description": "Array of data objects"
@@ -747,6 +819,17 @@
                 15
               ]
             },
+            "symbolBy": {
+              "type": [
+                "string",
+                "function"
+              ],
+              "description": "Categorical field → glyph shape; each mark renders as a d3-shape glyph (circle/square/triangle/diamond/star/cross/wye/chevron) instead of a circle."
+            },
+            "symbolMap": {
+              "type": "object",
+              "description": "Explicit {category → shape} map for symbolBy; unmapped categories auto-assign."
+            },
             "pointRadius": {
               "type": "number",
               "description": "Fixed point radius",
@@ -892,6 +975,24 @@
             "yLabel": {
               "type": "string"
             },
+            "xScaleType": {
+              "type": "string",
+              "enum": [
+                "linear",
+                "log",
+                "time"
+              ],
+              "description": "x scale type. \"time\" builds a scaleTime (required for landmark ticks on timestamps)."
+            },
+            "yScaleType": {
+              "type": "string",
+              "enum": [
+                "linear",
+                "log",
+                "time"
+              ],
+              "description": "y scale type."
+            },
             "data": {
               "type": "array",
               "description": "Array of data objects"
@@ -1091,6 +1192,24 @@
             "yLabel": {
               "type": "string"
             },
+            "xScaleType": {
+              "type": "string",
+              "enum": [
+                "linear",
+                "log",
+                "time"
+              ],
+              "description": "x scale type. \"time\" builds a scaleTime (required for landmark ticks on timestamps)."
+            },
+            "yScaleType": {
+              "type": "string",
+              "enum": [
+                "linear",
+                "log",
+                "time"
+              ],
+              "description": "y scale type."
+            },
             "data": {
               "type": "array",
               "description": "Array of data objects shared by both series"
@@ -1235,6 +1354,24 @@
             "yLabel": {
               "type": "string"
             },
+            "xScaleType": {
+              "type": "string",
+              "enum": [
+                "linear",
+                "log",
+                "time"
+              ],
+              "description": "x scale type. \"time\" builds a scaleTime (required for landmark ticks on timestamps)."
+            },
+            "yScaleType": {
+              "type": "string",
+              "enum": [
+                "linear",
+                "log",
+                "time"
+              ],
+              "description": "y scale type."
+            },
             "data": {
               "type": "array"
             },
@@ -1408,6 +1545,24 @@
             "yLabel": {
               "type": "string"
             },
+            "xScaleType": {
+              "type": "string",
+              "enum": [
+                "linear",
+                "log",
+                "time"
+              ],
+              "description": "x scale type. \"time\" builds a scaleTime (required for landmark ticks on timestamps)."
+            },
+            "yScaleType": {
+              "type": "string",
+              "enum": [
+                "linear",
+                "log",
+                "time"
+              ],
+              "description": "y scale type."
+            },
             "data": {
               "type": "array",
               "description": "Array of data objects"
@@ -1584,6 +1739,24 @@
             "yLabel": {
               "type": "string"
             },
+            "xScaleType": {
+              "type": "string",
+              "enum": [
+                "linear",
+                "log",
+                "time"
+              ],
+              "description": "x scale type. \"time\" builds a scaleTime (required for landmark ticks on timestamps)."
+            },
+            "yScaleType": {
+              "type": "string",
+              "enum": [
+                "linear",
+                "log",
+                "time"
+              ],
+              "description": "y scale type."
+            },
             "data": {
               "type": "array",
               "description": "Array of data objects with x, y, and value"
@@ -1757,6 +1930,24 @@
             "yLabel": {
               "type": "string"
             },
+            "xScaleType": {
+              "type": "string",
+              "enum": [
+                "linear",
+                "log",
+                "time"
+              ],
+              "description": "x scale type. \"time\" builds a scaleTime (required for landmark ticks on timestamps)."
+            },
+            "yScaleType": {
+              "type": "string",
+              "enum": [
+                "linear",
+                "log",
+                "time"
+              ],
+              "description": "y scale type."
+            },
             "data": {
               "type": "array",
               "description": "Array of data objects"
@@ -2659,6 +2850,17 @@
                 8
               ]
             },
+            "symbolBy": {
+              "type": [
+                "string",
+                "function"
+              ],
+              "description": "Categorical field → glyph shape; each point renders as a d3-shape glyph instead of a circle."
+            },
+            "symbolMap": {
+              "type": "object",
+              "description": "Explicit {category → shape} map for symbolBy; unmapped categories auto-assign."
+            },
             "pointRadius": {
               "type": "number",
               "default": 4
@@ -7599,6 +7801,24 @@
             "yLabel": {
               "type": "string"
             },
+            "xScaleType": {
+              "type": "string",
+              "enum": [
+                "linear",
+                "log",
+                "time"
+              ],
+              "description": "x scale type. \"time\" builds a scaleTime (required for landmark ticks on timestamps)."
+            },
+            "yScaleType": {
+              "type": "string",
+              "enum": [
+                "linear",
+                "log",
+                "time"
+              ],
+              "description": "y scale type."
+            },
             "data": {
               "type": "array",
               "description": "Array of `{x, a, b}` objects. Omit for push API mode."

package/ai/system-prompt.md

@@ -2,7 +2,7 @@
 
 <!-- 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` (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.
+**Use sub-path imports** — `semiotic/xy` (96KB gz), `semiotic/ordinal` (78KB gz), `semiotic/network` (73KB gz), `semiotic/geo` (57KB gz), `semiotic/realtime` (104KB gz), `semiotic/server` (132KB gz), `semiotic/utils` (39KB gz), `semiotic/recipes` (19KB gz), `semiotic/themes` (6KB gz), `semiotic/data` (4KB gz), `semiotic/value` (6KB gz), `semiotic/ai` (269KB gz). Full `semiotic` is 216KB gz.
 <!-- semiotic-bundle-sizes:end -->
 
 ## Flat Array Data (`data: object[]`)
@@ -143,4 +143,5 @@ These rules are generated from `ai/behaviorContracts.cjs` and are consumed by `s
 - **SSR**: `renderChart("BarChart", props)` from `semiotic/server` — uses HOC names. Also `"Sparkline"` (no axes, 2px margins). `renderChartWithEvidence()` returns `{ svg, evidence }` (mark counts by scene type, axis domains, empty flag, annotation count, accessible name) so agents can verify the render drew data marks. `renderToImage()` (PNG), `renderToAnimatedGif()` (GIF), `renderDashboard()` (multi-chart). All accept `theme`. Required props: StackedBarChart needs `stackBy`, GroupedBarChart needs `groupBy`, StackedAreaChart needs `areaBy`, BubbleChart needs `sizeBy`, FunnelChart uses `stepAccessor`, GaugeChart needs `value` (`thresholds` optional).
 - **CLI**: `npx semiotic-ai --list` shows components/import paths/renderability; `npx semiotic-ai --schema GaugeChart` prints one component schema with metadata; `--doctor` validates props JSON and behavior contracts.
 - **MCP**: `npx semiotic-mcp` exposes schema, suggestion, diagnosis, accessibility, grounding, issue, theme, static render (`renderChart`), and ChatGPT Apps render (`renderInteractiveChart`) tools. Resources include `semiotic://schema`, `semiotic://components`, `semiotic://behavior-contracts`, `semiotic://system-prompt`, `semiotic://examples`, and the widget template `ui://semiotic/chart-widget.html`. Prompts: `build-semiotic-chart`, `debug-semiotic-chart`.
+- **Data Pitfalls bridge**: `toDataPitfallsChain(component, props, { rendered, context, narrative })` from `semiotic/ai` returns a dependency-free `datapitfalls` chain input containing config, JSX, reader grounding, diagnostics, accessibility audit, and optional render evidence/image.
 - **exportChart**: Pass the wrapper div, not the SVG element: `exportChart(wrapperDiv, { format: "png" })`. It finds canvas+SVG internally.

package/dist/components/Annotation.d.ts

@@ -7,6 +7,10 @@ type AnnotationNote = {
     orientation?: string;
     align?: string;
     noWrap?: boolean;
+    /** Render note text in a foreignObject for browser-native HTML wrapping. */
+    useHTML?: boolean;
+    /** Alias for useHTML. */
+    html?: boolean;
 };
 type AnnotationConnector = {
     end?: "arrow";

package/dist/components/DataSummaryContext.d.ts

@@ -3,6 +3,7 @@ interface DataSummaryState {
     /** When true, AccessibleDataTable renders visibly instead of sr-only */
     visible: boolean;
     setVisible: React.Dispatch<React.SetStateAction<boolean>>;
+    toggle: () => void;
 }
 export declare function DataSummaryProvider({ children }: {
     children: React.ReactNode;

package/dist/components/ai/chartCapabilityTypes.d.ts

@@ -73,6 +73,22 @@ export interface ChartDataProfile extends DataSummary {
     hasRepeatedX: boolean;
     /** True when the primary x candidate is monotonic. */
     monotonicX: boolean;
+    /**
+     * How amenable the (x × series) grid is to stacking. Only populated when both
+     * a primary x and series field exist. A stacked area/bar reads as bands only
+     * when series share x columns; when most columns hold a single series, the
+     * renderer zero-fills the gaps and every layer collapses into an isolated
+     * triangular spike instead of a continuous band. Capabilities gate on this to
+     * decline stacking on near-unique x (flat record lists, scatter-shaped data).
+     */
+    stackability?: {
+        /** Mean distinct series present per x value. ~1 → spiky; ~seriesCount → dense. */
+        seriesPerX: number;
+        /** Fraction of x columns where 2+ series coexist (where stacking is visible). */
+        multiSeriesFraction: number;
+        /** Number of distinct x columns considered. */
+        xColumns: number;
+    };
     /** True when there is at least one date-typed candidate. */
     hasTimeAxis: boolean;
     /**

package/dist/components/ai/dataPitfallsBridge.d.ts

@@ -0,0 +1,101 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import { type AccessibilityAuditResult, type AuditAccessibilityOptions } from "../charts/shared/auditAccessibility";
+import { type DiagnosisResult } from "../charts/shared/diagnoseConfig";
+import { type ChartConfig, type ToConfigOptions } from "../export/chartConfig";
+import { type ChartReaderGrounding, type ChartReaderGroundingOptions } from "./readerGrounding";
+export type DataPitfallsImageMediaType = "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+export interface DataPitfallsImageSource {
+    content: string;
+    mediaType: DataPitfallsImageMediaType;
+    filename?: string;
+}
+export interface DataPitfallsTextInput {
+    kind: "code" | "text";
+    content: string;
+    language?: string;
+    filename?: string;
+}
+export interface DataPitfallsImageInput {
+    kind: "image";
+    images: DataPitfallsImageSource[];
+}
+export interface DataPitfallsDocumentInput {
+    kind: "document";
+    content: string;
+    mediaType: "application/pdf";
+    filename?: string;
+}
+export interface DataPitfallsSlideContent {
+    text: string;
+    images: DataPitfallsImageSource[];
+}
+export interface DataPitfallsSlidesInput {
+    kind: "slides";
+    slides: DataPitfallsSlideContent[];
+    filename?: string;
+}
+export type DataPitfallsSingleArtifactInput = DataPitfallsTextInput | DataPitfallsImageInput | DataPitfallsDocumentInput | DataPitfallsSlidesInput;
+export interface DataPitfallsChainStage {
+    role: string;
+    artifact: DataPitfallsSingleArtifactInput;
+}
+export interface DataPitfallsChainInput {
+    kind: "chain";
+    stages: DataPitfallsChainStage[];
+}
+export interface DataPitfallsRenderedChart {
+    /** SVG markup from `semiotic/server` renderChart/renderChartWithEvidence or MCP renderChart. */
+    svg?: string;
+    /** Render evidence from `renderChartWithEvidence` or MCP renderChart. */
+    evidence?: unknown;
+    /** Optional rendered chart image for Data Pitfalls' Vision path. */
+    image?: DataPitfallsImageSource | DataPitfallsImageSource[];
+}
+export interface DataPitfallsBridgeOptions {
+    /** Default true. Include the serializable Semiotic chart config as JSON. */
+    includeConfig?: boolean;
+    /** Default true. Include JSX reconstructed from the serializable chart config. */
+    includeJSX?: boolean;
+    /** Default true. Include describeChart/buildReaderGrounding text and structure. */
+    includeGrounding?: boolean;
+    /** Default true. Include diagnoseConfig output. */
+    includeDiagnostics?: boolean;
+    /** Default true. Include auditAccessibility output. */
+    includeAccessibility?: boolean;
+    /** Optional author or app context, such as the analytical question or intended claim. */
+    context?: string;
+    /** Optional narrative/caption/claim that will be reviewed alongside the chart. */
+    narrative?: string;
+    /** Optional output from a render path. */
+    rendered?: DataPitfallsRenderedChart;
+    /** Forwarded to toConfig. Use includeData: false to omit raw rows from config/JSX stages; other stages may still summarize data. */
+    config?: ToConfigOptions;
+    /** Forwarded to buildReaderGrounding. */
+    grounding?: ChartReaderGroundingOptions;
+    /** Forwarded to auditAccessibility. */
+    accessibility?: AuditAccessibilityOptions;
+    /** Prefix used for generated filenames. Default: component name. */
+    filenamePrefix?: string;
+    /** Extra caller-supplied chain stages, appended last. */
+    additionalStages?: DataPitfallsChainStage[];
+}
+export interface DataPitfallsBridgeResult {
+    input: DataPitfallsChainInput;
+    config: ChartConfig;
+    grounding?: ChartReaderGrounding;
+    diagnosis?: DiagnosisResult;
+    accessibility?: AccessibilityAuditResult;
+}
+/**
+ * Build a Data Pitfalls-compatible chain input from a Semiotic chart config.
+ *
+ * The returned `input` is intentionally dependency-free: pass it to
+ * `detectPitfalls(input, options)` from the `datapitfalls` package in your app,
+ * CI job, or research harness. Semiotic contributes the chart config,
+ * reader-grounding payload, config diagnostics, accessibility audit, and
+ * optional rendered output; Data Pitfalls remains responsible for model-backed
+ * pitfall detection.
+ */
+export declare function buildDataPitfallsBridge(component: string, props: Datum, options?: DataPitfallsBridgeOptions): DataPitfallsBridgeResult;
+/** Convenience wrapper when you only need the Data Pitfalls input object. */
+export declare function toDataPitfallsChain(component: string, props: Datum, options?: DataPitfallsBridgeOptions): DataPitfallsChainInput;