semiotic 3.2.2 → 3.3.0

package/ai/system-prompt.md

@@ -1,6 +1,6 @@
 # Semiotic — React Data Visualization
 
-Use `import { ComponentName } from "semiotic/ai"` for all components below.
+Use sub-path imports: `semiotic/xy` (143KB gz), `semiotic/ordinal` (109KB), `semiotic/network` (98KB), `semiotic/geo` (93KB), `semiotic/realtime` (145KB). Or `semiotic/ai` for all 38 HOCs in one import (269KB).
 
 ## Flat Array Data (`data: object[]`)
 - **LineChart** — `xAccessor`, `yAccessor`, `lineBy` (multi-line), `curve`
@@ -58,7 +58,7 @@ const chartRef = useRef()
 chartRef.current.push({ x: 1, y: 2 })
 <Scatterplot ref={chartRef} xAccessor="x" yAccessor="y" />
 ```
-Methods: `push(datum)`, `pushMany(data)`, `clear()`, `getData()`. Streaming-specific props (`windowSize`, `decay`, `pulse`) go in `frameProps`. Supported: XY charts, ordinal charts, network charts (ForceDirectedGraph, SankeyDiagram, ChordDiagram), ProportionalSymbolMap, DistanceCartogram. Not supported: hierarchy charts (TreeDiagram, Treemap, CirclePack, OrbitDiagram), ChoroplethMap, FlowMap, ScatterplotMatrix.
+Methods: `push(datum)`, `pushMany(data)`, `remove(id)` (requires `pointIdAccessor`/`dataIdAccessor`), `update(id, updater)`, `clear()`, `getData()`. Network HOC refs use `remove()`/`update()` for node operations. Edge-level methods (`removeNode`, `removeEdge`, `updateNode`, `updateEdge`) are on `StreamNetworkFrameHandle`. Geo charts: `update()` is implemented as remove+push internally. Streaming-specific props (`windowSize`, `decay`, `pulse`) go in `frameProps`. Supported: XY charts, ordinal charts, network charts (ForceDirectedGraph, SankeyDiagram, ChordDiagram), ProportionalSymbolMap, DistanceCartogram. Not supported: hierarchy charts (TreeDiagram, Treemap, CirclePack, OrbitDiagram), ChoroplethMap, FlowMap, ScatterplotMatrix.
 
 For advanced streaming control, use Stream Frames (`StreamXYFrame`, `StreamOrdinalFrame`, `StreamNetworkFrame`) with `runtimeMode="streaming"` and ref-based push.
 
@@ -113,5 +113,5 @@ Or use ThemeProvider with 15 named presets: `<ThemeProvider theme="tufte">`, `"t
 
 ## Key Patterns
 - **Percentile band + main line**: Layer `<AreaChart yAccessor="p95" y0Accessor="p5" showLine={false} />` + `<LineChart yAccessor="p50" />`. AreaChart's `showLine` only draws the top edge, NOT a separate main line.
