semiotic 3.8.0 → 3.8.2

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

@@ -33,6 +33,12 @@ export type { GlyphDef, GlyphPart } from "./stream/glyphDef";
 export type { GlyphSceneNode, SceneAccessibilityMetadata } from "./stream/types";
 export { createHatchPattern } from "./charts/shared/hatchPattern";
 export type { HatchPatternOptions } from "./charts/shared/hatchPattern";
+export { isHatchFill, hatchPatternDef, resolveSvgFill, hatchFillId } from "./charts/shared/hatchFill";
+export type { HatchFill } from "./charts/shared/hatchFill";
+export { resolveStyleRules, matchesThreshold, ruleMatches, makeRuleValueResolver, makeXYRuleContext, makeNodeRuleContext, composeStyleRules, makeStyleRuleStyleFn, } from "./charts/shared/styleRules";
+export type { StyleRule, StyleRuleStyle, StyleRuleThreshold, StyleRuleContext, StyleRulePredicate, } from "./charts/shared/styleRules";
+export { AnnotationLabel, estimateLabelWidth } from "./charts/shared/AnnotationLabel";
+export type { AnnotationLabelBackground, AnnotationLabelBackgroundConfig, AnnotationLabelProps } from "./charts/shared/AnnotationLabel";
 export type { StreamOrdinalFrameProps, StreamOrdinalFrameHandle, OrdinalChartType, OrdinalScales, OrdinalSceneNode } from "./stream/ordinalTypes";
 export type { BarChartProps } from "./charts/ordinal/BarChart";
 export type { StackedBarChartProps } from "./charts/ordinal/StackedBarChart";

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

