semiotic 3.7.5 → 3.8.1

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

@@ -0,0 +1,41 @@
+/**
+ * Pure physics pipeline helpers: spawn scheduling, colliders, cloning, hit geometry.
+ * Extracted from PhysicsPipelineStore so the store class stays orchestration-only.
+ */
+import { type PhysicsActiveSensorPair, type PhysicsBodyState, type PhysicsColliderSpec, type PhysicsKernelOptions, type PhysicsKernelSnapshot } from "./PhysicsKernel";
+import type { PhysicsBodyBudgetOptions } from "./PhysicsBodyBudget";
+import type { PhysicsBoundsColliderOptions, PhysicsObservationEvent, PhysicsPipelineConfig, PhysicsPipelineObservationOptions, PhysicsPipelineQueuedSpawnSnapshot, PhysicsPlotBounds, PhysicsQueuedSpawn, PhysicsSensorObservationConfig, PhysicsSimulationState, PhysicsSpawnPacingOptions, PhysicsXBinColliderOptions } from "./PhysicsPipelineTypes";
+export type InternalQueuedSpawn = PhysicsPipelineQueuedSpawnSnapshot;
+export declare const DEFAULT_PHYSICS_PIPELINE_CONFIG: Required<Omit<PhysicsPipelineConfig, "bodyBudget" | "colliders" | "engine" | "kernel" | "observation" | "sediment">>;
+export interface NormalizedObservationConfig {
+    chartId: string;
+    chartType: string;
+    sensors: Record<string, PhysicsSensorObservationConfig>;
+    onObservation?: (event: PhysicsObservationEvent) => void;
+    onSimulationStateChange?: (state: PhysicsSimulationState, previousState: PhysicsSimulationState) => void;
+}
+export declare const DEFAULT_OBSERVATION_CONFIG: NormalizedObservationConfig;
+export declare function normalizeObservationConfig(options?: PhysicsPipelineObservationOptions, previous?: NormalizedObservationConfig): NormalizedObservationConfig;
+export declare function cloneSpawn(spawn: PhysicsQueuedSpawn): PhysicsQueuedSpawn;
+export declare function finiteNumber(value: unknown): number | undefined;
+export declare function schedulePhysicsSpawns(spawns: PhysicsQueuedSpawn[], options?: PhysicsSpawnPacingOptions): PhysicsQueuedSpawn[];
+export declare function cloneQueuedSpawn(spawn: InternalQueuedSpawn): InternalQueuedSpawn;
+export declare function cloneColliders(colliders: PhysicsColliderSpec[]): PhysicsColliderSpec[];
+export declare function cloneBodyBudgetOptions(options: false | PhysicsBodyBudgetOptions): false | PhysicsBodyBudgetOptions;
+export declare function sortQueue(a: InternalQueuedSpawn, b: InternalQueuedSpawn): number;
+export declare function requiredKernelOptions(kernel: PhysicsKernelSnapshot["options"]): Required<PhysicsKernelOptions>;
+export declare function bodySearchRadius(body: PhysicsBodyState): number;
+export declare function bodyHitDistanceSquared(body: PhysicsBodyState, x: number, y: number, radius: number): number | null;
+export declare function sensorPairKey(sensorId: string, bodyId: string): string;
+export declare function parseSensorPairKey(key: string): PhysicsActiveSensorPair;
+export type PhysicsQuadtreeLeaf = {
+    data?: PhysicsBodyState;
+    next?: PhysicsQuadtreeLeaf;
+    length?: number;
+};
+export declare function collidersFromPlotBounds(bounds: PhysicsPlotBounds, options?: PhysicsBoundsColliderOptions): PhysicsColliderSpec[];
+export declare function collidersFromXScaleBins(options: PhysicsXBinColliderOptions): PhysicsColliderSpec[];
+export interface PhysicsPipelineEvictionResult {
+    evicted: string[];
+    sedimented: string[];
+}

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

