semiotic 3.7.5 → 3.8.0

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

@@ -0,0 +1,177 @@
+/**
+ * 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";
+    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?: any;
+    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?: any;
+    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

@@ -3,7 +3,12 @@ import type { Datum } 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<any, 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

@@ -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<any, 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,12 @@
+import { type ChangeSet, type UpdateResult } from "./pipelineUpdateContract";
+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;
+    recordData(kind: DataChangeKind, count?: number): UpdateResult;
+    recordNoop(kind: DataChangeKind | "restyle"): UpdateResult;
+    recordRestyle(hasCustomRestyle: boolean): UpdateResult;
+    recordConfig(keys: readonly string[], requiresRebuild: boolean, extentAccessorChanged: boolean): UpdateResult;
+}
+export {};

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

@@ -0,0 +1,46 @@
+/**
+ * Pure style / color-map resolution helpers for PipelineStore.
+ * Accept a small context object so the store methods stay thin wrappers.
+ */
+import type { Datum } from "../charts/shared/datumTypes";
+import type { PipelineConfig } from "./pipelineConfig";
+import type { Style } from "./types";
+export interface PipelineColorMapCache {
+    key: string;
+    map: Map<string, string>;
+    version: number;
+}
+export interface PipelineGroupDataCache {
+    version: number;
+    group: ((d: Datum) => string) | undefined;
+    data: Datum[];
+    result: {
+        key: string;
+        data: Datum[];
+    }[];
+}
+export declare function groupPipelineData(data: Datum[], getGroup: ((d: Datum) => string) | undefined, ingestVersion: number, cache: PipelineGroupDataCache | null): {
+    result: {
+        key: string;
+        data: Datum[];
+    }[];
+    cache: PipelineGroupDataCache;
+};
+export declare function resolvePipelineColorMap(data: Datum[], getColor: ((d: Datum) => string) | undefined, config: Pick<PipelineConfig, "colorScheme" | "themeCategorical">, ingestVersion: number, cache: PipelineColorMapCache | null): {
+    map: Map<string, string>;
+    cache: PipelineColorMapCache;
+};
+export declare function resolvePipelineGroupColor(options: {
+    group: string;
+    colorMapCache: PipelineColorMapCache | null;
+    groupColorMap: Map<string, string>;
+    groupColorCounter: number;
+    groupColorMapCap: number;
+    config: Pick<PipelineConfig, "colorScheme" | "themeCategorical">;
+}): {
+    color: string | null;
+    groupColorCounter: number;
+};
+export declare function resolvePipelineLineStyle(config: PipelineConfig, group: string, sampleDatum: Datum | undefined, resolveGroupColor: (group: string) => string | null): Style;
+export declare function resolvePipelineAreaStyle(config: PipelineConfig, group: string, sampleDatum: Datum | undefined, resolveGroupColor: (group: string) => string | null): Style;
+export declare function resolvePipelineBoundsStyle(config: PipelineConfig, group: string, sampleDatum: Datum | undefined, resolveLineStyle: (group: string, sampleDatum?: Datum) => Style): Style;

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

@@ -11,6 +11,7 @@
  * Consumed by: PipelineStore.computeScene (after decay/pulse)
  */
 import type { SceneNode, TransitionConfig } from "./types";
