semiotic 3.7.4 → 3.7.5

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

@@ -1,7 +1,8 @@
 import type { ReactNode } from "react";
 import type { NetworkSceneNode, NetworkSceneEdge, NetworkLabel, RealtimeNode, RealtimeEdge } from "./networkTypes";
-import type { ThemeSemanticColors } from "./types";
+import type { Style, ThemeSemanticColors } from "./types";
 import type { Datum } from "../charts/shared/datumTypes";
+import type { CustomLayoutSelection } from "./customLayoutSelection";
 /**
  * The shared selection state, projected into the custom-layout context.
  *
@@ -90,6 +91,43 @@ export interface NetworkLayoutContext<C extends object = Record<string, unknown>
      */
     selection?: NetworkLayoutSelection | null;
 }
+/**
+ * An HTML/React node positioned in plot space, rendered into a real DOM layer
+ * above the canvas (and above the SVG `overlays`) — **not** an SVG
+ * `<foreignObject>`.
+ *
+ * Reach for this over `overlays` when a mark is text-heavy or a rich component
+ * (a labelled card, an Axon widget) **and** it dims/animates on interaction.
+ * HTML-in-SVG (`<foreignObject>`) gets no compositor layer, so an `opacity`
+ * change — the common hover-dim — re-rasterizes the text; on a large graph that
+ * stalls the interaction. A real DOM element composites `opacity` / `transform`
+ * / `visibility` without re-painting its contents.
+ *
+ * The framework owns placement: each mark is wrapped in an absolutely-positioned
+ * element that tracks the same margin (and any future zoom/pan) transform the
+ * canvas and `overlays` receive, so a mark at `(x, y)` lands exactly where a
+ * `sceneNode` at `(x, y)` does. The consumer owns the content's appearance.
+ *
+ * Marks are non-interactive by default (`pointer-events: none`) — pointer events
+ * fall through to the canvas, so existing `sceneNodes` hit-testing
+ * (`onObservation` / `onClick`) is unaffected. Emit a transparent hit-rect
+ * `sceneNode` per mark to keep the canvas authoritative for interaction.
+ */
+export interface NetworkHtmlMark {
+    /** Stable identity for keying / reconciliation across layout runs. A
+     *  position-only update repositions without remounting the content. */
+    id: string;
+    /** Top-left x in plot coordinates — the same space as `sceneNodes`. */
+    x: number;
+    /** Top-left y in plot coordinates — the same space as `sceneNodes`. */
+    y: number;
+    /** Wrapper width in plot units. */
+    width: number;
+    /** Wrapper height in plot units. */
+    height: number;
+    /** Arbitrary HTML/React rendered inside the positioned wrapper. */
+    content: ReactNode;
+}
 export interface NetworkLayoutResult {
     /** Positioned scene primitives. Circles, rects, or arcs. */
     sceneNodes?: NetworkSceneNode[];
@@ -99,4 +137,31 @@ export interface NetworkLayoutResult {
     labels?: NetworkLabel[];
     /** SVG overlays composited above the canvas. */
     overlays?: ReactNode;
+    /**
+     * HTML/React nodes positioned in plot space, rendered into one real DOM layer
+     * above the canvas and SVG `overlays`. Use for rich-text / component marks that
+     * dim or animate on hover — they composite `opacity`/`transform` changes
+     * instead of re-rasterizing text the way an SVG `<foreignObject>` does. The
+     * framework owns positioning + transform so marks stay pixel-aligned with
+     * `sceneNodes`. Additive: a layout that omits it renders no extra DOM. See
+     * {@link NetworkHtmlMark}.
+     */
+    htmlMarks?: NetworkHtmlMark[];
+    /**
+     * **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 quadtree. Return
+     * a style patch merged onto the node's *base* style (the style it was emitted
+     * with); return nothing to leave it unchanged.
+     *
+     * This is the canvas counterpart to {@link useCustomLayoutSelection} (which
+     * restyles `overlays`): compute geometry once in the layout body, and express
+     * selection-driven dimming/highlighting here so hover stays O(nodes) paint
+     * instead of O(nodes+edges) relayout. Providing it opts the chart into the
+     * cheap selection path; omit it and selection changes re-run the layout (the
+     * pre-existing behavior).
+     */
+    restyle?: (node: NetworkSceneNode, selection: CustomLayoutSelection | null) => Partial<Style> | void;
+    /** Per-frame restyle of edges — same contract as {@link NetworkLayoutResult.restyle}. */
+    restyleEdge?: (edge: NetworkSceneEdge, selection: CustomLayoutSelection | null) => Partial<Style> | void;
 }

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

@@ -6,6 +6,7 @@ import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig
 import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { Datum } from "../charts/shared/datumTypes";
 import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
+import type { NetworkSymbolName } from "./symbolPath";
 export interface TensionConfig {
     weightChange: number;
     newEdge: number;
@@ -247,6 +248,33 @@ export interface NetworkArcNode {
     _pulseColor?: string;
     _pulseGlowRadius?: number;
 }
+/**
+ * Symbol node — a glyph rendered from a `d3-shape` symbol path (or a custom
+ * path). The per-datum shape channel: recipes that encode a categorical field
+ * as marker shape (e.g. `packedClusterMatrix`) emit these. Hit-tests as a
+ * circle of the symbol's effective radius; renders on canvas and in SVG/SSR.
+ */
+export interface NetworkSymbolNode {
+    type: "symbol";
+    cx: number;
+    cy: number;
+    /** d3-symbol area in px² — drives the glyph's drawn size. */
+    size: number;
+    /** Named shape. Ignored when `path` is set. @default "circle" */
+    symbolType?: NetworkSymbolName;
+    /** Pre-built SVG path string, origin-centered — overrides `symbolType`. */
+    path?: string;
+    /** Rotation in radians about (cx, cy). */
+    rotation?: number;
+    style: Style;
+    datum: SceneDatum;
+    id?: string;
+    label?: string;
+    depth?: number;
+    _pulseIntensity?: number;
+    _pulseColor?: string;
+    _pulseGlowRadius?: number;
+}
 /** Line edge — used by force */
 export interface NetworkLineEdge {
     type: "line";
@@ -305,7 +333,7 @@ export interface NetworkCurvedEdge {
     _cachedPath2D?: Path2D;
     _cachedPath2DSource?: string;
 }
-export type NetworkSceneNode = NetworkCircleNode | NetworkRectNode | NetworkArcNode;
+export type NetworkSceneNode = NetworkCircleNode | NetworkRectNode | NetworkArcNode | NetworkSymbolNode;
 export type NetworkSceneEdge = NetworkLineEdge | NetworkBezierEdge | NetworkRibbonEdge | NetworkCurvedEdge;
 /** Label data for the SVG overlay */
 export interface NetworkLabel {

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

@@ -3,7 +3,8 @@ import type { ScaleBand, ScaleLinear } from "d3-scale";
 import type { Datum } from "../charts/shared/datumTypes";
 import type { MarginType } from "../types/marginType";
 import type { OrdinalSceneNode, OrdinalScales } from "./ordinalTypes";
-import type { ThemeSemanticColors } from "./types";
+import type { Style, ThemeSemanticColors } from "./types";
+import type { CustomLayoutSelection } from "./customLayoutSelection";
 /**
  * customLayout escape hatch for `StreamOrdinalFrame`.
  *
@@ -75,10 +76,25 @@ export interface OrdinalLayoutContext<C extends object = Record<string, unknown>
     resolveColor: (key: string) => string;
     /** User-supplied config blob threaded through `layoutConfig`. */
     config: C;
+    /**
+     * Shared-selection projection (from `selection` / `linkedHover`). `null` when
+     * unwired. For selection-driven styling without a relayout, use
+     * {@link OrdinalLayoutResult.restyle} (canvas) / `useCustomLayoutSelection`
+     * (overlays) rather than recomputing geometry here.
+     */
+    selection?: CustomLayoutSelection | null;
 }
 export interface OrdinalLayoutResult {
     /** Scene nodes to render. Get hit testing, transitions, decay, SSR for free. */
     nodes?: OrdinalSceneNode[];
     /** SVG overlays composited above the canvas (labels, axis lines, 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 +
+     * repaints — no relayout, no quadtree rebuild. Return a style patch merged onto
+     * the node's *base* style. Providing it opts into the cheap selection path.
+     * Pairs with `useCustomLayoutSelection` for the `overlays`.
+     */
+    restyle?: (node: OrdinalSceneNode, selection: CustomLayoutSelection | null) => Partial<Style> | void;
 }

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

@@ -10,6 +10,8 @@ export interface OrdinalSceneContext {
     getStack?: (d: Datum) => string;
     getGroup?: (d: Datum) => string;
     getColor?: (d: Datum) => string;
+    /** Categorical accessor → glyph shape (swarm/dot symbolBy). */
+    getSymbol?: (d: Datum) => string;
     getConnector?: (d: Datum) => string;
     getO: (d: Datum) => string;
     multiScales: ScaleLinear<number, number>[];

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

@@ -2,6 +2,7 @@ import type { ReactNode } from "react";
 import type { ScaleLinear, ScaleBand } from "d3-scale";
 import type { WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext } from "../realtime/types";
 import type { AutoPlaceAnnotations } from "../recipes/annotationLayout";
+import type { SymbolName } from "./symbolPath";
 import type { Style, SceneDatum, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, ThemeSemanticColors } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../types/legendTypes";
@@ -162,9 +163,9 @@ export interface TrapezoidSceneNode {
     _targetOpacity?: number;
     _transitionKey?: string;
 }
-export type { Style, PointSceneNode, RectSceneNode } from "./types";
-import type { PointSceneNode, RectSceneNode } from "./types";
-export type OrdinalSceneNode = RectSceneNode | PointSceneNode | WedgeSceneNode | BoxplotSceneNode | ViolinSceneNode | ConnectorSceneNode | TrapezoidSceneNode;
+export type { Style, PointSceneNode, RectSceneNode, SymbolSceneNode } from "./types";
+import type { PointSceneNode, RectSceneNode, SymbolSceneNode } from "./types";
+export type OrdinalSceneNode = RectSceneNode | PointSceneNode | SymbolSceneNode | WedgeSceneNode | BoxplotSceneNode | ViolinSceneNode | ConnectorSceneNode | TrapezoidSceneNode;
 export interface OrdinalColumn {
     name: string;
     x: number;
@@ -193,6 +194,10 @@ export interface OrdinalPipelineConfig {
     categoryAccessor?: string | ((d: Datum) => string);
     valueAccessor?: string | ((d: Datum) => number) | Array<string | ((d: Datum) => number)>;
     colorAccessor?: string | ((d: Datum) => string);
+    /** Categorical accessor → glyph shape (swarm/dot). Emits SymbolSceneNodes. */
+    symbolAccessor?: string | ((d: Datum) => string);
+    /** Explicit `{category → shape}` map; unmapped categories auto-assign. */
+    symbolMap?: Record<string, SymbolName>;
     stackBy?: string | ((d: Datum) => string);
     groupBy?: string | ((d: Datum) => string);
     timeAccessor?: string | ((d: Datum) => number);
@@ -275,6 +280,9 @@ export interface OrdinalPipelineConfig {
     /** Resolved margin — passed through so OrdinalLayoutContext.dimensions.margin
      *  reflects what the frame actually used. */
     layoutMargin?: import("../types/marginType").MarginType;
+    /** Resolved shared selection projected into OrdinalLayoutContext.selection.
+     *  Owned by a dedicated frame effect (kept off the rebuild path). */
+    layoutSelection?: import("./customLayoutSelection").CustomLayoutSelection | null;
 }
 export interface StreamOrdinalFrameProps<T = Datum> {
     chartType: OrdinalChartType;
@@ -285,6 +293,10 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     /** Value field — the quantitative dimension (replaces rAccessor). Can be array for multiAxis. */
     valueAccessor?: string | ((d: T) => number) | Array<string | ((d: T) => number)>;
     colorAccessor?: string | ((d: T) => string);
+    /** Categorical accessor → glyph shape (swarm/dot). */
+    symbolAccessor?: string | ((d: T) => string);
+    /** Explicit `{category → shape}` map for `symbolAccessor`; unmapped auto-assign. */
+    symbolMap?: Record<string, SymbolName>;
     stackBy?: string | ((d: T) => string);
     groupBy?: string | ((d: T) => string);
     timeAccessor?: string | ((d: T) => number);
@@ -440,6 +452,10 @@ export interface StreamOrdinalFrameProps<T = Datum> {
     customLayout?: import("./ordinalCustomLayout").OrdinalCustomLayout;
     /** User-supplied config blob threaded through to OrdinalLayoutContext.config. */
     layoutConfig?: object;
+    /** Resolved shared selection projected into `OrdinalLayoutContext.selection`.
+     *  Kept off the rebuild path — restyles (if the layout returned `restyle`) or
+     *  rebuilds, never re-ingests. */
+    layoutSelection?: import("./customLayoutSelection").CustomLayoutSelection | null;
 }
 export interface StreamOrdinalFrameHandle<T = Datum> {
     push(datum: T): 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/symbolCanvasRenderer.d.ts

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

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/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,7 @@ 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";
 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 +48,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 +117,7 @@ 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;
+export type SceneNode = LineSceneNode | AreaSceneNode | PointSceneNode | SymbolSceneNode | RectSceneNode | HeatcellSceneNode | CandlestickSceneNode;
 export interface LineColorThreshold {
     value: number;
     color: string;
@@ -219,6 +240,46 @@ 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;
+    /** 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;
@@ -467,6 +528,10 @@ export interface StreamXYFrameProps<T = Datum> {
     yAccessor?: string | ((d: T) => CoercibleNumber);
     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;
@@ -712,6 +777,10 @@ export interface StreamXYFrameProps<T = Datum> {
      *  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;

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

@@ -4,10 +4,15 @@ interface StoreWithIngestTime {
 }
 /**
  * Shared hook that polls a store's `lastIngestTime` on a 1-second interval
- * and manages staleness state. When staleness changes it sets
+ * and manages staleness state. When the resolved staleness changes it sets
  * `dirtyRef.current = true` and calls `scheduleRender()` so the canvas
  * repaints with the appropriate dimming.
  *
+ * Handles both binary staleness (a single live→stale flip) and graded
+ * staleness (progressive dimming through fresh → aging → stale → expired):
+ * a repaint is scheduled whenever the resolved *band* changes, so the
+ * graded ramp advances even though `isStale` may already be true.
+ *
  * Call this hook after `storeRef`, `dirtyRef`, and `scheduleRender` are
  * declared. The `isStale` / `setIsStale` state must live in the caller
  * so that the `useState` call order stays unchanged.

package/dist/components/stream/xySceneBuilders/pointScene.d.ts

@@ -8,6 +8,6 @@ import type { Datum } from "../../charts/shared/datumTypes";
  * Dependencies: SceneGraph (buildPointNode)
  * Consumed by: PipelineStore.buildSceneNodes (chartTypes "scatter", "bubble")
  */
-import type { PointSceneNode } from "../types";
+import type { PointSceneNode, SymbolSceneNode } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildPointScene(ctx: XYSceneContext, data: Datum[]): PointSceneNode[];
+export declare function buildPointScene(ctx: XYSceneContext, data: Datum[]): (PointSceneNode | SymbolSceneNode)[];

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

@@ -8,6 +8,7 @@ import type { AreaGradientConfig } from "./areaGradient";
  * accessing PipelineStore instance fields directly.
  */
 import type { StreamScales, Style, CurveType, BarStyle, ThemeSemanticColors } from "../types";
+import type { SymbolName } from "../symbolPath";
 import type { ResolvedRibbon } from "./ribbonScene";
 export interface XYSceneContext {
     scales: StreamScales;
@@ -17,6 +18,8 @@ export interface XYSceneContext {
     getY0?: (d: Datum) => number | null;
     getSize?: (d: Datum) => number;
     getColor?: (d: Datum) => string;
+    /** Categorical accessor → glyph shape (scatter/bubble symbolBy). */
+    getSymbol?: (d: Datum) => string;
     getGroup?: (d: Datum) => string;
     getCategory?: (d: Datum) => string;
     getPointId?: (d: Datum) => string;
@@ -68,6 +71,8 @@ export interface XYSceneConfig {
         r?: number;
     };
     sizeRange?: [number, number];
+    /** Explicit `{category → shape}` map for symbolBy; unmapped auto-assign. */
+    symbolMap?: Record<string, SymbolName>;
     xAccessor?: string | ((d: Datum) => any);
     yAccessor?: string | ((d: Datum) => any);
     valueAccessor?: string | ((d: Datum) => any);