semiotic 3.8.0 → 3.8.1

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

@@ -5,7 +5,7 @@ import type { StreamNetworkFrameProps, RealtimeEdge } from "../stream/networkTyp
 import type { StreamOrdinalFrameProps } from "../stream/ordinalTypes";
 import type { StreamGeoFrameProps } from "../stream/geoTypes";
 import type { PhysicsSettledSVGOptions } from "../stream/physics/PhysicsSettledSVG";
-import type { PhysicsPipelineStore } from "../stream/physics/PhysicsPipelineStore";
+import type { PhysicsPipelineStore, PhysicsQueuedSpawn } from "../stream/physics/PhysicsPipelineStore";
 import type { OrdinalPipelineStore } from "../stream/OrdinalPipelineStore";
 import type { RenderEvidence } from "./renderEvidence";
 import { resolveTheme, type ThemeInput } from "./themeResolver";
@@ -14,7 +14,7 @@ import * as React from "react";
 export type FrameType = RenderEvidence["frameType"];
 export type StaticPhysicsFrameProps = PhysicsSettledSVGOptions & {
     config?: ConstructorParameters<typeof PhysicsPipelineStore>[0];
-    initialSpawns?: Array<Record<string, unknown>>;
+    initialSpawns?: PhysicsQueuedSpawn[];
     projectionRows?: PhysicsSettledSVGOptions["projectionRows"];
     size?: [number, number];
     _idPrefix?: string;

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

@@ -6,6 +6,8 @@ interface ObservationBase {
     chartType: string;
     chartId?: string;
 }
+/** Input channel that produced a semantic chart interaction. */
+export type ObservationInputType = "keyboard" | "pointer" | "touch" | "navigation-tree";
 export interface HoverObservation extends ObservationBase {
     type: "hover";
     datum: Datum;
@@ -47,6 +49,24 @@ export interface ClickObservation extends ObservationBase {
 export interface ClickEndObservation extends ObservationBase {
     type: "click-end";
 }
+/** A datum became the reader's active focus target. */
+export interface FocusObservation extends ObservationBase {
+    type: "focus";
+    datum: Datum;
+    inputType: Exclude<ObservationInputType, "touch">;
+}
+/** A datum was deliberately activated, independent of input modality. */
+export interface ActivateObservation extends ObservationBase {
+    type: "activate";
+    datum: Datum;
+    inputType: ObservationInputType;
+}
+/** A stable, interactive annotation was deliberately activated. */
+export interface AnnotationActivateObservation extends ObservationBase {
+    type: "annotation-activate";
+    annotationId: string;
+    inputType: ObservationInputType;
+}
 /**
  * Emitted when an event-time stream receives a record outside its
  * lateness/grace window (see `ReorderBuffer`). Surfaces lateness as an
@@ -66,7 +86,7 @@ export interface LateDataObservation extends ObservationBase {
     /** Running total of late events seen on this chart. */
     lateCount: number;
 }
-export type ChartObservation = HoverObservation | HoverEndObservation | BrushObservation | BrushEndObservation | SelectionObservation | SelectionEndObservation | ClickObservation | ClickEndObservation | ControlObservation | LateDataObservation;
+export type ChartObservation = HoverObservation | HoverEndObservation | BrushObservation | BrushEndObservation | SelectionObservation | SelectionEndObservation | ClickObservation | ClickEndObservation | FocusObservation | ActivateObservation | AnnotationActivateObservation | ControlObservation | LateDataObservation;
 export type OnObservationCallback = (observation: ChartObservation) => void;
 export interface ObservationStoreState {
     /** Ring buffer of recent observations (newest last). Mutated in place for perf. */

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

@@ -1,8 +1,9 @@
 import * as React from "react";
+import type { Datum } from "../charts/shared/datumTypes";
 import { type AccessibleSceneNode as AnySceneNode } from "./accessibleDataRows";
 export { extractAllRows } from "./accessibleDataRows";
 export type { DataRow } from "./accessibleDataRows";
-declare const SR_ONLY_STYLE: React.CSSProperties;
+export { AriaLiveTooltip, SR_ONLY_STYLE } from "./AriaLiveTooltip";
 /**
  * Compute an aria-label describing the chart type and data shape from the scene graph.
  */
@@ -28,7 +29,7 @@ interface AccessibleDataTableProps {
 export declare function AccessibleDataTable({ scene, chartType, tableId, chartTitle }: AccessibleDataTableProps): React.JSX.Element | null;
 interface NetworkAccessibleDataTableProps {
     nodes: Array<{
-        datum?: any;
+        datum?: Datum | null;
         id?: string;
         cx?: number;
         cy?: number;
@@ -36,7 +37,7 @@ interface NetworkAccessibleDataTableProps {
         y?: number;
     }>;
     edges: Array<{
-        datum?: any;
+        datum?: Datum | null;
         source?: string;
         target?: string;
     }>;
@@ -62,10 +63,3 @@ export declare function ScreenReaderSummary({ summary }: {
 export declare function SkipToTableLink({ tableId }: {
     tableId: string;
 }): React.JSX.Element;
-/**
- * Visually-hidden aria-live region that mirrors tooltip text for screen readers.
- */
-export declare function AriaLiveTooltip({ hoverPoint }: {
-    hoverPoint: any;
-}): React.JSX.Element;
-export { SR_ONLY_STYLE };

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

@@ -0,0 +1,9 @@
+import * as React from "react";
+import type { HoverData } from "../realtime/types";
+export declare const SR_ONLY_STYLE: React.CSSProperties;
+/** Visually-hidden aria-live region that mirrors tooltip text for screen readers. */
+export declare function AriaLiveTooltip({ hoverPoint }: {
+    hoverPoint: Pick<HoverData, "data"> | {
+        data: object;
+    } | null;
+}): React.JSX.Element;

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

@@ -1,17 +1,17 @@
-import type { SceneNode, PointSceneNode } from "./types";
+import type { SceneNode, SceneDatum, PointSceneNode } from "./types";
+import type { Datum } from "../charts/shared/datumTypes";
 import type { RingBuffer } from "../realtime/RingBuffer";
 import type { Quadtree } from "d3-quadtree";
-import type { Datum } from "../charts/shared/datumTypes";
 export interface HitResult {
     node: SceneNode;
-    datum: any;
+    datum: SceneDatum;
     x: number;
     y: number;
     distance: number;
 }
 export interface XHitResult {
     node: SceneNode;
-    datum: any;
+    datum: SceneDatum;
     x: number;
     y: number;
     y0?: number;

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

@@ -1,7 +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 = Datum> {
+export declare class DataSourceAdapter<T extends object = Datum> {
     private callback;
     private lastBoundedData;
     private chunkTimer;

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

@@ -0,0 +1,57 @@
+/**
+ * Shared timing and randomness policy for frame hosts.
+ *
+ * A runtime converts a wall clock into logical frame time. Logical time moves
+ * forward only while the frame is active, so a paused or hidden chart resumes
+ * from its previous animation state instead of fast-forwarding through the
+ * elapsed wall-clock interval.
+ */
+export type FrameClock = () => number;
+export type FrameRandom = () => number;
+export interface FrameRuntimeOptions {
+    /** Monotonic wall-clock milliseconds. Defaults to performance.now/Date.now. */
+    clock?: FrameClock;
+    /** Injectable random source for tests or an embedding runtime. */
+    random?: FrameRandom;
+    /** Serializable deterministic random seed. Ignored when `random` is provided. */
+    seed?: number;
+    paused?: boolean;
+    visible?: boolean;
+}
+export interface FrameRuntimeSnapshot {
+    now: number;
+    paused: boolean;
+    seed?: number;
+    visible: boolean;
+}
+/** Mulberry32 is small, deterministic, and accepts the serializable integer seed surface. */
+export declare function createSeededFrameRandom(seed: number): FrameRandom;
+export declare class FrameRuntime {
+    private clock;
+    private lastWallTime;
+    private logicalTime;
+    private randomInput;
+    private randomSource;
+    private seedValue;
+    private pausedValue;
+    private subscribers;
+    private visibleValue;
+    /** Stable callable seam for stores and render loops. */
+    readonly now: () => number;
+    /** Stable callable seam for stochastic renderers. */
+    readonly random: () => number;
+    constructor(options?: FrameRuntimeOptions);
+    get isActive(): boolean;
+    get paused(): boolean;
+    get seed(): number | undefined;
+    get visible(): boolean;
+    configure(options: Pick<FrameRuntimeOptions, "clock" | "random" | "seed">): void;
+    setPaused(paused: boolean): void;
+    setVisible(visible: boolean): void;
+    snapshot(): FrameRuntimeSnapshot;
+    subscribe(listener: () => void): () => void;
+    private advance;
+    private emit;
+    private setClock;
+    private setRandomSource;
+}

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

@@ -35,7 +35,7 @@ export declare class GeoParticlePool {
     particles: GeoParticle[];
     private capacity;
     constructor(capacity: number);
-    spawn(lineIndex: number): GeoParticle | null;
+    spawn(lineIndex: number, random?: () => number): GeoParticle | null;
     /**
      * Advance all active particles.
      * @param paths - array of polyline paths, one per line index

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

@@ -7,8 +7,17 @@ import type { Datum } from "../charts/shared/datumTypes";
 import type { GeoLayoutResult } from "./geoCustomLayout";
 import type { CustomLayoutSelection } from "./customLayoutSelection";
 import { type CustomLayoutFailureDiagnostic } from "./customLayoutFailure";
-export declare class GeoPipelineStore {
+import { GeoPipelineUpdateResults } from "./geoPipelineUpdateResults";
+import { type UpdateResult, type UpdateResultStore } from "./pipelineUpdateStore";
+export declare class GeoPipelineStore implements UpdateResultStore {
+    getLastUpdateResult: () => UpdateResult;
+    getUpdateSnapshot: () => UpdateResult;
+    subscribeUpdateResult: (listener: () => void) => () => void;
+    setLayoutSelection: (selection: CustomLayoutSelection | null) => void;
+    markStylePaintPending: () => void;
+    consumeStylePaintPending: () => boolean;
     config: GeoPipelineConfig;
+    protected updateResults: GeoPipelineUpdateResults;
     scene: GeoSceneNode[];
     scales: GeoScales | null;
     version: number;
@@ -55,18 +64,47 @@ export declare class GeoPipelineStore {
     private prevPositions;
     private _hasRenderedOnce;
     constructor(config: GeoPipelineConfig);
+    /** Keep Geo transitions and pulse lifecycle on the host's logical clock
+     *  when one is supplied, while preserving the existing wall-clock default. */
+    private currentTime;
+    /** Resolve the one configuration-owned retention bound for both streaming
+     *  points and flow lines. Keeping it here prevents imperative push paths
+     *  from silently allocating a differently sized window. */
+    private getConfiguredWindowSize;
+    /** Trim the array-backed line collection only while it participates in a
+     *  stream. Bounded `setLines` snapshots remain complete until conversion. */
+    private retainNewestLines;
+    /** Rebuild both point resources from the same retained suffix so pulse
+     *  timestamps remain indexed to their matching point after a resize. */
+    private resizeStreamingWindow;
     updateConfig(config: Partial<GeoPipelineConfig>): void;
+    /** Additive explicit-result form of {@link updateConfig}. */
+    updateConfigWithResult(config: Partial<GeoPipelineConfig>): UpdateResult;
     setAreas(features: GeoJSON.Feature[]): void;
+    /** Additive explicit-result form of {@link setAreas}. */
+    setAreasWithResult(features: GeoJSON.Feature[]): UpdateResult;
     setPoints(data: Datum[]): void;
+    /** Additive explicit-result form of {@link setPoints}. */
+    setPointsWithResult(data: Datum[]): UpdateResult;
     setLines(data: Datum[]): void;
-    /** Initialize streaming mode with a ring buffer */
+    /** Additive explicit-result form of {@link setLines}. */
+    setLinesWithResult(data: Datum[]): UpdateResult;
+    /**
+     * Enter streaming mode while retaining the newest configured window from a
+     * bounded snapshot. The optional legacy argument is immediately reflected
+     * in config so the config remains the sole owner of the active capacity.
+     */
     initStreaming(windowSize?: number): void;
     /** Push a single streaming point */
     pushPoint(datum: Datum): void;
+    /** Additive explicit-result form of {@link pushPoint}. */
+    pushPointWithResult(datum: Datum): UpdateResult;
     /** Push multiple streaming points */
     pushMany(data: Datum[]): void;
+    /** Additive explicit-result form of {@link pushMany}. */
+    pushManyWithResult(data: Datum[]): UpdateResult;
     /** Append a single line/flow record (coordinates pre-resolved). Lines
-     *  aren't ring-buffered — the bounded set is the geography.
+     *  use array storage, then retain the active configured window in streaming mode.
      *  Mutates `lineData` in place to avoid the O(n) GC churn of an
      *  array spread per push. The mutation is invisible to callers
      *  because `setLines` defensive-copies on entry and `getLines`
@@ -92,15 +130,6 @@ export declare class GeoPipelineStore {
      */
     removePoint(id: string | string[]): Datum[];
     clear(): void;
-    setLayoutSelection(selection: CustomLayoutSelection | null): void;
-    /**
-     * "Styles changed, repaint the data canvas without rebuilding the scene."
-     * Set by {@link restyleScene}; consumed once per frame by the paint loop, so a
-     * style-only selection change repaints without a projection/scene recompute.
-     */
-    private _stylePaintPending;
-    /** Consume the style-only repaint signal (see {@link _stylePaintPending}). */
-    consumeStylePaintPending(): boolean;
     restyleScene(selection: CustomLayoutSelection | null): void;
     computeScene(layout: StreamLayout): void;
     private fitProjection;
@@ -148,6 +177,8 @@ export declare class GeoPipelineStore {
     private applyCartogramTransform;
     private applyDecay;
     private applyPulse;
+    refreshPulse(now: number): boolean;
+    hasActivePulsesAt(now: number): boolean;
     get hasActivePulses(): boolean;
     private startTransition;
     /**

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

@@ -0,0 +1,64 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { OnObservationCallback } from "../store/ObservationStore";
+import { type OnAnnotationActivateCallback } from "../charts/shared/annotationActivation";
+import * as React from "react";
+import type { ReactNode } from "react";
+import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../types/legendTypes";
+import { type AutoPlaceAnnotations } from "../recipes/annotationLayout";
+interface GeoSVGOverlayProps {
+    width: number;
+    height: number;
+    totalWidth: number;
+    totalHeight: number;
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    /**
+     * Geo has no Cartesian axis scale, but this remains part of the internal
+     * contract because StreamGeoFrame historically used it to request an empty
+     * accessible overlay shell.
+     */
+    showAxes?: boolean;
+    title?: string | ReactNode;
+    legend?: ReactNode | {
+        legendGroups: LegendGroup[];
+    } | {
+        gradient: GradientLegendConfig;
+    };
+    legendHoverBehavior?: (item: {
+        label: string;
+    } | null) => void;
+    legendClickBehavior?: (item: {
+        label: string;
+    }) => void;
+    legendHighlightedCategory?: string | null;
+    legendIsolatedCategories?: Set<string>;
+    legendPosition?: "right" | "left" | "top" | "bottom";
+    legendLayout?: LegendLayout;
+    foregroundGraphics?: ReactNode;
+    annotations?: Datum[];
+    onAnnotationActivate?: OnAnnotationActivateCallback;
+    onObservation?: OnObservationCallback;
+    chartId?: string;
+    chartType?: string;
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
+    pointNodes?: {
+        pointId?: string;
+        x: number;
+        y: number;
+        r: number;
+    }[];
+}
+/**
+ * The SVG chrome used by StreamGeoFrame.
+ *
+ * Geo previously imported the Cartesian SVGOverlay even though it never
+ * supplies scales, marginal graphics, grids, or linked-crosshair state. Keep
+ * the subset Geo actually exercises here so those XY-only dependencies do not
+ * enter the Geo bundle.
+ */
+export declare function GeoSVGOverlay(props: GeoSVGOverlayProps): React.JSX.Element | null;
+export {};

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

@@ -1,8 +1,9 @@
 import type { NetworkSceneNode, NetworkSceneEdge, NetworkCircleNode } from "./networkTypes";
 import type { Quadtree } from "d3-quadtree";
+import type { SceneDatum } from "./types";
 export interface NetworkHitResult {
     type: "node" | "edge";
-    datum: any;
+    datum: SceneDatum;
     x: number;
     y: number;
     distance: number;

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

@@ -1,11 +1,13 @@
 import { ParticlePool } from "./ParticlePool";
 import type { NetworkLayoutResult, NetworkHtmlMark } from "./networkCustomLayout";
 import type { CustomLayoutSelection } from "./customLayoutSelection";
-import { type CustomLayoutFailureDiagnostic } from "./customLayoutFailure";
+import type { CustomLayoutFailureDiagnostic } from "./customLayoutFailure";
 import type { ActiveTransition } from "./pipelineTransitionUtils";
 import { type Quadtree } from "d3-quadtree";
 import type { NetworkPipelineConfig, NetworkSceneNode, NetworkSceneEdge, NetworkCircleNode, NetworkLabel, RealtimeNode, RealtimeEdge, EdgePush } from "./networkTypes";
 import type { Datum } from "../charts/shared/datumTypes";
+import { NetworkPipelineUpdateResults } from "./networkPipelineUpdateResults";
+import { type UpdateResult, type UpdateResultStore } from "./pipelineUpdateStore";
 /**
  * NetworkPipelineStore — stateful store for the StreamNetworkFrame.
  *
@@ -15,7 +17,13 @@ import type { Datum } from "../charts/shared/datumTypes";
  * For bounded data: ingests nodes/edges arrays, runs layout once, builds scene.
  * For streaming data: ingests edge pushes, tracks tension, relayouts on threshold.
  */
-export declare class NetworkPipelineStore {
+export declare class NetworkPipelineStore implements UpdateResultStore {
+    getLastUpdateResult: () => UpdateResult;
+    getUpdateSnapshot: () => UpdateResult;
+    subscribeUpdateResult: (listener: () => void) => () => void;
+    setLayoutSelection: (selection: CustomLayoutSelection | null) => void;
+    markStylePaintPending: () => void;
+    consumeStylePaintPending: () => boolean;
     nodes: Map<string, RealtimeNode>;
     edges: Map<string, RealtimeEdge>;
     tension: number;
@@ -65,6 +73,9 @@ export declare class NetworkPipelineStore {
     particlePool: ParticlePool | null;
     private config;
     private tensionConfig;
+    protected updateResults: NetworkPipelineUpdateResults;
+    /** Keep ingest, live encodings, staleness, and transitions on one clock. */
+    private currentTime;
     transition: ActiveTransition | null;
     private _hasRenderedOnce;
     /** Snapshot of node positions from before bounded re-ingestion cleared the maps */
@@ -97,19 +108,25 @@ export declare class NetworkPipelineStore {
         y: number;
     }> | null;
     constructor(config: NetworkPipelineConfig);
-    updateConfig(config: NetworkPipelineConfig): void;
+    updateConfig(config: Partial<NetworkPipelineConfig>): void;
+    /** Additive explicit-result form of {@link updateConfig}. */
+    updateConfigWithResult(config: Partial<NetworkPipelineConfig>): UpdateResult;
     /**
      * Ingest hierarchy root data for tree/treemap/circlepack/partition layouts.
      * The hierarchy root is passed to the layout plugin via config.__hierarchyRoot.
      */
-    ingestHierarchy(rootData: any, size: [number, number]): void;
+    ingestHierarchy(rootData: Datum, size: [number, number]): void;
     /**
      * Ingest bounded node/edge arrays (from props).
      * Clears existing topology and rebuilds from scratch.
      */
-    ingestBounded(rawNodes: any[], rawEdges: any[], size: [number, number], options?: {
+    ingestBounded(rawNodes: Datum[], rawEdges: Datum[], size: [number, number], options?: {
         deferLayout?: boolean;
     }): void;
+    /** Additive explicit-result form of {@link ingestBounded}. */
+    ingestBoundedWithResult(rawNodes: Datum[], rawEdges: Datum[], size: [number, number], options?: {
+        deferLayout?: boolean;
+    }): UpdateResult;
     /**
      * Apply worker-computed force positions through the normal layout finalizer.
      * The force plugin still resolves edge endpoints, clamps bounds, records
@@ -129,6 +146,8 @@ export declare class NetworkPipelineStore {
      * Returns true if a relayout is needed.
      */
     ingestEdge(push: EdgePush): boolean;
+    /** Additive explicit-result form of {@link ingestEdge}. */
+    ingestEdgeWithResult(push: EdgePush): UpdateResult;
     /**
      * Run the layout algorithm via the appropriate plugin.
      */
@@ -145,13 +164,6 @@ export declare class NetworkPipelineStore {
     /**
      * Build the scene graph from current layout positions.
      */
-    /** Update the selection the layout reads at the next `buildScene`, without
-     *  triggering a rebuild. The frame calls this on selection change; whether it
-     *  then repaints (restyle) or rebuilds is the frame's decision. */
-    setLayoutSelection(selection: CustomLayoutSelection | null): void;
-    /** Snapshot each mark's as-emitted style so {@link restyleScene} can re-apply
-     *  patches from the original rather than compounding. */
-    private snapshotBaseStyles;
     /**
      * Re-apply the custom layout's `restyle`/`restyleEdge` to the existing scene
      * for `selection`, mutating styles **in place** off each mark's base style.
@@ -159,15 +171,6 @@ export declare class NetworkPipelineStore {
      * stays valid and no relayout/repack happens. The frame repaints the canvas
      * after calling this. No-op when the layout supplied no restyle callbacks.
      */
-    /**
-     * "Styles changed, repaint the data canvas without rebuilding the scene."
-     * Set by {@link restyleScene}; consumed once per frame by the paint loop.
-     * Deliberately separate from `_sceneNodesRevision` (the quadtree-invalidation
-     * counter) so a style-only selection change repaints without a relayout.
-     */
-    private _stylePaintPending;
-    /** Consume the style-only repaint signal (see {@link _stylePaintPending}). */
-    consumeStylePaintPending(): boolean;
     restyleScene(selection: CustomLayoutSelection | null): void;
     buildScene(size: [number, number]): void;
     /**

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

@@ -0,0 +1,17 @@
+import * as React from "react";
+import type { StreamNetworkFrameProps } from "./networkTypes";
+import { NetworkPipelineStore } from "./NetworkPipelineStore";
+import { NetworkSVGOverlay } from "./NetworkSVGOverlay";
+interface NetworkSSRFrameProps {
+    props: StreamNetworkFrameProps;
+    store: NetworkPipelineStore | null;
+    responsiveRef: React.Ref<HTMLDivElement>;
+    size: [number, number];
+    margin: React.ComponentProps<typeof NetworkSVGOverlay>["margin"];
+    adjustedWidth: number;
+    adjustedHeight: number;
+    resolvedBackground: React.ReactNode;
+    resolvedForeground: React.ReactNode;
+}
+export declare function NetworkSSRFrame({ props, store, responsiveRef, size, margin, adjustedWidth, adjustedHeight, resolvedBackground, resolvedForeground }: NetworkSSRFrameProps): React.JSX.Element;
+export {};

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

@@ -6,6 +6,8 @@ import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/l
 import { type AutoPlaceAnnotations } from "../recipes/annotationLayout";
 import type { AnnotationContext } from "../realtime/types";
 import { type GlyphDef } from "./glyphDef";
+import type { OnObservationCallback } from "../store/ObservationStore";
+import { type OnAnnotationActivateCallback } from "../charts/shared/annotationActivation";
 type AnnotationAnchorNode = {
     type: string;
     datum: Datum | null;
@@ -75,6 +77,10 @@ export interface NetworkSVGOverlayProps {
     sceneNodes?: AnnotationAnchorNode[];
     /** Annotations */
     annotations?: Datum[];
+    onAnnotationActivate?: OnAnnotationActivateCallback;
+    onObservation?: OnObservationCallback;
+    chartId?: string;
+    chartType?: string;
     autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: NetworkAnnotationContext) => ReactNode;
     annotationFrame?: number;

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

@@ -1,8 +1,8 @@
 import type { OrdinalSceneNode } from "./ordinalTypes";
-import type { PointSceneNode } from "./types";
+import type { SceneDatum, PointSceneNode } from "./types";
 import type { Quadtree } from "d3-quadtree";
 export interface OrdinalHitResult {
-    datum: any;
+    datum: SceneDatum;
     x: number;
     y: number;
     distance: number;

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

@@ -23,15 +23,22 @@ import type { ActiveTransition } from "./pipelineTransitionUtils";
 import type { OrdinalLayoutResult } from "./ordinalCustomLayout";
 import type { CustomLayoutSelection } from "./customLayoutSelection";
 import { type CustomLayoutFailureDiagnostic } from "./customLayoutFailure";
-import type { UpdateResult } from "./pipelineUpdateContract";
-export declare class OrdinalPipelineStore {
+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;
-    private updateResults;
+    protected updateResults: OrdinalPipelineUpdateResults;
     private getO;
     private getR;
     /** All resolved rAccessors (length > 1 when multiAxis) */
@@ -46,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;
@@ -98,6 +103,8 @@ export declare class OrdinalPipelineStore {
      * 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;
@@ -112,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
@@ -171,8 +175,6 @@ export declare class OrdinalPipelineStore {
      */
     private getBufferArray;
     getData(): Datum[];
-    /** Most recent additive update result for revision-aware hosts and tests. */
-    getLastUpdateResult(): UpdateResult;
     /**
      * Remove data items by ID. Requires dataIdAccessor to be configured.
      * Returns the removed items. Marks the store dirty for scene rebuild.
@@ -187,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

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;
+}