semiotic 3.7.5 → 3.8.0

package/dist/components/server/serverChartConfigs.d.ts

@@ -1,10 +1,9 @@
-import type { Datum } from "../charts/shared/datumTypes";
-type FrameType = "xy" | "ordinal" | "network" | "geo";
-interface ChartConfig {
-    frameType: FrameType;
-    /** Build frame props from HOC-level props */
-    buildProps: (data: any, colorBy: any, colorScheme: any, common: Datum, rest: Datum) => Datum;
-}
+/**
+ * Chart-specific prop mapping for renderChart().
+ *
+ * Family implementations live in serverChartConfigs{XY,Ordinal,Network,Geo,Custom,Physics}.ts.
+ */
+import type { ChartConfig } from "./serverChartConfigShared";
 export declare const CHART_CONFIGS: {
     Sparkline: ChartConfig;
     LineChart: ChartConfig;
@@ -15,7 +14,7 @@ export declare const CHART_CONFIGS: {
     CandlestickChart: ChartConfig;
     BubbleChart: {
         frameType: "xy";
-        buildProps: (data: any, colorBy: any, colorScheme: any, common: Datum, rest: Datum) => {
+        buildProps: (data: any, colorBy: any, colorScheme: any, common: import("../stream/networkColorAccessors").Datum, rest: import("../stream/networkColorAccessors").Datum) => {
             chartType: string;
             data: any;
             xAccessor: any;
@@ -29,6 +28,7 @@ export declare const CHART_CONFIGS: {
     ConnectedScatterplot: ChartConfig;
     QuadrantChart: ChartConfig;
     Heatmap: ChartConfig;
+    XYCustomChart: ChartConfig;
     BarChart: ChartConfig;
     StackedBarChart: ChartConfig;
     GroupedBarChart: ChartConfig;
@@ -44,7 +44,9 @@ export declare const CHART_CONFIGS: {
     LikertChart: ChartConfig;
     FunnelChart: ChartConfig;
     GaugeChart: ChartConfig;
+    OrdinalCustomChart: ChartConfig;
     ForceDirectedGraph: ChartConfig;
+    NetworkCustomChart: ChartConfig;
     SankeyDiagram: ChartConfig;
     ProcessSankey: ChartConfig;
     ChordDiagram: ChartConfig;
@@ -54,5 +56,13 @@ export declare const CHART_CONFIGS: {
     ChoroplethMap: ChartConfig;
     ProportionalSymbolMap: ChartConfig;
     FlowMap: ChartConfig;
+    GeoCustomChart: ChartConfig;
+    GaltonBoardChart: ChartConfig;
+    EventDropChart: ChartConfig;
+    PhysicsPileChart: ChartConfig;
+    CollisionSwarmChart: ChartConfig;
+    ProcessFlowChart: ChartConfig;
+    GauntletChart: ChartConfig;
+    PhysicalFlowChart: ChartConfig;
+    PhysicsCustomChart: ChartConfig;
 };
-export {};

package/dist/components/server/serverChartConfigsCustom.d.ts

@@ -0,0 +1,5 @@
+import { type ChartConfig } from "./serverChartConfigShared";
+export declare const xyCustomChart: ChartConfig;
+export declare const ordinalCustomChart: ChartConfig;
+export declare const networkCustomChart: ChartConfig;
+export declare const geoCustomChart: ChartConfig;

package/dist/components/server/serverChartConfigsGeo.d.ts

@@ -0,0 +1,9 @@
+import { type ChartConfig } from "./serverChartConfigShared";
+export declare const choroplethMap: ChartConfig;
+export declare const proportionalSymbolMap: ChartConfig;
+/**
+ * FlowMap expands `flows` (edges with source/target ids) + `nodes` (points
+ * with coordinates) into the `lines` shape StreamGeoFrame expects, where
+ * each line carries a `coordinates` array of two {x,y} endpoints.
+ */
+export declare const flowMap: ChartConfig;

package/dist/components/server/serverChartConfigsNetwork.d.ts

@@ -0,0 +1,8 @@
+import { type ChartConfig } from "./serverChartConfigShared";
+export declare const forceDirectedGraph: ChartConfig;
+export declare const processSankey: ChartConfig;
+export declare const sankeyDiagram: ChartConfig;
+export declare const chordDiagram: ChartConfig;
+export declare const treeDiagram: ChartConfig;
+export declare const treemap: ChartConfig;
+export declare const circlePack: ChartConfig;

package/dist/components/server/serverChartConfigsOrdinal.d.ts

@@ -0,0 +1,16 @@
+import { type ChartConfig } from "./serverChartConfigShared";
+export declare const barChart: ChartConfig;
+export declare const stackedBarChart: ChartConfig;
+export declare const groupedBarChart: ChartConfig;
+export declare const pieChart: ChartConfig;
+export declare const donutChart: ChartConfig;
+export declare const histogram: ChartConfig;
+export declare const boxPlot: ChartConfig;
+export declare const violinPlot: ChartConfig;
+export declare const swarmPlot: ChartConfig;
+export declare const dotPlot: ChartConfig;
+export declare const swimlaneChart: ChartConfig;
+export declare const ridgelinePlot: ChartConfig;
+export declare const likertChart: ChartConfig;
+export declare const funnelChart: ChartConfig;
+export declare const gaugeChart: ChartConfig;

package/dist/components/server/serverChartConfigsPhysics.d.ts

@@ -0,0 +1,9 @@
+import { type ChartConfig } from "./serverChartConfigShared";
+export declare const galtonBoardChart: ChartConfig;
+export declare const eventDropChart: ChartConfig;
+export declare const physicsPileChart: ChartConfig;
+export declare const collisionSwarmChart: ChartConfig;
+export declare const processFlowChart: ChartConfig;
+export declare const gauntletChart: ChartConfig;
+export declare const physicalFlowChart: ChartConfig;
+export declare const physicsCustomChart: ChartConfig;

package/dist/components/server/serverChartConfigsXY.d.ts

@@ -0,0 +1,11 @@
+import { type ChartConfig } from "./serverChartConfigShared";
+export declare const sparkline: ChartConfig;
+export declare const lineChart: ChartConfig;
+export declare const areaChart: ChartConfig;
+export declare const differenceChart: ChartConfig;
+export declare const stackedAreaChart: ChartConfig;
+export declare const candlestickChart: ChartConfig;
+export declare const scatterplot: ChartConfig;
+export declare const quadrantChart: ChartConfig;
+export declare const connectedScatterplot: ChartConfig;
+export declare const heatmap: ChartConfig;

package/dist/components/server/staticGeo.d.ts

@@ -0,0 +1,4 @@
+import type { StreamGeoFrameProps } from "../stream/geoTypes";
+import { type EvidenceSink } from "./renderEvidence";
+import type { ThemeAwareProps } from "./staticSVGChrome";
+export declare function renderGeoFrame(props: StreamGeoFrameProps & ThemeAwareProps, sink?: EvidenceSink): string;

package/dist/components/server/staticLegend.d.ts

@@ -26,7 +26,7 @@ export interface StaticLegendConfig {
     /** Category labels to show in legend */
     categories: string[];
     /** Color scheme — array of colors or d3-scale-chromatic name */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Theme for text/font colors */
     theme: SemioticTheme;
     /** Legend position */

package/dist/components/server/staticNetwork.d.ts

@@ -0,0 +1,8 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { NetworkPipelineConfig, RealtimeNode, RealtimeEdge, StreamNetworkFrameProps } from "../stream/networkTypes";
+import { type EvidenceSink } from "./renderEvidence";
+import type { ThemeAwareProps } from "./staticSVGChrome";
+export declare function resolveAccessor(accessor: string | ((d: Datum) => any) | undefined, defaultKey: string): (d: Datum) => any;
+export declare function buildRealtimeNodes(propsNodes: any[], config: NetworkPipelineConfig): RealtimeNode[];
+export declare function buildRealtimeEdges(propsEdges: any[], config: NetworkPipelineConfig): RealtimeEdge[];
+export declare function renderNetworkFrame(props: StreamNetworkFrameProps & ThemeAwareProps, sink?: EvidenceSink): string;

package/dist/components/server/staticOrdinal.d.ts

@@ -0,0 +1,11 @@
+import * as React from "react";
+import { OrdinalPipelineStore } from "../stream/OrdinalPipelineStore";
+import type { StreamOrdinalFrameProps } from "../stream/ordinalTypes";
+import { type EvidenceSink } from "./renderEvidence";
+import type { SemioticTheme } from "../store/ThemeStore";
+import type { ThemeAwareProps } from "./staticSVGChrome";
+export declare function generateOrdinalAxesSVG(store: OrdinalPipelineStore, layout: {
+    width: number;
+    height: number;
+}, props: StreamOrdinalFrameProps, theme: SemioticTheme, idPrefix?: string): React.ReactNode;
+export declare function renderOrdinalFrame(props: StreamOrdinalFrameProps & ThemeAwareProps, sink?: EvidenceSink): string;

package/dist/components/server/staticPhysics.d.ts

@@ -0,0 +1,3 @@
+import { type EvidenceSink } from "./renderEvidence";
+import type { StaticPhysicsFrameProps } from "./staticSVGChrome";
+export declare function renderPhysicsFrame(props: StaticPhysicsFrameProps, sink?: EvidenceSink): string;

package/dist/components/server/staticSVGChrome.d.ts

@@ -0,0 +1,110 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { LegendLayout } from "../types/legendTypes";
+import type { StreamXYFrameProps, StreamScales, StreamLayout } from "../stream/types";
+import type { StreamNetworkFrameProps, RealtimeEdge } from "../stream/networkTypes";
+import type { StreamOrdinalFrameProps } from "../stream/ordinalTypes";
+import type { StreamGeoFrameProps } from "../stream/geoTypes";
+import type { PhysicsSettledSVGOptions } from "../stream/physics/PhysicsSettledSVG";
+import type { PhysicsPipelineStore } from "../stream/physics/PhysicsPipelineStore";
+import type { OrdinalPipelineStore } from "../stream/OrdinalPipelineStore";
+import type { RenderEvidence } from "./renderEvidence";
+import { resolveTheme, type ThemeInput } from "./themeResolver";
+import type { SemioticTheme } from "../store/ThemeStore";
+import * as React from "react";
+export type FrameType = RenderEvidence["frameType"];
+export type StaticPhysicsFrameProps = PhysicsSettledSVGOptions & {
+    config?: ConstructorParameters<typeof PhysicsPipelineStore>[0];
+    initialSpawns?: Array<Record<string, unknown>>;
+    projectionRows?: PhysicsSettledSVGOptions["projectionRows"];
+    size?: [number, number];
+    _idPrefix?: string;
+};
+export type StaticFrameProps = (StreamXYFrameProps | StreamNetworkFrameProps | StreamOrdinalFrameProps | StreamGeoFrameProps | StaticPhysicsFrameProps) & ThemeAwareProps;
+export type CategoricalAccessor = string | ((d: Datum) => string);
+type EdgeEndpoint = RealtimeEdge["source"] | RealtimeEdge["target"] | null | undefined;
+export declare function edgeEndpointId(endpoint: EdgeEndpoint): string | null;
+/** Generate a short stable ID from chart props for unique SVG element IDs */
+export declare function chartUID(props: Datum): string;
+export interface ThemeAwareProps {
+    theme?: ThemeInput;
+    showLegend?: boolean;
+    showGrid?: boolean;
+    annotations?: Datum[];
+    title?: string | React.ReactNode;
+    description?: string;
+    background?: string;
+    className?: string;
+    legendPosition?: "right" | "left" | "top" | "bottom";
+    legendLayout?: LegendLayout;
+    /** Prefix for SVG element IDs — used by renderDashboard to avoid collisions */
+    _idPrefix?: string;
+}
+export declare function reserveStaticLegendMargin(margin: {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}, options: {
+    categories: string[];
+    colorScheme?: string | string[] | Record<string, string>;
+    theme: ReturnType<typeof resolveTheme>;
+    position?: "right" | "left" | "top" | "bottom";
+    size: [number, number];
+    hasTitle?: boolean;
+    legendLayout?: LegendLayout;
+}): void;
+export declare function reserveLegendConfigMargin(margin: {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}, options: {
+    legend: unknown;
+    theme: ReturnType<typeof resolveTheme>;
+    position?: "right" | "left" | "top" | "bottom";
+    size: [number, number];
+    hasTitle?: boolean;
+    legendLayout?: LegendLayout;
+}): void;
+export declare function renderLegendConfig(legend: unknown, options: {
+    theme: ReturnType<typeof resolveTheme>;
+    position?: "right" | "left" | "top" | "bottom";
+    size: [number, number];
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    hasTitle?: boolean;
+    legendLayout?: LegendLayout;
+    idPrefix?: string;
+}): React.ReactNode;
+export declare function defaultTickFormat(v: number): string;
+/** Render grid lines for XY charts */
+export declare function renderGridSVG(scales: StreamScales, layout: StreamLayout, theme: SemioticTheme, idPrefix?: string): React.ReactNode;
+/** Render grid lines for ordinal charts */
+export declare function renderOrdinalGridSVG(store: OrdinalPipelineStore, layout: {
+    width: number;
+    height: number;
+}, theme: SemioticTheme, idPrefix?: string): React.ReactNode;
+/** Wrap SVG content with accessibility attributes */
+export declare function wrapSVG(content: React.ReactNode, opts: {
+    width: number;
+    height: number;
+    className: string;
+    title?: string | React.ReactNode;
+    description?: string;
+    background?: string;
+    theme: SemioticTheme;
+    innerTransform: string;
+    innerWidth: number;
+    innerHeight: number;
+    legend?: React.ReactNode;
+    outerElements?: React.ReactNode;
+    defs?: React.ReactNode;
+    /** Prefix for SVG element IDs to avoid collisions in multi-chart documents */
+    idPrefix?: string;
+}): React.ReactElement;
+export declare function generateAxesSVG(scales: StreamScales, layout: StreamLayout, props: StreamXYFrameProps, theme: SemioticTheme, idPrefix?: string): React.ReactNode;
+export {};

package/dist/components/server/staticXY.d.ts

@@ -0,0 +1,4 @@
+import type { StreamXYFrameProps } from "../stream/types";
+import { type EvidenceSink } from "./renderEvidence";
+import type { ThemeAwareProps } from "./staticSVGChrome";
+export declare function renderStreamXYFrame(props: StreamXYFrameProps & ThemeAwareProps, sink?: EvidenceSink): string;

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

@@ -1,4 +1,6 @@
 import type { Datum } from "../charts/shared/datumTypes";
+import type { ControlObservation } from "../controls/controlContract";
+export type { ControlObservation } from "../controls/controlContract";
 interface ObservationBase {
     timestamp: number;
     chartType: string;
@@ -64,7 +66,7 @@ export interface LateDataObservation extends ObservationBase {
     /** 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 ChartObservation = HoverObservation | HoverEndObservation | BrushObservation | BrushEndObservation | SelectionObservation | SelectionEndObservation | ClickObservation | ClickEndObservation | ControlObservation | LateDataObservation;
 export type OnObservationCallback = (observation: ChartObservation) => void;
 export interface ObservationStoreState {
     /** Ring buffer of recent observations (newest last). Mutated in place for perf. */
@@ -76,4 +78,3 @@ export interface ObservationStoreState {
     clearObservations: () => void;
 }
 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/themeSerialization.d.ts

@@ -0,0 +1,32 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { SemioticTheme } from "./ThemeStore";
+/**
+ * Convert a SemioticTheme to a CSS custom properties string.
+ * Useful for SSR or generating stylesheet content.
+ *
+ * @param theme - A SemioticTheme object
+ * @param selector - CSS selector to scope the variables (default: `:root`)
+ * @returns CSS string with custom properties
+ *
+ * @example
+ * ```ts
+ * const css = themeToCSS(TUFTE_LIGHT, ".my-charts")
+ * // .my-charts {
+ * //   --semiotic-bg: #fffff8;
+ * //   --semiotic-text: #111111;
+ * //   ...
+ * // }
+ * ```
+ */
+export declare function themeToCSS(theme: SemioticTheme, selector?: string): string;
+/**
+ * Convert a SemioticTheme to a design tokens JSON object.
+ * Compatible with Style Dictionary / Design Token Community Group format.
+ *
+ * @example
+ * ```ts
+ * const tokens = themeToTokens(TUFTE_LIGHT)
+ * // { semiotic: { bg: { $value: "#fffff8", $type: "color" }, ... } }
+ * ```
+ */
+export declare function themeToTokens(theme: SemioticTheme): Datum;

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

@@ -2,6 +2,7 @@ import type { Datum } from "../charts/shared/datumTypes";
 import { type DataSummary } from "../data/DataSummarizer";
 import type { ChartDataProfile, Suggestion } from "../ai/chartCapabilityTypes";
 import type { IntentId } from "../ai/intents";
+import { type ChartReaderGrounding, type ChartReaderGroundingOptions } from "../ai/readerGrounding";
 /**
  * Identifies a single point of interest on the chart — typically the datum
  * the user is currently hovering, clicked, or otherwise focused on. When
@@ -31,6 +32,8 @@ export interface InterrogationContext {
     componentName?: string;
     /** Optional caller-supplied chart props (accessor names, scales, etc.). */
     props?: Record<string, unknown>;
+    /** Optional reader-grounding payload for faithful chart interpretation. */
+    grounding?: ChartReaderGrounding;
     /**
      * The current focused datum — what the user is interactively pointing at.
      * Lets the LLM tailor responses to a specific point ("why is *this* one
@@ -82,6 +85,12 @@ export interface UseChartInterrogationOptions {
      * `onObservation` callback or the convenience `useChartFocus` hook.
      */
     focus?: InterrogationFocus | null;
+    /**
+     * Include `buildReaderGrounding()` in the interrogation context. Pass true
+     * for default grounding, or an options object for capability/audience,
+     * structure, and physics runtime grounding controls.
+     */
+    includeGrounding?: boolean | ChartReaderGroundingOptions;
 }
 export interface UseChartInterrogationResult {
     /** Ask a question. Updates history, annotations, loading, and error. */

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

@@ -1,9 +1,7 @@
 import * as React from "react";
-/** Scene node type used by the accessible data table — accepts any frame's scene nodes */
-type AnySceneNode = {
-    type?: string;
-    [key: string]: any;
-};
+import { type AccessibleSceneNode as AnySceneNode } from "./accessibleDataRows";
+export { extractAllRows } from "./accessibleDataRows";
+export type { DataRow } from "./accessibleDataRows";
 declare const SR_ONLY_STYLE: React.CSSProperties;
 /**
  * Compute an aria-label describing the chart type and data shape from the scene graph.
@@ -13,14 +11,6 @@ export declare function computeCanvasAriaLabel(scene: AnySceneNode[] | null | un
  * Compute an aria-label for network charts from scene nodes and edges.
  */
 export declare function computeNetworkAriaLabel(nodeCount: number, edgeCount: number, chartType: string): string;
-interface DataRow {
-    label: string;
-    values: Record<string, string | number>;
-}
-/** Extract a flat list of typed rows from scene nodes, surfacing the raw datum
- *  fields (not pixel coordinates). Defensively handles missing/malformed data —
- *  never throws. Exported for direct testing. */
-export declare function extractAllRows(scene: AnySceneNode[]): DataRow[];
 interface AccessibleDataTableProps {
     scene: AnySceneNode[];
     chartType: string;

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

@@ -24,10 +24,12 @@ export interface FocusRingProps {
     /** Total chart size */
     size: [number, number];
     /** Shape hint from the focused nav point */
-    shape?: "circle" | "rect" | "wedge";
+    shape?: "circle" | "rect" | "wedge" | "geoarea" | "path";
     /** Width of rect-shaped focus target */
     width?: number;
     /** Height of rect-shaped focus target */
     height?: number;
+    /** SVG path (plot-relative) outlined for a geoarea focus. */
+    pathData?: string;
 }
-export declare function FocusRing({ active, hoverPoint, margin, size, shape, width, height }: FocusRingProps): React.JSX.Element | null;
+export declare function FocusRing({ active, hoverPoint, margin, size, shape, width, height, pathData }: FocusRingProps): React.JSX.Element | null;

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

@@ -16,4 +16,4 @@ export interface GeoHitResult {
  * The `hitCtx` parameter is a shared offscreen canvas context used for
  * isPointInPath checks without polluting the visible canvas.
  */
-export declare function findNearestGeoNode(nodes: GeoSceneNode[], mouseX: number, mouseY: number, maxDistance: number, hitCtx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, pointQuadtree?: Quadtree<PointSceneNode> | null, maxPointRadius?: number): GeoHitResult | null;
+export declare function findNearestGeoNode(nodes: GeoSceneNode[], mouseX: number, mouseY: number, maxDistance: number, hitCtx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, pointQuadtree?: Quadtree<PointSceneNode> | null, maxPointRadius?: number, lineMaxDistance?: number): GeoHitResult | null;

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

@@ -4,11 +4,29 @@ import type { GeoPipelineConfig, GeoScales, GeoSceneNode } from "./geoTypes";
 import type { PointSceneNode, StreamLayout } from "./types";
 import type { ActiveTransition } from "./pipelineTransitionUtils";
 import type { Datum } from "../charts/shared/datumTypes";
+import type { GeoLayoutResult } from "./geoCustomLayout";
+import type { CustomLayoutSelection } from "./customLayoutSelection";
+import { type CustomLayoutFailureDiagnostic } from "./customLayoutFailure";
 export declare class GeoPipelineStore {
     config: GeoPipelineConfig;
     scene: GeoSceneNode[];
     scales: GeoScales | null;
     version: number;
+    /** SVG overlays returned from the active custom layout. */
+    customLayoutOverlays: import("react").ReactNode;
+    /** Most recent custom layout result for host readback (`getCustomLayout()`).
+     *  Null before the first layout or without a custom layout. A failed
+     *  re-layout retains the prior good result alongside its diagnostic. */
+    lastCustomLayoutResult: GeoLayoutResult | null;
+    /** Most recent exception from a custom layout invocation, for host readback. */
+    lastCustomLayoutFailure: CustomLayoutFailureDiagnostic | null;
+    private _customLayoutDiagnosticsWarned;
+    private _customRestyle;
+    hasCustomRestyle: boolean;
+    private _baseStyles;
+    /** Set only while a custom-layout invocation throws. The rebuild callers use
+     *  it to retain the previous scene and projection state without mutating it. */
+    private _customLayoutFailedThisBuild;
     private static readonly QUADTREE_THRESHOLD;
     private _quadtree;
     /** Largest visual point radius in the current scene; used to widen quadtree
@@ -74,6 +92,16 @@ export declare class GeoPipelineStore {
      */
     removePoint(id: string | string[]): Datum[];
     clear(): void;
+    setLayoutSelection(selection: CustomLayoutSelection | null): void;
+    /**
+     * "Styles changed, repaint the data canvas without rebuilding the scene."
+     * Set by {@link restyleScene}; consumed once per frame by the paint loop, so a
+     * style-only selection change repaints without a projection/scene recompute.
+     */
+    private _stylePaintPending;
+    /** Consume the style-only repaint signal (see {@link _stylePaintPending}). */
+    consumeStylePaintPending(): boolean;
+    restyleScene(selection: CustomLayoutSelection | null): void;
     computeScene(layout: StreamLayout): void;
     private fitProjection;
     /**

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

@@ -1,6 +1,7 @@
 import { ParticlePool } from "./ParticlePool";
-import type { NetworkHtmlMark } from "./networkCustomLayout";
+import type { NetworkLayoutResult, NetworkHtmlMark } from "./networkCustomLayout";
 import type { CustomLayoutSelection } from "./customLayoutSelection";
+import { type CustomLayoutFailureDiagnostic } from "./customLayoutFailure";
 import type { ActiveTransition } from "./pipelineTransitionUtils";
 import { type Quadtree } from "d3-quadtree";
 import type { NetworkPipelineConfig, NetworkSceneNode, NetworkSceneEdge, NetworkCircleNode, NetworkLabel, RealtimeNode, RealtimeEdge, EdgePush } from "./networkTypes";
@@ -31,6 +32,12 @@ export declare class NetworkPipelineStore {
     labels: NetworkLabel[];
     /** Overlays returned from customNetworkLayout (consumed by StreamNetworkFrame). */
     customLayoutOverlays: import("react").ReactNode;
+    /** Most recent custom layout result for host readback (`getCustomLayout()`).
+     *  Null before the first layout or without a custom layout. A failed rerun
+     *  retains this last successful result when its rendered scene is reusable. */
+    lastCustomLayoutResult: NetworkLayoutResult | null;
+    /** Latest custom-layout failure for frame-handle readback. */
+    lastCustomLayoutFailure: CustomLayoutFailureDiagnostic | null;
     /** 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. */
@@ -83,6 +90,7 @@ export declare class NetworkPipelineStore {
     lastTopologyChangeTime: number;
     private previousNodeIds;
     private previousEdgeKeys;
+    private _networkDecayCache;
     /** Snapshot of node positions from the last layout — used for force warm-start */
     _lastPositionSnapshot: Map<string, {
         x: number;
@@ -99,7 +107,19 @@ export declare class NetworkPipelineStore {
      * Ingest bounded node/edge arrays (from props).
      * Clears existing topology and rebuilds from scratch.
      */
-    ingestBounded(rawNodes: any[], rawEdges: any[], size: [number, number]): void;
+    ingestBounded(rawNodes: any[], rawEdges: any[], size: [number, number], options?: {
+        deferLayout?: boolean;
+    }): void;
+    /**
+     * Apply worker-computed force positions through the normal layout finalizer.
+     * The force plugin still resolves edge endpoints, clamps bounds, records
+     * topology diffs, snapshots positions, and prepares transitions; it only
+     * skips the expensive simulation itself.
+     */
+    applyForceLayoutPositions(positions: Record<string, {
+        x: number;
+        y: number;
+    }>, size: [number, number]): void;
     /**
      * Unique key for an edge (same as TopologyStore).
      */
@@ -139,6 +159,15 @@ export declare class NetworkPipelineStore {
      * stays valid and no relayout/repack happens. The frame repaints the canvas
      * after calling this. No-op when the layout supplied no restyle callbacks.
      */
+    /**
+     * "Styles changed, repaint the data canvas without rebuilding the scene."
+     * Set by {@link restyleScene}; consumed once per frame by the paint loop.
+     * Deliberately separate from `_sceneNodesRevision` (the quadtree-invalidation
+     * counter) so a style-only selection change repaints without a relayout.
+     */
+    private _stylePaintPending;
+    /** Consume the style-only repaint signal (see {@link _stylePaintPending}). */
+    consumeStylePaintPending(): boolean;
     restyleScene(selection: CustomLayoutSelection | null): void;
     buildScene(size: [number, number]): void;
     /**
@@ -198,37 +227,13 @@ export declare class NetworkPipelineStore {
     private restorePreviousPositions;
     private snapToTargets;
     private updateEdgeBezier;
-    private buildStandardBezier;
-    private buildCircularBezier;
     rebuildAllBeziers(): void;
-    /**
-     * Apply pulse glow to scene nodes/edges based on their creation timestamps.
-     */
     applyPulse(now: number): void;
-    /**
-     * Apply decay opacity to scene nodes based on topology age order.
-     * Older nodes (created earlier) are more faded.
-     */
     applyDecay(): void;
-    /**
-     * Apply topology diff highlight — newly added nodes glow briefly.
-     * Duration: 2 seconds from lastTopologyChangeTime.
-     */
     applyTopologyDiff(now: number): void;
-    /** Whether there is an active topology diff animation */
     get hasActiveTopologyDiff(): boolean;
-    /**
-     * Apply threshold alerting to scene nodes.
-     * Overrides fill color and adds pulse for nodes exceeding thresholds.
-     */
     applyThresholds(now: number): void;
-    /**
-     * Whether there are active threshold alerts on any node.
-     */
     get hasActiveThresholds(): boolean;
-    /**
-     * Whether there are active pulse animations (recent ingests within pulse duration).
-     */
     get hasActivePulses(): boolean;
     getLayoutData(): {
         nodes: RealtimeNode[];

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

@@ -5,6 +5,7 @@ import type { NetworkLabel } from "./networkTypes";
 import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/legendTypes";
 import { type AutoPlaceAnnotations } from "../recipes/annotationLayout";
 import type { AnnotationContext } from "../realtime/types";
+import { type GlyphDef } from "./glyphDef";
 type AnnotationAnchorNode = {
     type: string;
     datum: Datum | null;
@@ -19,8 +20,10 @@ 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. */
+    /** Symbol nodes carry a d3-symbol area; glyph nodes reuse `size` as rendered height. */
     size?: number;
+    /** Glyph nodes (the composite-pictogram channel) carry a definition. */
+    glyph?: GlyphDef;
 };
 type NetworkAnnotationContext = AnnotationContext & {
     sceneNodes?: AnnotationAnchorNode[];