semiotic 3.5.1 → 3.5.3

package/ai/system-prompt.md

@@ -1,6 +1,9 @@
 # Semiotic — React Data Visualization
 
-Use sub-path imports: `semiotic/xy` (143KB gz), `semiotic/ordinal` (109KB), `semiotic/network` (98KB), `semiotic/geo` (93KB), `semiotic/realtime` (145KB). Or `semiotic/ai` for all 39 non-geo HOCs in one import (269KB).
+<!-- semiotic-bundle-sizes:start -->
+<!-- Auto-generated by scripts/sync-bundle-sizes.mjs — do not edit by hand. -->
+**Use sub-path imports** — `semiotic/xy` (85KB gz), `semiotic/ordinal` (68KB gz), `semiotic/network` (63KB gz), `semiotic/geo` (51KB gz), `semiotic/realtime` (90KB gz), `semiotic/server` (117KB gz), `semiotic/utils` (22KB gz), `semiotic/recipes` (5KB gz), `semiotic/themes` (4KB gz), `semiotic/data` (3KB gz), `semiotic/ai` (188KB gz). Full `semiotic` is 186KB gz.
+<!-- semiotic-bundle-sizes:end -->
 
 ## Flat Array Data (`data: object[]`)
 - **LineChart** — `xAccessor`, `yAccessor`, `lineBy` (multi-line), `curve`

package/dist/components/ThemeProvider.d.ts

@@ -1,10 +1,10 @@
 import * as React from "react";
 import { LIGHT_THEME, DARK_THEME, HIGH_CONTRAST_THEME } from "./store/ThemeStore";
