semiotic 3.7.4 → 3.7.5

package/dist/components/semiotic-experimental.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Experimental entry point for temporary adapters and unstable previews.
+ *
+ * Anything imported from "semiotic/experimental" is intentionally outside
+ * Semiotic's stable public API. Exports may be renamed, moved, or removed
+ * without a deprecation window and are excluded from stable API-surface and
+ * bundle-size gates.
+ */
+export { EXPERIMENTAL_GOFISH_ADAPTER_NAME, unstable_fromGofishIR, } from "./recipes/gofishIR";
+export type { GofishIRDocument as UnstableGofishIRDocument, GofishChartConfig as UnstableGofishChartConfig, GofishChartFamily as UnstableGofishChartFamily, FromGofishIROptions as UnstableFromGofishIROptions, } from "./recipes/gofishIR";
+export { registerGofishLambda as unstable_registerGofishLambda, unregisterGofishLambda as unstable_unregisterGofishLambda, } from "./recipes/gofishLambdas";
+export type { GofishLambda as UnstableGofishLambda, } from "./recipes/gofishLambdas";
+export { gofishIRExamples as unstable_gofishIRExamples, flowerIR as unstable_gofishFlowerIR, bottleIR as unstable_gofishBottleIR, polarRibbonIR as unstable_gofishPolarRibbonIR, titanicCircleTreemapIR as unstable_gofishTitanicCircleTreemapIR, pythonMemoryIR as unstable_gofishPythonMemoryIR, bobaIR as unstable_gofishBobaIR, } from "./recipes/gofishIRExamples";
+export type { GofishIRExample as UnstableGofishIRExample } from "./recipes/gofishIRExamples";
+export { IDID_SPEC_VERSION, BUILTIN_INTENT_IDS as unstable_BUILTIN_INTENT_IDS, validatePortableCapability as unstable_validatePortableCapability, validatePortableAudienceProfile as unstable_validatePortableAudienceProfile, validatePortableAnnotation as unstable_validatePortableAnnotation, toVegaLite as unstable_toVegaLite, attachIDID as unstable_attachIDID, readIDID as unstable_readIDID, attachIDIDAnnotations as unstable_attachIDIDAnnotations, readIDIDAnnotations as unstable_readIDIDAnnotations, } from "./data/portability";
+export { fromObservablePlot as unstable_fromObservablePlot } from "./data/fromObservablePlot";
+export { fromMermaid as unstable_fromMermaid } from "./data/fromMermaid";
+export type { MermaidResult as UnstableMermaidResult, MermaidNode as UnstableMermaidNode, MermaidEdge as UnstableMermaidEdge, MermaidDirection as UnstableMermaidDirection, MermaidNodeShape as UnstableMermaidNodeShape, } from "./data/fromMermaid";
+export type { ObservablePlotSpec as UnstableObservablePlotSpec, ObservablePlotMark as UnstableObservablePlotMark, ObservablePlotMarkOptions as UnstableObservablePlotMarkOptions, ObservablePlotScale as UnstableObservablePlotScale, ObservablePlotChannel as UnstableObservablePlotChannel, } from "./data/fromObservablePlot";
+export type { BuiltInIntentId as UnstableBuiltInIntentId, PortableIntentId as UnstablePortableIntentId, PortableChartRubric as UnstablePortableChartRubric, PortableChartVariant as UnstablePortableChartVariant, PortableChartCapability as UnstablePortableChartCapability, PortableReceptionModality as UnstablePortableReceptionModality, PortableAudienceTarget as UnstablePortableAudienceTarget, PortableAudienceProfile as UnstablePortableAudienceProfile, PortableAnnotationProvenance as UnstablePortableAnnotationProvenance, PortableAnnotationLifecycle as UnstablePortableAnnotationLifecycle, PortableAnnotated as UnstablePortableAnnotated, ValidationResult as UnstablePortabilityValidationResult, IDIDVegaLiteMeta as UnstableIDIDVegaLiteMeta, } from "./data/portability";

package/dist/components/semiotic-network.d.ts

@@ -13,6 +13,8 @@ export { CirclePack } from "./charts/network/CirclePack";
 export { OrbitDiagram } from "./charts/network/OrbitDiagram";
 export { ProcessSankey } from "./charts/network/ProcessSankey";
 export { NetworkCustomChart } from "./charts/custom/NetworkCustomChart";
