semiotic 3.7.5 → 3.8.0

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

@@ -0,0 +1,73 @@
+/**
+ * Gauntlet React-facing controller glue: builds the imperative ref handle,
+ * the per-gate capacity controllers, and the per-tick crash/event-application
+ * pass. Plain functions (no hooks) called from inside GauntletChart's
+ * existing useImperativeHandle/useMemo/useCallback — refs and memoized
+ * callbacks are passed in explicitly instead of closed over, so identity and
+ * dependency-array semantics are unchanged from before extraction.
+ */
+import type { Datum } from "../shared/datumTypes";
+import type { PhysicsFrameHandle } from "./physicsHocHandle";
+import { type CapacityQueueSnapshot, type PhysicsController } from "../../stream/physics/PhysicsControllers";
+import type { PhysicsPipelineControlSurface, PhysicsPipelineTickResult } from "../../stream/physics/PhysicsPipelineStore";
+import type { StreamPhysicsFrameHandle } from "../../stream/physics/StreamPhysicsFrame";
+import { type GauntletCoreBodyFn, type GauntletEffect, type GauntletEvent, type GauntletLayout, type GauntletProjectPlacementFn, type GauntletProjectState, type GauntletPropertyDefinition, type GauntletViabilityFn } from "./gauntletPhysics";
+export declare function capacitySnapshotsEqual(a: readonly CapacityQueueSnapshot[], b: readonly CapacityQueueSnapshot[]): boolean;
+/** Build one capacity-queue controller per gate that declares `capacity`. */
+export declare function buildGauntletCapacityControllers<TDatum extends Datum>(options: {
+    dataKey: string;
+    gates: GauntletLayout["gates"];
+    statesRef: {
+        current: readonly GauntletProjectState<TDatum>[];
+    };
+    processedGateVisitsRef: {
+        current: Map<string, number>;
+    };
+}): PhysicsController[];
+/** Build the `ref.current` imperative API (push/pushMany/remove/update/clear/...). */
+export declare function buildGauntletImperativeHandle<TDatum extends Datum>(deps: {
+    statesRef: {
+        current: GauntletProjectState<TDatum>[];
+    };
+    setStates: (states: GauntletProjectState<TDatum>[]) => void;
+    elapsedRef: {
+        current: number;
+    };
+    frameRef: {
+        current: StreamPhysicsFrameHandle | null;
+    };
+    layout: GauntletLayout;
+    projectPlacement: GauntletProjectPlacementFn<TDatum> | undefined;
+    positiveById: Map<string, GauntletPropertyDefinition>;
+    negativeById: Map<string, GauntletPropertyDefinition>;
+    coreBody: GauntletCoreBodyFn<TDatum> | undefined;
+    createState: (datum: TDatum, index: number, defaultStartedAt?: number) => GauntletProjectState<TDatum>;
+}): PhysicsFrameHandle;
+/** Per-tick crash detection + due-event application, driving `updateProjectState`. */
+export declare function runGauntletTick<TDatum extends Datum>(result: PhysicsPipelineTickResult, controls: PhysicsPipelineControlSurface, deps: {
+    frameProps: {
+        onTick?: (result: PhysicsPipelineTickResult, controls: PhysicsPipelineControlSurface) => void;
+    };
+    elapsedRef: {
+        current: number;
+    };
+    statesRef: {
+        current: readonly GauntletProjectState<TDatum>[];
+    };
+    crashDetection: boolean;
+    layout: GauntletLayout;
+    projectEvents: (project: GauntletProjectState<TDatum>) => readonly GauntletEvent[];
+    gateById: Map<string, GauntletLayout["gates"][number]>;
+    capacityEventReady: (project: GauntletProjectState<TDatum>, event: GauntletEvent, timeline: readonly GauntletEvent[]) => boolean;
+    addBodiesForEffect: (project: GauntletProjectState<TDatum>, effect: GauntletEffect, controls: PhysicsPipelineControlSurface) => void;
+    updateProjectState: (projectId: string, updater: (project: GauntletProjectState<TDatum>) => GauntletProjectState<TDatum>) => void;
+    viability: GauntletViabilityFn<TDatum> | undefined;
+    positiveById: Map<string, GauntletPropertyDefinition>;
+    negativeById: Map<string, GauntletPropertyDefinition>;
+    outcome: ((project: GauntletProjectState<TDatum>, context: {
+        layout: GauntletLayout;
+        negativeProperties: Map<string, GauntletPropertyDefinition>;
+        positiveProperties: Map<string, GauntletPropertyDefinition>;
+    }) => string) | undefined;
+    reportCapacity: () => void;
+}): void;

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

