semiotic 3.3.1 → 3.4.1

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

@@ -1,6 +1,7 @@
 import type { Changeset } from "./types";
+import type { Datum } from "../charts/shared/datumTypes";
 export type ChangesetCallback<T> = (changeset: Changeset<T>) => void;
-export declare class DataSourceAdapter<T = Record<string, any>> {
+export declare class DataSourceAdapter<T = Datum> {
     private callback;
     private lastBoundedData;
     private chunkTimer;
@@ -32,6 +33,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/FocusRing.d.ts

@@ -1,4 +1,3 @@
-import * as React from "react";
 /**
  * Shape-appropriate keyboard focus indicator for canvas-based charts.
  *
@@ -30,4 +29,4 @@ export interface FocusRingProps {
     /** Height of rect-shaped focus target */
     height?: number;
 }
-export declare function FocusRing({ active, hoverPoint, margin, size, shape, width, height }: FocusRingProps): React.JSX.Element | null;
+export declare function FocusRing({ active, hoverPoint, margin, size, shape, width, height }: FocusRingProps): import("react/jsx-runtime").JSX.Element | null;

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/GeoParticlePool.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../charts/shared/datumTypes";
 /**
  * GeoParticlePool — particle system for geo line paths.
  *
@@ -20,7 +21,7 @@ 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);
+    color?: string | ((datum: Datum) => string);
     /** Particle opacity @default 0.7 */
     opacity?: number;
     /** Speed multiplier @default 1 */

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

@@ -1,12 +1,19 @@
 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";
+import type { Datum } from "../charts/shared/datumTypes";
 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,22 +35,23 @@ 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;
-    setPoints(data: Record<string, any>[]): void;
-    setLines(data: Record<string, any>[]): void;
+    setPoints(data: Datum[]): void;
+    setLines(data: Datum[]): void;
     /** Initialize streaming mode with a ring buffer */
     initStreaming(windowSize?: number): void;
     /** Push a single streaming point */
-    pushPoint(datum: Record<string, any>): void;
+    pushPoint(datum: Datum): void;
     /** Push multiple streaming points */
-    pushMany(data: Record<string, any>[]): void;
+    pushMany(data: Datum[]): void;
     /**
      * Remove points by ID. Requires pointIdAccessor to be configured.
      * Returns the removed items.
      */
-    removePoint(id: string | string[]): Record<string, any>[];
+    removePoint(id: string | string[]): Datum[];
     clear(): void;
     computeScene(layout: StreamLayout): void;
     private fitProjection;
@@ -75,7 +83,18 @@ export declare class GeoPipelineStore {
         scale: number;
         translate: [number, number];
     };
-    getPoints(): Record<string, any>[];
+    getPoints(): Datum[];
+    /**
+     * 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/MarginalGraphics.d.ts

@@ -1,4 +1,3 @@
-import * as React from "react";
 import type { ScaleLinear } from "d3-scale";
 import type { MarginalConfig, MarginalType } from "./types";
 export type MarginalOrient = "top" | "bottom" | "left" | "right";
@@ -16,4 +15,4 @@ export interface MarginalGraphicsProps {
 }
 /** Resolve a string shorthand or full config into a MarginalConfig */
 export declare function normalizeMarginalConfig(input: MarginalConfig | MarginalType): MarginalConfig;
-export declare function MarginalGraphics({ orient, config: rawConfig, values, scale, size, length }: MarginalGraphicsProps): React.JSX.Element | null;
+export declare function MarginalGraphics({ orient, config: rawConfig, values, scale, size, length }: MarginalGraphicsProps): import("react/jsx-runtime").JSX.Element | null;

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

@@ -1,6 +1,7 @@
 import { ParticlePool } from "./ParticlePool";
 import type { ActiveTransition } from "./pipelineTransitionUtils";
 import type { NetworkPipelineConfig, NetworkSceneNode, NetworkSceneEdge, NetworkLabel, RealtimeNode, RealtimeEdge, EdgePush } from "./networkTypes";
+import type { Datum } from "../charts/shared/datumTypes";
 /**
  * NetworkPipelineStore — stateful store for the StreamNetworkFrame.
  *
@@ -22,6 +23,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;
@@ -129,12 +135,12 @@ export declare class NetworkPipelineStore {
     /**
      * Update a node's data by ID. Returns the previous data, or null if not found.
      */
-    updateNode(id: string, updater: (data: Record<string, any>) => Record<string, any>): Record<string, any> | null;
+    updateNode(id: string, updater: (data: Datum) => Datum): Datum | null;
     /**
      * Update all edges between source and target. Handles parallel edges.
      * Returns array of previous data values (one per updated edge), or empty array.
      */
-    updateEdge(sourceId: string, targetId: string, updater: (data: Record<string, any>) => Record<string, any>): Record<string, any>[];
+    updateEdge(sourceId: string, targetId: string, updater: (data: Datum) => Datum): Datum[];
     /**
      * Remove a node by ID. Also removes all edges connected to this node.
      * Returns true if the node was found and removed.

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

@@ -1,4 +1,4 @@
-import * as React from "react";
+import type { Datum } from "../charts/shared/datumTypes";
 import type { ReactNode } from "react";
 import type { NetworkLabel } from "./networkTypes";
 import type { LegendGroup, GradientLegendConfig } from "../types/legendTypes";
@@ -47,8 +47,8 @@ export interface NetworkSVGOverlayProps {
         h?: number;
     }>;
     /** Annotations */
-    annotations?: Record<string, any>[];
-    svgAnnotationRules?: (annotation: Record<string, any>, index: number, context: any) => ReactNode;
+    annotations?: Datum[];
+    svgAnnotationRules?: (annotation: Datum, index: number, context: any) => ReactNode;
     annotationFrame?: number;
 }
 /**
@@ -57,7 +57,7 @@ export interface NetworkSVGOverlayProps {
  * Unlike XY/ordinal overlays, network charts don't have axes or grid lines.
  * The overlay is positioned absolutely over the canvas.
  */
