semiotic 3.7.4 → 3.8.0

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

@@ -0,0 +1,170 @@
+import type { PointSceneNode, RectSceneNode, SceneDatum } from "./types";
+import type { GeoAreaSceneNode } from "./geoTypes";
+import type { NetworkCircleNode, NetworkRectNode } from "./networkTypes";
+/** Default hit/keyboard-focus radius (px) — larger than a typical glyph so the
+ *  target is easy to hit by pointer and to land on by keyboard (Fitts's law). */
+export declare const DEFAULT_HIT_RADIUS = 8;
+export interface HitTargetPointProps {
+    /** Plot-relative x of the mark's center. */
+    x: number;
+    /** Plot-relative y of the mark's center. */
+    y: number;
+    /** The raw user datum to surface on hover/click/focus and in the data table. */
+    datum: SceneDatum;
+    /** Stable identity. Set as the node's `pointId` (annotation anchor + nav-tree
+     *  leaf match) *and* its transition key, so the mark keeps identity across
+     *  re-layouts. Strongly recommended for interactive/animated custom charts. */
+    id?: string | number;
+    /** Hit + keyboard-focus radius in px. @default {@link DEFAULT_HIT_RADIUS} */
+    r?: number;
+}
+/**
+ * A transparent, hit-testable **point** node for a custom XY or ordinal layout
+ * whose visible marks live in `overlays`. Inherits keyboard navigation, the
+ * focus ring, annotation anchoring (by `id` → `pointId`), tooltip/`onObservation`
+ * emission, and transition identity. See the module overview for the full
+ * contract.
+ *
+ * @example
+ * ```ts
+ * nodes: ctx.data.map((row) => {
+ *   const { x, y } = polarToXY(angle(row.day), radius(row.value))
+ *   return hitTargetPoint({ x, y, datum: row, id: `day-${row.day}` })
+ * })
+ * ```
+ */
+export declare function hitTargetPoint(props: HitTargetPointProps): PointSceneNode;
+/**
+ * A transparent, hit-testable point node for a custom **geo** layout whose
+ * visible marks (sprites, icons, forts) live in `overlays`. Project a lon/lat
+ * with `ctx.scales.projectedPoint(lon, lat)` first, then pass the resulting
+ * `x` / `y`. Functionally identical to {@link hitTargetPoint} — geo scenes use
+ * the same `PointSceneNode` — but named for discoverability: it makes
+ * overlay-drawn geographic marks keyboard-navigable, focus-ringed, and
+ * annotation-anchorable, exactly as {@link networkHitTarget} does for networks.
+ *
+ * @example
+ * ```ts
+ * // inside a GeoCustomChart layout
+ * nodes: pois.map((p) => {
+ *   const [x, y] = ctx.scales.projectedPoint(p.lon, p.lat)!
+ *   return geoHitTarget({ x, y, datum: p, id: p.id })
+ * })
+ * ```
+ */
+export declare function geoHitTarget(props: HitTargetPointProps): PointSceneNode;
+export interface GeoAreaHitTargetProps {
+    /** SVG path string in plot-relative screen coordinates. */
+    pathData: string;
+    /** Screen-space centroid for tooltip and focus positioning. */
+    centroid: [number, number];
+    /** Screen-space bounds as [[x0, y0], [x1, y1]]. */
+    bounds: [[number, number], [number, number]];
+    /** The raw user datum to surface on hover/click/focus and in the data table. */
+    datum: SceneDatum;
+    /** Optional series/category key for grouped selection + legend interaction. */
+    group?: string;
+    /** Screen-space area in px^2. Defaults to the bounding-box area. */
+    screenArea?: number;
+}
+/**
+ * A transparent, hit-testable **area** node for a custom geo layout whose
+ * visible polygons live in `overlays`. Use this when the semantic mark is not
+ * point-like: isometric tiles, schematic regions, hex/cell maps, contour bands,
+ * or any hand-built path that should retain GeoFrame hover, keyboard focus,
+ * tooltips, accessible rows, and shape-aware canvas hit testing.
+ *
+ * @example
+ * ```ts
+ * return geoAreaHitTarget({
+ *   pathData: diamondPath(x, y, tileWidth, tileHeight),
+ *   centroid: [x, y],
+ *   bounds: [[x - tileWidth / 2, y - tileHeight / 2], [x + tileWidth / 2, y + tileHeight / 2]],
+ *   screenArea: (tileWidth * tileHeight) / 2,
+ *   datum: tile,
+ *   group: tile.kind,
+ * })
+ * ```
+ */
+export declare function geoAreaHitTarget(props: GeoAreaHitTargetProps): GeoAreaSceneNode;
+export interface HitTargetRectProps {
+    /** Plot-relative x of the rect's top-left corner. */
+    x: number;
+    /** Plot-relative y of the rect's top-left corner. */
+    y: number;
+    /** Rect width in px. */
+    width: number;
+    /** Rect height in px. */
+    height: number;
+    /** The raw user datum to surface on hover/click/focus and in the data table. */
+    datum: SceneDatum;
+    /** Stable identity — used as the transition key, and as `group` for shared
+     *  selection. (Rect nodes anchor annotations by their center via the
+     *  point-anchor harvest only on network; for XY/ordinal pair a rect hit area
+     *  with {@link hitTargetPoint} if you need annotation anchoring.) */
+    id?: string | number;
+    /** Optional series/category key for grouped selection + legend interaction. */
+    group?: string;
+}
+/**
+ * A transparent, hit-testable **rect** node for a custom XY or ordinal layout —
+ * the rectangular sibling of {@link hitTargetPoint}, for marks that read as a
+ * box (a bar, an interval lane segment, a labelled card). Same free interaction:
+ * keyboard nav, focus ring, tooltip/`onObservation`, transition identity.
+ */
+export declare function hitTargetRect(props: HitTargetRectProps): RectSceneNode;
+export interface NetworkHitTargetCircleProps {
+    /** Plot-relative x of the mark's center. */
+    x: number;
+    /** Plot-relative y of the mark's center. */
+    y: number;
+    /** The raw user datum (the object you passed in `nodes`, typically `node.data`). */
+    datum: SceneDatum;
+    /** Stable identity — set as the node `id`, which is how a `pointId`-anchored
+     *  annotation resolves to this mark and how shared selection keys it. */
+    id?: string | number;
+    /** Hit + keyboard-focus radius in px. @default {@link DEFAULT_HIT_RADIUS} */
+    r?: number;
+    /** Optional accessible label override for the node. */
+    label?: string;
+}
+export interface NetworkHitTargetRectProps {
+    /** Plot-relative x of the rect's top-left corner. */
+    x: number;
+    /** Plot-relative y of the rect's top-left corner. */
+    y: number;
+    /** Rect width in px. */
+    width: number;
+    /** Rect height in px. */
+    height: number;
+    /** The raw user datum (the object you passed in `nodes`, typically `node.data`). */
+    datum: SceneDatum;
+    /** Stable identity — set as the node `id` for annotation anchoring + selection. */
+    id?: string | number;
+    /** Optional accessible label override for the node. */
+    label?: string;
+}
+/**
+ * A transparent, hit-testable node for a custom **network** layout. Pass `width`
+ * + `height` for a rect (a labelled box / card), or omit them for a circle of
+ * radius `r`. Every network scene node is harvested as an annotation anchor, so
+ * `id` resolves a `{ pointId: id }` annotation to this mark. Inherits the same
+ * keyboard nav, focus ring, tooltip/`onObservation`, and shared-selection
+ * threading the built-in network charts get.
+ *
+ * @example
+ * ```ts
+ * sceneNodes: positioned.map((node) =>
+ *   networkHitTarget({
+ *     x: node.x - node.width / 2,
+ *     y: node.y - node.height / 2,
+ *     width: node.width,
+ *     height: node.height,
+ *     datum: node,
+ *     id: node.id,
+ *   })
+ * )
+ * ```
+ */
+export declare function networkHitTarget(props: NetworkHitTargetRectProps): NetworkRectNode;
+export declare function networkHitTarget(props: NetworkHitTargetCircleProps): NetworkCircleNode;

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