@@ -0,0 +1,36 @@
+/**
+ * Pure Gauntlet gate-effect helpers (no React): resolving which attached
+ * properties an effect pops, planning bounded property work, and applying
+ * an effect to project state.
+ */
+import type { Datum } from "../shared/datumTypes";
+import type { GauntletEffect, GauntletEvent, GauntletEventContext, GauntletEventLogItem, GauntletNegativeReplacementOptions, GauntletPopSpec, GauntletProjectState, GauntletPropertyWorkPlan, GauntletPropertyWorkPlanOptions } from "./gauntletTypes";
+export declare function expandIds(input: readonly string[] | Record<string, number> | undefined): string[];
+export declare function isReadonlyStringArray(value: GauntletPopSpec | undefined): value is readonly string[];
+export declare function resolvePopSpecIds(attachedIds: readonly string[], popSpec: GauntletPopSpec | undefined): string[];
+export declare function resolvePopPositiveIds<TDatum extends Datum>(project: GauntletProjectState<TDatum>, effect: GauntletEffect): string[];
+/**
+ * Select attached property occurrences without exceeding a bounded work
+ * budget. Selection is deterministic: property priority, then attachment
+ * order. Expensive occurrences are skipped so later affordable work can fit.
+ */
+export declare function planGauntletPropertyWork(options: GauntletPropertyWorkPlanOptions): GauntletPropertyWorkPlan;
+/** Build one add/pop effect for an occurrence-preserving replacement. */
+export declare function replaceGauntletNegative<TDatum extends Datum>(project: GauntletProjectState<TDatum>, options: GauntletNegativeReplacementOptions): GauntletEffect;
+/**
+ * Resolve which negative property instances to detach. Returns body indices
+ * into `project.negativeIds` so multi-instance loads keep stable body ids.
+ */
+export declare function resolvePopNegativeEntries<TDatum extends Datum>(project: GauntletProjectState<TDatum>, effect: GauntletEffect): Array<{
+    propertyId: string;
+    index: number;
+}>;
+/**
+ * Pure project-state transition for a single gate effect. Exported so unit
+ * tests can cover popPositive / popNegative / add* without driving the
+ * full physics tick loop.
+ */
+export declare function applyGauntletEffect<TDatum extends Datum>(project: GauntletProjectState<TDatum>, effect: GauntletEffect, context: GauntletEventContext<TDatum>): GauntletProjectState<TDatum>;
+export declare function eventLogItem(event: GauntletEvent, effects: readonly GauntletEffect[]): GauntletEventLogItem;
+/** Append one semantic event exactly once, even when render ticks outpace state commits. */
+export declare function recordGauntletEvent<TDatum extends Datum>(project: GauntletProjectState<TDatum>, logItem: GauntletEventLogItem): GauntletProjectState<TDatum>;

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