@@ -0,0 +1,14 @@
+import type { PhysicsEngineAdapter } from "./PhysicsEngineAdapter";
+import type { PhysicsKernelEvent } from "./PhysicsKernel";
+import type { PhysicsObservationEvent, PhysicsSimulationState } from "./PhysicsPipelineTypes";
+import { type NormalizedObservationConfig } from "./physicsPipelineHelpers";
+export interface PhysicsObservationContext {
+    elapsedSeconds: number;
+    observation: NormalizedObservationConfig;
+    emit: (event: PhysicsObservationEvent) => void;
+}
+export declare function observePhysicsKernelEvents(world: PhysicsEngineAdapter, events: PhysicsKernelEvent[], context: PhysicsObservationContext): void;
+export declare function observePhysicsSensorTransitions(world: PhysicsEngineAdapter, previousPairs: ReadonlySet<string>, context: PhysicsObservationContext): Set<string>;
+export declare function removePhysicsSensorPairsForBodies(pairs: Set<string>, bodyIds: ReadonlySet<string>): void;
+export declare function resolvePhysicsSimulationState(paused: boolean, visible: boolean, hasQueuedBodies: boolean, allSleeping: boolean): PhysicsSimulationState;
+export declare function emitPhysicsSimulationStateTransition(previous: PhysicsSimulationState, next: PhysicsSimulationState, context: PhysicsObservationContext): void;

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

@@ -0,0 +1,27 @@
+import type { PhysicsKernelOptions } from "./PhysicsKernel";
+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_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/physicsRegionRuntime.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Region effect application, body forces, and post-tick pipeline for
+ * StreamPhysicsFrame. Pure control-surface helpers — no React.
+ */
+import type { Style } from "../types";
+import type { PhysicsBodyState, PhysicsColliderSpec } from "./PhysicsKernel";
+import type { PhysicsPipelineControlSurface, PhysicsPipelineStore, PhysicsPipelineTickResult, PhysicsSimulationState } from "./PhysicsPipelineStore";
+import { composePhysicsControllers } from "./PhysicsControllers";
+import type { PhysicsBodySelection, StreamPhysicsBodyForce, StreamPhysicsBodyForceContext, StreamPhysicsBodyRegionState, StreamPhysicsRegionEffect, StreamPhysicsRegionEffectContext, StreamPhysicsRegionVector, PhysicsSemanticItem, StreamPhysicsFrameProps } from "./StreamPhysicsTypes";
+/** Internal region bookkeeping (Sets for O(1) membership). */
+export interface InternalStreamPhysicsBodyRegionState {
+    activeRegionIds: Set<string>;
+    regionIds: Set<string>;
+    charges: Record<string, unknown>;
+    attributes: Record<string, unknown>;
+    energy: number;
+}
+export declare function isSelected(body: PhysicsBodyState, selection: PhysicsBodySelection | null | undefined): boolean;
+export declare function regionSensorId(region: StreamPhysicsRegionEffect): string;
+export declare function regionBoundaryColliders(region: StreamPhysicsRegionEffect): PhysicsColliderSpec[];
+export declare function publicRegionState(state: InternalStreamPhysicsBodyRegionState | undefined): StreamPhysicsBodyRegionState | undefined;
+export declare function cloneRegionStateSnapshot(state: Map<string, InternalStreamPhysicsBodyRegionState>): Record<string, StreamPhysicsBodyRegionState>;
+export declare function ensureInternalRegionState(state: Map<string, InternalStreamPhysicsBodyRegionState>, bodyId: string): InternalStreamPhysicsBodyRegionState;
+export declare function resolveRegionVector(vector: StreamPhysicsRegionVector | ((context: StreamPhysicsRegionEffectContext) => StreamPhysicsRegionVector | null | undefined) | undefined, context: StreamPhysicsRegionEffectContext): StreamPhysicsRegionVector | null;
+export declare function mergeRegionAttributes(region: StreamPhysicsRegionEffect, context: StreamPhysicsRegionEffectContext, state: InternalStreamPhysicsBodyRegionState): void;
+export declare function resolveRegionCharge(region: StreamPhysicsRegionEffect, context: StreamPhysicsRegionEffectContext): unknown;
+export declare function regionToSemanticItem(region: StreamPhysicsRegionEffect): PhysicsSemanticItem | null;
+export declare function regionRuntimeEffectsRequireSync(regionEffects: readonly StreamPhysicsRegionEffect[]): boolean;
+export declare function applyActiveRegionEffects(controls: PhysicsPipelineControlSurface, regionEffects: readonly StreamPhysicsRegionEffect[], regionState: Map<string, InternalStreamPhysicsBodyRegionState>, dtSeconds: number): boolean;
+export declare function resolveBodyForceVector(force: StreamPhysicsBodyForce | undefined, context: StreamPhysicsBodyForceContext): StreamPhysicsRegionVector | null;
+export declare function applyBodyForces(controls: PhysicsPipelineControlSurface, bodyForces: StreamPhysicsBodyForce | undefined, regionEffects: readonly StreamPhysicsRegionEffect[], regionState: Map<string, InternalStreamPhysicsBodyRegionState>, simulationState: PhysicsSimulationState, dtSeconds: number): boolean;
+/**
+ * Shared post-tick pipeline: region forces → body forces → controllers → onTick.
+ * Used by the main RAF path and the worker-fallback path (DRY + one snapshot).
+ */
+export declare function runPhysicsPostTick(options: {
+    store: PhysicsPipelineStore;
+    result: PhysicsPipelineTickResult;
+    regionEffects: readonly StreamPhysicsRegionEffect[];
+    regionState: Map<string, InternalStreamPhysicsBodyRegionState>;
+    bodyForces: StreamPhysicsBodyForce | undefined;
+    composed: ReturnType<typeof composePhysicsControllers>;
+    onTick?: (result: PhysicsPipelineTickResult, controls: PhysicsPipelineControlSurface) => void;
+}): {
+    regionEffectsApplied: boolean;
+    bodyForcesApplied: boolean;
+    snapshot: ReturnType<PhysicsPipelineStore["snapshot"]>;
+};
+export declare function resolveStyle(body: PhysicsBodyState, simulationState: PhysicsSimulationState, bodyStyle: StreamPhysicsFrameProps["bodyStyle"], selectedBodyStyle: StreamPhysicsFrameProps["selectedBodyStyle"], selection: StreamPhysicsFrameProps["selection"], regionState: StreamPhysicsBodyRegionState | undefined, activeRegions: StreamPhysicsRegionEffect[], fallbackFill: string, fallbackStroke: string, primitives?: {
+    color?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+}): Style;

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

