semiotic 3.0.0-beta.3 → 3.0.0-beta.5

package/README.md

@@ -87,10 +87,20 @@ LLM code generation. AI coding assistants can generate correct Semiotic code on
 the first try. Run `npx semiotic-ai --help` for CLI options or add `semiotic-mcp`
 to your MCP client config for tool-based chart rendering.
 
+**Vega-Lite compatible.** Have existing Vega-Lite specs? `fromVegaLite(spec)`
+translates them to Semiotic chart configs — instant onboarding from notebooks,
+dashboards, or AI-generated specs. Composes with `configToJSX()`,
+`copyConfig()`, and `toURL()` for full round-trip interop.
+
+**Streaming system models.** Turn a streaming Sankey into a live system monitor:
+click-to-inspect `DetailsPanel`, particle speed proportional to edge throughput,
+threshold alerting with animated glow, and automatic topology diffing that
+highlights new services as they appear. Visualization as product navigation.
+
 ## Install
 
 ```bash
-npm install semiotic@3.0.0-beta.3
+npm install semiotic@3.0.0-beta.4
 ```
 
 Requires React 18.1 or later.
@@ -154,6 +164,31 @@ import { ForceDirectedGraph, SankeyDiagram } from "semiotic"
 />
 ```
 
+### Streaming System Monitor
+
+Live service topology with threshold alerting and click-to-inspect:
+
+```jsx
+import { StreamNetworkFrame, ChartContainer, DetailsPanel, LinkedCharts } from "semiotic"
+
+const chartRef = useRef()
+chartRef.current.push({ source: "API", target: "Orders", value: 15 })
+
+<LinkedCharts>
+  <ChartContainer title="System Monitor" status="live"
+    detailsPanel={
+      <DetailsPanel position="right" trigger="click">
+        {(datum) => <div>{datum.id}: {datum.value} req/s</div>}
+      </DetailsPanel>
+    }>
+    <StreamNetworkFrame ref={chartRef} chartType="sankey"
+      showParticles particleStyle={{ proportionalSpeed: true }}
+      thresholds={{ metric: n => n.value, warning: 100, critical: 250 }}
+    />
+  </ChartContainer>
+</LinkedCharts>
+```
+
 ### Standard Charts
 
 Line, bar, scatter, area — all the basics, with sensible defaults:
@@ -185,20 +220,53 @@ import { LineChart, BarChart } from "semiotic"
 | **Coordination** | `LinkedCharts` `ScatterplotMatrix` |
 | **Frames** | `StreamXYFrame` `StreamOrdinalFrame` `StreamNetworkFrame` |
 
+### Vega-Lite Translation
+
+Paste a Vega-Lite spec, get a Semiotic chart:
+
+```jsx
+import { fromVegaLite } from "semiotic/data"
+import { configToJSX, fromConfig } from "semiotic"
+
+const config = fromVegaLite({
+  mark: "bar",
+  data: { values: [{ a: "A", b: 28 }, { a: "B", b: 55 }] },
+  encoding: {
+    x: { field: "a", type: "nominal" },
+    y: { field: "b", type: "quantitative" },
+  },
+})
+
+// Render directly
+const { componentName, props } = fromConfig(config)
+// → componentName: "BarChart", props: { data, categoryAccessor: "a", valueAccessor: "b" }
+
+// Or generate JSX code
+configToJSX(config)
+// → <BarChart data={[...]} categoryAccessor="a" valueAccessor="b" />
+```
+
+Supports bar, line, area, point, rect, arc, tick marks with encoding translation
+for color, size, aggregation, and binning.
+
 ## Smaller Bundles
 
 Import only what you need:
 
 ```jsx
