semiotic 3.7.5 → 3.8.1

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

@@ -5,6 +5,7 @@ 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 StyleRule } from "../shared/styleRules";
 /**
  * ChordDiagram component props
  */
@@ -16,11 +17,18 @@ export interface ChordDiagramProps<TNode extends Datum = Datum, TEdge extends Da
     valueAccessor?: ChartAccessor<TEdge, number>;
     nodeIdAccessor?: ChartAccessor<TNode, string>;
     colorBy?: ChartAccessor<TNode, string>;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
+    /**
+     * Declarative, threshold-aware node styling (see ForceDirectedGraph).
+     * Ordered `{ when, style }` rules; last applicable rule wins. Rules see the
+     * raw node object. A rule `fill` may be a color or a HatchFill.
+     */
+    styleRules?: StyleRule[];
     edgeColorBy?: "source" | "target" | ((d: Datum) => string);
     padAngle?: number;
     groupWidth?: number;
-    sortGroups?: (a: any, b: any) => number;
+    /** Compare D3 chord group indices to control their angular order. */
+    sortGroups?: (a: number, b: number) => number;
     nodeLabel?: ChartAccessor<TNode, string>;
     showLabels?: boolean;
     enableHover?: boolean;

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

@@ -13,7 +13,7 @@ export interface CirclePackProps<TNode extends Datum = Datum> extends BaseChartP
     valueAccessor?: ChartAccessor<TNode, number>;
     nodeIdAccessor?: ChartAccessor<TNode, string>;
     colorBy?: ChartAccessor<TNode, string | number>;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     colorByDepth?: boolean;
     showLabels?: boolean;
     nodeLabel?: ChartAccessor<TNode, string>;

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

@@ -5,6 +5,7 @@ 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";
+import { type StyleRule } from "../shared/styleRules";
 /**
  * ForceDirectedGraph component props
  */
@@ -67,7 +68,17 @@ export interface ForceDirectedGraphProps<TNode extends Datum = Datum, TEdge exte
      */
     colorBy?: ChartAccessor<TNode, string>;
     /** d3 scheme name or explicit color array; falls back to theme. */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
+    /**
+     * Declarative, threshold-aware node styling. Ordered `{ when, style }`
+     * rules; the last applicable rule wins per property. `when` accepts a
+     * predicate `(node, ctx) => boolean` (rules see the raw node object; `ctx` =
+     * `{ value, category }` where `category` is the `colorBy` group), a
+     * declarative threshold (`{ field, gt, eq, in, … }`), or `true` — so you can
+     * style whole groups of nodes (`{ field: "type", eq: "db" }`). A rule's
+     * `fill` may be a color or a HatchFill. Layers over the resolved node color.
+     */
+    styleRules?: StyleRule[];
     /**
      * Constant pixel radius, or a function/field returning a numeric value
      * scaled into `nodeSizeRange`.
@@ -93,11 +104,21 @@ export interface ForceDirectedGraphProps<TNode extends Datum = Datum, TEdge exte
      */
     iterations?: number;
     /**
-     * Magnitude of the repulsion force between nodes; higher values spread
-     * the graph more.
+     * Link-attraction multiplier. Lower values produce a looser, more
+     * spread-out graph; higher values pull connected nodes together.
      * @default 0.1
      */
     forceStrength?: number;