@@ -0,0 +1,20 @@
+/**
+ * Physics frame semantic items, default tooltip, and accessible data table.
+ */
+import * as React from "react";
+import type { PhysicsBodyState } from "./PhysicsKernel";
+import type { PhysicsSimulationState } from "./PhysicsPipelineStore";
+import type { PhysicsHoverData, PhysicsSemanticItem, StreamPhysicsFrameProps } from "./StreamPhysicsTypes";
+export declare const SR_ONLY_STYLE: React.CSSProperties;
+declare function physicsHoverData(body: PhysicsBodyState): PhysicsHoverData;
+declare function createBodySemanticItems(bodies: readonly PhysicsBodyState[], simulationState: PhysicsSimulationState, bodySemanticItems: StreamPhysicsFrameProps["bodySemanticItems"], limit: number): PhysicsSemanticItem[];
+declare function semanticItemsChanged(previous: readonly PhysicsSemanticItem[], next: readonly PhysicsSemanticItem[]): boolean;
+declare function DefaultPhysicsTooltip({ hover }: {
+    hover: PhysicsHoverData;
+}): React.ReactElement;
+declare function PhysicsSemanticDataTable(props: {
+    chartTitle?: string;
+    items: readonly PhysicsSemanticItem[];
+    tableId: string;
+}): React.ReactElement;
+export { physicsHoverData, createBodySemanticItems, semanticItemsChanged, DefaultPhysicsTooltip, PhysicsSemanticDataTable };

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

@@ -0,0 +1,18 @@
+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;
+    requestRender: () => void;
+    storeRef: RefObject<PhysicsPipelineStore | null>;
+    suspendWhenHidden: boolean;
+}
+/** Keep pause and page-visibility scheduling policy consistent for physics frames. */
+export declare function usePhysicsFrameLifecyclePolicy({ cancelRender, frameRuntime, lastFrameTimeRef, paused, postWorkerCommand, requestRender, storeRef, suspendWhenHidden }: PhysicsFrameLifecyclePolicyInput): void;
+export {};

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