@@ -0,0 +1,71 @@
+/**
+ * Pure Gauntlet physics helpers (no React).
+ * Types: `./gauntletTypes`.
+ */
+import type { Datum } from "../shared/datumTypes";
+import type { ChartAccessor } from "../shared/types";
+import type { PhysicsPipelineConfig, PhysicsQueuedSpawn } from "../../stream/physics/PhysicsPipelineStore";
+import { type GauntletAccessors, type GauntletCoreBodyFn, type GauntletGate, type GauntletLayout, type GauntletProjectPlacement, type GauntletProjectPlacementFn, type GauntletProjectState, type GauntletPropertyDefinition, type GauntletViabilityFn } from "./gauntletTypes";
+export { CORE_KIND, POSITIVE_KIND, NEGATIVE_KIND } from "./gauntletTypes";
+export type { GauntletAccessors, GauntletBodyDatum, GauntletCoreBodyFn, GauntletEffect, GauntletEvent, GauntletEventContext, GauntletEventLogItem, GauntletGate, GauntletLayout, GauntletNegativeReplacementOptions, GauntletPopSpec, GauntletProjectPlacement, GauntletProjectPlacementFn, GauntletProjectState, GauntletPropertyDefinition, GauntletPropertyForceContext, GauntletPropertyWorkPlan, GauntletPropertyWorkPlanOptions, GauntletViabilityFn } from "./gauntletTypes";
+export declare const DEFAULT_WIDTH = 900;
+export declare const DEFAULT_HEIGHT = 520;
+export declare function gauntletWallColliders(layout: Pick<GauntletLayout, "width" | "floorY">): NonNullable<PhysicsPipelineConfig["colliders"]>;
+export declare function readAccessor<TDatum extends Datum, TValue>(datum: TDatum, index: number, accessor: ChartAccessor<TDatum, TValue> | undefined, fallback: TValue): TValue;
+export declare function propertyLabel(property: GauntletPropertyDefinition | undefined): string;
+export declare function projectCoreId(projectId: string): string;
+export declare function projectPositiveId(projectId: string, propertyId: string): string;
+export declare function projectNegativeId(projectId: string, propertyId: string, index: number): string;
+/** Interior of the collider box (matches wall segments in the frame config). */
+export declare const GAUNTLET_WALL: {
+    readonly left: 28;
+    readonly top: 76;
+    readonly rightInset: 30;
+    readonly thickness: 8;
+};
+/**
+ * Keep body centers inside the playable gauntlet corridor so satellite
+ * property particles never spawn or settle outside the left/right walls
+ * (the "stuck on the left" regression for Homes on Main Street).
+ */
+export declare function clampGauntletPoint(x: number, y: number, radius: number, layout: Pick<GauntletLayout, "width" | "floorY">): {
+    x: number;
+    y: number;
+};
+export declare function buildLayout(size: [number, number], gates: readonly GauntletGate[] | undefined, crashOffset: number): GauntletLayout;
+export declare function defaultPlacement(layout: GauntletLayout): Required<GauntletProjectPlacement>;
+export declare function resolvePlacement<TDatum extends Datum>(project: GauntletProjectState<TDatum>, index: number, layout: GauntletLayout, projectPlacement: GauntletProjectPlacementFn<TDatum> | undefined): Required<GauntletProjectPlacement>;
+export declare function featureSlot(ids: readonly string[], id: string): {
+    angle: number;
+    index: number;
+    radius: number;
+};
+export declare function defaultViability<TDatum extends Datum>(project: GauntletProjectState<TDatum>, positiveProperties: Map<string, GauntletPropertyDefinition>, negativeProperties: Map<string, GauntletPropertyDefinition>): number;
+export declare function createInitialState<TDatum extends Datum>(datum: TDatum, index: number, props: GauntletAccessors<TDatum>, positiveProperties: readonly GauntletPropertyDefinition[], negativeProperties: Map<string, GauntletPropertyDefinition>): GauntletProjectState<TDatum>;
+export declare function buildProjectSpawns<TDatum extends Datum>(project: GauntletProjectState<TDatum>, projectIndex: number, layout: GauntletLayout, placement: Required<GauntletProjectPlacement>, positiveProperties: Map<string, GauntletPropertyDefinition>, negativeProperties: Map<string, GauntletPropertyDefinition>, coreBody?: GauntletCoreBodyFn<TDatum>): PhysicsQueuedSpawn[];
+/**
+ * Pure Gauntlet world builder for SSR / renderChart. Materializes project
+ * cores + property satellites once without React state or gate animation.
+ */
+export declare function buildGauntletPhysics<TDatum extends Datum = Datum>(options: {
+    data?: readonly TDatum[];
+    size?: [number, number];
+    gates?: readonly GauntletGate[];
+    positiveProperties?: readonly GauntletPropertyDefinition[];
+    negativeProperties?: readonly GauntletPropertyDefinition[];
+    crashOffset?: number;
+    idAccessor?: ChartAccessor<TDatum, string>;
+    positiveAccessor?: ChartAccessor<TDatum, readonly string[]>;
+    negativeAccessor?: ChartAccessor<TDatum, readonly string[]>;
+    metricsAccessor?: ChartAccessor<TDatum, Record<string, number>>;
+    initialViability?: ChartAccessor<TDatum, number>;
+    startTimeAccessor?: ChartAccessor<TDatum, number>;
+    projectPlacement?: GauntletProjectPlacementFn<TDatum>;
+    coreBody?: GauntletCoreBodyFn<TDatum>;
+    viability?: GauntletViabilityFn<TDatum>;
+}): {
+    config: NonNullable<import("../../stream/physics/PhysicsPipelineStore").PhysicsPipelineConfig>;
+    initialSpawns: PhysicsQueuedSpawn[];
+    layout: GauntletLayout;
+};
+export declare function buildNegativeSpawn<TDatum extends Datum>(project: GauntletProjectState<TDatum>, property: GauntletPropertyDefinition, index: number, x: number, y: number, layout: Pick<GauntletLayout, "width" | "floorY">, spawnAt?: number): PhysicsQueuedSpawn;

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

