semiotic 3.7.5 → 3.8.0

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

@@ -0,0 +1,96 @@
+import * as React from "react";
+import { type PhysicsBodySelection, type StreamPhysicsFrameProps } from "../../stream/physics/StreamPhysicsFrame";
+import { type CapacityQueueSnapshot } from "../../stream/physics/PhysicsControllers";
+import { type ProcessChromeOptions } from "../../recipes/processChrome";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type ProcessFlowProjectionMetadata, type ProcessFlowStageDef } from "./physicsChartUtils";
+import { type PhysicsFrameHandle } from "./physicsHocHandle";
+import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type TooltipProp } from "./physicsHocUtils";
+export type { ProcessFlowStageDef, ProcessFlowProjectionMetadata };
+export interface ProcessFlowChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "selection">, PhysicsSharedChartProps {
+    data?: TDatum[];
+    size?: [number, number];
+    stages: readonly ProcessFlowStageDef[];
+    idAccessor?: ChartAccessor<TDatum, string>;
+    stageAccessor?: ChartAccessor<TDatum, string>;
+    groupBy?: ChartAccessor<TDatum, string>;
+    groupLabelAccessor?: ChartAccessor<TDatum, string>;
+    workAccessor?: ChartAccessor<TDatum, number>;
+    radiusAccessor?: ChartAccessor<TDatum, number>;
+    ballRadius?: number;
+    colorBy?: ChartAccessor<TDatum, string>;
+    seed?: number;
+    route?: "horizontal";
+    groupCompletion?: "allAbsorbed" | "none";
+    groupAnchorAlong?: number;
+    showProjection?: boolean;
+    showChrome?: boolean;
+    /** Options for the default processChrome overlay (stage bays, badges, sockets). */
+    chromeOptions?: ProcessChromeOptions;
+    settle?: boolean;
+    gravityX?: number;
+    gravityY?: number;
+    springStiffness?: number;
+    springDamping?: number;
+    tooltip?: TooltipProp;
+    paused?: boolean;
+    initialSpawnPacing?: StreamPhysicsFrameProps["initialSpawnPacing"];
+    /**
+     * When true (default), stages with `capacity` install live FIFO queue
+     * controllers that drain work at unitsPerSecond — not just force theater.
+     */
+    liveCapacity?: boolean;
+    /** Live capacity metrics callback (queue depth, processed count per region). */
+    onCapacityChange?: (stats: CapacityQueueSnapshot[]) => void;
+    /** Shared selection (process body restyle without relayout). */
+    selection?: PhysicsBodySelection | null;
+    /**
+     * Soft body budget: caps live bodies via pipeline bodyLimit (evict oldest).
+     * Use for infinite/long streams with sediment-style history in the readout.
+     */
+    bodyLimit?: number;
+    /** Mark kind for all bodies, or read per-row from datum.__physicsMark / mark. */
+    bodyMark?: "circle" | "halo" | "faceted" | "pill" | "diamond" | "square";
+    /** Frame passthrough; HOC-owned `config` is merged after the built pipeline config. */
+    frameProps?: PhysicsHocFrameProps;
+}
+/**
+ * Physics-backed multi-body process flow: work items move through capacitated
+ * stages with optional feature groups that complete only when every member is
+ * absorbed (the merge-pressure / review-queue pattern).
+ *
+ * @example
+ * ```tsx
+ * <ProcessFlowChart
+ *   data={prs}
+ *   idAccessor="id"
+ *   stageAccessor="status"
+ *   groupBy="featureId"
+ *   stages={[
+ *     { id: "coding", label: "Coding", force: 14 },
+ *     { id: "review", label: "Review", capacity: { unitsPerSecond: 4 }, pressure: true },
+ *     { id: "merged", label: "Merged", absorb: true },
+ *   ]}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Push-only: omit data, stream work items live through the capacity lane.
+ * const ref = useRef()
+ * <ProcessFlowChart
+ *   ref={ref}
+ *   stages={[
+ *     { id: "triage", label: "Triage", force: 10 },
+ *     { id: "review", label: "Review", capacity: { unitsPerSecond: 3 } },
+ *     { id: "done", label: "Done", absorb: true },
+ *   ]}
+ *   stageAccessor="stage"
+ *   liveCapacity
+ * />
+ * ref.current?.push({ id: "pr-42", stage: "review", work: 2 })
+ * ```
+ */
+export declare const ProcessFlowChart: React.ForwardRefExoticComponent<ProcessFlowChartProps<Datum> & React.RefAttributes<PhysicsFrameHandle>>;
+export default ProcessFlowChart;

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

