semiotic 3.3.0 → 3.4.0

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

@@ -1,6 +1,7 @@
 import type React from "react";
 import type { MarginType } from "../../types/generalTypes";
 import type { OnObservationCallback } from "../../store/ObservationStore";
+import type { AnimateProp } from "../../stream/pipelineTransitionUtils";
 /**
  * Selection consumption config — makes this chart react to a named selection
  */
@@ -103,12 +104,10 @@ export interface BaseChartProps {
     dataIdAccessor?: string | ((d: any) => string);
     /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */
     emphasis?: "primary" | "secondary";
-    /** Enable declarative bounded animation (enter/exit/update transitions).
-     * `true` uses defaults (300ms ease-out). Object form allows customization. */
-    animate?: boolean | {
-        duration?: number;
-        easing?: "linear" | "ease-out";
-    };
+    /** Enable declarative bounded animation (enter/exit/update transitions + intro).
+     * `true` uses defaults (300ms ease-out, intro enabled). Object form allows customization.
+     * Set `{ intro: false }` to disable the animated intro on first render. */
+    animate?: AnimateProp;
 }
 /**
  * Axis configuration props

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

@@ -104,6 +104,14 @@ export interface ChartSetupResult {
         linkedCrosshairName: string;
         linkedCrosshairSourceId: string;
     } | undefined;
+    /**
+     * Selection config merged with theme-level defaults. HOCs should pass this
+     * to `wrapStyleWithSelection` instead of the raw `selection` prop so that
+     * the current theme's `colors.selectionOpacity` becomes the effective
+     * unselected-opacity fallback. Per-chart `selection.unselectedOpacity`
+     * still takes priority over the theme value.
+     */
+    resolvedSelection: SelectionConfig | undefined;
 }
 /**
  * Hook that consolidates the shared boilerplate across all HOC charts:

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

@@ -0,0 +1,2 @@
+import type { SelectionConfig } from "./types";
+export declare function useResolvedSelection(selection: SelectionConfig | undefined): SelectionConfig | undefined;

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

@@ -64,11 +64,50 @@ export interface HoverAnnotationConfig {
     pointColor?: string;
 }
 export interface HoverData {
-    data: Record<string, any>;
-    time: number;
-    value: number;
+    /** The raw datum from the user's data array (may be an object, array, or null for exit nodes) */
+    data: any;
+    /** Pixel X coordinate of the hovered element */
     x: number;
+    /** Pixel Y coordinate of the hovered element */
     y: number;