+    /**
+     * Execute layout synchronously, in a Web Worker, or automatically choose
+     * based on estimated graph cost.
+     * @default "auto"
+     */
+    layoutExecution?: "auto" | "worker" | "sync";
+    /** Content rendered in the chart slot while worker layout is pending. */
+    layoutLoadingContent?: React.ReactNode | false;
+    /** Called when internally-managed worker layout changes state. */
+    onLayoutStateChange?: (state: "pending" | "ready" | "error") => void;
     /**
      * Render labels next to nodes. Uses `nodeLabel` accessor (defaulting to
      * `nodeIdAccessor`).
@@ -113,8 +134,8 @@ export interface ForceDirectedGraphProps<TNode extends Datum = Datum, TEdge exte
 /**
  * ForceDirectedGraph - Visualize network relationships with a force-directed layout.
  *
- * Nodes are positioned by simulating attraction along edges and repulsion
- * between unconnected nodes; the layout settles after `iterations` ticks.
+ * Nodes are positioned by simulating degree-aware attraction and repulsion
+ * with radius-aware collision; the layout settles after `iterations` ticks.
  * Wraps {@link StreamNetworkFrame} (canvas-first rendering for large graphs).
  *
  * For ordered hierarchical data prefer {@link TreeDiagram}; for flow

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

@@ -25,7 +25,7 @@ export interface OrbitDiagramProps<TDatum extends Datum = Datum> extends BaseCha
     /** Field or function for node color */
     colorBy?: string | ((d: Datum) => string);
     /** Color scheme @default "category10" */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Color by hierarchy depth instead of field @default false */
     colorByDepth?: boolean;
     /**

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

@@ -48,7 +48,7 @@ export interface ProcessSankeyProps<TNode extends Datum = Datum, TEdge extends D
     xExtentAccessor?: ChartAccessor<TNode, [TimeLike, TimeLike]>;
     edgeIdAccessor?: ChartAccessor<TEdge, string>;
     colorBy?: ChartAccessor<TNode, string>;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Show a swatch + label legend. Defaults to `true` when `colorBy` is set. */
     showLegend?: boolean;
     /** Legend position. Default `"right"`. */

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

@@ -5,6 +5,7 @@ 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";
+import { type StyleRule } from "../shared/styleRules";
 /**
  * SankeyDiagram component props
  */
@@ -16,7 +17,14 @@ export interface SankeyDiagramProps<TNode extends Datum = Datum, TEdge extends D
     valueAccessor?: ChartAccessor<TEdge, number>;
     nodeIdAccessor?: ChartAccessor<TNode, string>;
     colorBy?: ChartAccessor<TNode, string>;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
+    /**
+     * Declarative, threshold-aware node styling (see ForceDirectedGraph).
+     * Ordered `{ when, style }` rules; last applicable rule wins. Rules see the
+     * raw node object; `ctx` = `{ value, category }`. A rule `fill` may be a
+     * color or a HatchFill. Layers over the resolved node color.
+     */
+    styleRules?: StyleRule[];
     edgeColorBy?: "source" | "target" | "gradient" | ((d: Datum) => string);
     orientation?: "horizontal" | "vertical";
     nodeAlign?: "justify" | "left" | "right" | "center";
@@ -31,7 +39,7 @@ export interface SankeyDiagramProps<TNode extends Datum = Datum, TEdge extends D
     legendPosition?: LegendPosition;
     legendInteraction?: LegendInteractionMode;
     edgeOpacity?: number;
-    edgeSort?: (a: any, b: any) => number;
+    edgeSort?: (a: TEdge, b: TEdge) => number;
     tooltip?: TooltipProp;
     frameProps?: Partial<Omit<StreamNetworkFrameProps, "edges" | "size">>;
 }

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

@@ -15,7 +15,7 @@ export interface TreeDiagramProps<TNode extends Datum = Datum> extends BaseChart
     valueAccessor?: ChartAccessor<TNode, number>;
     nodeIdAccessor?: ChartAccessor<TNode, string>;
     colorBy?: ChartAccessor<TNode, string | number>;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     colorByDepth?: boolean;
     edgeStyle?: "line" | "curve";
     nodeLabel?: ChartAccessor<TNode, string>;

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

@@ -13,7 +13,7 @@ export interface TreemapProps<TNode extends Datum = Datum> extends BaseChartProp
     valueAccessor?: ChartAccessor<TNode, number>;
     nodeIdAccessor?: ChartAccessor<TNode, string>;
     colorBy?: ChartAccessor<TNode, string | number>;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     colorByDepth?: boolean;
     showLabels?: boolean;
     labelMode?: "leaf" | "parent" | "all";

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