@@ -0,0 +1,22 @@
+import * as React from "react";
+import type { Datum } from "../shared/datumTypes";
+import type { DependencyMachine, DependencyTrackLayout } from "./dependencyMachine";
+import type { RuntimeState } from "./chainReactionRuntime";
+export interface ChainReactionOverlayProps<TDatum extends Datum = Datum> {
+    machine: DependencyMachine<TDatum>;
+    layout: DependencyTrackLayout;
+    runtime: RuntimeState;
+    downstreamSet: ReadonlySet<string>;
+    selectedSet: ReadonlySet<string>;
+    width: number;
+    height: number;
+    seed: number;
+    reduced: boolean;
+    onSelectTask: (taskID: string) => void;
+}
+/**
+ * SVG chrome painted above the physics canvas: workstream lanes, dependency
+ * tracks + delivery sockets, and the domino task cards (which topple on
+ * completion). Interaction is delegated back through `onSelectTask`.
+ */
+export declare function ChainReactionOverlay<TDatum extends Datum = Datum>({ machine, layout, runtime, downstreamSet, selectedSet, width, height, seed, reduced, onSelectTask }: ChainReactionOverlayProps<TDatum>): React.ReactElement;

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

@@ -0,0 +1,37 @@
+import type { PhysicsBodyState } from "../../stream/physics/PhysicsKernel";
+import type { PhysicsQueuedSpawn } from "../../stream/physics/PhysicsPipelineStore";
+import type { PhysicsSemanticItem, StreamPhysicsBodyForceContext } from "../../stream/physics/StreamPhysicsFrame";
+import type { Datum } from "../shared/datumTypes";
+import type { DependencyMachine, DependencyMachineEdge, DependencyMachineNode, DependencyPoint, DependencyTrackLayout, DependencyTrackRoute } from "./dependencyMachine";
+import type { ChainReactionMode } from "./chainReactionTypes";
+export interface RuntimeState {
+    currentTime: number;
+    playing: boolean;
+    completed: Set<string>;
+    delivered: Set<string>;
+    inFlight: Set<string>;
+    armed: Set<string>;
+    blockers: Map<string, string>;
+    previewTaskID: string | null;
+}
+interface DependencyBallDatum {
+    kind: "dependency-ball";
+    edgeID: string;
+    sourceID: string;
+    targetID: string;
+    route: DependencyPoint[];
+}
+export declare const EMPTY_SPAWNS: PhysicsQueuedSpawn[];
+export declare function numericTime(value: number | Date | undefined, fallback?: number): number;
+export declare function taskCompletionTime<TDatum extends Datum>(node: DependencyMachineNode<TDatum>): number | null;
+export declare function resolvedArmed<TDatum extends Datum>(machine: DependencyMachine<TDatum>, delivered: ReadonlySet<string>, blockers: ReadonlyMap<string, string>, completed: ReadonlySet<string>): Set<string>;
+export declare function initialRuntime<TDatum extends Datum>(machine: DependencyMachine<TDatum>, mode: ChainReactionMode, currentTime: number, reducedMotion: boolean): RuntimeState;
+export declare function copyRuntime(runtime: RuntimeState): RuntimeState;
+export declare function dependencyBallDatum(body: PhysicsBodyState): DependencyBallDatum | null;
+export declare function dependencyBodyForce(context: StreamPhysicsBodyForceContext): {
+    x: number;
+    y: number;
+} | null;
+export declare function ballSpawn(edge: DependencyMachineEdge, route: DependencyTrackRoute): PhysicsQueuedSpawn;
+export declare function machineSemanticItems<TDatum extends Datum>(machine: DependencyMachine<TDatum>, layout: DependencyTrackLayout, runtime: RuntimeState): PhysicsSemanticItem[];
+export {};

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

