semiotic 3.0.1 → 3.1.0

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

@@ -8,6 +8,16 @@ export interface LineStyle {
     strokeWidth?: number;
     strokeDasharray?: string;
 }
+/**
+ * Anchoring mode for streaming annotations.
+ * - `"fixed"` (default): anchored to specific datum coordinates; disappears when out of view.
+ * - `"latest"`: annotation attaches to the most recent datum in the buffer.
+ *   On each frame, the annotation's position is re-resolved to the latest data point.
+ *   Useful for "current value" labels.
+ * - `"sticky"`: annotation stays at its last known pixel position after the target datum
+ *   is evicted from the window. It freezes in place rather than disappearing.
+ */
+export type AnnotationAnchorMode = "fixed" | "latest" | "sticky";
 export interface AnnotationContext {
     scales?: {
         x?: ScaleLinear<number, number>;
@@ -30,6 +40,13 @@ export interface AnnotationContext {
         y: number;
         r: number;
     }[];
+    /** Curve interpolation type from the parent chart */
+    curve?: string;
+    /** Cache of last known pixel positions for sticky annotations, keyed by annotation index */
+    stickyPositionCache?: Map<number, {
+        x: number;
+        y: number;
+    }>;
 }
 export interface CrosshairStyle {
     stroke?: string;

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

@@ -5,3 +5,4 @@
 export { bin, rollup, groupBy, pivot } from "./data/transforms";
 export { fromVegaLite } from "./data/fromVegaLite";
 export type { VegaLiteSpec, VegaLiteEncoding } from "./data/fromVegaLite";
+export { mergeData } from "./geo/mergeData";

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

@@ -0,0 +1,16 @@
+/**
+ * Geo entry point — geographic visualization: choropleth, proportional symbol, flow maps.
+ * Import from "semiotic/geo" instead of the full bundle to reduce bundle size.
+ */
+import StreamGeoFrame from "./stream/StreamGeoFrame";
+export { StreamGeoFrame };
+export { ChoroplethMap } from "./charts/geo/ChoroplethMap";
+export { ProportionalSymbolMap } from "./charts/geo/ProportionalSymbolMap";
+export { FlowMap } from "./charts/geo/FlowMap";
+export { DistanceCartogram } from "./charts/geo/DistanceCartogram";
+export type { StreamGeoFrameProps, StreamGeoFrameHandle, GeoAreaSceneNode, GeoSceneNode, GeoScales, ProjectionProp, ProjectionName, GraticuleConfig, DistanceCartogramConfig, GeoPipelineConfig } from "./stream/geoTypes";
+export type { GeoParticleStyle } from "./stream/GeoParticlePool";
+export { mergeData } from "./geo/mergeData";
+export { resolveReferenceGeography } from "./geo/referenceGeography";
+export type { ReferenceGeography } from "./geo/referenceGeography";
+export type { AreasProp } from "./geo/useReferenceAreas";

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

@@ -1 +1 @@
-export { renderToStaticSVG, renderXYToStaticSVG, renderOrdinalToStaticSVG, renderNetworkToStaticSVG } from "./server/renderToStaticSVG";
+export { renderToStaticSVG, renderXYToStaticSVG, renderOrdinalToStaticSVG, renderNetworkToStaticSVG, renderGeoToStaticSVG } from "./server/renderToStaticSVG";

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

@@ -13,4 +13,5 @@ export { BubbleChart } from "./charts/xy/BubbleChart";
 export { Heatmap } from "./charts/xy/Heatmap";
 export { ScatterplotMatrix } from "./charts/xy/ScatterplotMatrix";
 export { MinimapChart } from "./charts/xy/MinimapChart";
+export { QuadrantChart } from "./charts/xy/QuadrantChart";
 export type { StreamXYFrameProps, StreamXYFrameHandle } from "./stream/types";

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, SwarmPlot, BoxPlot, Histogram, ViolinPlot, RidgelinePlot, DotPlot, PieChart, DonutChart, GroupedBarChart, ForceDirectedGraph, ChordDiagram, SankeyDiagram, TreeDiagram, Treemap, CirclePack, OrbitDiagram, ScatterplotMatrix, MinimapChart } from "./charts";
+import { Scatterplot, ConnectedScatterplot, LineChart, AreaChart, StackedAreaChart, Heatmap, BubbleChart, BarChart, StackedBarChart, SwarmPlot, BoxPlot, Histogram, ViolinPlot, RidgelinePlot, DotPlot, PieChart, DonutChart, GroupedBarChart, ForceDirectedGraph, ChordDiagram, SankeyDiagram, TreeDiagram, Treemap, CirclePack, OrbitDiagram, ScatterplotMatrix, MinimapChart, QuadrantChart } from "./charts";
 import { LinkedCharts } from "./LinkedCharts";
 import { ThemeProvider, useTheme } from "./ThemeProvider";
 import { exportChart } from "./export/exportChart";
@@ -22,8 +22,8 @@ import { RealtimeTemporalHistogram, RealtimeHistogram } from "./charts/realtime/
 import { RealtimeSwarmChart } from "./charts/realtime/RealtimeSwarmChart";
 import { RealtimeWaterfallChart } from "./charts/realtime/RealtimeWaterfallChart";
 import { RealtimeHeatmap } from "./charts/realtime/RealtimeHeatmap";
-export { StreamXYFrame, StreamOrdinalFrame, StreamNetworkFrame, Scatterplot, ConnectedScatterplot, LineChart, AreaChart, StackedAreaChart, Heatmap, BubbleChart, BarChart, StackedBarChart, SwarmPlot, BoxPlot, Histogram, ViolinPlot, RidgelinePlot, DotPlot, ForceDirectedGraph, ChordDiagram, SankeyDiagram, TreeDiagram, PieChart, DonutChart, GroupedBarChart, Treemap, CirclePack, OrbitDiagram, ScatterplotMatrix, MinimapChart, 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 };
-export { ScatterplotProps, ConnectedScatterplotProps, LineChartProps, AreaChartProps, StackedAreaChartProps, HeatmapProps, BubbleChartProps, BarChartProps, StackedBarChartProps, SwarmPlotProps, BoxPlotProps, HistogramProps, ViolinPlotProps, DotPlotProps, PieChartProps, DonutChartProps, GroupedBarChartProps, RidgelinePlotProps, OrbitDiagramProps, OrbitNode, ForceDirectedGraphProps, ChordDiagramProps, SankeyDiagramProps, TreeDiagramProps, TreemapProps, CirclePackProps, ScatterplotMatrixProps, MinimapChartProps, MinimapConfig, BaseChartProps, AxisConfig, Accessor, ChartAccessor, ChartMode } from "./charts";
+export { StreamXYFrame, StreamOrdinalFrame, StreamNetworkFrame, Scatterplot, ConnectedScatterplot, LineChart, AreaChart, StackedAreaChart, Heatmap, BubbleChart, BarChart, StackedBarChart, SwarmPlot, BoxPlot, Histogram, ViolinPlot, RidgelinePlot, DotPlot, ForceDirectedGraph, ChordDiagram, SankeyDiagram, TreeDiagram, PieChart, DonutChart, GroupedBarChart, Treemap, CirclePack, OrbitDiagram, ScatterplotMatrix, MinimapChart, QuadrantChart, 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 };
+export { ScatterplotProps, ConnectedScatterplotProps, LineChartProps, AreaChartProps, StackedAreaChartProps, HeatmapProps, BubbleChartProps, BarChartProps, StackedBarChartProps, SwarmPlotProps, BoxPlotProps, HistogramProps, ViolinPlotProps, DotPlotProps, PieChartProps, DonutChartProps, GroupedBarChartProps, RidgelinePlotProps, OrbitDiagramProps, OrbitNode, ForceDirectedGraphProps, ChordDiagramProps, SankeyDiagramProps, TreeDiagramProps, TreemapProps, CirclePackProps, ScatterplotMatrixProps, MinimapChartProps, MinimapConfig, QuadrantChartProps, QuadrantsConfig, QuadrantConfig, CenterlineStyle, BaseChartProps, AxisConfig, Accessor, ChartAccessor, ChartMode } from "./charts";
 export type { StreamXYFrameProps, StreamXYFrameHandle, StreamChartType, RuntimeMode, SceneNode, Changeset, StreamScales, StreamLayout, CurveType, CanvasRendererFn } from "./stream/types";
 export type { StreamRendererFn } from "./stream/renderers/types";
 export type { StreamOrdinalFrameProps, StreamOrdinalFrameHandle, OrdinalChartType, OrdinalScales, OrdinalSceneNode } from "./stream/ordinalTypes";
@@ -49,7 +49,7 @@ export type { VegaLiteSpec, VegaLiteEncoding } from "./data/fromVegaLite";
 export type { SerializedSelections, SerializedSelection, SerializedFieldSelection } from "./export/selectionSerializer";
 export { smartTickFormat } from "./charts/shared/formatUtils";
 export type { TooltipProp, TooltipConfig, TooltipField, MultiLineTooltipConfig } from "./Tooltip/Tooltip";
-export type { ArrowOfTime, WindowMode, ThresholdType, LineStyle, BarStyle, WaterfallStyle, SwarmStyle, AnnotationContext, CrosshairStyle, HoverAnnotationConfig, HoverData } from "./realtime/types";
+export type { ArrowOfTime, WindowMode, ThresholdType, LineStyle, BarStyle, WaterfallStyle, SwarmStyle, AnnotationContext, AnnotationAnchorMode, CrosshairStyle, HoverAnnotationConfig, HoverData } from "./realtime/types";
 export type { RealtimeLineChartProps } from "./charts/realtime/RealtimeLineChart";
 export type { RealtimeTemporalHistogramProps, RealtimeHistogramProps } from "./charts/realtime/RealtimeHistogram";
 export type { RealtimeSwarmChartProps } from "./charts/realtime/RealtimeSwarmChart";

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

@@ -8,9 +8,11 @@
 import type { StreamXYFrameProps } from "../stream/types";
 import type { StreamNetworkFrameProps } from "../stream/networkTypes";
 import type { StreamOrdinalFrameProps } from "../stream/ordinalTypes";
-type FrameType = "xy" | "ordinal" | "network";
-export declare function renderToStaticSVG(frameType: FrameType, props: StreamXYFrameProps | StreamNetworkFrameProps | StreamOrdinalFrameProps): string;
+import type { StreamGeoFrameProps } from "../stream/geoTypes";
+type FrameType = "xy" | "ordinal" | "network" | "geo";
+export declare function renderToStaticSVG(frameType: FrameType, props: StreamXYFrameProps | StreamNetworkFrameProps | StreamOrdinalFrameProps | StreamGeoFrameProps): string;
 export declare function renderXYToStaticSVG(props: StreamXYFrameProps): string;
 export declare function renderOrdinalToStaticSVG(props: StreamOrdinalFrameProps): string;
 export declare function renderNetworkToStaticSVG(props: StreamNetworkFrameProps): string;
+export declare function renderGeoToStaticSVG(props: StreamGeoFrameProps): string;
 export {};

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

@@ -0,0 +1,50 @@
+import * as React from "react";
+/** Scene node type used by the accessible data table — accepts any frame's scene nodes */
+type AnySceneNode = {
+    type: string;
+    [key: string]: any;
+};
+/**
+ * Compute an aria-label describing the chart type and data shape from the scene graph.
+ */
+export declare function computeCanvasAriaLabel(scene: AnySceneNode[], chartType: string): string;
+/**
+ * Compute an aria-label for network charts from scene nodes and edges.
+ */
+export declare function computeNetworkAriaLabel(nodeCount: number, edgeCount: number, chartType: string): string;
+interface AccessibleDataTableProps {
+    scene: AnySceneNode[];
+    chartType: string;
+}
+/**
+ * Visually-hidden data table for screen readers, generated from the scene graph.
+ * Renders up to 50 rows with a truncation note.
+ */
+export declare function AccessibleDataTable({ scene, chartType }: AccessibleDataTableProps): React.JSX.Element | null;
+interface NetworkAccessibleDataTableProps {
+    nodes: Array<{
+        datum?: any;
+        id?: string;
+        cx?: number;
+        cy?: number;
+        x?: number;
+        y?: number;
+    }>;
+    edges: Array<{
+        datum?: any;
+        source?: string;
+        target?: string;
+    }>;
+    chartType: string;
+}
+/**
+ * Visually-hidden data table for network charts.
+ */
+export declare function NetworkAccessibleDataTable({ nodes, edges, chartType }: NetworkAccessibleDataTableProps): React.JSX.Element | null;
+/**
+ * Visually-hidden aria-live region that mirrors tooltip text for screen readers.
+ */
+export declare function AriaLiveTooltip({ hoverPoint }: {
+    hoverPoint: any;
+}): React.JSX.Element;
+export {};

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

@@ -1,5 +1,6 @@
-import type { SceneNode } from "./types";
+import type { SceneNode, PointSceneNode } from "./types";
 import type { RingBuffer } from "../realtime/RingBuffer";
+import type { Quadtree } from "d3-quadtree";
 export interface HitResult {
     node: SceneNode;
     datum: any;
@@ -10,8 +11,13 @@ export interface HitResult {
 /**
  * Find the nearest scene node to the given pixel coordinates.
  * Dispatches to type-specific hit testers for optimal performance.
+ *
+ * When a quadtree spatial index is provided (for scatter/bubble charts with
+ * many points), point hit testing uses O(log n) quadtree.find() instead of
+ * iterating all nodes. Non-point node types (line, rect, area, etc.) still
+ * use the linear scan.
  */
-export declare function findNearestNode(scene: SceneNode[], px: number, py: number, maxDistance?: number): HitResult | null;
+export declare function findNearestNode(scene: SceneNode[], px: number, py: number, maxDistance?: number, pointQuadtree?: Quadtree<PointSceneNode> | null): HitResult | null;
 /**
  * Binary search for nearest point by time value in a RingBuffer.
  */

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

@@ -4,9 +4,23 @@ export declare class DataSourceAdapter<T = Record<string, any>> {
     private callback;
     private lastBoundedData;
     private chunkTimer;
-    constructor(callback: ChangesetCallback<T>);
+    private chunkThreshold;
+    private chunkSize;
+    /** Buffer for batching high-frequency push() calls */
+    private pushBuffer;
+    /** Whether a microtask flush is already scheduled */
+    private flushScheduled;
+    constructor(callback: ChangesetCallback<T>, options?: {
+        chunkThreshold?: number;
+        chunkSize?: number;
+    });
+    /** Update chunking options without recreating the adapter. */
+    updateChunkOptions(options: {
+        chunkThreshold?: number;
+        chunkSize?: number;
+    }): void;
     /** Clear the dedup cache so the next setBoundedData call re-ingests even the same reference.
-     *  Also cancels any in-flight progressive chunking. */
+     *  Also cancels any in-flight progressive chunking and discards buffered pushes. */
     clearLastData(): void;
     /**
      * Ingest a bounded data array (from props).
@@ -18,16 +32,31 @@ export declare class DataSourceAdapter<T = Record<string, any>> {
      * animation frames (bounded: false so they append without clearing).
      */
     setBoundedData(data: T[]): void;
+    /**
+     * Flush all buffered push data as a single changeset.
+     * Called automatically via microtask after push()/pushMany().
+     */
+    private flushPushBuffer;
+    /** Schedule a microtask flush if one isn't already pending. */
+    private scheduleFlush;
     /**
      * Push a single datum (streaming mode).
-     * Emits a micro-changeset with `bounded: false`.
+     * 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.
      */
     push(datum: T): void;
     /**
      * Push multiple data (streaming batch).
-     * Emits a single changeset with `bounded: false`.
+     * Like push(), data is buffered and flushed via microtask. Multiple
+     * pushMany() calls within the same task are coalesced.
      */
     pushMany(data: T[]): void;
+    /**
+     * Immediately flush any buffered push data without waiting for the microtask.
+     * Useful when you need the data to be processed synchronously (e.g., in tests).
+     */
+    flush(): void;
     /**
      * Reset the adapter state.
      */

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

@@ -0,0 +1,19 @@
+import type { GeoSceneNode } from "./geoTypes";
+import type { PointSceneNode } from "./types";
+import type { Quadtree } from "d3-quadtree";
+export interface GeoHitResult {
+    node: GeoSceneNode;
+    distance: number;
+}
+/**
+ * Hit test geo scene nodes.
+ *
+ * Strategy:
+ * 1. Points first (topmost visual layer) — quadtree if available, else linear scan
+ * 2. Geo areas via ctx.isPointInPath(Path2D) — reverse order for top-layer-wins
+ * 3. Lines via closest-segment distance
+ *
+ * The `hitCtx` parameter is a shared offscreen canvas context used for
+ * isPointInPath checks without polluting the visible canvas.
+ */
+export declare function findNearestGeoNode(nodes: GeoSceneNode[], mouseX: number, mouseY: number, maxDistance: number, hitCtx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, pointQuadtree?: Quadtree<PointSceneNode>): GeoHitResult | null;

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

@@ -0,0 +1,46 @@
+/**
+ * GeoParticlePool — particle system for geo line paths.
+ *
+ * Unlike the network ParticlePool (which uses bezier curves), this
+ * travels particles along polyline paths (arrays of screen-space points).
+ * Used by StreamGeoFrame to animate flow lines on maps.
+ */
+export interface GeoParticle {
+    /** Progress along the polyline [0, 1] */
+    t: number;
+    /** Perpendicular offset from path centerline [-0.5, 0.5] */
+    offset: number;
+    /** Which line index this particle travels */
+    lineIndex: number;
+    active: boolean;
+    x: number;
+    y: number;
+}
+export interface GeoParticleStyle {
+    /** Particle radius @default 2 */
+    radius?: number;
+    /** Particle color: a CSS color string, "source" to inherit from line stroke, or a function `(datum) => string` */
+    color?: string | ((datum: any) => string);
+    /** Particle opacity @default 0.7 */
+    opacity?: number;
+    /** Speed multiplier @default 1 */
+    speedMultiplier?: number;
+    /** Max particles per line @default 30 */
+    maxPerLine?: number;
+    /** Spawn rate (probability per frame per line) @default 0.15 */
+    spawnRate?: number;
+}
+export declare class GeoParticlePool {
+    particles: GeoParticle[];
+    private capacity;
+    constructor(capacity: number);
+    spawn(lineIndex: number): GeoParticle | null;
+    /**
+     * Advance all active particles.
+     * @param paths - array of polyline paths, one per line index
+     * @param lineWidths - strokeWidth per line (for perpendicular offset scaling)
+     */
+    step(deltaTime: number, speed: number, paths: [number, number][][], lineWidths: number[]): void;
+    countForLine(lineIndex: number): number;
+    clear(): void;
+}

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

@@ -0,0 +1,81 @@
+import type { ZoomTransform } from "d3-zoom";
+import type { GeoPipelineConfig, GeoScales, GeoSceneNode } from "./geoTypes";
+import type { StreamLayout } from "./types";
+import type { ActiveTransition } from "./pipelineTransitionUtils";
+export declare class GeoPipelineStore {
+    config: GeoPipelineConfig;
+    scene: GeoSceneNode[];
+    scales: GeoScales | null;
+    version: number;
+    private projection;
+    private geoPath;
+    private baseScale;
+    private baseTranslate;
+    private baseRotation;
+    currentZoom: number;
+    cartogramLayout: {
+        cx: number;
+        cy: number;
+        maxCost: number;
+        availableRadius: number;
+    } | null;
+    private areas;
+    private pointData;
+    private lineData;
+    private pointBuffer;
+    private streaming;
+    lastIngestTime: number;
+    private timestampBuffer;
+    activeTransition: ActiveTransition | null;
+    private prevPositions;
+    constructor(config: GeoPipelineConfig);
+    updateConfig(config: Partial<GeoPipelineConfig>): void;
+    setAreas(features: GeoJSON.Feature[]): void;
+    setPoints(data: Record<string, any>[]): void;
+    setLines(data: Record<string, any>[]): void;
+    /** Initialize streaming mode with a ring buffer */
+    initStreaming(windowSize?: number): void;
+    /** Push a single streaming point */
+    pushPoint(datum: Record<string, any>): void;
+    /** Push multiple streaming points */
+    pushMany(data: Record<string, any>[]): void;
+    clear(): void;
+    computeScene(layout: StreamLayout): void;
+    private fitProjection;
+    /**
+     * Apply a d3-zoom transform to the projection.
+     * Called on zoom end — updates projection scale/translate and rebuilds scene.
+     */
+    applyZoomTransform(transform: ZoomTransform, layout: StreamLayout): void;
+    /**
+     * Apply zoom as scale-only (no translate shift).
+     * Used in drag-rotate mode to prevent globe drift on zoom.
+     */
+    applyZoomScale(k: number, layout: StreamLayout): void;
+    /**
+     * Apply a rotation to the projection and rebuild the scene.
+     * Called during drag-rotate gestures (orthographic globe spinning).
+     */
+    applyRotation(rotation: [number, number, number], layout: StreamLayout): void;
+    /**
+     * Set the projection rotation without rebuilding the scene.
+     * Use when rotation will be followed by another operation that rebuilds
+     * (e.g., applyZoomScale), to avoid redundant scene builds.
+     */
+    setRotation(rotation: [number, number, number]): void;
+    /** Get current rotation (for external tracking) */
+    getRotation(): [number, number, number];
+    /** Get the current base projection state (for zoom reset) */
+    getBaseProjectionState(): {
+        scale: number;
+        translate: [number, number];
+    };
+    private getPoints;
+    private buildSceneNodes;
+    private applyCartogramTransform;
+    private applyDecay;
+    private applyPulse;
+    get hasActivePulses(): boolean;
+    private startTransition;
+    advanceTransition(now: number): boolean;
+}

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

@@ -0,0 +1,31 @@
+import type { GeoProjection } from "d3-geo";
+export type TileURLTemplate = string | ((z: number, x: number, y: number, dpr: number) => string);
+interface CachedTile {
+    img: HTMLImageElement;
+    loaded: boolean;
+    key: string;
+    lastUsed: number;
+}
+export declare class TileCache {
+    private cache;
+    private limit;
+    constructor(limit?: number);
+    get(key: string): CachedTile | undefined;
+    set(key: string, entry: CachedTile): void;
+    private evict;
+    clear(): void;
+}
+export interface TileRenderOptions {
+    tileURL: TileURLTemplate;
+    projection: GeoProjection;
+    width: number;
+    height: number;
+    tileCache: TileCache;
+    onTileLoad?: () => void;
+}
+/**
+ * Render visible tiles onto a canvas context.
+ * Returns true if all visible tiles are loaded (no pending fetches).
+ */
+export declare function renderTiles(ctx: CanvasRenderingContext2D, options: TileRenderOptions): boolean;
+export {};

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

@@ -1,4 +1,5 @@
 import { ParticlePool } from "./ParticlePool";
+import type { ActiveTransition } from "./pipelineTransitionUtils";
 import type { NetworkPipelineConfig, NetworkSceneNode, NetworkSceneEdge, NetworkLabel, RealtimeNode, RealtimeEdge, EdgePush } from "./networkTypes";
 /**
  * NetworkPipelineStore — stateful store for the StreamNetworkFrame.
@@ -20,13 +21,12 @@ export declare class NetworkPipelineStore {
     particlePool: ParticlePool | null;
     private config;
     private tensionConfig;
-    transition: {
-        startTime: number;
-        duration: number;
-    } | null;
+    transition: ActiveTransition | null;
     lastIngestTime: number;
     private nodeTimestamps;
     private edgeTimestamps;
+    /** Cached sorted node-timestamp entries for applyDecay(); null = needs rebuild */
+    private _decaySortedNodes;
     /** Node IDs added in the most recent layout */
     addedNodes: Set<string>;
     /** Node IDs removed in the most recent layout */
@@ -39,6 +39,11 @@ export declare class NetworkPipelineStore {
     lastTopologyChangeTime: number;
     private previousNodeIds;
     private previousEdgeKeys;
+    /** Snapshot of node positions from the last layout — used for force warm-start */
+    _lastPositionSnapshot: Map<string, {
+        x: number;
+        y: number;
+    }> | null;
     constructor(config: NetworkPipelineConfig);
     updateConfig(config: NetworkPipelineConfig): void;
     /**
@@ -68,6 +73,13 @@ export declare class NetworkPipelineStore {
      * Build the scene graph from current layout positions.
      */
     buildScene(size: [number, number]): void;
+    /** Whether the current layout plugin drives continuous animation (respects orbitAnimated config) */
+    get isAnimating(): boolean;
+    /**
+     * Advance the layout animation by one frame (e.g. orbit rotation).
+     * Returns true if the scene should be rebuilt.
+     */
+    tickAnimation(size: [number, number], deltaTime: number): boolean;
     /**
      * Advance the transition animation. Returns true if still animating.
      */

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

@@ -1,7 +1,7 @@
 import * as React from "react";
 import type { ReactNode } from "react";
 import type { NetworkLabel } from "./networkTypes";
-import type { LegendGroup } from "../types/legendTypes";
+import type { LegendGroup, GradientLegendConfig } from "../types/legendTypes";
 export interface NetworkSVGOverlayProps {
     width: number;
     height: number;
@@ -20,6 +20,8 @@ export interface NetworkSVGOverlayProps {
     /** Legend configuration */
     legend?: ReactNode | {
         legendGroups: LegendGroup[];
+    } | {
+        gradient: GradientLegendConfig;
     };
     legendHoverBehavior?: (item: {
         label: string;
@@ -29,6 +31,7 @@ export interface NetworkSVGOverlayProps {
     }) => void;
     legendHighlightedCategory?: string | null;
     legendIsolatedCategories?: Set<string>;
+    legendPosition?: "right" | "left" | "top" | "bottom";
     /** User-provided SVG elements on top */
     foregroundGraphics?: ReactNode;
     /** Scene nodes for annotation positioning */

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

@@ -1,6 +1,7 @@
 import { type ScaleLinear } from "d3-scale";
 import type { OrdinalPipelineConfig, OrdinalScales, OrdinalSceneNode, OrdinalColumn, OrdinalLayout } from "./ordinalTypes";
 import type { Changeset } from "./types";
+import type { ActiveTransition } from "./pipelineTransitionUtils";
 export declare class OrdinalPipelineStore {
     private buffer;
     private rExtent;
@@ -17,15 +18,16 @@ export declare class OrdinalPipelineStore {
     private getConnector;
     /** Discovered categories in insertion order */
     private categories;
+    /** True once a non-bounded (push) changeset has been ingested */
+    private _hasStreamingData;
     /** Lazy color map built from colorScheme for resolvePieceStyle */
     private _colorSchemeMap;
     private _colorSchemeIndex;
     private timestampBuffer;
-    activeTransition: {
-        startTime: number;
-        duration: number;
-    } | null;
+    activeTransition: ActiveTransition | null;
     private prevPositionMap;
+    /** Exit nodes awaiting fade-out removal */
+    exitNodes: import("./ordinalTypes").OrdinalSceneNode[];
     lastIngestTime: number;
     scales: OrdinalScales | null;
     /** Per-accessor scales for multiAxis */
@@ -53,6 +55,8 @@ export declare class OrdinalPipelineStore {
     private applyDecay;
     private applyPulse;
     get hasActivePulses(): boolean;
+    /** Build a stable identity key for a scene node based on its content, not array index */
+    private getNodeKey;
     private snapshotPositions;
     private startTransition;
     advanceTransition(now: number): boolean;

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

@@ -2,7 +2,7 @@ import * as React from "react";
 import type { OrdinalScales } from "./ordinalTypes";
 import type { AnnotationContext } from "../realtime/types";
 import type { ReactNode } from "react";
-import type { LegendGroup } from "../types/legendTypes";
+import type { LegendGroup, GradientLegendConfig } from "../types/legendTypes";
 interface OrdinalSVGOverlayProps {
     width: number;
     height: number;
@@ -24,6 +24,8 @@ interface OrdinalSVGOverlayProps {
     title?: string | ReactNode;
     legend?: ReactNode | {
         legendGroups: LegendGroup[];
+    } | {
+        gradient: GradientLegendConfig;
     };
     legendHoverBehavior?: (item: {
         label: string;
@@ -33,6 +35,7 @@ interface OrdinalSVGOverlayProps {
     }) => void;
     legendHighlightedCategory?: string | null;
     legendIsolatedCategories?: Set<string>;
+    legendPosition?: "right" | "left" | "top" | "bottom";
     foregroundGraphics?: ReactNode;
     annotations?: Record<string, any>[];
     svgAnnotationRules?: (annotation: Record<string, any>, index: number, context: AnnotationContext) => ReactNode;
@@ -40,7 +43,26 @@ interface OrdinalSVGOverlayProps {
     xAccessor?: string;
     yAccessor?: string;
     annotationData?: Record<string, any>[];
+    /** When true, grid lines and axis baselines are skipped (rendered by OrdinalSVGUnderlay instead) */
+    underlayRendered?: boolean;
     children?: ReactNode;
 }
+interface OrdinalSVGUnderlayProps {
+    width: number;
+    height: number;
+    totalWidth: number;
+    totalHeight: number;
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    scales: OrdinalScales | null;
+    showAxes?: boolean;
+    showGrid?: boolean;
+    rFormat?: (d: number) => string;
+}
+export declare function OrdinalSVGUnderlay(props: OrdinalSVGUnderlayProps): React.JSX.Element | null;
 export declare function OrdinalSVGOverlay(props: OrdinalSVGOverlayProps): React.JSX.Element | null;
 export {};