semiotic 3.8.0 → 3.8.2

package/dist/components/stream/ordinalSceneBuilders/types.d.ts

@@ -16,8 +16,8 @@ export interface OrdinalSceneContext {
     getO: (d: Datum) => string;
     multiScales: ScaleLinear<number, number>[];
     rAccessors: ((d: Datum) => number)[];
-    resolvePieceStyle: (d: any, category?: string) => Style;
-    resolveSummaryStyle: (d: any, category?: string) => Style;
+    resolvePieceStyle: (d: Datum | null, category?: string) => Style;
+    resolveSummaryStyle: (d: Datum | null, category?: string) => Style;
     /** For timeline: resolve rAccessor as [start, end] */
     getRawRange: (d: Datum) => [number, number] | null;
 }

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

@@ -3,10 +3,13 @@ import type { ScaleLinear, ScaleBand } from "d3-scale";
 import type { WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext } from "../realtime/types";
 import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
 import type { SymbolName } from "./symbolPath";
-import type { Style, SceneDatum, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors, FrameGraphicsProp, SceneAccessibilityMetadata } from "./types";
+import type { Style, SceneDatum, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors, FrameGraphicsProp, SceneAccessibilityMetadata, SceneRenderMode } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../types/legendTypes";
 import type { Datum } from "../charts/shared/datumTypes";