@@ -0,0 +1,97 @@
+import type { Datum } from "../shared/datumTypes";
+import type { BlockerAmplification, DependencyAccessor, DependencyTaskStatus } from "./dependencyMachine";
+export type ChainReactionMode = "snapshot" | "replay" | "mechanical";
+export type ChainReactionInsight = "none" | "blocker-amplification";
+export type ChainReactionControl = "play" | "pause" | "step" | "reset" | "settle";
+export type ChainReactionObservation<TDatum extends Datum = Datum> = {
+    type: "task-completed";
+    taskID: string;
+    datum: TDatum;
+} | {
+    type: "dependency-delivered";
+    sourceID: string;
+    targetID: string;
+} | {
+    type: "task-armed";
+    taskID: string;
+} | {
+    type: "machine-stalled";
+    blockerID: string;
+    downstreamTaskCount: number;
+    affectedLaneCount: number;
+} | {
+    type: "blocker-previewed";
+    blockerID: string;
+    downstreamTaskIDs: string[];
+} | {
+    type: "machine-settled";
+};
+export interface ChainReactionTaskState {
+    taskID: string;
+    completed: boolean;
+    armed: boolean;
+    blocked: boolean;
+    blockerReason?: string;
+}
+export interface ChainReactionDependencyState {
+    edgeID: string;
+    sourceID: string;
+    targetID: string;
+    state: "waiting" | "in-flight" | "delivered";
+}
+export interface ChainReactionMachineState {
+    currentTime: number;
+    playing: boolean;
+    previewTaskID: string | null;
+    selectedTaskIDs: string[];
+    tasks: ChainReactionTaskState[];
+    dependencies: ChainReactionDependencyState[];
+}
+export interface ChainReactionChartHandle {
+    play: () => void;
+    pause: () => void;
+    step: () => void;
+    reset: () => void;
+    settle: () => void;
+    previewResolve: (taskID: string) => void;
+    clearPreview: () => void;
+    completeTask: (taskID: string) => void;
+    blockTask: (taskID: string, reason: string) => void;
+    unblockTask: (taskID: string) => void;
+    getAmplification: (taskID: string) => BlockerAmplification;
+    getMachineState: () => ChainReactionMachineState;
+}
+export interface ChainReactionChartProps<TDatum extends Datum = Datum> {
+    data: readonly TDatum[];
+    taskIDAccessor: DependencyAccessor<TDatum, string | number>;
+    labelAccessor: DependencyAccessor<TDatum, string>;
+    laneAccessor: DependencyAccessor<TDatum, string>;
+    dependencyAccessor: DependencyAccessor<TDatum, readonly (string | number)[]>;
+    startAccessor?: DependencyAccessor<TDatum, number | Date | undefined>;
+    endAccessor?: DependencyAccessor<TDatum, number | Date | undefined>;
+    progressAccessor?: DependencyAccessor<TDatum, number | undefined>;
+    statusAccessor?: DependencyAccessor<TDatum, DependencyTaskStatus | undefined>;
+    completionTimeAccessor?: DependencyAccessor<TDatum, number | Date | undefined>;
+    blockerAccessor?: DependencyAccessor<TDatum, string | undefined>;
+    milestoneAccessor?: DependencyAccessor<TDatum, boolean | undefined>;
+    mechanism?: "domino-ball";
+    orientation?: "vertical";
+    mode?: ChainReactionMode;
+    insight?: ChainReactionInsight;
+    currentTime?: number | Date;
+    controls?: boolean | readonly ChainReactionControl[];
+    selectedTaskIDs?: readonly string[];
+    onSelectionChange?: (ids: string[]) => void;
+    onObservation?: (event: ChainReactionObservation<TDatum>) => void;
+    reducedMotion?: "settle";
+    seed?: number;
+    width?: number;
+    height?: number;
+    responsiveWidth?: boolean;
+    responsiveHeight?: boolean;
+    title?: string;
+    description?: string;
+    className?: string;
+    accessibleTable?: boolean;
+    enableHover?: boolean;
+}

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

