semiotic 3.0.0-beta.2 → 3.0.0-beta.4

package/README.md

@@ -69,16 +69,38 @@ Semiotic is for projects that outgrow those libraries — when you need
 network graphs alongside time series, streaming data alongside static
 snapshots, or coordinated views across chart types.
 
+### Bundle size comparison
+
+| Library | Packed | Unpacked | What you get |
+|---|---|---|---|
+| Victory | 393 KB | 2.3 MB | Charts only |
+| Lightweight Charts | 586 KB | 3.0 MB | Financial charts only |
+| **Semiotic** | **668 KB** | **2.5 MB** | **Charts + networks + streaming + coordination** |
+| Recharts | 1.4 MB | 6.4 MB | Charts only |
+| Chart.js | 1.6 MB | 6.2 MB | Charts only, no React |
+| ApexCharts | 1.8 MB | 8.4 MB | Charts only |
+| ECharts | 11.4 MB | 57.6 MB | Everything, no React |
+
 **AI-ready.** Semiotic ships with structured schemas (`ai/schema.json`), an
 `import from "semiotic/ai"` entry point, and an MCP server — all designed for
 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
+npm install semiotic@3.0.0-beta.4
 ```
 
 Requires React 18.1 or later.
@@ -142,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:
@@ -173,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 }
@@ -222,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
 
@@ -241,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/ai/dist/componentRegistry.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPONENT_REGISTRY = void 0;
+const ai_1 = require("semiotic/ai");
+exports.COMPONENT_REGISTRY = {
+    LineChart: { component: ai_1.LineChart, category: "xy" },
+    AreaChart: { component: ai_1.AreaChart, category: "xy" },
+    StackedAreaChart: { component: ai_1.StackedAreaChart, category: "xy" },
+    Scatterplot: { component: ai_1.Scatterplot, category: "xy" },
+    BubbleChart: { component: ai_1.BubbleChart, category: "xy" },
+    Heatmap: { component: ai_1.Heatmap, category: "xy" },
+    BarChart: { component: ai_1.BarChart, category: "ordinal" },
+    StackedBarChart: { component: ai_1.StackedBarChart, category: "ordinal" },
+    GroupedBarChart: { component: ai_1.GroupedBarChart, category: "ordinal" },
+    SwarmPlot: { component: ai_1.SwarmPlot, category: "ordinal" },
+    BoxPlot: { component: ai_1.BoxPlot, category: "ordinal" },
+    DotPlot: { component: ai_1.DotPlot, category: "ordinal" },
+    PieChart: { component: ai_1.PieChart, category: "ordinal" },
+    DonutChart: { component: ai_1.DonutChart, category: "ordinal" },
+    ForceDirectedGraph: { component: ai_1.ForceDirectedGraph, category: "network" },
+    ChordDiagram: { component: ai_1.ChordDiagram, category: "network" },
+    SankeyDiagram: { component: ai_1.SankeyDiagram, category: "network" },
+    TreeDiagram: { component: ai_1.TreeDiagram, category: "network" },
+    Treemap: { component: ai_1.Treemap, category: "network" },
+    CirclePack: { component: ai_1.CirclePack, category: "network" },
+};

package/ai/dist/{ai/mcp-server.js → mcp-server.js}

@@ -58,7 +58,7 @@ const path = __importStar(require("path"));
 const renderHOCToSVG_1 = require("./renderHOCToSVG");
 const componentRegistry_1 = require("./componentRegistry");
 // Load schema.json for tool definitions
-const schemaPath = path.resolve(__dirname, "schema.json");
+const schemaPath = path.resolve(__dirname, "../schema.json");
 const schema = JSON.parse(fs.readFileSync(schemaPath, "utf-8"));
 // Build MCP server
 const server = new mcp_js_1.McpServer({

package/ai/dist/{ai/renderHOCToSVG.js → renderHOCToSVG.js}

@@ -43,7 +43,7 @@ exports.renderHOCToSVG = renderHOCToSVG;
 const React = __importStar(require("react"));
 const ReactDOMServer = __importStar(require("react-dom/server"));
 const componentRegistry_1 = require("./componentRegistry");
-const validateProps_1 = require("../src/components/charts/shared/validateProps");
+const ai_1 = require("semiotic/ai");
 function renderHOCToSVG(componentName, props) {
     // Look up component
     const entry = componentRegistry_1.COMPONENT_REGISTRY[componentName];
@@ -54,7 +54,7 @@ function renderHOCToSVG(componentName, props) {
         };
     }
     // Validate props
-    const validation = (0, validateProps_1.validateProps)(componentName, props);
+    const validation = (0, ai_1.validateProps)(componentName, props);
     if (!validation.valid) {
         return {
             svg: 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/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;

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

@@ -1,22 +1,28 @@
+import { interpolateBlues, interpolateReds, interpolateGreens, interpolateOranges, interpolatePurples, interpolateViridis, interpolatePlasma } from "d3-scale-chromatic";
 /**
  * Predefined color schemes
  */
 export declare const COLOR_SCHEMES: {
-    category10: any;
-    tableau10: any;
-    set3: any;
-    blues: any;
-    reds: any;
-    greens: any;
-    oranges: any;
-    purples: any;
-    viridis: any;
-    plasma: any;
+    category10: readonly string[];
+    tableau10: readonly string[];
+    set3: readonly string[];
+    blues: typeof interpolateBlues;
+    reds: typeof interpolateReds;
+    greens: typeof interpolateGreens;
+    oranges: typeof interpolateOranges;
+    purples: typeof interpolatePurples;
+    viridis: typeof interpolateViridis;
+    plasma: typeof interpolatePlasma;
 };
 /**
  * Default colors for charts
  */
-export declare const DEFAULT_COLORS: any;
+export declare const DEFAULT_COLORS: readonly string[];
+/**
+ * Pastel palette for depth-based hierarchy coloring (Treemap, CirclePack, TreeDiagram).
+ * Index corresponds to hierarchy depth, wraps via modulo.
+ */
+export declare const DEPTH_PALETTE_COLORS: string[];
 /**
  * Gets a color for a data point based on the colorBy configuration
  *