semiotic 3.3.1 → 3.4.1

package/CLAUDE.md

@@ -2,7 +2,7 @@
 
 ## Quick Start
 - Install: `npm install semiotic`
-- **Use sub-path imports** — `semiotic/xy` (143KB gz), `semiotic/ordinal` (109KB), `semiotic/network` (98KB), `semiotic/geo` (93KB), `semiotic/realtime` (145KB), `semiotic/server` (100KB), `semiotic/utils` (31KB), `semiotic/themes` (5KB), `semiotic/data` (5KB). Full `semiotic` is 278KB gz.
+- **Use sub-path imports** — `semiotic/xy` (78KB gz), `semiotic/ordinal` (65KB), `semiotic/network` (54KB), `semiotic/geo` (53KB), `semiotic/realtime` (77KB), `semiotic/server` (58KB), `semiotic/utils` (19KB), `semiotic/themes` (3KB), `semiotic/data` (3KB). Full `semiotic` is 158KB gz.
 - CLI: `npx semiotic-ai [--schema|--compact|--examples|--doctor]`
 - MCP: `npx semiotic-mcp`
 
@@ -12,7 +12,9 @@
 - Every HOC accepts `frameProps` for pass-through. TypeScript `strict: true`. Every HOC has error boundary + dev-mode validation.
 
 ## Common Props (all HOCs)
-`title`, `description` (aria-label), `summary` (sr-only), `width` (600), `height` (400), `responsiveWidth`, `responsiveHeight`, `margin`, `className`, `color` (uniform fill), `enableHover` (true), `tooltip` (boolean | "multi" | function | config object), `showLegend`, `showGrid` (false), `frameProps`, `onObservation`, `onClick`, `chartId`, `loading` (false), `emptyContent`, `legendInteraction` ("none"|"highlight"|"isolate"), `legendPosition` ("right"|"left"|"top"|"bottom"), `emphasis` ("primary"|"secondary"), `annotations` (array), `accessibleTable` (true), `hoverHighlight` (boolean — dims non-hovered series, requires `colorBy`), `hoverRadius` (30)
+`title`, `description` (aria-label), `summary` (sr-only), `width` (600), `height` (400), `responsiveWidth`, `responsiveHeight`, `margin`, `className`, `color` (uniform fill), `stroke` (uniform stroke color — CSS var OK), `strokeWidth` (uniform stroke width in px), `opacity` (uniform 0–1 opacity), `enableHover` (true), `tooltip` (boolean | "multi" | function | config object), `showLegend`, `showGrid` (false), `frameProps`, `onObservation`, `onClick`, `chartId`, `loading` (false), `emptyContent`, `legendInteraction` ("none"|"highlight"|"isolate"), `legendPosition` ("right"|"left"|"top"|"bottom"), `emphasis` ("primary"|"secondary"), `annotations` (array), `accessibleTable` (true), `hoverHighlight` (boolean — dims non-hovered series, requires `colorBy`), `hoverRadius` (30), `animate` (boolean | { duration?, easing?, intro? } — animated intro on first render + smooth transitions on data change; intro defaults to true when animate is enabled)
+
+**Primitive styling props** (`color`, `stroke`, `strokeWidth`, `opacity`) apply to any shape the chart draws (bars, circles, lines, wedges, rects). Precedence: top-level prop > `frameProps.*Style` function return > HOC base > theme fallback. Use CSS variables (`stroke="var(--semiotic-border)"`) for theme-aware, cascade-overridable styling. For per-datum customization, keep using the function-form `frameProps.pieceStyle` / `pointStyle` / `lineStyle` etc. — the top-level prop overlays on top of whatever the function returns.
 
 `onClick` receives `(datum, { x, y })`. `onObservation` receives `{ type, datum?, x?, y?, timestamp, chartType, chartId }`.
 
@@ -29,10 +31,11 @@
 **Heatmap** — `data`, `xAccessor`, `yAccessor`, `valueAccessor`, `colorScheme`, `showValues`, `cellBorderColor`
 **ScatterplotMatrix** — `data`, `fields` (array of numeric field names for grid)
 **MinimapChart** — Overview + detail with linked zoom. Wraps an XY chart.
+**CandlestickChart** — `data`, `xAccessor`, `highAccessor` (req), `lowAccessor` (req), `openAccessor` + `closeAccessor` (optional). With all four: OHLC bars. With only high/low: degrades to a range chart. `candlestickStyle` ({ upColor, downColor, wickColor, rangeColor, bodyWidth, wickWidth }). Honors `mode` (primary/context/sparkline).
 
 ## Ordinal Charts (`semiotic/ordinal`)
 