@@ -18,7 +18,10 @@ import type { HoverData } from "../realtime/types";
 export interface HoverPointerCoords {
     clientX: number;
     clientY: number;
+    pointerType?: string;
 }
+export declare const TOUCH_HIT_RADIUS = 24;
+export declare function getPointerHitRadius(baseRadius: number, pointerType?: string): number;
 export declare function normalizeHoverDatum(rawDatum: any): any;
 /**
  * Build a HoverData object from a raw datum and pixel coordinates.

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

@@ -20,11 +20,14 @@ export interface NavPoint {
     y: number;
     datum: Datum | null;
     /** Shape hint for focus ring rendering */
-    shape?: "circle" | "rect" | "wedge";
+    shape?: "circle" | "rect" | "wedge" | "geoarea";
     /** Width of rect-shaped elements (bars, sankey nodes) */
     w?: number;
     /** Height of rect-shaped elements */
     h?: number;
+    /** SVG path (plot-relative) for a geoarea focus ring — the shape is
+     *  outlined instead of drawing a circle at the centroid. */
+    pathData?: string;
     /** Group identifier for graph navigation (series name, category, node id) */
     group?: string;
     /** Index in NavGraph.flat — set by buildNavGraph for O(1) lookup */

package/dist/components/stream/layouts/forceLayoutPlugin.d.ts

