semiotic 3.7.5 → 3.8.0

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

@@ -15,7 +15,7 @@ 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;

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

@@ -15,7 +15,7 @@ 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);

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,47 @@
+import * as React from "react";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+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>;
+    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,53 @@
+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 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>;
+    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,66 @@
+import * as React from "react";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+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>;
+    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;

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

@@ -0,0 +1,73 @@
+import * as React from "react";
+import type { PhysicsFrameHandle } from "./physicsHocHandle";
+import type { Datum } from "../shared/datumTypes";
+import type { GauntletChartProps } from "./gauntletChartProps";
+export { GAUNTLET_WALL, clampGauntletPoint, buildGauntletPhysics } from "./gauntletPhysics";
+export { applyGauntletEffect, planGauntletPropertyWork, replaceGauntletNegative } from "./gauntletEffects";
+export type { GauntletAccessors, GauntletCoreBodyFn, GauntletEffect, GauntletEvent, GauntletEventContext, GauntletEventLogItem, GauntletGate, GauntletLayout, GauntletPopSpec, GauntletProjectPlacement, GauntletProjectPlacementFn, GauntletProjectState, GauntletPropertyDefinition, GauntletPropertyForceContext, GauntletPropertyWorkPlan, GauntletPropertyWorkPlanOptions, GauntletNegativeReplacementOptions, GauntletViabilityFn } from "./gauntletPhysics";
+export type { GauntletChartProps };
+/**
+ * Physics-backed gauntlet: project core + property satellites through timed or
+ * capacity-gated process events.
+ *
+ * @example
+ * ```tsx
+ * <GauntletChart
+ *   data={[{ id: "plan-a", positives: ["homes"], negatives: ["cost"] }]}
+ *   positiveProperties={[{ id: "homes", label: "Homes", radius: 10 }]}
+ *   negativeProperties={[{ id: "cost", label: "Cost", load: 1.2, radius: 8 }]}
+ *   size={[720, 380]}
+ * />
+ * ```
+ *
+ * @example
+ * Multiple attached properties routed through timed gates, with the
+ * settled viability/outcome projection strip enabled:
+ * ```tsx
+ * <GauntletChart
+ *   data={[{ id: "plan-a", positives: ["homes", "jobs"], negatives: ["cost"] }]}
+ *   positiveProperties={[
+ *     { id: "homes", label: "Homes", radius: 10 },
+ *     { id: "jobs", label: "Jobs", radius: 10 },
+ *   ]}
+ *   negativeProperties={[{ id: "cost", label: "Cost", load: 1.2, radius: 8 }]}
+ *   gates={[
+ *     { id: "review", label: "Review" },
+ *     { id: "budget", label: "Budget" },
+ *   ]}
+ *   showProjection
+ *   size={[720, 380]}
+ * />
+ * ```
+ *
+ * @example
+ * Stagger negative-only compound entities on project-local clocks and share a
+ * finite service across their root bodies:
+ * ```tsx
+ * <GauntletChart
+ *   data={pullRequests}
+ *   startTimeAccessor="arrival"
+ *   negativeAccessor="risks"
+ *   negativeProperties={riskProperties}
+ *   gates={[{
+ *     id: "review",
+ *     capacity: { unitsPerSecond: 5, unitAccessor: "reviewWork" }
+ *   }]}
+ *   events={reviewEvents}
+ *   onCapacityChange={setCapacity}
+ * />
+ * ```
+ */
+export declare const GauntletChart: {
+    <TDatum extends Datum = Datum>(props: GauntletChartProps<TDatum> & React.RefAttributes<PhysicsFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};
+/**
+ * @deprecated Typo alias of {@link GauntletChart}. Use `GauntletChart` instead.
+ * Removed in the next major version.
+ */
+export declare const GuantletChart: {
+    <TDatum extends Datum = Datum>(props: GauntletChartProps<TDatum> & React.RefAttributes<PhysicsFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};
+export default GauntletChart;

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

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

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

@@ -0,0 +1,63 @@
+import * as React from "react";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type PhysicalFlowCoordinateMode, type PhysicalFlowPathConstraint, type PhysicalFlowRawPath } from "./physicsChartUtils";
+import { type PhysicsFrameHandle } from "./physicsHocHandle";
+import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type TooltipProp } from "./physicsHocUtils";
+export interface PhysicalFlowChartProps<TNode extends Datum = Datum, TLink extends Datum = Datum> extends Omit<BaseChartProps, "margin">, PhysicsSharedChartProps {
+    nodes?: TNode[];
+    links?: TLink[];
+    edges?: TLink[];
+    data?: TLink[];
+    size?: [number, number];
+    nodeIdAccessor?: ChartAccessor<TNode, string>;
+    nodeXAccessor?: ChartAccessor<TNode, number>;
+    nodeYAccessor?: ChartAccessor<TNode, number>;
+    sourceAccessor?: ChartAccessor<TLink, string>;
+    targetAccessor?: ChartAccessor<TLink, string>;
+    throughputAccessor?: ChartAccessor<TLink, number>;
+    pathAccessor?: ChartAccessor<TLink, PhysicalFlowRawPath | undefined>;
+    coordinateMode?: PhysicalFlowCoordinateMode;
+    particleRate?: number;
+    maxParticles?: number;
+    particleRadius?: number;
+    flowSpeed?: number;
+    pathConstraint?: PhysicalFlowPathConstraint;
+    reducedMotion?: boolean;
+    showStaticFlow?: boolean;
+    showNodeLabels?: boolean;
+    showSensors?: boolean;
+    colorBy?: ChartAccessor<TLink, string>;
+    seed?: number;
+    tooltip?: TooltipProp;
+    paused?: boolean;
+    frameProps?: PhysicsHocFrameProps<"config">;
+}
+/**
+ * Physics-backed flow chart that sends packet bodies along authored routes while retaining a static throughput layer.
+ *
+ * @example
+ * ```tsx
+ * <PhysicalFlowChart
+ *   nodes={[{ id: "in", x: 0.1, y: 0.5 }, { id: "out", x: 0.9, y: 0.5 }]}
+ *   links={[{ source: "in", target: "out", value: 40 }]}
+ *   coordinateMode="normalized"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <PhysicalFlowChart
+ *   nodes={ports}
+ *   edges={routes}
+ *   pathAccessor="path"
+ *   maxParticles={120}
+ *   showSensors
+ * />
+ * ```
+ */
+export declare const PhysicalFlowChart: {
+    <TNode extends Datum = Datum, TLink extends Datum = Datum>(props: PhysicalFlowChartProps<TNode, TLink> & React.RefAttributes<PhysicsFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};
+export default PhysicalFlowChart;

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

@@ -0,0 +1,120 @@
+import * as React from "react";
+import type { ReactNode } from "react";
+import { type ScaleLinear } from "d3-scale";
+import type { ThemeSemanticColors } from "../../stream/types";
+import { type PhysicsSemanticItem, type StreamPhysicsBodyForce, type StreamPhysicsFrameProps, type StreamPhysicsRegionEffect } from "../../stream/physics/StreamPhysicsFrame";
+import type { PhysicsController } from "../../stream/physics/PhysicsControllers";
+import { PhysicsPipelineStore, type PhysicsPipelineConfig, type PhysicsQueuedSpawn, type PhysicsSpawnPacingOptions } from "../../stream/physics/PhysicsPipelineStore";
+import type { PhysicsColliderSpec, PhysicsSpringSpec } from "../../stream/physics/PhysicsKernel";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type PhysicsChartArea } from "./physicsChartUtils";
+import { type PhysicsDatumSpawnResult, type PhysicsFrameHandle } from "./physicsHocHandle";
+import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type TooltipProp } from "./physicsHocUtils";
+export interface PhysicsCustomLayoutContext<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> {
+    data: TDatum[];
+    scales: {
+        x: ScaleLinear<number, number>;
+        y: ScaleLinear<number, number>;
+    };
+    dimensions: PhysicsChartArea;
+    theme: {
+        semantic: ThemeSemanticColors;
+        categorical: string[];
+    };
+    resolveColor: (key: string, datum?: TDatum) => string;
+    config: TConfig;
+    /**
+     * Scratch pipeline store initialized from the base frame config. Use it for
+     * derived geometry, seeded randomness, or quick settle probes; return
+     * declarative `bodies`/`colliders` from the layout result for rendering.
+     */
+    world: PhysicsPipelineStore;
+}
+export interface PhysicsCustomLayoutResult {
+    bodies?: PhysicsQueuedSpawn[];
+    initialSpawns?: PhysicsQueuedSpawn[];
+    /** Fresh collider geometry replaces the live world without resetting bodies. */
+    colliders?: PhysicsColliderSpec[];
+    /** Fresh sensor geometry replaces the live world without resetting bodies. */
+    sensors?: PhysicsColliderSpec[];
+    constraints?: PhysicsSpringSpec[];
+    config?: PhysicsPipelineConfig;
+    initialSpawnPacing?: PhysicsSpawnPacingOptions;
+    /**
+     * Region effects (membranes, capacity stages, portals). Prefer declaring
+     * these here and driving interaction via `controllers` / `layoutConfig`
+     * rather than re-spawning bodies.
+     */
+    regionEffects?: StreamPhysicsRegionEffect[];
+    /**
+     * Process plugins (capacity queues, portals). Tick with the frame heartbeat
+     * without rebuilding world topology when only `layoutConfig` changes.
+     */
+    controllers?: PhysicsController[];
+    bodyForces?: StreamPhysicsBodyForce;
+    overlays?: ReactNode;
+    backgroundOverlays?: ReactNode;
+    bodyStyle?: StreamPhysicsFrameProps["bodyStyle"];
+    selectedBodyStyle?: StreamPhysicsFrameProps["selectedBodyStyle"];
+    semanticItems?: PhysicsSemanticItem[];
+}
+export type PhysicsCustomLayout<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> = (ctx: PhysicsCustomLayoutContext<TDatum, TConfig>) => PhysicsCustomLayoutResult;
+export type PhysicsCustomSpawnDatumResult = PhysicsDatumSpawnResult | PhysicsQueuedSpawn | PhysicsQueuedSpawn[];
+export interface PhysicsCustomChartProps<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> extends Omit<BaseChartProps, "margin">, PhysicsSharedChartProps {
+    data?: TDatum[];
+    layout: PhysicsCustomLayout<TDatum, TConfig>;
+    /**
+     * Interaction / style config passed as `ctx.config`. Changing only
+     * `layoutConfig` re-runs the layout for colliders, sensors, regionEffects,
+     * controllers, overlays, and bodyStyle — it does **not** re-create the
+     * physics store or re-enqueue initial spawns (topology is keyed by data +
+     * size + layout identity). Keep collider/sensor ids stable across updates.
+     */
+    layoutConfig?: TConfig;
+    config?: PhysicsPipelineConfig;
+    size?: [number, number];
+    xExtent?: [number, number];
+    yExtent?: [number, number];
+    colorBy?: ChartAccessor<TDatum, string | number>;
+    colorScheme?: string | string[] | Record<string, string>;
+    paused?: boolean;
+    tooltip?: TooltipProp;
+    /**
+     * Extra process controllers composed with any returned from `layout()`.
+     */
+    controllers?: PhysicsController[];
+    spawnDatum?: (datum: TDatum, index: number, ctx: PhysicsCustomLayoutContext<TDatum, TConfig>) => PhysicsCustomSpawnDatumResult;
+    /**
+     * Frame passthrough. Prefer top-level `controllers` / layout-returned
+     * regionEffects; frameProps merges are still supported for escape hatches.
+     */
+    frameProps?: PhysicsHocFrameProps<"config">;
+}
+interface ResolvedPhysicsCustomLayout<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> {
+    config: PhysicsPipelineConfig;
+    context: PhysicsCustomLayoutContext<TDatum, TConfig>;
+    initialSpawnPacing?: PhysicsSpawnPacingOptions;
+    initialSpawns: PhysicsQueuedSpawn[];
+    result: PhysicsCustomLayoutResult;
+}
+export declare function resolveCustomLayout<TDatum extends Datum, TConfig extends object>(options: {
+    chartId?: string;
+    colorScheme?: string | string[] | Record<string, string>;
+    config?: PhysicsPipelineConfig;
+    data: TDatum[];
+    layout: PhysicsCustomLayout<TDatum, TConfig>;
+    layoutConfig?: TConfig;
+    onObservation?: BaseChartProps["onObservation"];
+    semantic: ThemeSemanticColors;
+    skipLayout?: boolean;
+    size: [number, number];
+    themeCategorical: string[];
+    xExtent?: [number, number];
+    yExtent?: [number, number];
+}): ResolvedPhysicsCustomLayout<TDatum, TConfig>;
+export declare const PhysicsCustomChart: {
+    <TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>>(props: PhysicsCustomChartProps<TDatum, TConfig> & React.RefAttributes<PhysicsFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};
+export default PhysicsCustomChart;

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

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

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

@@ -0,0 +1,53 @@
+import * as React from "react";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps, ChartAccessor, ChartMode } from "../shared/types";
+import { type PhysicsFrameHandle } from "./physicsHocHandle";
+import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type PhysicsSimulationMode, type TooltipProp } from "./physicsHocUtils";
+export interface PhysicsPileChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "mode">, PhysicsSharedChartProps {
+    data?: TDatum[];
+    size?: [number, number];
+    categoryAccessor?: ChartAccessor<TDatum, string>;
+    valueAccessor?: ChartAccessor<TDatum, number>;
+    /**
+     * Chart display mode **or** legacy simulation mode (`sample`/`mechanical`).
+     * Prefer `simulationMode` for mechanical demos; use `mode` for ChartMode.
+     */
+    mode?: ChartMode | PhysicsSimulationMode;
+    simulationMode?: PhysicsSimulationMode;
+    mechanicalCount?: number;
+    mechanicalCategories?: readonly string[];
+    unitValue?: number;
+    ballRadius?: number;
+    colorBy?: ChartAccessor<TDatum, string>;
+    seed?: number;
+    showProjection?: boolean;
+    sediment?: boolean;
+    tooltip?: TooltipProp;
+    paused?: boolean;
+    frameProps?: PhysicsHocFrameProps<"config">;
+}
+/**
+ * Physics-backed unit pile chart that converts category values into repeated bodies and a readable settled projection.
+ *
+ * @example
+ * ```tsx
+ * <PhysicsPileChart
+ *   data={[{ category: "A", value: 12 }, { category: "B", value: 8 }]}
+ *   categoryAccessor="category"
+ *   valueAccessor="value"
+ *   unitValue={1}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <PhysicsPileChart
+ *   mode="mechanical"
+ *   mechanicalCategories={["North", "South", "West"]}
+ *   mechanicalCount={90}
+ *   seed={5}
+ * />
+ * ```
+ */
+export declare const PhysicsPileChart: React.ForwardRefExoticComponent<PhysicsPileChartProps<Datum> & React.RefAttributes<PhysicsFrameHandle>>;
+export default PhysicsPileChart;

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

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