+import type { GlyphDef } from "./glyphDef";
 import type { ActiveTransition } from "./pipelineTransitionUtils";
 import type { Datum } from "../charts/shared/datumTypes";
 export type PrevPosition = {
@@ -24,6 +25,7 @@ export type PrevPosition = {
     closeY?: number;
     highY?: number;
     lowY?: number;
+    glyph?: GlyphDef;
 };
 export type PrevPath = {
     topPath?: [number, number][];

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

@@ -0,0 +1,62 @@
+/**
+ * Pure update contract for the stream-pipeline migration pilot.
+ *
+ * Stores still expose their established boolean/void mutation APIs. This
+ * module gives a host an additive, inspectable result path without coupling it
+ * to React, canvas, timers, or a particular chart family.
+ */
+/** Reasons a host may need to recompute or repaint part of a chart. */
+export declare const INVALIDATION_KINDS: readonly ["data", "domain", "layout", "scene-geometry", "scene-style", "data-paint", "interaction-paint", "overlay", "accessibility", "evidence"];
+export type Invalidation = (typeof INVALIDATION_KINDS)[number];
+/**
+ * Describes the operation that produced an update without retaining raw data
+ * or user callbacks in a diagnostic/result object.
+ */
+export interface ChangeSet {
+    readonly kind: "initialize" | "ingest" | "replace" | "remove" | "update" | "clear" | "config" | "restyle" | "enqueue" | "tick" | "settle" | "restore" | "constraint" | "impulse" | "pause" | "visibility";
+    readonly keys?: readonly string[];
+    readonly count?: number;
+}
+/**
+ * Monotonic revision counters. A host can consume only the counters relevant
+ * to its work (for example a canvas data layer observes `dataPaint`, while an
+ * accessibility tree observes `accessibility`).
+ */
+export interface RevisionSet {
+    readonly data: number;
+    readonly domain: number;
+    readonly layout: number;
+    readonly sceneGeometry: number;
+    readonly sceneStyle: number;
+    readonly dataPaint: number;
+    readonly interactionPaint: number;
+    readonly overlay: number;
+    readonly accessibility: number;
+    readonly evidence: number;
+}
+/** The additive result exposed by the XY PipelineStore reference path. */
+export interface UpdateResult {
+    readonly changeSet: ChangeSet;
+    readonly changed: ReadonlySet<Invalidation>;
+    readonly revisions: RevisionSet;
+}
+export declare function createRevisionSet(): RevisionSet;
+/** Return a fresh revision snapshot with exactly the invalidated counters bumped. */
+export declare function advanceRevisions(previous: RevisionSet, invalidations: Iterable<Invalidation>): RevisionSet;
+/**
+ * Build an immutable-by-convention update record from a change description.
+ * The Set is copied so later mutation of the caller's iterable cannot alter
+ * the revision decision that was recorded.
+ */
+export declare function createUpdateResult(changeSet: ChangeSet, invalidations: Iterable<Invalidation>, previousRevisions: RevisionSet): UpdateResult;
+/**
+ * Small retained-state helper for stores adopting the result contract. It
+ * keeps revision bookkeeping out of family-specific data/layout code while
+ * preserving each store's existing mutation API.
+ */
+export declare class UpdateResultTracker {
+    private revisions;
+    private latest;
+    get last(): UpdateResult;
+    record(changeSet: ChangeSet, invalidations: Iterable<Invalidation>): UpdateResult;
+}

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

@@ -0,0 +1,22 @@
+/** Minimal surface shared by stream frames for idle pulse repainting. */
+export interface PulseRefreshStore {
+    lastCustomLayoutFailure?: {
+        preservedLastGoodScene?: boolean;
+    } | null;
+    hasActivePulsesAt(now: number): boolean;
+    refreshPulse(now: number): boolean;
+}
+export interface IdlePulseRefresh {
+    /** Whether the data canvas needs a style-only repaint this frame. */
+    changed: boolean;
+    /** Keep one subsequent frame so an expired glow can be cleared. */
+    pending: boolean;
+}
+/**
+ * Advance pulse styling without triggering a layout rebuild. A failed custom
+ * layout deliberately retains its last good scene, which must remain
+ * immutable until the layout owner recovers.
+ */
+export declare function refreshIdlePulse(store: PulseRefreshStore, now: number, sceneRecomputed: boolean, pendingRef: {
+    current: boolean;
+}): IdlePulseRefresh;

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

@@ -0,0 +1,6 @@
+import type { NetworkSceneNode } from "../networkTypes";
+import type { StreamRendererFn } from "./types";
+/** XY / ordinal / geo painter (x/y-positioned glyph nodes). */
+export declare const glyphCanvasRenderer: StreamRendererFn;
+/** Network painter (cx/cy-positioned glyph nodes). */
+export declare function networkGlyphRenderer(ctx: CanvasRenderingContext2D, nodes: NetworkSceneNode[]): void;

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

@@ -21,6 +21,12 @@ export declare function resolveCSSColor(ctx: CanvasRenderingContext2D, value: st
  * invalidation is global because theme changes are global.
  */
 export declare function clearCSSColorCache(_canvas?: HTMLCanvasElement): void;
+/**
+ * Monotonic version bumped by theme changes and `clearCSSColorCache`.
+ * Frames can cache derived theme color objects keyed by this value so
+ * paint loops avoid `getComputedStyle` on every rAF.
+ */
+export declare function getCSSColorCacheVersion(): number;
 /**
  * Test-only: reset all cache state, including disconnecting any installed
  * observer/matchMedia listeners. Required for test isolation — without it,

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

@@ -0,0 +1,18 @@
+import type { RevisionSet, UpdateResult } from "./pipelineUpdateContract";
+type SceneRevisionSet = Pick<RevisionSet, "sceneGeometry" | "layout" | "domain">;
+interface SceneRevisionCheck {
+    revisions: SceneRevisionSet;
+    signature: string;
+    sawSignals: boolean;
+    wasUnconsumed: boolean;
+    warnUnconsumed: boolean;
+}
+/** Development-only consumption and duplicate-compute diagnostics for an XY scene host. */
+export declare class SceneRevisionDiagnostics {
+    private lastConsumed;
+    private lastDuplicateWarning;
+    private lastUnconsumedWarning;
+    beforeCompute(updateResult: UpdateResult, isTransitioning: boolean): SceneRevisionCheck;
+    afterCompute(check: SceneRevisionCheck, computedScene: boolean, dimsChanged: boolean): void;
+}
+export {};

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

@@ -0,0 +1,37 @@
+import { type MutableRefObject } from "react";
+/**
+ * Push the memoized pipeline config into the scene store and repaint.
+ *
+ * `config` is memoized upstream (the frames' `stablePipelineConfig`), so this
+ * fires only on a real config change, never per render. Marks the scene dirty
+ * and repaints because style callbacks (pointStyle, areaStyle, …) carried in
+ * the config may have changed even when geometry did not.
+ */
+export declare function useConfigSync<C>(storeRef: MutableRefObject<{
+    updateConfig(config: C): void;
+} | null>, config: C, dirtyRef: MutableRefObject<boolean>, scheduleRender: () => void): void;
+/**
+ * Bridge a custom layout's resolved selection (`layoutSelection`) into the
+ * scene store and repaint.
+ *
+ * `layoutSelection` has no single home in a store: the custom-chart HOCs
+ * assemble it in React by merging local component state (hover-highlight,
+ * legend interaction) with the cross-chart selection store
+ * (`effectiveSelectionHook = hover ?? legend ?? activeSelection`). React owns
+ * that blended value.
+ *
+ * Kept OFF the rebuild path: when the layout returned a `restyle` callback a
+ * selection change re-applies styles to the existing scene and repaints (no
+ * relayout, no quadtree rebuild); otherwise it marks the scene dirty so a
+ * rebuild lets `ctx.selection` reach the layout. Either way the overlay subtree
+ * re-renders against the new selection via `CustomLayoutSelectionProvider`.
+ *
+ * The `lastSelectionRef` guard makes the write fire only on a real selection
+ * change (the HOCs already memoize `layoutSelection` on its `isActive`/
+ * `predicate` identity), never per render.
+ */
+export declare function useLayoutSelectionSync<S>(storeRef: MutableRefObject<{
+    setLayoutSelection(selection: S | null): void;
+    hasCustomRestyle: boolean;
+    restyleScene(selection: S | null): void;
+} | null>, layoutSelection: S | null | undefined, dirtyRef: MutableRefObject<boolean>, scheduleRender: () => void): void;