@@ -0,0 +1,26 @@
+import { RingBuffer } from "../realtime/RingBuffer";
+/**
+ * Resize a data buffer and its optional timestamp companion to fit a bounded
+ * replacement dataset. Keeps timestamp/data indices aligned for pulse logic.
+ */
+export declare function ensureRingBufferCapacity<T>(buffer: RingBuffer<T>, targetSize: number, timestampBuffer?: RingBuffer<number> | null): void;
+/**
+ * Create a timestamp companion for data that predates pulse tracking.
+ *
+ * A pulse buffer is indexed in lockstep with the datum buffer. When pulse is
+ * enabled after mount, an empty companion would make the next inserted datum
+ * line up with the *oldest* retained datum. Seed every retained row at the
+ * activation time instead, so the two rings start aligned and the newly
+ * enabled encoding has a coherent first frame.
+ */
+export declare function createTimestampBufferForData<T>(buffer: RingBuffer<T>, timestamp: number): RingBuffer<number>;
+/**
+ * Push a datum and its ingest timestamp in lockstep. Returns any evicted datum
+ * from the data buffer so callers can update extents/categories.
+ */
+export declare function pushWithTimestamp<T>(buffer: RingBuffer<T>, datum: T, timestampBuffer: RingBuffer<number> | null | undefined, timestamp: number): T | undefined;
+/**
+ * Compact a timestamp ring buffer before removing matching rows from the data
+ * ring buffer. The predicate must be the same one passed to `buffer.remove()`.
+ */
+export declare function compactTimestampBufferForRemoval<T>(buffer: RingBuffer<T>, timestampBuffer: RingBuffer<number> | null | undefined, predicate: (item: T) => boolean): void;

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