@@ -0,0 +1,17 @@
+import { type ForceLayoutAsyncOptions } from "../../recipes/forceLayoutAsync";
+import type { GraphEdge, GraphNode, Point } from "../../recipes/networkAnalysis";
+export type ForceLayoutStatus = "pending" | "ready" | "error";
+export interface UseForceLayoutResult {
+    positions: Record<string, Point> | null;
+    status: ForceLayoutStatus;
+    error: Error | null;
+}
+/**
+ * React lifecycle wrapper for deterministic force layout. Direct SSR and the
+ * first hydration render stay synchronous so markup matches; client-side mounts
+ * and subsequent graph changes use {@link forceLayoutAsync}. Settled positions
+ * are memoized by node/edge array identity + options, so remounting with the
+ * same module-constant graph resolves "ready" immediately instead of
+ * re-flashing a pending state.
+ */
+export declare function useForceLayout(nodes: ReadonlyArray<GraphNode>, edges: ReadonlyArray<GraphEdge>, options?: Omit<ForceLayoutAsyncOptions, "signal">): UseForceLayoutResult;

package/dist/components/charts/ordinal/BarChart.d.ts

@@ -5,6 +5,7 @@ import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
+import { type StyleRule } from "../shared/styleRules";
 import { type RegressionProp } from "../shared/regressionUtils";
 /**
  * BarChart component props
@@ -51,7 +52,7 @@ export interface BarChartProps<TDatum extends Datum = Datum> extends BaseChartPr
      * `"set2"`, etc.) or an explicit array of colors. Falls back to the
      * theme's categorical palette when omitted.
      */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Category ordering. `false` (default) = insertion order. `"asc"` /
      *  `"desc"` sorts by total value. `"auto"` preserves insertion order
      *  while streaming and falls through to value-desc on static data.
@@ -81,6 +82,26 @@ export interface BarChartProps<TDatum extends Datum = Datum> extends BaseChartPr
             color: string;
         }>;
     };
+    /**
+     * Declarative, threshold-aware bar styling. An ordered list of
+     * `{ when, style }` rules; every rule whose condition matches a bar
+     * contributes its style, merged in order so the **last applicable rule
+     * wins** per property. `when` accepts a predicate `(datum, ctx) => boolean`,
+     * a declarative threshold (`{ gt, lte, within, in, … }` — compares the
+     * bar's value unless `field` is set), or `true`/omitted (always applies).
+     * A rule's `fill` may be a color string or a declarative
+     * {@link HatchFill} for diagonal hatching (renders on canvas and SSR).
+     * Rules layer over the resolved base color; `frameProps.pieceStyle` and
+     * top-level `stroke`/`strokeWidth`/`opacity` still override them.
+     * @example
+     * ```tsx
+     * styleRules={[
+     *   { when: { gte: 10 }, style: { fill: "var(--semiotic-warning)" } },
+     *   { when: { gt: 15 }, style: { fill: { type: "hatch", background: "#e0a92a", stroke: "#fff" } } },
+     * ]}
+     * ```
+     */
+    styleRules?: StyleRule[];
     /** When true, adds padding below the 0 baseline. Default false (bars flush with axis). */
     baselinePadding?: boolean;
     enableHover?: boolean;

package/dist/components/charts/ordinal/BoxPlot.d.ts

@@ -14,7 +14,7 @@ export interface BoxPlotProps<TDatum extends Datum = Datum> extends BaseChartPro
     valueLabel?: string;
     valueFormat?: (d: number | string) => string;
     colorBy?: ChartAccessor<TDatum, string>;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     showOutliers?: boolean;
     outlierRadius?: number;
     categoryPadding?: number;

package/dist/components/charts/ordinal/DonutChart.d.ts

@@ -12,7 +12,7 @@ export interface DonutChartProps<TDatum extends Datum = Datum> extends BaseChart
     innerRadius?: number;
     centerContent?: React.ReactNode;
     colorBy?: ChartAccessor<TDatum, string>;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     startAngle?: number;
     /** Rounded corner radius on wedge arcs */
     cornerRadius?: number;