@@ -0,0 +1,42 @@
+/**
+ * Gauntlet per-frame body force + tick helpers (no React).
+ */
+import type { PhysicsBodyState } from "../../stream/physics/PhysicsKernel";
+import type { PhysicsPipelineControlSurface } from "../../stream/physics/PhysicsPipelineStore";
+import type { Datum } from "../shared/datumTypes";
+import { type GauntletCoreBodyFn, type GauntletEffect, type GauntletEvent, type GauntletLayout, type GauntletProjectPlacement, type GauntletProjectPlacementFn, type GauntletProjectState, type GauntletPropertyDefinition } from "./gauntletPhysics";
+export declare function computeGauntletBodyForce<TDatum extends Datum>(options: {
+    body: PhysicsBodyState;
+    bodies: readonly PhysicsBodyState[];
+    layout: GauntletLayout;
+    states: readonly GauntletProjectState<TDatum>[];
+    projectPlacement: GauntletProjectPlacementFn<TDatum> | undefined;
+    positiveById: Map<string, GauntletPropertyDefinition>;
+    negativeById: Map<string, GauntletPropertyDefinition>;
+    projectEvents: (project: GauntletProjectState<TDatum>) => readonly GauntletEvent[];
+    gateById: Map<string, GauntletLayout["gates"][number]>;
+    coreForceMode: "route" | "net";
+    terminalBehavior: "outcome" | "hold-last";
+    elapsed: number;
+}): {
+    x: number;
+    y: number;
+} | null;
+export declare function spawnBodiesForGauntletEffect<TDatum extends Datum>(options: {
+    project: GauntletProjectState<TDatum>;
+    effect: GauntletEffect;
+    controls: PhysicsPipelineControlSurface;
+    layout: GauntletLayout;
+    positiveById: Map<string, GauntletPropertyDefinition>;
+    negativeById: Map<string, GauntletPropertyDefinition>;
+    coreBody?: GauntletCoreBodyFn<TDatum>;
+    popBodies: (ids: string[], options?: {
+        color?: string;
+        durationMs?: number;
+        radius?: number;
+    }) => unknown;
+}): void;
+export declare function projectRouteTarget<TDatum extends Datum>(elapsed: number, project: GauntletProjectState<TDatum>, layout: GauntletLayout, placement: Required<GauntletProjectPlacement>, events: readonly GauntletEvent[], gateById: Map<string, GauntletLayout["gates"][number]>, terminalBehavior: "outcome" | "hold-last"): {
+    x: number;
+    y: number;
+};

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