+export { useCustomLayoutSelection } from "./stream/customLayoutSelection";
+export type { CustomLayoutSelection } from "./stream/customLayoutSelection";
 export type { StreamNetworkFrameProps, StreamNetworkFrameHandle, NetworkChartType, NetworkSceneNode, NetworkSceneEdge, NetworkLabel, ThresholdAlertConfig } from "./stream/networkTypes";
 export type { ForceDirectedGraphProps } from "./charts/network/ForceDirectedGraph";
 export type { SankeyDiagramProps } from "./charts/network/SankeyDiagram";
@@ -23,6 +25,6 @@ export type { TreemapProps } from "./charts/network/Treemap";
 export type { CirclePackProps } from "./charts/network/CirclePack";
 export type { OrbitDiagramProps } from "./charts/network/OrbitDiagram";
 export type { NetworkCustomChartProps } from "./charts/custom/NetworkCustomChart";
-export type { NetworkCustomLayout, NetworkLayoutContext, NetworkLayoutResult, } from "./stream/networkCustomLayout";
+export type { NetworkCustomLayout, NetworkLayoutContext, NetworkLayoutResult, NetworkHtmlMark, } from "./stream/networkCustomLayout";
 export { validateProcessSankey, formatProcessSankeyIssue, } from "./charts/network/processSankey/algorithm";
 export type { ProcessSankeyNode as ProcessSankeyValidatorNode, ProcessSankeyEdge as ProcessSankeyValidatorEdge, ProcessSankeyIssue, } from "./charts/network/processSankey/algorithm";

package/dist/components/semiotic-ordinal.d.ts

@@ -21,6 +21,8 @@ export { RidgelinePlot } from "./charts/ordinal/RidgelinePlot";
 export { FunnelChart } from "./charts/ordinal/FunnelChart";
 export { LikertChart } from "./charts/ordinal/LikertChart";
 export { OrdinalCustomChart } from "./charts/custom/OrdinalCustomChart";
+export { useCustomLayoutSelection } from "./stream/customLayoutSelection";
+export type { CustomLayoutSelection } from "./stream/customLayoutSelection";
 export { createHatchPattern } from "./charts/shared/hatchPattern";
 export type { HatchPatternOptions } from "./charts/shared/hatchPattern";
 export type { StreamOrdinalFrameProps, StreamOrdinalFrameHandle, OrdinalChartType, OrdinalScales, OrdinalSceneNode } from "./stream/ordinalTypes";

package/dist/components/semiotic-realtime.d.ts

@@ -6,12 +6,20 @@ import StreamXYFrame from "./stream/StreamXYFrame";
 import StreamNetworkFrame from "./stream/StreamNetworkFrame";
 import { RingBuffer } from "./realtime/RingBuffer";
 import { IncrementalExtent } from "./realtime/IncrementalExtent";
+import { RunningStats } from "./realtime/RunningStats";
+import { WindowAccumulator, statValue, bandBounds } from "./realtime/WindowAccumulator";
+import { parseWindowDuration } from "./realtime/parseWindowDuration";
+import { ReorderBuffer } from "./realtime/ReorderBuffer";
 import { RealtimeLineChart } from "./charts/realtime/RealtimeLineChart";
 import { RealtimeHistogram, TemporalHistogram } from "./charts/realtime/RealtimeHistogram";
 import { RealtimeSwarmChart } from "./charts/realtime/RealtimeSwarmChart";
 import { RealtimeWaterfallChart } from "./charts/realtime/RealtimeWaterfallChart";
 import { RealtimeHeatmap } from "./charts/realtime/RealtimeHeatmap";
-export { StreamXYFrame, StreamNetworkFrame, RingBuffer, IncrementalExtent, RealtimeLineChart, RealtimeHistogram, TemporalHistogram, RealtimeSwarmChart, RealtimeWaterfallChart, RealtimeHeatmap };
+export { StreamXYFrame, StreamNetworkFrame, RingBuffer, IncrementalExtent, RunningStats, WindowAccumulator, statValue, bandBounds, parseWindowDuration, ReorderBuffer, RealtimeLineChart, RealtimeHistogram, TemporalHistogram, RealtimeSwarmChart, RealtimeWaterfallChart, RealtimeHeatmap };
+export type { WindowType, AggregateStat, AggregateBand, WindowAccumulatorConfig, AggregatedWindow, } from "./realtime/WindowAccumulator";
+export type { AggregateConfig } from "./charts/realtime/aggregate";
+export type { LatePolicy, ReorderBufferConfig, ReorderResult, } from "./realtime/ReorderBuffer";
+export type { EventTimeConfig } from "./charts/realtime/eventTime";
 export type { RealtimeLineChartProps } from "./charts/realtime/RealtimeLineChart";
 export type { RealtimeHistogramProps, TemporalHistogramProps } from "./charts/realtime/RealtimeHistogram";
 export type { RealtimeSwarmChartProps } from "./charts/realtime/RealtimeSwarmChart";