@@ -1,2 +1,10 @@
-import type { NetworkLayoutPlugin } from "../networkTypes";
+import type { NetworkLayoutPlugin, RealtimeNode } from "../networkTypes";
+import type { Datum } from "../../charts/shared/datumTypes";
 export declare const forceLayoutPlugin: NetworkLayoutPlugin;
+/**
+ * Build a function that returns a node radius. If `nodeSize` is a number,
+ * use it directly. If it is a string accessor, look up `node.data[nodeSize]`
+ * and scale the result to `nodeSizeRange`. If it is a function, call it.
+ * Falls back to a default radius of 8.
+ */
+export declare function resolveNodeSizeFn(nodeSize: number | string | ((d: Datum) => number) | undefined, nodeSizeRange: [number, number] | undefined, allNodes: RealtimeNode[]): (node: RealtimeNode) => number;

package/dist/components/stream/layouts/forceLayoutWorkerClient.d.ts

@@ -0,0 +1,57 @@
+import type { GraphEdge, GraphNode, Point } from "../../recipes/networkAnalysis";
+import type { ForceLayoutOptions } from "../../recipes/forceLayout";
+import type { NetworkPipelineConfig, RealtimeEdge, RealtimeNode } from "../networkTypes";
+export type ForceLayoutExecution = "auto" | "worker" | "sync";
+export interface NormalizedForceWorkerRequest {
+    kind: "normalized";
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    options: Omit<ForceLayoutOptions, "nodeRadius">;
+    nodeRadii?: Record<string, number>;
+}
+export interface FrameForceWorkerRequest {
+    kind: "frame";
+    nodes: RealtimeNode[];
+    edges: RealtimeEdge[];
+    config: {
+        chartType: "force";
+        iterations?: number;
+        forceStrength?: number;
+    };
+    size: [number, number];
+}
+export type ForceWorkerRequest = NormalizedForceWorkerRequest | FrameForceWorkerRequest;
+export interface ForceWorkerResponse {
+    positions: Record<string, Point>;
+}
+export declare const DEFAULT_FORCE_WORKER_THRESHOLD = 40000;
+export declare function shouldUseForceWorker(execution: ForceLayoutExecution, nodeCount: number, edgeCount: number, iterations: number, threshold?: number): boolean;
+export declare function canUseForceWorker(): boolean;
+export declare function createForceLayoutWorker(): Worker;
+export declare function createFrameForceWorkerRequest(nodes: RealtimeNode[], edges: RealtimeEdge[], config: NetworkPipelineConfig, size: [number, number], previousPositions?: Map<string, {
+    x: number;
+    y: number;
+}> | null): FrameForceWorkerRequest;
+/**
+ * Long-lived force-layout worker session. Mirrors PhysicsWorkerSession:
+ * one Worker is reused across layouts so module parse + startup cost is
+ * paid once per page, not once per graph re-layout.
+ */
+export declare class ForceLayoutWorkerSession {
+    private nextRequestId;
+    private pending;
+    private worker;
+    private dead;
+    constructor(worker?: Worker);
+    get isDead(): boolean;
+    request(request: ForceWorkerRequest, signal?: AbortSignal): Promise<ForceWorkerResponse>;
+    terminate(): void;
+    private rejectAll;
+}
+/** Test helper: drop the shared session so the next call creates a fresh Worker. */
+export declare function _resetSharedForceLayoutSessionForTest(): void;
+/**
+ * Run a force layout on a reused worker session.
+ * Prefer this over constructing a new Worker per layout.
+ */
+export declare function runForceLayoutWorker(request: ForceWorkerRequest, signal?: AbortSignal): Promise<ForceWorkerResponse>;

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