@@ -0,0 +1,27 @@
+import type { Datum } from "../shared/datumTypes";
+import type { ChartAccessor } from "../shared/types";
+import { type PhysicsChartArea, type PhysicsChartLayout } from "./physicsChartShared";
+export interface CollisionSwarmPhysicsOptions<TDatum extends Datum = Datum> {
+    data: readonly TDatum[];
+    xAccessor: ChartAccessor<TDatum, number>;
+    groupAccessor?: ChartAccessor<TDatum, string>;
+    radiusAccessor?: ChartAccessor<TDatum, number>;
+    pointRadius: number;
+    seed: number;
+    size: [number, number];
+    xExtent?: [number, number];
+    collisionIterations?: number;
+    settle?: boolean;
+}
+export interface CollisionSwarmProjectionMetadata {
+    kind: "collision-swarm";
+    xExtent: [number, number];
+    xRange: [number, number];
+    groups: Array<{
+        label: string;
+        y: number;
+        count: number;
+    }>;
+    plot: PhysicsChartArea["plot"];
+}
+export declare function buildCollisionSwarmPhysics<TDatum extends Datum>(options: CollisionSwarmPhysicsOptions<TDatum>): PhysicsChartLayout;

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

@@ -0,0 +1,188 @@
+import type { Datum } from "../shared/datumTypes";
+export type DependencyAccessor<TDatum, TValue> = keyof TDatum | ((datum: TDatum, index: number) => TValue);
+export type DependencyTaskStatus = "done" | "in-progress" | "blocked" | "waiting";
+export interface DependencyMachineAccessors<TDatum extends Datum = Datum> {
+    taskIDAccessor: DependencyAccessor<TDatum, string | number>;
+    labelAccessor: DependencyAccessor<TDatum, string>;
+    laneAccessor: DependencyAccessor<TDatum, string>;
+    dependencyAccessor: DependencyAccessor<TDatum, readonly (string | number)[]>;
+    startAccessor?: DependencyAccessor<TDatum, number | Date | undefined>;
+    endAccessor?: DependencyAccessor<TDatum, number | Date | undefined>;
+    progressAccessor?: DependencyAccessor<TDatum, number | undefined>;
+    statusAccessor?: DependencyAccessor<TDatum, DependencyTaskStatus | undefined>;
+    completionTimeAccessor?: DependencyAccessor<TDatum, number | Date | undefined>;
+    blockerAccessor?: DependencyAccessor<TDatum, string | undefined>;
+    milestoneAccessor?: DependencyAccessor<TDatum, boolean | undefined>;
+}
+export interface CompileDependencyMachineOptions<TDatum extends Datum = Datum> extends DependencyMachineAccessors<TDatum> {
+    data: readonly TDatum[];
+    /** Defaults to first-seen lane order. */
+    laneOrder?: readonly string[];
+}
+export type DependencyMachineDiagnosticCode = "duplicate-task-id" | "missing-dependency" | "cycle";
+export interface DependencyMachineDiagnostic {
+    code: DependencyMachineDiagnosticCode;
+    message: string;
+    taskIDs: string[];
+}
+export interface DependencyMachineNode<TDatum extends Datum = Datum> {
+    id: string;
+    label: string;
+    lane: string;
+    laneIndex: number;
+    level: number;
+    index: number;
+    datum: TDatum;
+    dependencyIDs: string[];
+    incomingEdgeIDs: string[];
+    outgoingEdgeIDs: string[];
+    socketIDs: string[];
+    start?: number | Date;
+    end?: number | Date;
+    progress: number;
+    status: DependencyTaskStatus;
+    completionTime?: number | Date;
+    blockerReason?: string;
+    milestone: boolean;
+}
+export interface DependencyMachineEdge {
+    id: string;
+    sourceID: string;
+    targetID: string;
+    sourceIndex: number;
+    targetIndex: number;
+    socketID: string;
+    socketIndex: number;
+}
+export interface DependencyMachine<TDatum extends Datum = Datum> {
+    nodes: DependencyMachineNode<TDatum>[];
+    edges: DependencyMachineEdge[];
+    byID: Map<string, DependencyMachineNode<TDatum>>;
+    incoming: Map<string, DependencyMachineEdge[]>;
+    outgoing: Map<string, DependencyMachineEdge[]>;
+    lanes: string[];
+    maxLevel: number;
+    diagnostics: DependencyMachineDiagnostic[];
+    valid: boolean;
+}
+export interface DependencyPoint {
+    x: number;
+    y: number;
+}
+export interface DependencyTrackDimensions {
+    width: number;
+    height: number;
+    paddingX?: number;
+    paddingTop?: number;
+    paddingBottom?: number;
+}
+export interface DependencyTrackOptions {
+    taskWidth?: number;
+    taskHeight?: number;
+    gutterCount?: number;
+    socketRadius?: number;
+}
+export interface DependencyTaskPlacement extends DependencyPoint {
+    taskID: string;
+    lane: string;
+    laneIndex: number;
+    level: number;
+    width: number;
+    height: number;
+}
+export interface DependencySocketPlacement extends DependencyPoint {
+    id: string;
+    edgeID: string;
+    taskID: string;
+    index: number;
+    radius: number;
+}
+export interface DependencyTrackRoute {
+    edgeID: string;
+    sourceID: string;
+    targetID: string;
+    socketID: string;
+    points: DependencyPoint[];
+}
+export interface DependencyTrackLayout {
+    tasks: DependencyTaskPlacement[];
+    sockets: DependencySocketPlacement[];
+    routes: DependencyTrackRoute[];
+    taskByID: Map<string, DependencyTaskPlacement>;
+    socketByID: Map<string, DependencySocketPlacement>;
+    routeByEdgeID: Map<string, DependencyTrackRoute>;
+}
+export interface LogicalJoinSnapshot {
+    taskID: string;
+    mode: "all";
+    incomingEdgeIDs: string[];
+    deliveredEdgeIDs: string[];
+    satisfied: boolean;
+}
+export interface LogicalJoin {
+    taskID: string;
+    mode: "all";
+    incomingEdgeIDs: readonly string[];
+    deliver: (edgeID: string) => boolean;
+    reset: (deliveredEdgeIDs?: Iterable<string>) => void;
+    isSatisfied: () => boolean;
+    getSnapshot: () => LogicalJoinSnapshot;
+}
+export type DependencyReplayEvent = {
+    type: "task-completed";
+    taskID: string;
+    at: number | Date;
+} | {
+    type: "task-blocked";
+    taskID: string;
+    reason: string;
+    at: number | Date;
+} | {
+    type: "task-unblocked";
+    taskID: string;
+    at: number | Date;
+} | {
+    type: "dependency-delivered";
+    edgeID: string;
+    at: number | Date;
+} | {
+    type: "task-armed";
+    taskID: string;
+    at: number | Date;
+};
+export type DependencyReplayClock = number | Date | {
+    currentTime: number | Date;
+};
+export interface DependencyReplayState {
+    currentTime: number;
+    appliedEvents: DependencyReplayEvent[];
+    completedTaskIDs: Set<string>;
+    blockedByTaskID: Map<string, string>;
+    deliveredEdgeIDs: Set<string>;
+    armedTaskIDs: Set<string>;
+}
+export interface BlockerAmplification {
+    blockerID: string;
+    downstreamTaskCount: number;
+    affectedLaneCount: number;
+    downstreamTaskIDs: string[];
+    affectedLanes: string[];
+}
+export interface BlockerAmplificationOptions<TDatum extends Datum = Datum> {
+    completedTaskIDs?: Iterable<string>;
+    isComplete?: (node: DependencyMachineNode<TDatum>) => boolean;
+}
+/**
+ * Compile task records into deterministic directed-DAG structure. Invalid
+ * graphs are returned with explicit diagnostics so a chart can render a useful
+ * failure state rather than silently inventing dependency order.
+ */
+export declare function compileDependencyMachine<TDatum extends Datum = Datum>(options: CompileDependencyMachineOptions<TDatum>): DependencyMachine<TDatum>;
+/** Resolve task tiles, receiving sockets, and shared point-based track routes. */
+export declare function routeDependencyTracks<TDatum extends Datum = Datum>(machine: DependencyMachine<TDatum>, dimensions: DependencyTrackDimensions, options?: DependencyTrackOptions): DependencyTrackLayout;
+/** Stateful exact logical join. Physics contacts may call `deliver`; they never define the rule. */
+export declare function createLogicalJoin(taskID: string, incomingEdgeIDs: readonly string[], mode?: "all"): LogicalJoin;
+/** Deterministically fold recorded process events through a supplied clock. */
+export declare function replayStateTransitions(events: readonly DependencyReplayEvent[], clock: DependencyReplayClock): DependencyReplayState;
+/** Directed unfinished-descendant reach, deliberately not a critical-path claim. */
+export declare function calculateBlockerAmplification<TDatum extends Datum = Datum>(machine: DependencyMachine<TDatum>, blockerID: string, options?: BlockerAmplificationOptions<TDatum>): BlockerAmplification;

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