package/dist/components/charts/ordinal/DotPlot.d.ts

@@ -15,7 +15,7 @@ export interface DotPlotProps<TDatum extends Datum = Datum> extends BaseChartPro
     valueLabel?: string;
     valueFormat?: (d: number | string) => string;
     colorBy?: ChartAccessor<TDatum, string>;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Category ordering. Default (`undefined`) resolves to `"auto"`, which
      *  preserves insertion order while streaming and falls through to
      *  value-desc on static data — the recommended choice when using the

package/dist/components/charts/ordinal/FunnelChart.d.ts

@@ -17,7 +17,7 @@ export interface FunnelChartProps<TDatum extends Datum = Datum> extends BaseChar
     /** Accessor for splitting into mirrored categories (e.g., "control" vs "treatment") */
     categoryAccessor?: ChartAccessor<TDatum, string>;
     colorBy?: ChartAccessor<TDatum, string>;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /**
      * Funnel orientation.
      *

package/dist/components/charts/ordinal/GroupedBarChart.d.ts

@@ -4,6 +4,7 @@ import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
 import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import { type StyleRule } from "../shared/styleRules";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 export interface GroupedBarChartProps<TDatum extends Datum = Datum> extends BaseChartProps {
     data?: TDatum[];
@@ -15,12 +16,22 @@ export interface GroupedBarChartProps<TDatum extends Datum = Datum> extends Base
     valueLabel?: string;
     valueFormat?: (d: number | string) => string;
     colorBy?: ChartAccessor<TDatum, string>;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Category sort order. Default: `false` (data insertion order). `"asc"`/`"desc"` sorts by total grouped value. `"auto"` preserves insertion order while streaming and falls through to value-desc on static data. Custom comparators receive category keys. */
     sort?: boolean | "asc" | "desc" | "auto" | ((a: string, b: string) => number);
     barPadding?: number;
     /** Rounded corner radius on bar ends (away from baseline). */
     roundedTop?: number;
+    /**
+     * Declarative, threshold-aware bar styling. Ordered `{ when, style }`
+     * rules; the last applicable rule wins per property. `when` accepts a
+     * predicate `(datum, ctx) => boolean` (where `ctx.category` is the group
+     * series key), a declarative threshold on the bar value
+     * (`{ gt, lte, within, in, … }`), or `true`. A rule's `fill` may be a color
+     * or a {@link HatchFill}. Layers over the resolved series color;
+     * `frameProps.pieceStyle` overrides.
+     */
+    styleRules?: StyleRule[];
     baselinePadding?: boolean;
     enableHover?: boolean;
     showGrid?: boolean;

package/dist/components/charts/ordinal/Histogram.d.ts

@@ -51,7 +51,7 @@ export interface HistogramProps<TDatum extends Datum = Datum> extends BaseChartP
     valueLabel?: string;
     valueFormat?: (d: number | string) => string;
     colorBy?: ChartAccessor<TDatum, string>;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     categoryPadding?: number;
     enableHover?: boolean;
     showGrid?: boolean;

package/dist/components/charts/ordinal/PieChart.d.ts