+    /** Pixel X coordinate, aliased as "time" for backwards compatibility with realtime charts */
+    time: number;
+    /** Pixel Y coordinate, aliased as "value" for backwards compatibility with realtime charts */
+    value: number;
+    /** All series values at hovered X (multi-point tooltip mode) */
+    allSeries?: Array<{
+        group: string;
+        value: number;
+        valuePx?: number;
+        color: string;
+        datum: any;
+    }>;
+    /** Pixel X of hover position (may differ from x for multi-point snap) */
+    xPx?: number;
+    /** Raw X domain value at hover position */
+    xValue?: any;
+    /** Distribution statistics for boxplot/violin/ridgeline */
+    stats?: {
+        n: number;
+        min: number;
+        q1: number;
+        median: number;
+        q3: number;
+        max: number;
+        mean: number;
+    };
+    /** Category label of hovered element */
+    category?: string;
+    /** @internal Category accessor name for tooltip rendering */
+    __oAccessor?: string;
+    /** @internal Value accessor name for tooltip rendering */
+    __rAccessor?: string;
+    /** @internal Chart type hint for tooltip rendering */
+    __chartType?: string;
+    /** Whether the hovered element is a node or edge */
+    nodeOrEdge?: "node" | "edge";
+    /** GeoJSON feature properties (flattened for convenience) */
+    properties?: Record<string, any>;
 }
 export interface BarStyle {
     fill?: string;
@@ -137,6 +176,18 @@ export interface RealtimeFrameHandle {
     update(id: string | string[], updater: (d: Record<string, any>) => Record<string, any>): Record<string, any>[];
     clear(): void;
     getData(): Record<string, any>[];
+    /** Returns the frame's resolved scales, or null if unavailable.
+     *
+     *  The concrete scales object differs by frame type — XY charts
+     *  expose `{ x, y }`, ordinal charts expose `{ o, r, projection }`,
+     *  network/geo don't have a meaningful scale concept and may not
+     *  implement this method at all.
+     *
+     *  Typed as `unknown` so the shared handle stays compatible across
+     *  chart families. HOCs that want a narrower return type should
+     *  export a chart-specific handle (e.g. `LikertChartHandle`) that
+     *  extends this interface and narrows `getScales()`. */
+    getScales?(): unknown | null;
 }
 export interface RealtimeScales {
     time: ScaleLinear<number, number>;

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

@@ -14,3 +14,7 @@ export { mergeData } from "./geo/mergeData";
 export { resolveReferenceGeography } from "./geo/referenceGeography";
 export type { ReferenceGeography } from "./geo/referenceGeography";
 export type { AreasProp } from "./geo/useReferenceAreas";
+export type { ChoroplethMapProps } from "./charts/geo/ChoroplethMap";
+export type { ProportionalSymbolMapProps } from "./charts/geo/ProportionalSymbolMap";
+export type { FlowMapProps } from "./charts/geo/FlowMap";
+export type { DistanceCartogramProps } from "./charts/geo/DistanceCartogram";

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

@@ -12,3 +12,10 @@ export { Treemap } from "./charts/network/Treemap";
 export { CirclePack } from "./charts/network/CirclePack";
 export { OrbitDiagram } from "./charts/network/OrbitDiagram";
 export type { StreamNetworkFrameProps, StreamNetworkFrameHandle, NetworkChartType, NetworkSceneNode, NetworkSceneEdge, NetworkLabel, ThresholdAlertConfig } from "./stream/networkTypes";
+export type { ForceDirectedGraphProps } from "./charts/network/ForceDirectedGraph";
+export type { SankeyDiagramProps } from "./charts/network/SankeyDiagram";
+export type { ChordDiagramProps } from "./charts/network/ChordDiagram";
+export type { TreeDiagramProps } from "./charts/network/TreeDiagram";
+export type { TreemapProps } from "./charts/network/Treemap";
+export type { CirclePackProps } from "./charts/network/CirclePack";
+export type { OrbitDiagramProps } from "./charts/network/OrbitDiagram";

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

@@ -23,3 +23,11 @@ export { LikertChart } from "./charts/ordinal/LikertChart";
 export { createHatchPattern } from "./charts/shared/hatchPattern";
 export type { HatchPatternOptions } from "./charts/shared/hatchPattern";
 export type { StreamOrdinalFrameProps, StreamOrdinalFrameHandle, OrdinalChartType, OrdinalScales, OrdinalSceneNode } from "./stream/ordinalTypes";
+export type { BarChartProps } from "./charts/ordinal/BarChart";
+export type { StackedBarChartProps } from "./charts/ordinal/StackedBarChart";
+export type { GroupedBarChartProps } from "./charts/ordinal/GroupedBarChart";
+export type { SwimlaneChartProps } from "./charts/ordinal/SwimlaneChart";
+export type { PieChartProps } from "./charts/ordinal/PieChart";
+export type { DonutChartProps } from "./charts/ordinal/DonutChart";
+export type { FunnelChartProps } from "./charts/ordinal/FunnelChart";
+export type { LikertChartProps } from "./charts/ordinal/LikertChart";

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

@@ -16,3 +16,12 @@ export { MinimapChart } from "./charts/xy/MinimapChart";
 export { QuadrantChart } from "./charts/xy/QuadrantChart";
 export { MultiAxisLineChart } from "./charts/xy/MultiAxisLineChart";
 export type { StreamXYFrameProps, StreamXYFrameHandle } from "./stream/types";
+export type { LineChartProps } from "./charts/xy/LineChart";
+export type { AreaChartProps } from "./charts/xy/AreaChart";
+export type { StackedAreaChartProps } from "./charts/xy/StackedAreaChart";
+export type { ScatterplotProps } from "./charts/xy/Scatterplot";
+export type { ConnectedScatterplotProps } from "./charts/xy/ConnectedScatterplot";
+export type { BubbleChartProps } from "./charts/xy/BubbleChart";
+export type { HeatmapProps } from "./charts/xy/Heatmap";
+export type { QuadrantChartProps } from "./charts/xy/QuadrantChart";
+export type { MultiAxisLineChartProps } from "./charts/xy/MultiAxisLineChart";

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

@@ -29,6 +29,7 @@ interface ThemeAwareProps {
     description?: string;
     background?: string;
     className?: string;
+    legendPosition?: "right" | "left" | "top" | "bottom";
     /** Prefix for SVG element IDs — used by renderDashboard to avoid collisions */
     _idPrefix?: string;
 }
@@ -38,7 +39,7 @@ export declare function renderOrdinalToStaticSVG(props: StreamOrdinalFrameProps
 export declare function renderNetworkToStaticSVG(props: StreamNetworkFrameProps & ThemeAwareProps): string;
 export declare function renderGeoToStaticSVG(props: StreamGeoFrameProps & ThemeAwareProps): string;
 /** Chart component name to frame type + props mapping */
-type ChartName = "LineChart" | "AreaChart" | "StackedAreaChart" | "Scatterplot" | "BubbleChart" | "ConnectedScatterplot" | "Heatmap" | "Sparkline" | "BarChart" | "StackedBarChart" | "GroupedBarChart" | "PieChart" | "DonutChart" | "SwimlaneChart" | "Histogram" | "BoxPlot" | "ViolinPlot" | "SwarmPlot" | "DotPlot" | "RidgelinePlot" | "FunnelChart" | "GaugeChart" | "ForceDirectedGraph" | "SankeyDiagram" | "ChordDiagram" | "TreeDiagram" | "Treemap" | "CirclePack" | "ChoroplethMap" | "ProportionalSymbolMap";
+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";
 interface RenderChartOptions {
     /** Output format — currently only "svg" is synchronous */
     format?: "svg";

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

@@ -0,0 +1,17 @@
+/**
+ * Chart-specific prop mapping for renderChart().
+ *
+ * Each entry maps HOC-level props (categoryAccessor, valueAccessor, etc.)
+ * to frame-level props (oAccessor, rAccessor, etc.) for server rendering.
+ *
+ * Extracted from renderToStaticSVG.tsx's 400-line switch statement to make
+ * each chart type independently readable and testable.
+ */
+type FrameType = "xy" | "ordinal" | "network" | "geo";
+interface ChartConfig {
+    frameType: FrameType;
+    /** Build frame props from HOC-level props */
+    buildProps: (data: any, colorBy: any, colorScheme: any, common: Record<string, any>, rest: Record<string, any>) => Record<string, any>;
+}
+export declare const CHART_CONFIGS: Record<string, ChartConfig>;
+export {};

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

@@ -32,4 +32,8 @@ export declare function themeStyles(theme: SemioticTheme): {
     labelSize: number;
     tickSize: number;
     categorical: string[];
+    annotation: string;
+    legendSize: number;
+    titleFontSize: number;
+    tickFontFamily: string;
 };

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

@@ -1,3 +1,5 @@
+/** Apply accessibility flags to a resolved theme. Shared by ThemeStore and server themeResolver. */
+export declare function applyThemeAccessibility(theme: SemioticTheme): SemioticTheme;
 export interface SemioticTheme {
     mode: "light" | "dark" | "auto";
     colors: {
@@ -16,12 +18,20 @@ export interface SemioticTheme {
         selection?: string;
         /** Opacity for non-selected (dimmed) elements, 0–1 */
         selectionOpacity?: number;
+        /** Default annotation text/marker color. Falls back to `text` if unset. */
+        annotation?: string;
     };
     typography: {
         fontFamily: string;
         titleSize: number;
         labelSize: number;
         tickSize: number;
+        /** Font size for legend text. Falls back to `labelSize` if unset. */
+        legendSize?: number;
+        /** Font family for axis tick labels. Use monospace for aligned numerics. Falls back to `fontFamily`. */
+        tickFontFamily?: string;
+        /** Font size for chart title. Falls back to `titleSize` if unset. */
+        titleFontSize?: number;
     };
     tooltip?: {
         background?: string;
@@ -31,6 +41,12 @@ export interface SemioticTheme {
         shadow?: string;
     };
     borderRadius?: string;
+    accessibility?: {
+        /** Auto-swap to color-blind safe palette when true */
+        colorBlindSafe?: boolean;
+        /** Enforce minimum 3:1 contrast ratios */
+        highContrast?: boolean;
+    };
 }
 /** Color-blind safe categorical palette (8 colors).
  *  Derived from Wong (2011) "Points of view: Color blindness" — safe for

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

@@ -13,11 +13,16 @@ export interface HitResult {
  * 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
+ * many points), point hit testing routes through `findHitPointInQuadtree`,
+ * which visits every candidate within the widened search radius (using
+ * `maxPointRadius` so variable-size points like BubbleChart can't hide
+ * behind a nearer non-hit). The visit is authoritative — when it returns
+ * null, no point hit exists and the linear point loop is skipped.
+ *
+ * Non-point node types (line, rect, area, heatcell, candlestick) still
  * use the linear scan.
  */
-export declare function findNearestNode(scene: SceneNode[], px: number, py: number, maxDistance?: number, pointQuadtree?: Quadtree<PointSceneNode> | null): HitResult | null;
+export declare function findNearestNode(scene: SceneNode[], px: number, py: number, maxDistance?: number, pointQuadtree?: Quadtree<PointSceneNode> | null, maxPointRadius?: number): HitResult | null;
 /**
  * Find all line/area nodes at a given X pixel coordinate.
  * For each node, interpolates the Y value at px using the path data.

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

@@ -32,6 +32,23 @@ export declare class DataSourceAdapter<T = Record<string, any>> {
      * animation frames (bounded: false so they append without clearing).
      */
     setBoundedData(data: T[]): void;
+    /**
+     * Replace the buffer contents without clearing category insertion-order
+     * memory. Intended for aggregator HOCs (e.g. LikertChart) that re-derive
+     * a full dataset from streaming input on every push — the transport is
+     * wholesale replacement, but the user perceives it as a live stream
+     * where categories should stay put across updates.
+     *
+     * Small datasets (≤ chunkThreshold) emit a single synchronous
+     * changeset — the common aggregator case. Larger datasets fall
+     * through to progressive chunking so an unexpectedly-huge replacement
+     * doesn't block the main thread. Only the first chunk carries
+     * `preserveCategoryOrder: true` (it's the one that resets the
+     * buffer and seeds the category Set); subsequent chunks are plain
+     * append-only streaming changesets, which preserve order anyway via
+     * the streaming-mode branch.
+     */
+    setReplacementData(data: T[]): void;
     /**
      * Flush all buffered push data as a single changeset.
      * Called automatically via microtask after push()/pushMany().

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

@@ -16,4 +16,4 @@ export interface GeoHitResult {
  * 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;
+export declare function findNearestGeoNode(nodes: GeoSceneNode[], mouseX: number, mouseY: number, maxDistance: number, hitCtx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, pointQuadtree?: Quadtree<PointSceneNode> | null, maxPointRadius?: number): GeoHitResult | null;

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

@@ -1,12 +1,18 @@
 import type { ZoomTransform } from "d3-zoom";
+import { type Quadtree } from "d3-quadtree";
 import type { GeoPipelineConfig, GeoScales, GeoSceneNode } from "./geoTypes";
-import type { StreamLayout } from "./types";
+import type { PointSceneNode, StreamLayout } from "./types";
 import type { ActiveTransition } from "./pipelineTransitionUtils";
 export declare class GeoPipelineStore {
     config: GeoPipelineConfig;
     scene: GeoSceneNode[];
     scales: GeoScales | null;
     version: number;
+    private static readonly QUADTREE_THRESHOLD;
+    private _quadtree;
+    /** Largest visual point radius in the current scene; used to widen quadtree
+     *  hit-test radius when points are larger than the default maxDistance. */
+    private _maxPointRadius;
     private projection;
     private geoPath;
     private baseScale;
@@ -28,6 +34,7 @@ export declare class GeoPipelineStore {
     private timestampBuffer;
     activeTransition: ActiveTransition | null;
     private prevPositions;
+    private _hasRenderedOnce;
     constructor(config: GeoPipelineConfig);
     updateConfig(config: Partial<GeoPipelineConfig>): void;
     setAreas(features: GeoJSON.Feature[]): void;
@@ -76,6 +83,17 @@ export declare class GeoPipelineStore {
         translate: [number, number];
     };
     getPoints(): Record<string, any>[];
+    /**
+     * Build (or clear) the quadtree spatial index for point scene nodes.
+     * Only built when the point count exceeds QUADTREE_THRESHOLD; below that
+     * a linear scan is faster than indexing overhead. Also tracks the largest
+     * point radius so the hit tester can widen its query when symbols are big.
+     */
+    private rebuildQuadtree;
+    /** Quadtree spatial index for point hit testing, or null when below threshold. */
+    get quadtree(): Quadtree<PointSceneNode> | null;
+    /** Largest visual point radius in the current scene. */
+    get maxPointRadius(): number;
     private buildSceneNodes;
     private applyCartogramTransform;
     private applyDecay;

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

@@ -22,6 +22,11 @@ export declare class NetworkPipelineStore {
     private config;
     private tensionConfig;
     transition: ActiveTransition | null;
+    private _hasRenderedOnce;
+    /** Snapshot of node positions from before bounded re-ingestion cleared the maps */
+    private _boundedPrevSnapshot;
+    /** Snapshot of edge positions from before bounded re-ingestion cleared the maps */
+    private _boundedEdgeSnapshot;
     lastIngestTime: number;
     private nodeTimestamps;
     private edgeTimestamps;
@@ -145,6 +150,12 @@ export declare class NetworkPipelineStore {
      * Handles parallel edges (multiple edges between the same pair).
      * Returns true if at least one edge was removed.
      */
-    removeEdge(sourceId: string, targetId: string): boolean;
+    /**
+     * Remove edges by source+target IDs, or by edge ID when edgeIdAccessor is configured.
+     *
+     * - `removeEdge(sourceId, targetId)` — removes all parallel edges between endpoints
+     * - `removeEdge(edgeId)` — removes the edge matching edgeIdAccessor (requires config.edgeIdAccessor)
+     */
+    removeEdge(sourceIdOrEdgeId: string, targetId?: string): boolean;
     clear(): void;
 }

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

@@ -1,4 +1,6 @@
 import type { OrdinalSceneNode } from "./ordinalTypes";
+import type { PointSceneNode } from "./types";
+import type { Quadtree } from "d3-quadtree";
 export interface OrdinalHitResult {
     datum: any;
     x: number;
@@ -7,4 +9,4 @@ export interface OrdinalHitResult {
     category?: string;
     stats?: import("./ordinalTypes").DistributionStats;
 }
-export declare function findNearestOrdinalNode(scene: OrdinalSceneNode[], px: number, py: number, maxDistance?: number): OrdinalHitResult | null;
+export declare function findNearestOrdinalNode(scene: OrdinalSceneNode[], px: number, py: number, maxDistance?: number, pointQuadtree?: Quadtree<PointSceneNode> | null, maxPointRadius?: number): OrdinalHitResult | null;

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

@@ -15,8 +15,9 @@
  * Consumed by: StreamOrdinalFrame (sole consumer).
  */
 import { type ScaleLinear } from "d3-scale";
+import { type Quadtree } from "d3-quadtree";
 import type { OrdinalPipelineConfig, OrdinalScales, OrdinalSceneNode, OrdinalColumn, OrdinalLayout } from "./ordinalTypes";
-import type { Changeset } from "./types";
+import type { Changeset, PointSceneNode } from "./types";
 import type { ActiveTransition } from "./pipelineTransitionUtils";
 export declare class OrdinalPipelineStore {
     private buffer;
@@ -52,6 +53,17 @@ export declare class OrdinalPipelineStore {
     scene: OrdinalSceneNode[];
     columns: Record<string, OrdinalColumn>;
     version: number;
+    /** Bumped whenever the buffer is mutated. Used to invalidate per-frame caches. */
+    private _dataVersion;
+    private static readonly QUADTREE_THRESHOLD;
+    private _pointQuadtree;
+    /** Largest visual point radius in the current scene. */
+    private _maxPointRadius;
+    /** Cached datum→index map for applyDecay/applyPulse. Keyed by `_dataVersion`. */
+    private _datumIndexCache;
+    /** Cached category→indices map for applyPulse wedge path. Keyed by `_dataVersion`. */
+    private _categoryIndexCache;
+    private _hasRenderedOnce;
     constructor(config: OrdinalPipelineConfig);
     ingest(changeset: Changeset): boolean;
     private pushValueExtent;
@@ -69,9 +81,34 @@ export declare class OrdinalPipelineStore {
     private getColorFromScheme;
     private resolveSummaryStyle;
     computeDecayOpacity(bufferIndex: number, bufferSize: number): number;
+    /**
+     * Build (or return cached) datum→buffer-index map. Cached against
+     * `_dataVersion` so the per-frame applyDecay/applyPulse calls don't
+     * rebuild it during animation when the buffer hasn't changed.
+     */
+    private getDatumIndexMap;
+    /**
+     * Build (or return cached) category→[indices] map used by applyPulse for
+     * wedge nodes. Cached against `_dataVersion` so the per-wedge inner loop
+     * collapses from O(data) to O(matches-for-this-category).
+     */
+    private getCategoryIndexMap;
+    /**
+     * Build (or clear) a quadtree spatial index for point scene nodes.
+     * Useful for swarm plots — other ordinal types (bar/wedge/box/violin) are
+     * not indexed because they're typically few in number or already O(1) hit
+     * tests via bbox checks.
+     */
+    private rebuildPointQuadtree;
+    /** Quadtree spatial index for point hit testing, or null when below threshold. */
+    get pointQuadtree(): Quadtree<PointSceneNode> | null;
+    /** Largest visual point radius in the current scene. */
+    get maxPointRadius(): number;
     private applyDecay;
     private applyPulse;
     get hasActivePulses(): boolean;
+    /** Synthesize a zero-state prevPositionMap for animated intro (first render). */
+    private synthesizeIntroPositions;
     /** Build a stable identity key for a scene node based on its content, not array index */
     private getNodeKey;
     private snapshotPositions;

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

@@ -4,10 +4,14 @@ import type { Particle, RealtimeEdge } from "./networkTypes";
  *
  * Pre-allocates a fixed-size array to avoid GC pressure.
  * Particles travel along bezier paths within link bands.
+ *
+ * `_freeIndices` is a stack of currently-free slot indices. Spawn pops; step
+ * pushes when a particle expires. This makes spawn O(1) instead of O(capacity).
  */
 export declare class ParticlePool {
     particles: Particle[];
     private capacity;
+    private _freeIndices;
     constructor(capacity: number);
     /**
      * Spawn a new particle on the given edge.

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

@@ -76,11 +76,15 @@ export interface PipelineConfig {
         strokeWidth?: number;
     };
     colorScheme?: string | string[];
+    /** Theme categorical palette — used as fallback when colorScheme is not an explicit array */
+    themeCategorical?: string[];
     barColors?: Record<string, string>;
     annotations?: Record<string, any>[];
     decay?: DecayConfig;
     pulse?: PulseConfig;
     transition?: TransitionConfig;
+    /** Whether to animate elements on first render (points scale up, lines/areas clip from left, rects grow from baseline) */
+    introAnimation?: boolean;
     staleness?: StalenessConfig;
     heatmapAggregation?: "count" | "sum" | "mean";
     heatmapXBins?: number;
@@ -111,6 +115,7 @@ export declare class PipelineStore {
     private getPointId;
     private timestampBuffer;
     activeTransition: ActiveTransition | null;
+    private _hasRenderedOnce;
     private prevPositionMap;
     /** Previous line/area path arrays for path interpolation */
     private prevPathMap;
@@ -140,6 +145,10 @@ export declare class PipelineStore {
     /** True when the x accessor returns Date objects (auto-detected on first data ingestion) */
     xIsDate: boolean;
     private _quadtree;
+    /** Largest visual point radius in the current scene. The hit tester uses
+     *  this to widen its quadtree query so points with big radii (bubble) don't
+     *  fall outside the search region. */
+    private _maxPointRadius;
     private static readonly QUADTREE_THRESHOLD;
     constructor(config: PipelineConfig);
     /**
@@ -161,6 +170,8 @@ export declare class PipelineStore {
      * Returns null when chart type is not scatter/bubble or point count is below threshold.
      */
     get quadtree(): Quadtree<PointSceneNode> | null;
+    /** Largest visual point radius in the current scene. */
+    get maxPointRadius(): number;
     /**
      * Remap existing scene node coordinates for a new layout size.
      * Proportionally scales all pixel coordinates without rebuilding from data.
@@ -174,13 +185,17 @@ export declare class PipelineStore {
     get hasActivePulses(): boolean;
     private get transitionContext();
     private snapshotPositions;
+    /** Synthesize a zero-state prevPositionMap/prevPathMap for animated intro (first render). */
+    private synthesizeIntroPositions;
     private startTransition;
     advanceTransition(now: number): boolean;
     private groupData;
     /**
      * Resolve a category→color map from data using the colorAccessor.
-     * Caches the result in _colorMapCache keyed by sorted category set —
-     * only rebuilds when the set of categories changes.
+     * Caches the result in _colorMapCache keyed by `_ingestVersion` (fast path)
+     * and a sorted-category fingerprint (so palette/scheme changes still
+     * invalidate). Multiple scene builders within one frame skip the data scan
+     * entirely after the first call.
      */
     private resolveColorMap;
     private resolveLineStyle;

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

@@ -1,4 +1,21 @@
 import * as React from "react";
 import type { StreamXYFrameProps, StreamXYFrameHandle } from "./types";
+/**
+ * Append a 2-char hex alpha to an existing CSS color, returning a valid
+ * CSS color string. The naive `${color}${alpha}` concatenation only works
+ * when `color` is a 6-char `#rrggbb`; shorthand `#rgb` produces the
+ * invalid 5-char `#rgbXX`, which `ctx.strokeStyle`/`fillStyle` silently
+ * rejects (falling back to `#000000` — black, invisible on dark themes).
+ * The /cookbook/marginal-graphics crosshair invisibility was caused
+ * precisely by `--semiotic-text-secondary: "#aaa"` hitting this path.
+ *
+ * Handles:
+ *   • 3-char hex (`#abc`) → expanded to 6-char then concatenated
+ *   • 6-char hex (`#aabbcc`) → concatenated directly
+ *   • `rgb(...)` → repacked as `rgba(..., a)` with numeric alpha
+ * Any other form (named colors, hsl(), oklch(), etc.) falls back to the
+ * raw color without alpha — degrades gracefully.
+ */
+export declare function withAlpha(color: string, alphaHex: string): string;
 declare const StreamXYFrame: React.ForwardRefExoticComponent<StreamXYFrameProps<Record<string, any>> & React.RefAttributes<StreamXYFrameHandle<Record<string, any>>>>;
 export default StreamXYFrame;

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

@@ -1,7 +1,8 @@
 import type { ReactNode } from "react";
 import type { GeoProjection, GeoPath, GeoPermissibleObjects } from "d3-geo";
 import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, PointSceneNode, LineSceneNode } from "./types";
-import type { HoverAnnotationConfig } from "../realtime/types";
+import type { AnimateProp } from "./pipelineTransitionUtils";
+import type { HoverAnnotationConfig, HoverData } from "../realtime/types";
 import type { GeoParticleStyle } from "./GeoParticlePool";
 export type ProjectionProp = GeoProjection | ProjectionName | ProjectionConfig;
 export type ProjectionName = "mercator" | "equalEarth" | "albersUsa" | "orthographic" | "naturalEarth" | "equirectangular";
@@ -75,6 +76,8 @@ export interface GeoPipelineConfig {
     decay?: DecayConfig;
     pulse?: PulseConfig;
     transition?: TransitionConfig;
+    /** Whether to animate elements on first render */
+    introAnimation?: boolean;
     annotations?: Record<string, any>[];
     pointIdAccessor?: string | ((d: any) => string);
 }
@@ -139,13 +142,17 @@ export interface StreamGeoFrameProps<T = Record<string, any>> {
     colorScheme?: string | string[];
     enableHover?: boolean;
     hoverAnnotation?: boolean | HoverAnnotationConfig;
-    tooltipContent?: (d: any) => ReactNode;
-    customClickBehavior?: (d: any) => void;
-    customHoverBehavior?: (d: any) => void;
+    tooltipContent?: (d: HoverData) => ReactNode;
+    customClickBehavior?: (d: HoverData | null) => void;
+    customHoverBehavior?: (d: HoverData | null) => void;
     annotations?: Record<string, any>[];
     decay?: DecayConfig;
     pulse?: PulseConfig;
     transition?: TransitionConfig;
+    /** Declarative animation: `true` for defaults (300ms ease-out), or config object.
+     *  When enabled, charts animate on first render (intro) and on data change.
+     *  Set `{ intro: false }` to disable the intro animation. */
+    animate?: AnimateProp;
     staleness?: StalenessConfig;
     backgroundGraphics?: ReactNode;
     foregroundGraphics?: ReactNode;

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

@@ -0,0 +1,34 @@
+/**
+ * Shared hover data utilities for stream frames.
+ *
+ * Centralizes the common HoverData construction pattern used by
+ * XY, Ordinal, and Network stream frames for hover and click events.
+ * Geo frame and keyboard navigation use variants with additional
+ * property flattening that are handled at the call site.
+ */
+import type { HoverData } from "../realtime/types";
+/**
+ * Minimal shape a Stream Frame's internal hover handler needs from a pointer
+ * event. React.MouseEvent satisfies this structurally, as does the plain
+ * `{clientX, clientY}` object the rAF-coalescing path synthesizes. Using this
+ * narrower type on `hoverHandlerRef` (instead of `React.MouseEvent`) prevents
+ * downstream code from reading event fields — `currentTarget`, `target`,
+ * `preventDefault` — that wouldn't survive the coalescing cast.
+ */
+export interface HoverPointerCoords {
+    clientX: number;
+    clientY: number;
+}
+/**
+ * Spread raw datum properties onto HoverData if it's a non-null,
+ * non-array object. Class instances (Date, etc.) are included —
+ * this matches the historical behavior where all datum fields are
+ * accessible directly on the hover object (d.fieldName).
+ */
+export declare function spreadDatum(rawDatum: any): Record<string, any>;
+/**
+ * Build a HoverData object from a raw datum and pixel coordinates.
+ * Spreads plain-object datum properties for backwards compatibility
+ * (consumers can access d.fieldName directly in addition to d.data.fieldName).
+ */
+export declare function buildHoverData(rawDatum: any, x: number, y: number, extra?: Partial<HoverData>): HoverData;