-- **SSR**: `renderToStaticSVG("ordinal", props)` or `renderOrdinalToStaticSVG(props)` from `semiotic/server`. Frame type is `"xy"` | `"ordinal"` | `"network"` (NOT component name).
+- **SSR**: `renderChart("BarChart", props)` from `semiotic/server` — uses HOC names. Also `"Sparkline"` (no axes, 2px margins). `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 `thresholds`.
 - **exportChart**: Pass the wrapper div, not the SVG element: `exportChart(wrapperDiv, { format: "png" })`. It finds canvas+SVG internally.

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

@@ -134,12 +134,17 @@ export declare function MultiLineTooltip(config?: MultiLineTooltipConfig): (data
 /**
  * Type for tooltip prop that chart components accept
  */
-export type TooltipProp = boolean | ((data: Record<string, unknown>) => React.ReactNode) | ReturnType<typeof Tooltip> | ReturnType<typeof MultiLineTooltip> | TooltipConfig;
+export type TooltipProp = boolean | "multi" | ((data: Record<string, unknown>) => React.ReactNode) | ReturnType<typeof Tooltip> | ReturnType<typeof MultiLineTooltip> | TooltipConfig;
 /**
  * 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;
+/**
+ * Multi-point tooltip: shows all series values at the hovered X position
+ * with color swatches (legend-style). Used when tooltipMode="multi".
+ */
+export declare function MultiPointTooltip(): TooltipContentFn;
 /**
  * Convert a tooltip prop to the format Semiotic expects.
  * Returns `false` to disable, or a `TooltipContentFn` compatible with

package/dist/components/charts/index.d.ts

@@ -52,6 +52,8 @@ export { PieChart } from "./ordinal/PieChart";
 export type { PieChartProps } from "./ordinal/PieChart";
 export { DonutChart } from "./ordinal/DonutChart";
 export type { DonutChartProps } from "./ordinal/DonutChart";
+export { GaugeChart } from "./ordinal/GaugeChart";
+export type { GaugeChartProps, GaugeThreshold } from "./ordinal/GaugeChart";
 export { GroupedBarChart } from "./ordinal/GroupedBarChart";
 export type { GroupedBarChartProps } from "./ordinal/GroupedBarChart";
 export { SwimlaneChart } from "./ordinal/SwimlaneChart";

package/dist/components/charts/ordinal/BarChart.d.ts

@@ -19,6 +19,8 @@ export interface BarChartProps<TDatum extends Record<string, any> = Record<strin
     colorScheme?: string | string[];
     sort?: boolean | "asc" | "desc" | ((a: Record<string, any>, b: Record<string, any>) => number);
     barPadding?: number;
+    /** When true, adds padding below the 0 baseline. Default false (bars flush with axis). */
+    baselinePadding?: boolean;
     enableHover?: boolean;
     showGrid?: boolean;
     showCategoryTicks?: boolean;

package/dist/components/charts/ordinal/GaugeChart.d.ts

@@ -0,0 +1,55 @@
+import * as React from "react";
+import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
+import type { BaseChartProps } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+export interface GaugeThreshold {
+    /** Upper bound of this zone (value, not percentage) */
+    value: number;
+    /** Color for this threshold zone */
+    color: string;
+    /** Optional label for the zone */
+    label?: string;
+}
+export interface GaugeChartProps extends BaseChartProps {
+    /** Current gauge value */
+    value: number;
+    /** Minimum scale value (default 0) */
+    min?: number;
+    /** Maximum scale value (default 100) */
+    max?: number;
+    /** Threshold zones — ordered list of { value, color, label? }. Last threshold's value should equal max. */
+    thresholds?: GaugeThreshold[];
+    /** Color of the value arc when no thresholds defined (default: theme primary) */
+    color?: string;
+    /** Background arc color (default: var(--semiotic-grid, #e0e0e0)) */
+    backgroundColor?: string;
+    /** Arc thickness as fraction of radius (0–1, default 0.3) */
+    arcWidth?: number;
+    /** Show needle indicator (default true) */
+    showNeedle?: boolean;
+    /** Needle color (default: var(--semiotic-text, #333)) */
+    needleColor?: string;
+    /** Center content — ReactNode rendered at the gauge center. If not provided, shows the value. */
+    centerContent?: React.ReactNode | ((value: number, min: number, max: number) => React.ReactNode);
+    /** Format function for the default center value label */
+    valueFormat?: (value: number) => string;
+    /** Show scale tick labels at min, max, and threshold boundaries (default true) */
+    showScaleLabels?: boolean;
+    /** Arc sweep angle in degrees (default 240 — leaves a 120° gap at the bottom) */
+    sweep?: number;
+    /** When false, all threshold zones render at full color and only the needle indicates value. Default true (zones fill up to value). */
+    fillZones?: boolean;
+    /** Enable tooltip on arc segments */
+    tooltip?: TooltipProp;
+    /** Annotations — supports threshold markers via standard annotation system */
+    annotations?: Record<string, any>[];
+    /** Enable hover interaction (default true) */
+    enableHover?: boolean;
+    /** frameProps escape hatch */
+    frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
+}
+export declare const GaugeChart: {
+    (props: GaugeChartProps & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/components/charts/ordinal/GroupedBarChart.d.ts

@@ -16,6 +16,7 @@ export interface GroupedBarChartProps<TDatum extends Record<string, any> = Recor
     colorBy?: ChartAccessor<TDatum, string>;
     colorScheme?: string | string[];
     barPadding?: number;
+    baselinePadding?: boolean;
     enableHover?: boolean;
     showGrid?: boolean;
     showCategoryTicks?: boolean;

package/dist/components/charts/ordinal/StackedBarChart.d.ts

@@ -17,6 +17,7 @@ export interface StackedBarChartProps<TDatum extends Record<string, any> = Recor
     colorScheme?: string | string[];
     normalize?: boolean;
     barPadding?: number;
+    baselinePadding?: boolean;
     enableHover?: boolean;
     showGrid?: boolean;
     showCategoryTicks?: boolean;

package/dist/components/charts/ordinal/SwimlaneChart.d.ts

@@ -56,6 +56,10 @@ export interface SwimlaneChartProps<TDatum extends Record<string, any> = Record<
     };
     /** Custom formatter for category tick labels */
     categoryFormat?: CategoryFormatFn;
+    /** Custom tick values for the value axis. Forces specific values instead of d3 auto-ticks. */
+    rTickValues?: number[];
+    /** Align first value tick label to start, last to end. Prevents clipping at chart edges. */
+    tickLabelEdgeAlign?: boolean;
     /** Pass-through props to StreamOrdinalFrame */
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }

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

@@ -96,6 +96,8 @@ export interface RealtimeHeatmapProps<TDatum extends Record<string, any> = Recor
     legendPosition?: LegendPosition;
     /** Legend interaction mode */
     legendInteraction?: LegendInteractionMode;
+    /** ID accessor for remove()/update() on the push API */
+    pointIdAccessor?: string | ((d: any) => string);
 }
 /**
  * RealtimeHeatmap - Streaming heatmap with 2D grid binning.

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

@@ -130,6 +130,8 @@ export interface RealtimeTemporalHistogramProps<TDatum extends Record<string, an
     legendPosition?: LegendPosition;
     /** Legend interaction mode */
     legendInteraction?: LegendInteractionMode;
+    /** ID accessor for remove()/update() on the push API */
+    pointIdAccessor?: string | ((d: any) => string);
 }
 /**
  * RealtimeTemporalHistogram - Streaming temporal histogram.

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

@@ -96,6 +96,8 @@ export interface RealtimeLineChartProps<TDatum extends Record<string, any> = Rec
     legendPosition?: LegendPosition;
     /** Legend interaction mode */
     legendInteraction?: LegendInteractionMode;
+    /** ID accessor for remove()/update() on the push API */
+    pointIdAccessor?: string | ((d: any) => string);
 }
 /**
  * RealtimeLineChart - Simplified wrapper for streaming line charts.

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

@@ -96,6 +96,8 @@ export interface RealtimeSwarmChartProps<TDatum extends Record<string, any> = Re
     legendPosition?: LegendPosition;
     /** Legend interaction mode */
     legendInteraction?: LegendInteractionMode;
+    /** ID accessor for remove()/update() on the push API */
+    pointIdAccessor?: string | ((d: any) => string);
 }
 /**
  * RealtimeSwarmChart - Simplified wrapper for streaming dot/swarm charts.

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

@@ -96,6 +96,8 @@ export interface RealtimeWaterfallChartProps<TDatum extends Record<string, any>
     legendPosition?: LegendPosition;
     /** Legend interaction mode */
     legendInteraction?: LegendInteractionMode;
+    /** ID accessor for remove()/update() on the push API */
+    pointIdAccessor?: string | ((d: any) => string);
 }
 /**
  * RealtimeWaterfallChart - Simplified wrapper for streaming waterfall charts.

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

@@ -43,7 +43,7 @@ export declare function useSortedData(data: Array<Record<string, any>>, sort: bo
  * @param unwrapData - Deprecated / no-op. Hover data is always unwrapped
  *   (stream frames wrap the raw datum in { data, time, value, x, y }).
  */
-export declare function useChartSelection({ selection, linkedHover, fallbackFields, unwrapData, onObservation, chartType, chartId, onClick, }: {
+export declare function useChartSelection({ selection, linkedHover, fallbackFields, unwrapData, onObservation, chartType, chartId, onClick, hoverHighlight, colorByField, }: {
     selection?: SelectionConfig;
     linkedHover?: LinkedHoverProp;
     fallbackFields?: string[];
@@ -55,8 +55,11 @@ export declare function useChartSelection({ selection, linkedHover, fallbackFiel
         x: number;
         y: number;
     }) => void;
+    hoverHighlight?: boolean;
+    colorByField?: string;
 }): {
     activeSelectionHook: SelectionHookResult | null;
+    hoverSelectionHook: SelectionHookResult | null;
     customHoverBehavior: (d: Record<string, any> | null) => void;
     customClickBehavior: (d: Record<string, any> | null) => void;
     /** Stable ID for this chart instance, used to suppress linked crosshair on source chart */
@@ -125,6 +128,7 @@ export declare function useLegendInteraction(mode: LegendInteractionMode | undef
 interface ChartModeInput {
     width?: number;
     height?: number;
+    showAxes?: boolean;
     showGrid?: boolean;
     enableHover?: boolean;
     showLegend?: boolean;

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

@@ -1,3 +1,4 @@
+import type React from "react";
 import type { MarginType } from "../../types/generalTypes";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 /**
@@ -92,6 +93,14 @@ export interface BaseChartProps {
         x: number;
         y: number;
     }) => void;
+    /** Dim non-hovered series when hovering a data mark. Requires `colorBy`. */
+    hoverHighlight?: boolean;
+    /** Max pixel distance for hover/click hit testing. Default 30. Increase for sparse charts, decrease for dense ones. */
+    hoverRadius?: number;
+    /** ID accessor for remove()/update() on XY charts. Extracts a unique identifier from each datum. */
+    pointIdAccessor?: string | ((d: any) => string);
+    /** ID accessor for remove()/update() on ordinal charts. Extracts a unique identifier from each datum. */
+    dataIdAccessor?: string | ((d: any) => string);
     /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */
     emphasis?: "primary" | "secondary";
     /** Enable declarative bounded animation (enter/exit/update transitions).
@@ -109,16 +118,16 @@ export interface AxisConfig {
     xLabel?: string;
     /** Label for the y-axis */
     yLabel?: string;
-    /** Format function for x-axis tick labels */
-    xFormat?: (d: any, index?: number, allTicks?: number[]) => string;
-    /** Format function for y-axis tick labels */
-    yFormat?: (d: any) => string;
+    /** Format function for x-axis tick labels. Return string or ReactNode for custom rendering. */
+    xFormat?: (d: any, index?: number, allTicks?: number[]) => string | React.ReactNode;
+    /** Format function for y-axis tick labels. Return string or ReactNode for custom rendering. */
+    yFormat?: (d: any) => string | React.ReactNode;
 }
 /**
  * Category formatting for ordinal chart tick labels.
  * Receives the category value and its index, returns a formatted string.
  */
-export type CategoryFormatFn = (label: string, index?: number) => string;
+export type CategoryFormatFn = (label: string, index?: number) => string | React.ReactNode;
 /**
  * Accessor type - can be a property name or a function
  * @deprecated Use DataAccessor from generalTypes for generic type safety

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

@@ -55,6 +55,8 @@ export interface ChartSetupInput {
         x: number;
         y: number;
     }) => void;
+    /** Dim non-hovered series on data mark hover */
+    hoverHighlight?: boolean;
     /** Loading state */
     loading: boolean | undefined;
     /** Empty content override */

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

@@ -74,19 +74,34 @@ export interface AreaChartProps<TDatum extends Record<string, any> = Record<stri
      */
     y0Accessor?: ChartAccessor<TDatum, number>;
     /**
-     * Gradient fill from line to baseline. Set `true` for default (80% → 5%)
-     * or `{ topOpacity, bottomOpacity }` for custom values.
+     * Gradient fill from line to baseline. Set `true` for default opacity (80% → 5%),
+     * `{ topOpacity, bottomOpacity }` for custom opacity, or
+     * `{ colorStops: [{offset, color}] }` for multi-color gradients.
      * @default false
      */
     gradientFill?: boolean | {
         topOpacity: number;
         bottomOpacity: number;
+    } | {
+        colorStops: Array<{
+            offset: number;
+            color: string;
+        }>;
     };
     /**
      * Area opacity (flat fill, ignored when gradientFill is set)
      * @default 0.7
      */
     areaOpacity?: number;
+    /**
+     * Horizontal gradient for the line stroke. Color stops define a left-to-right gradient.
+     */
+    lineGradient?: {
+        colorStops: Array<{
+            offset: number;
+            color: string;
+        }>;
+    };
     /**
      * Show line on top of area
      * @default true

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

@@ -38,7 +38,7 @@ export interface LineChartProps<TDatum extends Record<string, any> = Record<stri
      * Scale type for the x-axis
      * @default "linear"
      */
-    xScaleType?: "linear" | "log";
+    xScaleType?: "linear" | "log" | "time";
     /**
      * Scale type for the y-axis
      * @default "linear"
@@ -89,15 +89,26 @@ export interface LineChartProps<TDatum extends Record<string, any> = Record<stri
      */
     pointRadius?: number;
     /**
-     * Fill area under the line
+     * Fill area under the line. `true` fills all series, `string[]` lists series
+     * names (matching lineBy/colorBy group key) that get area fill while others stay as lines.
      * @default false
      */
-    fillArea?: boolean;
+    fillArea?: boolean | string[];
     /**
      * Area opacity when fillArea is true
      * @default 0.3
      */
     areaOpacity?: number;
+    /**
+     * Horizontal gradient for the line stroke. Color stops define a left-to-right gradient.
+     * `{ colorStops: [{ offset: 0, color: "blue" }, { offset: 1, color: "red" }] }`
+     */
+    lineGradient?: {
+        colorStops: Array<{
+            offset: number;
+            color: string;
+        }>;
+    };
     /**
      * Line stroke width
      * @default 2

package/dist/components/realtime/RingBuffer.d.ts

@@ -13,6 +13,17 @@ export declare class RingBuffer<T> {
     forEach(callback: (value: T, index: number) => void): void;
     toArray(): T[];
     resize(newCapacity: number): T[];
+    /**
+     * Update items in place. The updater receives each matching item and returns
+     * the replacement. Returns the previous values of updated items.
+     * O(n) scan, no compaction needed — buffer positions stay stable.
+     */
+    update(predicate: (item: T) => boolean, updater: (item: T) => T): T[];
+    /**
+     * Remove items matching a predicate. Returns removed items.
+     * O(n) scan + compaction. Size decreases; capacity stays the same.
+     */
+    remove(predicate: (item: T) => boolean): T[];
     clear(): void;
     get size(): number;
     get capacity(): number;

package/dist/components/realtime/types.d.ts

@@ -131,6 +131,10 @@ export interface RealtimeFrameProps {
 export interface RealtimeFrameHandle {
     push(point: Record<string, any>): void;
     pushMany(points: Record<string, any>[]): void;
+    /** Remove data by ID. Requires an ID accessor (pointIdAccessor or dataIdAccessor). */
+    remove(id: string | string[]): Record<string, any>[];
+    /** Update data by ID in place. Requires an ID accessor. Returns previous values. */
+    update(id: string | string[], updater: (d: Record<string, any>) => Record<string, any>): Record<string, any>[];
     clear(): void;
     getData(): Record<string, any>[];
 }

package/dist/components/semiotic-ordinal.d.ts

@@ -15,6 +15,8 @@ export { ViolinPlot } from "./charts/ordinal/ViolinPlot";
 export { DotPlot } from "./charts/ordinal/DotPlot";
 export { PieChart } from "./charts/ordinal/PieChart";
 export { DonutChart } from "./charts/ordinal/DonutChart";
+export { GaugeChart } from "./charts/ordinal/GaugeChart";
+export type { GaugeChartProps, GaugeThreshold } from "./charts/ordinal/GaugeChart";
 export { RidgelinePlot } from "./charts/ordinal/RidgelinePlot";
 export { FunnelChart } from "./charts/ordinal/FunnelChart";
 export { LikertChart } from "./charts/ordinal/LikertChart";

package/dist/components/semiotic-server.d.ts

@@ -1 +1,6 @@
-export { renderToStaticSVG, renderXYToStaticSVG, renderOrdinalToStaticSVG, renderNetworkToStaticSVG, renderGeoToStaticSVG } from "./server/renderToStaticSVG";
+export { renderToStaticSVG, renderXYToStaticSVG, renderOrdinalToStaticSVG, renderNetworkToStaticSVG, renderGeoToStaticSVG, renderChart, renderToImage, renderDashboard, } from "./server/renderToStaticSVG";
+export type { RenderToImageOptions, DashboardChart, DashboardLayout, RenderDashboardOptions, } from "./server/renderToStaticSVG";
+export { renderToAnimatedGif, generateFrameSVGs, generateFrameSequence } from "./server/animatedGif";
+export type { AnimatedGifOptions } from "./server/animatedGif";
+export { resolveTheme, themeStyles } from "./server/themeResolver";
+export type { ThemeInput } from "./server/themeResolver";

package/dist/components/semiotic-utils.d.ts

@@ -17,6 +17,7 @@ export { createHatchPattern } from "./charts/shared/hatchPattern";
 export type { HatchPatternOptions } from "./charts/shared/hatchPattern";
 export { validateProps } from "./charts/shared/validateProps";
 export { diagnoseConfig } from "./charts/shared/diagnoseConfig";
+export { getHitRadius } from "./stream/hitTestUtils";
 export { toConfig, fromConfig, toURL, fromURL, copyConfig, configToJSX } from "./export/chartConfig";
 export type { ChartConfig, ToConfigOptions, CopyFormat } from "./export/chartConfig";
 export { serializeSelections, deserializeSelections } from "./export/selectionSerializer";
@@ -26,5 +27,5 @@ export { fromVegaLite } from "./data/fromVegaLite";
 export type { VegaLiteSpec, VegaLiteEncoding } from "./data/fromVegaLite";
 export { RingBuffer } from "./realtime/RingBuffer";
 export { IncrementalExtent } from "./realtime/IncrementalExtent";
-export { normalizeTooltip } from "./Tooltip/Tooltip";
+export { normalizeTooltip, MultiPointTooltip } from "./Tooltip/Tooltip";
 export { useReducedMotion, useHighContrast } from "./stream/useMediaPreferences";

package/dist/components/semiotic.d.ts

@@ -1,7 +1,7 @@
 import StreamXYFrame from "./stream/StreamXYFrame";
 import StreamOrdinalFrame from "./stream/StreamOrdinalFrame";
 import StreamNetworkFrame from "./stream/StreamNetworkFrame";
-import { Scatterplot, ConnectedScatterplot, LineChart, AreaChart, StackedAreaChart, Heatmap, BubbleChart, BarChart, StackedBarChart, LikertChart, SwarmPlot, BoxPlot, Histogram, ViolinPlot, RidgelinePlot, DotPlot, PieChart, DonutChart, GroupedBarChart, FunnelChart, SwimlaneChart, ForceDirectedGraph, ChordDiagram, SankeyDiagram, TreeDiagram, Treemap, CirclePack, OrbitDiagram, ScatterplotMatrix, MinimapChart, QuadrantChart, MultiAxisLineChart } from "./charts";
+import { Scatterplot, ConnectedScatterplot, LineChart, AreaChart, StackedAreaChart, Heatmap, BubbleChart, BarChart, StackedBarChart, LikertChart, SwarmPlot, BoxPlot, Histogram, ViolinPlot, RidgelinePlot, DotPlot, PieChart, DonutChart, GaugeChart, GroupedBarChart, FunnelChart, SwimlaneChart, ForceDirectedGraph, ChordDiagram, SankeyDiagram, TreeDiagram, Treemap, CirclePack, OrbitDiagram, ScatterplotMatrix, MinimapChart, QuadrantChart, MultiAxisLineChart } from "./charts";
 import { LinkedCharts } from "./LinkedCharts";
 import { ThemeProvider, useTheme } from "./ThemeProvider";
 import { exportChart } from "./export/exportChart";
@@ -23,8 +23,8 @@ import { RealtimeTemporalHistogram, RealtimeHistogram } from "./charts/realtime/
 import { RealtimeSwarmChart } from "./charts/realtime/RealtimeSwarmChart";
 import { RealtimeWaterfallChart } from "./charts/realtime/RealtimeWaterfallChart";
 import { RealtimeHeatmap } from "./charts/realtime/RealtimeHeatmap";
-export { StreamXYFrame, StreamOrdinalFrame, StreamNetworkFrame, Scatterplot, ConnectedScatterplot, LineChart, AreaChart, StackedAreaChart, Heatmap, BubbleChart, BarChart, StackedBarChart, LikertChart, SwarmPlot, BoxPlot, Histogram, ViolinPlot, RidgelinePlot, DotPlot, ForceDirectedGraph, ChordDiagram, SankeyDiagram, TreeDiagram, PieChart, DonutChart, FunnelChart, GroupedBarChart, SwimlaneChart, Treemap, CirclePack, OrbitDiagram, ScatterplotMatrix, MinimapChart, QuadrantChart, MultiAxisLineChart, LinkedCharts, ThemeProvider, useTheme, exportChart, toConfig, fromConfig, toURL, fromURL, copyConfig, configToJSX, serializeSelections, deserializeSelections, fromVegaLite, ChartErrorBoundary, ChartContainer, ChartGrid, CategoryColorProvider, useCategoryColors, ContextLayout, DetailsPanel, Tooltip, MultiLineTooltip, normalizeTooltip, RingBuffer, IncrementalExtent, RealtimeLineChart, RealtimeTemporalHistogram, RealtimeHistogram, RealtimeSwarmChart, RealtimeWaterfallChart, RealtimeHeatmap, createHatchPattern };
-export { ScatterplotProps, ConnectedScatterplotProps, LineChartProps, AreaChartProps, StackedAreaChartProps, HeatmapProps, BubbleChartProps, BarChartProps, StackedBarChartProps, LikertChartProps, SwarmPlotProps, BoxPlotProps, HistogramProps, ViolinPlotProps, DotPlotProps, PieChartProps, DonutChartProps, FunnelChartProps, GroupedBarChartProps, SwimlaneChartProps, RidgelinePlotProps, OrbitDiagramProps, OrbitNode, ForceDirectedGraphProps, ChordDiagramProps, SankeyDiagramProps, TreeDiagramProps, TreemapProps, CirclePackProps, ScatterplotMatrixProps, MinimapChartProps, MinimapConfig, QuadrantChartProps, MultiAxisLineChartProps, MultiAxisSeriesConfig, QuadrantsConfig, QuadrantConfig, CenterlineStyle, BaseChartProps, AxisConfig, Accessor, ChartAccessor, ChartMode } from "./charts";
+export { StreamXYFrame, StreamOrdinalFrame, StreamNetworkFrame, Scatterplot, ConnectedScatterplot, LineChart, AreaChart, StackedAreaChart, Heatmap, BubbleChart, BarChart, StackedBarChart, LikertChart, SwarmPlot, BoxPlot, Histogram, ViolinPlot, RidgelinePlot, DotPlot, ForceDirectedGraph, ChordDiagram, SankeyDiagram, TreeDiagram, PieChart, DonutChart, GaugeChart, FunnelChart, GroupedBarChart, SwimlaneChart, Treemap, CirclePack, OrbitDiagram, ScatterplotMatrix, MinimapChart, QuadrantChart, MultiAxisLineChart, LinkedCharts, ThemeProvider, useTheme, exportChart, toConfig, fromConfig, toURL, fromURL, copyConfig, configToJSX, serializeSelections, deserializeSelections, fromVegaLite, ChartErrorBoundary, ChartContainer, ChartGrid, CategoryColorProvider, useCategoryColors, ContextLayout, DetailsPanel, Tooltip, MultiLineTooltip, normalizeTooltip, RingBuffer, IncrementalExtent, RealtimeLineChart, RealtimeTemporalHistogram, RealtimeHistogram, RealtimeSwarmChart, RealtimeWaterfallChart, RealtimeHeatmap, createHatchPattern };
+export { ScatterplotProps, ConnectedScatterplotProps, LineChartProps, AreaChartProps, StackedAreaChartProps, HeatmapProps, BubbleChartProps, BarChartProps, StackedBarChartProps, LikertChartProps, SwarmPlotProps, BoxPlotProps, HistogramProps, ViolinPlotProps, DotPlotProps, PieChartProps, DonutChartProps, GaugeChartProps, GaugeThreshold, FunnelChartProps, GroupedBarChartProps, SwimlaneChartProps, RidgelinePlotProps, OrbitDiagramProps, OrbitNode, ForceDirectedGraphProps, ChordDiagramProps, SankeyDiagramProps, TreeDiagramProps, TreemapProps, CirclePackProps, ScatterplotMatrixProps, MinimapChartProps, MinimapConfig, QuadrantChartProps, MultiAxisLineChartProps, MultiAxisSeriesConfig, QuadrantsConfig, QuadrantConfig, CenterlineStyle, BaseChartProps, AxisConfig, Accessor, ChartAccessor, ChartMode } from "./charts";
 export type { StreamXYFrameProps, StreamXYFrameHandle, StreamChartType, RuntimeMode, SceneNode, Changeset, StreamScales, StreamLayout, CurveType, CanvasRendererFn } from "./stream/types";
 export type { StreamRendererFn } from "./stream/renderers/types";
 export type { StreamOrdinalFrameProps, StreamOrdinalFrameHandle, OrdinalChartType, OrdinalScales, OrdinalSceneNode } from "./stream/ordinalTypes";

package/dist/components/server/animatedGif.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Animated GIF generation from semiotic chart data.
+ *
+ * Renders a sequence of chart frames by progressively feeding data into
+ * PipelineStore, optionally applying transition easing and decay effects,
+ * then encoding all frames as an animated GIF.
+ *
+ * Phases:
+ *   1. Sliding window — slice data into progressive windows, render each
+ *   2. Transition easing — interpolate enter/update between data windows
+ *   3. Decay/pulse — apply age-based opacity fading per frame
+ *
+ * Requires: sharp (SVG→PNG rasterization), gifenc (GIF encoding)
+ * Both are optional dependencies of semiotic.
+ */
+import type { SemioticTheme } from "../store/ThemeStore";
+export interface AnimatedGifOptions {
+    /** Frames per second (default 12) */
+    fps?: number;
+    /** Number of data points to advance per frame (default: auto-calculated) */
+    stepSize?: number;
+    /** Data points visible per frame (default: all data up to current step) */
+    windowSize?: number;
+    /** Total number of frames (default: auto from data length / stepSize) */
+    frameCount?: number;
+    /** Lock X axis domain to prevent shifting (default: auto from full data) */
+    xExtent?: [number, number];
+    /** Lock Y axis domain (default: auto from full data) */
+    yExtent?: [number, number];
+    /** Transition frames between data steps (0 = no easing, default 4). XY charts only — ordinal charts use instant transitions. */
+    transitionFrames?: number;
+    /** Easing for transitions (default "ease-out") */
+    easing?: "linear" | "ease-out";
+    /** Apply decay (age-based fade) to older data points */
+    decay?: {
+        type: "linear" | "exponential" | "step";
+        minOpacity?: number;
+        halfLife?: number;
+    };
+    /** Loop the GIF (default true) */
+    loop?: boolean;
+    /** Scale factor for resolution (default 1) */
+    scale?: number;
+    /** Background color */
+    background?: string;
+}
+export interface AnimatedGifFrameConfig {
+    /** Chart width */
+    width: number;
+    /** Chart height */
+    height: number;
+    /** Theme for styling */
+    theme: SemioticTheme;
+}
+/**
+ * Generate SVG strings for each animation frame.
+ * This is the core logic shared between GIF export and client-side preview.
+ */
+export declare function generateFrameSVGs(chartType: string, data: Record<string, any>[], props: Record<string, any>, options?: AnimatedGifOptions): string[];
+/**
+ * Generate SVG strings from an array of data snapshots.
+ *
+ * Unlike `generateFrameSVGs` which slices a single array progressively,
+ * this accepts pre-built snapshots — each entry is the complete props
+ * for one frame. Use for scenarios where data changes non-monotonically
+ * (edge deletion, network splits, failover paths).
+ *
+ * Each snapshot is passed directly to `renderChart()`.
+ */
+export declare function generateFrameSequence(component: string, snapshots: Record<string, any>[], baseProps?: Record<string, any>): string[];
+/**
+ * Render a chart as an animated GIF.
+ *
+ * Requires `sharp` (SVG→PNG) and `gifenc` (GIF encoding) as optional dependencies.
+ *
+ * @returns Buffer containing the animated GIF
+ */
+export declare function renderToAnimatedGif(chartType: string, data: Record<string, any>[], props: Record<string, any>, options?: AnimatedGifOptions): Promise<Buffer>;

package/dist/components/server/renderToStaticSVG.d.ts

@@ -4,15 +4,95 @@
  * Uses the shared SceneToSVG converters (same code used by Stream Frames
  * for SSR) plus PipelineStore / OrdinalPipelineStore / NetworkPipelineStore
  * for scene graph computation.
+ *
+ * Features:
+ * - Theme inlining (resolve presets to concrete SVG styles)
+ * - Legend rendering (categorical color swatches)
+ * - Accessibility (title, desc, role="img")
+ * - Grid lines
+ * - Annotations (y-threshold, x-threshold, band, label, text, category-highlight)
+ * - renderChart HOC-level API
  */
+import * as React from "react";
 import type { StreamXYFrameProps } from "../stream/types";
 import type { StreamNetworkFrameProps } from "../stream/networkTypes";
 import type { StreamOrdinalFrameProps } from "../stream/ordinalTypes";
 import type { StreamGeoFrameProps } from "../stream/geoTypes";
+import { type ThemeInput } from "./themeResolver";
 type FrameType = "xy" | "ordinal" | "network" | "geo";
-export declare function renderToStaticSVG(frameType: FrameType, props: StreamXYFrameProps | StreamNetworkFrameProps | StreamOrdinalFrameProps | StreamGeoFrameProps): string;
-export declare function renderXYToStaticSVG(props: StreamXYFrameProps): string;
-export declare function renderOrdinalToStaticSVG(props: StreamOrdinalFrameProps): string;
-export declare function renderNetworkToStaticSVG(props: StreamNetworkFrameProps): string;
-export declare function renderGeoToStaticSVG(props: StreamGeoFrameProps): string;
+interface ThemeAwareProps {
+    theme?: ThemeInput;
+    showLegend?: boolean;
+    showGrid?: boolean;
+    annotations?: Record<string, any>[];
+    title?: string | React.ReactNode;
+    description?: string;
+    background?: string;
+    className?: string;
+    /** Prefix for SVG element IDs — used by renderDashboard to avoid collisions */
+    _idPrefix?: string;
+}
+export declare function renderToStaticSVG(frameType: FrameType, props: (StreamXYFrameProps | StreamNetworkFrameProps | StreamOrdinalFrameProps | StreamGeoFrameProps) & ThemeAwareProps): string;
+export declare function renderXYToStaticSVG(props: StreamXYFrameProps & ThemeAwareProps): string;
+export declare function renderOrdinalToStaticSVG(props: StreamOrdinalFrameProps & ThemeAwareProps): string;
+export declare function renderNetworkToStaticSVG(props: StreamNetworkFrameProps & ThemeAwareProps): string;
+export declare function renderGeoToStaticSVG(props: StreamGeoFrameProps & ThemeAwareProps): string;
+/** Chart component name to frame type + props mapping */
+type ChartName = "LineChart" | "AreaChart" | "StackedAreaChart" | "Scatterplot" | "BubbleChart" | "ConnectedScatterplot" | "Heatmap" | "Sparkline" | "BarChart" | "StackedBarChart" | "GroupedBarChart" | "PieChart" | "DonutChart" | "SwimlaneChart" | "Histogram" | "BoxPlot" | "ViolinPlot" | "SwarmPlot" | "DotPlot" | "RidgelinePlot" | "FunnelChart" | "GaugeChart" | "ForceDirectedGraph" | "SankeyDiagram" | "ChordDiagram" | "TreeDiagram" | "Treemap" | "CirclePack" | "ChoroplethMap" | "ProportionalSymbolMap";
+interface RenderChartOptions {
+    /** Output format — currently only "svg" is synchronous */
+    format?: "svg";
+}
+/**
+ * Render a chart using HOC-level props (categoryAccessor, valueAccessor, etc.)
+ * instead of frame-level props (oAccessor, rAccessor, etc.).
+ *
+ * This is the primary API for AI/MCP workflows.
+ */
+export declare function renderChart(component: ChartName, props: Record<string, any>, _options?: RenderChartOptions): string;
+export interface RenderToImageOptions {
+    /** Output format */
+    format?: "png" | "jpeg";
+    /** Scale factor (e.g., 2 for retina) */
+    scale?: number;
+    /** Background color (overrides theme) */
+    background?: string;
+}
+/**
+ * Render a chart to a PNG or JPEG Buffer.
+ *
+ * Requires `sharp` as an optional peer dependency.
+ * Falls back to a descriptive error if sharp is not installed.
+ */
+export declare function renderToImage(frameTypeOrComponent: FrameType | ChartName, props: Record<string, any>, options?: RenderToImageOptions): Promise<Buffer>;
+export interface DashboardChart {
+    /** Frame type or HOC component name */
+    component?: ChartName;
+    frameType?: FrameType;
+    /** Chart props (data, accessors, etc.) */
+    props: Record<string, any>;
+    /** Span multiple columns (for emphasis="primary") */
+    colSpan?: number;
+}
+export interface DashboardLayout {
+    /** Number of columns */
+    columns?: number;
+    /** Gap between charts in pixels */
+    gap?: number;
+}
+export interface RenderDashboardOptions {
+    title?: string;
+    subtitle?: string;
+    theme?: ThemeInput;
+    width?: number;
+    height?: number;
+    layout?: DashboardLayout;
+    background?: string;
+    /** Output format */
+    format?: "svg";
+}
+/**
+ * Compose multiple charts into a single SVG.
+ */
+export declare function renderDashboard(charts: DashboardChart[], options?: RenderDashboardOptions): string;
 export {};