semiotic 3.7.4 → 3.8.0

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

@@ -1,157 +1,49 @@
 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 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 { 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);
-    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;
-}
+import type { LayoutResult } from "./customLayout";
+import type { CustomLayoutSelection } from "./customLayoutSelection";
+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;
     private getCategory;
     private getSize;
     private getColor;
+    private getSymbol;
     private getY0;
     /** Unified ribbon list — `boundsAccessor` + `band` both compose into
      *  this single array (see `resolveRibbons`). Read by the scene
@@ -196,27 +88,58 @@ 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;
+    /** True when the active custom layout supplied a `restyle`. */
+    hasCustomRestyle: boolean;
+    /** Base (as-emitted) style per node, so restyle passes don't compound. */
+    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;
@@ -233,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;
     /**
@@ -257,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;
@@ -300,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.
@@ -316,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.
@@ -339,5 +255,27 @@ export declare class PipelineStore {
     getXAccessor(): (d: Datum) => number;
     getYAccessor(): (d: Datum) => number;
     getCategoryAccessor(): ((d: Datum) => string) | undefined;
+    /** Update the selection the layout reads at the next rebuild, without
+     *  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

@@ -1,10 +1,11 @@
-import type { SceneNode, LineSceneNode, AreaSceneNode, PointSceneNode, RectSceneNode, HeatcellSceneNode, Style, StreamScales, CurveType } from "./types";
+import type { SceneNode, LineSceneNode, AreaSceneNode, PointSceneNode, SymbolSceneNode, RectSceneNode, HeatcellSceneNode, Style, StreamScales, CurveType } from "./types";
+import type { SymbolName } from "./symbolPath";
 import type { Datum } from "../charts/shared/datumTypes";
 export declare function buildLineNode(data: Datum[], scales: StreamScales, xGet: (d: Datum) => number, yGet: (d: Datum) => number, style: Style, group?: string): LineSceneNode;
 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
@@ -16,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[];
@@ -26,6 +35,9 @@ export declare function buildStackedAreaNodes(groups: {
     stackedTops: StackedTops;
 };
 export declare function buildPointNode(datum: Datum, scales: StreamScales, xGet: (d: Datum) => number, yGet: (d: Datum) => number, r: number, style: Style, pointId?: string): PointSceneNode | null;
+/** Build a {@link SymbolSceneNode} — the glyph sibling of {@link buildPointNode}.
+ *  `size` is the d3-symbol area (px²); convert from a target radius with πr². */
+export declare function buildSymbolNode(datum: Datum, scales: StreamScales, xGet: (d: Datum) => number, yGet: (d: Datum) => number, size: number, symbolType: SymbolName, style: Style, pointId?: string): SymbolSceneNode | null;
 export declare function buildRectNode(x: number, y: number, w: number, h: number, style: Style, datum: any, group?: string): RectSceneNode;
 export declare function buildHeatcellNode(x: number, y: number, w: number, h: number, fill: string, datum: any, options?: {
     value?: number;

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;

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

@@ -2,6 +2,7 @@ import type { ReactNode } from "react";
 import type { Datum } from "../charts/shared/datumTypes";
 import type { MarginType } from "../types/marginType";
 import type { SceneNode, StreamScales, Style, ThemeSemanticColors } from "./types";
+import type { CustomLayoutSelection } from "./customLayoutSelection";
 /**
  * customLayout — escape hatch for bespoke chart geometry.
  *
@@ -57,12 +58,31 @@ export interface LayoutContext<C extends object = Record<string, unknown>> {
     resolveColor: (group: string, datum?: Datum) => string;
     /** User-supplied config blob threaded through `layoutConfig`. */
     config: C;
+    /**
+     * Shared-selection projection (from `selection` / `linkedHover`). `null` when
+     * the chart isn't wired to a selection store. Dim/highlight by
+     * `selection.predicate(datum)`. For selection-driven styling that shouldn't
+     * pay a relayout, express it via {@link LayoutResult.restyle} (canvas) /
+     * `useCustomLayoutSelection` (overlays) instead of recomputing geometry here.
+     */
+    selection?: CustomLayoutSelection | null;
 }
 export interface LayoutResult {
     /** Scene nodes to render. Get hit testing, transitions, decay, SSR for free. */
     nodes?: SceneNode[];
     /** SVG overlays composited above the canvas (labels, annotations). */
     overlays?: ReactNode;
+    /**
+     * **Per-frame restyle of canvas marks, without re-positioning.** When present,
+     * a selection/hover change re-applies styles to the existing scene nodes and
+     * repaints — it does NOT re-run the layout or rebuild the point quadtree.
+     * Return a style patch merged onto the node's *base* style; return nothing to
+     * leave it unchanged. Providing it opts the chart into the cheap selection
+     * path (hover stays O(nodes) paint, not O(nodes) relayout); omit it and
+     * selection changes re-run the layout. Pairs with `useCustomLayoutSelection`
+     * for the `overlays`.
+     */
+    restyle?: (node: SceneNode, selection: CustomLayoutSelection | null) => Partial<Style> | void;
 }
 /**
  * Note on extents: customLayout v1 does not return extents. Layouts that

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

@@ -0,0 +1,11 @@
+import type { ReactNode } from "react";
+export interface CustomLayoutDiagnosticNode {
+    datum?: unknown;
+}
+export interface CustomLayoutDiagnosticsOptions {
+    label: string;
+    nodes: readonly CustomLayoutDiagnosticNode[];
+    overlays?: ReactNode;
+    warned: Set<string>;
+}
+export declare function warnCustomLayoutDiagnostics(options: CustomLayoutDiagnosticsOptions): void;