@@ -54,3 +54,7 @@ export { compileDependencyMachine, routeDependencyTracks, createLogicalJoin, rep
 export type { DependencyAccessor, DependencyTaskStatus, DependencyMachineAccessors, CompileDependencyMachineOptions, DependencyMachineDiagnosticCode, DependencyMachineDiagnostic, DependencyMachineNode, DependencyMachineEdge, DependencyMachine, DependencyPoint, DependencyTrackDimensions, DependencyTrackOptions, DependencyTaskPlacement, DependencySocketPlacement, DependencyTrackRoute, DependencyTrackLayout, LogicalJoinSnapshot, LogicalJoin, DependencyReplayEvent, DependencyReplayClock, DependencyReplayState, BlockerAmplification, BlockerAmplificationOptions } from "./charts/physics/dependencyMachine";
 export { compileMotionEncoding, resolveMotionAccessor, resolveMotionAge, opacityFromAge, resolveMotionVector, deriveMotionVector } from "./charts/shared/motionEncoding";
 export type { MotionEncodingConstant, MotionEncodingAccessor, MotionTimeBasis, MotionTimeUnit, MotionCoordinateSpace, MotionTimeEncoding, MotionPlacementEncoding, MotionKinematicsEncoding, MotionProcessEncoding, MotionAccessibleEncoding, MotionEncoding, ResolvedMotionEncodingRow, MotionEncodingCompilation, CompileMotionEncodingOptions, ResolveMotionAgeOptions, ResolvedMotionAge, MotionAgeOpacityType, MotionAgeOpacityOptions, MotionPoint, ResolvedMotionVector } from "./charts/shared/motionEncoding";
+export { resolveStyleRules, matchesThreshold, ruleMatches, makeRuleValueResolver, composeStyleRules } from "./charts/shared/styleRules";
+export type { StyleRule, StyleRuleStyle, StyleRuleThreshold, StyleRuleContext, StyleRulePredicate } from "./charts/shared/styleRules";
+export { isHatchFill, hatchPatternDef, resolveSvgFill, hatchFillId } from "./charts/shared/hatchFill";
+export type { HatchFill } from "./charts/shared/hatchFill";

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

@@ -0,0 +1,4 @@
+/** Optional Rough.js rendering adapter. Import from `semiotic/rough`. */
+export { createRoughRenderMode, stableRoughSeed } from "./rough/createRoughRenderMode";
+export type { RoughRenderMode, RoughRenderModeOptions } from "./rough/createRoughRenderMode";
+export type { SceneRenderBackend, SceneRenderMode } from "./stream/types";

package/dist/components/semiotic-utils-core.d.ts

@@ -14,6 +14,10 @@ export { adaptiveTimeTicks, smartTickFormat } from "./charts/shared/formatUtils"
 export { darkenColor, lightenColor } from "./charts/shared/colorManipulation";
 export { createHatchPattern } from "./charts/shared/hatchPattern";
 export type { HatchPatternOptions } from "./charts/shared/hatchPattern";
+export { isHatchFill, hatchFillId, hatchFillKey } from "./charts/shared/hatchFill";
+export type { HatchFill } from "./charts/shared/hatchFill";
+export { resolveStyleRules, matchesThreshold, ruleMatches, makeRuleValueResolver, makeXYRuleContext, makeNodeRuleContext, composeStyleRules, makeStyleRuleStyleFn, } from "./charts/shared/styleRules";
+export type { StyleRule, StyleRuleStyle, StyleRuleThreshold, StyleRuleContext, StyleRulePredicate, } from "./charts/shared/styleRules";
 export { validateProps } from "./charts/shared/validateProps";
 export { diagnoseConfig } from "./charts/shared/diagnoseConfig";
 export { auditAccessibility, formatAccessibilityAudit, accessibilityCaveats } from "./charts/shared/auditAccessibility";

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

@@ -42,3 +42,7 @@ export type { QuadrantChartProps, QuadrantsConfig, QuadrantsConfigOverride, Quad
 export type { MultiAxisLineChartProps } from "./charts/xy/MultiAxisLineChart";
 export type { CandlestickChartProps } from "./charts/xy/CandlestickChart";
 export type { XYCustomChartProps } from "./charts/custom/XYCustomChart";
+export { resolveStyleRules, matchesThreshold, ruleMatches, makeRuleValueResolver, makeXYRuleContext, composeStyleRules } from "./charts/shared/styleRules";
+export type { StyleRule, StyleRuleStyle, StyleRuleThreshold, StyleRuleContext, StyleRulePredicate } from "./charts/shared/styleRules";
+export { isHatchFill, hatchPatternDef, resolveSvgFill, hatchFillId } from "./charts/shared/hatchFill";
+export type { HatchFill } from "./charts/shared/hatchFill";

package/dist/components/semiotic.d.ts

@@ -52,7 +52,9 @@ export type { CustomLayoutFailureDiagnostic, CustomLayoutFailureRecovery, Custom
 export type { UseSelectionOptions, UseSelectionResult, UseSelectionActionsResult, UseLinkedHoverOptions, UseLinkedHoverResult, UseBrushSelectionOptions, UseBrushSelectionResult } from "./LinkedCharts";
 export { useChartObserver } from "./LinkedCharts";
 export type { UseChartObserverOptions, UseChartObserverResult } from "./LinkedCharts";
-export type { ChartObservation, OnObservationCallback } from "./store/ObservationStore";
+export type { ChartObservation, OnObservationCallback, ObservationInputType, FocusObservation, ActivateObservation, AnnotationActivateObservation } from "./store/ObservationStore";
+export { annotationStableId } from "./charts/shared/annotationActivation";
+export type { ChartAnnotation, AnnotationActivationEvent, OnAnnotationActivateCallback } from "./charts/shared/annotationActivation";
 export type { ResolutionMode, SelectionClause, Selection } from "./store/SelectionStore";
 export type { SemioticTheme } from "./ThemeProvider";
 export { LIGHT_THEME, DARK_THEME, HIGH_CONTRAST_THEME } from "./ThemeProvider";
@@ -83,6 +85,12 @@ export type { ChartConfig, ToConfigOptions, CopyFormat } from "./export/chartCon
 export type { VegaLiteSpec, VegaLiteEncoding } from "./data/fromVegaLite";
 export type { SerializedSelections, SerializedSelection, SerializedFieldSelection } from "./export/selectionSerializer";
 export type { HatchPatternOptions } from "./charts/shared/hatchPattern";
+export { isHatchFill, hatchPatternDef, resolveSvgFill, hatchFillId } from "./charts/shared/hatchFill";
+export type { HatchFill } from "./charts/shared/hatchFill";
+export { resolveStyleRules, matchesThreshold, ruleMatches, makeRuleValueResolver, makeXYRuleContext, makeNodeRuleContext, composeStyleRules, makeStyleRuleStyleFn, styleRulesToPieceStyle, styleRulesToXYStyle, styleRulesToNodeStyle, } from "./charts/shared/styleRules";
+export type { StyleRule, StyleRuleStyle, StyleRuleThreshold, StyleRuleContext, StyleRulePredicate, } from "./charts/shared/styleRules";
+export { AnnotationLabel, estimateLabelWidth } from "./charts/shared/AnnotationLabel";
+export type { AnnotationLabelBackground, AnnotationLabelBackgroundConfig, AnnotationLabelProps } from "./charts/shared/AnnotationLabel";
 export { smartTickFormat, adaptiveTimeTicks } from "./charts/shared/formatUtils";
 export { darkenColor, lightenColor } from "./charts/shared/colorManipulation";
 export type { TooltipProp, TooltipConfig, TooltipField, MultiLineTooltipConfig } from "./Tooltip/Tooltip";

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

@@ -0,0 +1,37 @@
+export interface SharpPipeline {
+    resize(width: number, height: number): SharpPipeline;
+    ensureAlpha(): SharpPipeline;
+    raw(): SharpPipeline;
+    jpeg(options: {
+        quality: number;
+    }): SharpPipeline;
+    png(): SharpPipeline;
+    toBuffer(): Promise<Buffer>;
+}
+export type SharpFactory = (input: Uint8Array, options?: {
+    density: number;
+}) => SharpPipeline;
+export type SharpModule = SharpFactory & {
+    default?: SharpFactory;
+};
+export type GifPalette = number[][] | Uint8Array;
+export interface GifEncoder {
+    writeFrame(indexedPixels: Uint8Array, width: number, height: number, options: {
+        palette: GifPalette;
+        delay: number;
+        repeat: number;
+    }): void;
+    finish(): void;
+    bytes(): Uint8Array;
+}
+export interface GifencExports {
+    GIFEncoder?: () => GifEncoder;
+    quantize?: (pixels: Uint8Array, maxColors: number) => GifPalette;
+    applyPalette?: (pixels: Uint8Array, palette: GifPalette) => Uint8Array;
+    default?: GifencExports;
+}
+export interface GifencRuntimeExports extends GifencExports {
+    GIFEncoder: () => GifEncoder;
+    quantize: (pixels: Uint8Array, maxColors: number) => GifPalette;
+    applyPalette: (pixels: Uint8Array, palette: GifPalette) => Uint8Array;
+}

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

@@ -1,15 +1,19 @@
 import type { Datum } from "../charts/shared/datumTypes";
 export type FrameType = "xy" | "ordinal" | "network" | "geo" | "physics";
+export type ServerAccessorValue = string | number | boolean | Date | null | undefined;
+export type ServerAccessor = string | ((datum: Datum) => ServerAccessorValue);
+export type ServerColorScheme = string | string[] | Record<string, string> | undefined;
+export type ServerChartData = Datum | Datum[] | null | undefined;
 export interface ChartConfig {
     frameType: FrameType;
     /** Build frame props from HOC-level props */
-    buildProps: (data: any, colorBy: any, colorScheme: any, common: Datum, rest: Datum) => Datum;
+    buildProps: (data: ServerChartData, colorBy: ServerAccessor | undefined, colorScheme: ServerColorScheme, common: Datum, rest: Datum) => Datum;
 }
-export declare function accessorValue(accessor: any, fallback: string, d: Datum): any;
-export declare function numericValue(value: any): number;
+export declare function accessorValue(accessor: ServerAccessor | undefined, fallback: string, d: Datum): ServerAccessorValue;
+export declare function numericValue(value: ServerAccessorValue): number;
 export declare function viridisColor(i: number, n: number): string;
-export declare function prepareConnectedScatterplotData(data: any, rest: Datum): {
-    data: any;
+export declare function prepareConnectedScatterplotData(data: ServerChartData, rest: Datum): {
+    data: ServerChartData;
     orderMap: WeakMap<Datum, {
         idx: number;
         total: number;

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

@@ -14,15 +14,15 @@ export declare const CHART_CONFIGS: {
     CandlestickChart: ChartConfig;
     BubbleChart: {
         frameType: "xy";
-        buildProps: (data: any, colorBy: any, colorScheme: any, common: import("../stream/networkColorAccessors").Datum, rest: import("../stream/networkColorAccessors").Datum) => {
+        buildProps: (data: import("./serverChartConfigShared").ServerChartData, colorBy: import("./serverChartConfigShared").ServerAccessor | undefined, colorScheme: import("./serverChartConfigShared").ServerColorScheme, common: import("../stream/networkColorAccessors").Datum, rest: import("../stream/networkColorAccessors").Datum) => {
             chartType: string;
-            data: any;
+            data: import("./serverChartConfigShared").ServerChartData;
             xAccessor: any;
             yAccessor: any;
-            colorAccessor: any;
+            colorAccessor: import("./serverChartConfigShared").ServerAccessor | undefined;
             sizeAccessor: any;
             sizeRange: any;
-            colorScheme: any;
+            colorScheme: import("./serverChartConfigShared").ServerColorScheme;
         };
     };
     ConnectedScatterplot: ChartConfig;

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

@@ -1,4 +1,4 @@
-import type { Datum } from "../charts/shared/datumTypes";
+import type { Datum, DatumValue } from "../charts/shared/datumTypes";
 /**
  * Static annotation rendering for server-side SVG.
  *
@@ -9,8 +9,8 @@ import * as React from "react";
 import type { SemioticTheme } from "../store/ThemeStore";
 import { type AutoPlaceAnnotations } from "../recipes/annotationLayout";
 interface AnnotationScales {
-    x?: (v: any) => number;
-    y?: (v: any) => number;
+    x?: AnnotationScale;
+    y?: AnnotationScale;
     /** For ordinal charts: band scale */
     o?: {
         (v: string): number | undefined;
@@ -25,6 +25,9 @@ interface AnnotationScales {
      */
     geoProjection?: (coords: [number, number]) => [number, number] | null;
 }
+type AnnotationScale = {
+    bivarianceHack(value: DatumValue): number;
+}["bivarianceHack"];
 interface AnnotationLayout {
     width: number;
     height: number;

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

@@ -71,5 +71,5 @@ export declare function renderStaticGradientLegend(config: StaticGradientLegendC
 /**
  * Extract unique categories from data using an accessor.
  */
-export declare function extractCategories(data: any[], accessor: string | ((d: Datum) => string) | undefined): string[];
+export declare function extractCategories(data: Datum[], accessor: string | ((d: Datum) => string) | undefined): string[];
 export {};

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

@@ -1,8 +1,8 @@
-import type { Datum } from "../charts/shared/datumTypes";
+import type { Datum, DatumValue } from "../charts/shared/datumTypes";
 import type { NetworkPipelineConfig, RealtimeNode, RealtimeEdge, StreamNetworkFrameProps } from "../stream/networkTypes";
 import { type EvidenceSink } from "./renderEvidence";
 import type { ThemeAwareProps } from "./staticSVGChrome";
-export declare function resolveAccessor(accessor: string | ((d: Datum) => any) | undefined, defaultKey: string): (d: Datum) => any;
-export declare function buildRealtimeNodes(propsNodes: any[], config: NetworkPipelineConfig): RealtimeNode[];
-export declare function buildRealtimeEdges(propsEdges: any[], config: NetworkPipelineConfig): RealtimeEdge[];
+export declare function resolveAccessor(accessor: string | ((d: Datum) => DatumValue) | undefined, defaultKey: string): (d: Datum) => DatumValue;
+export declare function buildRealtimeNodes(propsNodes: Datum[], config: NetworkPipelineConfig): RealtimeNode[];
+export declare function buildRealtimeEdges(propsEdges: Datum[], config: NetworkPipelineConfig): RealtimeEdge[];
 export declare function renderNetworkFrame(props: StreamNetworkFrameProps & ThemeAwareProps, sink?: EvidenceSink): string;

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

@@ -5,16 +5,17 @@ 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";
 import type { SemioticTheme } from "../store/ThemeStore";
 import * as React from "react";
+import { type AxisExtentMode } from "../charts/shared/axisExtent";
 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;
@@ -82,12 +83,12 @@ export declare function renderLegendConfig(legend: unknown, options: {
 }): React.ReactNode;
 export declare function defaultTickFormat(v: number): string;
 /** Render grid lines for XY charts */
-export declare function renderGridSVG(scales: StreamScales, layout: StreamLayout, theme: SemioticTheme, idPrefix?: string): React.ReactNode;
+export declare function renderGridSVG(scales: StreamScales, layout: StreamLayout, theme: SemioticTheme, idPrefix?: string, axisExtent?: AxisExtentMode): React.ReactNode;
 /** Render grid lines for ordinal charts */
 export declare function renderOrdinalGridSVG(store: OrdinalPipelineStore, layout: {
     width: number;
     height: number;
-}, theme: SemioticTheme, idPrefix?: string): React.ReactNode;
+}, theme: SemioticTheme, idPrefix?: string, axisExtent?: AxisExtentMode): React.ReactNode;
 /** Wrap SVG content with accessibility attributes */
 export declare function wrapSVG(content: React.ReactNode, opts: {
     width: number;

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;