@@ -0,0 +1,10 @@
+import type { BezierCache, RealtimeEdge, RealtimeNode } from "./networkTypes";
+/** Default cubic control-point curvature (fraction of span). */
+export declare const NETWORK_EDGE_CURVATURE = 0.5;
+export declare function buildStandardBezier(edge: RealtimeEdge, sourceNode: RealtimeNode, targetNode: RealtimeNode, curvature?: number): BezierCache;
+export declare function buildCircularBezier(edge: RealtimeEdge, curvature?: number): BezierCache;
+/**
+ * Resolve source/target RealtimeNodes and attach the edge's bezier cache.
+ * Returns false if endpoints cannot be resolved.
+ */
+export declare function updateEdgeBezier(edge: RealtimeEdge, nodes: Map<string, RealtimeNode>, curvature?: number): boolean;

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

@@ -0,0 +1,49 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { RealtimeEdge, RealtimeNode } from "./networkTypes";
+export declare function resolveNetworkEdgeEndpoint(endpoint: RealtimeNode | string | undefined, nodes: Map<string, RealtimeNode> | undefined): RealtimeNode | null;
+export declare function resolveNetworkNodeColor(options: {
+    node: RealtimeNode;
+    colorBy?: string | ((node: RealtimeNode) => unknown);
+    colorScheme?: string | string[] | Record<string, string>;
+    nodeColorMap: Map<string, string>;
+    colorIndexRef: {
+        current: number;
+    };
+}): string;
+export declare function resolveNetworkEdgeColor(options: {
+    edge: RealtimeEdge;
+    edgeColorBy?: string | ((edge: RealtimeEdge) => string);
+    getNodeColor: (node: RealtimeNode) => string;
+    resolveEndpoint: (endpoint: RealtimeNode | string | undefined) => RealtimeNode | null;
+    fallback: string;
+}): string;
+export declare function resolveNetworkParticleColor(options: {
+    edge: RealtimeEdge;
+    particleStyleColor?: string | ((edge: RealtimeEdge, node: RealtimeNode) => string);
+    particleColorBy?: string;
+    hasExplicitParticleColorBy: boolean;
+    getEdgeColor: (edge: RealtimeEdge) => string;
+    getNodeColor: (node: RealtimeNode) => string;
+    resolveEndpoint: (endpoint: RealtimeNode | string | undefined) => RealtimeNode | null;
+    fallback: string;
+}): string;
+/** Sync scene fills into the node color map; fill gaps from palette. */
+export declare function syncNetworkNodeColorMap(options: {
+    sceneNodes: ReadonlyArray<{
+        id?: string;
+        style?: {
+            fill?: unknown;
+        };
+    }>;
+    nodes: Iterable<RealtimeNode>;
+    nodeColorMap: Map<string, string>;
+    colorScheme?: string | string[] | Record<string, string>;
+}): number;
+export declare function networkEdgeFallbackColor(theme: {
+    colors?: {
+        border?: string;
+        secondary?: string;
+        primary?: string;
+    };
+} | null | undefined): string;
+export type { Datum };

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

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

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

@@ -0,0 +1,10 @@
+/**
+ * Default network hover tooltip for StreamNetworkFrame.
+ * Uses shared `defaultTooltipStyle` for theme CSS-var consistency.
+ */
+import * as React from "react";
+import type { HoverData } from "../realtime/types";
+declare function DefaultNetworkTooltip({ data }: {
+    data: HoverData;
+}): React.JSX.Element | null;
+export { DefaultNetworkTooltip };

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

