semiotic 3.4.1 → 3.5.0

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

@@ -0,0 +1,24 @@
+/**
+ * Recipes entry point — curated layout functions for use with `XYCustomChart`.
+ *
+ * Import from "semiotic/recipes" instead of the full bundle. Recipes are
+ * pure CustomLayout functions that emit standard SceneNodes; they get hit
+ * testing, transitions, decay, theme cascade, and SSR for free.
+ */
+export { waffleLayout } from "./recipes/waffle";
+export type { WaffleConfig } from "./recipes/waffle";
+export { calendarLayout } from "./recipes/calendar";
+export type { CalendarConfig } from "./recipes/calendar";
+export { flextreeLayout } from "./recipes/flextree";
+export type { FlextreeConfig } from "./recipes/flextree";
+export { dagreLayout } from "./recipes/dagre";
+export type { DagreConfig } from "./recipes/dagre";
+export { marimekkoLayout } from "./recipes/marimekko";
+export type { MarimekkoConfig } from "./recipes/marimekko";
+export { bulletLayout } from "./recipes/bullet";
+export type { BulletConfig } from "./recipes/bullet";
+export { parallelCoordinatesLayout } from "./recipes/parallelCoordinates";
+export type { ParallelCoordinatesConfig } from "./recipes/parallelCoordinates";
+export type { CustomLayout, LayoutContext, LayoutResult, } from "./stream/customLayout";
+export type { NetworkCustomLayout, NetworkLayoutContext, NetworkLayoutResult, } from "./stream/networkCustomLayout";
+export type { OrdinalCustomLayout, OrdinalLayoutContext, OrdinalLayoutResult, } from "./stream/ordinalCustomLayout";

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

@@ -16,7 +16,9 @@ export { MinimapChart } from "./charts/xy/MinimapChart";
 export { QuadrantChart } from "./charts/xy/QuadrantChart";
 export { MultiAxisLineChart } from "./charts/xy/MultiAxisLineChart";
 export { CandlestickChart } from "./charts/xy/CandlestickChart";
+export { XYCustomChart } from "./charts/custom/XYCustomChart";
 export type { StreamXYFrameProps, StreamXYFrameHandle } from "./stream/types";
+export type { CustomLayout, LayoutContext, LayoutResult } from "./stream/customLayout";
 export type { LineChartProps } from "./charts/xy/LineChart";
 export type { AreaChartProps } from "./charts/xy/AreaChart";
 export type { StackedAreaChartProps } from "./charts/xy/StackedAreaChart";
@@ -27,3 +29,4 @@ export type { HeatmapProps } from "./charts/xy/Heatmap";
 export type { QuadrantChartProps } from "./charts/xy/QuadrantChart";
 export type { MultiAxisLineChartProps } from "./charts/xy/MultiAxisLineChart";
 export type { CandlestickChartProps } from "./charts/xy/CandlestickChart";
+export type { XYCustomChartProps } from "./charts/custom/XYCustomChart";

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, GaugeChart, GroupedBarChart, FunnelChart, SwimlaneChart, ForceDirectedGraph, ChordDiagram, SankeyDiagram, TreeDiagram, Treemap, CirclePack, OrbitDiagram, ScatterplotMatrix, MinimapChart, QuadrantChart, MultiAxisLineChart, CandlestickChart } 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, CandlestickChart, XYCustomChart, NetworkCustomChart, OrdinalCustomChart } from "./charts";
 import { LinkedCharts } from "./LinkedCharts";
 import { ThemeProvider, useTheme } from "./ThemeProvider";
 import { exportChart } from "./export/exportChart";
