semiotic 3.7.4 → 3.8.0

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;

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;
+};