semiotic 3.7.5 → 3.8.0

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

@@ -16,17 +16,22 @@ import type { Datum } from "../charts/shared/datumTypes";
  * Consumed by: StreamOrdinalFrame (sole consumer).
  */
 import { type ScaleLinear } from "d3-scale";
-import { type Quadtree } from "d3-quadtree";
+import type { Quadtree } from "d3-quadtree";
 import type { OrdinalPipelineConfig, OrdinalScales, OrdinalSceneNode, OrdinalColumn, OrdinalLayout } from "./ordinalTypes";
 import type { Changeset, PointSceneNode } from "./types";
 import type { ActiveTransition } from "./pipelineTransitionUtils";
+import type { OrdinalLayoutResult } from "./ordinalCustomLayout";
 import type { CustomLayoutSelection } from "./customLayoutSelection";
+import { type CustomLayoutFailureDiagnostic } from "./customLayoutFailure";
+import type { UpdateResult } from "./pipelineUpdateContract";
 export declare class OrdinalPipelineStore {
     private buffer;
     private rExtent;
     /** Per-accessor extents for multiAxis mode */
     private rExtents;
     private config;
+    private windowSizeWarned;
+    private updateResults;
     private getO;
     private getR;
     /** All resolved rAccessors (length > 1 when multiAxis) */
@@ -57,6 +62,15 @@ export declare class OrdinalPipelineStore {
     columns: Record<string, OrdinalColumn>;
     /** Overlays returned from customLayout (consumed by StreamOrdinalFrame). */
     customLayoutOverlays: import("react").ReactNode;
+    /** Most recent custom layout result for host readback (`getCustomLayout()`).
+     *  Null before the first layout or without a custom layout. A failed rerun
+     *  keeps the last successful result while its scene remains recoverable. */
+    lastCustomLayoutResult: OrdinalLayoutResult | null;
+    /** Latest custom-layout failure for frame-handle readback. */
+    lastCustomLayoutFailure: CustomLayoutFailureDiagnostic | null;
+    /** Lets `computeScene` retain a prior scene without mutating it after an
+     * exception from `buildSceneNodes`. */
+    private _customLayoutFailedThisBuild;
     private _customLayoutDiagnosticsWarned;
     /** Per-frame restyle callback from the custom layout result (see OrdinalLayoutResult.restyle). */
     private _customRestyle;
@@ -67,7 +81,8 @@ export declare class OrdinalPipelineStore {
     version: number;
     /** Bumped whenever the buffer is mutated. Used to invalidate per-frame caches. */
     private _dataVersion;
-    private static readonly QUADTREE_THRESHOLD;
+    /** Materialized source data, cached for pulse/decay animation frames. */
+    private _bufferArrayCache;
     private _pointQuadtree;
     /** Largest visual point radius in the current scene. */
     private _maxPointRadius;
@@ -77,7 +92,14 @@ export declare class OrdinalPipelineStore {
     private _categoryIndexCache;
     private _hasRenderedOnce;
     constructor(config: OrdinalPipelineConfig);
+    /**
+     * Keep the optional pulse timestamp ring in lockstep with the datum ring.
+     * Enabling pulse after mount must seed timestamps for retained rows; an
+     * empty ring would associate later timestamps with the wrong datum index.
+     */
+    private syncPulseTimestampBuffer;
     ingest(changeset: Changeset): boolean;
+    ingestWithResult(changeset: Changeset): UpdateResult;
     private pushValueExtent;
     private evictValueExtent;
     /** For timeline type: resolve rAccessor as a [start, end] pair */
@@ -119,6 +141,12 @@ export declare class OrdinalPipelineStore {
     get maxPointRadius(): number;
     private applyDecay;
     private applyPulse;
+    /**
+     * Refresh only pulse-derived fields on the existing scene. This deliberately
+     * avoids a scene/layout rebuild on every rAF pulse tick.
+     */
+    refreshPulse(now: number): boolean;
+    hasActivePulsesAt(now: number): boolean;
     get hasActivePulses(): boolean;
     /** Synthesize a zero-state prevPositionMap for animated intro (first render). */
     private synthesizeIntroPositions;
@@ -136,7 +164,15 @@ export declare class OrdinalPipelineStore {
      * after the server already painted the chart.
      */
     cancelIntroAnimation(): void;
+    /**
+     * Materialize the ring buffer at most once per data version. Pulse decay
+     * ticks reuse this array and the datum/category index caches rather than
+     * allocating a fresh copy at animation-frame frequency.
+     */
+    private getBufferArray;
     getData(): Datum[];
+    /** Most recent additive update result for revision-aware hosts and tests. */
+    getLastUpdateResult(): UpdateResult;
     /**
      * Remove data items by ID. Requires dataIdAccessor to be configured.
      * Returns the removed items. Marks the store dirty for scene rebuild.
@@ -160,5 +196,13 @@ export declare class OrdinalPipelineStore {
      * No-op when the layout supplied no `restyle`.
      */
     restyleScene(selection: CustomLayoutSelection | null): void;
+    /**
+     * Re-derive every retained fact that depends on the category/value
+     * accessors. `updateConfig` can change an accessor without a subsequent
+     * ingest (the normal React path), so clearing only a cache would leave the
+     * next scene with an empty/stale domain against the existing buffer.
+     */
+    private rebuildAccessorDerivedState;
     updateConfig(config: Partial<OrdinalPipelineConfig>): void;
+    updateConfigWithResult(config: Partial<OrdinalPipelineConfig>): UpdateResult;
 }

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

@@ -1,160 +1,42 @@
 import type { Datum } from "../charts/shared/datumTypes";
-import { type Quadtree } from "d3-quadtree";
+/**
+ * PipelineStore — stateful pipeline for XY/streaming chart data.
+ *
+ * Owns: data ingestion (RingBuffer), extent tracking, scale computation,
+ * scene layout delegation (via xySceneBuilders/), transition animation,
+ * decay/pulse/staleness encoding, and quadtree spatial indexing.
+ *
+ * Scene building was extracted to xySceneBuilders/ — this store constructs
+ * an XYSceneContext and dispatches to the appropriate builder function.
+ *
+ * Key dependencies:
+ *   xySceneBuilders/ — per-chartType scene layout (line, area, point, etc.)
+ *   SceneGraph        — node constructors (buildLineNode, buildPointNode, etc.)
+ *   RingBuffer         — sliding window data storage
+ *   IncrementalExtent  — O(1) min/max tracking
+ *
+ * Consumed by: StreamXYFrame (sole consumer).
+ */
 import { RingBuffer } from "../realtime/RingBuffer";
-import type { Changeset, StreamChartType, StreamScales, StreamLayout, SceneNode, PointSceneNode, CandlestickStyle, Style, ArrowOfTime, WindowMode, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, CurveType, BarStyle, ThemeSemanticColors, BandConfig } from "./types";
-import type { SymbolName } from "./symbolPath";
-import { type CoercibleNumber } from "./accessorUtils";
-import type { ActiveTransition } from "./pipelineTransitionUtils";
+import type { Changeset, StreamScales, StreamLayout, SceneNode } from "./types";
+import { type ActiveTransition } from "./pipelineTransitionUtils";
 import type { ResolvedRibbon } from "./xySceneBuilders/ribbonScene";
-import type { CustomLayout } from "./customLayout";
+import type { LayoutResult } 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;
-    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;
-    xScaleType?: "linear" | "log" | "time";
-    yScaleType?: "linear" | "log";
-    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";
-    /** Stack order — see StreamXYFrameProps.stackOrder. */
-    stackOrder?: "key" | "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[];
-    /** 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;
-    /** 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;
-}
+import { type CustomLayoutFailureDiagnostic } from "./customLayoutFailure";
+import { type PipelineConfig } from "./pipelineConfig";
+import type { UpdateResult } from "./pipelineUpdateContract";
+export type { PipelineConfig } from "./pipelineConfig";
+export type { ChangeSet, Invalidation, RevisionSet, UpdateResult, } from "./pipelineUpdateContract";
+export { DEFAULT_GROWING_MAX_CAPACITY, GROWING_CAPACITY_WARN_THRESHOLD } from "./pipelineConfig";
 export declare class PipelineStore {
     private buffer;
     private xExtent;
     private yExtent;
     private config;
     private growingCap;
+    private growingCapacityWarned;
+    private windowSizeWarned;
     private getX;
     private getY;
     private getGroup;
@@ -206,17 +88,32 @@ export declare class PipelineStore {
     private _stackExtentCache;
     /** Monotonic counter incremented on each ingest — used as part of cache keys */
     private _ingestVersion;
+    /** Datum→index map for decay/pulse, cached by `_ingestVersion`. */
+    private _datumIndexCache;
     /** Cached materialized array from buffer.toArray() — only rebuilt when buffer changes */
     private _bufferArrayCache;
     /** True when the buffer has been mutated since last toArray() call */
     private _bufferDirty;
     private needsFullRebuild;
     private lastLayout;
+    private updateResults;
     scales: StreamScales | null;
     scene: SceneNode[];
     version: number;
     /** Overlays returned from customLayout (consumed by StreamXYFrame for SVGOverlay). */
     customLayoutOverlays: import("react").ReactNode;
+    /** The most recent custom layout result, exposed for host readback via the
+     *  frame handle's `getCustomLayout()` — so a page that needs the computed
+     *  placement (stats, inspectors) doesn't re-run the layout. Null before the
+     *  first layout or when no custom layout is set. A rerun failure preserves
+     *  this last successful result when it is safe to do so. */
+    lastCustomLayoutResult: LayoutResult | null;
+    /** Latest custom-layout failure for frame-handle readback. */
+    lastCustomLayoutFailure: CustomLayoutFailureDiagnostic | null;
+    /** Set only while `buildSceneNodes` is recovering from a layout exception.
+     * `computeScene` uses it to retain the previous scene/scales without applying
+     * a new transition, pulse, or decay pass to that retained output. */
+    private _customLayoutFailedThisBuild;
     private _customLayoutDiagnosticsWarned;
     /** Per-frame restyle callback from the custom layout result (see LayoutResult.restyle). */
     private _customRestyle;
@@ -226,14 +123,23 @@ export declare class PipelineStore {
     private _baseStyles;
     /** True when the x accessor returns Date objects (auto-detected on first data ingestion) */
     xIsDate: boolean;
-    private _quadtree;
-    /** Largest visual point radius in the current scene. The hit tester uses
-     *  this to widen its quadtree query so points with big radii (bubble) don't
-     *  fall outside the search region. */
-    private _maxPointRadius;
-    private static readonly QUADTREE_THRESHOLD;
+    private spatialIndex;
     constructor(config: PipelineConfig);
+    /**
+     * Keep pulse timestamps structurally coupled to the datum ring when pulse
+     * is changed after construction. A fresh timestamp ring must be seeded for
+     * already-retained data; otherwise the next push would be timestamp index 0
+     * while its datum is at the end of the data ring.
+     */
+    private syncPulseTimestampBuffer;
     private pushDatumYExtent;
+    /**
+     * Remove every y-domain contribution made by {@link pushDatumYExtent}.
+     * Keeping these paths paired is important: a ribbon/band can extend the
+     * visible domain beyond the point itself, so removing or replacing that
+     * datum must evict its envelope extrema too.
+     */
+    private evictDatumYExtent;
     private rebuildYExtent;
     private rebuildExtents;
     private _lastBoundedInsertsRef;
@@ -250,20 +156,14 @@ export declare class PipelineStore {
      * meaningful — streaming consumers don't pass the same array twice.
      */
     ingest(changeset: Changeset): boolean;
+    /** Additive explicit-result form of {@link ingest}; `ingest()` remains unchanged. */
+    ingestWithResult(changeset: Changeset): UpdateResult;
     /**
      * Recompute scales and scene graph for the current buffer contents.
      */
     computeScene(layout: StreamLayout): void;
-    /**
-     * Build or clear the quadtree spatial index for point scene nodes.
-     * Only built for scatter/bubble charts with >QUADTREE_THRESHOLD points.
-     */
-    private rebuildQuadtree;
-    /**
-     * Get the quadtree spatial index, if available.
-     * Returns null when chart type is not scatter/bubble or point count is below threshold.
-     */
-    get quadtree(): Quadtree<PointSceneNode> | null;
+    /** Get the retained point-scene spatial index, if available. */
+    get quadtree(): import("d3-quadtree").Quadtree<import("./types").PointSceneNode> | null;
     /** Largest visual point radius in the current scene. */
     get maxPointRadius(): number;
     /**
@@ -274,8 +174,12 @@ export declare class PipelineStore {
     private buildSceneNodes;
     private resolveBoundsStyle;
     computeDecayOpacity(bufferIndex: number, bufferSize: number): number;
+    private getDatumIndexMap;
     private applyDecay;
     private applyPulse;
+    /** Refresh pulse fields without rebuilding layout; retained custom scenes stay immutable. */
+    refreshPulse(now: number): boolean;
+    hasActivePulsesAt(now: number): boolean;
     get hasActivePulses(): boolean;
     private get transitionContext();
     private snapshotPositions;
@@ -317,13 +221,6 @@ export declare class PipelineStore {
     private resolveColorMap;
     private resolveLineStyle;
     private resolveAreaStyle;
-    /** Resolve a group name to a color from the cached color map or a dedicated group palette.
-     *  First checks _colorMapCache (populated by resolveColorMap when colorAccessor is set).
-     *  Falls back to _groupColorMap (insertion-order, never mutates _colorMapCache).
-     *
-     *  FIFO-evicts the oldest entry when the map exceeds `GROUP_COLOR_MAP_CAP`. The palette index
-     *  uses `_groupColorCounter` (monotonic, decoupled from map size) so eviction doesn't cause
-     *  new groups to collide with existing entries on a shrunk map. */
     private resolveGroupColor;
     /**
      * Return a cached materialized array of the buffer contents.
@@ -333,6 +230,8 @@ export declare class PipelineStore {
      */
     private getBufferArray;
     getData(): Datum[];
+    /** Most recent additive update result for revision-aware hosts and tests. */
+    getLastUpdateResult(): UpdateResult;
     /**
      * Remove data points by ID. Requires pointIdAccessor to be configured.
      * Returns the removed items. Marks the store dirty for scene rebuild.
@@ -360,11 +259,23 @@ export declare class PipelineStore {
      *  triggering one. The frame then either repaints (restyle) or rebuilds. */
     setLayoutSelection(selection: CustomLayoutSelection | null): void;
     private applyCustomRestyle;
+    /**
+     * "Styles changed, repaint the data canvas without rebuilding the scene."
+     * Set by {@link restyleScene}; consumed once per frame by the render loop.
+     * Kept separate from the dirty flag so a style-only selection change repaints
+     * without forcing a layout/scene rebuild (the point of the restyle fast path).
+     */
+    private _stylePaintPending;
+    /** Consume the style-only repaint signal (see {@link _stylePaintPending}). */
+    consumeStylePaintPending(): boolean;
     /**
      * Re-apply the custom layout's `restyle` to the existing scene for
      * `selection`, off each node's base style — no relayout, no quadtree rebuild
      * (positions are unchanged). No-op when the layout supplied no `restyle`.
+     * Flags a style-only repaint so the render loop redraws the mutated styles.
      */
     restyleScene(selection: CustomLayoutSelection | null): void;
     updateConfig(config: Partial<PipelineConfig>): void;
+    /** Additive explicit-result form of {@link updateConfig}. */
+    updateConfigWithResult(config: Partial<PipelineConfig>): UpdateResult;
 }

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

@@ -5,7 +5,7 @@ export declare function buildLineNode(data: Datum[], scales: StreamScales, xGet:
 export declare function buildAreaNode(data: Datum[], scales: StreamScales, xGet: (d: Datum) => number, yGet: (d: Datum) => number, baselineY: number, style: Style, group?: string, y0Get?: (d: Datum) => number): AreaSceneNode;
 /** Per-group-per-x stacked top values, keyed by group then x */
 export type StackedTops = Map<string, Map<number, number>>;
-export type StackBaseline = "zero" | "wiggle" | "silhouette";
+export type StackBaseline = "zero" | "wiggle" | "silhouette" | "diverging";
 /**
  * Compute per-x stack baseline offsets. Shared between scene rendering
  * (`buildStackedAreaNodes`) and extent computation (`PipelineStore`) so
@@ -17,8 +17,16 @@ export type StackBaseline = "zero" | "wiggle" | "silhouette";
  *   xValues   — sorted unique x values
  *   groupKeys — group keys in stacking order (same order both callers use)
  *   valueAt   — (groupKey, x) → group's value at x (0 if absent)
+ *
+ * `"diverging"` returns zero offsets — positives and negatives stack from
+ * y=0 independently inside {@link buildStackedAreaNodes}.
  */
 export declare function computeStackOffsets(xValues: number[], groupKeys: string[], valueAt: (groupKey: string, x: number) => number, baseline: StackBaseline): Map<number, number>;
+/**
+ * Diverging stack extent: positives accumulate above 0, negatives below.
+ * Shared by PipelineStore auto-extent and any host that needs matching bounds.
+ */
+export declare function computeDivergingStackExtent(xValues: number[], groupKeys: string[], valueAt: (groupKey: string, x: number) => number): [number, number];
 export declare function buildStackedAreaNodes(groups: {
     key: string;
     data: Datum[];

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

@@ -1,5 +1,5 @@
 import type { Datum } from "../charts/shared/datumTypes";
 import * as React from "react";
 import type { StreamGeoFrameProps, StreamGeoFrameHandle } from "./geoTypes";
-declare const StreamGeoFrame: React.ForwardRefExoticComponent<StreamGeoFrameProps<Datum> & React.RefAttributes<StreamGeoFrameHandle>>;
+declare const StreamGeoFrame: React.NamedExoticComponent<StreamGeoFrameProps<Datum> & React.RefAttributes<StreamGeoFrameHandle>>;
 export default StreamGeoFrame;

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

@@ -1,5 +1,5 @@
 import type { Datum } from "../charts/shared/datumTypes";
 import * as React from "react";
 import type { StreamNetworkFrameProps, StreamNetworkFrameHandle } from "./networkTypes";
-declare const StreamNetworkFrame: React.ForwardRefExoticComponent<StreamNetworkFrameProps<Datum> & React.RefAttributes<StreamNetworkFrameHandle>>;
+declare const StreamNetworkFrame: React.NamedExoticComponent<StreamNetworkFrameProps<Datum> & React.RefAttributes<StreamNetworkFrameHandle>>;
 export default StreamNetworkFrame;

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

@@ -1,5 +1,5 @@
 import type { Datum } from "../charts/shared/datumTypes";
 import * as React from "react";
 import type { StreamOrdinalFrameProps, StreamOrdinalFrameHandle } from "./ordinalTypes";
-declare const StreamOrdinalFrame: React.ForwardRefExoticComponent<StreamOrdinalFrameProps<Datum> & React.RefAttributes<StreamOrdinalFrameHandle<Datum>>>;
+declare const StreamOrdinalFrame: React.NamedExoticComponent<StreamOrdinalFrameProps<Datum> & React.RefAttributes<StreamOrdinalFrameHandle<Datum>>>;
 export default StreamOrdinalFrame;

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

@@ -1,22 +1,6 @@
 import type { Datum } from "../charts/shared/datumTypes";
 import * as React from "react";
 import type { StreamXYFrameProps, StreamXYFrameHandle } from "./types";
-/**
- * Append a 2-char hex alpha to an existing CSS color, returning a valid
- * CSS color string. The naive `${color}${alpha}` concatenation only works
- * when `color` is a 6-char `#rrggbb`; shorthand `#rgb` produces the
- * invalid 5-char `#rgbXX`, which `ctx.strokeStyle`/`fillStyle` silently
- * rejects (falling back to `#000000` — black, invisible on dark themes).
- * The /cookbook/marginal-graphics crosshair invisibility was caused
- * precisely by `--semiotic-text-secondary: "#aaa"` hitting this path.
- *
- * Handles:
- *   • 3-char hex (`#abc`) → expanded to 6-char then concatenated
- *   • 6-char hex (`#aabbcc`) → concatenated directly
- *   • `rgb(...)` → repacked as `rgba(..., a)` with numeric alpha
- * Any other form (named colors, hsl(), oklch(), etc.) falls back to the
- * raw color without alpha — degrades gracefully.
- */
-export declare function withAlpha(color: string, alphaHex: string): string;
-declare const StreamXYFrame: React.ForwardRefExoticComponent<StreamXYFrameProps<Datum> & React.RefAttributes<StreamXYFrameHandle<Datum>>>;
+export { withAlpha } from "./frameThemeColors";
+declare const StreamXYFrame: React.NamedExoticComponent<StreamXYFrameProps<Datum> & React.RefAttributes<StreamXYFrameHandle<Datum>>>;
 export default StreamXYFrame;

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

@@ -0,0 +1,33 @@
+/** Structural scene node accepted from any frame family. */
+export type AccessibleSceneNode = {
+    type?: unknown;
+    datum?: unknown;
+    accessibleDatum?: unknown;
+    accessibility?: unknown;
+    group?: unknown;
+    value?: unknown;
+    category?: unknown;
+    label?: unknown;
+    name?: unknown;
+    properties?: unknown;
+    tableFields?: unknown;
+    x?: unknown;
+    y?: unknown;
+    w?: unknown;
+    h?: unknown;
+    path?: unknown;
+    topPath?: unknown;
+    openY?: unknown;
+    closeY?: unknown;
+    highY?: unknown;
+    lowY?: unknown;
+};
+export interface DataRow {
+    label: string;
+    values: Record<string, string | number>;
+}
+/**
+ * Extract user-facing table rows from scene nodes. Geometry is ignored; rich
+ * accessibleDatum/tableFields metadata takes precedence over the render datum.
+ */
+export declare function extractAllRows(scene: AccessibleSceneNode[]): DataRow[];

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

@@ -1,15 +1,28 @@
 /**
- * Compare two accessor specs for equivalence.
- * - Same reference: always equivalent (`===`)
- * - String accessors: exact string match
- * - Function accessors: `.toString()` comparison (catches inline arrow functions
- *   like `d => d.value` that are recreated on every render but have identical source)
- * - Mismatched types or undefined vs defined: not equivalent
+ * Compare two accessor specs for equivalence, using **identity** semantics.
+ * - String accessors: compared by value (`"value" === "value"`).
+ * - Function accessors: compared by reference. Two distinct function objects are
+ *   NOT equivalent, even when their source text matches.
+ * - Mismatched types or `undefined` vs defined: not equivalent.
  *
- * **Known limitation**: `.toString()` compares source text, not closure bindings.
- * Two functions with identical source but different captured variables will appear
- * equivalent. For closures that depend on changing values, use `useCallback` with
- * the variable in the dependency array so the reference changes when behavior changes.
+ * **Why identity, not source text.** A previous implementation compared
+ * `a.toString() === b.toString()` to treat re-created inline arrows
+ * (`d => d.value`) as equivalent across renders. That was a correctness bug:
+ * `.toString()` compares source text, not captured variables, so two closures
+ * with identical source but different bindings — `makeAccessor(1)` vs
+ * `makeAccessor(10)` — compared equal, and the store retained a stale
+ * domain/scene against a genuinely different accessor. Identity comparison also
+ * matches how the frames already decide a config changed
+ * (`useStableShallow` compares function props by identity), so the store no
+ * longer second-guesses a change the frame already detected.
+ *
+ * **Consumer contract.** Passing a *new* function accessor (a fresh inline
+ * arrow every render) now triggers a rebuild, because the library can no longer
+ * prove the new closure is semantically identical. Use a string accessor
+ * (always referentially stable) or memoize the function with `useCallback`. For
+ * the rare case where a stable function's captured semantics change *without*
+ * its identity changing, bump the pipeline config's `accessorRevision` to force
+ * re-derivation.
  */
 export declare function accessorsEquivalent(a: string | ((...args: any[]) => any) | undefined, b: string | ((...args: any[]) => any) | undefined): boolean;
 export type CoercibleNumber = number | Date | string;

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

@@ -0,0 +1,25 @@
+import * as React from "react";
+export type BrushKeyboardAction = {
+    type: "nudge";
+    direction: "left" | "right" | "up" | "down";
+    resize: boolean;
+} | {
+    type: "clear";
+};
+export interface BrushAccessibilityOptions {
+    label?: string;
+    description?: string;
+    onAction?: (action: BrushKeyboardAction) => void;
+}
+/** Shared ARIA and keyboard vocabulary for frame-owned D3 brushes. */
+export declare function useBrushAccessibility({ label, description, onAction, }?: BrushAccessibilityOptions): {
+    description: string;
+    descriptionId: string;
+    svgProps: {
+        role: string;
+        tabIndex: number;
+        "aria-label": string;
+        "aria-describedby": string;
+        onKeyDown: (event: React.KeyboardEvent<SVGSVGElement>) => void;
+    };
+};

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

@@ -0,0 +1,24 @@
+export interface PaintCanvasBackgroundOptions {
+    /** Explicit chart background color (or CSS var). */
+    background?: string;
+    /**
+     * When true, skip the fill so an SVG backgroundGraphics layer shows through.
+     * Equivalent to frames' `backgroundGraphics` prop being set.
+     */
+    hasBackgroundGraphics?: boolean;
+    /**
+     * Theme fallback when `background` is unset (e.g. `--semiotic-bg`).
+     * Empty / transparent values are ignored.
+     */
+    themeBackground?: string;
+    /** Fill origin (plot-local or canvas-local depending on frame transform). */
+    x?: number;
+    y?: number;
+    width: number;
+    height: number;
+}
+/**
+ * Paint an opaque chart background when appropriate.
+ * Returns true if a fill was applied.
+ */
+export declare function paintCanvasBackground(ctx: CanvasRenderingContext2D, options: PaintCanvasBackgroundOptions): boolean;

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

@@ -21,6 +21,9 @@ export interface CanvasMargin {
  */
 export declare function prepareCanvas(canvas: HTMLCanvasElement, size: [number, number], margin: CanvasMargin, dpr: number): CanvasRenderingContext2D | null;
 /**
- * Get the current devicePixelRatio, defaulting to 1 in non-browser environments.
+ * Get the effective canvas devicePixelRatio, defaulting to 1 in non-browser
+ * environments. Mobile/coarse-pointer screens are capped at 2x to avoid
+ * allocating very large backing stores on high-density phones; desktop stays
+ * crisper but still caps pathological DPR values at 3x.
  */
 export declare function getDevicePixelRatio(): number;