@@ -41,7 +41,7 @@ export interface PieChartProps<TDatum extends Datum = Datum> extends BaseChartPr
      * `"set2"`, etc.) or an explicit array of colors. Falls back to the
      * theme's categorical palette when omitted.
      */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /**
      * Rotation in **degrees** applied to the first wedge. `0` starts at 12
      * o'clock and proceeds clockwise; `90` starts at 3 o'clock, `180` at 6

package/dist/components/charts/ordinal/RidgelinePlot.d.ts

@@ -17,7 +17,7 @@ export interface RidgelinePlotProps<TDatum extends Datum = Datum> extends BaseCh
     valueLabel?: string;
     valueFormat?: (d: number | string) => string;
     colorBy?: ChartAccessor<TDatum, string>;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     categoryPadding?: number;
     enableHover?: boolean;
     showGrid?: boolean;

package/dist/components/charts/ordinal/StackedBarChart.d.ts

@@ -5,6 +5,7 @@ import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
+import { type StyleRule } from "../shared/styleRules";
 export interface StackedBarChartProps<TDatum extends Datum = Datum> extends BaseChartProps {
     data?: TDatum[];
     categoryAccessor?: ChartAccessor<TDatum, string>;
@@ -15,13 +16,23 @@ export interface StackedBarChartProps<TDatum extends Datum = Datum> extends Base
     valueLabel?: string;
     valueFormat?: (d: number | string) => string;
     colorBy?: ChartAccessor<TDatum, string>;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     normalize?: boolean;
     /** Category sort order. Default: `false` (data insertion order). `"asc"`/`"desc"` sorts by total stacked value. `"auto"` preserves insertion order while streaming and falls through to value-desc on static data. Custom comparators receive category keys. */
     sort?: boolean | "asc" | "desc" | "auto" | ((a: string, b: string) => number);
     barPadding?: number;
     /** Rounded top corner radius. Only the topmost stacked segment gets rounded. */
     roundedTop?: number;
+    /**
+     * Declarative, threshold-aware segment styling. Ordered `{ when, style }`
+     * rules; the last applicable rule wins per property. `when` accepts a
+     * predicate `(datum, ctx) => boolean` (where `ctx.category` is the stack
+     * series key), a declarative threshold on the segment value
+     * (`{ gt, lte, within, in, … }`), or `true`. A rule's `fill` may be a color
+     * or a {@link HatchFill} for hatching a segment (e.g. a "fixed-rate" band).
+     * Layers over the resolved series color; `frameProps.pieceStyle` overrides.
+     */
+    styleRules?: StyleRule[];
     baselinePadding?: boolean;
     enableHover?: boolean;
     showGrid?: boolean;

package/dist/components/charts/ordinal/SwarmPlot.d.ts

@@ -15,7 +15,7 @@ export interface SwarmPlotProps<TDatum extends Datum = Datum> extends BaseChartP
     valueLabel?: string;
     valueFormat?: (d: number | string) => string;
     colorBy?: ChartAccessor<TDatum, string>;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     sizeBy?: ChartAccessor<TDatum, number>;
     sizeRange?: [number, number];
     /** Field name or function → glyph **shape**: each point renders as a d3-shape

package/dist/components/charts/ordinal/SwimlaneChart.d.ts

@@ -25,7 +25,7 @@ export interface SwimlaneChartProps<TDatum extends Datum = Datum> extends BaseCh
     /** Color accessor — defaults to subcategoryAccessor */
     colorBy?: ChartAccessor<TDatum, string>;
     /** Color scheme for subcategories */
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     /** Padding between lanes in pixels */
     barPadding?: number;
     /** Enable hover annotations */

package/dist/components/charts/ordinal/ViolinPlot.d.ts

@@ -17,7 +17,7 @@ export interface ViolinPlotProps<TDatum extends Datum = Datum> extends BaseChart
     valueLabel?: string;
     valueFormat?: (d: number | string) => string;
     colorBy?: ChartAccessor<TDatum, string>;
-    colorScheme?: string | string[];
+    colorScheme?: string | string[] | Record<string, string>;
     categoryPadding?: number;
     enableHover?: boolean;
     showGrid?: boolean;

package/dist/components/charts/physics/ChainReactionChart.d.ts

@@ -0,0 +1,9 @@
+import * as React from "react";
+import type { Datum } from "../shared/datumTypes";
+import type { ChainReactionChartHandle, ChainReactionChartProps } from "./chainReactionTypes";
+export type * from "./chainReactionTypes";
+export declare const ChainReactionChart: {
+    <TDatum extends Datum = Datum>(props: ChainReactionChartProps<TDatum> & React.RefAttributes<ChainReactionChartHandle>): React.ReactElement | null;
+    displayName?: string;
+};
+export default ChainReactionChart;

package/dist/components/charts/physics/CollisionSwarmChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const CollisionSwarmChartCapability: ChartCapability;

