semiotic 3.5.2 → 3.5.3

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` (83KB gz), `semiotic/ordinal` (67KB gz), `semiotic/network` (62KB gz), `semiotic/geo` (50KB gz), `semiotic/realtime` (88KB gz), `semiotic/server` (114KB gz), `semiotic/utils` (22KB gz), `semiotic/recipes` (5KB gz), `semiotic/themes` (4KB gz), `semiotic/data` (3KB gz), `semiotic/ai` (184KB gz). Full `semiotic` is 183KB gz.
+- **Use sub-path imports** — `semiotic/xy` (85KB gz), `semiotic/ordinal` (68KB gz), `semiotic/network` (63KB gz), `semiotic/geo` (51KB gz), `semiotic/realtime` (90KB gz), `semiotic/server` (117KB gz), `semiotic/utils` (22KB gz), `semiotic/recipes` (5KB gz), `semiotic/themes` (4KB gz), `semiotic/data` (3KB gz), `semiotic/ai` (188KB gz). Full `semiotic` is 186KB gz.
 <!-- semiotic-bundle-sizes:end -->
 - CLI: `npx semiotic-ai [--schema|--compact|--examples|--doctor]`
 - MCP: `npx semiotic-mcp`
@@ -15,7 +15,7 @@
 - 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), `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), `axisExtent` ("nice" default | "exact" — pins first/last tick to actual data min/max with equidistant intermediates. Applies to XY x/y axes and ordinal value axis only; no-op on network/geo/hierarchy. Explicit `tickValues` still wins.)
+`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), `loadingContent` (ReactNode — replaces the default skeleton when `loading` is true; pass `false` to suppress the loading UI entirely), `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), `axisExtent` ("nice" default | "exact" — pins first/last tick to actual data min/max with equidistant intermediates. Applies to XY x/y axes and ordinal value axis only; no-op on network/geo/hierarchy. Explicit `tickValues` still wins.)
 
 **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.
 
@@ -23,8 +23,8 @@
 
 ## XY Charts (`semiotic/xy`)
 
-**LineChart** — `data`, `xAccessor` ("x"), `yAccessor` ("y"), `lineBy`, `lineDataAccessor`, `colorBy`, `colorScheme`, `curve`, `lineWidth` (2), `showPoints`, `pointRadius` (3), `fillArea` (boolean|string[]), `areaOpacity` (0.3), `lineGradient`, `anomaly`, `forecast`, `directLabel`, `gapStrategy`, `xScaleType`/`yScaleType` ("linear"|"log"|"time"), `tooltip="multi"` for hover-anywhere series comparison
-**AreaChart** — LineChart props + `areaBy`, `y0Accessor`, `gradientFill`, `areaOpacity` (0.7), `showLine` (true), `tooltip="multi"` for hover-anywhere area comparison
+**LineChart** — `data`, `xAccessor` ("x"), `yAccessor` ("y"), `lineBy`, `lineDataAccessor`, `colorBy`, `colorScheme`, `curve`, `lineWidth` (2), `showPoints`, `pointRadius` (3), `fillArea` (boolean|string[]), `areaOpacity` (0.3), `lineGradient`, `anomaly`, `forecast`, `band` (asymmetric min/max envelope: `{ y0Accessor, y1Accessor, style?, perSeries?, interactive? }` or array for fan charts; participates in yExtent; non-interactive by default; hovered datum is enriched with `band: {y0,y1}` and `bands: [...]`), `directLabel`, `gapStrategy`, `xScaleType`/`yScaleType` ("linear"|"log"|"time"), `tooltip="multi"` for hover-anywhere series comparison
+**AreaChart** — LineChart props + `areaBy`, `y0Accessor`, `gradientFill`, `areaOpacity` (0.7), `showLine` (true), `band` (same shape as LineChart — decorative envelope under the area), `tooltip="multi"` for hover-anywhere area comparison
 **DifferenceChart** — Two-series A/B comparison. Fills the area between with `seriesAColor` where A > B and `seriesBColor` where B > A; crossovers interpolated. Props: `data`, `xAccessor` ("x"), `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` (max raw rows in push buffer; FIFO eviction). Push API via `ref.current.push({x, a, b})`. Accessor outputs coerce through `toNumber` so `Date` + numeric strings are accepted.
 **StackedAreaChart** — flat array + `areaBy` (required), `colorBy`, `normalize`, `baseline` (`"zero"` default | `"wiggle"` streamgraph | `"silhouette"` centered), `stackOrder` (`"key"` alpha | `"insideOut"` largest-in-middle | `"asc"`/`"desc"`). Streamgraph: `baseline="wiggle"` + `stackOrder="insideOut"`. `baseline` ⊥ `normalize`. No `lineBy`/`lineDataAccessor`. `tooltip="multi"` lists every series at the hovered x (values interpolated between samples).
 **Scatterplot** — `data`, `xAccessor`, `yAccessor`, `colorBy`, `sizeBy`, `sizeRange`, `pointRadius` (5), `pointOpacity` (0.8), `marginalGraphics`, `regression` (boolean | "linear" | "polynomial" | "loess" | RegressionConfig — sugar for a trend-annotation overlay; sits underneath user annotations)