@@ -0,0 +1,37 @@
+/**
+ * Pointer hit-testing helpers for StreamNetworkFrame hover/click.
+ * Returns a structured result so the frame owns React setState.
+ */
+import type { HoverData } from "../realtime/types";
+import { type HoverPointerCoords } from "./hoverUtils";
+import type { NetworkSceneEdge, NetworkSceneNode } from "./networkTypes";
+import type { Quadtree } from "d3-quadtree";
+import type { NetworkCircleNode } from "./networkTypes";
+export type NetworkPointerHit = {
+    kind: "miss-outside";
+} | {
+    kind: "miss";
+} | {
+    kind: "hit";
+    hover: HoverData;
+};
+export declare function resolveNetworkPointerHit(options: {
+    clientX: number;
+    clientY: number;
+    canvasRect: DOMRect;
+    margin: {
+        left: number;
+        top: number;
+    };
+    adjustedWidth: number;
+    adjustedHeight: number;
+    sceneNodes: NetworkSceneNode[];
+    sceneEdges: NetworkSceneEdge[];
+    nodeQuadtree: Quadtree<NetworkCircleNode> | null;
+    maxNodeRadius: number;
+    hitRadius?: number;
+}): NetworkPointerHit;
+export declare function pointerFromMouseEvent(e: {
+    clientX: number;
+    clientY: number;
+}): HoverPointerCoords;

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

@@ -0,0 +1,43 @@
+import type { NetworkPipelineStore } from "./NetworkPipelineStore";
+import type { NetworkPipelineConfig, ParticleStyle, RealtimeEdge } from "./networkTypes";
+import type { MarginType } from "../types/marginType";
+import type { DecayConfig, PulseConfig, StalenessConfig } from "./types";
+export interface NetworkFramePaintContext {
+    canvas: HTMLCanvasElement;
+    store: NetworkPipelineStore;
+    size: [number, number];
+    margin: MarginType;
+    adjustedWidth: number;
+    adjustedHeight: number;
+    background?: string;
+    dirtyRef: {
+        current: boolean;
+    };
+    lastFrameTimeRef: {
+        current: number;
+    };
+    reducedMotion: boolean;
+    showParticles: boolean;
+    isContinuous: boolean;
+    /** Truthy animate (boolean or config object) enables topology-diff pulses. */
+    animate: unknown;
+    decay?: DecayConfig;
+    pulse?: PulseConfig;
+    thresholds?: NetworkPipelineConfig["thresholds"];
+    staleness?: StalenessConfig;
+    particleStyle: ParticleStyle;
+    getParticleColor: (edge: RealtimeEdge, node?: unknown) => string;
+    pendingAnnotationFrameRef: {
+        current: boolean;
+    };
+    lastAnnotationFrameTimeRef: {
+        current: number;
+    };
+    setAnnotationFrame: (updater: (f: number) => number) => void;
+    scheduleNextFrame: () => void;
+}
+/**
+ * Run one paint tick. Returns whether another rAF should be scheduled
+ * (also invoked via scheduleNextFrame for continuous modes).
+ */
+export declare function paintNetworkFrame(ctx: NetworkFramePaintContext): void;

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

@@ -0,0 +1,22 @@
+/**
+ * Build NetworkPipelineConfig from StreamNetworkFrame props + theme.
+ * Keeps the large useMemo payload out of the React component file.
+ */
+import type { SemioticTheme } from "../store/ThemeStore";
+import type { NetworkPipelineConfig } from "./networkTypes";
+import type { StreamNetworkFrameProps } from "./networkTypes";
+export type NetworkPipelineConfigSources = Pick<StreamNetworkFrameProps, "chartType" | "nodeIDAccessor" | "sourceAccessor" | "targetAccessor" | "valueAccessor" | "edgeIdAccessor" | "childrenAccessor" | "hierarchySum" | "orientation" | "nodeAlign" | "nodePaddingRatio" | "nodeWidth" | "iterations" | "forceStrength" | "padAngle" | "groupWidth" | "sortGroups" | "edgeSort" | "treeOrientation" | "edgeType" | "padding" | "paddingTop" | "nodeStyle" | "edgeStyle" | "nodeLabel" | "showLabels" | "labelMode" | "colorBy" | "colorScheme" | "edgeColorBy" | "edgeOpacity" | "colorByDepth" | "nodeSize" | "nodeSizeRange" | "decay" | "pulse" | "transition" | "staleness" | "thresholds" | "orbitMode" | "orbitSize" | "orbitSpeed" | "orbitRevolution" | "orbitRevolutionStyle" | "orbitEccentricity" | "orbitShowRings" | "orbitAnimated" | "customNetworkLayout" | "onLayoutError" | "layoutConfig"> & {
+    tensionConfig: NetworkPipelineConfig["tensionConfig"];
+    showParticles: boolean;
+    particleStyle: NetworkPipelineConfig["particleStyle"];
+    introAnimation: boolean;
+    currentTheme: SemioticTheme | null | undefined;
+};
+export declare function buildNetworkPipelineConfig(sources: NetworkPipelineConfigSources): NetworkPipelineConfig;
+/** Fields that force re-ingest / re-layout when changed. */
+export type NetworkLayoutConfigSignature = Pick<NetworkPipelineConfigSources, "chartType" | "nodeIDAccessor" | "sourceAccessor" | "targetAccessor" | "valueAccessor" | "edgeIdAccessor" | "childrenAccessor" | "hierarchySum" | "orientation" | "nodeAlign" | "nodePaddingRatio" | "nodeWidth" | "iterations" | "forceStrength" | "padAngle" | "groupWidth" | "sortGroups" | "edgeSort" | "treeOrientation" | "edgeType" | "padding" | "paddingTop" | "tensionConfig" | "customNetworkLayout"> & {
+    orbitMode?: NetworkPipelineConfigSources["orbitMode"];
+    orbitSize?: NetworkPipelineConfigSources["orbitSize"];
+    orbitEccentricity?: NetworkPipelineConfigSources["orbitEccentricity"];
+};
+export declare function buildNetworkLayoutConfigSignature(sources: NetworkLayoutConfigSignature): Record<string, unknown>;

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