-import { LineChart } from "semiotic/xy"        // 125 KB (vs 218 KB full)
-import { BarChart } from "semiotic/ordinal"     // 140 KB
-import { ForceDirectedGraph } from "semiotic/network"  // 133 KB
-import { LineChart } from "semiotic/ai"           // HOC-only surface for AI generation
+import { LineChart } from "semiotic/xy"                 // 123 KB
+import { BarChart } from "semiotic/ordinal"              // 118 KB
+import { ForceDirectedGraph } from "semiotic/network"    // 127 KB
+import { LineChart } from "semiotic/ai"                  // HOC-only surface for AI generation
 ```
 
+Granular entry points export only v3 Stream Frames and HOC charts — no legacy
+utilities or backwards-compatibility shims.
+
 ## TypeScript
 
-Full type definitions ship with the package. Generics for type-safe accessors:
+Built with `strict: true`. Full type definitions ship with the package.
+Generics for type-safe accessors:
 
 ```tsx
 interface Sale { month: number; revenue: number }
@@ -234,7 +302,7 @@ Works with Next.js App Router, Remix, and Astro via `"use client"` directives.
 - [Getting Started](https://semiotic.nteract.io/getting-started)
 - [Charts](https://semiotic.nteract.io/charts) — all 27 chart types with live examples
 - [Frames](https://semiotic.nteract.io/frames) — full Frame API reference
-- [Features](https://semiotic.nteract.io/features) — axes, annotations, tooltips, styling
+- [Features](https://semiotic.nteract.io/features) — axes, annotations, tooltips, styling, Vega-Lite translator
 - [Cookbook](https://semiotic.nteract.io/cookbook) — advanced patterns and recipes
 - [Playground](https://semiotic.nteract.io/playground) — interactive prop exploration
 
@@ -253,6 +321,11 @@ See [CONTRIBUTING.md](CONTRIBUTING.md). Our community follows the nteract
 Development of this library owes a lot to Susie Lu, Jason Reid, James Womack,
 Matt Herman, Shelby Sturgis, and Tristan Reid.
 
+The Sankey layout engine is based on [sankey-plus](https://github.com/tomshanley/sankey-plus)
+by [Tom Shanley](https://github.com/tomshanley), which improved on his earlier
+`d3-sankey-circular` with better cycle detection, hierarchical arc stacking,
+and dynamic extent adjustment.
+
 _Semiotic icon based on an icon by Andre Schauer._
 
 ## License

package/dist/CategoryColors.d.ts

@@ -0,0 +1,48 @@
+import * as React from "react";
+/**
+ * Category→color mapping. Maps category values (like "North", "error", "active")
+ * to fixed color strings. Charts inside a CategoryColorProvider will use these
+ * colors consistently regardless of what subset of categories each chart displays.
+ */
+export type CategoryColorMap = Record<string, string>;
+export interface CategoryColorProviderProps {
+    /** Explicit category→color mapping */
+    colors?: CategoryColorMap;
+    /**
+     * Category values to auto-assign colors from a scheme.
+     * Use when you want consistent colors but don't need specific assignments.
+     */
+    categories?: string[];
+    /** Color scheme to use for auto-assignment. Default: "category10" */
+    colorScheme?: string | string[];
+    children: React.ReactNode;
+}
+/**
+ * CategoryColorProvider — assigns stable colors to category values
+ * shared across all Semiotic charts within its subtree.
+ *
+ * Two modes:
+ * - **Explicit**: pass a `colors` map of category→color
+ * - **Auto**: pass a `categories` array and optional `colorScheme`
+ *
+ * Charts with `colorBy` inside this provider will use the mapped colors
+ * instead of computing their own color scale per-chart.
+ *
+ * ```tsx
+ * <CategoryColorProvider colors={{ North: "#e41a1c", South: "#377eb8", East: "#4daf4a" }}>
+ *   <ChartGrid columns={2}>
+ *     <LineChart data={d1} colorBy="region" responsiveWidth />
+ *     <BarChart data={d2} colorBy="region" responsiveWidth />
+ *   </ChartGrid>
+ * </CategoryColorProvider>
+ * ```
+ */
+export declare function CategoryColorProvider({ colors, categories, colorScheme, children, }: CategoryColorProviderProps): React.JSX.Element;
+export declare namespace CategoryColorProvider {
+    var displayName: string;
+}
+/**
+ * Hook to access the category color map from the nearest provider.
+ * Returns null if no provider is present.
+ */
+export declare function useCategoryColors(): CategoryColorMap | null;

package/dist/ChartContainer.d.ts

@@ -0,0 +1,60 @@
+import * as React from "react";
+import type { ChartConfig, CopyFormat } from "./export/chartConfig";
+export interface ChartContainerProps {
+    /** Chart title */
+    title?: string;
+    /** Subtitle / description */
+    subtitle?: string;
+    /** Chart children (any Semiotic chart component) */
+    children: React.ReactNode;
+    /** Width — passed to child chart if not set on child. Default: "100%" */
+    width?: number | string;
+    /** Height of the chart area (excluding header). Default: 400 */
+    height?: number;
+    /** Built-in actions. Each can be true (default config), false (hidden), or config object */
+    actions?: {
+        export?: boolean | {
+            format?: "svg" | "png";
+            scale?: number;
+            filename?: string;
+        };
+        fullscreen?: boolean;
+        /** Enable "Copy Config" action button. Requires chartConfig prop. */
+        copyConfig?: boolean | {
+            format?: CopyFormat;
+        };
+    };
+    /** Chart configuration for serialization. Enables the "Copy Config" toolbar action. */
+    chartConfig?: ChartConfig;
+    /** Additional controls rendered in the toolbar after built-in actions */
+    controls?: React.ReactNode;
+    /** Loading state — shows skeleton placeholder */
+    loading?: boolean;
+    /** Error state — shows error message (overrides children) */
+    error?: string | React.ReactNode;
+    /** Wrap children in ChartErrorBoundary */
+    errorBoundary?: boolean;
+    /** Status indicator (wired to streaming staleness) */
+    status?: "live" | "stale" | "paused" | "error" | "static";
+    /** Details panel rendered alongside the chart (e.g. DetailsPanel component) */
+    detailsPanel?: React.ReactNode;
+    /** CSS class for the outer container */
+    className?: string;
+    /** Inline style overrides */
+    style?: React.CSSProperties;
+}
+export interface ChartContainerHandle {
+    /** Export chart to SVG or PNG */
+    export: (options?: {
+        format?: "svg" | "png";
+        scale?: number;
+        filename?: string;
+    }) => Promise<void>;
+    /** Toggle fullscreen */
+    toggleFullscreen: () => void;
+    /** Copy chart config to clipboard */
+    copyConfig: (format?: CopyFormat) => Promise<void>;
+    /** The chart container DOM element */
+    element: HTMLDivElement | null;
+}
+export declare const ChartContainer: React.ForwardRefExoticComponent<ChartContainerProps & React.RefAttributes<ChartContainerHandle>>;

package/dist/ChartGrid.d.ts

@@ -0,0 +1,37 @@
+import * as React from "react";
+export interface ChartGridProps {
+    /** Chart components to arrange in the grid */
+    children: React.ReactNode;
+    /** Number of columns. Default: "auto" (auto-fill based on minCellWidth) */
+    columns?: number | "auto";
+    /** Minimum cell width for auto columns. Default: 300 */
+    minCellWidth?: number;
+    /** Gap between cells in pixels. Default: 16 */
+    gap?: number;
+    /** CSS class for the grid container */
+    className?: string;
+    /** Inline style overrides */
+    style?: React.CSSProperties;
+}
+/**
+ * ChartGrid — responsive grid layout for multiple Semiotic charts.
+ *
+ * Arranges child charts in a CSS Grid that reflows based on available space.
+ * Each cell automatically gets `responsiveWidth` behavior since the grid
+ * manages the cell dimensions.
+ *
+ * Works naturally with `LinkedCharts` for coordinated views:
+ *
+ * ```tsx
+ * <LinkedCharts>
+ *   <ChartGrid columns={2}>
+ *     <LineChart data={d} xAccessor="x" yAccessor="y" responsiveWidth />
+ *     <BarChart data={d} categoryAccessor="cat" valueAccessor="val" responsiveWidth />
+ *   </ChartGrid>
+ * </LinkedCharts>
+ * ```
+ */
+export declare function ChartGrid({ children, columns, minCellWidth, gap, className, style, }: ChartGridProps): React.JSX.Element;
+export declare namespace ChartGrid {
+    var displayName: string;
+}

package/dist/ContextLayout.d.ts

@@ -0,0 +1,38 @@
+import * as React from "react";
+export interface ContextLayoutProps {
+    /** The main chart (renders at full size in the primary slot) */
+    children: React.ReactNode;
+    /** Context chart(s) displayed alongside the primary chart */
+    context: React.ReactNode;
+    /** Position of the context panel. Default: "right" */
+    position?: "right" | "left" | "bottom" | "top";
+    /** Size of the context panel in pixels. Default: 250 */
+    contextSize?: number;
+    /** Gap between primary and context panels in pixels. Default: 12 */
+    gap?: number;
+    /** CSS class for the layout container */
+    className?: string;
+    /** Inline style overrides */
+    style?: React.CSSProperties;
+}
+/**
+ * ContextLayout — places a primary chart alongside one or more context charts.
+ *
+ * The primary chart fills available space while the context panel has a fixed
+ * width (or height for top/bottom). Context charts should use `mode="context"`
+ * for compact rendering without axes or labels.
+ *
+ * ```tsx
+ * <ContextLayout
+ *   context={<Treemap data={hierarchy} mode="context" responsiveWidth colorByDepth />}
+ *   position="right"
+ *   contextSize={250}
+ * >
+ *   <LineChart data={timeSeries} xAccessor="time" yAccessor="value" responsiveWidth />
+ * </ContextLayout>
+ * ```
+ */
+export declare function ContextLayout({ children, context, position, contextSize, gap, className, style, }: ContextLayoutProps): React.JSX.Element;
+export declare namespace ContextLayout {
+    var displayName: string;
+}

package/dist/DetailsPanel.d.ts

@@ -0,0 +1,37 @@
+import * as React from "react";
+import type { ChartObservation, ClickObservation } from "./store/ObservationStore";
+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;
+    /** Panel position relative to the chart. Default: "right" */
+    position?: "right" | "bottom" | "overlay";
+    /** Panel width (for "right" position) or height (for "bottom"). Default: 300 */
+    size?: number;
+    /** Observation trigger type. Default: "click" */
+    trigger?: "click" | "hover";
+    /** Filter observations by chart ID */
+    chartId?: string;
+    /**
+     * Direct observation feed — use when the chart pushes observations via
+     * onObservation callback rather than through the ObservationStore.
+     * When set, bypasses useChartObserver and reacts to this prop directly.
+     */
+    observation?: ChartObservation | null;
+    /** Whether clicking empty space dismisses the panel. Default: true */
+    dismissOnEmpty?: boolean;
+    /** Custom close button. Set to false to hide. Default: true */
+    showClose?: boolean;
+    /** Called when the panel opens or closes */
+    onToggle?: (open: boolean) => void;
+    /** CSS class for the panel container */
+    className?: string;
+    /** 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 namespace DetailsPanel {
+    var displayName: string;
+}

package/dist/LinkedCharts.d.ts

@@ -2,6 +2,8 @@ import * as React from "react";
 import type { ResolutionMode } from "./store/SelectionStore";
 export { useSelection, useLinkedHover, useBrushSelection, useFilteredData } from "./store/useSelection";
 export type { UseSelectionOptions, UseSelectionResult, UseLinkedHoverOptions, UseLinkedHoverResult, UseBrushSelectionOptions, UseBrushSelectionResult } from "./store/useSelection";
+export { useChartObserver } from "./store/useObservation";
+export type { UseChartObserverOptions, UseChartObserverResult } from "./store/useObservation";
 export interface LinkedChartsProps {
     children: React.ReactNode;
     /** Pre-configure selections with resolution modes */

package/dist/Tooltip/Tooltip.d.ts

@@ -87,7 +87,7 @@ export declare const defaultTooltipStyle: React.CSSProperties;
  * />
  * ```
  */
-export declare function Tooltip(config?: TooltipConfig): (data: Record<string, unknown>) => React.JSX.Element;
+export declare function Tooltip(config?: TooltipConfig): (data: Record<string, unknown>) => React.JSX.Element | null;
 /**
  * Create a multi-line tooltip that displays multiple fields
  *
@@ -130,7 +130,7 @@ export declare function Tooltip(config?: TooltipConfig): (data: Record<string, u
  * />
  * ```
  */
-export declare function MultiLineTooltip(config?: MultiLineTooltipConfig): (data: Record<string, unknown>) => React.JSX.Element;
+export declare function MultiLineTooltip(config?: MultiLineTooltipConfig): (data: Record<string, unknown>) => React.JSX.Element | null;
 /**
  * Type for tooltip prop that chart components accept
  */

package/dist/charts/index.d.ts

@@ -66,7 +66,7 @@ export { RealtimeWaterfallChart } from "./realtime/RealtimeWaterfallChart";
 export type { RealtimeWaterfallChartProps } from "./realtime/RealtimeWaterfallChart";
 export { RealtimeHeatmap } from "./realtime/RealtimeHeatmap";
 export type { RealtimeHeatmapProps } from "./realtime/RealtimeHeatmap";
-export type { BaseChartProps, AxisConfig, Accessor, ChartAccessor } from "./shared/types";
+export type { BaseChartProps, AxisConfig, Accessor, ChartAccessor, ChartMode } from "./shared/types";
 export { useColorScale, useSortedData, DEFAULT_COLOR } from "./shared/hooks";
 export { COLOR_SCHEMES, DEFAULT_COLORS, getColor, createColorScale, getSize } from "./shared/colorUtils";
 export { formatNumber, formatDate, formatAxis, createTooltip, formatLargeNumber, truncateText } from "./shared/formatUtils";

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

@@ -21,6 +21,7 @@ export interface BarChartProps<TDatum extends Record<string, any> = Record<strin
     showGrid?: boolean;
     showLegend?: boolean;
     tooltip?: TooltipProp;
+    annotations?: Record<string, any>[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 /**

package/dist/charts/ordinal/BoxPlot.d.ts

@@ -19,6 +19,7 @@ export interface BoxPlotProps<TDatum extends Record<string, any> = Record<string
     showGrid?: boolean;
     showLegend?: boolean;
     tooltip?: TooltipProp;
+    annotations?: Record<string, any>[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 export declare function BoxPlot<TDatum extends Record<string, any> = Record<string, any>>(props: BoxPlotProps<TDatum>): React.JSX.Element;

package/dist/charts/ordinal/DonutChart.d.ts

@@ -15,6 +15,7 @@ export interface DonutChartProps<TDatum extends Record<string, any> = Record<str
     enableHover?: boolean;
     showLegend?: boolean;
     tooltip?: TooltipProp;
+    annotations?: Record<string, any>[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 export declare function DonutChart<TDatum extends Record<string, any> = Record<string, any>>(props: DonutChartProps<TDatum>): React.JSX.Element;

package/dist/charts/ordinal/DotPlot.d.ts

@@ -19,6 +19,7 @@ export interface DotPlotProps<TDatum extends Record<string, any> = Record<string
     showGrid?: boolean;
     showLegend?: boolean;
     tooltip?: TooltipProp;
+    annotations?: Record<string, any>[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 export declare function DotPlot<TDatum extends Record<string, any> = Record<string, any>>(props: DotPlotProps<TDatum>): React.JSX.Element;

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

@@ -18,6 +18,7 @@ export interface GroupedBarChartProps<TDatum extends Record<string, any> = Recor
     showGrid?: boolean;
     showLegend?: boolean;
     tooltip?: TooltipProp;
+    annotations?: Record<string, any>[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 export declare function GroupedBarChart<TDatum extends Record<string, any> = Record<string, any>>(props: GroupedBarChartProps<TDatum>): React.JSX.Element;

package/dist/charts/ordinal/Histogram.d.ts

@@ -18,6 +18,7 @@ export interface HistogramProps<TDatum extends Record<string, any> = Record<stri
     showGrid?: boolean;
     showLegend?: boolean;
     tooltip?: TooltipProp;
+    annotations?: Record<string, any>[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 export declare function Histogram<TDatum extends Record<string, any> = Record<string, any>>(props: HistogramProps<TDatum>): React.JSX.Element;

package/dist/charts/ordinal/PieChart.d.ts

@@ -13,6 +13,7 @@ export interface PieChartProps<TDatum extends Record<string, any> = Record<strin
     enableHover?: boolean;
     showLegend?: boolean;
     tooltip?: TooltipProp;
+    annotations?: Record<string, any>[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 export declare function PieChart<TDatum extends Record<string, any> = Record<string, any>>(props: PieChartProps<TDatum>): React.JSX.Element;

package/dist/charts/ordinal/RidgelinePlot.d.ts

@@ -20,6 +20,7 @@ export interface RidgelinePlotProps<TDatum extends Record<string, any> = Record<
     showGrid?: boolean;
     showLegend?: boolean;
     tooltip?: TooltipProp;
+    annotations?: Record<string, any>[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 /**

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

@@ -19,6 +19,7 @@ export interface StackedBarChartProps<TDatum extends Record<string, any> = Recor
     showGrid?: boolean;
     showLegend?: boolean;
     tooltip?: TooltipProp;
+    annotations?: Record<string, any>[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 export declare function StackedBarChart<TDatum extends Record<string, any> = Record<string, any>>(props: StackedBarChartProps<TDatum>): React.JSX.Element;

package/dist/charts/ordinal/SwarmPlot.d.ts

@@ -21,6 +21,7 @@ export interface SwarmPlotProps<TDatum extends Record<string, any> = Record<stri
     showGrid?: boolean;
     showLegend?: boolean;
     tooltip?: TooltipProp;
+    annotations?: Record<string, any>[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 export declare function SwarmPlot<TDatum extends Record<string, any> = Record<string, any>>(props: SwarmPlotProps<TDatum>): React.JSX.Element;

package/dist/charts/ordinal/ViolinPlot.d.ts

@@ -20,6 +20,7 @@ export interface ViolinPlotProps<TDatum extends Record<string, any> = Record<str
     showGrid?: boolean;
     showLegend?: boolean;
     tooltip?: TooltipProp;
+    annotations?: Record<string, any>[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 export declare function ViolinPlot<TDatum extends Record<string, any> = Record<string, any>>(props: ViolinPlotProps<TDatum>): React.JSX.Element;

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

@@ -2,7 +2,11 @@ import * as React from "react";
 import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext, DecayConfig, PulseConfig, StalenessConfig } from "../../stream/types";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
+import type { ChartMode } from "../shared/types";
+import type { OnObservationCallback } from "../../store/ObservationStore";
 export interface RealtimeHeatmapProps {
+    /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
+    mode?: ChartMode;
     /** Chart dimensions as [width, height] */
     size?: [number, number];
     /** Chart width (alternative to size) */
@@ -18,6 +22,8 @@ export interface RealtimeHeatmapProps {
     };
     /** CSS class name */
     className?: string;
+    onObservation?: OnObservationCallback;
+    chartId?: string;
     /** Direction time flows */
     arrowOfTime?: ArrowOfTime;
     /** Data retention strategy */
@@ -70,6 +76,11 @@ export interface RealtimeHeatmapProps {
     staleness?: StalenessConfig;
     /** Custom tooltip renderer (alias for tooltipContent) */
     tooltip?: (d: HoverData) => ReactNode;
+    /** Enable linked hover selection events for cross-chart highlighting */
+    linkedHover?: boolean | string | {
+        name?: string;
+        fields: string[];
+    };
 }
 /**
  * RealtimeHeatmap - Streaming heatmap with 2D grid binning.

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

@@ -1,8 +1,12 @@
 import * as React from "react";
-import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext } from "../../stream/types";
+import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext, DecayConfig, PulseConfig, StalenessConfig, TransitionConfig } from "../../stream/types";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
+import type { ChartMode } from "../shared/types";
+import type { OnObservationCallback } from "../../store/ObservationStore";
 export interface RealtimeTemporalHistogramProps {
+    /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
+    mode?: ChartMode;
     /** Time interval for binning */
     binSize: number;
     /** Chart dimensions as [width, height] */
@@ -20,6 +24,8 @@ export interface RealtimeTemporalHistogramProps {
     };
     /** CSS class name */
     className?: string;
+    onObservation?: OnObservationCallback;
+    chartId?: string;
     /** Direction time flows */
     arrowOfTime?: ArrowOfTime;
     /** Data retention strategy */
@@ -81,6 +87,14 @@ export interface RealtimeTemporalHistogramProps {
         name?: string;
         fields: string[];
     };
+    /** Configurable opacity decay for older data */
+    decay?: DecayConfig;
+    /** Flash effect on newly inserted data */
+    pulse?: PulseConfig;
+    /** Frame-level data liveness indicator */
+    staleness?: StalenessConfig;
+    /** Smooth position interpolation on data change */
+    transition?: TransitionConfig;
 }
 /**
  * RealtimeTemporalHistogram - Streaming temporal histogram.

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

@@ -2,7 +2,11 @@ import * as React from "react";
 import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext, DecayConfig, PulseConfig, StalenessConfig, TransitionConfig } from "../../stream/types";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
+import type { ChartMode } from "../shared/types";
+import type { OnObservationCallback } from "../../store/ObservationStore";
 export interface RealtimeLineChartProps {
+    /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
+    mode?: ChartMode;
     /** Chart dimensions as [width, height] */
     size?: [number, number];
     /** Chart width (alternative to size) */
@@ -18,6 +22,8 @@ export interface RealtimeLineChartProps {
     };
     /** CSS class name */
     className?: string;
+    onObservation?: OnObservationCallback;
+    chartId?: string;
     /** Direction time flows */
     arrowOfTime?: ArrowOfTime;
     /** Data retention strategy */

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

@@ -2,7 +2,11 @@ import * as React from "react";
 import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext } from "../../stream/types";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
+import type { ChartMode } from "../shared/types";
+import type { OnObservationCallback } from "../../store/ObservationStore";
 export interface RealtimeSwarmChartProps {
+    /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
+    mode?: ChartMode;
     /** Chart dimensions as [width, height] */
     size?: [number, number];
     /** Chart width (alternative to size) */
@@ -18,6 +22,8 @@ export interface RealtimeSwarmChartProps {
     };
     /** CSS class name */
     className?: string;
+    onObservation?: OnObservationCallback;
+    chartId?: string;
     /** Direction time flows */
     arrowOfTime?: ArrowOfTime;
     /** Data retention strategy */

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

@@ -2,7 +2,11 @@ import * as React from "react";
 import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext } from "../../stream/types";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
+import type { ChartMode } from "../shared/types";
+import type { OnObservationCallback } from "../../store/ObservationStore";
 export interface RealtimeWaterfallChartProps {
+    /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
+    mode?: ChartMode;
     /** Chart dimensions as [width, height] */
     size?: [number, number];
     /** Chart width (alternative to size) */
@@ -18,6 +22,8 @@ export interface RealtimeWaterfallChartProps {
     };
     /** CSS class name */
     className?: string;
+    onObservation?: OnObservationCallback;
+    chartId?: string;
     /** Direction time flows */
     arrowOfTime?: ArrowOfTime;
     /** Data retention strategy */

package/dist/charts/shared/annotationRules.d.ts

@@ -0,0 +1,3 @@
+import * as React from "react";
+import type { AnnotationContext } from "../../realtime/types";
+export declare function createDefaultAnnotationRules(frameType: "xy" | "ordinal" | "network"): (annotation: Record<string, any>, index: number, context: AnnotationContext) => React.ReactNode | null;