@@ -61,7 +61,7 @@ All ordinal: `colorBy`, `colorScheme`, `categoryFormat` (string|ReactNode), `sho
 
 **ForceDirectedGraph** — `nodes`, `edges`, `nodeIDAccessor`, `sourceAccessor`, `targetAccessor`, `colorBy`, `nodeSize`, `nodeSizeRange`, `edgeWidth`, `iterations` (300), `forceStrength` (0.1), `showLabels`, `nodeLabel`
 **SankeyDiagram** — `edges`, `nodes`, `valueAccessor`, `nodeIdAccessor`, `colorBy`, `edgeColorBy`, `orientation`, `nodeAlign`, `nodeWidth`, `nodePaddingRatio`, `showLabels`
-**ProcessSankey** — temporal sankey with a real time x-axis. `nodes`, `edges` (each with `startTime`/`endTime`), `domain` (required `[t0, t1]`), `axisTicks?`, `xExtentAccessor` (optional `[start, end]` lifetime per node — lane spans `min(xExtent[0], earliestEdge)` to `max(xExtent[1], latestEdge)`), `colorBy`/`colorScheme`/`showLegend`/`legendPosition`, `pairing` ("value"|"temporal"), `packing` ("off"|"reuse"), `laneOrder` ("crossing-min"|"inside-out"|"crossing-min+inside-out"|"insertion"), `lifetimeMode` ("full"|"half"), `ribbonLane` ("source"|"target"|"both"), `showLaneRails`, `showQualityReadout`, `showParticles` + `particleStyle` (same shape as SankeyDiagram, canvas + ParticlePool), `timeFormat`/`valueFormat`, push API via ref. Static-graph cycles are valid as long as edges move forward in time. Use for time-stamped flow events; use `SankeyDiagram` for static total-flow snapshots.
+**ProcessSankey** — temporal sankey with a real time x-axis. `nodes`, `edges` (each with `startTime`/`endTime`), `domain` (required `[t0, t1]`), `axisTicks?`, `xExtentAccessor` (optional `[start, end]` lifetime per node — lane spans `min(xExtent[0], earliestEdge)` to `max(xExtent[1], latestEdge)`), `colorBy`/`colorScheme`/`showLegend`/`legendPosition`, `pairing` ("value"|"temporal"), `packing` ("off"|"reuse"), `laneOrder` ("crossing-min"|"inside-out"|"crossing-min+inside-out"|"insertion"), `lifetimeMode` ("full"|"half"), `ribbonLane` ("source"|"target"|"both"), `showLaneRails`, `showLabels` (default true), `showQualityReadout`, `showParticles` + `particleStyle` (same shape as SankeyDiagram, canvas + ParticlePool), `timeFormat`/`valueFormat`, push API via ref. Static-graph cycles are valid as long as edges move forward in time. Use for time-stamped flow events; use `SankeyDiagram` for static total-flow snapshots.
 **ChordDiagram** — `edges`, `nodes`, `valueAccessor`, `edgeColorBy`, `padAngle`, `showLabels`
 **TreeDiagram** — `data` (root), `layout`, `orientation`, `childrenAccessor`, `colorBy`, `colorByDepth`
 **Treemap** — `data` (root), `childrenAccessor`, `valueAccessor`, `colorBy`, `colorByDepth`, `showLabels`
@@ -243,7 +243,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-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`.
+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-tick-font-size` (10px default — drives axis tick text), `--semiotic-axis-label-font-size` (12px default — drives axis-label text + foreignObject ticks), `--semiotic-tooltip-bg`/`text`/`radius`/`font-size`/`shadow`.
 
 ```jsx
 <ThemeProvider theme="tufte">       {/* Named preset */}