-**BarChart** — `data`, `categoryAccessor`, `valueAccessor`, `orientation`, `colorBy`, `sort`, `barPadding` (40)
+**BarChart** — `data`, `categoryAccessor`, `valueAccessor`, `orientation`, `colorBy`, `sort`, `barPadding` (40), `roundedTop`, `gradientFill` (`true` | `{topOpacity, bottomOpacity}` | `{colorStops}` — same API as AreaChart; runs tip→base)
 **StackedBarChart** — + `stackBy` (required), `normalize`, `sort` (default false — insertion order)
 **GroupedBarChart** — + `groupBy` (required), `barPadding` (60), `sort` (default false — insertion order)
 **SwarmPlot** — `colorBy`, `sizeBy`, `pointRadius`, `pointOpacity`
@@ -40,7 +43,7 @@
 **Histogram** — + `bins` (25), `relative`. Always horizontal.
 **ViolinPlot** — + `bins`, `curve`, `showIQR`
 **RidgelinePlot** — + `bins`, `amplitude` (1.5)
-**DotPlot** — + `sort` (true), `dotRadius`, `showGrid` default true
+**DotPlot** — + `sort` ("auto" — insertion order when streaming, value-desc on static), `dotRadius`, `showGrid` default true
 **PieChart** — `categoryAccessor`, `valueAccessor`, `colorBy`, `startAngle`
 **DonutChart** — PieChart + `innerRadius` (60), `centerContent`
 **FunnelChart** — `stepAccessor`, `valueAccessor`, `categoryAccessor` (optional), `connectorOpacity`, `orientation`
@@ -86,20 +89,23 @@ Most HOCs support push via `forwardRef`. **Omit** `data` — do NOT pass `data={
 const ref = useRef()
 ref.current.push({ id: "p1", x: 1, y: 2 })
 ref.current.pushMany([...points])
+ref.current.replace([...points])                   // ordinal only — full dataset replacement, preserves category order + transitions (progressively chunks large datasets)
 ref.current.remove("p1")                          // by ID — requires pointIdAccessor
 ref.current.remove(["p1", "p2"])                   // batch remove
 ref.current.update("p1", d => ({ ...d, y: 99 }))  // in-place update — requires pointIdAccessor
 ref.current.clear()
 ref.current.getData()
+ref.current.getScales()                            // returns {o, r, projection} (ordinal) / {x, y} (XY) — null if not yet computed
 <Scatterplot ref={ref} xAccessor="x" yAccessor="y" pointIdAccessor="id" />
 ```
-`remove()` and `update()` require an ID accessor: `pointIdAccessor` on XY/realtime charts, `dataIdAccessor` on ordinal charts. Network HOC refs also use `remove(id)`/`update(id, updater)` (operates on nodes). For edge-level operations, use `StreamNetworkFrameHandle` directly: `removeNode(id)`, `removeEdge(sourceId, targetId)` or `removeEdge(edgeId)` (requires `edgeIdAccessor`), `updateNode(id, updater)`, `updateEdge(sourceId, targetId, updater)`.
+`remove()` and `update()` require an ID accessor: `pointIdAccessor` on XY/realtime charts, `dataIdAccessor` on ordinal charts. `replace()` is ordinal-only and routes through a bounded-ingest path that preserves category insertion-order memory and the transition position snapshot — what aggregator HOCs like LikertChart use under the hood to re-aggregate streaming input without shuffling categories or losing animations. Network HOC refs also use `remove(id)`/`update(id, updater)` (operates on nodes). For edge-level operations, use `StreamNetworkFrameHandle` directly: `removeNode(id)`, `removeEdge(sourceId, targetId)` or `removeEdge(edgeId)` (requires `edgeIdAccessor`), `updateNode(id, updater)`, `updateEdge(sourceId, targetId, updater)`.
 Not supported: Tree, Treemap, CirclePack, Orbit, ChoroplethMap, FlowMap, ScatterplotMatrix.
 
 ## Coordinated Views
 
 **LinkedCharts** — `selections`, **CategoryColorProvider** — `colors`|`categories` + `colorScheme`
 Chart props: `selection`, `linkedHover`, `linkedBrush`. Hooks: `useSelection`, `useLinkedHover`, `useBrushSelection`
+**Shared categories inside LinkedCharts → wrap in `CategoryColorProvider`.** When two or more charts encode the same categorical field (e.g. both `colorBy="region"`), wrapping in `CategoryColorProvider` gives every chart identical colors per category AND makes `LinkedCharts` render one unified legend (and suppress individual chart legends). Without it, each chart renders its own legend independently — often with mismatched colors.
 **Linked crosshair**: `linkedHover={{ name: "sync", mode: "x-position", xField: "time" }}`. Click-to-lock: click locks crosshair (dashed white), click/Escape unlocks.
 **ScatterplotMatrix**, **ChartContainer** (`title`, `subtitle`, `actions`), **ChartGrid** (`columns`, `gap`), **ContextLayout**
 
@@ -152,7 +158,7 @@ All HOCs accept `annotations` (array). Coordinates use data field names.
 
 ## Theming
 