@@ -23,7 +23,7 @@ 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, GaugeChart, FunnelChart, GroupedBarChart, SwimlaneChart, Treemap, CirclePack, OrbitDiagram, ScatterplotMatrix, MinimapChart, QuadrantChart, MultiAxisLineChart, CandlestickChart, 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 { 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, CandlestickChart, XYCustomChart, NetworkCustomChart, OrdinalCustomChart, 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, CandlestickChartProps, 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";

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

@@ -20,6 +20,7 @@ import type { StreamNetworkFrameProps } from "../stream/networkTypes";
 import type { StreamOrdinalFrameProps } from "../stream/ordinalTypes";
 import type { StreamGeoFrameProps } from "../stream/geoTypes";
 import { type ThemeInput } from "./themeResolver";
+import { CHART_CONFIGS } from "./serverChartConfigs";
 type FrameType = "xy" | "ordinal" | "network" | "geo";
 interface ThemeAwareProps {
     theme?: ThemeInput;
@@ -39,8 +40,13 @@ export declare function renderXYToStaticSVG(props: StreamXYFrameProps & ThemeAwa
 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" | "LikertChart" | "FunnelChart" | "GaugeChart" | "ForceDirectedGraph" | "SankeyDiagram" | "ChordDiagram" | "TreeDiagram" | "Treemap" | "CirclePack" | "ChoroplethMap" | "ProportionalSymbolMap" | "FlowMap";
+/**
+ * Chart component names renderable via `renderChart()`. Derived from the
+ * registry so adding a chart to `CHART_CONFIGS` automatically widens this
+ * union — no second edit required, no silent drift like the CandlestickChart
+ * gap that motivated this refactor.
+ */
+type ChartName = keyof typeof CHART_CONFIGS;
 interface RenderChartOptions {
     /** Output format — currently only "svg" is synchronous */
     format?: "svg";

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

@@ -5,5 +5,51 @@ interface ChartConfig {
     /** Build frame props from HOC-level props */
     buildProps: (data: any, colorBy: any, colorScheme: any, common: Datum, rest: Datum) => Datum;
 }
-export declare const CHART_CONFIGS: Record<string, ChartConfig>;
+export declare const CHART_CONFIGS: {
+    Sparkline: ChartConfig;
+    LineChart: ChartConfig;
+    AreaChart: ChartConfig;
+    StackedAreaChart: ChartConfig;
+    Scatterplot: ChartConfig;
+    CandlestickChart: ChartConfig;
+    BubbleChart: {
+        frameType: "xy";
+        buildProps: (data: any, colorBy: any, colorScheme: any, common: Datum, rest: Datum) => {
+            chartType: string;
+            data: any;
+            xAccessor: any;
+            yAccessor: any;
+            colorAccessor: any;
+            sizeAccessor: any;
+            sizeRange: any;
+            colorScheme: any;
+        };
+    };
+    ConnectedScatterplot: ChartConfig;
+    Heatmap: ChartConfig;
+    BarChart: ChartConfig;
+    StackedBarChart: ChartConfig;
+    GroupedBarChart: ChartConfig;
+    PieChart: ChartConfig;
+    DonutChart: ChartConfig;
+    Histogram: ChartConfig;
+    BoxPlot: ChartConfig;
+    ViolinPlot: ChartConfig;
+    SwarmPlot: ChartConfig;
+    DotPlot: ChartConfig;
+    SwimlaneChart: ChartConfig;
+    RidgelinePlot: ChartConfig;
+    LikertChart: ChartConfig;
+    FunnelChart: ChartConfig;
+    GaugeChart: ChartConfig;
+    ForceDirectedGraph: ChartConfig;
+    SankeyDiagram: ChartConfig;
+    ChordDiagram: ChartConfig;
+    TreeDiagram: ChartConfig;
+    Treemap: ChartConfig;
+    CirclePack: ChartConfig;
+    ChoroplethMap: ChartConfig;
+    ProportionalSymbolMap: ChartConfig;
+    FlowMap: ChartConfig;
+};
 export {};

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

@@ -17,6 +17,12 @@ interface AnnotationScales {
     };
     /** For ordinal charts: value scale */
     r?: (v: number) => number;
+    /**
+     * For geo charts: projects [lon, lat] → [x, y] pixel coords. Set by
+     * `renderGeoFrame` from the resolved `GeoPipelineStore` projection.
+     * Annotations that carry `coordinates: [lon, lat]` resolve through this.
+     */
+    geoProjection?: (coords: [number, number]) => [number, number] | null;
 }
 interface AnnotationLayout {
     width: number;

package/dist/components/store/ObservationStore.d.ts

@@ -56,7 +56,5 @@ export interface ObservationStoreState {
     pushObservation: (observation: ChartObservation) => void;
     clearObservations: () => void;
 }
-export declare const ObservationProvider: import("react").FC<{
-    children: React.ReactNode;
-}>, useObservationSelector: <R>(selector: (state: ObservationStoreState) => R) => R;
+export declare const ObservationProvider: import("react").FC<import("./createStore").StoreProviderProps<ObservationStoreState>>, useObservationSelector: <R>(selector: (state: ObservationStoreState) => R) => R;
 export {};

package/dist/components/store/SelectionStore.d.ts

@@ -2,7 +2,7 @@ import type { Datum } from "../charts/shared/datumTypes";
 export type ResolutionMode = "union" | "intersect" | "crossfilter";
 export interface FieldConstraint {
     type: "point";
-    values: Set<any>;
+    values: Set<unknown>;
 }
 export interface IntervalConstraint {
     type: "interval";
@@ -27,6 +27,4 @@ export interface SelectionStoreState {
     clearSelection: (selectionName: string) => void;
 }
 export declare function buildPredicate(selection: Selection, requestingClientId?: string): (d: Datum) => boolean;
-export declare const SelectionProvider: import("react").FC<{
-    children: React.ReactNode;
-}>, useSelectionSelector: <R>(selector: (state: SelectionStoreState) => R) => R;
+export declare const SelectionProvider: import("react").FC<import("./createStore").StoreProviderProps<SelectionStoreState>>, useSelectionSelector: <R>(selector: (state: SelectionStoreState) => R) => R;

package/dist/components/store/ThemeStore.d.ts

@@ -88,8 +88,8 @@ export declare const DARK_THEME: SemioticTheme;
 export declare const HIGH_CONTRAST_THEME: SemioticTheme;
 export interface ThemeStoreState {
     theme: SemioticTheme;
-    setTheme: (theme: Partial<SemioticTheme> | "light" | "dark" | "high-contrast") => void;
+    setTheme: (theme: ThemeStoreUpdate) => void;
 }
-export declare const ThemeProvider: import("react").FC<{
-    children: React.ReactNode;
-}>, useThemeSelector: <R>(selector: (state: ThemeStoreState) => R) => R;
+export type ThemeStoreUpdate = Partial<SemioticTheme> | "light" | "dark" | "high-contrast";
+export declare function resolveThemeUpdate(current: SemioticTheme, theme: ThemeStoreUpdate): SemioticTheme;
+export declare const ThemeProvider: import("react").FC<import("./createStore").StoreProviderProps<ThemeStoreState>>, useThemeSelector: <R>(selector: (state: ThemeStoreState) => R) => R;

package/dist/components/store/TooltipStore.d.ts

@@ -1,4 +1,6 @@
-declare const TooltipProvider: import("react").FC<{
-    children: React.ReactNode;
-}>, useTooltip: <R>(selector: (state: unknown) => R) => R;
+interface TooltipStoreState {
+    tooltip: unknown;
+    changeTooltip: (tooltip: unknown) => void;
+}
+declare const TooltipProvider: import("react").FC<import("./createStore").StoreProviderProps<TooltipStoreState>>, useTooltip: <R>(selector: (state: TooltipStoreState) => R) => R;
 export { TooltipProvider, useTooltip };

package/dist/components/store/createStore.d.ts

@@ -1,4 +1,6 @@
 import * as React from "react";
-export declare function createStore<T>(fn: (set: (updater: (current: T) => Partial<T>) => void) => T): [React.FC<{
+export interface StoreProviderProps<T> {
     children: React.ReactNode;
-}>, <R>(selector: (state: T) => R) => R];
+    initialState?: Partial<T>;
+}
+export declare function createStore<T>(fn: (set: (updater: (current: T) => Partial<T>) => void) => T): [React.FC<StoreProviderProps<T>>, <R>(selector: (state: T) => R) => R];

package/dist/components/store/useSelection.d.ts

@@ -14,7 +14,7 @@ export interface UseSelectionResult {
     /** Whether any selection clause is currently active */
     isActive: boolean;
     /** Set a point selection (categorical values) */
-    selectPoints: (fieldValues: Record<string, any[]>) => void;
+    selectPoints: (fieldValues: Record<string, unknown[]>) => void;
     /** Set an interval selection (numeric ranges) */
     selectInterval: (fieldRanges: Record<string, [number, number]>) => void;
     /** Clear this client's clause */
@@ -47,12 +47,12 @@ export interface UseBrushSelectionOptions {
     yField?: string;
 }
 export interface UseBrushSelectionResult {
-    /** Interaction config to pass to frameProps.interaction */
     brushInteraction: {
         brush: "xyBrush" | "xBrush" | "yBrush";
-        during: (extent: any) => void;
-        end: (extent: any) => void;
+        during: (extent: BrushExtent | null) => void;
+        end: (extent: BrushExtent | null) => void;
     };
+    /** Interaction config to pass to frameProps.interaction */
     /** Returns true if datum matches the brush selection */
     predicate: (datum: Datum) => boolean;
     /** Whether any brush is active */
@@ -60,6 +60,9 @@ export interface UseBrushSelectionResult {
     /** Clear the brush */
     clear: () => void;
 }
+type LinearBrushExtent = [number, number];
+type XYBrushExtent = [[number, number], [number, number]];
+type BrushExtent = LinearBrushExtent | XYBrushExtent | [number, number][];
 export declare function useBrushSelection(options: UseBrushSelectionOptions): UseBrushSelectionResult;
 /**
  * Returns the subset of `data` that matches the given selection.

package/dist/components/stream/CanvasHitTester.d.ts

@@ -9,6 +9,15 @@ export interface HitResult {
     y: number;
     distance: number;
 }
+export interface XHitResult {
+    node: SceneNode;
+    datum: any;
+    x: number;
+    y: number;
+    y0?: number;
+    group?: string;
+    color?: string;
+}
 /**
  * Find the nearest scene node to the given pixel coordinates.
  * Dispatches to type-specific hit testers for optimal performance.
@@ -29,14 +38,7 @@ export declare function findNearestNode(scene: SceneNode[], px: number, py: numb
  * For each node, interpolates the Y value at px using the path data.
  * Used for multi-point tooltip (show all series values at the hovered X).
  */
-export declare function findAllNodesAtX(scene: SceneNode[], px: number, maxXDistance?: number): Array<{
-    node: SceneNode;
-    datum: any;
-    x: number;
-    y: number;
-    group?: string;
-    color?: string;
-}>;
+export declare function findAllNodesAtX(scene: SceneNode[], px: number, maxXDistance?: number): XHitResult[];
 /**
  * Binary search for nearest point by time value in a RingBuffer.
  */

package/dist/components/stream/DataSourceAdapter.d.ts

@@ -62,12 +62,21 @@ export declare class DataSourceAdapter<T = Datum> {
      * Data is buffered and flushed as a single changeset via microtask,
      * so rapid sequential push() calls within the same task are batched
      * into one callback invocation.
+     *
+     * Drops `null`/non-object data so a `ref.push(null)` (typically from a
+     * loader returning a falsy row) doesn't reach extent/accessor reads
+     * inside the pipeline store. Mirrors the bounded-ingest hardening.
      */
     push(datum: T): void;
     /**
      * Push multiple data (streaming batch).
      * Like push(), data is buffered and flushed via microtask. Multiple
      * pushMany() calls within the same task are coalesced.
+     *
+     * Sparse entries are dropped during the buffer copy. Mirrors the
+     * bounded-ingest hardening — `ref.pushMany([null, valid])` lands the
+     * valid row and silently skips the null instead of crashing the
+     * pipeline. The early `length === 0` short-circuit still applies.
      */
     pushMany(data: T[]): void;
     /**

package/dist/components/stream/GeoPipelineStore.d.ts

@@ -101,5 +101,14 @@ export declare class GeoPipelineStore {
     private applyPulse;
     get hasActivePulses(): boolean;
     private startTransition;
+    /**
+     * Cancel any pending intro animation set up by the most recent
+     * `computeScene` call. After this, the next paint shows the scene
+     * in its final state directly. See `PipelineStore.cancelIntroAnimation`
+     * for the full rationale — Stream Frames call this when they detect
+     * SSR hydration so the canvas takeover doesn't re-animate from
+     * blank after the server already painted the chart.
+     */
+    cancelIntroAnimation(): void;
     advanceTransition(now: number): boolean;
 }

package/dist/components/stream/GeoTileRenderer.d.ts

@@ -1,3 +1,17 @@
+/**
+ * GeoTileRenderer — fetches, caches, and renders raster map tiles on a canvas.
+ *
+ * Inlines slippy-tile math from `d3-tile` (the v1 module is ~30 lines
+ * of math; the dependency wasn't earning its weight). The math is
+ * Web Mercator standard: each zoom level z has 2^z × 2^z 256-px tiles
+ * tiling the world; given a projection scale (in d3 units, where
+ * scale=256 puts the world in 256 px) and a translate offset, we
+ * compute the tile coordinates that cover the visible viewport and
+ * the (translate, scale) transform that maps tile coords to canvas px.
+ *
+ * Tiles are always in Web Mercator projection. A dev warning is
+ * emitted if tiles are used with a non-Mercator projection.
+ */
 import type { GeoProjection } from "d3-geo";
 export type TileURLTemplate = string | ((z: number, x: number, y: number, dpr: number) => string);
 interface CachedTile {

package/dist/components/stream/NetworkPipelineStore.d.ts

@@ -19,6 +19,8 @@ export declare class NetworkPipelineStore {
     sceneNodes: NetworkSceneNode[];
     sceneEdges: NetworkSceneEdge[];
     labels: NetworkLabel[];
+    /** Overlays returned from customNetworkLayout (consumed by StreamNetworkFrame). */
+    customLayoutOverlays: import("react").ReactNode;
     particlePool: ParticlePool | null;
     private config;
     private tensionConfig;
@@ -75,6 +77,15 @@ export declare class NetworkPipelineStore {
      * Run the layout algorithm via the appropriate plugin.
      */
     runLayout(size: [number, number]): void;
+    /**
+     * Compute added/removed node and edge sets relative to the previous
+     * layout snapshot, and update `lastTopologyChangeTime` if anything
+     * changed. Shared by the plugin path (`runLayout` finalization) and the
+     * customLayout escape hatch — without this, `getTopologyDiff()` and
+     * built-in topology-diff highlighting silently stop working when a
+     * `customNetworkLayout` is supplied.
+     */
+    private recordTopologyDiff;
     /**
      * Build the scene graph from current layout positions.
      */
@@ -86,6 +97,20 @@ export declare class NetworkPipelineStore {
      * Returns true if the scene should be rebuilt.
      */
     tickAnimation(size: [number, number], deltaTime: number): boolean;
+    /**
+     * Cancel any pending intro animation that the most recent layout
+     * pass set up. After this, the next paint shows nodes/edges in
+     * their final positions directly — no transition from the
+     * center-origin intro state.
+     *
+     * Stream Frames call this when they detect SSR hydration. The
+     * server already painted the chart in its final state via the SVG
+     * branch, so re-animating from blank when the canvas takes over is
+     * a visual regression.
+     *
+     * Idempotent — a second call is a no-op.
+     */
+    cancelIntroAnimation(): void;
     /**
      * Advance the transition animation. Returns true if still animating.
      */

package/dist/components/stream/NetworkSVGOverlay.d.ts

@@ -2,6 +2,17 @@ import type { Datum } from "../charts/shared/datumTypes";
 import type { ReactNode } from "react";
 import type { NetworkLabel } from "./networkTypes";
 import type { LegendGroup, GradientLegendConfig } from "../types/legendTypes";
+type AnnotationAnchorNode = {
+    type: string;
+    datum: Datum | null;
+    id?: string;
+    x?: number;
+    y?: number;
+    cx?: number;
+    cy?: number;
+    w?: number;
+    h?: number;
+};
 export interface NetworkSVGOverlayProps {
     width: number;
     height: number;
@@ -35,20 +46,14 @@ export interface NetworkSVGOverlayProps {
     /** User-provided SVG elements on top */
     foregroundGraphics?: ReactNode;
     /** Scene nodes for annotation positioning */
-    sceneNodes?: Array<{
-        type: string;
-        datum: any;
-        id?: string;
-        x?: number;
-        y?: number;
-        cx?: number;
-        cy?: number;
-        w?: number;
-        h?: number;
-    }>;
+    sceneNodes?: AnnotationAnchorNode[];
     /** Annotations */
     annotations?: Datum[];
-    svgAnnotationRules?: (annotation: Datum, index: number, context: any) => ReactNode;
+    svgAnnotationRules?: (annotation: Datum, index: number, context: {
+        width: number;
+        height: number;
+        sceneNodes?: AnnotationAnchorNode[];
+    }) => ReactNode;
     annotationFrame?: number;
 }
 /**
@@ -61,3 +66,4 @@ export declare function NetworkSVGOverlay(props: NetworkSVGOverlayProps): import
 export declare namespace NetworkSVGOverlay {
     var displayName: string;
 }
+export {};

package/dist/components/stream/OrdinalPipelineStore.d.ts

@@ -53,6 +53,8 @@ export declare class OrdinalPipelineStore {
     multiScales: (ScaleLinear<number, number>)[];
     scene: OrdinalSceneNode[];
     columns: Record<string, OrdinalColumn>;
+    /** Overlays returned from customLayout (consumed by StreamOrdinalFrame). */
+    customLayoutOverlays: import("react").ReactNode;
     version: number;
     /** Bumped whenever the buffer is mutated. Used to invalidate per-frame caches. */
     private _dataVersion;
@@ -78,6 +80,7 @@ export declare class OrdinalPipelineStore {
     private buildColumns;
     private getSceneContext;
     private buildSceneNodes;
+    private buildLayoutContext;
     private resolvePieceStyle;
     private getColorFromScheme;
     private resolveSummaryStyle;
@@ -115,6 +118,15 @@ export declare class OrdinalPipelineStore {
     private snapshotPositions;
     private startTransition;
     advanceTransition(now: number): boolean;
+    /**
+     * Cancel any pending intro animation that the most recent
+     * `computeScene` call set up. After this, the next paint shows the
+     * scene in its final state directly. See `PipelineStore.cancelIntroAnimation`
+     * for the full rationale — Stream Frames call this when they detect
+     * SSR hydration so the canvas takeover doesn't re-animate from blank
+     * after the server already painted the chart.
+     */
+    cancelIntroAnimation(): void;
     getData(): Datum[];
     /**
      * Remove data items by ID. Requires dataIdAccessor to be configured.

package/dist/components/stream/PipelineStore.d.ts

@@ -3,6 +3,8 @@ import { type Quadtree } from "d3-quadtree";
 import { RingBuffer } from "../realtime/RingBuffer";
 import type { Changeset, StreamChartType, StreamScales, StreamLayout, SceneNode, PointSceneNode, CandlestickStyle, Style, ArrowOfTime, WindowMode, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, CurveType, BarStyle, ThemeSemanticColors } from "./types";
 import type { ActiveTransition } from "./pipelineTransitionUtils";
+import type { CustomLayout } from "./customLayout";
+import type { MarginType } from "../types/marginType";
 export interface PipelineConfig {
     chartType: StreamChartType;
     runtimeMode?: "streaming" | "bounded";
@@ -29,6 +31,10 @@ export interface PipelineConfig {
     sizeRange?: [number, number];
     binSize?: number;
     normalize?: boolean;
+    /** Stacked area baseline mode. Only consulted by stackedarea chart type. */
+    baseline?: "zero" | "wiggle" | "silhouette";
+    /** Stack order — see StreamXYFrameProps.stackOrder. */
+    stackOrder?: "key" | "insideOut" | "asc" | "desc";
     openAccessor?: string | ((d: Datum) => number);
     highAccessor?: string | ((d: Datum) => number);
     lowAccessor?: string | ((d: Datum) => number);
@@ -117,6 +123,14 @@ export interface PipelineConfig {
     heatmapValueFormat?: (v: number) => string;
     pointIdAccessor?: string | ((d: Datum) => string);
     curve?: CurveType;
+    /** When provided, replaces chart-type dispatch in scene building.
+     *  Receives a LayoutContext (scales, dimensions, theme, resolveColor)
+     *  and returns scene nodes plus optional overlays. */
+    customLayout?: CustomLayout;
+    /** User-supplied config blob threaded through to LayoutContext.config. */
+    layoutConfig?: object;
+    /** Resolved margin — passed through so LayoutContext.dimensions.margin reflects what the frame actually used. */
+    layoutMargin?: MarginType;
 }
 export declare class PipelineStore {
     private buffer;
@@ -173,6 +187,8 @@ export declare class PipelineStore {
     scales: StreamScales | null;
     scene: SceneNode[];
     version: number;
+    /** Overlays returned from customLayout (consumed by StreamXYFrame for SVGOverlay). */
+    customLayoutOverlays: import("react").ReactNode;
     /** True when the x accessor returns Date objects (auto-detected on first data ingestion) */
     xIsDate: boolean;
     private _quadtree;
@@ -182,9 +198,21 @@ export declare class PipelineStore {
     private _maxPointRadius;
     private static readonly QUADTREE_THRESHOLD;
     constructor(config: PipelineConfig);
+    private pushDatumYExtent;
+    private rebuildYExtent;
+    private rebuildExtents;
+    private _lastBoundedInsertsRef;
     /**
      * Process a changeset from DataSourceAdapter.
      * Returns true if the scene needs re-rendering.
+     *
+     * Bounded mode is idempotent on identical `inserts` references —
+     * passing the same array a second time is a no-op (returns `false`,
+     * indicating no re-render needed). This makes render-time calls
+     * from the SSR branch safe under React StrictMode / concurrent
+     * rendering, where render runs twice. Non-bounded (streaming)
+     * ingests have no such guard because each new buffer entry is
+     * meaningful — streaming consumers don't pass the same array twice.
      */
     ingest(changeset: Changeset): boolean;
     /**
@@ -220,6 +248,29 @@ export declare class PipelineStore {
     private synthesizeIntroPositions;
     private startTransition;
     advanceTransition(now: number): boolean;
+    /**
+     * Cancel any pending intro animation that the most recent
+     * `computeScene` call set up. After this, the next paint shows the
+     * scene in its final state directly — no transition from zero-state
+     * positions, no clip-from-left animation on line/area marks.
+     *
+     * Stream Frames call this when they detect SSR hydration: the server
+     * already painted the chart in its final state via the SVG branch,
+     * so re-animating from blank when the canvas takes over is a visual
+     * regression. Subsequent data-change transitions still animate
+     * normally because they re-populate `prevPositionMap` from the
+     * snapshot taken before the change.
+     *
+     * Per-node `_introClipFraction` MUST be cleared too — line and area
+     * canvas renderers consume it directly (a `clipFrac < 1` produces a
+     * left-clip that hides the rest of the path), and `synthesizeIntroPositions`
+     * sets it to 0. Without the clear, line / area charts would paint
+     * blank on the first canvas frame after hydration.
+     *
+     * Idempotent — a second call is a no-op since the maps are already
+     * empty and the per-node flags are already undefined.
+     */
+    cancelIntroAnimation(): void;
     private groupData;
     /**
      * Resolve a category→color map from data using the colorAccessor.

package/dist/components/stream/SVGOverlay.d.ts

@@ -81,6 +81,18 @@ interface SVGOverlayProps {
     curve?: string;
     /** When true, grid lines and axis baselines are skipped (rendered by SVGUnderlay instead) */
     underlayRendered?: boolean;
+    /**
+     * Hint from the frame about whether the canvas is painting an opaque
+     * background that will hide `SVGUnderlay`. When `true`, this overlay
+     * also renders grid + baselines (otherwise nothing shows in the CSR
+     * steady state — the canvas covers the underlay copy). When `false`
+     * — e.g. `background="transparent"` or a `backgroundGraphics` SVG
+     * sibling — the underlay is visible and we skip the overlay copy to
+     * avoid the doubled / slightly-darker stroke. Defaults to `true` so
+     * existing callers behave the same as the post-jagged-base-fix
+     * baseline.
+     */
+    canvasObscuresUnderlay?: boolean;
     /** Name of the linked crosshair store entry to read */
     linkedCrosshairName?: string;
     /** Source chart ID — crosshair line is suppressed on the source to avoid double rendering */

package/dist/components/stream/SceneGraph.d.ts

@@ -4,10 +4,24 @@ export declare function buildLineNode(data: Datum[], scales: StreamScales, xGet:
 export declare function buildAreaNode(data: Datum[], scales: StreamScales, xGet: (d: Datum) => number, yGet: (d: Datum) => number, baselineY: number, style: Style, group?: string, y0Get?: (d: Datum) => number): AreaSceneNode;
 /** Per-group-per-x stacked top values, keyed by group then x */
 export type StackedTops = Map<string, Map<number, number>>;
+export type StackBaseline = "zero" | "wiggle" | "silhouette";
+/**
+ * Compute per-x stack baseline offsets. Shared between scene rendering
+ * (`buildStackedAreaNodes`) and extent computation (`PipelineStore`) so
+ * both see the same y-bounds — without this, the wiggle offset's
+ * accumulated drift can exceed `±total/2` and clip against a too-small
+ * y-domain.
+ *
+ * Inputs:
+ *   xValues   — sorted unique x values
+ *   groupKeys — group keys in stacking order (same order both callers use)
+ *   valueAt   — (groupKey, x) → group's value at x (0 if absent)
+ */
+export declare function computeStackOffsets(xValues: number[], groupKeys: string[], valueAt: (groupKey: string, x: number) => number, baseline: StackBaseline): Map<number, number>;
 export declare function buildStackedAreaNodes(groups: {
     key: string;
     data: Datum[];
-}[], scales: StreamScales, xGet: (d: Datum) => number, yGet: (d: Datum) => number, styleFn: (group: string, sampleDatum?: Datum) => Style, normalize?: boolean, curve?: CurveType): {
+}[], scales: StreamScales, xGet: (d: Datum) => number, yGet: (d: Datum) => number, styleFn: (group: string, sampleDatum?: Datum) => Style, normalize?: boolean, curve?: CurveType, baseline?: StackBaseline): {
     nodes: AreaSceneNode[];
     stackedTops: StackedTops;
 };

package/dist/components/stream/SceneToSVG.d.ts

@@ -9,7 +9,7 @@ import type { SceneNode } from "./types";
 import type { NetworkSceneNode, NetworkSceneEdge, NetworkLabel } from "./networkTypes";
 import type { OrdinalSceneNode } from "./ordinalTypes";
 import type { GeoSceneNode } from "./geoTypes";
-export declare function xySceneNodeToSVG(node: SceneNode, i: number): React.ReactNode;
+export declare function xySceneNodeToSVG(node: SceneNode, i: number, idPrefix?: string): React.ReactNode;
 export declare function networkSceneNodeToSVG(node: NetworkSceneNode, i: number): React.ReactNode;
 export declare function networkSceneEdgeToSVG(edge: NetworkSceneEdge, i: number): React.ReactNode;
 export declare function networkLabelToSVG(label: NetworkLabel, i: number): React.ReactNode;

package/dist/components/stream/categoryDomain.d.ts

@@ -0,0 +1,4 @@
+import type { Datum } from "../charts/shared/datumTypes";
+export type CategoryDomainAccessor<T = Datum> = string | ((d: T) => unknown);
+export declare function extractCategoryDomain<T extends Datum>(data: T[], accessor: CategoryDomainAccessor<T> | undefined): string[];
+export declare function sameCategoryDomain(a: readonly string[], b: readonly string[]): boolean;