semiotic 3.8.0 → 3.8.1

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

@@ -26,10 +26,18 @@ import type { CustomLayoutSelection } from "./customLayoutSelection";
 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 {
+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;
@@ -64,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
@@ -96,7 +106,7 @@ export declare class PipelineStore {
     private _bufferDirty;
     private needsFullRebuild;
     private lastLayout;
-    private updateResults;
+    protected updateResults: PipelineStoreUpdateResults;
     scales: StreamScales | null;
     scene: SceneNode[];
     version: number;
@@ -230,8 +240,6 @@ export declare class PipelineStore {
      */
     private getBufferArray;
     getData(): Datum[];
-    /** Most recent additive update result for revision-aware hosts and tests. */
-    getLastUpdateResult(): UpdateResult;
     /**
      * Remove data points by ID. Requires pointIdAccessor to be configured.
      * Returns the removed items. Marks the store dirty for scene rebuild.
@@ -255,19 +263,7 @@ 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;
-    /**
-     * "Styles changed, repaint the data canvas without rebuilding the scene."
-     * Set by {@link restyleScene}; consumed once per frame by the render loop.
-     * Kept separate from the dirty flag so a style-only selection change repaints
-     * without forcing a layout/scene rebuild (the point of the restyle fast path).
-     */
-    private _stylePaintPending;
-    /** Consume the style-only repaint signal (see {@link _stylePaintPending}). */
-    consumeStylePaintPending(): boolean;
     /**
      * Re-apply the custom layout's `restyle` to the existing scene for
      * `selection`, off each node's base style — no relayout, no quadtree rebuild

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,4 +1,4 @@
-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;
@@ -38,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/accessorUtils.d.ts

@@ -24,8 +24,8 @@
  * its identity changing, bump the pipeline config's `accessorRevision` to force
  * re-derivation.
  */
-export declare function accessorsEquivalent(a: string | ((...args: any[]) => any) | undefined, b: string | ((...args: any[]) => any) | undefined): boolean;
+export declare function accessorsEquivalent<TDatum, TResult>(a: string | ((datum: TDatum, index?: number) => TResult) | undefined, b: string | ((datum: TDatum, index?: number) => TResult) | undefined): boolean;
 export type CoercibleNumber = number | Date | string;
 export declare function resolveAccessor<T extends Record<string, unknown>>(accessor: string | ((d: T) => CoercibleNumber) | undefined, fallback: string): (d: T) => number;
-export declare function resolveRawAccessor<T extends Record<string, unknown>>(accessor: string | ((d: T) => unknown) | undefined, fallback: string): (d: T) => unknown;
+export declare function resolveRawAccessor<T extends Record<string, unknown>, TResult>(accessor: string | ((d: T) => TResult) | undefined, fallback: string): (d: T) => TResult;
 export declare function resolveStringAccessor<T extends Record<string, unknown>>(accessor: string | ((d: T) => string) | undefined, fallback?: string): ((d: T) => string) | undefined;

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

@@ -9,14 +9,14 @@
  * `StreamOrdinalFrame` (and any future frame with the same need)
  * can share the same plumbing rather than re-implementing it.
  */
-import type { Datum } from "../charts/shared/datumTypes";
+import type { Datum, DatumValue } from "../charts/shared/datumTypes";
 export interface ResolvedAnnotationAccessor {
     /** String key the annotation context will read on each datum. */
     key: string | undefined;
     /** Accessor function when the user supplied one (synthetic key
      *  gets baked from this); `null` when the user supplied a string
      *  or nothing. */
-    fn: ((d: Datum) => any) | null;
+    fn: ((d: Datum) => DatumValue) | null;
 }
 /**
  * Resolve an accessor pair to the (key, fn) shape the annotation

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

@@ -0,0 +1,4 @@
+import type { ReactNode } from "react";
+import type { FrameGraphicsContext, FrameGraphicsProp } from "./types";
+/** Resolve a static or scale-aware SVG graphics layer for a frame family. */
+export declare function resolveFrameGraphics<S>(graphics: FrameGraphicsProp<S> | undefined, size: number[], margin: FrameGraphicsContext<S>["margin"], scales: S | null): ReactNode;

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

@@ -0,0 +1,45 @@
+import type { Dispatch, KeyboardEvent, SetStateAction } from "react";
+import type { HoverData } from "../realtime/types";
+import type { SemanticClickBehavior, SemanticHoverBehavior } from "../charts/shared/semanticInteractions";
+import type { PipelineStore } from "./PipelineStore";
+import type { OrdinalPipelineStore } from "./OrdinalPipelineStore";
+import type { GeoPipelineStore } from "./GeoPipelineStore";
+import type { SceneNode } from "./types";
+import type { OrdinalSceneNode } from "./ordinalTypes";
+import type { GeoSceneNode } from "./geoTypes";
+import { type NavPoint } from "./keyboardNav";
+type RefValue<Value> = {
+    current: Value;
+};
+type SetHoverPoint = Dispatch<SetStateAction<HoverData | null>>;
+type FocusedNavPoint = Pick<NavPoint, "shape" | "w" | "h" | "pathData">;
+interface KeyboardInteractionParams<Store, Node = unknown> {
+    storeRef: RefValue<Store | null>;
+    hoverRef: RefValue<HoverData | null>;
+    hoveredNodeRef?: RefValue<Node | null>;
+    setHoverPoint: SetHoverPoint;
+    customHoverBehavior: SemanticHoverBehavior<HoverData>;
+    customClickBehavior: SemanticClickBehavior<HoverData>;
+    scheduleRender: () => void;
+}
+export declare function useXYKeyboardNavigation(params: KeyboardInteractionParams<PipelineStore, SceneNode>): {
+    kbFocusIndexRef: import("react").RefObject<number>;
+    focusedNavPointRef: import("react").RefObject<FocusedNavPoint | null>;
+    onKeyDown: (event: KeyboardEvent) => void;
+};
+interface OrdinalKeyboardParams extends KeyboardInteractionParams<OrdinalPipelineStore, OrdinalSceneNode> {
+    chartType: string;
+    oAccessor: unknown;
+    rAccessor: unknown;
+}
+export declare function useOrdinalKeyboardNavigation({ chartType, oAccessor, rAccessor, ...params }: OrdinalKeyboardParams): {
+    kbFocusIndexRef: import("react").RefObject<number>;
+    focusedNavPointRef: import("react").RefObject<FocusedNavPoint | null>;
+    onKeyDown: (event: KeyboardEvent) => void;
+};
+export declare function useGeoKeyboardNavigation({ storeRef, hoverRef, hoveredNodeRef, setHoverPoint, customHoverBehavior, customClickBehavior, scheduleRender }: KeyboardInteractionParams<GeoPipelineStore, GeoSceneNode>): {
+    kbFocusIndexRef: import("react").RefObject<number>;
+    focusedNavPointRef: import("react").RefObject<FocusedNavPoint | null>;
+    onKeyDown: (event: KeyboardEvent) => void;
+};
+export {};

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

@@ -9,8 +9,8 @@ import type { Style } from "./types";
 import type { Datum } from "../charts/shared/datumTypes";
 export declare function resolveProjection(prop: ProjectionProp | undefined): GeoProjection;
 export declare function makeGeoNumericAccessor(acc: string | ((d: Datum) => number) | undefined, fallback: string): (d: Datum) => number;
-export declare function makeLineDataAccessor(acc: string | ((d: Datum) => any[]) | undefined): (d: Datum) => any[];
-export declare function resolveGeoStyle(styleProp: Style | ((d: Datum) => Style) | undefined, datum: any, defaults: Style): Style;
+export declare function makeLineDataAccessor(acc: string | ((d: Datum) => Datum[]) | undefined): (d: Datum) => Datum[];
+export declare function resolveGeoStyle<TDatum extends object>(styleProp: Style | ((d: TDatum) => Style) | undefined, datum: TDatum, defaults: Style): Style;
 export declare function themedDefaultArea(config: GeoPipelineConfig): Style;
 export declare function themedDefaultPoint(config: GeoPipelineConfig): Style & {
     r?: number;
@@ -43,4 +43,4 @@ export declare function buildOffsetGeoPath(screenPath: [number, number][], strok
  * Bidirectional pairs (A->B and B->A) naturally separate because their
  * left-hand normals point to opposite sides.
  */
-export declare function buildOffsetPath(start: [number, number], end: [number, number], _flow: any, _allFlows: any[], strokeWidth: number): [number, number][];
+export declare function buildOffsetPath(start: [number, number], end: [number, number], _flow: Datum, _allFlows: Datum[], strokeWidth: number): [number, number][];

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

@@ -0,0 +1,34 @@
+import { type ChangeSet, type Invalidation, type UpdateResult } from "./pipelineUpdateContract";
+/** Whether a config patch must re-derive its retained Geo data resources. */
+export type GeoRetainedDataEffect = "preserve" | "rebuild";
+export interface GeoConfigPatchDependency {
+    readonly retainedData: GeoRetainedDataEffect;
+    readonly invalidations: readonly Invalidation[];
+}
+/**
+ * Geo's key-level config-patch dependency table. `windowSize` is a retained
+ * resource rebuild: its `data` revision is added only when an active stream
+ * actually resizes, so a bounded config-only patch is never reported as an
+ * ingest.
+ */
+export declare const GEO_CONFIG_PATCH_DEPENDENCIES: Readonly<Record<string, GeoConfigPatchDependency>>;
+export interface GeoConfigPatchClassification {
+    readonly retainedData: GeoRetainedDataEffect;
+    readonly invalidations: ReadonlySet<Invalidation>;
+}
+/** Union the declared effects for a patch after its effective keys are known. */
+export declare function classifyGeoConfigPatch(keys: readonly string[]): GeoConfigPatchClassification;
+type DataChangeKind = Extract<ChangeSet["kind"], "ingest" | "replace" | "remove" | "update" | "clear">;
+/** Result bookkeeping and explicit config-patch dependency policy for Geo. */
+export declare class GeoPipelineUpdateResults {
+    private tracker;
+    get last(): UpdateResult;
+    subscribe(listener: () => void): () => void;
+    recordData(kind: DataChangeKind, count?: number): UpdateResult;
+    recordNoop(kind: DataChangeKind | "restyle"): UpdateResult;
+    recordRestyle(hasCustomRestyle: boolean): UpdateResult;
+    recordConfig(keys: readonly string[], options?: {
+        retainedDataChanged?: boolean;
+    }): UpdateResult;
+}
+export {};

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

@@ -0,0 +1,16 @@
+import type { GeoPath, GeoPermissibleObjects, GeoProjection } from "d3-geo";
+import type { GeoPipelineConfig, GeoSceneNode } from "./geoTypes";
+import type { StreamLayout } from "./types";
+import type { Datum } from "../charts/shared/datumTypes";
+interface GeoSceneBuildInput {
+    config: GeoPipelineConfig;
+    projection: GeoProjection;
+    path: GeoPath<void, GeoPermissibleObjects>;
+    areas: GeoJSON.Feature[];
+    points: Datum[];
+    lines: Datum[];
+    layout: StreamLayout;
+}
+/** Builds the built-in geo scene independently of store-owned custom layout state. */
+export declare function buildBuiltInGeoScene({ config, projection, path, areas, points, lines, layout }: GeoSceneBuildInput): GeoSceneNode[];
+export {};

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

@@ -1,7 +1,7 @@
 import type { ReactNode } from "react";
 import type { GeoProjection, GeoPath, GeoPermissibleObjects } from "d3-geo";
 import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../types/legendTypes";
-import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, SceneDatum, PointSceneNode, GlyphSceneNode, ThemeSemanticColors, SceneAccessibilityMetadata } from "./types";
+import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, SceneDatum, PointSceneNode, GlyphSceneNode, ThemeSemanticColors, SceneAccessibilityMetadata, SceneRenderMode } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { HoverAnnotationConfig, HoverData } from "../realtime/types";
 import type { GeoParticleStyle } from "./GeoParticlePool";
@@ -11,6 +11,9 @@ import type { MarginType } from "../types/marginType";
 import type { GeoCustomLayout } from "./geoCustomLayout";
 import type { CustomLayoutSelection } from "./customLayoutSelection";
 import type { CustomLayoutFailureDiagnostic } from "./customLayoutFailure";
+import type { OnObservationCallback } from "../store/ObservationStore";
+import type { SemanticClickBehavior, SemanticHoverBehavior } from "../charts/shared/semanticInteractions";
+import type { OnAnnotationActivateCallback } from "../charts/shared/annotationActivation";
 export type ProjectionProp = GeoProjection | ProjectionName | ProjectionConfig;
 export type ProjectionName = "mercator" | "equalEarth" | "albersUsa" | "orthographic" | "naturalEarth" | "equirectangular";
 export interface ProjectionConfig {
@@ -69,7 +72,7 @@ export interface GeoLineSceneNode {
 export type GeoSceneNode = GeoAreaSceneNode | PointSceneNode | GlyphSceneNode | GeoLineSceneNode;
 export interface GeoScales {
     projection: GeoProjection;
-    geoPath: GeoPath<any, GeoPermissibleObjects>;
+    geoPath: GeoPath<void, GeoPermissibleObjects>;
     projectedPoint: (lon: number, lat: number) => [number, number] | null;
     invertedPoint: (px: number, py: number) => [number, number] | null;
 }
@@ -77,19 +80,20 @@ export interface GeoPipelineConfig {
     projection: ProjectionProp;
     projectionExtent?: [[number, number], [number, number]];
     /**
-     * Auto-fit padding as a **fraction** of the plot (0–0.5), not pixels.
-     * `0.1` insets the fitted geography 10% from each edge. A value `>= 1` is
-     * almost always a pixel mistake and collapses the projection off-canvas.
+     * Projection-fit padding as a finite fraction of the plot, not pixels.
+     * Valid values are in `[0, 0.5)`; `0.1` insets automatic fitting 10% from
+     * each edge. `null` and `undefined` use `0`; other values throw `RangeError`
+     * at the config boundary. Ignored when `projectionExtent` is supplied.
      * @default 0
      */
-    fitPadding?: number;
+    fitPadding?: number | null;
     xAccessor?: string | ((d: Datum) => number);
     yAccessor?: string | ((d: Datum) => number);
     lineDataAccessor?: string | ((d: Datum) => Datum[]);
     lineType?: "geo" | "line";
     /** Flow rendering style: "basic" (straight/great-circle), "offset" (bidirectional offset), "arc" (curved arcs) @default "basic" */
     flowStyle?: "basic" | "offset" | "arc";
-    areaStyle?: Style | ((d: Datum) => Style);
+    areaStyle?: Style | ((d: GeoJSON.Feature) => Style);
     pointStyle?: (d: Datum) => Style & {
         r?: number;
     };
@@ -103,6 +107,10 @@ export interface GeoPipelineConfig {
     themeDiverging?: string;
     graticule?: boolean | GraticuleConfig;
     projectionTransform?: DistanceCartogramConfig;
+    /** Maximum retained points and lines after the store enters streaming mode. @default 500 */
+    windowSize?: number;
+    /** Logical clock used for Geo pulse and transition work. */
+    clock?: import("./FrameRuntime").FrameClock;
     decay?: DecayConfig;
     pulse?: PulseConfig;
     transition?: TransitionConfig;
@@ -125,12 +133,13 @@ export interface StreamGeoFrameProps<T = Datum> {
     projection: ProjectionProp;
     projectionExtent?: [[number, number], [number, number]];
     /**
-     * Auto-fit padding as a **fraction** of the plot (0–0.5), not pixels.
-     * `0.1` insets the fitted geography 10% from each edge. A value `>= 1` is
-     * almost always a pixel mistake and collapses the projection off-canvas.
+     * Projection-fit padding as a finite fraction of the plot, not pixels.
+     * Valid values are in `[0, 0.5)`; `0.1` insets automatic fitting 10% from
+     * each edge. `null` and `undefined` use `0`; other values throw `RangeError`
+     * at the config boundary. Ignored when `projectionExtent` is supplied.
      * @default 0
      */
-    fitPadding?: number;
+    fitPadding?: number | null;
     areas?: GeoJSON.Feature[];
     points?: T[];
     lines?: T[];
@@ -190,7 +199,11 @@ export interface StreamGeoFrameProps<T = Datum> {
     className?: string;
     background?: string;
     runtimeMode?: "bounded" | "streaming";
-    areaStyle?: Style | ((d: Datum) => Style);
+    /** Maximum retained points and lines after imperative streaming begins. @default 500 */
+    windowSize?: number;
+    /** Optional scene paint backend. Exact projected geometry remains interactive. */
+    renderMode?: SceneRenderMode<GeoSceneNode>;
+    areaStyle?: Style | ((d: GeoJSON.Feature) => Style);
     pointStyle?: (d: Datum) => Style & {
         r?: number;
     };
@@ -214,9 +227,17 @@ export interface StreamGeoFrameProps<T = Datum> {
      * @default false
      */
     allowTooltipOverflow?: boolean;
-    customClickBehavior?: (d: HoverData | null) => void;
-    customHoverBehavior?: (d: HoverData | null) => void;
+    customClickBehavior?: SemanticClickBehavior<HoverData>;
+    customHoverBehavior?: SemanticHoverBehavior<HoverData>;
+    /** Structured interaction observations, including semantic focus/activate. */
+    onObservation?: OnObservationCallback;
+    /** @internal HOC observation callback forwarded only to annotation widgets. */
+    annotationObservationCallback?: OnObservationCallback;
+    /** Chart instance identifier included in observation events. */
+    chartId?: string;
     annotations?: Datum[];
+    /** Observe activation of widget annotations without replacing widget behavior. */
+    onAnnotationActivate?: OnAnnotationActivateCallback;
     autoPlaceAnnotations?: AutoPlaceAnnotations;
     decay?: DecayConfig;
     pulse?: PulseConfig;
@@ -226,6 +247,18 @@ export interface StreamGeoFrameProps<T = Datum> {
      *  Set `{ intro: false }` to disable the intro animation. */
     animate?: AnimateProp;
     staleness?: StalenessConfig;
+    /** Optional rAF seam for deterministic host scheduling. */
+    frameScheduler?: import("./useFrame").FrameScheduler;
+    /** Monotonic wall-clock seam for deterministic replay, tests, or evidence capture. */
+    clock?: import("./FrameRuntime").FrameClock;
+    /** Injectable random source for frame-local stochastic work. */
+    random?: import("./FrameRuntime").FrameRandom;
+    /** Serializable deterministic random seed. Ignored when `random` is supplied. */
+    seed?: number;
+    /** Freeze logical animation time and cancel queued work while paused. */
+    paused?: boolean;
+    /** Freeze logical animation time while the page is hidden. Defaults to true for Geo frames. */
+    suspendWhenHidden?: boolean;
     backgroundGraphics?: ReactNode;
     foregroundGraphics?: ReactNode;
     title?: string | ReactNode;
@@ -271,7 +304,7 @@ export interface StreamGeoFrameHandle {
     getLines(): Datum[];
     clear(): void;
     getProjection(): GeoProjection | null;
-    getGeoPath(): GeoPath<any, GeoPermissibleObjects> | null;
+    getGeoPath(): GeoPath<void, GeoPermissibleObjects> | null;
     /** Get cartogram layout info (center position, max cost, radius) */
     getCartogramLayout(): {
         cx: number;

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

@@ -27,11 +27,11 @@ export declare function getHitRadius(nodeRadius: number | undefined, maxDistance
  * Convert a value to a Date if possible. Returns null for non-date values.
  * Treats numbers > 1e9 as millisecond timestamps.
  */
-export declare function toDate(value: any): Date | null;
+export declare function toDate(value: Date | number | string | null | undefined): Date | null;
 /**
  * Detect whether a tick marks a time boundary (new month or year) compared to the previous tick.
  */
-export declare function isTimeLandmark(value: any, prevValue: any): boolean;
+export declare function isTimeLandmark(value: Date | number | string | null | undefined, prevValue: Date | number | string | null | undefined): boolean;
 /**
  * Normalize an angle to the [0, 2π) range.
  */

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

@@ -7,6 +7,8 @@
  * property flattening that are handled at the call site.
  */
 import type { HoverData } from "../realtime/types";
+import type { Datum } from "../charts/shared/datumTypes";
+export type RawHoverDatum = Datum | Datum[] | null;
 /**
  * Minimal shape a Stream Frame's internal hover handler needs from a pointer
  * event. React.MouseEvent satisfies this structurally, as does the plain
@@ -22,7 +24,7 @@ export interface HoverPointerCoords {
 }
 export declare const TOUCH_HIT_RADIUS = 24;
 export declare function getPointerHitRadius(baseRadius: number, pointerType?: string): number;
-export declare function normalizeHoverDatum(rawDatum: any): any;
+export declare function normalizeHoverDatum(rawDatum: RawHoverDatum): Datum | null;
 /**
  * Build a HoverData object from a raw datum and pixel coordinates.
  * The raw datum is preserved as `hover.data` for tooltip / callback
@@ -30,4 +32,4 @@ export declare function normalizeHoverDatum(rawDatum: any): any;
  * relevant to a specific frame family — `category`, `stats`,
  * `nodeOrEdge`, `xValue`, etc. — is layered in via `extra`.
  */
-export declare function buildHoverData(rawDatum: any, x: number, y: number, extra?: Partial<HoverData>): HoverData;
+export declare function buildHoverData(rawDatum: RawHoverDatum, x: number, y: number, extra?: Partial<HoverData>): HoverData;

package/dist/components/stream/layouts/forceLayoutWorkerClient.d.ts

@@ -17,6 +17,7 @@ export interface FrameForceWorkerRequest {
         chartType: "force";
         iterations?: number;
         forceStrength?: number;
+        seed?: number;
     };
     size: [number, number];
 }

package/dist/components/stream/layouts/hierarchyUtils.d.ts

@@ -20,7 +20,7 @@ export declare function parseColor(color: string): [number, number, number];
  * Uses perceived luminance (ITU-R BT.601).
  */
 export declare function contrastTextColor(bgColor: string): string;
-export declare function resolveChildrenAccessor(accessor: string | ((d: Datum) => any[]) | undefined): ((d: Datum) => any[]) | undefined;
-export declare function resolveNodeId(d: any, config: NetworkPipelineConfig, index: number): string;
+export declare function resolveChildrenAccessor(accessor: string | ((d: Datum) => Datum[]) | undefined): ((d: Datum) => Datum[]) | undefined;
+export declare function resolveNodeId(d: Datum, config: NetworkPipelineConfig, index: number): string;
 export declare function resolveLabelFn(nodeLabel: string | ((d: Datum) => string) | undefined): ((d: Datum) => string) | null;
 export declare function resolveDefaultNodeSize(nodeSize: number | string | ((d: Datum) => number) | undefined): number;

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

@@ -0,0 +1,23 @@
+import type { NetworkLayoutResult } from "./networkCustomLayout";
+import { type CustomLayoutFailureDiagnostic } from "./customLayoutFailure";
+import type { NetworkPipelineConfig, RealtimeEdge, RealtimeNode } from "./networkTypes";
+interface NetworkCustomLayoutRunInput {
+    config: NetworkPipelineConfig;
+    customLayout: NonNullable<NetworkPipelineConfig["customNetworkLayout"]>;
+    size: [number, number];
+    nodes: RealtimeNode[];
+    edges: RealtimeEdge[];
+    previousResult: NetworkLayoutResult | null;
+    revision: number;
+}
+export type NetworkCustomLayoutRunResult = {
+    kind: "success";
+    result: NetworkLayoutResult;
+} | {
+    kind: "failure";
+    diagnostic: CustomLayoutFailureDiagnostic;
+    preservedLastGoodScene: boolean;
+};
+/** Runs user-provided network layout code behind the common failure boundary. */
+export declare function runNetworkCustomLayout({ config, customLayout, size, nodes, edges, previousResult, revision }: NetworkCustomLayoutRunInput): NetworkCustomLayoutRunResult;
+export {};

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

@@ -0,0 +1,15 @@
+import type { CustomLayoutSelection } from "./customLayoutSelection";
+import type { NetworkLayoutResult } from "./networkCustomLayout";
+import type { NetworkSceneEdge, NetworkSceneNode } from "./networkTypes";
+import type { Style } from "./types";
+export declare function snapshotNetworkCustomStyles(nodes: NetworkSceneNode[], edges: NetworkSceneEdge[]): WeakMap<object, Style>;
+interface NetworkRestyleInput {
+    nodes: NetworkSceneNode[];
+    edges: NetworkSceneEdge[];
+    restyle: NetworkLayoutResult["restyle"];
+    restyleEdge: NetworkLayoutResult["restyleEdge"];
+    baseStyles: WeakMap<object, Style>;
+    selection: CustomLayoutSelection | null;
+}
+export declare function restyleNetworkCustomScene({ nodes, edges, restyle, restyleEdge, baseStyles, selection }: NetworkRestyleInput): boolean;
+export {};

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

@@ -0,0 +1,7 @@
+/**
+ * Whether the network paint loop needs another animation frame.
+ *
+ * Particles are continuous only for sankey and custom layouts; pulse and
+ * pipeline animations apply to every chart type.
+ */
+export declare function shouldContinueNetworkAnimation(chartType: string, hasCustomNetworkLayout: boolean, showParticles: boolean, hasPulse: boolean, isStoreAnimating: boolean): boolean;

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

@@ -0,0 +1,39 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { EdgePush, RealtimeEdge, RealtimeNode } from "./networkTypes";
+import type { CustomLayoutFailureDiagnostic } from "./customLayoutFailure";
+import type { NetworkLayoutResult } from "./networkCustomLayout";
+/** Imperative API exposed by `StreamNetworkFrame` refs. */
+export interface StreamNetworkFrameHandle {
+    push(edge: EdgePush): void;
+    pushMany(edges: EdgePush[]): void;
+    /** Remove a node by ID. Also removes connected edges. */
+    removeNode(id: string): boolean;
+    /** Remove edges by source+target, or by edge ID when edgeIdAccessor is configured. */
+    removeEdge(sourceIdOrEdgeId: string, targetId?: string): boolean;
+    /** Update a node's data by ID. Returns previous data. */
+    updateNode(id: string, updater: (data: Datum) => Datum): Datum | null;
+    /** Update all edges between source+target. Returns array of previous data. */
+    updateEdge(sourceId: string, targetId: string, updater: (data: Datum) => Datum): Datum[];
+    clear(): void;
+    getTopology(): {
+        nodes: RealtimeNode[];
+        edges: RealtimeEdge[];
+    };
+    getTopologyDiff(): {
+        addedNodes: string[];
+        removedNodes: string[];
+        addedEdges: string[];
+        removedEdges: string[];
+    };
+    relayout(): void;
+    getTension(): number;
+    /** The most recent custom layout result (sceneNodes/sceneEdges/overlays as
+     *  returned by `customNetworkLayout`) - host readback so pages that need the
+     *  computed placement do not re-run the layout. Null before the first layout
+     *  or when no custom layout is configured. A failed retry retains the prior
+     *  good result; inspect `getLayoutFailure()` to distinguish recovery. */
+    getCustomLayout(): NetworkLayoutResult | null;
+    /** The latest custom-layout failure, if any. Cleared by a successful layout,
+     * removing the custom layout, or `clear()`. */
+    getLayoutFailure(): CustomLayoutFailureDiagnostic | null;
+}

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

@@ -0,0 +1,15 @@
+import { type SemanticClickBehavior, type SemanticHoverBehavior } from "../charts/shared/semanticInteractions";
+import type { HoverData } from "../realtime/types";
+import type { OnObservationCallback } from "../store/ObservationStore";
+interface NetworkObservationBehaviorOptions {
+    customHoverBehavior?: SemanticHoverBehavior<HoverData>;
+    customClickBehavior?: SemanticClickBehavior<HoverData>;
+    onObservation?: OnObservationCallback;
+    chartId?: string;
+}
+/** Adds the standard observation vocabulary to the network behavior callbacks. */
+export declare function useNetworkObservationBehaviors({ customHoverBehavior: customHoverBehaviorProp, customClickBehavior: customClickBehaviorProp, onObservation, chartId }: NetworkObservationBehaviorOptions): {
+    customHoverBehavior: SemanticHoverBehavior<HoverData>;
+    customClickBehavior: SemanticClickBehavior<HoverData>;
+};
+export {};

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

@@ -1,21 +1,30 @@
 import type { NetworkPipelineStore } from "./NetworkPipelineStore";
-import type { NetworkPipelineConfig, ParticleStyle, RealtimeEdge } from "./networkTypes";
+import type { SceneRevisionDiagnostics } from "./sceneRevisionDiagnostics";
+import type { NetworkPipelineConfig, ParticleStyle, RealtimeEdge, NetworkSceneNode, NetworkSceneEdge } from "./networkTypes";
 import type { MarginType } from "../types/marginType";
-import type { DecayConfig, PulseConfig, StalenessConfig } from "./types";
+import type { DecayConfig, PulseConfig, StalenessConfig, SceneRenderMode } from "./types";
 export interface NetworkFramePaintContext {
     canvas: HTMLCanvasElement;
     store: NetworkPipelineStore;
+    sceneRevisionDiagnostics?: SceneRevisionDiagnostics;
     size: [number, number];
     margin: MarginType;
     adjustedWidth: number;
     adjustedHeight: number;
     background?: string;
+    renderMode?: SceneRenderMode<NetworkSceneNode | NetworkSceneEdge>;
+    /** Skip opaque canvas fill when an SVG backgroundGraphics layer is present. */
+    hasBackgroundGraphics?: boolean;
     dirtyRef: {
         current: boolean;
     };
     lastFrameTimeRef: {
         current: number;
     };
+    /** FrameRuntime logical timestamp for this paint. */
+    now: number;
+    /** FrameRuntime random source for particle placement/spawn sampling. */
+    random: () => number;
     reducedMotion: boolean;
     showParticles: boolean;
     isContinuous: boolean;