package/dist/components/charts/physics/CollisionSwarmChart.d.ts

@@ -0,0 +1,54 @@
+import * as React from "react";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import type { StyleRule } from "../shared/styleRules";
+import { type PhysicsFrameHandle } from "./physicsHocHandle";
+import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type TooltipProp } from "./physicsHocUtils";
+export interface CollisionSwarmChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin">, PhysicsSharedChartProps {
+    data?: TDatum[];
+    size?: [number, number];
+    xAccessor?: ChartAccessor<TDatum, number>;
+    groupAccessor?: ChartAccessor<TDatum, string>;
+    radiusAccessor?: ChartAccessor<TDatum, number>;
+    pointRadius?: number;
+    colorBy?: ChartAccessor<TDatum, string>;
+    /**
+     * Declarative, threshold-aware dot styling. Ordered `{ when, style }` rules;
+     * last applicable rule wins. `ctx` = `{ value, category }` (value = the
+     * `xAccessor` position). A rule `fill` may be a color or a HatchFill.
+     */
+    styleRules?: StyleRule[];
+    seed?: number;
+    xExtent?: [number, number];
+    collisionIterations?: number;
+    settle?: boolean;
+    showProjection?: boolean;
+    tooltip?: TooltipProp;
+    paused?: boolean;
+    frameProps?: PhysicsHocFrameProps<"config">;
+}
+/**
+ * Physics-backed collision swarm chart that preserves a quantitative x position while separating overlapping bodies.
+ *
+ * @example
+ * ```tsx
+ * <CollisionSwarmChart
+ *   data={[{ id: "a", x: 12, group: "East" }, { id: "b", x: 14, group: "East" }]}
+ *   xAccessor="x"
+ *   groupAccessor="group"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <CollisionSwarmChart
+ *   data={samples}
+ *   xAccessor={(d) => d.score}
+ *   radiusAccessor="weight"
+ *   collisionIterations={180}
+ *   settle
+ * />
+ * ```
+ */
+export declare const CollisionSwarmChart: React.ForwardRefExoticComponent<CollisionSwarmChartProps<Datum> & React.RefAttributes<PhysicsFrameHandle>>;
+export default CollisionSwarmChart;

package/dist/components/charts/physics/EventDropChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const EventDropChartCapability: ChartCapability;

package/dist/components/charts/physics/EventDropChart.d.ts

@@ -0,0 +1,60 @@
+import * as React from "react";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type EventDropWindowOptions } from "./physicsChartUtils";
+import type { StyleRule } from "../shared/styleRules";
+import { type PhysicsFrameHandle } from "./physicsHocHandle";
+import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type TooltipProp } from "./physicsHocUtils";
+export interface EventDropChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin">, PhysicsSharedChartProps {
+    data?: TDatum[];
+    size?: [number, number];
+    timeAccessor?: ChartAccessor<TDatum, number>;
+    arrivalAccessor?: ChartAccessor<TDatum, number>;
+    windows?: EventDropWindowOptions;
+    watermark?: {
+        delay?: number;
+        value?: number;
+    } | ((latestEventTime: number) => number);
+    ballRadius?: number;
+    colorBy?: ChartAccessor<TDatum, string>;
+    /**
+     * Declarative, threshold-aware drop styling. Ordered `{ when, style }`
+     * rules; last applicable rule wins. `ctx` = `{ value, category }` (value =
+     * the event time). A rule `fill` may be a color or a HatchFill.
+     */
+    styleRules?: StyleRule[];
+    seed?: number;
+    timeExtent?: [number, number];
+    timeScale?: number;
+    showProjection?: boolean;
+    tooltip?: TooltipProp;
+    paused?: boolean;
+    frameProps?: PhysicsHocFrameProps<"config">;
+}
+/**
+ * Physics-backed event drop chart for replaying arrivals against event-time windows and watermarks.
+ *
+ * @example
+ * ```tsx
+ * <EventDropChart
+ *   data={[{ id: "a", time: 4, arrivalTime: 8 }, { id: "b", time: 18, arrivalTime: 12 }]}
+ *   timeAccessor="time"
+ *   arrivalAccessor="arrivalTime"
+ *   windows={{ size: 10 }}
+ *   watermark={{ delay: 5 }}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <EventDropChart
+ *   data={events}
+ *   windows={{ size: 60_000 }}
+ *   watermark={{ value: Date.now() - 120_000 }}
+ *   timeScale={4}
+ *   timeExtent={[start, end]}
+ * />
+ * ```
+ */
+export declare const EventDropChart: React.ForwardRefExoticComponent<EventDropChartProps<Datum> & React.RefAttributes<PhysicsFrameHandle>>;
+export default EventDropChart;