-export declare function NetworkSVGOverlay(props: NetworkSVGOverlayProps): React.JSX.Element;
+export declare function NetworkSVGOverlay(props: NetworkSVGOverlayProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace NetworkSVGOverlay {
     var displayName: string;
 }

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

@@ -1,21 +1,3 @@
-/**
- * OrdinalBrushOverlay — d3-brush SVG overlay for ordinal frames.
- *
- * Renders a transparent SVG positioned above the canvas. Brushes along the
- * r-axis (value axis) only: horizontal projection → brushX, vertical → brushY.
- *
- * Key design decisions:
- *   - Outer SVG has pointerEvents:"none", inner brush-g has "all", so
- *     axes/legends rendered underneath remain clickable.
- *   - d3-brush lifecycle (useEffect) depends on [width, height, isHorizontal]
- *     only — NOT scales. Scales are read from a ref to avoid brush teardown
- *     mid-drag (scales change every render due to new object identity).
- *   - A separate useEffect repositions the brush when scales change (streaming).
- *
- * Consumed by: StreamOrdinalFrame (rendered when brush prop is set).
- * Wired by: useOrdinalBrush hook in HOC charts.
- */
-import * as React from "react";
 import type { OrdinalScales } from "./ordinalTypes";
 interface OrdinalBrushOverlayProps {
     width: number;
@@ -39,5 +21,5 @@ interface OrdinalBrushOverlayProps {
  * In horizontal projection, r maps to x-pixels → uses brushX.
  * In vertical projection, r maps to y-pixels → uses brushY.
  */
-export declare function OrdinalBrushOverlay({ width, height, totalWidth, totalHeight, margin, scales, onBrush }: OrdinalBrushOverlayProps): React.JSX.Element;
+export declare function OrdinalBrushOverlay({ width, height, totalWidth, totalHeight, margin, scales, onBrush }: OrdinalBrushOverlayProps): import("react/jsx-runtime").JSX.Element;
 export {};

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

@@ -1,3 +1,4 @@
+import type { Datum } from "../charts/shared/datumTypes";
 /**
  * OrdinalPipelineStore — stateful pipeline for ordinal chart data.
  *
@@ -15,8 +16,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 +54,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,28 +82,53 @@ 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;
     private startTransition;
     advanceTransition(now: number): boolean;
-    getData(): Record<string, any>[];
+    getData(): Datum[];
     /**
      * Remove data items by ID. Requires dataIdAccessor to be configured.
      * Returns the removed items. Marks the store dirty for scene rebuild.
      */
-    remove(id: string | string[]): Record<string, any>[];
+    remove(id: string | string[]): Datum[];
     /**
      * Update data items by ID. Requires dataIdAccessor.
      * Returns the previous values. Categories and extents are rebuilt.
      */
-    update(id: string | string[], updater: (d: Record<string, any>) => Record<string, any>): Record<string, any>[];
+    update(id: string | string[], updater: (d: Datum) => Datum): Datum[];
     clear(): void;
     get size(): number;
-    getOAccessor(): (d: any) => string;
-    getRAccessor(): (d: any) => number;
+    getOAccessor(): (d: Datum) => string;
+    getRAccessor(): (d: Datum) => number;
     updateConfig(config: Partial<OrdinalPipelineConfig>): void;
 }

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

@@ -1,3 +1,4 @@
+import type { Datum } from "../charts/shared/datumTypes";
 import * as React from "react";
 import type { OrdinalScales } from "./ordinalTypes";
 import type { AnnotationContext } from "../realtime/types";
@@ -42,12 +43,12 @@ interface OrdinalSVGOverlayProps {
     legendIsolatedCategories?: Set<string>;
     legendPosition?: "right" | "left" | "top" | "bottom";
     foregroundGraphics?: ReactNode;
-    annotations?: Record<string, any>[];
-    svgAnnotationRules?: (annotation: Record<string, any>, index: number, context: AnnotationContext) => ReactNode;
+    annotations?: Datum[];
+    svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     annotationFrame?: number;
     xAccessor?: string;
     yAccessor?: string;
-    annotationData?: Record<string, any>[];
+    annotationData?: Datum[];
     /** When true, grid lines and axis baselines are skipped (rendered by OrdinalSVGUnderlay instead) */
     underlayRendered?: boolean;
     children?: ReactNode;
@@ -69,6 +70,6 @@ interface OrdinalSVGUnderlayProps {
     rFormat?: (d: number) => string;
     rTickValues?: number[];
 }
-export declare function OrdinalSVGUnderlay(props: OrdinalSVGUnderlayProps): React.JSX.Element | null;
-export declare function OrdinalSVGOverlay(props: OrdinalSVGOverlayProps): React.JSX.Element | null;
+export declare function OrdinalSVGUnderlay(props: OrdinalSVGUnderlayProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function OrdinalSVGOverlay(props: OrdinalSVGOverlayProps): import("react/jsx-runtime").JSX.Element | null;
 export {};

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

@@ -1,6 +1,7 @@
+import type { Datum } from "../charts/shared/datumTypes";
 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 } from "./types";
+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";
 export interface PipelineConfig {
     chartType: StreamChartType;
@@ -12,14 +13,14 @@ export interface PipelineConfig {
     /** Pixel inset on scale ranges to prevent glyph clipping at chart edges. Default 0. */
     scalePadding?: number;
     maxCapacity?: number;
-    xAccessor?: string | ((d: any) => number);
-    yAccessor?: string | ((d: any) => number);
-    timeAccessor?: string | ((d: any) => number);
-    valueAccessor?: string | ((d: any) => number);
-    colorAccessor?: string | ((d: any) => string);
-    sizeAccessor?: string | ((d: any) => number);
-    groupAccessor?: string | ((d: any) => string);
-    categoryAccessor?: string | ((d: any) => string);
+    xAccessor?: string | ((d: Datum) => number);
+    yAccessor?: string | ((d: Datum) => number);
+    timeAccessor?: string | ((d: Datum) => number);
+    valueAccessor?: string | ((d: Datum) => number);
+    colorAccessor?: string | ((d: Datum) => string);
+    sizeAccessor?: string | ((d: Datum) => number);
+    groupAccessor?: string | ((d: Datum) => string);
+    categoryAccessor?: string | ((d: Datum) => string);
     lineDataAccessor?: string;
     xScaleType?: "linear" | "log" | "time";
     yScaleType?: "linear" | "log";
@@ -28,16 +29,16 @@ export interface PipelineConfig {
     sizeRange?: [number, number];
     binSize?: number;
     normalize?: boolean;
-    openAccessor?: string | ((d: any) => number);
-    highAccessor?: string | ((d: any) => number);
-    lowAccessor?: string | ((d: any) => number);
-    closeAccessor?: string | ((d: any) => number);
+    openAccessor?: string | ((d: Datum) => number);
+    highAccessor?: string | ((d: Datum) => number);
+    lowAccessor?: string | ((d: Datum) => number);
+    closeAccessor?: string | ((d: Datum) => number);
     candlestickStyle?: CandlestickStyle;
     /** Internal: set by PipelineStore when open/close accessors are both missing */
     candlestickRangeMode?: boolean;
-    boundsAccessor?: string | ((d: any) => number);
+    boundsAccessor?: string | ((d: Datum) => number);
     boundsStyle?: any;
-    y0Accessor?: string | ((d: any) => number);
+    y0Accessor?: string | ((d: Datum) => number);
     gradientFill?: {
         topOpacity: number;
         bottomOpacity: number;
@@ -55,10 +56,10 @@ export interface PipelineConfig {
         }>;
     };
     lineStyle?: any;
-    pointStyle?: (d: any) => Style & {
+    pointStyle?: (d: Datum) => Style & {
         r?: number;
     };
-    areaStyle?: (d: any) => Style;
+    areaStyle?: (d: Datum) => Style;
     swarmStyle?: {
         radius?: number;
         fill?: string;
@@ -76,18 +77,45 @@ export interface PipelineConfig {
         strokeWidth?: number;
     };
     colorScheme?: string | string[];
+    /** Theme categorical palette — used as fallback when colorScheme is not an explicit array */
+    themeCategorical?: string[];
+    /**
+     * Theme-resolved semantic role colors. Scene builders use these as the
+     * default before falling back to hardcoded hex. Populated by the Stream
+     * Frame from the in-memory `SemioticTheme.colors` object at render time
+     * — the values are concrete hex (or whatever the preset declares), not
+     * `var(...)` strings, and so this channel does NOT participate in the
+     * DOM CSS cascade. Changing the ambient theme (`<ThemeProvider>`) or
+     * swapping to a nested provider is how you override these values.
+     *
+     * Per-scope overrides via CSS custom properties
+     * (e.g. `<div style={{ "--semiotic-danger": "#c00" }}>`) work only for
+     * values a user explicitly passes through as `var(--...)` strings in
+     * chart props — those are resolved via `getComputedStyle` in the
+     * canvas renderer at paint time (see `resolveCSSColor.ts`). The theme
+     * defaults in this field don't read CSS.
+     */
+    themeSemantic?: ThemeSemanticColors;
+    /** Theme sequential scheme name (e.g. "blues") — fallback when `colorScheme` is not explicitly set for magnitude encodings (heatmap, choropleth, size). */
+    themeSequential?: string;
+    /** Theme diverging scheme name (e.g. "RdBu") — fallback when `colorScheme` is not explicitly set for midpoint encodings (likert, bivariate, ± deviation). */
+    themeDiverging?: string;
     barColors?: Record<string, string>;
-    annotations?: Record<string, any>[];
+    /** Histogram bar style — fill/stroke/strokeWidth/gap. Accepted by RealtimeHistogram and routed through to the bar scene builder. */
+    barStyle?: BarStyle;
+    annotations?: Datum[];
     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;
     heatmapYBins?: number;
     showValues?: boolean;
     heatmapValueFormat?: (v: number) => string;
-    pointIdAccessor?: string | ((d: any) => string);
+    pointIdAccessor?: string | ((d: Datum) => string);
     curve?: CurveType;
 }
 export declare class PipelineStore {
@@ -111,6 +139,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;
@@ -119,8 +148,15 @@ export declare class PipelineStore {
     lastIngestTime: number;
     /** Unified color map cache keyed by sorted category set — shared across point, swarm, etc. */
     private _colorMapCache;
-    /** Separate group→color map for resolveGroupColor (insertion-order based, never invalidates _colorMapCache) */
+    /** Separate group→color map for resolveGroupColor (insertion-order based, never invalidates _colorMapCache).
+     *  FIFO-bounded to `GROUP_COLOR_MAP_CAP` entries — in long-running streams with unique group IDs (e.g. UUIDs
+     *  as `lineBy` keys) this would otherwise grow unboundedly. Evicted groups that re-appear get a new palette
+     *  slot; stable color assignment is only guaranteed for the most-recent `CAP` unique groups. */
     private _groupColorMap;
+    /** Monotonic counter for group-color palette indexing. Decoupled from `_groupColorMap.size` so FIFO eviction
+     *  doesn't cause new groups to collide with existing entries on a shrunk map. */
+    private _groupColorCounter;
+    private static readonly GROUP_COLOR_MAP_CAP;
     private _barCategoryCache;
     /** Sorted bin boundary values from the last bar scene build (for data-driven brush snapping) */
     private _binBoundaries;
@@ -140,6 +176,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 +201,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,20 +216,28 @@ 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;
     private resolveAreaStyle;
     /** Resolve a group name to a color from the cached color map or a dedicated group palette.
      *  First checks _colorMapCache (populated by resolveColorMap when colorAccessor is set).
-     *  Falls back to _groupColorMap (insertion-order, never mutates _colorMapCache). */
+     *  Falls back to _groupColorMap (insertion-order, never mutates _colorMapCache).
+     *
+     *  FIFO-evicts the oldest entry when the map exceeds `GROUP_COLOR_MAP_CAP`. The palette index
+     *  uses `_groupColorCounter` (monotonic, decoupled from map size) so eviction doesn't cause
+     *  new groups to collide with existing entries on a shrunk map. */
     private resolveGroupColor;
     /**
      * Return a cached materialized array of the buffer contents.
@@ -196,18 +246,18 @@ export declare class PipelineStore {
      * transition ticks, hover redraws, and other non-data-changing renders.
      */
     private getBufferArray;
-    getData(): Record<string, any>[];
+    getData(): Datum[];
     /**
      * Remove data points by ID. Requires pointIdAccessor to be configured.
      * Returns the removed items. Marks the store dirty for scene rebuild.
      */
-    remove(id: string | string[]): Record<string, any>[];
+    remove(id: string | string[]): Datum[];
     /**
      * Update data points by ID. Requires pointIdAccessor.
      * The updater receives the current datum and returns the replacement.
      * Returns the previous values. Extents and scene are marked dirty.
      */
-    update(id: string | string[], updater: (d: Record<string, any>) => Record<string, any>): Record<string, any>[];
+    update(id: string | string[], updater: (d: Datum) => Datum): Datum[];
     /** Returns sorted bin boundary values from the last bar scene build. Persists until clear() or the next bar scene build. */
     getBinBoundaries(): number[];
     getExtents(): {
@@ -216,9 +266,9 @@ export declare class PipelineStore {
     } | null;
     clear(): void;
     get size(): number;
-    getBuffer(): RingBuffer<Record<string, any>>;
-    getXAccessor(): (d: any) => number;
-    getYAccessor(): (d: any) => number;
-    getCategoryAccessor(): ((d: any) => string) | undefined;
+    getBuffer(): RingBuffer<Datum>;
+    getXAccessor(): (d: Datum) => number;
+    getYAccessor(): (d: Datum) => number;
+    getCategoryAccessor(): ((d: Datum) => string) | undefined;
     updateConfig(config: Partial<PipelineConfig>): void;
 }