@@ -0,0 +1,213 @@
+/**
+ * Gauntlet domain types + body-kind constants (no heavy runtime).
+ */
+import type { Datum } from "../shared/datumTypes";
+import type { ChartAccessor } from "../shared/types";
+import type { PhysicsBodyState } from "../../stream/physics/PhysicsKernel";
+import type { PhysicsQueuedSpawn, PhysicsSpawnSpringSpec } from "../../stream/physics/PhysicsPipelineStore";
+import type { StreamPhysicsRegionEffect } from "../../stream/physics/StreamPhysicsTypes";
+export declare const CORE_KIND: "gauntlet-core";
+export declare const POSITIVE_KIND: "gauntlet-positive";
+export declare const NEGATIVE_KIND: "gauntlet-negative";
+export interface GauntletProjectPlacement {
+    graveyardX?: number;
+    graveyardY?: number;
+    routeY?: number;
+    socketX?: number;
+    socketY?: number;
+    startX?: number;
+    startY?: number;
+}
+export interface GauntletPropertyForceContext<TDatum extends Datum = Datum> {
+    body: PhysicsBodyState;
+    bodies: readonly PhysicsBodyState[];
+    core: PhysicsBodyState;
+    index: number;
+    layout: GauntletLayout;
+    placement: Required<GauntletProjectPlacement>;
+    project: GauntletProjectState<TDatum>;
+}
+export interface GauntletPropertyDefinition {
+    id: string;
+    label?: string;
+    short?: string;
+    color?: string;
+    value?: number;
+    radius?: number;
+    mass?: number;
+    buoyancy?: number;
+    load?: number;
+    /** Work units required to remove one occurrence at a bounded-work gate. */
+    work?: number;
+    /** Lower values are selected first by the default work-budget planner. */
+    priority?: number;
+    pull?: {
+        x?: number;
+        y?: number;
+    };
+    popColor?: string;
+    spring?: false | Partial<PhysicsSpawnSpringSpec>;
+    target?: (context: GauntletPropertyForceContext) => {
+        x: number;
+        y: number;
+    } | null | undefined;
+}
+export interface GauntletGate {
+    id: string;
+    label?: string;
+    description?: string;
+    color?: string;
+    /**
+     * Optional shared FIFO capacity for compound cores crossing this gate.
+     * Event time remains the earliest arrival; the matching gate event waits
+     * until the project's core has been processed.
+     */
+    capacity?: {
+        unitsPerSecond: number;
+        /** Reads work units from the source datum or live project state. */
+        unitAccessor?: string | ((project: GauntletProjectState) => number);
+        maxQueue?: number;
+        queueLayout?: "lane" | "none";
+        queueSlotSpacing?: number;
+        queueStiffness?: number;
+        /** Invisible sensor/queue width; independent from the drawn gate width. */
+        sensorWidth?: number;
+    };
+    enabled?: boolean;
+    regionEffect?: Partial<Omit<StreamPhysicsRegionEffect, "id" | "shape">>;
+    time?: number;
+    x?: number;
+    width?: number;
+}
+/** Pop one or more attached property ids from a project. */
+export type GauntletPopSpec = readonly string[] | {
+    candidates?: readonly string[];
+    count?: number;
+    ids?: readonly string[];
+};
+export interface GauntletEffect {
+    addPositive?: readonly string[] | Record<string, number>;
+    addNegative?: readonly string[] | Record<string, number>;
+    popPositive?: GauntletPopSpec;
+    /**
+     * Remove attached negative property bodies — the inverse of the common
+     * "pop positives / add negatives" gate. Supports the same array / candidates
+     * / ids shape as {@link popPositive}.
+     */
+    popNegative?: GauntletPopSpec;
+    delayDelta?: number;
+    metricsDelta?: Record<string, number>;
+    outcome?: string;
+    stage?: string;
+    summary?: string;
+    viabilityDelta?: number;
+    when?: (context: GauntletEventContext) => boolean;
+}
+export interface GauntletEvent {
+    id: string;
+    label?: string;
+    time: number;
+    gateId?: string;
+    /** Capacity-gate visit this event waits for. Defaults to its gate-event ordinal. */
+    gateVisit?: number;
+    effects?: readonly GauntletEffect[];
+    final?: boolean;
+    outcome?: string;
+    routeX?: number;
+    routeY?: number;
+    summary?: string;
+}
+export interface GauntletEventLogItem {
+    id: string;
+    label: string;
+    summary?: string;
+    /** Actual project-local application time (event `time` is the authored earliest time). */
+    appliedAt?: number;
+    time?: number;
+}
+export interface GauntletProjectState<TDatum extends Datum = Datum> {
+    crashX?: number;
+    id: string;
+    activePositiveIds: string[];
+    datum: TDatum;
+    delay: number;
+    eventsApplied: string[];
+    /** Ordered event tape for readouts, replay evidence, and accessibility. */
+    eventHistory?: GauntletEventLogItem[];
+    killed: boolean;
+    lastEvent?: GauntletEventLogItem;
+    metrics: Record<string, number>;
+    missingPositiveIds: string[];
+    negativeIds: string[];
+    outcome: string;
+    poppedPositiveIds: string[];
+    /** Negative property ids removed by {@link GauntletEffect.popNegative}. */
+    poppedNegativeIds: string[];
+    /** Project-local timeline origin in simulation seconds. */
+    startedAt?: number;
+    stage: string;
+    viability: number;
+}
+export interface GauntletLayout {
+    crashY: number;
+    floorY: number;
+    gates: Array<Required<Pick<GauntletGate, "id" | "x" | "width">> & GauntletGate>;
+    graveyardX: number;
+    graveyardY: number;
+    height: number;
+    routeY: number;
+    socketX: number;
+    startX: number;
+    width: number;
+}
+export interface GauntletEventContext<TDatum extends Datum = Datum> {
+    event: GauntletEvent;
+    gate?: GauntletLayout["gates"][number];
+    negativeProperties: Map<string, GauntletPropertyDefinition>;
+    positiveProperties: Map<string, GauntletPropertyDefinition>;
+    project: GauntletProjectState<TDatum>;
+}
+/** Placement override for a project in layout space. */
+export type GauntletProjectPlacementFn<TDatum extends Datum = Datum> = (project: GauntletProjectState<TDatum>, index: number, layout: GauntletLayout) => Partial<GauntletProjectPlacement>;
+/** Optional spawn overrides for the project core body. */
+export type GauntletCoreBodyFn<TDatum extends Datum = Datum> = (project: GauntletProjectState<TDatum>, index: number, layout: GauntletLayout, placement: Required<GauntletProjectPlacement>) => Partial<PhysicsQueuedSpawn>;
+/** Custom viability scorer. */
+export type GauntletViabilityFn<TDatum extends Datum = Datum> = (project: GauntletProjectState<TDatum>, context: {
+    negativeProperties: Map<string, GauntletPropertyDefinition>;
+    positiveProperties: Map<string, GauntletPropertyDefinition>;
+}) => number;
+/** Accessors used when seeding project state from user rows. */
+export interface GauntletAccessors<TDatum extends Datum = Datum> {
+    idAccessor?: ChartAccessor<TDatum, string>;
+    initialViability?: ChartAccessor<TDatum, number>;
+    metricsAccessor?: ChartAccessor<TDatum, Record<string, number>>;
+    negativeAccessor?: ChartAccessor<TDatum, readonly string[]>;
+    positiveAccessor?: ChartAccessor<TDatum, readonly string[]>;
+    startTimeAccessor?: ChartAccessor<TDatum, number>;
+}
+export interface GauntletPropertyWorkPlanOptions {
+    attachedIds: readonly string[];
+    properties: readonly GauntletPropertyDefinition[] | Map<string, GauntletPropertyDefinition>;
+    budget: number;
+    candidates?: readonly string[];
+}
+export interface GauntletPropertyWorkPlan {
+    ids: string[];
+    used: number;
+    budget: number;
+    remaining: number;
+    skippedIds: string[];
+}
+export interface GauntletNegativeReplacementOptions {
+    from: string;
+    to: string;
+    count?: number;
+}
+/** Wall colliders matching {@link GAUNTLET_WALL} / SSR builder. */
+export interface GauntletBodyDatum<TDatum extends Datum = Datum> {
+    __gauntlet: true;
+    kind: typeof CORE_KIND | typeof POSITIVE_KIND | typeof NEGATIVE_KIND;
+    projectId: string;
+    property?: GauntletPropertyDefinition;
+    sourceDatum: TDatum;
+}

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