@@ -309,7 +309,8 @@ These rules are generated from `ai/behaviorContracts.cjs` and are consumed by `s
 - **fillArea**: `fillArea={["seriesA"]}` fills named series only. Names must match `lineBy`/`colorBy` keys.
 - **hoverHighlight**: Requires `colorBy` as a string field.
 - **tooltip="multi"**: Shows all series at hovered X for LineChart, AreaChart, and StackedAreaChart. Custom fn receives `datum.allSeries`.
-- **Axis config**: `frameProps.axes: [{ orient, includeMax, autoRotate, gridStyle, landmarkTicks }]`
+- **Axis config**: `frameProps.axes: [{ orient, includeMax, autoRotate, gridStyle, landmarkTicks, tickAnchor }]`. `tickAnchor: "edges"` flips the first tick's `text-anchor` to `start` and the last to `end` on horizontal axes (and `dominant-baseline` to `hanging`/`auto` on vertical axes) so edge labels don't overflow the plot. Pairs naturally with `axisExtent: "exact"`.
+- **Targeting individual axes from CSS**: every axis renders as its own `<g class="semiotic-axis semiotic-axis-{bottom|left|right|top}" data-orient="…">`. Style with `[data-orient="left"] text { font-size: 14px }` or via the class names — no `!important` needed because the CSS-var defaults are set inline via `var(--semiotic-tick-font-size, …)`, so cascade overrides win cleanly. Tick text carries `class="semiotic-axis-tick"`; labels carry `class="semiotic-axis-label"`; titles carry `class="semiotic-chart-title"`.
 - **xScaleType: "time"**: Creates `scaleTime`. Required for landmark ticks with timestamps.
 - **scalePadding**: Pixel inset on scale ranges. Pass via `frameProps={{ scalePadding: 12 }}`.
 - **categoryFormat/xFormat/yFormat**: Can return ReactNode (renders in `<foreignObject>`).

package/README.md

@@ -35,7 +35,7 @@ generate correct code without examples.
 Semiotic ships with everything an AI coding assistant needs to generate
 correct visualizations without trial and error:
 
-- **`semiotic/ai`** — a single import with 40 HOC charts (XY, ordinal, network, realtime), optimized for LLM code generation. Geo charts are in `semiotic/geo` to keep d3-geo out of non-geo bundles.
+- **`semiotic/ai`** — a single import with 41 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
@@ -240,12 +240,12 @@ import { LineChart, BarChart } from "semiotic"
 
 | Category | Components |
 |---|---|
-| **XY** | `LineChart` `AreaChart` `StackedAreaChart` `Scatterplot` `ConnectedScatterplot` `BubbleChart` `Heatmap` `QuadrantChart` `MultiAxisLineChart` `MinimapChart` |
-| **Categorical** | `BarChart` `StackedBarChart` `GroupedBarChart` `LikertChart` `SwimlaneChart` `FunnelChart` `SwarmPlot` `BoxPlot` `Histogram` `ViolinPlot` `RidgelinePlot` `DotPlot` `PieChart` `DonutChart` |
-| **Network** | `ForceDirectedGraph` `ChordDiagram` `SankeyDiagram` `TreeDiagram` `Treemap` `CirclePack` `OrbitDiagram` |
+| **XY** | `LineChart` `AreaChart` `DifferenceChart` `StackedAreaChart` `Scatterplot` `ConnectedScatterplot` `BubbleChart` `Heatmap` `QuadrantChart` `MultiAxisLineChart` `MinimapChart` `CandlestickChart` `ScatterplotMatrix` |
+| **Categorical** | `BarChart` `StackedBarChart` `GroupedBarChart` `LikertChart` `SwimlaneChart` `FunnelChart` `SwarmPlot` `BoxPlot` `Histogram` `ViolinPlot` `RidgelinePlot` `DotPlot` `PieChart` `DonutChart` `GaugeChart` |
+| **Network** | `ForceDirectedGraph` `ChordDiagram` `SankeyDiagram` `ProcessSankey` `TreeDiagram` `Treemap` `CirclePack` `OrbitDiagram` |
 | **Geo** | `ChoroplethMap` `ProportionalSymbolMap` `FlowMap` `DistanceCartogram` |
 | **Realtime** | `RealtimeLineChart` `RealtimeHistogram` `RealtimeSwarmChart` `RealtimeWaterfallChart` `RealtimeHeatmap` |
-| **Coordination** | `LinkedCharts` `ScatterplotMatrix` |
+| **Coordination** | `LinkedCharts` |
 | **Layout** | `ChartGrid` `ContextLayout` `CategoryColorProvider` |
 | **Frames** | `StreamXYFrame` `StreamOrdinalFrame` `StreamNetworkFrame` `StreamGeoFrame` |
 
@@ -287,18 +287,18 @@ Semiotic ships 12 entry points. **Don't import from `"semiotic"` unless you need
 
 | Entry Point | gzip | What's inside |
 |---|---|---|
-| `semiotic/xy` | **83 KB** | LineChart, AreaChart, Scatterplot, Heatmap, + 8 more XY charts |
-| `semiotic/ordinal` | **67 KB** | BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts |
-| `semiotic/network` | **62 KB** | ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4 more |
-| `semiotic/geo` | **50 KB** | ChoroplethMap, FlowMap, DistanceCartogram, ProportionalSymbolMap |
-| `semiotic/realtime` | **88 KB** | RealtimeLineChart, RealtimeHistogram, + 3 streaming charts |
-| `semiotic/server` | **114 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
+| `semiotic/xy` | **85 KB** | LineChart, AreaChart, Scatterplot, Heatmap, + 8 more XY charts |
+| `semiotic/ordinal` | **68 KB** | BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts |
+| `semiotic/network` | **63 KB** | ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4 more |
+| `semiotic/geo` | **51 KB** | ChoroplethMap, FlowMap, DistanceCartogram, ProportionalSymbolMap |
+| `semiotic/realtime` | **90 KB** | RealtimeLineChart, RealtimeHistogram, + 3 streaming charts |
+| `semiotic/server` | **117 KB** | renderChart, renderDashboard, renderToImage, renderToAnimatedGif |
 | `semiotic/utils` | **22 KB** | ThemeProvider, validators, serialization — no chart components |
 | `semiotic/recipes` | **5 KB** | Pure layout functions (waffle, marimekko, flextree, dagre, …) |
 | `semiotic/themes` | **4 KB** | Theme presets only (tufte, carbon, etc.) |
 | `semiotic/data` | **3 KB** | bin, rollup, groupBy, pivot, fromVegaLite |
-| `semiotic/ai` | **184 KB** | All 40 HOCs + validation — optimized for LLM code generation |
-| `semiotic` | **183 KB** | Everything below (full bundle) |
+| `semiotic/ai` | **188 KB** | All 41 HOCs + validation — optimized for LLM code generation |
+| `semiotic` | **186 KB** | Everything below (full bundle) |
 
 <!-- semiotic-bundle-sizes:end -->
 
@@ -389,7 +389,7 @@ No API keys or authentication required. The server runs locally via stdio. HTTP
 | Tool | Description |
 |------|-------------|
 | **`renderChart`** | Render a Semiotic chart to static SVG. Supports the components returned by `getSchema` that are marked `[renderable]`. Pass `{ component: "LineChart", props: { data: [...], xAccessor: "x", yAccessor: "y" } }`. Returns SVG string or validation errors with fix suggestions. |
-| **`getSchema`** | Return the prop schema for a specific component. Pass `{ component: "LineChart" }` to get its props, or omit `component` to list all 43 chart schemas. Components marked `[renderable]` are available through `renderChart`; realtime charts require a browser/live environment. |
+| **`getSchema`** | Return the prop schema for a specific component. Pass `{ component: "LineChart" }` to get its props, or omit `component` to list all 45 chart schemas. Components marked `[renderable]` are available through `renderChart`; realtime charts require a browser/live environment. |
 | **`suggestChart`** | Recommend chart types for a data sample. Pass `{ data: [{...}, ...] }` with 1–5 sample objects. Optionally include `intent` (`"comparison"`, `"trend"`, `"distribution"`, `"relationship"`, `"composition"`, `"geographic"`, `"network"`, `"hierarchy"`). Returns ranked suggestions with example props. |
 | **`diagnoseConfig`** | Check a chart configuration for common problems — empty data, bad dimensions, missing accessors, wrong data shape, and more. Returns a human-readable diagnostic report with actionable fixes. |
 | **`reportIssue`** | Generate a pre-filled GitHub issue URL for bug reports or feature requests. Pass `{ title: "...", body: "...", labels: ["bug"] }`. Returns a URL the user can open to submit. |
@@ -502,7 +502,7 @@ Semiotic is indexed by AI-coding-agent documentation tools so your assistant (Cl
 
 Agent-facing API surface:
 
-- **`CLAUDE.md`**, **`ai/schema.json`**, **`ai/behaviorContracts.cjs`** — bundled in the npm tarball (see `package.json#files`); agents that install Semiotic locally read these directly. `CLAUDE.md` is the quick-start cheat sheet (HOC props, push API, theming, usage notes); `ai/schema.json` is the JSON Schema for every chart's prop surface (44 charts); `ai/behaviorContracts.cjs` carries the agent-visible semantic rules (color precedence, push-mode requirements, ID-accessor contracts).
+- **`CLAUDE.md`**, **`ai/schema.json`**, **`ai/behaviorContracts.cjs`** — bundled in the npm tarball (see `package.json#files`); agents that install Semiotic locally read these directly. `CLAUDE.md` is the quick-start cheat sheet (HOC props, push API, theming, usage notes); `ai/schema.json` is the JSON Schema for every chart's prop surface (45 charts); `ai/behaviorContracts.cjs` carries the agent-visible semantic rules (color precedence, push-mode requirements, ID-accessor contracts).
 - [**`semiotic.nteract.io/llms.txt`**](https://semiotic.nteract.io/llms.txt) + [**`/llms-full.txt`**](https://semiotic.nteract.io/llms-full.txt) — deployed at the docs site per the [llms.txt standard](https://llmstxt.org). Agents fetch the navigation map (`llms.txt`) or the full inlined docs (`llms-full.txt`) over HTTP; they're not part of the npm package itself.
 
 ## Documentation

package/ai/schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "name": "semiotic",
-  "version": "3.5.2",
+  "version": "3.5.3",
   "description": "React data visualization library for charts, networks, and beyond",
   "tools": [
     {
@@ -188,6 +188,13 @@
             "anomaly": {
               "type": "object",
               "description": "Anomaly overlay config — ±σ band + anomaly dot annotations. See AnomalyConfig."
+            },
+            "band": {
+              "type": [
+                "object",
+                "array"
+              ],
+              "description": "Asymmetric min/max envelope drawn under the line. `{ y0Accessor, y1Accessor, style?, perSeries?, interactive? }` or an array of those for percentile fans. Distinct from `forecast`/`anomaly` (computed) — band is pure data passthrough. Hovered datum is enriched with `band: { y0, y1 }` and `bands: [...]`."
             }
           },
           "required": [
@@ -368,6 +375,13 @@
             "anomaly": {
               "type": "object",
               "description": "Anomaly overlay config — ±σ band + anomaly dot annotations. See AnomalyConfig."
+            },
+            "band": {
+              "type": [
+                "object",
+                "array"
+              ],
+              "description": "Asymmetric min/max envelope drawn under the area. See LineChart.band — same shape, same enrichment."
             }
           },
           "required": [

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` (83KB gz), `semiotic/ordinal` (67KB gz), `semiotic/network` (62KB gz), `semiotic/geo` (50KB gz), `semiotic/realtime` (88KB gz), `semiotic/server` (114KB gz), `semiotic/utils` (22KB gz), `semiotic/recipes` (5KB gz), `semiotic/themes` (4KB gz), `semiotic/data` (3KB gz), `semiotic/ai` (184KB gz). Full `semiotic` is 183KB gz.
+**Use sub-path imports** — `semiotic/xy` (85KB gz), `semiotic/ordinal` (68KB gz), `semiotic/network` (63KB gz), `semiotic/geo` (51KB gz), `semiotic/realtime` (90KB gz), `semiotic/server` (117KB gz), `semiotic/utils` (22KB gz), `semiotic/recipes` (5KB gz), `semiotic/themes` (4KB gz), `semiotic/data` (3KB gz), `semiotic/ai` (188KB gz). Full `semiotic` is 186KB gz.
 <!-- semiotic-bundle-sizes:end -->
 
 ## Flat Array Data (`data: object[]`)

package/dist/components/ThemeProvider.d.ts

@@ -1,10 +1,10 @@
 import * as React from "react";
 import { LIGHT_THEME, DARK_THEME, HIGH_CONTRAST_THEME } from "./store/ThemeStore";
-import type { SemioticTheme } from "./store/ThemeStore";
+import type { SemioticTheme, SemioticThemeUpdate } from "./store/ThemeStore";
 import type { ThemePresetName } from "./semiotic-themes";
 interface ThemeProviderProps {
     /** Theme preset name (e.g. "tufte", "pastels-dark", "bi-tool") or a partial SemioticTheme object. */
-    theme?: ThemePresetName | Partial<SemioticTheme>;
+    theme?: ThemePresetName | SemioticThemeUpdate;
     children: React.ReactNode;
 }
 declare function ThemeProviderWrapper({ theme, children }: ThemeProviderProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/charts/network/ProcessSankey.d.ts

@@ -22,6 +22,24 @@ export interface ProcessSankeyProps<TNode extends Datum = Datum, TEdge extends D
     valueAccessor?: ChartAccessor<TEdge, number>;
     startTimeAccessor?: ChartAccessor<TEdge, TimeLike>;
     endTimeAccessor?: ChartAccessor<TEdge, TimeLike>;
+    /**
+     * Optional accessor for the per-edge "system in" time — when
+     * `value` is added to the SOURCE node's mass. Use when the
+     * source node has an intake event distinct from when this edge
+     * departs (e.g. a patient is admitted to the ER at 7pm and
+     * transferred out at 9pm — the ER node carries the patient's
+     * weight between 7pm and 9pm). Without this, the source node's
+     * mass is synthesized as a flat baseline and the band reads as
+     * "always there." Set it and the node band climbs / falls as
+     * units arrive and depart — a true staircase profile.
+     */
+    systemInTimeAccessor?: ChartAccessor<TEdge, TimeLike>;
+    /**
+     * Optional accessor for the per-edge "system out" time — when
+     * `value` is removed from the TARGET node's mass. Mirror of
+     * `systemInTimeAccessor` for the inbound side.
+     */
+    systemOutTimeAccessor?: ChartAccessor<TEdge, TimeLike>;
     /**
      * Accessor for a node's explicit lifetime extent — a `[start, end]`
      * tuple of time-likes. Lane spans
@@ -50,6 +68,10 @@ export interface ProcessSankeyProps<TNode extends Datum = Datum, TEdge extends D
     lifetimeMode?: "full" | "half";
     showLaneRails?: boolean;
     showQualityReadout?: boolean;
+    /** Render the per-band node id label at the band's left edge.
+     *  Default `true`. Set `false` for dense layouts where labels
+     *  would overlap, or when the legend already names every band. */
+    showLabels?: boolean;
     edgeOpacity?: number;
     /** Tooltip content. `false` disables, `true` uses the default,
      *  or pass a `Tooltip(...)` / custom function for full control. */

package/dist/components/charts/network/SankeyDiagram.d.ts

@@ -4,7 +4,7 @@ import type { StreamNetworkFrameProps } from "../../stream/networkTypes";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
-import type { LegendInteractionMode } from "../shared/hooks";
+import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 /**
  * SankeyDiagram component props
  */
@@ -25,6 +25,10 @@ export interface SankeyDiagramProps<TNode extends Datum = Datum, TEdge extends D
     nodeLabel?: ChartAccessor<TNode, string>;
     showLabels?: boolean;
     enableHover?: boolean;
+    /** Show a swatch + label legend. Defaults to `true` when `colorBy` is set. */
+    showLegend?: boolean;
+    /** Legend position. Default `"right"`. */
+    legendPosition?: LegendPosition;
     legendInteraction?: LegendInteractionMode;
     edgeOpacity?: number;
     edgeSort?: (a: any, b: any) => number;

package/dist/components/charts/network/processSankey/algorithm.d.ts

@@ -11,6 +11,25 @@ export interface ProcessSankeyEdge {
     value: number;
     startTime: number;
     endTime: number;
+    /** Optional: time at which this unit of mass actually "arrived" at
+     *  the SOURCE node (e.g., the hospital admit time for an ER patient
+     *  whose transfer to ICU happens later at `startTime`). Purely a
+     *  rendering hint — the layout/mass profile is unchanged. The
+     *  renderer cuts a rectangular slot out of the source node's band
+     *  from the node's left edge up to the scaled `systemInTime`, with
+     *  height equal to this edge's ribbon thickness. Edges without
+     *  `systemInTime` are drawn as-is. Result: a staircase profile on
+     *  the source side as units enter the system one by one.
+     *  Default: undefined. */
+    systemInTime?: number;
+    /** Optional: time at which this unit of mass leaves the TARGET node
+     *  (e.g., the discharge time for a patient who arrived at the ward
+     *  at `endTime`). Symmetric to `systemInTime`: the renderer cuts a
+     *  rectangular slot out of the target node's band from the scaled
+     *  `systemOutTime` to the node's right edge, with height equal to
+     *  this edge's ribbon thickness. Layout/mass profile unchanged.
+     *  Default: undefined. */
+    systemOutTime?: number;
 }
 export interface ProcessSankeyIssue {
     kind: string;
@@ -98,6 +117,44 @@ export declare function clampTime(t: number, domain: Domain): number;
 export declare function clampSamples(samples: ProcessSankeySample[], domain: Domain): ProcessSankeySample[];
 export declare function attachmentYRange(att: ProcessSankeyAttachment, cl: number, S: number): [number, number];
 export declare function buildBandPath(samples: ProcessSankeySample[], cl: number, S: number, xScale: (t: number) => number, domain: Domain): string | null;
+/**
+ * One 20-px gradient stub at an attachment with `systemInTime` /
+ * `systemOutTime`. Rendered as its own bezier scene-edge with a
+ * horizontal gradient, painted underneath the band. The band
+ * paints with `fill: none` whenever any stubs are present, so the
+ * stub gradients are the only colored regions inside the band's
+ * outline.
+ */
+export interface BandGradientStub {
+    /** Rect path (M-L-L-L-Z). */
+    pathD: string;
+    /** Gradient extent in screen pixels. */
+    x0: number;
+    x1: number;
+    /** Color stops — 0 = transparent end, 1 = band-color end. */
+    from: 0 | 1;
+    to: 0 | 1;
+}
+/**
+ * Build the per-edge 20-px gradient stubs that visualize
+ * `systemInTime` / `systemOutTime` on a node band. Each stub is
+ * a rect on the edge's attachment slot, painted with a horizontal
+ * gradient that fades the band color in (or out) over 20 screen
+ * pixels and saturates through the rest of the rect.
+ *
+ * The rect is clipped to the band's outline bounds (so cutouts don't
+ * spill outside the node shape), but the gradient extent stays at
+ * its natural `[xSysIn - FADE_PX, xSysIn]` / `[xSysOut, xSysOut + FADE_PX]`
+ * range. The canvas renderer uses pad-mode clamping for color stops
+ * outside the rect, so a stub whose fade region falls past the band's
+ * edge still paints solid band-color where it's visible — instead of
+ * collapsing to a degenerate gradient that the renderer would clamp
+ * to transparent.
+ *
+ * Pure rendering hint — layout/mass-profile unchanged. Returns an
+ * empty array when the node has no qualifying edges.
+ */
+export declare function buildBandCutoutsForNode(nodeId: string, edges: ProcessSankeyEdge[], layout: ProcessSankeyLayout, xScale: (t: number) => number, domain: Domain): BandGradientStub[];
 type SlotByNode = Record<string, number>;
 export declare function countCrossings(slotByNode: SlotByNode, edges: ProcessSankeyEdge[]): number;
 export declare function totalEdgeLength(slotByNode: SlotByNode, edges: ProcessSankeyEdge[]): number;

package/dist/components/charts/network/processSankey/buildScenes.d.ts

@@ -14,6 +14,12 @@ export interface ProcessSankeyNormalizedEdge {
     value: number;
     startTime: number;
     endTime: number;
+    /** Optional render-only hint: when this unit of mass actually
+     *  entered the source node. Triggers a cutout in the source band. */
+    systemInTime?: number;
+    /** Optional render-only hint: when this unit of mass left the
+     *  target node. Triggers a cutout in the target band. */
+    systemOutTime?: number;
     __raw?: Datum;
 }
 export interface BuildScenesInput {

package/dist/components/charts/network/processSankey/streamingLayout.d.ts

@@ -3,10 +3,16 @@ import type { BezierCache } from "../../../stream/networkTypes";
 import type { Datum } from "../../shared/datumTypes";
 export interface ProcessSankeyBandSpec {
     id: string;
+    /** Outer band perimeter — same path used for fill and stroke. */
     pathD: string;
     fill: string;
     stroke?: string;
     strokeWidth?: number;
+    /** Per-edge 20-px gradient stubs (band-color fade-in for
+     *  systemInTime, fade-out for systemOutTime). When at least one
+     *  stub is present, the band paints outline-only and the stubs
+     *  are the only colored regions inside the perimeter. */
+    gradientStubs?: BandGradientStub[];
     /** The user's raw node datum, surfaced as `data` in HoverData. */
     rawDatum: Datum;
     /** Pre-computed label x/y for the node band. */
@@ -14,6 +20,13 @@ export interface ProcessSankeyBandSpec {
     labelY: number;
     labelText: string;
 }
+export interface BandGradientStub {
+    pathD: string;
+    x0: number;
+    x1: number;
+    from: 0 | 1;
+    to: 0 | 1;
+}
 export interface ProcessSankeyRibbonSpec {
     id: string;
     pathD: string;

package/dist/components/charts/realtime/RealtimeHeatmap.d.ts

@@ -87,6 +87,8 @@ export interface RealtimeHeatmapProps<TDatum extends Datum = Datum> {
     selection?: SelectionConfig;
     /** Show a loading skeleton placeholder */
     loading?: boolean;
+    /** Custom content rendered in place of the default skeleton while `loading` is true. */
+    loadingContent?: React.ReactNode | false;
     /** Custom content to render when data is empty. Set to `false` to disable empty state. */
     emptyContent?: ReactNode | false;
     /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */

package/dist/components/charts/realtime/RealtimeHistogram.d.ts

@@ -103,6 +103,8 @@ export interface RealtimeHistogramProps<TDatum extends Datum = Datum> {
     transition?: TransitionConfig;
     /** Show a loading skeleton placeholder */
     loading?: boolean;
+    /** Custom content rendered in place of the default skeleton while `loading` is true. */
+    loadingContent?: React.ReactNode | false;
     /** Custom content to render when data is empty. Set to `false` to disable empty state. */
     emptyContent?: ReactNode | false;
     /** Brush configuration. `true` defaults to `{ dimension: "x", snap: "bin" }`. */

package/dist/components/charts/realtime/RealtimeLineChart.d.ts

@@ -89,6 +89,8 @@ export interface RealtimeLineChartProps<TDatum extends Datum = Datum> {
     selection?: SelectionConfig;
     /** Show a loading skeleton placeholder */
     loading?: boolean;
+    /** Custom content rendered in place of the default skeleton while `loading` is true. */
+    loadingContent?: React.ReactNode | false;
     /** Custom content to render when data is empty. Set to `false` to disable empty state. */
     emptyContent?: ReactNode | false;
     /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */

package/dist/components/charts/realtime/RealtimeSwarmChart.d.ts

@@ -87,6 +87,8 @@ export interface RealtimeSwarmChartProps<TDatum extends Datum = Datum> {
     selection?: SelectionConfig;
     /** Show a loading skeleton placeholder */
     loading?: boolean;
+    /** Custom content rendered in place of the default skeleton while `loading` is true. */
+    loadingContent?: React.ReactNode | false;
     /** Custom content to render when data is empty. Set to `false` to disable empty state. */
     emptyContent?: ReactNode | false;
     /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */

package/dist/components/charts/realtime/RealtimeWaterfallChart.d.ts

@@ -89,6 +89,8 @@ export interface RealtimeWaterfallChartProps<TDatum extends Datum = Datum> {
     selection?: SelectionConfig;
     /** Show a loading skeleton placeholder */
     loading?: boolean;
+    /** Custom content rendered in place of the default skeleton while `loading` is true. */
+    loadingContent?: React.ReactNode | false;
     /** Custom content to render when data is empty. Set to `false` to disable empty state. */
     emptyContent?: ReactNode | false;
     /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */

package/dist/components/charts/shared/tooltipUtils.d.ts

@@ -21,6 +21,17 @@ export interface TooltipFieldConfig {
 export declare function accessorName(acc: string | ((...args: any[]) => any)): string;
 export declare function formatVal(v: unknown): string;
 export declare function resolveValue(d: Datum, acc: string | ((d: Datum) => any)): unknown;
+/**
+ * Build TooltipFieldConfig rows for a `band` prop config so the default
+ * tooltip surfaces envelope values automatically. Reads from the
+ * `bands` array the hover handler synthesizes onto the datum — one
+ * row pair per configured band (low + high). String accessors are
+ * used verbatim as labels; function accessors fall back to "low"/"high".
+ *
+ * Returns an empty array when band is not configured, so the spread at
+ * the call site is a no-op for the common case.
+ */
+export declare function bandTooltipFields(band: unknown, valueFormat?: (v: any, ...rest: any[]) => React.ReactNode): TooltipFieldConfig[];
 /**
  * Build a default tooltipContent function for StreamXYFrame HOCs.
  * Receives HoverData ({ data, time, value, x, y }) and renders

package/dist/components/charts/shared/types.d.ts

@@ -78,6 +78,12 @@ export interface BaseChartProps {
     chartId?: string;
     /** Show a loading skeleton placeholder */
     loading?: boolean;
+    /** Custom content to render in place of the default skeleton when `loading` is `true`.
+     *  Sibling to `emptyContent` — use for branded loading states or progress UI.
+     *  When omitted, the built-in shimmer-bar skeleton renders.
+     *  Pass `false` to suppress the loading UI entirely (an outer wrapper's
+     *  loading state takes over). */
+    loadingContent?: React.ReactNode | false;
     /** Custom content to render when data is empty. Set to `false` to disable empty state. */
     emptyContent?: React.ReactNode | false;
     /** Uniform fill color for all data marks. Overrides colorScheme and theme categorical.

package/dist/components/charts/shared/useAreaSeriesSetup.d.ts

@@ -41,7 +41,7 @@ export interface AreaSeriesSetupOptions<TDatum extends Datum = Datum> {
     showPoints: boolean;
     /** Point radius when `showPoints`. @default 3 */
     pointRadius: number;
-    xAccessor: ChartAccessor<TDatum, number>;
+    xAccessor: ChartAccessor<TDatum, number | Date | string>;
     yAccessor: ChartAccessor<TDatum, number>;
     xLabel?: string;
     yLabel?: string;
@@ -52,6 +52,9 @@ export interface AreaSeriesSetupOptions<TDatum extends Datum = Datum> {
     /** Field used to label the series row in the default tooltip.
      *  Typically `areaBy ?? colorBy`. */
     groupField?: Accessor<string> | ChartAccessor<TDatum, string>;
+    /** Optional band prop — when set, the default tooltip surfaces a
+     *  pair of rows per band (low + high). Threaded through verbatim. */
+    band?: unknown;
 }
 export interface AreaSeriesSetupResult<TDatum extends Datum = Datum> {
     /** Flat data array ready for `<StreamXYFrame data={…} />`. Empty

package/dist/components/charts/shared/useChartSetup.d.ts

@@ -60,6 +60,8 @@ export interface ChartSetupInput {
     hoverHighlight?: boolean;
     /** Loading state */
     loading: boolean | undefined;
+    /** Custom content rendered in place of the default skeleton while `loading` is true. */
+    loadingContent?: ReactNode | false;
     /** Empty content override */
     emptyContent?: ReactNode;
     /** Resolved width from useChartMode */

package/dist/components/charts/shared/useCustomChartSetup.d.ts

@@ -64,6 +64,7 @@ interface DataSetupOptions extends ScaffoldOptions {
     }) => void;
     chartId?: string;
     loading?: boolean;
+    loadingContent?: ReactNode | false;
     emptyContent?: ReactNode;
 }
 interface DataSetupResult<TFrameHandle> extends ScaffoldResult<TFrameHandle> {

package/dist/components/charts/shared/useNetworkChartSetup.d.ts

@@ -45,6 +45,8 @@ export interface NetworkChartSetupInput<TNode extends Datum = Datum, TEdge exten
     width: number;
     height: number;
     loading?: boolean;
+    /** Custom content rendered in place of the default skeleton while `loading` is true. */
+    loadingContent?: ReactNode | false;
     emptyContent?: ReactNode | false;
     /**
      * Which array drives the empty-state check. `"edges"` (default)

package/dist/components/charts/shared/withChartWrapper.d.ts

@@ -27,10 +27,17 @@ export declare function SafeRender({ componentName, width, height, children }: S
  */
 export declare function renderEmptyState(data: any[] | undefined | null, width: number, height: number, emptyContent?: React.ReactNode | false): React.ReactElement | null;
 /**
- * Renders a shimmer/skeleton loading placeholder.
- * Returns null when loading is false.
+ * Renders a loading placeholder while `loading` is true.
+ *
+ * When `loadingContent` is provided, it replaces the default shimmer
+ * skeleton — wrapped in the same sized container so the chart still
+ * occupies the slot it would when rendered. Pass `false` to suppress
+ * the skeleton entirely (the early-return becomes null and the chart's
+ * own loading UI takes over).
+ *
+ * Returns null when `loading` is falsy.
  */
-export declare function renderLoadingState(loading: boolean | undefined, width: number, height: number): React.ReactElement | null;
+export declare function renderLoadingState(loading: boolean | undefined, width: number, height: number, loadingContent?: React.ReactNode | false): React.ReactElement | null;
 /** Warn if a string accessor isn't found in the first data element */
 export declare function warnMissingField(componentName: string, data: any[] | undefined, accessorName: string, accessorValue: any): void;
 /** Warn if data looks like the wrong shape for this chart type */

package/dist/components/charts/xy/AreaChart.d.ts

@@ -1,6 +1,6 @@
 import type { Datum } from "../shared/datumTypes";
 import * as React from "react";
-import type { StreamXYFrameProps } from "../../stream/types";
+import type { StreamXYFrameProps, BandConfig } from "../../stream/types";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
@@ -23,7 +23,7 @@ export interface AreaChartProps<TDatum extends Datum = Datum> extends BaseChartP
      * Field name or function to access x values
      * @default "x"
      */
-    xAccessor?: ChartAccessor<TDatum, number>;
+    xAccessor?: ChartAccessor<TDatum, number | Date | string>;
     /**
      * Field name or function to access y values
      * @default "y"
@@ -183,6 +183,16 @@ export interface AreaChartProps<TDatum extends Datum = Datum> extends BaseChartP
      * ```
      */
     anomaly?: AnomalyConfig;
+    /**
+     * Asymmetric min/max band(s) drawn under the area fill. Distinct from
+     * `y0Accessor` (which replaces the area's baseline) — `band` is a
+     * decorative envelope painted beneath the area, driven by independent
+     * `y0Accessor` / `y1Accessor` per band. Pass an array for fan charts.
+     *
+     * The hovered datum gets `band: { y0, y1 }` and `bands: [...]` for
+     * tooltip access. See the LineChart docs for full ergonomics.
+     */
+    band?: BandConfig<TDatum> | Array<BandConfig<TDatum>>;
     /**
      * Fixed x domain `[min, max]`. Either bound may be `undefined` to leave
      * that side data-derived. Useful for pinning a time axis to a known

package/dist/components/charts/xy/LineChart.d.ts

@@ -1,6 +1,6 @@
 import type { Datum } from "../shared/datumTypes";
 import * as React from "react";
-import type { StreamXYFrameProps } from "../../stream/types";
+import type { StreamXYFrameProps, BandConfig } from "../../stream/types";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
@@ -29,7 +29,7 @@ export interface LineChartProps<TDatum extends Datum = Datum> extends BaseChartP
      * Field name or function to access x values
      * @default "x"
      */
-    xAccessor?: ChartAccessor<TDatum, number>;
+    xAccessor?: ChartAccessor<TDatum, number | Date | string>;
     /**
      * Field name or function to access y values
      * @default "y"
@@ -181,6 +181,30 @@ export interface LineChartProps<TDatum extends Datum = Datum> extends BaseChartP
      * envelope around the extrapolated forecast region.
      */
     forecast?: ForecastConfig;
+    /**
+     * Asymmetric min/max band(s) drawn under the line. Differs from
+     * `forecast`/`anomaly` (computed envelopes around a series) by being
+     * pure data passthrough — provide `y0Accessor` / `y1Accessor` and the
+     * band is drawn between them at each x.
+     *
+     * Pass an array for percentile fans (e.g. p25/p75 on top of p10/p90).
+     * Each band participates in y-extent auto-derivation, so a tall band
+     * can never get clipped. The hovered datum is enriched with
+     * `band: { y0, y1 }` (first band) and `bands: [...]` (all bands) so
+     * tooltip functions can read the envelope without re-running the
+     * accessors.
+     *
+     * @example
+     * ```tsx
+     * <LineChart
+     *   data={[{ time, average, min, max }, ...]}
+     *   xAccessor="time"
+     *   yAccessor="average"
+     *   band={{ y0Accessor: "min", y1Accessor: "max" }}
+     * />
+     * ```
+     */
+    band?: BandConfig<TDatum> | Array<BandConfig<TDatum>>;
     /**
      * Fixed x domain `[min, max]`. Either bound may be `undefined` to leave
      * that side data-derived.