package/dist/components/charts/physics/GaltonBoardChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const GaltonBoardChartCapability: ChartCapability;

package/dist/components/charts/physics/GaltonBoardChart.d.ts

@@ -0,0 +1,74 @@
+import * as React from "react";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import type { StyleRule } from "../shared/styleRules";
+import { type PhysicsFrameHandle } from "./physicsHocHandle";
+import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type PhysicsSimulationMode, type TooltipProp } from "./physicsHocUtils";
+import type { ChartMode } from "../shared/types";
+export interface GaltonBoardReferenceLine {
+    value: number;
+    label?: React.ReactNode;
+    color?: string;
+    className?: string;
+    strokeDasharray?: string;
+    strokeWidth?: number;
+    labelPosition?: "top" | "bottom";
+}
+export interface GaltonBoardChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "mode">, PhysicsSharedChartProps {
+    data?: TDatum[];
+    size?: [number, number];
+    valueAccessor?: ChartAccessor<TDatum, number>;
+    valueExtent?: [number, number];
+    bins?: number;
+    /**
+     * Chart display mode (`primary`/`context`/`sparkline`/`mobile`) **or**
+     * legacy simulation mode (`sample`/`mechanical`). Prefer `simulationMode`
+     * for sample vs mechanical; use `mode` for ChartContainer / ChartMode.
+     */
+    mode?: ChartMode | PhysicsSimulationMode;
+    /** Sample data rows vs seeded mechanical demo (no data required). */
+    simulationMode?: PhysicsSimulationMode;
+    pegRows?: number;
+    mechanicalCount?: number;
+    branchProbability?: number;
+    ballRadius?: number;
+    colorBy?: ChartAccessor<TDatum, string>;
+    /**
+     * Declarative, threshold-aware ball styling. Ordered `{ when, style }`
+     * rules; last applicable rule wins. Rules resolve against each ball's datum;
+     * `ctx` = `{ value, category }` (category = the colorBy group). A rule `fill`
+     * may be a color or a HatchFill. Layers over the colorBy-derived fill.
+     */
+    styleRules?: StyleRule[];
+    referenceLines?: GaltonBoardReferenceLine | GaltonBoardReferenceLine[];
+    seed?: number;
+    showProjection?: boolean;
+    tooltip?: TooltipProp;
+    paused?: boolean;
+    frameProps?: PhysicsHocFrameProps<"config">;
+}
+/**
+ * Physics-backed Galton board chart that drops values through seeded pegs into a settled distribution.
+ *
+ * @example
+ * ```tsx
+ * <GaltonBoardChart
+ *   data={[{ id: "a", value: 2 }, { id: "b", value: 7 }]}
+ *   valueAccessor="value"
+ *   bins={12}
+ *   size={[520, 320]}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <GaltonBoardChart
+ *   mode="mechanical"
+ *   mechanicalCount={80}
+ *   branchProbability={0.62}
+ *   seed={11}
+ * />
+ * ```
+ */
+export declare const GaltonBoardChart: React.ForwardRefExoticComponent<GaltonBoardChartProps<Datum> & React.RefAttributes<PhysicsFrameHandle>>;
+export default GaltonBoardChart;

package/dist/components/charts/physics/GauntletChart.capability.d.ts

@@ -0,0 +1,2 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+export declare const GauntletChartCapability: ChartCapability;