+import type { OnObservationCallback } from "../store/ObservationStore";
+import type { SemanticClickBehavior, SemanticHoverBehavior } from "../charts/shared/semanticInteractions";
+import type { OnAnnotationActivateCallback } from "../charts/shared/annotationActivation";
 export type OrdinalChartType = "bar" | "clusterbar" | "point" | "swarm" | "pie" | "donut" | "boxplot" | "violin" | "histogram" | "ridgeline" | "timeline" | "funnel" | "bar-funnel" | "swimlane" | "custom";
 export interface OrdinalScales {
     o: ScaleBand<string>;
@@ -280,6 +283,8 @@ export interface OrdinalPipelineConfig {
     /** Whether to animate elements on first render (bars grow from baseline, wedges sweep in) */
     introAnimation?: boolean;
     staleness?: StalenessConfig;
+    /** Frame-owned logical clock for ingest, pulse, staleness, and transitions. */
+    clock?: import("./FrameRuntime").FrameClock;
     /** When provided, replaces chart-type dispatch in scene building.
      *  Receives an OrdinalLayoutContext (scales, dimensions, theme,
      *  resolveColor) and returns scene nodes plus optional overlays. */
@@ -384,6 +389,8 @@ export interface StreamOrdinalFrameProps<T = Datum> {
      *  it's a band scale, not a continuous one. Ignored when explicit
      *  `rTickValues` are provided — caller has hand-picked positions. */
     axisExtent?: import("../charts/shared/axisExtent").AxisExtentMode;
+    /** Optional scene paint backend. Exact scene geometry remains interactive. */
+    renderMode?: SceneRenderMode<OrdinalSceneNode>;
     pieceStyle?: (d: Datum, category?: string) => Style;
     summaryStyle?: (d: Datum, category?: string) => Style;
     colorScheme?: string | string[] | Record<string, string>;
@@ -409,9 +416,17 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     enableHover?: boolean;
     hoverAnnotation?: boolean | HoverAnnotationConfig;
     tooltipContent?: (d: HoverData) => ReactNode;
-    customHoverBehavior?: (d: HoverData | null) => void;
-    customClickBehavior?: (d: HoverData | null) => void;
+    customHoverBehavior?: SemanticHoverBehavior<HoverData>;
+    customClickBehavior?: SemanticClickBehavior<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;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     showGrid?: boolean;
@@ -460,6 +475,18 @@ export interface StreamOrdinalFrameProps<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 used to derive logical frame time. */
+    clock?: import("./FrameRuntime").FrameClock;
+    /** Injectable frame-local random source. Ordinal rendering currently has no stochastic layout. */
+    random?: import("./FrameRuntime").FrameRandom;
+    /** Serializable deterministic random seed for future ordinal stochastic work. */
+    seed?: number;
+    /** Freeze logical animation time and cancel queued work while paused. */
+    paused?: boolean;
+    /** Freeze logical animation time while the document is hidden. Defaults to true. */
+    suspendWhenHidden?: boolean;
     /** Render a visually-hidden data table from the scene graph for screen readers */
     accessibleTable?: boolean;
     /** Accessible description overriding the auto-generated aria-label on the chart container */

package/dist/components/stream/physics/PhysicsPipelineStore.d.ts

@@ -56,6 +56,8 @@ export declare class PhysicsPipelineStore {
     recordObservation(record: PhysicsObservationRecord): PhysicsObservationEvent;
     /** Most recent explicit update result for a revision-aware host or tool. */
     getLastUpdateResult(): UpdateResult;
+    getUpdateSnapshot(): UpdateResult;
+    subscribeUpdateResult(listener: () => void): () => void;
     version(): number;
     setPaused(paused: boolean): void;
     setVisible(visible: boolean): void;

package/dist/components/stream/physics/PhysicsSVGOverlay.d.ts

@@ -10,6 +10,8 @@ import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../../type
 import { type AutoPlaceAnnotations } from "../../recipes/annotationLayout";
 import type { AnnotationContext } from "../../realtime/types";
 import type { PhysicsBodyState } from "./PhysicsKernel";
+import type { OnObservationCallback } from "../../store/ObservationStore";
+import { type OnAnnotationActivateCallback } from "../../charts/shared/annotationActivation";
 export type PhysicsAnnotationAnchorNode = {
     pointId?: string;
     x: number;
@@ -47,6 +49,10 @@ export interface PhysicsSVGOverlayProps {
     /** Live body anchors for pointId / bodyId annotations. */
     pointNodes?: PhysicsAnnotationAnchorNode[];
     annotations?: Datum[];
+    onAnnotationActivate?: OnAnnotationActivateCallback;
+    onObservation?: OnObservationCallback;
+    chartId?: string;
+    chartType?: string;
     autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     /** Optional foreground SVG already composed into the frame stack. */

package/dist/components/stream/physics/StreamPhysicsTypes.d.ts

@@ -157,7 +157,7 @@ export type StreamPhysicsBodyForce = StreamPhysicsRegionVector | ((context: Stre
 export interface PhysicsHoverData {
     __semioticHoverData: true;
     body: PhysicsBodyState;
-    data: unknown;
+    data: Datum | PhysicsBodyState;
     id: string;
     type: "body";
     x: number;
@@ -183,6 +183,17 @@ export interface StreamPhysicsFrameProps {
      * deterministic clock for replayable tests or evidence capture.
      */
     clock?: () => number;
+    /**
+     * Host-level random seam for frame-local visual work. It deliberately does
+     * not replace the physics kernel's deterministic random source.
+     */
+    random?: () => number;
+    /**
+     * Serializable deterministic seed for frame-local work and, when
+     * `config.kernel.seed` is omitted, the built-in physics kernel. An explicit
+     * kernel seed always wins so existing simulation snapshots remain stable.
+     */
+    seed?: number;
     bodySemanticItemLimit?: number;
     bodySemanticItems?: boolean | PhysicsBodySemanticItemAccessor;
     bodySemanticUpdateMs?: number;
@@ -230,6 +241,8 @@ export interface StreamPhysicsFrameProps {
      * `physics: "barrier"|"sensor"` also feed colliders via PhysicsAnnotations.
      */
     annotations?: Datum[];
+    /** Observe activation of widget annotations without replacing widget behavior. */
+    onAnnotationActivate?: import("../../charts/shared/annotationActivation").OnAnnotationActivateCallback;
     autoPlaceAnnotations?: AutoPlaceAnnotations;
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => React.ReactNode;
     legend?: React.ReactNode | {
@@ -257,11 +270,13 @@ export interface StreamPhysicsFrameProps {
      * Click on a body (or empty canvas when null). Prefer this over
      * `onBodyPointerDown` when you only need the Semiotic click contract.
      */
-    onClick?: (datum: unknown | null, event: {
-        x: number;
-        y: number;
-        body: PhysicsBodyState | null;
-    }) => void;
+    onClick?: {
+        bivarianceHack(datum: Datum | null, event: {
+            x: number;
+            y: number;
+            body: PhysicsBodyState | null;
+        }): void;
+    }["bivarianceHack"];
     onRegionEvent?: (event: StreamPhysicsRegionEvent) => void;
     onSimulationExecutionChange?: (state: StreamPhysicsExecutionState) => void;
     onBodyPointerDown?: (body: PhysicsBodyState | null, event: React.PointerEvent<HTMLCanvasElement>) => void;

package/dist/components/stream/physics/physicsFrameObservations.d.ts

@@ -0,0 +1,19 @@
+import type { ObservationInputType, OnObservationCallback } from "../../store/ObservationStore";
+interface CurrentRef<T> {
+    current: T;
+}
+export type PhysicsFrameObservationType = "hover" | "hover-end" | "click" | "click-end" | "focus" | "activate";
+export interface PhysicsFrameObservationPayload {
+    datum?: unknown;
+    x?: number;
+    y?: number;
+    inputType?: ObservationInputType;
+}
+interface PhysicsFrameObservationOptions {
+    onObservationRef: CurrentRef<OnObservationCallback | undefined>;
+    chartIdRef: CurrentRef<string | undefined>;
+    wallClockRef: CurrentRef<() => number>;
+}
+/** Builds a stable emitter while reading the frame's latest callback and clock refs. */
+export declare function usePhysicsFrameObservationEmitter({ onObservationRef, chartIdRef, wallClockRef }: PhysicsFrameObservationOptions): (type: PhysicsFrameObservationType, payload?: PhysicsFrameObservationPayload) => void;
+export {};

package/dist/components/stream/physics/physicsFrameSetup.d.ts

@@ -0,0 +1,4 @@
+import { PhysicsPipelineStore, type PhysicsPipelineConfig, type PhysicsQueuedSpawn, type PhysicsSpawnPacingOptions } from "./PhysicsPipelineStore";
+/** Create the retained simulation store and seed its initial queued bodies. */
+export declare function createPhysicsFrameStore(config: PhysicsPipelineConfig | undefined, initialSpawns: PhysicsQueuedSpawn[] | undefined, initialSpawnPacing: PhysicsSpawnPacingOptions | undefined): PhysicsPipelineStore;
+export declare function defaultPhysicsFrameClock(): number;

package/dist/components/stream/physics/physicsPipelineUpdateResults.d.ts

@@ -3,7 +3,25 @@ import type { PhysicsPipelineConfig } from "./PhysicsPipelineTypes";
 import type { Invalidation } from "../pipelineUpdateContract";
 export declare const PHYSICS_BODY_INVALIDATIONS: readonly Invalidation[];
 export declare const PHYSICS_MOTION_INVALIDATIONS: readonly Invalidation[];
-export declare const PHYSICS_CONFIG_INVALIDATIONS: readonly Invalidation[];
 export declare const PHYSICS_STATE_INVALIDATIONS: readonly Invalidation[];
+/** Whether a config patch rebuilds Physics' retained simulation resource. */
+export type PhysicsRetainedDataEffect = "preserve" | "rebuild";
+export interface PhysicsConfigPatchDependency {
+    readonly retainedData: PhysicsRetainedDataEffect;
+    readonly invalidations: readonly Invalidation[];
+}
+/**
+ * Physics config changes either rebuild the retained engine, affect the next
+ * simulated geometry, alter capacity presentation, or only change future
+ * stepping/observation behavior. This keeps direct store consumers from
+ * treating every physics option as a full scene-layout update.
+ */
+export declare const PHYSICS_CONFIG_PATCH_DEPENDENCIES: Readonly<Record<string, PhysicsConfigPatchDependency>>;
+export interface PhysicsConfigPatchClassification {
+    readonly retainedData: PhysicsRetainedDataEffect;
+    readonly invalidations: ReadonlySet<Invalidation>;
+}
+/** Union the declared effects for a patch after its effective keys are known. */
+export declare function classifyPhysicsConfigPatch(keys: readonly string[]): PhysicsConfigPatchClassification;
 export declare function physicsKernelOptionsEqual(a: PhysicsKernelOptions | undefined, b: PhysicsKernelOptions | undefined): boolean;
 export declare function changedPhysicsConfigKeys(config: PhysicsPipelineConfig, previous: PhysicsPipelineConfig): string[];

package/dist/components/stream/physics/usePhysicsFrameLifecyclePolicy.d.ts

@@ -1,9 +1,11 @@
 import { type MutableRefObject, type RefObject } from "react";
+import type { FrameRuntime } from "../FrameRuntime";
 import type { PhysicsPipelineStore } from "./PhysicsPipelineStore";
 import type { PhysicsWorkerCommand } from "./PhysicsWorkerProtocol";
 export declare function isPhysicsDocumentVisible(): boolean;
 interface PhysicsFrameLifecyclePolicyInput {
     cancelRender: () => void;
+    frameRuntime: FrameRuntime;
     lastFrameTimeRef: MutableRefObject<number | null>;
     paused: boolean;
     postWorkerCommand: (command: PhysicsWorkerCommand, notifyTick?: boolean) => void;
@@ -12,5 +14,5 @@ interface PhysicsFrameLifecyclePolicyInput {
     suspendWhenHidden: boolean;
 }
 /** Keep pause and page-visibility scheduling policy consistent for physics frames. */
-export declare function usePhysicsFrameLifecyclePolicy({ cancelRender, lastFrameTimeRef, paused, postWorkerCommand, requestRender, storeRef, suspendWhenHidden }: PhysicsFrameLifecyclePolicyInput): void;
+export declare function usePhysicsFrameLifecyclePolicy({ cancelRender, frameRuntime, lastFrameTimeRef, paused, postWorkerCommand, requestRender, storeRef, suspendWhenHidden }: PhysicsFrameLifecyclePolicyInput): void;
 export {};

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

@@ -11,6 +11,8 @@ import type { MarginType } from "../types/marginType";
 export interface PipelineConfig {
     chartType: StreamChartType;
     runtimeMode?: "streaming" | "bounded";
+    /** Optional monotonic clock owned by a frame runtime or embedding host. */
+    clock?: () => number;
     windowSize: number;
     windowMode: WindowMode;
     arrowOfTime: ArrowOfTime;
@@ -71,7 +73,7 @@ export interface PipelineConfig {
     /** Internal: set by PipelineStore when open/close accessors are both missing */
     candlestickRangeMode?: boolean;
     boundsAccessor?: string | ((d: Datum) => CoercibleNumber);
-    boundsStyle?: any;
+    boundsStyle?: Style | ((d: Datum, group?: string) => Style);
     y0Accessor?: string | ((d: Datum) => CoercibleNumber);
     band?: BandConfig | BandConfig[];
     gradientFill?: {
@@ -90,7 +92,7 @@ export interface PipelineConfig {
             color: string;
         }>;
     };
-    lineStyle?: any;
+    lineStyle?: Style | ((d: Datum, group?: string) => Style);
     pointStyle?: (d: Datum) => Style & {
         r?: number;
     };

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

@@ -1,4 +1,4 @@
-import type { Datum } from "../charts/shared/datumTypes";
+import type { Datum, DatumValue } from "../charts/shared/datumTypes";
 /**
  * Shared decay encoding utilities for all pipeline stores.
  *
@@ -37,4 +37,4 @@ export declare function buildDatumIndexMap(data: readonly Datum[]): Map<Datum, n
  *
  * @param indexMap Optional prebuilt datum→index map (see {@link buildDatumIndexMap}).
  */
-export declare function applyDecay(decay: DecayConfig, nodes: SceneNode[], data: Datum[], indexMap?: Map<any, number>): void;
+export declare function applyDecay(decay: DecayConfig, nodes: SceneNode[], data: Datum[], indexMap?: Map<DatumValue, number>): void;

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

@@ -1,4 +1,4 @@
-import type { Datum } from "../charts/shared/datumTypes";
+import type { Datum, DatumValue } from "../charts/shared/datumTypes";
 /**
  * Pulse encoding for XY pipeline scene nodes.
  *
@@ -21,7 +21,7 @@ export declare function computePulseIntensity(pulse: PulseConfig, insertTime: nu
  * @param indexMap Optional prebuilt datum→index map so a scene pass that
  * also runs decay can share one O(n) walk of the buffer.
  */
-export declare function applyPulse(pulse: PulseConfig, nodes: SceneNode[], data: Datum[], timestampBuffer: RingBuffer<number>, indexMap?: Map<any, number>, now?: number): boolean;
+export declare function applyPulse(pulse: PulseConfig, nodes: SceneNode[], data: Datum[], timestampBuffer: RingBuffer<number>, indexMap?: Map<DatumValue, number>, now?: number): boolean;
 /**
  * Update the pulse-owned fields for a node that the pipeline has matched to
  * source data. Keeping this narrow is important for custom layouts: nodes

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

@@ -1,12 +1,33 @@
-import { type ChangeSet, type UpdateResult } from "./pipelineUpdateContract";
+import { type ChangeSet, type Invalidation, type UpdateResult } from "./pipelineUpdateContract";
+/** Whether a config patch re-derives retained XY data resources. */
+export type XYRetainedDataEffect = "preserve" | "rebuild";
+export interface XYConfigPatchDependency {
+    readonly retainedData: XYRetainedDataEffect;
+    readonly invalidations: readonly Invalidation[];
+}
+/**
+ * XY's explicit config-patch dependency table. Accessor and chart-mode
+ * changes re-derive retained data; scale/layout keys preserve data while
+ * rebuilding derived scene state; styling and overlays repaint their own
+ * layers. Mount-only and future-work keys intentionally have no immediate
+ * revision effect.
+ */
+export declare const XY_CONFIG_PATCH_DEPENDENCIES: Readonly<Record<string, XYConfigPatchDependency>>;
+export interface XYConfigPatchClassification {
+    readonly retainedData: XYRetainedDataEffect;
+    readonly invalidations: ReadonlySet<Invalidation>;
+}
+/** Union the declared effects for a patch after its effective keys are known. */
+export declare function classifyXYConfigPatch(keys: readonly string[]): XYConfigPatchClassification;
 type DataChangeKind = Extract<ChangeSet["kind"], "ingest" | "replace" | "remove" | "update" | "clear">;
 /** Result bookkeeping and invalidation policy for the XY PipelineStore pilot. */
 export declare class PipelineStoreUpdateResults {
     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[], requiresRebuild: boolean, extentAccessorChanged: boolean): UpdateResult;
+    recordConfig(keys: readonly string[]): UpdateResult;
 }
 export {};

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

@@ -65,7 +65,7 @@ export interface TransitionState {
  * Detects entering nodes (new, no prev match) and exiting nodes (prev, no new match).
  * Mutates scene and exitNodes in place. Returns updated state.
  */
-export declare function startTransition(ctx: TransitionContext, transition: TransitionConfig, state: TransitionState, prevPositionMap: Map<string, PrevPosition>, prevPathMap: Map<string, PrevPath>): TransitionState;
+export declare function startTransition(ctx: TransitionContext, transition: TransitionConfig, state: TransitionState, prevPositionMap: Map<string, PrevPosition>, prevPathMap: Map<string, PrevPath>, startTime?: number): TransitionState;
 /**
  * Advance the transition animation. Returns true if still animating.
  * Mutates scene nodes in place.

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

@@ -54,9 +54,16 @@ export declare function createUpdateResult(changeSet: ChangeSet, invalidations:
  * keeps revision bookkeeping out of family-specific data/layout code while
  * preserving each store's existing mutation API.
  */
+export type UpdateResultListener = () => void;
+export interface UpdateResultStore {
+    getUpdateSnapshot(): UpdateResult;
+    subscribeUpdateResult(listener: UpdateResultListener): () => void;
+}
 export declare class UpdateResultTracker {
     private revisions;
     private latest;
+    private listeners;
     get last(): UpdateResult;
+    subscribe(listener: UpdateResultListener): () => void;
     record(changeSet: ChangeSet, invalidations: Iterable<Invalidation>): UpdateResult;
 }

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

@@ -0,0 +1,21 @@
+import type { UpdateResult } from "./pipelineUpdateContract";
+import type { CustomLayoutSelection } from "./customLayoutSelection";
+export type { UpdateResult } from "./pipelineUpdateContract";
+/** Shared additive update-result read and subscription surface for stream stores. */
+export interface PipelineUpdateResultSource {
+    readonly last: UpdateResult;
+    subscribe(listener: () => void): () => void;
+}
+/** Public lifecycle surface installed on each stream store prototype. */
+export interface UpdateResultStore {
+    getLastUpdateResult(): UpdateResult;
+    getUpdateSnapshot(): UpdateResult;
+    subscribeUpdateResult(listener: () => void): () => void;
+    setLayoutSelection(selection: CustomLayoutSelection | null): void;
+    markStylePaintPending(): void;
+    consumeStylePaintPending(): boolean;
+}
+/** Adds the shared lifecycle methods without imposing a base-class constructor. */
+export declare function attachUpdateResultStore(target: {
+    prototype: object;
+}): void;

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

@@ -0,0 +1,27 @@
+import * as React from "react";
+import type { SceneRenderBackend, SceneRenderMode, Style } from "./types";
+type SceneLike = {
+    type?: string;
+    datum?: unknown;
+    style?: Style;
+};
+/** Resolve a whole-scene or per-datum renderer. The legacy `sketchy` token
+ * stays on the existing built-in rendering path. */
+export declare function resolveSceneRenderBackend<Node extends SceneLike>(renderMode: SceneRenderMode<Node> | undefined, node: Node): SceneRenderBackend<Node> | undefined;
+/** Paint nodes in scene order, delegating unsupported runs to the built-in renderer. */
+export declare function paintSceneWithBackend<Node extends SceneLike>(args: {
+    context: CanvasRenderingContext2D;
+    nodes: Node[];
+    renderMode: SceneRenderMode<Node> | undefined;
+    pixelRatio: number;
+    paintBuiltIn: (nodes: Node[]) => void;
+}): void;
+/** Try a backend for SSR/static SVG, then invoke the existing converter. */
+export declare function renderSceneWithBackend<Node extends SceneLike>(args: {
+    node: Node;
+    index: number;
+    renderMode: SceneRenderMode<Node> | undefined;
+    fallback: () => React.ReactNode;
+}): React.ReactNode;
+export declare function resetRenderBackendWarningsForTests(): void;
+export {};

package/dist/components/stream/renderers/canvasRenderHelpers.d.ts

@@ -16,6 +16,7 @@
  * mechanical bits that recur regardless of the shape being painted.
  */
 import type { CurveType } from "../types";
+import { type HatchFill } from "../../charts/shared/hatchFill";
 import type { CurveFactory } from "d3-shape";
 /**
  * Structural shapes for the gradient configs the helpers accept. Kept
@@ -61,7 +62,20 @@ export declare function resolveCurveFactory(curve: CurveType | undefined): Curve
  * `(typeof X === "string" ? resolveCSSColor(ctx, X) : X) || fallback`,
  * repeated once per renderer per fill/stroke site.
  */
-export declare function resolveCanvasFill(ctx: CanvasRenderingContext2D, fill: string | CanvasPattern | null | undefined, fallback: string): string | CanvasPattern;
+export declare function resolveCanvasFill(ctx: CanvasRenderingContext2D, fill: string | HatchFill | CanvasPattern | null | undefined, fallback: string): string | CanvasPattern;
+/**
+ * Narrow a possibly-`HatchFill` `style.fill` to the `string | CanvasPattern`
+ * a canvas `fillStyle` accepts, for the direct-assign sites that don't
+ * otherwise route through {@link resolveCanvasFill}. Returns `undefined` for a
+ * nullish (or unresolvable) fill so callers can apply their own fallback with
+ * `?? "…"`.
+ *
+ * Delegates to {@link resolveCanvasFill} so behavior stays consistent: string
+ * fills (including `var(--…)`) resolve through `resolveCSSColor` — a raw CSS
+ * variable written straight to `fillStyle` would silently paint black — and a
+ * `HatchFill` resolves to its `CanvasPattern` (or its resolved background).
+ */
+export declare function coerceCanvasFill(ctx: CanvasRenderingContext2D, fill: string | HatchFill | CanvasPattern | null | undefined): string | CanvasPattern | undefined;
 /**
  * Build a linear gradient from a `FillGradient` config. Returns `null`
  * when the gradient cannot be constructed (fewer than two valid color

package/dist/components/stream/renderers/geoCanvasRenderer.d.ts

@@ -1,4 +1,5 @@
-import type { GeoSceneNode } from "../geoTypes";
+import type { GeoScales, GeoSceneNode } from "../geoTypes";
+import type { StreamLayout } from "../types";
 /**
  * Canvas renderer for GeoAreaSceneNode — projected geographic polygons.
  * Uses Path2D for GPU-accelerated rendering of complex geo paths.
@@ -6,4 +7,4 @@ import type { GeoSceneNode } from "../geoTypes";
  * Points and lines in a geo frame are rendered by the existing
  * pointCanvasRenderer and lineCanvasRenderer respectively.
  */
-export declare function geoCanvasRenderer(ctx: CanvasRenderingContext2D, nodes: GeoSceneNode[], _scales: any, _layout: any): void;
+export declare function geoCanvasRenderer(ctx: CanvasRenderingContext2D, nodes: GeoSceneNode[], _scales: GeoScales, _layout: StreamLayout): void;

package/dist/components/stream/renderers/networkParticleRenderer.d.ts

@@ -8,4 +8,4 @@ export declare function renderNetworkParticles(ctx: CanvasRenderingContext2D, po
 /**
  * Spawn particles for all edges proportional to their value.
  */
-export declare function spawnNetworkParticles(pool: ParticlePool, edges: RealtimeEdge[], deltaTime: number, style: ParticleStyle): void;
+export declare function spawnNetworkParticles(pool: ParticlePool, edges: RealtimeEdge[], deltaTime: number, style: ParticleStyle, random?: () => number): void;

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

@@ -0,0 +1,28 @@
+import type { ReactNode } from "react";
+import type { Datum } from "../charts/shared/datumTypes";
+import type { Style } from "./types";
+/**
+ * Optional paint backend for pre-computed scene nodes. A backend may change
+ * how a mark looks, but it must not mutate the scene node: original geometry
+ * remains authoritative for interaction, focus, transitions, and accessibility.
+ */
+export interface SceneRenderBackend<Node = unknown> {
+    readonly id: string;
+    cacheKey(node: Node, style: Style): string;
+    drawCanvas(args: {
+        context: CanvasRenderingContext2D;
+        node: Node;
+        style: Style;
+        pixelRatio: number;
+    }): boolean;
+    renderStaticSVG(args: {
+        node: Node;
+        style: Style;
+        key: string;
+    }): ReactNode | null;
+}
+/** A backend can cover the whole scene or be selected per datum. */
+export type SceneRenderDatum<Node> = Node extends {
+    datum?: infer NodeDatum;
+} ? Exclude<NodeDatum, undefined> | null : Datum | null;
+export type SceneRenderMode<Node = unknown> = "sketchy" | SceneRenderBackend<Node> | ((datum: SceneRenderDatum<Node>, node: Node) => "sketchy" | SceneRenderBackend<Node> | undefined);

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

@@ -1,18 +1,45 @@
-import type { RevisionSet, UpdateResult } from "./pipelineUpdateContract";
-type SceneRevisionSet = Pick<RevisionSet, "sceneGeometry" | "layout" | "domain">;
-interface SceneRevisionCheck {
+import type { RevisionSet, UpdateResult, UpdateResultStore } from "./pipelineUpdateContract";
+export type SceneRevisionSet = Pick<RevisionSet, "sceneGeometry" | "layout" | "domain">;
+export interface SceneRevisionCheck {
     revisions: SceneRevisionSet;
     signature: string;
     sawSignals: boolean;
     wasUnconsumed: boolean;
     warnUnconsumed: boolean;
 }
-/** Development-only consumption and duplicate-compute diagnostics for an XY scene host. */
+interface SceneRevisionStore extends UpdateResultStore {
+    getLastUpdateResult(): UpdateResult;
+}
+/** Development-only consumption and duplicate-compute diagnostics for a scene host. */
 export declare class SceneRevisionDiagnostics {
+    private readonly hostName;
+    constructor(hostName?: string);
     private lastConsumed;
+    private lastObserved;
     private lastDuplicateWarning;
     private lastUnconsumedWarning;
+    /**
+     * Accept a React external-store observation without participating in frame
+     * scheduling or paint. The imperative result passed to beforeCompute remains
+     * authoritative; retaining the high-water mark only protects development
+     * diagnostics when React observes an update between frame passes.
+     */
+    observeUpdateResult(updateResult: UpdateResult): void;
     beforeCompute(updateResult: UpdateResult, isTransitioning: boolean): SceneRevisionCheck;
     afterCompute(check: SceneRevisionCheck, computedScene: boolean, dimsChanged: boolean): void;
 }
+/** Keep a frame's development-only revision tracker stable across renders. */
+export declare function useSceneRevisionDiagnostics(hostName: string): import("react").RefObject<SceneRevisionDiagnostics>;
+/** Wrap an unconditional scene build with the common revision accounting. */
+export declare function runSceneBuild(diagnostics: SceneRevisionDiagnostics, store: SceneRevisionStore, build: () => void, isTransitioning?: boolean, dimsChanged?: boolean): void;
+/**
+ * Observes external-store revisions without putting diagnostics on a React
+ * render path. Stores can record non-invalidating operational results during
+ * host effects, so a useSyncExternalStore subscription here could feed those
+ * diagnostics back into the host's render cycle.
+ */
+export declare const SceneRevisionDiagnosticsObserver: import("react").MemoExoticComponent<({ store, diagnostics }: {
+    store: UpdateResultStore;
+    diagnostics: SceneRevisionDiagnostics;
+}) => null>;
 export {};

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

@@ -0,0 +1,16 @@
+import type { OnObservationCallback } from "../store/ObservationStore";
+import type { SemanticClickBehavior, SemanticHoverBehavior } from "../charts/shared/semanticInteractions";
+import type { OnAnnotationActivateCallback } from "../charts/shared/annotationActivation";
+/** Interaction props shared by all Stream Frame families. */
+export interface StreamSemanticInteractionProps<Hover> {
+    customHoverBehavior?: SemanticHoverBehavior<Hover>;
+    customClickBehavior?: SemanticClickBehavior<Hover>;
+    /** 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;
+    /** Observe activation of widget annotations without replacing widget behavior. */
+    onAnnotationActivate?: OnAnnotationActivateCallback;
+}

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

@@ -0,0 +1,14 @@
+export interface ThemeSemanticColors {
+    primary?: string;
+    secondary?: string;
+    success?: string;
+    danger?: string;
+    warning?: string;
+    error?: string;
+    info?: string;
+    text?: string;
+    textSecondary?: string;
+    border?: string;
+    grid?: string;
+    surface?: string;
+}

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

@@ -0,0 +1,10 @@
+export declare function resolveHorizontalTickAnchor(mode: "middle" | "edges" | undefined, isLeftmost: boolean, isRightmost: boolean): "start" | "middle" | "end";
+export declare function resolveVerticalTickBaseline(mode: "middle" | "edges" | undefined, isTopmost: boolean, isBottommost: boolean): "hanging" | "middle" | "auto";
+export declare function tickPixelExtent(ticks: Array<{
+    pixel: number;
+}>): {
+    min: number | null;
+    max: number | null;
+};
+export declare function resolveGridDash(style: "dashed" | "dotted" | string | undefined): string | undefined;
+export declare function jaggedBaselinePath(orient: "left" | "right" | "top" | "bottom", width: number, height: number): string;

package/dist/components/stream/test-utils/frameScheduler.d.ts

@@ -0,0 +1,12 @@
+import type { FrameScheduler } from "../useFrame";
+/**
+ * Deterministic rAF scheduler for frame tests. It deliberately permits zero
+ * as the first handle so tests cannot rely on truthiness for pending work.
+ */
+export declare function createFrameScheduler(firstHandle?: number): {
+    scheduler: FrameScheduler;
+    requestedHandles: number[];
+    cancelledHandles: number[];
+    readonly pendingCount: number;
+    flush(timestamp?: number): void;
+};

package/dist/components/stream/test-utils/revisionConsumption.d.ts

@@ -0,0 +1,13 @@
+import { SceneRevisionDiagnostics, type SceneRevisionCheck } from "../sceneRevisionDiagnostics";
+import type { UpdateResult } from "../pipelineUpdateContract";
+export interface UnconsumedSceneRevisionProbe {
+    diagnostics: SceneRevisionDiagnostics;
+    initial: SceneRevisionCheck;
+    later: SceneRevisionCheck;
+}
+/**
+ * Assert the contract that a later style/state result cannot conceal scene
+ * work that a host has not consumed. Callers finish the probe with
+ * `diagnostics.afterCompute(probe.later, false, false)` and assert its warning.
+ */
+export declare function assertUnconsumedSceneRevisionSurvivesLaterUpdate(initialResult: UpdateResult, laterResult: UpdateResult, hostName?: string): UnconsumedSceneRevisionProbe;