@@ -0,0 +1,179 @@
+/**
+ * PipelineStore configuration types + growing-window capacity constants.
+ */
+import type { Datum } from "../charts/shared/datumTypes";
+import type { StreamChartType, ArrowOfTime, WindowMode, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, CurveType, BarStyle, ThemeSemanticColors, BandConfig, CandlestickStyle, Style } from "./types";
+import type { SymbolName } from "./symbolPath";
+import type { CoercibleNumber } from "./accessorUtils";
+import type { CustomLayout } from "./customLayout";
+import type { CustomLayoutSelection } from "./customLayoutSelection";
+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;
+    extentPadding: number;
+    /** Pixel inset on scale ranges to prevent glyph clipping at chart edges. Default 0. */
+    scalePadding?: number;
+    /** When `"exact"`, the x and y axis domains pin to the literal data
+     *  min/max — `extentPadding` is skipped so the first and last ticks
+     *  read as the actual data bounds. Default `"nice"` keeps the existing
+     *  padded domain so glyphs at the extremes don't clip the plot edge. */
+    axisExtent?: import("../charts/shared/axisExtent").AxisExtentMode;
+    /**
+     * Hard cap for `windowMode: "growing"`. Defaults to
+     * {@link DEFAULT_GROWING_MAX_CAPACITY} (100_000). Canvas scene graphs
+     * degrade well before the previous 1e6 ceiling; pass a higher value
+     * only when you know the host can afford it.
+     */
+    maxCapacity?: number;
+    xAccessor?: string | ((d: Datum) => CoercibleNumber);
+    yAccessor?: string | ((d: Datum) => CoercibleNumber);
+    timeAccessor?: string | ((d: Datum) => CoercibleNumber);
+    valueAccessor?: string | ((d: Datum) => CoercibleNumber);
+    colorAccessor?: string | ((d: Datum) => string);
+    sizeAccessor?: string | ((d: Datum) => CoercibleNumber);
+    /** Categorical accessor → glyph shape (scatter/bubble). Emits SymbolSceneNodes. */
+    symbolAccessor?: string | ((d: Datum) => string);
+    /** Explicit `{category → shape}` map; unmapped categories auto-assign. */
+    symbolMap?: Record<string, SymbolName>;
+    groupAccessor?: string | ((d: Datum) => string);
+    categoryAccessor?: string | ((d: Datum) => string);
+    lineDataAccessor?: string;
+    /**
+     * Escape hatch for the unusual case where a *stable* function accessor's
+     * captured semantics change without its identity changing (e.g. a
+     * `useCallback([])`-memoized closure that reads external mutable state).
+     * Accessor equality is identity-based, so such a change is invisible to the
+     * store. Bump this number to force the store to re-derive domains and rebuild
+     * the scene against the current accessor. Prefer changing the accessor
+     * identity (add the captured value to the `useCallback` dependency array);
+     * reach for `accessorRevision` only when you cannot. */
+    accessorRevision?: number;
+    xScaleType?: "linear" | "log" | "time";
+    yScaleType?: "linear" | "log" | "symlog";
+    xExtent?: [number | undefined, number | undefined] | [number];
+    yExtent?: [number | undefined, number | undefined] | [number];
+    sizeRange?: [number, number];
+    binSize?: number;
+    normalize?: boolean;
+    /** Stacked area baseline mode. Only consulted by stackedarea chart type. */
+    baseline?: "zero" | "wiggle" | "silhouette" | "diverging";
+    /** Stack order — see StreamXYFrameProps.stackOrder. */
+    stackOrder?: "key" | "input" | "insideOut" | "asc" | "desc";
+    openAccessor?: string | ((d: Datum) => CoercibleNumber);
+    highAccessor?: string | ((d: Datum) => CoercibleNumber);
+    lowAccessor?: string | ((d: Datum) => CoercibleNumber);
+    closeAccessor?: string | ((d: Datum) => CoercibleNumber);
+    candlestickStyle?: CandlestickStyle;
+    /** Internal: set by PipelineStore when open/close accessors are both missing */
+    candlestickRangeMode?: boolean;
+    boundsAccessor?: string | ((d: Datum) => CoercibleNumber);
+    boundsStyle?: Style | ((d: Datum, group?: string) => Style);
+    y0Accessor?: string | ((d: Datum) => CoercibleNumber);
+    band?: BandConfig | BandConfig[];
+    gradientFill?: {
+        topOpacity: number;
+        bottomOpacity: number;
+    } | {
+        colorStops: Array<{
+            offset: number;
+            color: string;
+        }>;
+    };
+    areaGroups?: Set<string>;
+    lineGradient?: {
+        colorStops: Array<{
+            offset: number;
+            color: string;
+        }>;
+    };
+    lineStyle?: Style | ((d: Datum, group?: string) => Style);
+    pointStyle?: (d: Datum) => Style & {
+        r?: number;
+    };
+    areaStyle?: (d: Datum) => Style;
+    swarmStyle?: {
+        radius?: number;
+        fill?: string;
+        opacity?: number;
+        stroke?: string;
+        strokeWidth?: number;
+    };
+    waterfallStyle?: {
+        positiveColor?: string;
+        negativeColor?: string;
+        connectorStroke?: string;
+        connectorWidth?: number;
+        gap?: number;
+        stroke?: string;
+        strokeWidth?: number;
+    };
+    colorScheme?: string | string[] | Record<string, string>;
+    /** Theme categorical palette — used as fallback when colorScheme is not an explicit array */
+    themeCategorical?: string[];
+    /**
+     * Theme-resolved semantic role colors. Scene builders use these as the
+     * default before falling back to hardcoded hex. Populated by the Stream
+     * Frame from the in-memory `SemioticTheme.colors` object at render time
+     * — the values are concrete hex (or whatever the preset declares), not
+     * `var(...)` strings, and so this channel does NOT participate in the
+     * DOM CSS cascade. Changing the ambient theme (`<ThemeProvider>`) or
+     * swapping to a nested provider is how you override these values.
+     *
+     * Per-scope overrides via CSS custom properties
+     * (e.g. `<div style={{ "--semiotic-danger": "#c00" }}>`) work only for
+     * values a user explicitly passes through as `var(--...)` strings in
+     * chart props — those are resolved via `getComputedStyle` in the
+     * canvas renderer at paint time (see `resolveCSSColor.ts`). The theme
+     * defaults in this field don't read CSS.
+     */
+    themeSemantic?: ThemeSemanticColors;
+    /** Theme sequential scheme name (e.g. "blues") — fallback when `colorScheme` is not explicitly set for magnitude encodings (heatmap, choropleth, size). */
+    themeSequential?: string;
+    /** Theme diverging scheme name (e.g. "RdBu") — fallback when `colorScheme` is not explicitly set for midpoint encodings (likert, bivariate, ± deviation). */
+    themeDiverging?: string;
+    barColors?: Record<string, string>;
+    /** Histogram bar style — fill/stroke/strokeWidth/gap. Accepted by RealtimeHistogram and routed through to the bar scene builder. */
+    barStyle?: BarStyle;
+    annotations?: Datum[];
+    decay?: DecayConfig;
+    pulse?: PulseConfig;
+    transition?: TransitionConfig;
+    /** Whether to animate elements on first render (points scale up, lines/areas clip from left, rects grow from baseline) */
+    introAnimation?: boolean;
+    staleness?: StalenessConfig;
+    heatmapAggregation?: "count" | "sum" | "mean";
+    heatmapXBins?: number;
+    heatmapYBins?: number;
+    showValues?: boolean;
+    heatmapValueFormat?: (v: number) => string;
+    pointIdAccessor?: string | ((d: Datum) => string);
+    curve?: CurveType;
+    /** When provided, replaces chart-type dispatch in scene building.
+     *  Receives a LayoutContext (scales, dimensions, theme, resolveColor)
+     *  and returns scene nodes plus optional overlays. */
+    customLayout?: CustomLayout;
+    /** Called when `customLayout` throws. The previous successful custom scene
+     * remains visible when one exists; inspect the diagnostic's `recovery` to
+     * distinguish that case from an initial empty-scene failure. */
+    onLayoutError?: (diagnostic: import("./customLayoutFailure").CustomLayoutFailureDiagnostic) => void;
+    /** User-supplied config blob threaded through to LayoutContext.config. */
+    layoutConfig?: object;
+    /** Resolved margin — passed through so LayoutContext.dimensions.margin reflects what the frame actually used. */
+    layoutMargin?: MarginType;
+    /** Resolved shared selection projected into LayoutContext.selection. Owned by
+     *  a dedicated frame effect (kept off the rebuild-triggering path). */
+    layoutSelection?: CustomLayoutSelection | null;
+}
+/** Default hard cap for `windowMode: "growing"`. */
+export declare const DEFAULT_GROWING_MAX_CAPACITY = 100000;
+/**
+ * Dev-only warning threshold: when a growing buffer first crosses this
+ * size we log once so unbounded push loops surface before the hard cap.
+ */
+export declare const GROWING_CAPACITY_WARN_THRESHOLD = 50000;

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