@@ -0,0 +1,57 @@
+import type { Datum } from "../shared/datumTypes";
+import type { ChartAccessor } from "../shared/types";
+import { type PhysicsChartArea, type PhysicsChartLayout } from "./physicsChartShared";
+export type PhysicalFlowCoordinateMode = "auto" | "normalized" | "pixels";
+export type PhysicalFlowPathConstraint = "path" | "none";
+export interface PhysicalFlowPoint {
+    x: number;
+    y: number;
+}
+export type PhysicalFlowRawPath = ReadonlyArray<PhysicalFlowPoint | readonly [number, number]>;
+export interface PhysicalFlowOptions<TNode extends Datum = Datum, TLink extends Datum = Datum> {
+    nodes: readonly TNode[];
+    links: readonly TLink[];
+    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;
+    seed: number;
+    size: [number, number];
+}
+export interface PhysicalFlowProjectionMetadata {
+    kind: "physical-flow";
+    coordinateMode: Exclude<PhysicalFlowCoordinateMode, "auto">;
+    particleCount: number;
+    totalThroughput: number;
+    plot: PhysicsChartArea["plot"];
+    nodes: Array<{
+        id: string;
+        label: string;
+        x: number;
+        y: number;
+        sensorId: string;
+        incoming: number;
+        outgoing: number;
+    }>;
+    links: Array<{
+        id: string;
+        source: string;
+        target: string;
+        sourceLabel: string;
+        targetLabel: string;
+        throughput: number;
+        packetCount: number;
+        path: PhysicalFlowPoint[];
+    }>;
+}
+export declare function buildPhysicalFlowPhysics<TNode extends Datum, TLink extends Datum>(options: PhysicalFlowOptions<TNode, TLink>): PhysicsChartLayout;

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