package/dist/components/semiotic-recipes.d.ts

@@ -15,6 +15,10 @@ export { dagreLayout } from "./recipes/dagre";
 export type { DagreConfig } from "./recipes/dagre";
 export { lineageDagLayout } from "./recipes/lineageDag";
 export type { LineageDagConfig, LineageLod, LineageStoreSlot } from "./recipes/lineageDag";
+export { mermaidDagLayout } from "./recipes/mermaidDag";
+export type { MermaidDagConfig } from "./recipes/mermaidDag";
+export { packedClusterMatrix } from "./recipes/packedClusterMatrix";
+export type { PackedClusterMatrixConfig } from "./recipes/packedClusterMatrix";
 export { marimekkoLayout } from "./recipes/marimekko";
 export type { MarimekkoConfig } from "./recipes/marimekko";
 export { bulletLayout } from "./recipes/bullet";
@@ -26,5 +30,18 @@ export type { AnnotationLayoutConfig, AnnotationLayoutOptions, AutoPlaceAnnotati
 export { annotationDensity, annotationBudget, DEFAULT_AREA_PER_ANNOTATION } from "./recipes/annotationDensity";
 export type { AnnotationDensityConfig, AnnotationDensityOptions, AnnotationDensityResult, } from "./recipes/annotationDensity";
 export type { CustomLayout, LayoutContext, LayoutResult, } from "./stream/customLayout";
-export type { NetworkCustomLayout, NetworkLayoutContext, NetworkLayoutResult, } from "./stream/networkCustomLayout";
+export type { NetworkCustomLayout, NetworkLayoutContext, NetworkLayoutResult, NetworkHtmlMark, } from "./stream/networkCustomLayout";
 export type { OrdinalCustomLayout, OrdinalLayoutContext, OrdinalLayoutResult, } from "./stream/ordinalCustomLayout";
+export { shade, makeShade, readField, groupBy } from "./recipes/recipeUtils";
+export { dimFor, matchesHighlight, signatureKey, LayoutCache } from "./recipes/recipeUtils";
+export type { DimOptions, HighlightMatch } from "./recipes/recipeUtils";
+export { symbolPathString, symbolRadius, symbolExtent, SYMBOL_SEQUENCE } from "./stream/symbolPath";
+export type { NetworkSymbolName } from "./stream/symbolPath";
+export { roundedEnclosure, boundsOf, bandLabel, markCallout } from "./recipes/recipeChrome";
+export type { RoundedEnclosureProps, BandLabelProps, MarkCalloutProps, CalloutConnector, } from "./recipes/recipeChrome";
+export { legendGroupsFrom } from "./recipes/recipeLegend";
+export type { LegendGroupsInput } from "./recipes/recipeLegend";
+export { useCustomLayoutSelection } from "./stream/customLayoutSelection";
+export type { CustomLayoutSelection } from "./stream/customLayoutSelection";
+export { buildTooltipEntries, extractTooltipDatum, formatTooltipValue, } from "./recipes/customTooltip";
+export type { CustomTooltipEntry, CustomTooltipEntryOptions, } from "./recipes/customTooltip";

package/dist/components/semiotic-themes.d.ts

@@ -79,3 +79,5 @@ export declare function themeToCSS(theme: SemioticTheme, selector?: string): str
  * ```
  */
 export declare function themeToTokens(theme: SemioticTheme): Datum;
+export { designTokensToTheme } from "./store/designTokens";
+export type { DesignTokensToThemeOptions } from "./store/designTokens";

package/dist/components/semiotic-xy.d.ts

@@ -18,6 +18,8 @@ export { QuadrantChart } from "./charts/xy/QuadrantChart";
 export { MultiAxisLineChart } from "./charts/xy/MultiAxisLineChart";
 export { CandlestickChart } from "./charts/xy/CandlestickChart";
 export { XYCustomChart } from "./charts/custom/XYCustomChart";
+export { useCustomLayoutSelection } from "./stream/customLayoutSelection";
+export type { CustomLayoutSelection } from "./stream/customLayoutSelection";
 export type { StreamXYFrameProps, StreamXYFrameHandle } from "./stream/types";
 export type { CustomLayout, LayoutContext, LayoutResult } from "./stream/customLayout";
 export type { LineChartProps } from "./charts/xy/LineChart";

package/dist/components/semiotic.d.ts

@@ -33,6 +33,8 @@ export type { StreamNetworkFrameProps, StreamNetworkFrameHandle, NetworkChartTyp
 export type { SelectionConfig, LinkedHoverProp, LinkedBrushProp } from "./charts/shared/types";
 export type { LinkedChartsProps } from "./LinkedCharts";
 export { useSelection, useSelectionActions, useLinkedHover, useBrushSelection, useFilteredData } from "./LinkedCharts";
+export { useCustomLayoutSelection } from "./stream/customLayoutSelection";
+export type { CustomLayoutSelection } from "./stream/customLayoutSelection";
 export type { UseSelectionOptions, UseSelectionResult, UseSelectionActionsResult, UseLinkedHoverOptions, UseLinkedHoverResult, UseBrushSelectionOptions, UseBrushSelectionResult } from "./LinkedCharts";
 export { useChartObserver } from "./LinkedCharts";
 export type { UseChartObserverOptions, UseChartObserverResult } from "./LinkedCharts";
@@ -62,6 +64,8 @@ export type { HatchPatternOptions } from "./charts/shared/hatchPattern";
 export { smartTickFormat, adaptiveTimeTicks } from "./charts/shared/formatUtils";
 export { darkenColor, lightenColor } from "./charts/shared/colorManipulation";
 export type { TooltipProp, TooltipConfig, TooltipField, MultiLineTooltipConfig } from "./Tooltip/Tooltip";
+export { smartTooltipEntries } from "./charts/shared/tooltipUtils";
+export type { SmartTooltipEntry, SmartTooltipResult } from "./charts/shared/tooltipUtils";
 export type { ArrowOfTime, WindowMode, ThresholdType, LineStyle, BarStyle, WaterfallStyle, SwarmStyle, AnnotationContext, AnnotationAnchorMode, CrosshairStyle, HoverAnnotationConfig, HoverData } from "./realtime/types";
 export type { RealtimeLineChartProps } from "./charts/realtime/RealtimeLineChart";
 export type { RealtimeTemporalHistogramProps, RealtimeHistogramProps, TemporalHistogramProps } from "./charts/realtime/RealtimeHistogram";

package/dist/components/store/ObservationStore.d.ts

@@ -45,7 +45,26 @@ export interface ClickObservation extends ObservationBase {
 export interface ClickEndObservation extends ObservationBase {
     type: "click-end";
 }
-export type ChartObservation = HoverObservation | HoverEndObservation | BrushObservation | BrushEndObservation | SelectionObservation | SelectionEndObservation | ClickObservation | ClickEndObservation;
+/**
+ * Emitted when an event-time stream receives a record outside its
+ * lateness/grace window (see `ReorderBuffer`). Surfaces lateness as an
+ * observable signal — for stream diagnostics — rather than silently
+ * dropping it.
+ */
+export interface LateDataObservation extends ObservationBase {
+    type: "late-data";
+    /** The late datum that arrived outside the grace window. */
+    datum: Datum;
+    /** Event-time of the late datum. */
+    eventTime: number;
+    /** Watermark (largest event-time seen) when it arrived. */
+    watermark: number;
+    /** Whether it was dropped or kept, per the late policy. */
+    policy: "drop" | "keep";
+    /** Running total of late events seen on this chart. */
+    lateCount: number;
+}
+export type ChartObservation = HoverObservation | HoverEndObservation | BrushObservation | BrushEndObservation | SelectionObservation | SelectionEndObservation | ClickObservation | ClickEndObservation | LateDataObservation;
 export type OnObservationCallback = (observation: ChartObservation) => void;
 export interface ObservationStoreState {
     /** Ring buffer of recent observations (newest last). Mutated in place for perf. */
@@ -56,5 +75,5 @@ export interface ObservationStoreState {
     pushObservation: (observation: ChartObservation) => void;
     clearObservations: () => void;
 }
-export declare const ObservationProvider: import("react").FC<import("./createStore").StoreProviderProps<ObservationStoreState>>, useObservationSelector: <R>(selector: (state: ObservationStoreState) => R) => R;
+export declare const ObservationProvider: import("react").FC<import("./createStore").StoreProviderProps<ObservationStoreState>>, useObservationSelector: <R>(selector: (state: ObservationStoreState) => R, equalityFn?: ((a: R, b: R) => boolean) | undefined) => R;
 export {};

package/dist/components/store/SelectionStore.d.ts

@@ -27,4 +27,4 @@ export interface SelectionStoreState {
     clearSelection: (selectionName: string) => void;
 }
 export declare function buildPredicate(selection: Selection, requestingClientId?: string): (d: Datum) => boolean;
-export declare const SelectionProvider: import("react").FC<import("./createStore").StoreProviderProps<SelectionStoreState>>, useSelectionSelector: <R>(selector: (state: SelectionStoreState) => R) => R;
+export declare const SelectionProvider: import("react").FC<import("./createStore").StoreProviderProps<SelectionStoreState>>, useSelectionSelector: <R>(selector: (state: SelectionStoreState) => R, equalityFn?: ((a: R, b: R) => boolean) | undefined) => R;

package/dist/components/store/ThemeStore.d.ts

@@ -100,4 +100,4 @@ export type SemioticThemeUpdate = Omit<Partial<SemioticTheme>, "colors" | "typog
 };
 export type ThemeStoreUpdate = SemioticThemeUpdate | "light" | "dark" | "high-contrast";
 export declare function resolveThemeUpdate(current: SemioticTheme, theme: ThemeStoreUpdate): SemioticTheme;
-export declare const ThemeProvider: import("react").FC<import("./createStore").StoreProviderProps<ThemeStoreState>>, useThemeSelector: <R>(selector: (state: ThemeStoreState) => R) => R;
+export declare const ThemeProvider: import("react").FC<import("./createStore").StoreProviderProps<ThemeStoreState>>, useThemeSelector: <R>(selector: (state: ThemeStoreState) => R, equalityFn?: ((a: R, b: R) => boolean) | undefined) => R;

package/dist/components/store/TooltipStore.d.ts

@@ -2,5 +2,5 @@ interface TooltipStoreState {
     tooltip: unknown;
     changeTooltip: (tooltip: unknown) => void;
 }
-declare const TooltipProvider: import("react").FC<import("./createStore").StoreProviderProps<TooltipStoreState>>, useTooltip: <R>(selector: (state: TooltipStoreState) => R) => R;
+declare const TooltipProvider: import("react").FC<import("./createStore").StoreProviderProps<TooltipStoreState>>, useTooltip: <R>(selector: (state: TooltipStoreState) => R, equalityFn?: ((a: R, b: R) => boolean) | undefined) => R;
 export { TooltipProvider, useTooltip };

package/dist/components/store/createStore.d.ts

@@ -3,4 +3,4 @@ export interface StoreProviderProps<T> {
     children: React.ReactNode;
     initialState?: Partial<T>;
 }
-export declare function createStore<T>(fn: (set: (updater: (current: T) => Partial<T>) => void) => T): [React.FC<StoreProviderProps<T>>, <R>(selector: (state: T) => R) => R];
+export declare function createStore<T>(fn: (set: (updater: (current: T) => Partial<T>) => void) => T): [React.FC<StoreProviderProps<T>>, <R>(selector: (state: T) => R, equalityFn?: (a: R, b: R) => boolean) => R];

package/dist/components/store/designTokens.d.ts

@@ -0,0 +1,15 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { SemioticTheme } from "./ThemeStore";
+type ColorRole = "primary" | "secondary" | "background" | "surface" | "text" | "textSecondary" | "border" | "grid" | "focus" | "annotation" | "success" | "danger" | "warning" | "error" | "info";
+export interface DesignTokensToThemeOptions {
+    /** Theme to merge resolved roles onto. Defaults to LIGHT/DARK by detected bg. */
+    base?: SemioticTheme;
+    /** Pin a role to a token path, e.g. `{ primary: "color.brand.500" }`. */
+    mapping?: Partial<Record<ColorRole | "fontFamily" | "categorical", string>>;
+}
+/**
+ * Build a `SemioticTheme` from a W3C Design Tokens object. Inverse of
+ * `themeToTokens`; round-trips exactly for tokens under a `semiotic.*` group.
+ */
+export declare function designTokensToTheme(tokens: Datum, options?: DesignTokensToThemeOptions): SemioticTheme;
+export {};

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

@@ -0,0 +1,44 @@
+import * as React from "react";
+import type { NetworkHtmlMark } from "./networkCustomLayout";
+import type { CustomLayoutSelection } from "./customLayoutSelection";
+export interface NetworkHtmlMarksLayerProps {
+    /** Marks emitted by the custom layout (`NetworkLayoutResult.htmlMarks`). */
+    marks: NetworkHtmlMark[] | undefined;
+    /** The frame's margin — the layer is offset by it so marks align with the
+     *  canvas and SVG `overlays`, which translate their content by the same. */
+    margin: {
+        top: number;
+        left: number;
+    };
+    /** Shared-selection projection, provided so mark content can subscribe via
+     *  `useCustomLayoutSelection()` and restyle on selection change without a
+     *  relayout (parity with the SVG `overlays` subtree). `null` when unwired. */
+    selection?: CustomLayoutSelection | null;
+    /**
+     * Pixels beyond each visible edge of the scrolling viewport for which marks are
+     * still mounted (so a scroll reveals already-present DOM, not blank space).
+     * Marks farther than this off-screen are not rendered at all. Defaults to 400.
+     */
+    overscan?: number;
+}
+/**
+ * Renders a custom network layout's {@link NetworkHtmlMark}s into one
+ * absolutely-positioned DOM layer above the canvas and SVG `overlays`.
+ *
+ * Each mark is its own positioned element, keyed by `id`, so the browser can
+ * composite `opacity`/`transform`/`visibility` changes on the mark's content
+ * without re-rasterizing it (the win over SVG `<foreignObject>`), and a
+ * position-only layout re-run repositions without remounting. The wrapper sets
+ * only placement + sizing + `pointer-events`; everything visual comes from
+ * `content`.
+ *
+ * Marks are viewport-culled against the nearest scrollable ancestor (plus
+ * `overscan`): a mark more than `overscan` px outside the visible window is not
+ * in the DOM at all, so a large topology mounts only roughly a viewport's worth
+ * regardless of total size, and the per-hover/paint cost stays bounded. When
+ * there's no scrollable ancestor (the content fits) every mark renders.
+ *
+ * Returns `null` when there are no marks, so layouts that don't use the feature
+ * render no extra DOM.
+ */
+export declare function NetworkHtmlMarksLayer({ marks, margin, selection, overscan, }: NetworkHtmlMarksLayerProps): React.ReactElement | null;

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

@@ -1,4 +1,6 @@
 import { ParticlePool } from "./ParticlePool";
+import type { NetworkHtmlMark } from "./networkCustomLayout";
+import type { CustomLayoutSelection } from "./customLayoutSelection";
 import type { ActiveTransition } from "./pipelineTransitionUtils";
 import { type Quadtree } from "d3-quadtree";
 import type { NetworkPipelineConfig, NetworkSceneNode, NetworkSceneEdge, NetworkCircleNode, NetworkLabel, RealtimeNode, RealtimeEdge, EdgePush } from "./networkTypes";
@@ -29,6 +31,21 @@ export declare class NetworkPipelineStore {
     labels: NetworkLabel[];
     /** Overlays returned from customNetworkLayout (consumed by StreamNetworkFrame). */
     customLayoutOverlays: import("react").ReactNode;
+    /** HTML marks returned from customNetworkLayout — positioned DOM nodes the
+     *  frame renders in a layer above the canvas/overlays (consumed by
+     *  StreamNetworkFrame). Empty for built-in chart types. */
+    customLayoutHtmlMarks: NetworkHtmlMark[];
+    private _customLayoutDiagnosticsWarned;
+    /** Per-frame restyle callbacks from the custom layout result. When set, the
+     *  frame routes selection changes through `restyleScene()` (style-only repaint)
+     *  instead of a full `buildScene()`. */
+    private _customRestyle;
+    private _customRestyleEdge;
+    /** True when the active custom layout supplied a `restyle`/`restyleEdge`. */
+    hasCustomRestyle: boolean;
+    /** Base (as-emitted) style per mark, so a restyle pass starts from the layout's
+     *  own style rather than compounding patches across selection changes. */
+    private _baseStyles;
     private _nodeQuadtree;
     private _maxNodeRadius;
     /** Bumped whenever sceneNodes is rebuilt; keys the quadtree cache. */
@@ -108,6 +125,21 @@ export declare class NetworkPipelineStore {
     /**
      * Build the scene graph from current layout positions.
      */
+    /** Update the selection the layout reads at the next `buildScene`, without
+     *  triggering a rebuild. The frame calls this on selection change; whether it
+     *  then repaints (restyle) or rebuilds is the frame's decision. */
+    setLayoutSelection(selection: CustomLayoutSelection | null): void;
+    /** Snapshot each mark's as-emitted style so {@link restyleScene} can re-apply
+     *  patches from the original rather than compounding. */
+    private snapshotBaseStyles;
+    /**
+     * Re-apply the custom layout's `restyle`/`restyleEdge` to the existing scene
+     * for `selection`, mutating styles **in place** off each mark's base style.
+     * Does NOT bump the scene revision — positions are unchanged, so the quadtree
+     * stays valid and no relayout/repack happens. The frame repaints the canvas
+     * after calling this. No-op when the layout supplied no restyle callbacks.
+     */
+    restyleScene(selection: CustomLayoutSelection | null): void;
     buildScene(size: [number, number]): void;
     /**
      * Lazily (re)build the circle-node spatial index. Only built when the scene

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

@@ -19,10 +19,22 @@ type AnnotationAnchorNode = {
     r?: number;
     /** Arc nodes (chord, radial) carry an outer radius. */
     outerR?: number;
+    /** Symbol nodes (the per-datum glyph channel) carry a d3-symbol area. */
+    size?: number;
 };
 type NetworkAnnotationContext = AnnotationContext & {
     sceneNodes?: AnnotationAnchorNode[];
 };
+/** Anchor id for a scene node — used to resolve `pointId`-anchored annotations
+ *  to a mark a layout emitted (incl. custom-layout marks). Exported for tests. */
+export declare function nodeAnchorId(node: AnnotationAnchorNode): string | undefined;
+/** Center + effective radius of a scene node for annotation anchoring. Exported
+ *  for tests. */
+export declare function nodeCenter(node: AnnotationAnchorNode): {
+    x: number;
+    y: number;
+    r: number;
+} | null;
 export interface NetworkSVGOverlayProps {
     width: number;
     height: number;

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

@@ -20,6 +20,7 @@ import { type Quadtree } from "d3-quadtree";
 import type { OrdinalPipelineConfig, OrdinalScales, OrdinalSceneNode, OrdinalColumn, OrdinalLayout } from "./ordinalTypes";
 import type { Changeset, PointSceneNode } from "./types";
 import type { ActiveTransition } from "./pipelineTransitionUtils";
+import type { CustomLayoutSelection } from "./customLayoutSelection";
 export declare class OrdinalPipelineStore {
     private buffer;
     private rExtent;
@@ -33,6 +34,7 @@ export declare class OrdinalPipelineStore {
     private getStack;
     private getGroup;
     private getColor;
+    private getSymbol;
     private getConnector;
     private getDataId;
     /** Discovered categories in insertion order */
@@ -55,6 +57,13 @@ export declare class OrdinalPipelineStore {
     columns: Record<string, OrdinalColumn>;
     /** Overlays returned from customLayout (consumed by StreamOrdinalFrame). */
     customLayoutOverlays: import("react").ReactNode;
+    private _customLayoutDiagnosticsWarned;
+    /** Per-frame restyle callback from the custom layout result (see OrdinalLayoutResult.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;
     version: number;
     /** Bumped whenever the buffer is mutated. Used to invalidate per-frame caches. */
     private _dataVersion;
@@ -142,5 +151,14 @@ export declare class OrdinalPipelineStore {
     get size(): number;
     getOAccessor(): (d: Datum) => string;
     getRAccessor(): (d: Datum) => number;
+    /** Update the selection the layout reads at the next rebuild, without one. */
+    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.
+     * No-op when the layout supplied no `restyle`.
+     */
+    restyleScene(selection: CustomLayoutSelection | null): void;
     updateConfig(config: Partial<OrdinalPipelineConfig>): void;
 }

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;