@@ -1,9 +1,14 @@
-import type { Datum } from "../charts/shared/datumTypes";
+import type { Datum, DatumValue } from "../charts/shared/datumTypes";
 /**
  * Shared decay encoding utilities for all pipeline stores.
  *
  * `computeDecayOpacity()` — core algorithm used by all four pipeline stores
- * (XY, Ordinal, Network, Geo) to compute age-based opacity.
+ * (XY, Ordinal, Network, Geo) to compute age-based opacity. It is the
+ * buffer-index projection of the runtime-neutral `opacityFromAge` age→opacity
+ * ramp: streaming decay is just "age measured in buffer positions", where the
+ * oldest surviving datum sits `bufferSize - 1` positions behind the newest.
+ * Keeping one ramp implementation means the streaming runtime, physics
+ * bodies, and any future age-based encoding share the exact same curves.
  *
  * `applyDecay()` — XY-specific application that handles per-vertex decay
  * for line/area nodes. Other stores call `computeDecayOpacity()` directly
@@ -13,10 +18,23 @@ import type { SceneNode, DecayConfig } from "./types";
 /**
  * Compute decay opacity for a datum at `bufferIndex` out of `bufferSize` items.
  * Index 0 = oldest, bufferSize-1 = newest. Returns 0–1.
+ *
+ * Delegates to the shared {@link opacityFromAge} ramp with age expressed in
+ * buffer positions (`age = 0` at the newest datum, `extent = bufferSize - 1`
+ * at the oldest). The buffer-based half-life / step defaults are passed
+ * explicitly so the streaming ramp is unchanged from its standalone form.
  */
 export declare function computeDecayOpacity(decay: DecayConfig, bufferIndex: number, bufferSize: number): number;
+/**
+ * Build a datum→buffer-index map. Callers that apply decay + pulse in the
+ * same scene pass should share one map (and cache it by ingest version)
+ * so continuous animation does not re-walk the buffer twice per frame.
+ */
+export declare function buildDatumIndexMap(data: readonly Datum[]): Map<Datum, number>;
 /**
  * Apply decay opacity to a list of scene nodes.
  * Uses the datum's index in the buffer data array.
+ *
+ * @param indexMap Optional prebuilt datum→index map (see {@link buildDatumIndexMap}).
  */
-export declare function applyDecay(decay: DecayConfig, nodes: SceneNode[], data: Datum[]): void;
+export declare function applyDecay(decay: DecayConfig, nodes: SceneNode[], data: Datum[], indexMap?: Map<DatumValue, number>): void;

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