@@ -0,0 +1,41 @@
+import type { Datum } from "../shared/datumTypes";
+import type { ChartAccessor } from "../shared/types";
+import type { Style } from "../../stream/types";
+import type { PhysicsColliderSpec } from "../../stream/physics/PhysicsKernel";
+import type { PhysicsPipelineConfig, PhysicsQueuedSpawn, PhysicsSpawnPacingOptions } from "../../stream/physics/PhysicsPipelineStore";
+import type { PhysicsSemanticItem } from "../../stream/physics/StreamPhysicsTypes";
+export interface PhysicsChartLayout {
+    config: PhysicsPipelineConfig;
+    initialSpawns: PhysicsQueuedSpawn[];
+    initialSpawnPacing?: PhysicsSpawnPacingOptions;
+    projectionRows: Array<{
+        label: string;
+        value: number;
+        secondary?: number;
+    }>;
+    metadata?: Record<string, unknown>;
+}
+export interface PhysicsChartArea {
+    width: number;
+    height: number;
+    plot: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export declare function physicsChartArea(size: [number, number]): PhysicsChartArea;
+export declare function hashStringColor(value: unknown): string;
+export declare function styleFromColorAccessor<TDatum extends Datum>(colorBy: ChartAccessor<TDatum, string> | undefined, fallback?: string): (body: {
+    datum?: unknown;
+}) => Style;
+export declare function baseConfig(seed: number, colliders: PhysicsColliderSpec[], chartType: string, kernel?: Partial<NonNullable<PhysicsPipelineConfig["kernel"]>>): PhysicsPipelineConfig;
+export declare function projectionRowsToSemanticItems(rows: readonly PhysicsChartLayout["projectionRows"][number][], size: [number, number], noun: string): PhysicsSemanticItem[];
+export declare function readAccessor<TDatum extends Datum, TValue>(datum: TDatum, index: number, accessor: ChartAccessor<TDatum, TValue>): TValue;
+export declare function finiteNumber(value: unknown): number | null;
+export declare function clampNumber(value: number, min: number, max: number): number;
+export declare function positiveNumber(value: unknown, fallback: number): number;
+export declare function normalizedFiniteExtent(extent: readonly [unknown, unknown] | undefined): [number, number] | undefined;
+export declare function safeIdPart(value: unknown): string;
+export declare function seededRandom(seed: number): () => number;

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

@@ -0,0 +1,18 @@
+/**
+ * Physics chart layout builders — barrel re-export.
+ * Implementations live in per-chart modules next to this file.
+ */
+export type { PhysicsChartLayout, PhysicsChartArea } from "./physicsChartShared";
+export { projectionRowsToSemanticItems, physicsChartArea, hashStringColor, styleFromColorAccessor } from "./physicsChartShared";
+export type { GaltonBoardPhysicsOptions, GaltonBoardProjectionMetadata, GaltonMechanicalSampleOptions } from "./galtonBoardPhysics";
+export { generateGaltonMechanicalSamples, buildGaltonBoardPhysics } from "./galtonBoardPhysics";
+export type { EventDropWindowOptions, EventDropPlotRegion, EventDropLidSegment, EventDropProjectionMetadata, EventDropPhysicsOptions } from "./eventDropPhysics";
+export { buildEventDropPhysics, placeEventDropSpawn } from "./eventDropPhysics";
+export type { PhysicsPileMechanicalSampleOptions, PhysicsPileOptions, PileTubeGeometry } from "./physicsPilePhysics";
+export { generatePhysicsPileMechanicalSamples, pileTubeGeometry, buildPhysicsPile } from "./physicsPilePhysics";
+export type { CollisionSwarmPhysicsOptions, CollisionSwarmProjectionMetadata } from "./collisionSwarmPhysics";
+export { buildCollisionSwarmPhysics } from "./collisionSwarmPhysics";
+export type { PhysicalFlowCoordinateMode, PhysicalFlowPathConstraint, PhysicalFlowPoint, PhysicalFlowRawPath, PhysicalFlowOptions, PhysicalFlowProjectionMetadata } from "./physicalFlowPhysics";
+export { buildPhysicalFlowPhysics } from "./physicalFlowPhysics";
+export type { ProcessFlowStageDef, ProcessFlowPhysicsOptions, ProcessFlowProjectionMetadata } from "./processFlowPhysics";
+export { buildProcessFlowPhysics } from "./processFlowPhysics";