@@ -0,0 +1,64 @@
+import type { Datum } from "../shared/datumTypes";
+import type { ChartAccessor } from "../shared/types";
+import { type PhysicsQueuedSpawn } from "../../stream/physics/PhysicsPipelineStore";
+import { type PhysicsChartArea, type PhysicsChartLayout } from "./physicsChartShared";
+export interface EventDropWindowOptions {
+    size: number;
+    gapPolicy?: "drop" | "keep";
+}
+export interface EventDropPlotRegion {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface EventDropLidSegment {
+    id: string;
+    windowIndex?: number;
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+export interface EventDropProjectionMetadata {
+    kind: "event-drop";
+    closedWindowCount: number;
+    gutter: EventDropPlotRegion;
+    lateCount: number;
+    lidSegments: EventDropLidSegment[];
+    plot: PhysicsChartArea["plot"];
+    windowPlot: EventDropPlotRegion;
+    watermarkValue: number;
+    windowCount: number;
+    windowSize: number;
+    windowStart: number;
+}
+export interface EventDropPhysicsOptions<TDatum extends Datum = Datum> {
+    data: readonly TDatum[];
+    timeAccessor: ChartAccessor<TDatum, number>;
+    arrivalAccessor: ChartAccessor<TDatum, number>;
+    windows: EventDropWindowOptions;
+    watermark?: {
+        delay?: number;
+        value?: number;
+    } | ((latestEventTime: number) => number);
+    ballRadius: number;
+    seed: number;
+    size: [number, number];
+    timeExtent?: [number, number];
+    timeScale?: number;
+}
+export declare function buildEventDropPhysics<TDatum extends Datum>(options: EventDropPhysicsOptions<TDatum>): PhysicsChartLayout;
+/**
+ * Place a single event onto an already-mounted EventDropChart using the live
+ * board's domain (window layout + current watermark) so a pushed arrival drops
+ * over its true event-time x instead of the center of a one-event mini-domain.
+ * Closed-window lids then decide whether physics sends it to the gutter.
+ * Returns null when the datum carries no finite event time. Omits `spawnAt` so
+ * the store drops it now.
+ */
+export declare function placeEventDropSpawn<TDatum extends Datum>(datum: TDatum, index: number, metadata: EventDropProjectionMetadata, options: {
+    timeAccessor: ChartAccessor<TDatum, number>;
+    arrivalAccessor: ChartAccessor<TDatum, number>;
+    ballRadius: number;
+}): PhysicsQueuedSpawn | null;

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

@@ -0,0 +1,28 @@
+import type { Datum } from "../shared/datumTypes";
+import type { ChartAccessor } from "../shared/types";
+import { type PhysicsChartArea, type PhysicsChartLayout } from "./physicsChartShared";
+export interface GaltonBoardPhysicsOptions<TDatum extends Datum = Datum> {
+    data: readonly TDatum[];
+    valueAccessor: ChartAccessor<TDatum, number>;
+    bins: number;
+    ballRadius: number;
+    seed: number;
+    size: [number, number];
+    valueExtent?: [number, number];
+}
+export interface GaltonBoardProjectionMetadata {
+    kind: "galton-board";
+    bins: number;
+    plot: PhysicsChartArea["plot"];
+    valueExtent: [number, number];
+}
+export interface GaltonMechanicalSampleOptions {
+    bins: number;
+    count?: number;
+    pegRows?: number;
+    branchProbability?: number;
+    seed?: number;
+    idPrefix?: string;
+}
+export declare function generateGaltonMechanicalSamples(options: GaltonMechanicalSampleOptions): Datum[];
+export declare function buildGaltonBoardPhysics<TDatum extends Datum>(options: GaltonBoardPhysicsOptions<TDatum>): PhysicsChartLayout;

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

@@ -0,0 +1,67 @@
+/**
+ * GauntletChart public props (HOC surface).
+ */
+import type { StreamPhysicsFrameProps } from "../../stream/physics/StreamPhysicsFrame";
+import type { CapacityQueueSnapshot } from "../../stream/physics/PhysicsControllers";
+import type { PhysicsQueuedSpawn } from "../../stream/physics/PhysicsPipelineStore";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import type { PhysicsProcessBodyGroup } from "./physicsProcessPrimitives";
+import type { PhysicsHocFrameProps, PhysicsSharedChartProps, TooltipProp } from "./physicsHocUtils";
+import type { GauntletEvent, GauntletGate, GauntletLayout, GauntletProjectPlacement, GauntletProjectState, GauntletPropertyDefinition } from "./gauntletTypes";
+export interface GauntletChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin">, PhysicsSharedChartProps {
+    data?: TDatum[];
+    size?: [number, number];
+    idAccessor?: ChartAccessor<TDatum, string>;
+    labelAccessor?: ChartAccessor<TDatum, string>;
+    positiveAccessor?: ChartAccessor<TDatum, readonly string[]>;
+    negativeAccessor?: ChartAccessor<TDatum, readonly string[]>;
+    /** Simulation second when each project's local gate timeline begins. */
+    startTimeAccessor?: ChartAccessor<TDatum, number>;
+    metricsAccessor?: ChartAccessor<TDatum, Record<string, number>>;
+    initialViability?: ChartAccessor<TDatum, number>;
+    positiveProperties?: readonly GauntletPropertyDefinition[];
+    negativeProperties: readonly GauntletPropertyDefinition[];
+    bodyGroups?: readonly PhysicsProcessBodyGroup<TDatum>[] | ((projects: readonly GauntletProjectState<TDatum>[], layout: GauntletLayout) => readonly PhysicsProcessBodyGroup<TDatum>[]);
+    coreBody?: (project: GauntletProjectState<TDatum>, index: number, layout: GauntletLayout, placement: Required<GauntletProjectPlacement>) => Partial<PhysicsQueuedSpawn>;
+    gates?: readonly GauntletGate[];
+    events?: readonly GauntletEvent[] | ((project: GauntletProjectState<TDatum>, layout: GauntletLayout) => readonly GauntletEvent[]);
+    crashOffset?: number;
+    /** Draw the crash line but optionally disable live crash-line termination. */
+    crashDetection?: boolean;
+    emptyContent?: BaseChartProps["emptyContent"];
+    frameProps?: PhysicsHocFrameProps<"bodyForces">;
+    initialSpawnPacing?: StreamPhysicsFrameProps["initialSpawnPacing"];
+    loading?: BaseChartProps["loading"];
+    loadingContent?: BaseChartProps["loadingContent"];
+    onStateChange?: (states: GauntletProjectState<TDatum>[]) => void;
+    /** Live snapshots for gates declaring shared FIFO capacity. */
+    onCapacityChange?: (snapshots: CapacityQueueSnapshot[]) => void;
+    outcome?: (project: GauntletProjectState<TDatum>, context: {
+        layout: GauntletLayout;
+        negativeProperties: Map<string, GauntletPropertyDefinition>;
+        positiveProperties: Map<string, GauntletPropertyDefinition>;
+    }) => string;
+    paused?: boolean;
+    projectPlacement?: (project: GauntletProjectState<TDatum>, index: number, layout: GauntletLayout) => Partial<GauntletProjectPlacement>;
+    showChrome?: boolean;
+    /**
+     * Settled-projection strip: project viability bars and outcome labels so the
+     * chart remains readable without tracking body motion.
+     */
+    showProjection?: boolean;
+    showTethers?: boolean;
+    /**
+     * Core-body vertical force model.
+     * - "route": default authored route plus lift/drag burden.
+     * - "net": vertical drift follows summed positive vs negative property
+     *   weight, leaving the crash line to decide physical failure.
+     */
+    coreForceMode?: "route" | "net";
+    terminalBehavior?: "outcome" | "hold-last";
+    tooltip?: TooltipProp;
+    viability?: (project: GauntletProjectState<TDatum>, context: {
+        negativeProperties: Map<string, GauntletPropertyDefinition>;
+        positiveProperties: Map<string, GauntletPropertyDefinition>;
+    }) => number;
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Gauntlet canvas paint + SVG chrome / projection overlay.
+ */
+import * as React from "react";
+import type { Datum } from "../shared/datumTypes";
+import type { Style } from "../../stream/types";
+import type { PhysicsBodyState } from "../../stream/physics/PhysicsKernel";
+import type { PhysicsHoverData } from "../../stream/physics/StreamPhysicsFrame";
+import type { PhysicsSemanticItem } from "../../stream/physics/StreamPhysicsTypes";
+import { type GauntletLayout, type GauntletProjectState } from "./gauntletPhysics";
+export declare function defaultGauntletTooltipContent(hover: PhysicsHoverData): React.ReactNode;
+export declare function drawGauntletBody(ctx: CanvasRenderingContext2D, body: PhysicsBodyState, style: Style): void;
+export declare function resolveCanvasColor(ctx: CanvasRenderingContext2D, value: Style[keyof Style] | undefined, fallback: string): string;
+export declare function drawTethers(ctx: CanvasRenderingContext2D, bodies: PhysicsBodyState[]): void;
+export declare function GauntletChrome({ layout, states }: {
+    layout: GauntletLayout;
+    states: readonly GauntletProjectState[];
+}): React.JSX.Element;
+export declare function gauntletSemanticItem(body: PhysicsBodyState): false | {
+    label: string;
+    group: string;
+    description: string;
+};
+export declare function gauntletProjectionRows<TDatum extends Datum>(states: readonly GauntletProjectState<TDatum>[]): Array<{
+    label: string;
+    value: number;
+    outcome: string;
+}>;
+export declare function gauntletProjectionSemanticItems<TDatum extends Datum>(states: readonly GauntletProjectState<TDatum>[], layout: GauntletLayout): PhysicsSemanticItem[];
+export declare function GauntletProjectionOverlay<TDatum extends Datum>({ states, layout }: {
+    states: readonly GauntletProjectState<TDatum>[];
+    layout: GauntletLayout;
+}): React.JSX.Element | null;