-CSS custom properties: `--semiotic-bg`, `--semiotic-text`, `--semiotic-text-secondary`, `--semiotic-border`, `--semiotic-grid`, `--semiotic-primary`, `--semiotic-focus`, `--semiotic-font-family`, `--semiotic-annotation-color`, `--semiotic-legend-font-size`, `--semiotic-title-font-size`, `--semiotic-tick-font-family`, `--semiotic-tooltip-bg`/`text`/`radius`/`font-size`/`shadow`.
+CSS custom properties: `--semiotic-bg`, `--semiotic-text`, `--semiotic-text-secondary`, `--semiotic-border`, `--semiotic-grid`, `--semiotic-primary`, `--semiotic-secondary`, `--semiotic-surface`, `--semiotic-success`, `--semiotic-danger`, `--semiotic-warning`, `--semiotic-error`, `--semiotic-info`, `--semiotic-focus`, `--semiotic-font-family`, `--semiotic-annotation-color`, `--semiotic-legend-font-size`, `--semiotic-title-font-size`, `--semiotic-tick-font-family`, `--semiotic-tooltip-bg`/`text`/`radius`/`font-size`/`shadow`.
 
 ```jsx
 <ThemeProvider theme="tufte">       {/* Named preset */}
@@ -163,6 +169,16 @@ CSS custom properties: `--semiotic-bg`, `--semiotic-text`, `--semiotic-text-seco
 Presets: `light`, `dark`, `high-contrast`, `pastels`(-dark), `bi-tool`(-dark), `italian`(-dark), `tufte`(-dark), `journalist`(-dark), `playful`(-dark), `carbon`(-dark).
 Serialization: `themeToCSS(theme, selector)`, `themeToTokens(theme)`, `resolveThemePreset(name)`.
 
+**Semantic status roles** (on every preset): `colors.success`, `colors.danger`, `colors.warning`, `colors.error`, `colors.info`, plus `colors.secondary` and `colors.surface`. Each emits as a `--semiotic-{role}` CSS custom property. Use for status-driven charts: `<Waterfall positiveColor="var(--semiotic-success)" negativeColor="var(--semiotic-danger)" />`, `<Swimlane color="var(--semiotic-warning)" />`, bar stroke delineation `<RealtimeHistogram stroke="var(--semiotic-border)" />`, status annotations.
+
+**Scoped CSS cascade override** (per-subtree, no ThemeProvider needed):
+```jsx
+<div style={{ "--semiotic-danger": "#4b0082" }}>
+  {/* every chart below inherits this danger color via canvas CSS-var lookup */}
+</div>
+```
+Canvas scene builders read CSS variables via `getComputedStyle` on the canvas DOM ancestor, so standard CSS cascade rules apply even though rendering is canvas-based. Use CSS vars for **single-role** overrides; use a nested `ThemeProvider` for **array/scale** overrides (categorical palette, sequential/diverging scheme name).
+
 ## AI Features
 `onObservation`/`useChartObserver`, `toConfig`/`fromConfig`/`toURL`/`fromURL`/`copyConfig`/`configToJSX`, `validateProps(component, props)`, `diagnoseConfig(component, props)`, `exportChart(div, { format })`, `npx semiotic-ai --doctor`
 
@@ -177,6 +193,8 @@ Serialization: `themeToCSS(theme, selector)`, `themeToTokens(theme)`, `resolveTh
 - **Log scale**: Domain min clamped to 1e-6.
 - **barPadding**: Pixel value (40/60 default). Reduce for small charts.
 - **sort on StackedBarChart/GroupedBarChart**: Default `false` preserves insertion order. The underlying frame defaults to value-descending if `oSort` is undefined, so always pass `sort` explicitly if order matters.
+- **sort `"auto"`** (BarChart/StackedBarChart/GroupedBarChart/DotPlot): insertion order while streaming, value-desc on static data. The right choice when using the push API — avoids categories shuffling as values fluctuate. DotPlot's default; opt-in on others.
+- **Tooltip format cascade**: `valueFormat` (ordinal) / `xFormat` / `yFormat` (XY) / `valueFormat` on Heatmap flow to the default tooltip automatically, so axis and tooltip read identically. Only applies to the default tooltip — a custom `tooltip` prop fully overrides; re-pass the formatter inside `Tooltip({format})` / `MultiLineTooltip({fields:[{format}]})` if you want it there. Bespoke-tooltip charts (Histogram, FunnelChart, LikertChart, GaugeChart) don't participate; customize via `tooltip`.
 - **Horizontal bars**: Need wider left margin: `margin={{ left: 120 }}`.
 - **Push API**: Omit `data` entirely. `data={[]}` clears on every render.
 - **frameProps style functions**: Bypass HOC color resolution — use `colorBy` prop instead.
@@ -189,6 +207,7 @@ Serialization: `themeToCSS(theme, selector)`, `themeToTokens(theme)`, `resolveTh
 - **scalePadding**: Pixel inset on scale ranges. Pass via `frameProps={{ scalePadding: 12 }}`.
 - **categoryFormat/xFormat/yFormat**: Can return ReactNode (renders in `<foreignObject>`).
 - **Tick deduplication**: Adjacent identical labels auto-removed.