@@ -0,0 +1,62 @@
+/**
+ * Pure domain / scale resolution for PipelineStore.computeScene.
+ * Chart-type-specific y-extent rules + d3 scale construction.
+ */
+import { type ScaleLinear } from "d3-scale";
+import type { Datum } from "../charts/shared/datumTypes";
+import type { PipelineConfig } from "./pipelineConfig";
+import type { ArrowOfTime, StreamScales } from "./types";
+import type { ResolvedRibbon } from "./xySceneBuilders/ribbonScene";
+import type { RingBuffer } from "../realtime/RingBuffer";
+export type StackExtentCache = {
+    key: string;
+    yDomain: [number, number];
+};
+export declare function getTimeAxis(arrowOfTime: ArrowOfTime): "x" | "y";
+export declare function mergePartialDomain(dataDomain: [number, number], userExtent: [number | undefined, number | undefined] | [number] | undefined): [number, number];
+export declare function isFullySpecifiedExtent(extent: [number | undefined, number | undefined] | [number] | undefined): boolean;
+/**
+ * Stacked-area y-domain covering cumulative stack sums (or [0,1] when
+ * normalized). Mirrors buildStackedAreaNodes order for wiggle offsets.
+ */
+export declare function resolveStackedAreaYDomain(options: {
+    config: Pick<PipelineConfig, "normalize" | "baseline" | "stackOrder" | "extentPadding" | "axisExtent">;
+    groups: {
+        key: string;
+        data: Datum[];
+    }[];
+    getX: (d: Datum) => number;
+    getY: (d: Datum) => number;
+    bufferSize: number;
+    ingestVersion: number;
+    stackExtentCache: StackExtentCache | null;
+}): {
+    yDomain: [number, number];
+    stackExtentCache: StackExtentCache;
+};
+export declare function resolveBarBinYDomain(buffer: RingBuffer<Datum>, getX: (d: Datum) => number, getY: (d: Datum) => number, binSize: number, getCategory: ((d: Datum) => string) | undefined, extentPadding: number, exactMode: boolean): [number, number];
+export declare function resolveWaterfallYDomain(buffer: RingBuffer<Datum>, getY: (d: Datum) => number, extentPadding: number, exactMode: boolean): [number, number];
+export declare function expandYDomainWithRibbons(yDomain: [number, number], bufferArray: Datum[], ribbons: ResolvedRibbon[]): [number, number];
+export declare function padYDomain(yDomain: [number, number], options: {
+    exactMode: boolean;
+    extentPadding: number;
+    userMin?: number;
+    userMax?: number;
+    yScaleType?: PipelineConfig["yScaleType"];
+    dataYDomain: [number, number];
+}): [number, number];
+export declare function reapplyPartialYExtent(yDomain: [number, number], yExtent: PipelineConfig["yExtent"], yFullySpecified: boolean): [number, number];
+export declare function rescueDegenerateDomains(xDomain: [number, number], yDomain: [number, number], xScaleType?: PipelineConfig["xScaleType"]): {
+    xDomain: [number, number];
+    yDomain: [number, number];
+};
+export declare function makePipelineScale(type: "linear" | "log" | "symlog" | "time" | undefined, domain: [number, number], range: [number, number]): ScaleLinear<number, number>;
+export declare function buildPipelineScales(options: {
+    config: PipelineConfig;
+    layout: {
+        width: number;
+        height: number;
+    };
+    xDomain: [number, number];
+    yDomain: [number, number];
+}): StreamScales;

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

@@ -0,0 +1,26 @@
+/**
+ * Shared identity-keyed mutation helpers for family pipeline stores.
+ *
+ * XY/Ordinal/Network stores each own their buffers, but remove/update by
+ * stable id follow the same shape: resolve ids → scan buffer → rebuild.
+ * Centralizing the pure scan logic keeps behavior aligned without forcing
+ * a single mega-class.
+ */
+import type { Datum } from "../charts/shared/datumTypes";
+export declare function toIdSet(id: string | string[]): Set<string>;
+/**
+ * Remove rows whose id is in `ids`. Returns `{ kept, removed }` where
+ * `kept` preserves original order.
+ */
+export declare function partitionById(data: readonly Datum[], ids: Set<string>, getId: (d: Datum) => string): {
+    kept: Datum[];
+    removed: Datum[];
+};
+/**
+ * Apply an updater to rows matching `ids`. Returns updated rows (the new
+ * objects) and the full next array (order preserved).
+ */
+export declare function updateById(data: readonly Datum[], ids: Set<string>, getId: (d: Datum) => string, updater: (d: Datum) => Datum): {
+    next: Datum[];
+    updated: Datum[];
+};

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.
  *