@@ -0,0 +1,12 @@
+/**
+ * Network pipeline pure helpers (node factory + bezier cache validation).
+ */
+import type { RealtimeNode, BezierCache } from "./networkTypes";
+export declare function createNode(id: string): RealtimeNode;
+/** Validate a value matches the `BezierCache` shape before assigning it
+ *  to a `RealtimeEdge`. The particle pipeline reads
+ *  `edge.bezier.points[i].x` etc. unguarded — a malformed bezier
+ *  (e.g. `bezier: true`, missing points, non-finite coords) would
+ *  crash the canvas frame loop. */
+export declare function isValidBezierCache(value: unknown): value is BezierCache;
+export declare function isFourFinitePoints(pts: unknown): boolean;

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

@@ -0,0 +1,41 @@
+import type { NetworkSceneEdge, NetworkSceneNode, RealtimeNode } from "./networkTypes";
+import type { DecayConfig, PulseConfig } from "./types";
+import type { NetworkPipelineConfig } from "./networkTypes";
+export type NetworkTimestampMap = Map<string, number>;
+export declare function applyNetworkPulse(options: {
+    sceneNodes: NetworkSceneNode[];
+    sceneEdges: NetworkSceneEdge[];
+    nodeTimestamps: NetworkTimestampMap;
+    edgeTimestamps: NetworkTimestampMap;
+    pulse: PulseConfig | undefined;
+    now: number;
+}): void;
+export interface NetworkDecayCache {
+    sortedNodes: [string, number][] | null;
+    ageMap: Map<string, number> | null;
+}
+export declare function applyNetworkDecay(options: {
+    sceneNodes: NetworkSceneNode[];
+    nodeTimestamps: NetworkTimestampMap;
+    decay: DecayConfig | undefined;
+    cache: NetworkDecayCache;
+}): void;
+export declare function applyNetworkTopologyDiff(options: {
+    sceneNodes: NetworkSceneNode[];
+    addedNodes: Set<string>;
+    lastTopologyChangeTime: number;
+    now: number;
+}): void;
+export declare function hasActiveNetworkTopologyDiff(addedNodes: Set<string>, lastTopologyChangeTime: number, now?: number): boolean;
+export declare function applyNetworkThresholds(options: {
+    sceneNodes: NetworkSceneNode[];
+    nodes: Map<string, RealtimeNode>;
+    thresholds: NetworkPipelineConfig["thresholds"];
+    now: number;
+}): void;
+export declare function hasActiveNetworkThresholds(nodes: Iterable<RealtimeNode>, thresholds: NetworkPipelineConfig["thresholds"]): boolean;
+export declare function hasActiveNetworkPulses(options: {
+    pulse: PulseConfig | undefined;
+    lastIngestTime: number;
+    now?: number;
+}): boolean;