+- **Composing overlays**: XY/Ordinal charts paint `--semiotic-bg` across the full canvas by default, hiding anything beneath. When stacking charts (e.g. `position: absolute` overlay on top of a base), pass `frameProps={{ background: "transparent" }}` on the overlay to skip the fill. Network/Geo frames don't paint bg by default, so this only matters for XY/Ordinal.
 
 ## Performance
 

package/README.md

@@ -34,7 +34,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 all 38 chart components, optimized for LLM code generation
+- **`semiotic/ai`** — a single import with 35 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.
 - **`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

package/ai/dist/mcp-server.js

@@ -24642,10 +24642,9 @@ var ProgressTokenSchema = union([string2(), number2().int()]);
 var CursorSchema = string2();
 var TaskCreationParamsSchema = looseObject({
   /**
-   * Time in milliseconds to keep task results available after completion.
-   * If null, the task has unlimited lifetime until manually cleaned up.
+   * Requested duration in milliseconds to retain task from creation.
    */
-  ttl: union([number2(), _null3()]).optional(),
+  ttl: number2().optional(),
   /**
    * Time in milliseconds to wait between task status requests.
    */
@@ -24945,7 +24944,11 @@ var ClientCapabilitiesSchema = object2({
   /**
    * Present if the client supports task creation.
    */
-  tasks: ClientTasksCapabilitySchema.optional()
+  tasks: ClientTasksCapabilitySchema.optional(),
+  /**
+   * Extensions that the client supports. Keys are extension identifiers (vendor-prefix/extension-name).
+   */
+  extensions: record(string2(), AssertObjectSchema).optional()
 });
 var InitializeRequestParamsSchema = BaseRequestParamsSchema.extend({
   /**
@@ -25007,7 +25010,11 @@ var ServerCapabilitiesSchema = object2({
   /**
    * Present if the server supports task creation.
    */
-  tasks: ServerTasksCapabilitySchema.optional()
+  tasks: ServerTasksCapabilitySchema.optional(),
+  /**
+   * Extensions that the server supports. Keys are extension identifiers (vendor-prefix/extension-name).
+   */
+  extensions: record(string2(), AssertObjectSchema).optional()
 });
 var InitializeResultSchema = ResultSchema.extend({
   /**
@@ -25199,6 +25206,12 @@ var ResourceSchema = object2({
    * The MIME type of this resource, if known.
    */
   mimeType: optional(string2()),
+  /**
+   * The size of the raw resource content, in bytes (i.e., before base64 encoding or any tokenization), if known.
+   *
+   * This can be used by Hosts to display file sizes and estimate context window usage.
+   */
+  size: optional(number2()),
   /**
    * Optional annotations for the client.
    */
@@ -27694,6 +27707,10 @@ var Protocol = class {
     this._progressHandlers.clear();
     this._taskProgressTokens.clear();
     this._pendingDebouncedNotifications.clear();
+    for (const info of this._timeoutInfo.values()) {
+      clearTimeout(info.timeoutId);
+    }
+    this._timeoutInfo.clear();
     for (const controller of this._requestHandlerAbortControllers.values()) {
       controller.abort();
     }
@@ -27824,7 +27841,9 @@ var Protocol = class {
         await capturedTransport?.send(errorResponse);
       }
     }).catch((error48) => this._onerror(new Error(`Failed to send response: ${error48}`))).finally(() => {
-      this._requestHandlerAbortControllers.delete(request.id);
+      if (this._requestHandlerAbortControllers.get(request.id) === abortController) {
+        this._requestHandlerAbortControllers.delete(request.id);
+      }
     });
   }
   _onprogress(notification) {
@@ -29837,6 +29856,9 @@ var McpServer = class {
           annotations = rest.shift();
         }
       } else if (typeof firstArg === "object" && firstArg !== null) {
+        if (Object.values(firstArg).some((v) => typeof v === "object" && v !== null)) {
+          throw new Error(`Tool ${name} expected a Zod schema or ToolAnnotations, but received an unrecognized object`);
+        }
         annotations = rest.shift();
       }
     }
@@ -29955,6 +29977,9 @@ function getZodSchemaObject(schema2) {
   if (isZodRawShapeCompat(schema2)) {
     return objectFromShape(schema2);
   }
+  if (!isZodSchemaInstance(schema2)) {
+    throw new Error("inputSchema must be a Zod schema or raw shape, received an unrecognized object");
+  }
   return schema2;
 }
 function promptArgumentsFromSchema(schema2) {
@@ -30240,6 +30265,17 @@ var requestPrototype = {
     }
   });
 });
+Object.defineProperty(requestPrototype, /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom"), {
+  value: function(depth, options, inspectFn) {
+    const props = {
+      method: this.method,
+      url: this.url,
+      headers: this.headers,
+      nativeRequest: this[requestCache]
+    };
+    return `Request (lightweight) ${inspectFn(props, { ...options, depth: depth == null ? null : depth - 1 })}`;
+  }
+});
 Object.setPrototypeOf(requestPrototype, Request.prototype);
 var newRequest = (incoming, defaultHostname) => {
   const req = Object.create(requestPrototype);
@@ -30344,6 +30380,17 @@ var Response2 = class _Response {
     }
   });
 });
+Object.defineProperty(Response2.prototype, /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom"), {
+  value: function(depth, options, inspectFn) {
+    const props = {
+      status: this.status,
+      headers: this.headers,
+      ok: this.ok,
+      nativeResponse: this[responseCache]
+    };
+    return `Response (lightweight) ${inspectFn(props, { ...options, depth: depth == null ? null : depth - 1 })}`;
+  }
+});
 Object.setPrototypeOf(Response2, GlobalResponse);
 Object.setPrototypeOf(Response2.prototype, GlobalResponse.prototype);
 async function readWithoutBlocking(readPromise) {
@@ -30415,6 +30462,50 @@ if (typeof global.crypto === "undefined") {
   global.crypto = import_crypto.default;
 }
 var outgoingEnded = /* @__PURE__ */ Symbol("outgoingEnded");
+var incomingDraining = /* @__PURE__ */ Symbol("incomingDraining");
+var DRAIN_TIMEOUT_MS = 500;
+var MAX_DRAIN_BYTES = 64 * 1024 * 1024;
+var drainIncoming = (incoming) => {
+  const incomingWithDrainState = incoming;
+  if (incoming.destroyed || incomingWithDrainState[incomingDraining]) {
+    return;
+  }
+  incomingWithDrainState[incomingDraining] = true;
+  if (incoming instanceof import_http2.Http2ServerRequest) {
+    try {
+      ;
+      incoming.stream?.close?.(import_http2.constants.NGHTTP2_NO_ERROR);
+    } catch {
+    }
+    return;
+  }
+  let bytesRead = 0;
+  const cleanup = () => {
+    clearTimeout(timer);
+    incoming.off("data", onData);
+    incoming.off("end", cleanup);
+    incoming.off("error", cleanup);
+  };
+  const forceClose = () => {
+    cleanup();
+    const socket = incoming.socket;
+    if (socket && !socket.destroyed) {
+      socket.destroySoon();
+    }
+  };
+  const timer = setTimeout(forceClose, DRAIN_TIMEOUT_MS);
+  timer.unref?.();
+  const onData = (chunk) => {
+    bytesRead += chunk.length;
+    if (bytesRead > MAX_DRAIN_BYTES) {
+      forceClose();
+    }
+  };
+  incoming.on("data", onData);
+  incoming.on("end", cleanup);
+  incoming.on("error", cleanup);
+  incoming.resume();
+};
 var handleRequestError = () => new Response(null, {
   status: 400
 });
@@ -30586,14 +30677,18 @@ var getRequestListener = (fetchCallback, options = {}) => {
               setTimeout(() => {
                 if (!incomingEnded) {
                   setTimeout(() => {
-                    incoming.destroy();
-                    outgoing.destroy();
+                    drainIncoming(incoming);
                   });
                 }
               });
             }
           };
         }
+        outgoing.on("finish", () => {
+          if (!incomingEnded) {
+            drainIncoming(incoming);
+          }
+        });
       }
       outgoing.on("close", () => {
         const abortController = req[abortControllerKey];
@@ -30608,7 +30703,7 @@ var getRequestListener = (fetchCallback, options = {}) => {
           setTimeout(() => {
             if (!incomingEnded) {
               setTimeout(() => {
-                incoming.destroy();
+                drainIncoming(incoming);
               });
             }
           });

package/ai/schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "name": "semiotic",
-  "version": "3.3.1",
+  "version": "3.4.1",
   "description": "React data visualization library for charts, networks, and beyond",
   "tools": [
     {
@@ -932,6 +932,47 @@
         }
       }
     },
+    {
+      "type": "function",
+      "function": {
+        "name": "CandlestickChart",
+        "description": "OHLC candlestick bars, or a range chart when open/close are omitted. Honors mode (primary/context/sparkline). Range variant degrades cleanly: endpoint dots + wick, sized against canvas height so sparkline rows don't render marble-sized dots.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "data": { "type": "array", "items": { "type": "object" } },
+            "xAccessor": { "type": "string", "default": "x" },
+            "highAccessor": { "type": "string", "default": "high", "description": "Required. Upper bound (candlestick high or range top)." },
+            "lowAccessor": { "type": "string", "default": "low", "description": "Required. Lower bound (candlestick low or range bottom)." },
+            "openAccessor": { "type": "string", "description": "Optional. Pair with closeAccessor for OHLC; omit both to render a range chart." },
+            "closeAccessor": { "type": "string", "description": "Optional. See openAccessor." },
+            "candlestickStyle": {
+              "type": "object",
+              "description": "Style overrides.",
+              "properties": {
+                "upColor": { "type": "string" },
+                "downColor": { "type": "string" },
+                "wickColor": { "type": "string" },
+                "wickWidth": { "type": "number" },
+                "bodyWidth": { "type": "number" },
+                "rangeColor": { "type": "string", "description": "Color for range-mode dots and wick." }
+              }
+            },
+            "mode": { "type": "string", "enum": ["primary", "context", "sparkline"] },
+            "xLabel": { "type": "string" },
+            "yLabel": { "type": "string" },
+            "title": { "type": "string" },
+            "width": { "type": "number", "default": 600 },
+            "height": { "type": "number", "default": 400 },
+            "enableHover": { "type": "boolean", "default": true },
+            "showGrid": { "type": "boolean", "default": false },
+            "margin": { "type": "object" },
+            "annotations": { "type": "array", "items": { "type": "object" } }
+          },
+          "required": ["highAccessor", "lowAccessor"]
+        }
+      }
+    },
     {
       "type": "function",
       "function": {

package/ai/system-prompt.md

@@ -109,6 +109,10 @@ Or use ThemeProvider with 15 named presets: `<ThemeProvider theme="tufte">`, `"t
 
 `semiotic/themes` entry point: `themeToCSS(theme, selector)` generates CSS string, `themeToTokens(theme)` generates DTCG design tokens, `resolveThemePreset("tufte")` returns theme object by name. Theme objects: `TUFTE_LIGHT`, `TUFTE_DARK`, `PASTELS_LIGHT`, `BI_TOOL_LIGHT`, `ITALIAN_LIGHT`, `JOURNALIST_LIGHT`, `PLAYFUL_LIGHT`, etc.
 
