semiotic 3.7.5 → 3.8.1

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

@@ -16,17 +16,29 @@ import type { Datum } from "../charts/shared/datumTypes";
  * Consumed by: StreamOrdinalFrame (sole consumer).
  */
 import { type ScaleLinear } from "d3-scale";
-import { type Quadtree } from "d3-quadtree";
+import type { Quadtree } from "d3-quadtree";
 import type { OrdinalPipelineConfig, OrdinalScales, OrdinalSceneNode, OrdinalColumn, OrdinalLayout } from "./ordinalTypes";
 import type { Changeset, PointSceneNode } from "./types";
 import type { ActiveTransition } from "./pipelineTransitionUtils";
+import type { OrdinalLayoutResult } from "./ordinalCustomLayout";
 import type { CustomLayoutSelection } from "./customLayoutSelection";
-export declare class OrdinalPipelineStore {
+import { type CustomLayoutFailureDiagnostic } from "./customLayoutFailure";
+import { type UpdateResult, type UpdateResultStore } from "./pipelineUpdateStore";
+import { OrdinalPipelineUpdateResults } from "./ordinalPipelineUpdateResults";
+export declare class OrdinalPipelineStore implements UpdateResultStore {
+    getLastUpdateResult: () => UpdateResult;
+    getUpdateSnapshot: () => UpdateResult;
+    subscribeUpdateResult: (listener: () => void) => () => void;
+    setLayoutSelection: (selection: CustomLayoutSelection | null) => void;
+    markStylePaintPending: () => void;
+    consumeStylePaintPending: () => boolean;
     private buffer;
     private rExtent;
     /** Per-accessor extents for multiAxis mode */
     private rExtents;
     private config;
+    private windowSizeWarned;
+    protected updateResults: OrdinalPipelineUpdateResults;
     private getO;
     private getR;
     /** All resolved rAccessors (length > 1 when multiAxis) */
@@ -41,9 +53,7 @@ export declare class OrdinalPipelineStore {
     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 styleResolver;
     private timestampBuffer;
     activeTransition: ActiveTransition | null;
     private prevPositionMap;
@@ -57,6 +67,15 @@ export declare class OrdinalPipelineStore {
     columns: Record<string, OrdinalColumn>;
     /** Overlays returned from customLayout (consumed by StreamOrdinalFrame). */
     customLayoutOverlays: import("react").ReactNode;
+    /** Most recent custom layout result for host readback (`getCustomLayout()`).
+     *  Null before the first layout or without a custom layout. A failed rerun
+     *  keeps the last successful result while its scene remains recoverable. */
+    lastCustomLayoutResult: OrdinalLayoutResult | null;
+    /** Latest custom-layout failure for frame-handle readback. */
+    lastCustomLayoutFailure: CustomLayoutFailureDiagnostic | null;
+    /** Lets `computeScene` retain a prior scene without mutating it after an
+     * exception from `buildSceneNodes`. */
+    private _customLayoutFailedThisBuild;
     private _customLayoutDiagnosticsWarned;
     /** Per-frame restyle callback from the custom layout result (see OrdinalLayoutResult.restyle). */
     private _customRestyle;
@@ -67,7 +86,8 @@ export declare class OrdinalPipelineStore {
     version: number;
     /** Bumped whenever the buffer is mutated. Used to invalidate per-frame caches. */
     private _dataVersion;
-    private static readonly QUADTREE_THRESHOLD;
+    /** Materialized source data, cached for pulse/decay animation frames. */
+    private _bufferArrayCache;
     private _pointQuadtree;
     /** Largest visual point radius in the current scene. */
     private _maxPointRadius;
@@ -77,7 +97,16 @@ export declare class OrdinalPipelineStore {
     private _categoryIndexCache;
     private _hasRenderedOnce;
     constructor(config: OrdinalPipelineConfig);
+    /**
+     * Keep the optional pulse timestamp ring in lockstep with the datum ring.
+     * Enabling pulse after mount must seed timestamps for retained rows; an
+     * empty ring would associate later timestamps with the wrong datum index.
+     */
+    private syncPulseTimestampBuffer;
+    /** Keep ingest, pulse, staleness, and transition timestamps on one clock. */
+    private currentTime;
     ingest(changeset: Changeset): boolean;
+    ingestWithResult(changeset: Changeset): UpdateResult;
     private pushValueExtent;
     private evictValueExtent;
     /** For timeline type: resolve rAccessor as a [start, end] pair */
@@ -90,9 +119,6 @@ export declare class OrdinalPipelineStore {
     private getSceneContext;
     private buildSceneNodes;
     private buildLayoutContext;
-    private resolvePieceStyle;
-    private getColorFromScheme;
-    private resolveSummaryStyle;
     computeDecayOpacity(bufferIndex: number, bufferSize: number): number;
     /**
      * Build (or return cached) datum→buffer-index map. Cached against
@@ -119,6 +145,12 @@ export declare class OrdinalPipelineStore {
     get maxPointRadius(): number;
     private applyDecay;
     private applyPulse;
+    /**
+     * Refresh only pulse-derived fields on the existing scene. This deliberately
+     * avoids a scene/layout rebuild on every rAF pulse tick.
+     */
+    refreshPulse(now: number): boolean;
+    hasActivePulsesAt(now: number): boolean;
     get hasActivePulses(): boolean;
     /** Synthesize a zero-state prevPositionMap for animated intro (first render). */
     private synthesizeIntroPositions;
@@ -136,6 +168,12 @@ export declare class OrdinalPipelineStore {
      * after the server already painted the chart.
      */
     cancelIntroAnimation(): void;
+    /**
+     * Materialize the ring buffer at most once per data version. Pulse decay
+     * ticks reuse this array and the datum/category index caches rather than
+     * allocating a fresh copy at animation-frame frequency.
+     */
+    private getBufferArray;
     getData(): Datum[];
     /**
      * Remove data items by ID. Requires dataIdAccessor to be configured.
@@ -151,8 +189,6 @@ export declare class OrdinalPipelineStore {
     get size(): number;
     getOAccessor(): (d: Datum) => string;
     getRAccessor(): (d: Datum) => number;
-    /** Update the selection the layout reads at the next rebuild, without one. */
-    setLayoutSelection(selection: CustomLayoutSelection | null): void;
     private applyCustomRestyle;
     /**
      * Re-apply the custom layout's `restyle` to the existing scene for
@@ -160,5 +196,13 @@ export declare class OrdinalPipelineStore {
      * No-op when the layout supplied no `restyle`.
      */
     restyleScene(selection: CustomLayoutSelection | null): void;
+    /**
+     * Re-derive every retained fact that depends on the category/value
+     * accessors. `updateConfig` can change an accessor without a subsequent
+     * ingest (the normal React path), so clearing only a cache would leave the
+     * next scene with an empty/stale domain against the existing buffer.
+     */
+    private rebuildAccessorDerivedState;
     updateConfig(config: Partial<OrdinalPipelineConfig>): void;
+    updateConfigWithResult(config: Partial<OrdinalPipelineConfig>): UpdateResult;
 }

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

@@ -4,6 +4,8 @@ import type { OrdinalScales } from "./ordinalTypes";
 import type { AnnotationContext } from "../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/legendTypes";
+import type { OnObservationCallback } from "../store/ObservationStore";
+import { type OnAnnotationActivateCallback } from "../charts/shared/annotationActivation";
 import { type AutoPlaceAnnotations } from "../recipes/annotationLayout";
 import { type AxisExtentMode } from "../charts/shared/axisExtent";
 interface OrdinalSVGOverlayProps {
@@ -53,14 +55,20 @@ interface OrdinalSVGOverlayProps {
     legendLayout?: LegendLayout;
     foregroundGraphics?: ReactNode;
     annotations?: Datum[];
+    onAnnotationActivate?: OnAnnotationActivateCallback;
+    onObservation?: OnObservationCallback;
+    chartId?: string;
+    chartType?: string;
     autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     annotationFrame?: number;
     xAccessor?: string;
     yAccessor?: string;
     annotationData?: Datum[];
-    /** When true, grid lines and axis baselines are skipped (rendered by OrdinalSVGUnderlay instead) */
+    /** When true, grid lines and axis baselines are also rendered by OrdinalSVGUnderlay. */
     underlayRendered?: boolean;
+    /** Whether an opaque canvas hides the SVG underlay and needs an overlay copy. */
+    canvasObscuresUnderlay?: boolean;
     children?: ReactNode;
 }
 interface OrdinalSVGUnderlayProps {

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

@@ -0,0 +1,12 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { OrdinalPipelineConfig } from "./ordinalTypes";
+import type { Style } from "./types";
+/** Resolves ordinal mark styles while retaining stable category colors. */
+export declare class OrdinalStyleResolver {
+    private colorSchemeMap;
+    private colorSchemeIndex;
+    resetColors(): void;
+    resolvePieceStyle(config: OrdinalPipelineConfig, datum: Datum | null, category?: string): Style;
+    resolveSummaryStyle(config: OrdinalPipelineConfig, datum: Datum | null, category?: string): Style;
+    private getColorFromScheme;
+}

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

@@ -17,7 +17,7 @@ export declare class ParticlePool {
      * Spawn a new particle on the given edge.
      * Returns the particle if a free slot was found, null otherwise.
      */
-    spawn(edgeIndex: number): Particle | null;
+    spawn(edgeIndex: number, random?: () => number): Particle | null;
     /**
      * Advance all active particles by deltaTime.
      * Recycles particles that have completed their journey (t >= 1).

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

@@ -1,160 +1,50 @@
 import type { Datum } from "../charts/shared/datumTypes";
-import { type Quadtree } from "d3-quadtree";
+/**
+ * PipelineStore — stateful pipeline for XY/streaming chart data.
+ *
+ * Owns: data ingestion (RingBuffer), extent tracking, scale computation,
+ * scene layout delegation (via xySceneBuilders/), transition animation,
+ * decay/pulse/staleness encoding, and quadtree spatial indexing.
+ *
+ * Scene building was extracted to xySceneBuilders/ — this store constructs
+ * an XYSceneContext and dispatches to the appropriate builder function.
+ *
+ * Key dependencies:
+ *   xySceneBuilders/ — per-chartType scene layout (line, area, point, etc.)
+ *   SceneGraph        — node constructors (buildLineNode, buildPointNode, etc.)
+ *   RingBuffer         — sliding window data storage
+ *   IncrementalExtent  — O(1) min/max tracking
+ *
+ * Consumed by: StreamXYFrame (sole consumer).
+ */
 import { RingBuffer } from "../realtime/RingBuffer";
-import type { Changeset, StreamChartType, StreamScales, StreamLayout, SceneNode, PointSceneNode, CandlestickStyle, Style, ArrowOfTime, WindowMode, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, CurveType, BarStyle, ThemeSemanticColors, BandConfig } from "./types";
-import type { SymbolName } from "./symbolPath";
-import { type CoercibleNumber } from "./accessorUtils";
-import type { ActiveTransition } from "./pipelineTransitionUtils";
+import type { Changeset, StreamScales, StreamLayout, SceneNode } from "./types";
+import { type ActiveTransition } from "./pipelineTransitionUtils";
 import type { ResolvedRibbon } from "./xySceneBuilders/ribbonScene";
-import type { CustomLayout } from "./customLayout";
+import type { LayoutResult } from "./customLayout";
 import type { CustomLayoutSelection } from "./customLayoutSelection";
-import type { MarginType } from "../types/marginType";
-export interface PipelineConfig {
-    chartType: StreamChartType;
-    runtimeMode?: "streaming" | "bounded";
-    windowSize: number;
-    windowMode: WindowMode;
-    arrowOfTime: ArrowOfTime;
-    extentPadding: number;
-    /** Pixel inset on scale ranges to prevent glyph clipping at chart edges. Default 0. */
-    scalePadding?: number;
-    /** When `"exact"`, the x and y axis domains pin to the literal data
-     *  min/max — `extentPadding` is skipped so the first and last ticks
-     *  read as the actual data bounds. Default `"nice"` keeps the existing
-     *  padded domain so glyphs at the extremes don't clip the plot edge. */
-    axisExtent?: import("../charts/shared/axisExtent").AxisExtentMode;
-    maxCapacity?: number;
-    xAccessor?: string | ((d: Datum) => CoercibleNumber);
-    yAccessor?: string | ((d: Datum) => CoercibleNumber);
-    timeAccessor?: string | ((d: Datum) => CoercibleNumber);
-    valueAccessor?: string | ((d: Datum) => CoercibleNumber);
-    colorAccessor?: string | ((d: Datum) => string);
-    sizeAccessor?: string | ((d: Datum) => CoercibleNumber);
-    /** Categorical accessor → glyph shape (scatter/bubble). Emits SymbolSceneNodes. */
-    symbolAccessor?: string | ((d: Datum) => string);
-    /** Explicit `{category → shape}` map; unmapped categories auto-assign. */
-    symbolMap?: Record<string, SymbolName>;
-    groupAccessor?: string | ((d: Datum) => string);
-    categoryAccessor?: string | ((d: Datum) => string);
-    lineDataAccessor?: string;
-    xScaleType?: "linear" | "log" | "time";
-    yScaleType?: "linear" | "log";
-    xExtent?: [number | undefined, number | undefined] | [number];
-    yExtent?: [number | undefined, number | undefined] | [number];
-    sizeRange?: [number, number];
-    binSize?: number;
-    normalize?: boolean;
-    /** Stacked area baseline mode. Only consulted by stackedarea chart type. */
-    baseline?: "zero" | "wiggle" | "silhouette";
-    /** Stack order — see StreamXYFrameProps.stackOrder. */
-    stackOrder?: "key" | "insideOut" | "asc" | "desc";
-    openAccessor?: string | ((d: Datum) => CoercibleNumber);
-    highAccessor?: string | ((d: Datum) => CoercibleNumber);
-    lowAccessor?: string | ((d: Datum) => CoercibleNumber);
-    closeAccessor?: string | ((d: Datum) => CoercibleNumber);
-    candlestickStyle?: CandlestickStyle;
-    /** Internal: set by PipelineStore when open/close accessors are both missing */
-    candlestickRangeMode?: boolean;
-    boundsAccessor?: string | ((d: Datum) => CoercibleNumber);
-    boundsStyle?: any;
-    y0Accessor?: string | ((d: Datum) => CoercibleNumber);
-    band?: BandConfig | BandConfig[];
-    gradientFill?: {
-        topOpacity: number;
-        bottomOpacity: number;
-    } | {
-        colorStops: Array<{
-            offset: number;
-            color: string;
-        }>;
-    };
-    areaGroups?: Set<string>;
-    lineGradient?: {
-        colorStops: Array<{
-            offset: number;
-            color: string;
-        }>;
-    };
-    lineStyle?: any;
-    pointStyle?: (d: Datum) => Style & {
-        r?: number;
-    };
-    areaStyle?: (d: Datum) => Style;
-    swarmStyle?: {
-        radius?: number;
-        fill?: string;
-        opacity?: number;
-        stroke?: string;
-        strokeWidth?: number;
-    };
-    waterfallStyle?: {
-        positiveColor?: string;
-        negativeColor?: string;
-        connectorStroke?: string;
-        connectorWidth?: number;
-        gap?: number;
-        stroke?: string;
-        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>;
-    /** 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: Datum) => string);
-    curve?: CurveType;
-    /** When provided, replaces chart-type dispatch in scene building.
-     *  Receives a LayoutContext (scales, dimensions, theme, resolveColor)
-     *  and returns scene nodes plus optional overlays. */
-    customLayout?: CustomLayout;
-    /** User-supplied config blob threaded through to LayoutContext.config. */
-    layoutConfig?: object;
-    /** Resolved margin — passed through so LayoutContext.dimensions.margin reflects what the frame actually used. */
-    layoutMargin?: MarginType;
-    /** Resolved shared selection projected into LayoutContext.selection. Owned by
-     *  a dedicated frame effect (kept off the rebuild-triggering path). */
-    layoutSelection?: CustomLayoutSelection | null;
-}
-export declare class PipelineStore {
+import { type CustomLayoutFailureDiagnostic } from "./customLayoutFailure";
+import { type PipelineConfig } from "./pipelineConfig";
+import type { UpdateResult } from "./pipelineUpdateContract";
+import { type UpdateResultStore } from "./pipelineUpdateStore";
+import { PipelineStoreUpdateResults } from "./pipelineStoreUpdateResults";
+export type { PipelineConfig } from "./pipelineConfig";
+export type { ChangeSet, Invalidation, RevisionSet, UpdateResult, } from "./pipelineUpdateContract";
+export { DEFAULT_GROWING_MAX_CAPACITY, GROWING_CAPACITY_WARN_THRESHOLD } from "./pipelineConfig";
+export declare class PipelineStore implements UpdateResultStore {
+    getLastUpdateResult: () => UpdateResult;
+    getUpdateSnapshot: () => UpdateResult;
+    subscribeUpdateResult: (listener: () => void) => () => void;
+    setLayoutSelection: (selection: CustomLayoutSelection | null) => void;
+    markStylePaintPending: () => void;
+    consumeStylePaintPending: () => boolean;
     private buffer;
     private xExtent;
     private yExtent;
     private config;
     private growingCap;
+    private growingCapacityWarned;
+    private windowSizeWarned;
     private getX;
     private getY;
     private getGroup;
@@ -182,6 +72,8 @@ export declare class PipelineStore {
     /** Exit nodes awaiting fade-out removal */
     exitNodes: SceneNode[];
     lastIngestTime: number;
+    /** Keep ingest, pulse, staleness, and transition timestamps on one clock. */
+    private currentTime;
     /** Unified color map cache keyed by sorted category set — shared across point, swarm, etc. */
     private _colorMapCache;
     /** groupData() result cache. The line/area/stacked-area builders all re-bucket
@@ -206,17 +98,32 @@ export declare class PipelineStore {
     private _stackExtentCache;
     /** Monotonic counter incremented on each ingest — used as part of cache keys */
     private _ingestVersion;
+    /** Datum→index map for decay/pulse, cached by `_ingestVersion`. */
+    private _datumIndexCache;
     /** Cached materialized array from buffer.toArray() — only rebuilt when buffer changes */
     private _bufferArrayCache;
     /** True when the buffer has been mutated since last toArray() call */
     private _bufferDirty;
     private needsFullRebuild;
     private lastLayout;
+    protected updateResults: PipelineStoreUpdateResults;
     scales: StreamScales | null;
     scene: SceneNode[];
     version: number;
     /** Overlays returned from customLayout (consumed by StreamXYFrame for SVGOverlay). */
     customLayoutOverlays: import("react").ReactNode;
+    /** The most recent custom layout result, exposed for host readback via the
+     *  frame handle's `getCustomLayout()` — so a page that needs the computed
+     *  placement (stats, inspectors) doesn't re-run the layout. Null before the
+     *  first layout or when no custom layout is set. A rerun failure preserves
+     *  this last successful result when it is safe to do so. */
+    lastCustomLayoutResult: LayoutResult | null;
+    /** Latest custom-layout failure for frame-handle readback. */
+    lastCustomLayoutFailure: CustomLayoutFailureDiagnostic | null;
+    /** Set only while `buildSceneNodes` is recovering from a layout exception.
+     * `computeScene` uses it to retain the previous scene/scales without applying
+     * a new transition, pulse, or decay pass to that retained output. */
+    private _customLayoutFailedThisBuild;
     private _customLayoutDiagnosticsWarned;
     /** Per-frame restyle callback from the custom layout result (see LayoutResult.restyle). */
     private _customRestyle;
@@ -226,14 +133,23 @@ export declare class PipelineStore {
     private _baseStyles;
     /** 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;
+    private spatialIndex;
     constructor(config: PipelineConfig);
+    /**
+     * Keep pulse timestamps structurally coupled to the datum ring when pulse
+     * is changed after construction. A fresh timestamp ring must be seeded for
+     * already-retained data; otherwise the next push would be timestamp index 0
+     * while its datum is at the end of the data ring.
+     */
+    private syncPulseTimestampBuffer;
     private pushDatumYExtent;
+    /**
+     * Remove every y-domain contribution made by {@link pushDatumYExtent}.
+     * Keeping these paths paired is important: a ribbon/band can extend the
+     * visible domain beyond the point itself, so removing or replacing that
+     * datum must evict its envelope extrema too.
+     */
+    private evictDatumYExtent;
     private rebuildYExtent;
     private rebuildExtents;
     private _lastBoundedInsertsRef;
@@ -250,20 +166,14 @@ export declare class PipelineStore {
      * meaningful — streaming consumers don't pass the same array twice.
      */
     ingest(changeset: Changeset): boolean;
+    /** Additive explicit-result form of {@link ingest}; `ingest()` remains unchanged. */
+    ingestWithResult(changeset: Changeset): UpdateResult;
     /**
      * Recompute scales and scene graph for the current buffer contents.
      */
     computeScene(layout: StreamLayout): void;
-    /**
-     * Build or clear the quadtree spatial index for point scene nodes.
-     * Only built for scatter/bubble charts with >QUADTREE_THRESHOLD points.
-     */
-    private rebuildQuadtree;
-    /**
-     * Get the quadtree spatial index, if available.
-     * Returns null when chart type is not scatter/bubble or point count is below threshold.
-     */
-    get quadtree(): Quadtree<PointSceneNode> | null;
+    /** Get the retained point-scene spatial index, if available. */
+    get quadtree(): import("d3-quadtree").Quadtree<import("./types").PointSceneNode> | null;
     /** Largest visual point radius in the current scene. */
     get maxPointRadius(): number;
     /**
@@ -274,8 +184,12 @@ export declare class PipelineStore {
     private buildSceneNodes;
     private resolveBoundsStyle;
     computeDecayOpacity(bufferIndex: number, bufferSize: number): number;
+    private getDatumIndexMap;
     private applyDecay;
     private applyPulse;
+    /** Refresh pulse fields without rebuilding layout; retained custom scenes stay immutable. */
+    refreshPulse(now: number): boolean;
+    hasActivePulsesAt(now: number): boolean;
     get hasActivePulses(): boolean;
     private get transitionContext();
     private snapshotPositions;
@@ -317,13 +231,6 @@ export declare class PipelineStore {
     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).
-     *
-     *  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.
@@ -356,15 +263,15 @@ export declare class PipelineStore {
     getXAccessor(): (d: Datum) => number;
     getYAccessor(): (d: Datum) => number;
     getCategoryAccessor(): ((d: Datum) => string) | undefined;
-    /** Update the selection the layout reads at the next rebuild, without
-     *  triggering one. The frame then either repaints (restyle) or rebuilds. */
-    setLayoutSelection(selection: CustomLayoutSelection | null): void;
     private applyCustomRestyle;
     /**
      * Re-apply the custom layout's `restyle` to the existing scene for
      * `selection`, off each node's base style — no relayout, no quadtree rebuild
      * (positions are unchanged). No-op when the layout supplied no `restyle`.
+     * Flags a style-only repaint so the render loop redraws the mutated styles.
      */
     restyleScene(selection: CustomLayoutSelection | null): void;
     updateConfig(config: Partial<PipelineConfig>): void;
+    /** Additive explicit-result form of {@link updateConfig}. */
+    updateConfigWithResult(config: Partial<PipelineConfig>): UpdateResult;
 }

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

@@ -5,6 +5,8 @@ import type { AnnotationContext } from "../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/legendTypes";
 import { type AutoPlaceAnnotations } from "../recipes/annotationLayout";
+import type { OnObservationCallback } from "../store/ObservationStore";
+import { type OnAnnotationActivateCallback } from "../charts/shared/annotationActivation";
 export type AxisConfig = XYFrameAxisConfig;
 interface SVGOverlayProps {
     width: number;
@@ -59,6 +61,10 @@ interface SVGOverlayProps {
     xValues?: number[];
     yValues?: number[];
     annotations?: Datum[];
+    onAnnotationActivate?: OnAnnotationActivateCallback;
+    onObservation?: OnObservationCallback;
+    chartId?: string;
+    chartType?: string;
     autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     annotationFrame?: number;

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

@@ -1,11 +1,11 @@
-import type { SceneNode, LineSceneNode, AreaSceneNode, PointSceneNode, SymbolSceneNode, RectSceneNode, HeatcellSceneNode, Style, StreamScales, CurveType } from "./types";
+import type { SceneNode, SceneDatum, LineSceneNode, AreaSceneNode, PointSceneNode, SymbolSceneNode, RectSceneNode, HeatcellSceneNode, Style, StreamScales, CurveType } from "./types";
 import type { SymbolName } from "./symbolPath";
 import type { Datum } from "../charts/shared/datumTypes";
 export declare function buildLineNode(data: Datum[], scales: StreamScales, xGet: (d: Datum) => number, yGet: (d: Datum) => number, style: Style, group?: string): LineSceneNode;
 export declare function buildAreaNode(data: Datum[], scales: StreamScales, xGet: (d: Datum) => number, yGet: (d: Datum) => number, baselineY: number, style: Style, group?: string, y0Get?: (d: Datum) => number): AreaSceneNode;
 /** Per-group-per-x stacked top values, keyed by group then x */
 export type StackedTops = Map<string, Map<number, number>>;
-export type StackBaseline = "zero" | "wiggle" | "silhouette";
+export type StackBaseline = "zero" | "wiggle" | "silhouette" | "diverging";
 /**
  * Compute per-x stack baseline offsets. Shared between scene rendering
  * (`buildStackedAreaNodes`) and extent computation (`PipelineStore`) so
@@ -17,8 +17,16 @@ export type StackBaseline = "zero" | "wiggle" | "silhouette";
  *   xValues   — sorted unique x values
  *   groupKeys — group keys in stacking order (same order both callers use)
  *   valueAt   — (groupKey, x) → group's value at x (0 if absent)
+ *
+ * `"diverging"` returns zero offsets — positives and negatives stack from
+ * y=0 independently inside {@link buildStackedAreaNodes}.
  */
 export declare function computeStackOffsets(xValues: number[], groupKeys: string[], valueAt: (groupKey: string, x: number) => number, baseline: StackBaseline): Map<number, number>;
+/**
+ * Diverging stack extent: positives accumulate above 0, negatives below.
+ * Shared by PipelineStore auto-extent and any host that needs matching bounds.
+ */
+export declare function computeDivergingStackExtent(xValues: number[], groupKeys: string[], valueAt: (groupKey: string, x: number) => number): [number, number];
 export declare function buildStackedAreaNodes(groups: {
     key: string;
     data: Datum[];
@@ -30,8 +38,8 @@ export declare function buildPointNode(datum: Datum, scales: StreamScales, xGet:
 /** Build a {@link SymbolSceneNode} — the glyph sibling of {@link buildPointNode}.
  *  `size` is the d3-symbol area (px²); convert from a target radius with πr². */
 export declare function buildSymbolNode(datum: Datum, scales: StreamScales, xGet: (d: Datum) => number, yGet: (d: Datum) => number, size: number, symbolType: SymbolName, style: Style, pointId?: string): SymbolSceneNode | null;
-export declare function buildRectNode(x: number, y: number, w: number, h: number, style: Style, datum: any, group?: string): RectSceneNode;
-export declare function buildHeatcellNode(x: number, y: number, w: number, h: number, fill: string, datum: any, options?: {
+export declare function buildRectNode(x: number, y: number, w: number, h: number, style: Style, datum: SceneDatum, group?: string): RectSceneNode;
+export declare function buildHeatcellNode(x: number, y: number, w: number, h: number, fill: string, datum: Datum, options?: {
     value?: number;
     showValues?: boolean;
     valueFormat?: (v: number) => string;

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

@@ -1,5 +1,5 @@
 import type { Datum } from "../charts/shared/datumTypes";
 import * as React from "react";
 import type { StreamGeoFrameProps, StreamGeoFrameHandle } from "./geoTypes";
-declare const StreamGeoFrame: React.ForwardRefExoticComponent<StreamGeoFrameProps<Datum> & React.RefAttributes<StreamGeoFrameHandle>>;
+declare const StreamGeoFrame: React.NamedExoticComponent<StreamGeoFrameProps<Datum> & React.RefAttributes<StreamGeoFrameHandle>>;
 export default StreamGeoFrame;

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

@@ -1,5 +1,5 @@
 import type { Datum } from "../charts/shared/datumTypes";
 import * as React from "react";
 import type { StreamNetworkFrameProps, StreamNetworkFrameHandle } from "./networkTypes";
-declare const StreamNetworkFrame: React.ForwardRefExoticComponent<StreamNetworkFrameProps<Datum> & React.RefAttributes<StreamNetworkFrameHandle>>;
+declare const StreamNetworkFrame: React.NamedExoticComponent<StreamNetworkFrameProps<Datum> & React.RefAttributes<StreamNetworkFrameHandle>>;
 export default StreamNetworkFrame;

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

@@ -1,5 +1,5 @@
 import type { Datum } from "../charts/shared/datumTypes";
 import * as React from "react";
 import type { StreamOrdinalFrameProps, StreamOrdinalFrameHandle } from "./ordinalTypes";
-declare const StreamOrdinalFrame: React.ForwardRefExoticComponent<StreamOrdinalFrameProps<Datum> & React.RefAttributes<StreamOrdinalFrameHandle<Datum>>>;
+declare const StreamOrdinalFrame: React.NamedExoticComponent<StreamOrdinalFrameProps<Datum> & React.RefAttributes<StreamOrdinalFrameHandle<Datum>>>;
 export default StreamOrdinalFrame;

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

@@ -1,22 +1,6 @@
 import type { Datum } from "../charts/shared/datumTypes";
 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<Datum> & React.RefAttributes<StreamXYFrameHandle<Datum>>>;
+export { withAlpha } from "./frameThemeColors";
+declare const StreamXYFrame: React.NamedExoticComponent<StreamXYFrameProps<Datum> & React.RefAttributes<StreamXYFrameHandle<Datum>>>;
 export default StreamXYFrame;