@@ -17,9 +17,23 @@ import type { RingBuffer } from "../realtime/RingBuffer";
 export declare function computePulseIntensity(pulse: PulseConfig, insertTime: number, now: number): number;
 /**
  * Apply pulse glow to scene nodes using insertion timestamps.
+ *
+ * @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<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
+ * which do not map back to a datum are left entirely alone, including any
+ * user-owned underscore fields they may carry.
  */
-export declare function applyPulse(pulse: PulseConfig, nodes: SceneNode[], data: Datum[], timestampBuffer: RingBuffer<number>): void;
+export declare function setPulseState(node: {
+    _pulseIntensity?: number;
+    _pulseColor?: string;
+    _pulseGlowRadius?: number;
+}, intensity: number, pulseColor: string, glowRadius?: number): boolean;
 /**
  * Check whether there are active pulse animations needing continuous rendering.
  */
-export declare function hasActivePulses(pulse: PulseConfig, timestampBuffer: RingBuffer<number> | null): boolean;
+export declare function hasActivePulses(pulse: PulseConfig, timestampBuffer: RingBuffer<number> | null, now?: number): boolean;

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

@@ -0,0 +1,41 @@
+/**
+ * Ribbon resolution — compose `boundsAccessor` + `band` into ResolvedRibbon[].
+ * Extracted from PipelineStore so scene builders / tests can reuse without
+ * the full store class.
+ */
+import type { Datum } from "../charts/shared/datumTypes";
+import type { BandConfig, StreamChartType, Style } from "./types";
+import type { ResolvedRibbon } from "./xySceneBuilders/ribbonScene";
+import { type CoercibleNumber } from "./accessorUtils";
+/**
+ * Minimal config surface required to resolve envelope ribbons.
+ * Full PipelineConfig satisfies this; kept narrow for pure helpers.
+ */
+export interface RibbonResolveConfig {
+    chartType: StreamChartType;
+    runtimeMode?: "streaming" | "bounded";
+    valueAccessor?: string | ((d: Datum) => CoercibleNumber);
+    yAccessor?: string | ((d: Datum) => CoercibleNumber);
+    boundsAccessor?: string | ((d: Datum) => CoercibleNumber);
+    boundsStyle?: Style | ((d: Datum, group?: string) => Style);
+    band?: BandConfig | BandConfig[];
+}
+/**
+ * Read a value off a datum preserving null/undefined as NaN so ribbon
+ * gap semantics work. `resolveAccessor` coerces null→0 via unary `+`,
+ * which would silently produce a "valid" 0 baseline for missing data —
+ * fine for primary y values, wrong for envelope edges.
+ */
+export declare function resolveRibbonValueAccessor(accessor: string | ((d: Datum) => CoercibleNumber) | undefined, fallback: string): (d: Datum) => number;
+/**
+ * Compose the full ribbon list from both public envelope APIs:
+ * `boundsAccessor` (symmetric ±offset) and `band` (asymmetric pairs).
+ * Bounds is prepended so it paints furthest back when both are set on
+ * the same chart. Both surfaces share scene-builder, y-extent, and
+ * style-cascade machinery — only the resolution differs.
+ *
+ * Both APIs use null-preserving accessors (NaN for null/undefined) so
+ * the unified `buildRibbonForGroup` can rely on a single
+ * `Number.isFinite` check to skip gap datums.
+ */
+export declare function resolveRibbons(config: RibbonResolveConfig): ResolvedRibbon[];

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

@@ -0,0 +1,12 @@
+import { type Quadtree } from "d3-quadtree";
+import type { PipelineConfig } from "./pipelineConfig";
+import type { PointSceneNode, SceneNode } from "./types";
+/** Retained point-scene spatial index used by PipelineStore hit testing. */
+export declare class PipelineSpatialIndex {
+    private maxRadius;
+    private tree;
+    get quadtree(): Quadtree<PointSceneNode> | null;
+    get maxPointRadius(): number;
+    clear(): void;
+    rebuild(chartType: PipelineConfig["chartType"], scene: SceneNode[]): void;
+}

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

@@ -0,0 +1,33 @@
+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[]): UpdateResult;
+}
+export {};