+**Semantic status roles**: Every preset defines `colors.success`, `colors.danger`, `colors.warning`, `colors.error`, `colors.info`, plus `colors.secondary` and `colors.surface`. Each emits as a `--semiotic-{role}` CSS custom property via ThemeProvider. Use for status-driven charts: `<Waterfall positiveColor="var(--semiotic-success)" negativeColor="var(--semiotic-danger)" />`, bar stroke delineation `<RealtimeHistogram stroke="var(--semiotic-border)" />`, status annotations.
+
+**Scoped CSS cascade override** (per-subtree, no ThemeProvider needed): wrap in `<div style={{ "--semiotic-danger": "#c00" }}>` — every chart beneath inherits the override via canvas CSS-var lookup (`getComputedStyle` on the canvas's DOM ancestor). Use CSS vars for **single-role** overrides, nested `ThemeProvider` for **array/scale** overrides.
+
 `COLOR_BLIND_SAFE_CATEGORICAL` — 8-color accessible palette (Wong 2011). Import from `semiotic`.
 
 ## Key Patterns

package/dist/components/Annotation.d.ts

@@ -1,3 +1,43 @@
 import * as React from "react";
-import { AnnotationProps } from "./types/annotationTypes";
-export default function SemioticAnnotation(props: AnnotationProps): React.JSX.Element;
+/** Props for the single-annotation renderer. Consumed only by `SemioticAnnotation`
+ *  below; the broader annotation API flows through the frame-level `annotations`
+ *  array and its `svgAnnotationRules` hook. */
+export interface AnnotationProps {
+    noteData: {
+        eventListeners?: Record<string, (e: React.SyntheticEvent) => void>;
+        events?: Record<string, (e: React.SyntheticEvent) => void>;
+        type: string;
+        screenCoordinates?: number[][];
+        /** When truthy, `screenCoordinates` is read as a sequence of anchor points
+         *  and one annotation renders per coordinate with `nx`/`ny` shared. */
+        coordinates?: boolean;
+        noteHeight?: number | ((d: Record<string, unknown>) => number);
+        noteWidth?: number | ((d: Record<string, unknown>) => number);
+        x: number | number[];
+        y: number | number[];
+        nx?: number;
+        ny?: number;
+        dx?: number;
+        dy?: number;
+        note: {
+            label?: string;
+            title?: string;
+            wrap?: number;
+            orientation?: string;
+            align?: string;
+            noWrap?: boolean;
+        };
+        i?: number;
+        fixedPosition?: boolean;
+        label?: string;
+        connector?: {
+            end?: "arrow";
+        };
+        subject?: Record<string, unknown>;
+        color?: string;
+        className?: string;
+        disable?: string[];
+        [key: string]: unknown;
+    };
+}
+export default function SemioticAnnotation(props: AnnotationProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/CategoryColors.d.ts

@@ -37,7 +37,7 @@ export interface CategoryColorProviderProps {
  * </CategoryColorProvider>
  * ```
  */
-export declare function CategoryColorProvider({ colors, categories, colorScheme, children, }: CategoryColorProviderProps): React.JSX.Element;
+export declare function CategoryColorProvider({ colors, categories, colorScheme, children, }: CategoryColorProviderProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace CategoryColorProvider {
     var displayName: string;
 }

package/dist/components/ChartGrid.d.ts

@@ -33,7 +33,7 @@ export interface ChartGridProps {
  * </ChartGrid>
  * ```
  */
-export declare function ChartGrid({ children, columns, minCellWidth, gap, className, style, }: ChartGridProps): React.JSX.Element;
+export declare function ChartGrid({ children, columns, minCellWidth, gap, className, style, }: ChartGridProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace ChartGrid {
     var displayName: string;
 }

package/dist/components/ContextLayout.d.ts

@@ -32,7 +32,7 @@ export interface ContextLayoutProps {
  * </ContextLayout>
  * ```
  */
-export declare function ContextLayout({ children, context, position, contextSize, gap, className, style, }: ContextLayoutProps): React.JSX.Element;
+export declare function ContextLayout({ children, context, position, contextSize, gap, className, style, }: ContextLayoutProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace ContextLayout {
     var displayName: string;
 }

package/dist/components/DataSummaryContext.d.ts

@@ -6,7 +6,7 @@ interface DataSummaryState {
 }
 export declare function DataSummaryProvider({ children }: {
     children: React.ReactNode;
-}): React.JSX.Element;
+}): import("react/jsx-runtime").JSX.Element;
 export declare function useDataSummary(): DataSummaryState | null;
 export declare function useDataSummaryToggle(): (() => void) | null;
 export {};

package/dist/components/DetailsPanel.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "./charts/shared/datumTypes";
 import * as React from "react";
 import type { ChartObservation, ClickObservation } from "./store/ObservationStore";
 export interface DetailsPanelProps {
@@ -5,7 +6,7 @@ export interface DetailsPanelProps {
      * Render function receiving the clicked datum and the full observation.
      * Return null to hide the panel for a given datum.
      */
-    children: (datum: Record<string, any>, observation: ClickObservation) => React.ReactNode;
+    children: (datum: Datum, observation: ClickObservation) => React.ReactNode;
     /** Panel position relative to the chart. Default: "right" */
     position?: "right" | "bottom" | "overlay";
     /** Panel width (for "right" position) or height (for "bottom"). Default: 300 */
@@ -31,7 +32,7 @@ export interface DetailsPanelProps {
     /** Inline style overrides */
     style?: React.CSSProperties;
 }
-export declare function DetailsPanel({ children, position, size, trigger, chartId, observation: directObservation, dismissOnEmpty, showClose, onToggle, className, style, }: DetailsPanelProps): React.JSX.Element | null;
+export declare function DetailsPanel({ children, position, size, trigger, chartId, observation: directObservation, dismissOnEmpty, showClose, onToggle, className, style, }: DetailsPanelProps): import("react/jsx-runtime").JSX.Element | null;
 export declare namespace DetailsPanel {
     var displayName: string;
 }

package/dist/components/Legend.d.ts

@@ -1,9 +1,8 @@
-import * as React from "react";
 import { LegendProps, GradientLegendConfig } from "./types/legendTypes";
 /** Gradient legend for continuous/sequential color scales */
 export declare function GradientLegend({ config, orientation, width, }: {
     config: GradientLegendConfig;
     orientation?: "vertical" | "horizontal";
     width?: number;
-}): React.JSX.Element;
-export default function Legend(props: LegendProps): React.JSX.Element;
+}): import("react/jsx-runtime").JSX.Element;
+export default function Legend(props: LegendProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/LinkedCharts.d.ts

@@ -44,6 +44,14 @@ export interface LinkedChartsProps {
      */
     legendField?: string;
 }
+/**
+ * Mirror of the wrap logic in Legend's renderLegendGroupHorizontal:
+ * itemWidth = SWATCH(16) + 10 + label.length * 7, wrap when the cursor
+ * would exceed maxWidth. Used only to size the container SVG — the
+ * authoritative layout still happens inside <Legend>. When width is
+ * unknown (e.g. first paint, SSR), return 1 so we don't pre-grow.
+ */
+export declare function estimateLegendRowCount(labels: string[], width: number): number;
 /**
  * LinkedCharts — context provider for coordinated chart views.
  *
@@ -74,4 +82,4 @@ export interface LinkedChartsProps {
  * </LinkedCharts>
  * ```
  */
-export declare function LinkedCharts({ children, selections, showLegend, legendPosition, legendInteraction, legendSelectionName, legendField, }: LinkedChartsProps): React.JSX.Element;
+export declare function LinkedCharts({ children, selections, showLegend, legendPosition, legendInteraction, legendSelectionName, legendField, }: LinkedChartsProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/ThemeProvider.d.ts

@@ -7,7 +7,7 @@ interface ThemeProviderProps {
     theme?: ThemePresetName | Partial<SemioticTheme>;
     children: React.ReactNode;
 }
-declare function ThemeProviderWrapper({ theme, children }: ThemeProviderProps): React.JSX.Element;
+declare function ThemeProviderWrapper({ theme, children }: ThemeProviderProps): import("react/jsx-runtime").JSX.Element;
 declare function useTheme(): SemioticTheme;
 export { ThemeProviderWrapper as ThemeProvider, useTheme };
 export { LIGHT_THEME, DARK_THEME, HIGH_CONTRAST_THEME };

package/dist/components/Tooltip/FlippingTooltip.d.ts

@@ -30,5 +30,5 @@ interface FlippingTooltipProps {
  * After measuring the actual tooltip size via ref, repositions precisely to
  * prevent clipping against container edges.
  */
-export declare function FlippingTooltip({ x, y, containerWidth, containerHeight, margin, children, className, zIndex }: FlippingTooltipProps): React.JSX.Element;
+export declare function FlippingTooltip({ x, y, containerWidth, containerHeight, margin, children, className, zIndex }: FlippingTooltipProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/Tooltip/Tooltip.d.ts

@@ -1,5 +1,6 @@
 import * as React from "react";
 import type { Accessor } from "../charts/shared/types";
+import type { Datum } from "../charts/shared/datumTypes";
 /**
  * Configuration for a single tooltip field
  */
@@ -87,7 +88,7 @@ export declare const defaultTooltipStyle: React.CSSProperties;
  * />
  * ```
  */
-export declare function Tooltip(config?: TooltipConfig): (data: Record<string, unknown>) => React.JSX.Element | null;
+export declare function Tooltip(config?: TooltipConfig): (data: Record<string, unknown>) => import("react/jsx-runtime").JSX.Element | null;
 /**
  * Create a multi-line tooltip that displays multiple fields
  *
@@ -130,7 +131,7 @@ export declare function Tooltip(config?: TooltipConfig): (data: Record<string, u
  * />
  * ```
  */
-export declare function MultiLineTooltip(config?: MultiLineTooltipConfig): (data: Record<string, unknown>) => React.JSX.Element | null;
+export declare function MultiLineTooltip(config?: MultiLineTooltipConfig): (data: Record<string, unknown>) => import("react/jsx-runtime").JSX.Element | null;
 /**
  * Type for tooltip prop that chart components accept
  */
@@ -139,7 +140,7 @@ export type TooltipProp = boolean | "multi" | ((data: Record<string, unknown>) =
  * The function signature that Stream Frames expect for tooltipContent.
  * Compatible with HoverData and any Record-based hover object.
  */
-export type TooltipContentFn = (d: Record<string, any>) => React.ReactNode;
+export type TooltipContentFn = (d: Datum) => React.ReactNode;
 /**
  * Multi-point tooltip: shows all series values at the hovered X position
  * with color swatches (legend-style). Used when tooltipMode="multi".

package/dist/components/charts/geo/ChoroplethMap.d.ts

@@ -1,10 +1,10 @@
-import * as React from "react";
+import type { Datum } from "../shared/datumTypes";
 import type { StreamGeoFrameProps, ProjectionProp } from "../../stream/geoTypes";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { LegendInteractionMode } from "../shared/hooks";
 import { type AreasProp } from "../../geo/useReferenceAreas";
-export interface ChoroplethMapProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
+export interface ChoroplethMapProps<TDatum extends Datum = Datum> extends BaseChartProps {
     /** GeoJSON features or a reference string ("world-110m", "world-50m", "land-110m", "land-50m") */
     areas: AreasProp;
     /** Accessor for the numeric value to encode as color */
@@ -43,11 +43,11 @@ export interface ChoroplethMapProps<TDatum extends Record<string, any> = Record<
     /** Fill opacity for area polygons. Useful for layering over tile basemaps. @default 1 */
     areaOpacity?: number;
     /** Annotations */
-    annotations?: Record<string, any>[];
+    annotations?: Datum[];
     /** Passthrough to StreamGeoFrame */
     frameProps?: Partial<Omit<StreamGeoFrameProps, "areas" | "projection">>;
 }
-export declare function ChoroplethMap<TDatum extends Record<string, any> = Record<string, any>>(props: ChoroplethMapProps<TDatum>): React.JSX.Element;
+export declare function ChoroplethMap<TDatum extends Datum = Datum>(props: ChoroplethMapProps<TDatum>): import("react/jsx-runtime").JSX.Element;
 export declare namespace ChoroplethMap {
     var displayName: string;
 }