semiotic 3.7.3 → 3.7.5

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

@@ -2,10 +2,12 @@ import type { Datum } from "../charts/shared/datumTypes";
 import { type Quadtree } from "d3-quadtree";
 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 { ResolvedRibbon } from "./xySceneBuilders/ribbonScene";
 import type { CustomLayout } from "./customLayout";
+import type { CustomLayoutSelection } from "./customLayoutSelection";
 import type { MarginType } from "../types/marginType";
 export interface PipelineConfig {
     chartType: StreamChartType;
@@ -28,6 +30,10 @@ export interface PipelineConfig {
     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;
@@ -139,6 +145,9 @@ export interface PipelineConfig {
     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;
 }
 export declare class PipelineStore {
     private buffer;
@@ -152,6 +161,7 @@ export declare class PipelineStore {
     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
@@ -207,6 +217,13 @@ export declare class PipelineStore {
     version: number;
     /** Overlays returned from customLayout (consumed by StreamXYFrame for SVGOverlay). */
     customLayoutOverlays: import("react").ReactNode;
+    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;
@@ -339,5 +356,15 @@ 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;
+    /**
+     * 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`.
+     */
+    restyleScene(selection: CustomLayoutSelection | null): void;
     updateConfig(config: Partial<PipelineConfig>): void;
 }

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

@@ -1,4 +1,5 @@
-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;
@@ -26,6 +27,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/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;

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

@@ -0,0 +1,52 @@
+import * as React from "react";
+import type { Datum } from "../charts/shared/datumTypes";
+/**
+ * The shared-selection state projected to a custom layout — both into the layout
+ * context (`ctx.selection`) and, via {@link useCustomLayoutSelection}, into the
+ * layout's React `overlays` subtree.
+ *
+ * `isActive` is `false` when no selection clause is present (treat every mark as
+ * selected). `predicate(datum)` returns `true` when the raw datum matches the
+ * active selection.
+ */
+export interface CustomLayoutSelection {
+    isActive: boolean;
+    predicate: (datum: Datum) => boolean;
+}
+/**
+ * Provided by the Stream Frames around a custom layout's `overlays`. The value
+ * is the chart's resolved selection; it updates on hover/selection change
+ * **without** the frame re-running the layout — so an overlay that subscribes
+ * via {@link useCustomLayoutSelection} restyles itself while sceneNodes, the
+ * canvas paint, and the quadtree stay untouched.
+ */
+export declare function CustomLayoutSelectionProvider({ value, children, }: {
+    value: CustomLayoutSelection | null;
+    children: React.ReactNode;
+}): React.ReactElement;
+/**
+ * Read the chart's resolved selection from inside a custom layout's `overlays`.
+ *
+ * Subscribing components re-render on selection/hover change **without a
+ * relayout** — the frame swaps only the context value, never rebuilding the
+ * scene. This is the read side of the styling channel; pair it with the
+ * `restyle` callback on the layout result to dim/highlight **canvas** marks
+ * without re-positioning.
+ *
+ * Returns an inactive selection (`isActive: false`, predicate always `true`)
+ * when called outside a custom chart, so overlays render fully-lit by default.
+ *
+ * @example
+ * ```tsx
+ * function ClusterLabel({ datum, x, y }) {
+ *   const { isActive, predicate } = useCustomLayoutSelection()
+ *   const dim = isActive && !predicate(datum)
+ *   return <text x={x} y={y} opacity={dim ? 0.15 : 1}>{datum.label}</text>
+ * }
+ * ```
+ */
+export declare function useCustomLayoutSelection(): CustomLayoutSelection;
+/** Wrap a custom layout's overlay node in the selection provider (no-op for a
+ *  null node, so an empty overlay layer stays empty rather than becoming a
+ *  provider element). Used by the Stream Frames. */
+export declare function wrapWithCustomLayoutSelection(node: React.ReactNode, selection: CustomLayoutSelection | null): React.ReactNode;

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

@@ -1,6 +1,34 @@
 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.
+ *
+ * When the chart participates in a `LinkedCharts` / selection store (via
+ * `NetworkCustomChart`'s `selection` / `linkedHover` props), the frame
+ * threads the resolved predicate here so a custom layout can dim or
+ * highlight marks by the *shared* selection — the same predicate the
+ * built-in HOCs apply to `nodeStyle`. Mirrors `SelectionHookResult`.
+ *
+ * `predicate` receives the **raw** datum (the user object you passed in
+ * `nodes`, i.e. `node.data ?? node`), matching the `d.data || d`
+ * convention the built-in network charts use. `isActive` is `false`
+ * when no selection clause is present — when `false`, treat every mark
+ * as selected (draw at full weight).
+ *
+ * This is orthogonal to `config` (your `layoutConfig` blob): use `config`
+ * for host-owned highlight sets you compute yourself (e.g. a graph
+ * reachability set), and `selection` for cross-chart coordination that
+ * rides the shared store.
+ */
+export interface NetworkLayoutSelection {
+    /** Whether a selection clause is currently active. */
+    isActive: boolean;
+    /** Returns `true` when the raw datum matches the active selection. */
+    predicate: (datum: Datum) => boolean;
+}
 /**
  * customLayout escape hatch for `StreamNetworkFrame`.
  *
@@ -54,6 +82,51 @@ export interface NetworkLayoutContext<C extends object = Record<string, unknown>
     resolveColor: (key: string) => string;
     /** User-supplied config blob threaded through `layoutConfig`. */
     config: C;
+    /**
+     * Shared-selection projection. Present when the chart is wired to a
+     * `LinkedCharts` / selection store; `null` otherwise. Use
+     * `selection.isActive` + `selection.predicate(node.data ?? node)` to
+     * dim/highlight marks by the cross-chart selection. See
+     * {@link NetworkLayoutSelection}.
+     */
+    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. */
@@ -64,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 {
@@ -453,6 +481,11 @@ export interface NetworkPipelineConfig {
     customNetworkLayout?: import("./networkCustomLayout").NetworkCustomLayout;
     /** User-supplied config blob threaded through to NetworkLayoutContext.config. */
     layoutConfig?: object;
+    /** Resolved shared-selection predicate, surfaced to a custom layout as
+     *  `NetworkLayoutContext.selection`. Render-only — deliberately kept out of
+     *  the layout/ingest-affecting signature so a selection change re-runs
+     *  `buildScene` (re-emitting dimmed marks) without a re-ingest or re-layout. */
+    layoutSelection?: import("./networkCustomLayout").NetworkLayoutSelection | null;
 }
 export interface StreamNetworkFrameProps<T = Datum> {
     chartType: NetworkChartType;
@@ -566,6 +599,10 @@ export interface StreamNetworkFrameProps<T = Datum> {
     customNetworkLayout?: import("./networkCustomLayout").NetworkCustomLayout;
     /** User-supplied config blob threaded through to NetworkLayoutContext.config. */
     layoutConfig?: object;
+    /** Resolved shared-selection predicate, surfaced to a custom layout as
+     *  `NetworkLayoutContext.selection`. Set by `NetworkCustomChart` from its
+     *  `selection` / `linkedHover` wiring; render-only (no re-ingest on change). */
+    layoutSelection?: import("./networkCustomLayout").NetworkLayoutSelection | null;
 }
 export interface StreamNetworkFrameHandle {
     push(edge: EdgePush): void;

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;