-import type { SemioticTheme } from "./store/ThemeStore";
+import type { SemioticTheme, SemioticThemeUpdate } from "./store/ThemeStore";
 import type { ThemePresetName } from "./semiotic-themes";
 interface ThemeProviderProps {
     /** Theme preset name (e.g. "tufte", "pastels-dark", "bi-tool") or a partial SemioticTheme object. */
-    theme?: ThemePresetName | Partial<SemioticTheme>;
+    theme?: ThemePresetName | SemioticThemeUpdate;
     children: React.ReactNode;
 }
 declare function ThemeProviderWrapper({ theme, children }: ThemeProviderProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/Tooltip/FlippingTooltip.d.ts

@@ -29,6 +29,21 @@ interface FlippingTooltipProps {
  * On first render, uses a heuristic (similar to the old 70%/30% thresholds).
  * After measuring the actual tooltip size via ref, repositions precisely to
  * prevent clipping against container edges.
+ *
+ * Two defensive behaviors:
+ *
+ *   - **Chrome guarantee.** If the rendered tooltip content lacks the
+ *     `semiotic-tooltip` className on its root, the wrapper applies
+ *     `defaultTooltipStyle` to itself so the tooltip always has a
+ *     visible background, padding, and shadow. Shared tooltip helpers
+ *     keep working unchanged (their `semiotic-tooltip` class causes the
+ *     wrapper to stay transparent).
+ *   - **Non-finite position guard.** Returns `null` when `x` or `y` is
+ *     `NaN` / `Infinity`. The frame's hover plumbing can occasionally
+ *     produce a non-finite hit-test result during a scale rebuild or
+ *     when a custom layout emits a degenerate vertex; without the
+ *     guard, React throws `'NaN' is an invalid value for the 'top' css
+ *     style property` and the entire frame stops rendering.
  */
-export declare function FlippingTooltip({ x, y, containerWidth, containerHeight, margin, children, className, zIndex }: FlippingTooltipProps): import("react/jsx-runtime").JSX.Element;
+export declare function FlippingTooltip({ x, y, containerWidth, containerHeight, margin, children, className, zIndex }: FlippingTooltipProps): import("react/jsx-runtime").JSX.Element | null;
 export {};

package/dist/components/charts/geo/FlowMap.d.ts

@@ -1,5 +1,7 @@
 import type { Datum } from "../shared/datumTypes";
+import * as React from "react";
 import type { StreamGeoFrameProps, ProjectionProp } from "../../stream/geoTypes";
+import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
@@ -79,6 +81,13 @@ export interface FlowMapProps<TDatum extends Datum = Datum> extends BaseChartPro
     tileCacheSize?: number;
     /** Annotations */
     annotations?: Datum[];
+    /**
+     * ID accessor on flow records — required for `ref.current.remove(id)`
+     * and `ref.current.update(id, …)`. The accessor reads the same field
+     * the user supplies on each flow; the field is preserved on the
+     * resolved line entry so the frame's `removeLine` can match by id.
+     */
+    lineIdAccessor?: string | ((d: Datum) => string);
     /** Passthrough */
     frameProps?: Partial<Omit<StreamGeoFrameProps, "projection">>;
 }
@@ -132,7 +141,7 @@ export interface FlowMapProps<TDatum extends Datum = Datum> extends BaseChartPro
  * />
  * ```
  */
-export declare function FlowMap<TDatum extends Datum = Datum>(props: FlowMapProps<TDatum>): import("react/jsx-runtime").JSX.Element;
-export declare namespace FlowMap {
-    var displayName: string;
-}
+export declare const FlowMap: {
+    <TDatum extends Datum = Datum>(props: FlowMapProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/components/charts/index.d.ts

@@ -14,6 +14,8 @@ export { LineChart } from "./xy/LineChart";
 export type { LineChartProps } from "./xy/LineChart";
 export { AreaChart } from "./xy/AreaChart";
 export type { AreaChartProps } from "./xy/AreaChart";
+export { DifferenceChart } from "./xy/DifferenceChart";
+export type { DifferenceChartProps } from "./xy/DifferenceChart";
 export { StackedAreaChart } from "./xy/StackedAreaChart";
 export type { StackedAreaChartProps } from "./xy/StackedAreaChart";
 export { Heatmap } from "./xy/Heatmap";
@@ -72,6 +74,10 @@ export { ChordDiagram } from "./network/ChordDiagram";
 export type { ChordDiagramProps } from "./network/ChordDiagram";
 export { SankeyDiagram } from "./network/SankeyDiagram";
 export type { SankeyDiagramProps } from "./network/SankeyDiagram";
+export { ProcessSankey } from "./network/ProcessSankey";
+export type { ProcessSankeyProps, ProcessSankeyTick } from "./network/ProcessSankey";
+export { validateProcessSankey, formatProcessSankeyIssue, } from "./network/processSankey/algorithm";
+export type { ProcessSankeyNode as ProcessSankeyValidatorNode, ProcessSankeyEdge as ProcessSankeyValidatorEdge, ProcessSankeyIssue, } from "./network/processSankey/algorithm";
 export { TreeDiagram } from "./network/TreeDiagram";
 export type { TreeDiagramProps } from "./network/TreeDiagram";
 export { Treemap } from "./network/Treemap";

package/dist/components/charts/network/OrbitDiagram.d.ts

@@ -4,7 +4,7 @@ import type { StreamNetworkFrameProps } from "../../stream/networkTypes";
 import type { BaseChartProps } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 export interface OrbitNode {
-    datum: any;
+    datum: Datum;
     x: number;
     y: number;
     ring: number;
@@ -38,11 +38,11 @@ export interface OrbitDiagramProps<TDatum extends Datum = Datum> extends BaseCha
      */
     orbitMode?: OrbitMode;
     /** Ring size divisor per depth. Larger = tighter orbits. @default 2.95 */
-    orbitSize?: number | ((node: any) => number);
+    orbitSize?: number | ((node: Datum) => number);
     /** Orbit speed in degrees per frame @default 0.25 */
     speed?: number;
     /** Per-node speed modifier @default (node) => 1 / (node.depth + 1) */
-    revolution?: (node: any) => number;
+    revolution?: (node: Datum) => number;
     /**
      * Built-in revolution style presets:
      * - "locked": children rotate with parent at decreasing speed (default)
@@ -53,11 +53,11 @@ export interface OrbitDiagramProps<TDatum extends Datum = Datum> extends BaseCha
      */
     revolutionStyle?: "locked" | "decay" | "alternate";
     /** Vertical squash for elliptical orbits. 1 = circle, 0.5 = ellipse @default 1 */
-    eccentricity?: number | ((node: any) => number);
+    eccentricity?: number | ((node: Datum) => number);
     /** Show orbital ring paths @default true */
     showRings?: boolean;
     /** Node radius. Number or function of node. @default 6 */
-    nodeRadius?: number | ((node: any) => number);
+    nodeRadius?: number | ((node: Datum) => number);
     /** Show node labels @default false */
     showLabels?: boolean;
     /** Enable animation @default true */

package/dist/components/charts/network/ProcessSankey.d.ts

@@ -0,0 +1,163 @@
+import * as React from "react";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+import type { StreamNetworkFrameProps, ParticleStyle } from "../../stream/networkTypes";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+type TimeLike = number | Date | string;
+export interface ProcessSankeyTick {
+    date: TimeLike;
+    label: string;
+}
+export interface ProcessSankeyProps<TNode extends Datum = Datum, TEdge extends Datum = Datum> extends BaseChartProps {
+    nodes?: TNode[];
+    edges?: TEdge[];
+    /** [tStart, tEnd] of the chart's x-axis. Required. */
+    domain: [TimeLike, TimeLike];
+    /** Optional axis ticks. Each tick: { date, label }. */
+    axisTicks?: ProcessSankeyTick[];
+    nodeIdAccessor?: ChartAccessor<TNode, string>;
+    sourceAccessor?: ChartAccessor<TEdge, string>;
+    targetAccessor?: ChartAccessor<TEdge, string>;
+    valueAccessor?: ChartAccessor<TEdge, number>;
+    startTimeAccessor?: ChartAccessor<TEdge, TimeLike>;
+    endTimeAccessor?: ChartAccessor<TEdge, TimeLike>;
+    /**
+     * Optional accessor for the per-edge "system in" time — when
+     * `value` is added to the SOURCE node's mass. Use when the
+     * source node has an intake event distinct from when this edge
+     * departs (e.g. a patient is admitted to the ER at 7pm and
+     * transferred out at 9pm — the ER node carries the patient's
+     * weight between 7pm and 9pm). Without this, the source node's
+     * mass is synthesized as a flat baseline and the band reads as
+     * "always there." Set it and the node band climbs / falls as
+     * units arrive and depart — a true staircase profile.
+     */
+    systemInTimeAccessor?: ChartAccessor<TEdge, TimeLike>;
+    /**
+     * Optional accessor for the per-edge "system out" time — when
+     * `value` is removed from the TARGET node's mass. Mirror of
+     * `systemInTimeAccessor` for the inbound side.
+     */
+    systemOutTimeAccessor?: ChartAccessor<TEdge, TimeLike>;
+    /**
+     * Accessor for a node's explicit lifetime extent — a `[start, end]`
+     * tuple of time-likes. Lane spans
+     * `min(xExtent[0], earliestEdge)` to `max(xExtent[1], latestEdge)`.
+     */
+    xExtentAccessor?: ChartAccessor<TNode, [TimeLike, TimeLike]>;
+    edgeIdAccessor?: ChartAccessor<TEdge, string>;
+    colorBy?: ChartAccessor<TNode, string>;
+    colorScheme?: string | string[];
+    /** Show a swatch + label legend. Defaults to `true` when `colorBy` is set. */
+    showLegend?: boolean;
+    /** Legend position. Default `"right"`. */
+    legendPosition?: "right" | "left" | "top" | "bottom";
+    /**
+     * Format function for time values — applied to axis tick labels and
+     * to time fields in the default tooltip. Same convention as
+     * `xFormat` on XY charts.
+     */
+    timeFormat?: (d: number | Date) => string | React.ReactNode;
+    /** Format function for the `value` field. Mirrors `yFormat` on XY charts. */
+    valueFormat?: (d: number) => string | React.ReactNode;
+    pairing?: "value" | "temporal";
+    packing?: "off" | "reuse";
+    laneOrder?: "insertion" | "crossing-min" | "inside-out" | "crossing-min+inside-out";
+    ribbonLane?: "source" | "target" | "both";
+    lifetimeMode?: "full" | "half";
+    showLaneRails?: boolean;
+    showQualityReadout?: boolean;
+    /** Render the per-band node id label at the band's left edge.
+     *  Default `true`. Set `false` for dense layouts where labels
+     *  would overlap, or when the legend already names every band. */
+    showLabels?: boolean;
+    edgeOpacity?: number;
+    /** Tooltip content. `false` disables, `true` uses the default,
+     *  or pass a `Tooltip(...)` / custom function for full control. */
+    tooltip?: TooltipProp;
+    enableHover?: boolean;
+    onClick?: (datum: Datum, position?: {
+        x: number;
+        y: number;
+    }) => void;
+    showParticles?: boolean;
+    /** Style config for the particle overlay — same shape
+     *  StreamNetworkFrame consumes from SankeyDiagram. Defaults
+     *  (radius 3, opacity 0.7, spawnRate 0.1, maxPerEdge 50) live in
+     *  `DEFAULT_PARTICLE_STYLE`. */
+    particleStyle?: ParticleStyle;
+    /** Pass-through to the underlying StreamNetworkFrame. */
+    frameProps?: Partial<Omit<StreamNetworkFrameProps, "nodes" | "edges" | "chartType" | "size" | "customNetworkLayout" | "layoutConfig">>;
+}
+/**
+ * ProcessSankey — temporal flow between nodes with an actual time x-axis.
+ *
+ * Built on top of `StreamNetworkFrame` via the `customNetworkLayout`
+ * escape hatch. Bands and ribbons emit as `bezier` scene-edges; the
+ * Frame handles canvas painting, hit testing, accessibility, theme
+ * cascade, and the push API.
+ *
+ * **Differs from SankeyDiagram in three ways:**
+ *
+ * 1. **Edges carry time.** Each edge has `startTime` / `endTime`.
+ * 2. **Nodes have lifetimes, not ranks.** A node's vertical lane spans
+ *    `min(xExtent[0], earliestEdge)` to `max(xExtent[1], latestEdge)`.
+ * 3. **Static-graph cycles are valid** as long as edges move forward in time.
+ *
+ * @example
+ * ```tsx
+ * // Static fixture: pre-built nodes + timed edges, categorical colors.
+ * <ProcessSankey
+ *   nodes={[
+ *     { id: "Alice", category: "Person", xExtent: ["2026-01-06", "2026-01-06"] },
+ *     { id: "Bob",   category: "Person", xExtent: ["2026-02-01", "2026-02-01"] },
+ *     { id: "Eng",     category: "Team" },
+ *     { id: "Release", category: "Milestone", xExtent: ["2026-04-15", "2026-05-30"] },
+ *   ]}
+ *   edges={[
+ *     { id: "alice-eng", source: "Alice", target: "Eng",     value: 8,
+ *       startTime: "2026-01-20", endTime: "2026-02-10" },
+ *     { id: "bob-eng",   source: "Bob",   target: "Eng",     value: 5,
+ *       startTime: "2026-02-15", endTime: "2026-03-15" },
+ *     { id: "eng-rel",   source: "Eng",   target: "Release", value: 13,
+ *       startTime: "2026-04-15", endTime: "2026-05-15" },
+ *   ]}
+ *   domain={["2026-01-01", "2026-05-31"]}
+ *   colorBy="category"
+ *   showLegend
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Push mode: omit `edges`, mutate via the ref. Same chart shape, but
+ * // edges arrive over time. Particles depict throughput.
+ * const ref = useRef<RealtimeFrameHandle>(null)
+ *
+ * useEffect(() => {
+ *   const id = setInterval(() => {
+ *     ref.current?.push({
+ *       source: "API", target: "DB", value: Math.random() * 10,
+ *       startTime: Date.now(), endTime: Date.now() + 1500,
+ *     })
+ *   }, 800)
+ *   return () => clearInterval(id)
+ * }, [])
+ *
+ * return (
+ *   <ProcessSankey
+ *     ref={ref}
+ *     domain={[t0, t0 + 60_000]}
+ *     showParticles
+ *     colorBy="category"
+ *     showLegend
+ *   />
+ * )
+ * ```
+ */
+export declare const ProcessSankey: {
+    <TNode extends Datum = Datum, TEdge extends Datum = Datum>(props: ProcessSankeyProps<TNode, TEdge> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};
+export default ProcessSankey;

package/dist/components/charts/network/SankeyDiagram.d.ts

@@ -4,7 +4,7 @@ import type { StreamNetworkFrameProps } from "../../stream/networkTypes";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
-import type { LegendInteractionMode } from "../shared/hooks";
+import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 /**
  * SankeyDiagram component props
  */
@@ -25,6 +25,10 @@ export interface SankeyDiagramProps<TNode extends Datum = Datum, TEdge extends D
     nodeLabel?: ChartAccessor<TNode, string>;
     showLabels?: boolean;
     enableHover?: boolean;
+    /** Show a swatch + label legend. Defaults to `true` when `colorBy` is set. */
+    showLegend?: boolean;
+    /** Legend position. Default `"right"`. */
+    legendPosition?: LegendPosition;
     legendInteraction?: LegendInteractionMode;
     edgeOpacity?: number;
     edgeSort?: (a: any, b: any) => number;

package/dist/components/charts/network/processSankey/algorithm.d.ts

@@ -0,0 +1,193 @@
+export interface ProcessSankeyNode {
+    id: string;
+    /** Optional explicit lifetime bound [start, end]. Lifetime is
+     *  `min(xExtent[0], earliestEdge)` to `max(xExtent[1], latestEdge)`. */
+    xExtent?: [number, number];
+}
+export interface ProcessSankeyEdge {
+    id: string;
+    source: string;
+    target: string;
+    value: number;
+    startTime: number;
+    endTime: number;
+    /** Optional: time at which this unit of mass actually "arrived" at
+     *  the SOURCE node (e.g., the hospital admit time for an ER patient
+     *  whose transfer to ICU happens later at `startTime`). Purely a
+     *  rendering hint — the layout/mass profile is unchanged. The
+     *  renderer cuts a rectangular slot out of the source node's band
+     *  from the node's left edge up to the scaled `systemInTime`, with
+     *  height equal to this edge's ribbon thickness. Edges without
+     *  `systemInTime` are drawn as-is. Result: a staircase profile on
+     *  the source side as units enter the system one by one.
+     *  Default: undefined. */
+    systemInTime?: number;
+    /** Optional: time at which this unit of mass leaves the TARGET node
+     *  (e.g., the discharge time for a patient who arrived at the ward
+     *  at `endTime`). Symmetric to `systemInTime`: the renderer cuts a
+     *  rectangular slot out of the target node's band from the scaled
+     *  `systemOutTime` to the node's right edge, with height equal to
+     *  this edge's ribbon thickness. Layout/mass profile unchanged.
+     *  Default: undefined. */
+    systemOutTime?: number;
+}
+export interface ProcessSankeyIssue {
+    kind: string;
+    id?: string;
+    source?: string;
+    target?: string;
+    endpoint?: string;
+    nodeId?: string;
+}
+export interface ProcessSankeySample {
+    t: number;
+    topMass: number;
+    botMass: number;
+}
+export type AttachmentSide = "top" | "bot";
+export type AttachmentKind = "in" | "out";
+export interface ProcessSankeyAttachment {
+    side: AttachmentSide;
+    time: number;
+    sideMassBefore: number;
+    sideMassAfter: number;
+    kind: AttachmentKind;
+    value: number;
+}
+export interface ProcessSankeyNodeData {
+    samples: ProcessSankeySample[];
+    peak: number;
+    topPeak: number;
+    botPeak: number;
+    localAttachments: Map<string, ProcessSankeyAttachment>;
+}
+export interface ProcessSankeySlotPeak {
+    topPeak: number;
+    botPeak: number;
+}
+export interface ProcessSankeySlotOccupant {
+    id: string;
+    end: number;
+}
+export interface ProcessSankeySlot {
+    peak: ProcessSankeySlotPeak;
+    occupants: ProcessSankeySlotOccupant[];
+}
+export interface ProcessSankeyLaneLifetime {
+    start: number | null;
+    end: number | null;
+}
+export interface ProcessSankeySideRecord {
+    sourceSide?: AttachmentSide;
+    targetSide?: AttachmentSide;
+}
+export interface ProcessSankeyLayout {
+    nodeData: Record<string, ProcessSankeyNodeData>;
+    sides: Map<string, ProcessSankeySideRecord>;
+    valueScale: number;
+    padding: number;
+    compressedPadding: boolean;
+    centerlines: Record<string, number>;
+    laneLifetime: Record<string, ProcessSankeyLaneLifetime>;
+    slots: ProcessSankeySlot[];
+    slotByNode: Record<string, number>;
+    crossingsBefore: number | null;
+    crossingsAfter: number | null;
+    lengthBefore: number | null;
+    lengthAfter: number | null;
+}
+export interface ProcessSankeyOptions {
+    plotH: number;
+    pairing?: "value" | "temporal";
+    packing?: "off" | "reuse";
+    laneOrder?: "insertion" | "crossing-min" | "inside-out" | "crossing-min+inside-out";
+    lifetimeMode?: "full" | "half";
+}
+export interface ProcessSankeyEdgeIndex {
+    incoming: Record<string, ProcessSankeyEdge[]>;
+    outgoing: Record<string, ProcessSankeyEdge[]>;
+}
+type Domain = [number, number] | null | undefined;
+export declare function validateProcessSankey(nodes: ProcessSankeyNode[], edges: ProcessSankeyEdge[], domain: [number, number]): ProcessSankeyIssue[];
+export declare function formatProcessSankeyIssue(issue: ProcessSankeyIssue): string;
+export declare function buildEdgeIndex(nodes: ProcessSankeyNode[], edges: ProcessSankeyEdge[]): ProcessSankeyEdgeIndex;
+export declare function assignSides(nodes: ProcessSankeyNode[], edges: ProcessSankeyEdge[], edgeIndex: ProcessSankeyEdgeIndex, pairing?: "value" | "temporal"): Map<string, ProcessSankeySideRecord>;
+export declare function computeNode(node: ProcessSankeyNode, edgeIndex: ProcessSankeyEdgeIndex, sides: Map<string, ProcessSankeySideRecord>): ProcessSankeyNodeData;
+export declare function clampTime(t: number, domain: Domain): number;
+export declare function clampSamples(samples: ProcessSankeySample[], domain: Domain): ProcessSankeySample[];
+export declare function attachmentYRange(att: ProcessSankeyAttachment, cl: number, S: number): [number, number];
+export declare function buildBandPath(samples: ProcessSankeySample[], cl: number, S: number, xScale: (t: number) => number, domain: Domain): string | null;
+/**
+ * One 20-px gradient stub at an attachment with `systemInTime` /
+ * `systemOutTime`. Rendered as its own bezier scene-edge with a
+ * horizontal gradient, painted underneath the band. The band
+ * paints with `fill: none` whenever any stubs are present, so the
+ * stub gradients are the only colored regions inside the band's
+ * outline.
+ */
+export interface BandGradientStub {
+    /** Rect path (M-L-L-L-Z). */
+    pathD: string;
+    /** Gradient extent in screen pixels. */
+    x0: number;
+    x1: number;
+    /** Color stops — 0 = transparent end, 1 = band-color end. */
+    from: 0 | 1;
+    to: 0 | 1;
+}
+/**
+ * Build the per-edge 20-px gradient stubs that visualize
+ * `systemInTime` / `systemOutTime` on a node band. Each stub is
+ * a rect on the edge's attachment slot, painted with a horizontal
+ * gradient that fades the band color in (or out) over 20 screen
+ * pixels and saturates through the rest of the rect.
+ *
+ * The rect is clipped to the band's outline bounds (so cutouts don't
+ * spill outside the node shape), but the gradient extent stays at
+ * its natural `[xSysIn - FADE_PX, xSysIn]` / `[xSysOut, xSysOut + FADE_PX]`
+ * range. The canvas renderer uses pad-mode clamping for color stops
+ * outside the rect, so a stub whose fade region falls past the band's
+ * edge still paints solid band-color where it's visible — instead of
+ * collapsing to a degenerate gradient that the renderer would clamp
+ * to transparent.
+ *
+ * Pure rendering hint — layout/mass-profile unchanged. Returns an
+ * empty array when the node has no qualifying edges.
+ */
+export declare function buildBandCutoutsForNode(nodeId: string, edges: ProcessSankeyEdge[], layout: ProcessSankeyLayout, xScale: (t: number) => number, domain: Domain): BandGradientStub[];
+type SlotByNode = Record<string, number>;
+export declare function countCrossings(slotByNode: SlotByNode, edges: ProcessSankeyEdge[]): number;
+export declare function totalEdgeLength(slotByNode: SlotByNode, edges: ProcessSankeyEdge[]): number;
+interface LaneLayoutOptions {
+    plotH: number;
+    padding: number;
+    valueScale: number;
+    packing?: "off" | "reuse";
+    laneOrder?: "insertion" | "crossing-min" | "inside-out" | "crossing-min+inside-out";
+    lifetimeMode?: "full" | "half";
+}
+interface LaneLayoutResult {
+    effectiveSlotsHeight: number;
+    centerlines: Record<string, number>;
+    laneLifetime: Record<string, ProcessSankeyLaneLifetime>;
+    slots: ProcessSankeySlot[];
+    slotByNode: SlotByNode;
+    slotCenter: number[];
+    crossingsBefore: number | null;
+    crossingsAfter: number | null;
+    lengthBefore: number | null;
+    lengthAfter: number | null;
+}
+export declare function computeLaneLayout(nodes: ProcessSankeyNode[], edges: ProcessSankeyEdge[], nodeData: Record<string, ProcessSankeyNodeData>, edgeIndex: ProcessSankeyEdgeIndex, opts: LaneLayoutOptions): LaneLayoutResult;
+/**
+ * Compute the full Process Sankey layout for a given dataset and
+ * configuration. Pure function, no side effects.
+ *
+ * The chart's time domain isn't a layout opt — domain handling lives
+ * in the geometry helpers (`buildBandPath`, `buildRibbonGeometry`,
+ * `clampSamples`) which receive an `xScale` and a domain pair from
+ * the caller. The layout itself is timeless apart from the per-node
+ * sample/event timestamps.
+ */
+export declare function computeProcessSankeyLayout(nodes: ProcessSankeyNode[], edges: ProcessSankeyEdge[], opts: ProcessSankeyOptions): ProcessSankeyLayout;
+export {};

package/dist/components/charts/network/processSankey/buildScenes.d.ts

@@ -0,0 +1,51 @@
+import { scaleTime } from "d3-scale";
+import { type ProcessSankeyOptions, type ProcessSankeyLayout, type ProcessSankeyIssue } from "./algorithm";
+import type { ProcessSankeyLayoutConfig } from "./streamingLayout";
+import type { Datum } from "../../shared/datumTypes";
+export interface ProcessSankeyNormalizedNode {
+    id: string;
+    xExtent?: [number, number];
+    __raw?: Datum;
+}
+export interface ProcessSankeyNormalizedEdge {
+    id: string;
+    source: string;
+    target: string;
+    value: number;
+    startTime: number;
+    endTime: number;
+    /** Optional render-only hint: when this unit of mass actually
+     *  entered the source node. Triggers a cutout in the source band. */
+    systemInTime?: number;
+    /** Optional render-only hint: when this unit of mass left the
+     *  target node. Triggers a cutout in the target band. */
+    systemOutTime?: number;
+    __raw?: Datum;
+}
+export interface BuildScenesInput {
+    nodes: ProcessSankeyNormalizedNode[];
+    edges: ProcessSankeyNormalizedEdge[];
+    domain: [number, number];
+    plotW: number;
+    plotH: number;
+    ribbonLane: "source" | "target" | "both";
+    edgeOpacity: number;
+    /** Resolves a node's color by id+index (lets the caller plug in
+     *  the same theme/colorScheme/colorBy resolution the HOC uses). */
+    colorOf: (id: string, idx: number) => string;
+    layoutOpts: Pick<ProcessSankeyOptions, "pairing" | "packing" | "laneOrder" | "lifetimeMode">;
+}
+export interface BuildScenesResult {
+    layout: ProcessSankeyLayout | null;
+    layoutConfig: ProcessSankeyLayoutConfig;
+    issues: ProcessSankeyIssue[];
+    /** Used downstream for tooltips (mass-history) and overlays. */
+    xScale: ReturnType<typeof scaleTime>;
+}
+/**
+ * Run the full ProcessSankey layout pipeline. Returns the algorithm
+ * output, the bands/ribbons specs ready for `customNetworkLayout`, and
+ * the validation issues (caller decides whether to render an error
+ * gate or fall through). Pure: no DOM, no React, no rAF.
+ */
+export declare function buildProcessSankeyScenes(input: BuildScenesInput): BuildScenesResult;

package/dist/components/charts/network/processSankey/ribbonInputs.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Compute the `RibbonGeometryInput` shape for a ProcessSankey ribbon
+ * from its source/target attachment data. Both the HOC (CSR) and the
+ * pure scene builder (SSR) call this so the coords feeding into the
+ * shared `buildRibbonGeometry` helper match between the two paths.
+ *
+ * Replaces `algorithm.js`'s `buildRibbonPath` — the path-D formula
+ * itself moved into `buildRibbonGeometry` so SankeyDiagram and
+ * ProcessSankey emit identical M-C-L-C-Z shapes.
+ */
+import type { RibbonGeometryInput } from "../../../geometry/ribbonGeometry";
+type Side = "top" | "bot";
+type Kind = "in" | "out";
+interface AttachmentLike {
+    side: Side;
+    time: number;
+    sideMassBefore: number;
+    sideMassAfter: number;
+    kind: Kind;
+    value: number;
+}
+type RibbonLane = "source" | "target" | "both";
+type XScale = (t: number) => number;
+/**
+ * Build the geometry inputs for a single ProcessSankey ribbon. The
+ * source attachment is assumed to be `kind: "out"` (the value leaves
+ * the source on its outgoing side); the target attachment is
+ * `kind: "in"`. attachmentYRange's formula is inlined here to keep
+ * this module pure TS (the `algorithm.js` version is JS-only).
+ */
+export declare function computeProcessSankeyRibbonInputs(srcAtt: AttachmentLike, srcCenterline: number, tgtAtt: AttachmentLike, tgtCenterline: number, valueScale: number, xScale: XScale, lane: RibbonLane, domain: [number, number] | null): RibbonGeometryInput;
+export {};