semiotic 3.7.4 → 3.8.0

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/networkSymbolRenderer.d.ts

@@ -0,0 +1,2 @@
+import type { NetworkSceneNode } from "../networkTypes";
+export declare function networkSymbolRenderer(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/renderers/symbolCanvasRenderer.d.ts

@@ -0,0 +1,2 @@
+import type { StreamRendererFn } from "./types";
+export declare const symbolCanvasRenderer: StreamRendererFn;

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/stalenessBands.d.ts

@@ -0,0 +1,28 @@
+import { type LifecycleBand, type LifecycleBandThresholds } from "../realtime/lifecycleBands";
+import type { StalenessConfig } from "./types";
+/**
+ * Default canvas alpha per band in graded mode. `fresh` is full; each
+ * older band dims further. Override individually via
+ * `staleness.graded.opacities`.
+ */
+export declare const DEFAULT_STALENESS_BAND_OPACITY: Record<LifecycleBand, number>;
+export interface ResolvedStaleness {
+    /** Canvas alpha to apply (1 = no dimming). */
+    alpha: number;
+    /**
+     * Classified band. In graded mode this is the `bandFromAge` result;
+     * in binary mode it collapses to `"fresh"` or `"stale"`.
+     */
+    band: LifecycleBand;
+    /** Whether the chart should read as stale (drives the badge). */
+    isStale: boolean;
+}
+/**
+ * Resolve the dimming + band for a given idle duration. Pure — the
+ * render path computes idle from `now - lastIngestTime` each paint and
+ * the staleness poll uses the same function to decide when to repaint.
+ *
+ * `idleMs` of 0 (no data yet) is treated as fresh.
+ */
+export declare function resolveStaleness(staleness: StalenessConfig | undefined, idleMs: number): ResolvedStaleness;
+export type { LifecycleBand, LifecycleBandThresholds };

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;

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

@@ -0,0 +1,24 @@
+/** Named glyph shapes a `symbol` scene node can request. */
+export type NetworkSymbolName = "circle" | "square" | "triangle" | "diamond" | "star" | "cross" | "wye" | "chevron";
+/** Pipeline-neutral alias — the symbol mark is shared by network, XY, and
+ *  ordinal scenes, so callers outside the network pipeline read this name. */
+export type SymbolName = NetworkSymbolName;
+/** Default shape assignment order when a recipe auto-maps distinct categories. */
+export declare const SYMBOL_SEQUENCE: NetworkSymbolName[];
+/**
+ * SVG path `d` string for a glyph, centered at the origin. `size` follows the
+ * d3-symbol area convention (px²) for named shapes; the custom `chevron`
+ * derives a comparable radius from it. `customPath`, when provided, is returned
+ * verbatim (already origin-centered and sized).
+ */
+export declare function symbolPathString(symbolType: NetworkSymbolName | string | undefined, size: number, customPath?: string): string;
+/** Effective radius of a glyph with the given d3-symbol `size` (used for hit testing). */
+export declare function symbolRadius(size: number): number;
+/**
+ * Maximum extent (circumradius) of a glyph from its center — the radius that
+ * actually bounds the drawn shape. For `circle` this equals {@link symbolRadius},
+ * but pointy shapes (triangle/star/chevron) reach further for the same area, so
+ * collision-packing must use this to avoid visual overlap. Polygonal shapes are
+ * measured from their path vertices; `circle` is the area formula.
+ */
+export declare function symbolExtent(symbolType: NetworkSymbolName | string | undefined, size: number, customPath?: string): number;

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

@@ -6,6 +6,8 @@ import type { ArrowOfTime, WindowMode, LineStyle, BarStyle, WaterfallStyle, Swar
 import type { Datum } from "../charts/shared/datumTypes";
 import type { CoercibleNumber } from "./accessorUtils";
 import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
+import type { SymbolName } from "./symbolPath";
+import type { GlyphDef } from "./glyphDef";
 export type SceneDatum = Datum | null;
 export type SeriesDatum = Datum[] | null;
 export type AxisTickFormat = ((d: number, index?: number, allTicks?: number[]) => string) | ((d: string, index?: number, allTicks?: number[]) => string) | ((d: Date, index?: number, allTicks?: number[]) => string);
@@ -47,14 +49,34 @@ export interface TransitionConfig {
     easing?: "ease-out" | "linear";
 }
 export interface StalenessConfig {
-    /** ms without data before "stale" (default: 5000) */
+    /**
+     * ms without data before "stale" (default: 5000). In graded mode this
+     * is the base TTL the lifecycle bands are measured against — `aging`
+     * begins here, `stale` at 1.5×, `expired` at 3× (overridable).
+     */
     threshold?: number;
-    /** Canvas alpha when stale (default: 0.5) */
+    /** Canvas alpha when stale, binary mode (default: 0.5) */
     dimOpacity?: number;
     /** Render LIVE/STALE badge (default: false) */
     showBadge?: boolean;
     /** Badge position (default: "top-right") */
     badgePosition?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+    /**
+     * Opt into graded (banded) staleness. Instead of a single live→stale
+     * flip at `threshold`, frames that support graded staleness dim
+     * progressively through fresh → aging → stale → expired as idle time
+     * crosses multiples of `threshold`, sharing one schedule with per-datum
+     * decay and annotation freshness. (Currently honored by `StreamXYFrame`,
+     * which backs the realtime XY charts; other frames treat it as binary.)
+     * `true` uses the default per-band opacities; pass an object to override
+     * the band thresholds or opacities.
+     */
+    graded?: boolean | {
+        /** Multiples of `threshold` marking each band edge (see LifecycleBandThresholds). */
+        thresholds?: import("../realtime/lifecycleBands").LifecycleBandThresholds;
+        /** Per-band canvas alpha override. Missing bands use the defaults. */
+        opacities?: Partial<Record<import("../realtime/lifecycleBands").LifecycleBand, number>>;
+    };
 }
 export type MarginalType = "histogram" | "violin" | "ridgeline" | "boxplot";
 export interface MarginalConfig {
@@ -96,7 +118,19 @@ export interface Style {
     /** Internal geo line flag: fade line ends at projection clipping edges. */
     _edgeFade?: boolean;
 }
-export type SceneNode = LineSceneNode | AreaSceneNode | PointSceneNode | RectSceneNode | HeatcellSceneNode | CandlestickSceneNode;
+/**
+ * Optional semantic payload carried beside render geometry. `accessibleDatum`
+ * preserves the full row; `tableFields` lets a recipe expose a curated,
+ * user-facing table projection without reducing the scene datum itself.
+ */
+export interface SceneAccessibilityMetadata {
+    accessibleDatum?: SceneDatum | Datum[];
+    accessibility?: {
+        label?: string;
+        tableFields?: SceneDatum | Datum[];
+    };
+}
+export type SceneNode = LineSceneNode | AreaSceneNode | PointSceneNode | SymbolSceneNode | GlyphSceneNode | RectSceneNode | HeatcellSceneNode | CandlestickSceneNode;
 export interface LineColorThreshold {
     value: number;
     color: string;
@@ -111,6 +145,8 @@ export interface LineSceneNode {
     colorThresholds?: LineColorThreshold[];
     style: Style;
     datum: SeriesDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     group?: string;
     /** Horizontal gradient for the line stroke */
     strokeGradient?: {
@@ -142,6 +178,8 @@ export interface AreaSceneNode {
     bottomPath: [number, number][];
     style: Style;
     datum: SeriesDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     group?: string;
     /** Clip the area to this rect (in plot-relative pixels). Used by horizon
      *  charts to band a single series into N slices. */
@@ -202,6 +240,8 @@ export interface PointSceneNode {
     r: number;
     style: Style;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     /** Optional unique identifier for point-anchored annotations */
     pointId?: string;
     /** Pulse glow intensity 0–1 (set by PipelineStore when pulse is active) */
@@ -219,6 +259,104 @@ export interface PointSceneNode {
     /** Stable identity key for transition tracking */
     _transitionKey?: string;
 }
+/**
+ * Symbol node — the per-datum **shape channel**, shared with the network and
+ * ordinal pipelines. A glyph drawn from a `d3-shape` symbol path (or a custom
+ * `path`), painted on canvas and in SVG/SSR via the shared `symbolPath` helpers,
+ * and hit-tested + keyboard-navigated as a unit. Emitted by custom XY layouts
+ * and by Scatterplot's `symbolBy` encoding. Uses `x`/`y` like its sibling
+ * `PointSceneNode` (the network variant uses `cx`/`cy`).
+ */
+export interface SymbolSceneNode {
+    type: "symbol";
+    x: number;
+    y: number;
+    /** d3-symbol area in px² — drives the glyph's drawn size. */
+    size: number;
+    /** Named shape. Ignored when `path` is set. @default "circle" */
+    symbolType?: SymbolName;
+    /** Pre-built SVG path string, origin-centered — overrides `symbolType`. */
+    path?: string;
+    /** Rotation in radians about (x, y). */
+    rotation?: number;
+    style: Style;
+    datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
+    /** Optional unique identifier for point-anchored annotations. */
+    pointId?: string;
+    /** Pulse glow intensity 0–1 (set by PipelineStore when pulse is active). */
+    _pulseIntensity?: number;
+    /** Pulse glow color. */
+    _pulseColor?: string;
+    /** Pulse glow radius in px. */
+    _pulseGlowRadius?: number;
+    /** Animation target fields (set during transitions). */
+    _targetX?: number;
+    _targetY?: number;
+    _targetR?: number;
+    _targetOpacity?: number;
+    /** Per-datum decay opacity (set by PipelineStore.applyDecay). */
+    _decayOpacity?: number;
+    /** Stable identity key for transition tracking. */
+    _transitionKey?: string;
+}
+/**
+ * Glyph node — the composite-pictogram channel. Where `symbol` stamps one
+ * `d3-shape` path, `glyph` stamps a small multi-part vector pictogram (a
+ * `GlyphDef`: an ISOTYPE server sign, a factory, a worker) with per-node
+ * `color`/`accent` paints resolved against the definition's role tokens, and
+ * an optional partial fill (`fraction`/`fractionStart`) for unit-chart final
+ * signs — pair with the `unitize` recipe. Painted on canvas and in SVG/SSR
+ * via the shared `glyphDef` helpers, hit-tested and keyboard-navigated by its
+ * drawn bounds, and transition-tracked like a point. Uses `x`/`y` in XY,
+ * ordinal, and geo scenes (the network variant uses `cx`/`cy`).
+ */
+export interface GlyphSceneNode {
+    type: "glyph";
+    x: number;
+    y: number;
+    /** Rendered height in px — width follows the definition's viewBox aspect. */
+    size: number;
+    /** The multi-part pictogram definition to stamp. */
+    glyph: GlyphDef;
+    /** Primary paint for parts declaring `"color"`. Falls back to `style.fill`. */
+    color?: string;
+    /** Accent paint for parts declaring `"accent"`. */
+    accent?: string;
+    /** Partial fill 0–1 — how much of the sign is painted. @default 1 */
+    fraction?: number;
+    /** Where the partial fill begins, 0–1 (range boundary signs). @default 0 */
+    fractionStart?: number;
+    /** Partial-fill axis: horizontal fills left→right, vertical bottom→up. @default "horizontal" */
+    fractionDirection?: "horizontal" | "vertical";
+    /** Ghost paint drawn at full extent beneath a partial fill so the whole
+     *  sign stays countable (the ISOTYPE partial-symbol convention). */
+    ghostColor?: string;
+    /** Rotation in radians about (x, y). */
+    rotation?: number;
+    style: Style;
+    datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
+    /** Optional unique identifier for point-anchored annotations. */
+    pointId?: string;
+    /** Pulse glow intensity 0–1 (set by PipelineStore when pulse is active). */
+    _pulseIntensity?: number;
+    /** Pulse glow color. */
+    _pulseColor?: string;
+    /** Pulse glow radius in px. */
+    _pulseGlowRadius?: number;
+    /** Animation target fields (set during transitions). */
+    _targetX?: number;
+    _targetY?: number;
+    _targetR?: number;
+    _targetOpacity?: number;
+    /** Per-datum decay opacity (set by PipelineStore.applyDecay). */
+    _decayOpacity?: number;
+    /** Stable identity key for transition tracking. */
+    _transitionKey?: string;
+}
 export interface RectSceneNode {
     type: "rect";
     x: number;
@@ -259,6 +397,8 @@ export interface RectSceneNode {
     };
     style: Style;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     group?: string;
     _pulseIntensity?: number;
     _pulseColor?: string;
@@ -281,6 +421,8 @@ export interface HeatcellSceneNode {
     h: number;
     fill: string;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     /** Optional style object (used for decay/transition opacity on heatmap cells) */
     style?: Style;
     /** Numeric cell value (for canvas text rendering when showValues is enabled) */
@@ -318,6 +460,8 @@ export interface CandlestickSceneNode {
     /** Range/dumbbell mode — no body, endpoint dots instead */
     isRange?: boolean;
     datum: SceneDatum;
+    accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
+    accessibility?: SceneAccessibilityMetadata["accessibility"];
     /** Optional style object (used during transition opacity animations) */
     style?: Style;
     _pulseIntensity?: number;
@@ -370,6 +514,30 @@ export interface StreamScales {
     x: ScaleLinear<number, number>;
     y: ScaleLinear<number, number>;
 }
+/**
+ * Context handed to a `foregroundGraphics` / `backgroundGraphics` callback. The
+ * function form receives the frame's **resolved scales** alongside `size` +
+ * `margin`, so bespoke SVG overlays anchor to the same scales the chart drew
+ * (instead of re-deriving them from extents by hand and risking drift). `scales`
+ * is `null` before the first layout pass — fall back to your own mapping then.
+ * This is the HOC analogue of what custom layouts get via `ctx.scales`.
+ *
+ * Generic over the scale shape: XY frames pass {@link StreamScales} (`{x, y}`),
+ * the ordinal frame passes its `{o, r, projection}` scales.
+ */
+export interface FrameGraphicsContext<S = StreamScales> {
+    size: number[];
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    scales: S | null;
+}
+/** A foreground/background graphics value: static SVG, or a function of the
+ *  frame's geometry + resolved scales. */
+export type FrameGraphicsProp<S = StreamScales> = ReactNode | ((ctx: FrameGraphicsContext<S>) => ReactNode);
 export interface StreamLayout {
     width: number;
     height: number;
@@ -465,8 +633,18 @@ export interface StreamXYFrameProps<T = Datum> {
     chunkSize?: number;
     xAccessor?: string | ((d: T) => CoercibleNumber);
     yAccessor?: string | ((d: T) => CoercibleNumber);
+    /**
+     * Force domain/scene re-derivation when a stable function accessor's
+     * external semantics changed without receiving a new function identity.
+     * Prefer changing the accessor reference where possible.
+     */
+    accessorRevision?: number;
     colorAccessor?: string | ((d: T) => string);
     sizeAccessor?: string | ((d: T) => CoercibleNumber);
+    /** Categorical accessor → glyph shape (scatter/bubble). */
+    symbolAccessor?: string | ((d: T) => string);
+    /** Explicit `{category → shape}` map for `symbolAccessor`; unmapped auto-assign. */
+    symbolMap?: Record<string, SymbolName>;
     groupAccessor?: string | ((d: T) => string);
     lineDataAccessor?: string;
     curve?: CurveType;
@@ -476,22 +654,25 @@ export interface StreamXYFrameProps<T = Datum> {
      * - "zero" (default): standard stack from y=0
      * - "wiggle": Byron–Wattenberg streamgraph offset (minimizes wiggle)
      * - "silhouette": center the stack symmetrically around y=0
+     * - "diverging": positives stack above 0, negatives below 0 (signed values)
      *
      * Mutually exclusive with `normalize`: when `normalize` is `true`, the
      * stack is forced to a `"zero"` baseline (any other value is ignored)
      * because normalization assumes a fixed `[0, 1]` y-domain.
      */
-    baseline?: "zero" | "wiggle" | "silhouette";
+    baseline?: "zero" | "wiggle" | "silhouette" | "diverging";
     /**
      * Stack order — controls which series sits at the top, middle, or bottom.
      * - "key" (default): alphabetical by group key
+     * - "input": first-seen group order within the current data
+     *   buffer/window; streaming eviction can change this order
      * - "insideOut": largest-total series in the middle, smaller alternating
      *   above/below. Combined with `baseline: "wiggle"` or `"silhouette"`,
      *   produces the canonical streamgraph look where a "central anchor"
      *   layer sits across y=0 and other layers stack outward.
      * - "asc" / "desc": by total ascending / descending
      */
-    stackOrder?: "key" | "insideOut" | "asc" | "desc";
+    stackOrder?: "key" | "input" | "insideOut" | "asc" | "desc";
     /**
      * Accessor returning a symmetric uncertainty offset per datum.
      * When set, an uncertainty band is drawn ± this offset from the line.
@@ -556,7 +737,7 @@ export interface StreamXYFrameProps<T = Datum> {
     windowSize?: number;
     timeAccessor?: string | ((d: T) => number);
     xScaleType?: "linear" | "log" | "time";
-    yScaleType?: "linear" | "log";
+    yScaleType?: "linear" | "log" | "symlog";
     xExtent?: [number | undefined, number | undefined] | [number];
     yExtent?: [number | undefined, number | undefined] | [number];
     extentPadding?: number;
@@ -585,7 +766,7 @@ export interface StreamXYFrameProps<T = Datum> {
     waterfallStyle?: WaterfallStyle;
     swarmStyle?: SwarmStyle;
     barColors?: Record<string, string>;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     showAxes?: boolean;
     /**
      * Per-axis config array. See `XYFrameAxisConfig` for the full set of
@@ -659,9 +840,9 @@ export interface StreamXYFrameProps<T = Datum> {
     /** Fires when the current legend category domain changes after scene rebuilds. */
     onCategoriesChange?: (categories: string[]) => void;
     /** SVG elements rendered behind the canvas (in pixel space) */
-    backgroundGraphics?: ReactNode;
+    backgroundGraphics?: FrameGraphicsProp;
     /** SVG elements rendered on top of everything (in SVG overlay) */
-    foregroundGraphics?: ReactNode;
+    foregroundGraphics?: FrameGraphicsProp;
     /** Canvas renderers executed before the chart-type renderers (e.g. connecting lines under points) */
     canvasPreRenderers?: CanvasRendererFn[];
     /** SVG pre-renderers for SSR — SVG equivalent of canvasPreRenderers, rendered under data marks */
@@ -707,11 +888,18 @@ export interface StreamXYFrameProps<T = Datum> {
      *  returns SceneNode[] + optional overlays. See `semiotic/recipes` for
      *  reference layouts (waffle, calendar, horizon). */
     customLayout?: import("./customLayout").CustomLayout;
+    /** Called when `customLayout` throws. See `getLayoutFailure()` for the
+     * latest structured failure diagnostic. */
+    onLayoutError?: (diagnostic: import("./customLayoutFailure").CustomLayoutFailureDiagnostic) => void;
     /** User-supplied config blob threaded through to LayoutContext.config.
      *  Typed as `object` so caller-defined interfaces (without an index
      *  signature) flow through without casts; layouts narrow via their
      *  own `CustomLayout<TConfig>` parameterization. */
     layoutConfig?: object;
+    /** Resolved shared selection projected into `LayoutContext.selection`. Kept off
+     *  the rebuild path — a change restyles (if the layout returned `restyle`) or
+     *  rebuilds, never re-ingests. */
+    layoutSelection?: import("./customLayoutSelection").CustomLayoutSelection | null;
 }
 export interface StreamXYFrameHandle<T = Datum> {
     push(datum: T): void;
@@ -727,6 +915,15 @@ export interface StreamXYFrameHandle<T = Datum> {
         x: [number, number];
         y: [number, number];
     } | null;
+    /** The most recent custom layout result (nodes/overlays as returned by the
+     *  `customLayout` function) — host readback so pages that need the computed
+     *  placement don't re-run the layout. Null before the first layout or when
+     *  no custom layout is configured. A failed retry retains the prior good
+     *  result; inspect `getLayoutFailure()` to distinguish that recovery. */
+    getCustomLayout(): import("./customLayout").LayoutResult | null;
+    /** The latest custom-layout failure, if any. Cleared by the next successful
+     * layout, by removing the custom layout, or by `clear()`. */
+    getLayoutFailure(): import("./customLayoutFailure").CustomLayoutFailureDiagnostic | null;
 }
 export type CanvasRendererFn = (ctx: CanvasRenderingContext2D, nodes: SceneNode[], scales: StreamScales, layout: StreamLayout) => void;
 /** SVG equivalent of CanvasRendererFn — returns React elements for SSR/SVG rendering */

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

@@ -6,6 +6,15 @@ import { resolveAnimateConfig } from "./pipelineTransitionUtils";
 import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { TransitionConfig } from "./types";
 import type { HoverPointerCoords } from "./hoverUtils";
+/**
+ * The small scheduling surface `useFrame` needs. Keeping this separate from
+ * the browser global gives hook tests a deterministic, handle-agnostic seam
+ * without coupling the frame lifecycle to a broader scheduler abstraction.
+ */
+export interface FrameScheduler {
+    requestAnimationFrame(callback: FrameRequestCallback): number;
+    cancelAnimationFrame(handle: number): void;
+}
 /**
  * Frame-supplied margin defaults. Each Stream Frame has its own — XY's
  * differs from Ordinal's, Network has both a default and a CENTERED variant
@@ -48,6 +57,12 @@ export interface UseFrameInput {
     animate?: AnimateProp;
     /** Frame's `transition` prop (legacy / explicit form). */
     transitionProp?: TransitionConfig;
+    /**
+     * Optional rAF seam for deterministic frame tests or an embedding runtime.
+     * It owns both render scheduling and pointer-move coalescing. Omit it to
+     * use the browser's `requestAnimationFrame` / `cancelAnimationFrame`.
+     */
+    frameScheduler?: FrameScheduler;
     /**
      * Frame's `dirtyRef` (the flag that forces a full canvas redraw on the
      * next paint). When provided, useFrame installs a theme-change effect
@@ -94,12 +109,15 @@ export interface UseFrameResult {
     introEnabled: boolean;
     /** Stable id for the AccessibleDataTable region (hash-suffixed). */
     tableId: string;
-    /** Token of the pending rAF, or 0 if none. */
-    rafRef: React.MutableRefObject<number>;
+    /** Token of the pending rAF, or `null` if none. `0` is a valid token. */
+    rafRef: React.MutableRefObject<number | null>;
     /** Frame assigns its render closure here. */
     renderFnRef: React.MutableRefObject<() => void>;
     /** Queue a render on the next animation frame. Coalesces. */
     scheduleRender: () => void;
+    /** Cancel a queued render, if any. Direct/hydration paints use this before
+     * taking over so a stale rAF cannot race a synchronous frame. */
+    cancelRender: () => void;
     /** Frame assigns its hover handler closure here. */
     hoverHandlerRef: React.MutableRefObject<(coords: HoverPointerCoords) => void>;
     /** Frame assigns its pointer-leave closure here. */
@@ -109,6 +127,7 @@ export interface UseFrameResult {
     onPointerMove: (e: {
         clientX: number;
         clientY: number;
+        pointerType?: string;
     }) => void;
     /** Stable callback to attach to canvas's onPointerLeave (or onMouseLeave).
      *  Cancels any pending hover rAF and invokes hoverLeaveRef. */

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

@@ -79,6 +79,12 @@ export interface HydrationLifecycleOptions {
      * would produce.
      */
     renderFnRef: MutableRefObject<() => void>;
+    /**
+     * Optional shared-scheduler cancellation. A hydration paint is synchronous,
+     * so it must take ownership from any queued render before invoking the
+     * frame closure.
+     */
+    cancelRender?: () => void;
     /**
      * Optional unmount cleanup. Frame-specific work the hook can't
      * generalize — e.g. clearing the streaming `DataSourceAdapter`