semiotic 3.7.5 → 3.8.1

package/dist/components/stream/physics/PhysicsKernel.d.ts

@@ -0,0 +1,207 @@
+export type PhysicsBodyShape = {
+    type: "circle";
+    radius: number;
+} | {
+    type: "aabb";
+    width: number;
+    height: number;
+};
+export type PhysicsColliderShape = {
+    type: "aabb";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | {
+    type: "segment";
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    thickness?: number;
+};
+export interface PhysicsKernelOptions {
+    seed?: number;
+    gravity?: {
+        x: number;
+        y: number;
+    };
+    fixedDt?: number;
+    cellSize?: number;
+    collisionIterations?: number;
+    velocityDamping?: number;
+    sleepSpeed?: number;
+    sleepAfter?: number;
+    restitution?: number;
+    friction?: number;
+    /** Speed cap (px/s) applied each substep to prevent tunneling through thin walls. */
+    maxVelocity?: number;
+    /**
+     * Contact impact speed (px/s) above which a resting/sleeping body is woken.
+     * Higher than `sleepSpeed` so a settled pile is not churned by every arrival —
+     * a sleeping body acts as a static anchor until something hits it hard enough.
+     */
+    contactWakeSpeed?: number;
+}
+export interface PhysicsBodySpec {
+    id: string;
+    x: number;
+    y: number;
+    vx?: number;
+    vy?: number;
+    angle?: number;
+    mass?: number;
+    restitution?: number;
+    friction?: number;
+    /** Disable body-body contacts for visual/tethered satellite marks. */
+    bodyCollisions?: boolean;
+    shape: PhysicsBodyShape;
+    datum?: unknown;
+}
+export interface PhysicsBodyState {
+    id: string;
+    x: number;
+    y: number;
+    prevX: number;
+    prevY: number;
+    vx: number;
+    vy: number;
+    angle: number;
+    mass: number;
+    bodyCollisions?: boolean;
+    shape: PhysicsBodyShape;
+    sleeping: boolean;
+    datum?: unknown;
+}
+export interface PhysicsColliderBodyFilterSpec {
+    property: string;
+    equals?: unknown;
+    notEquals?: unknown;
+    oneOf?: unknown[];
+    notOneOf?: unknown[];
+}
+export type PhysicsColliderBodyFilter = PhysicsColliderBodyFilterSpec | ((body: PhysicsBodyState) => boolean);
+export interface PhysicsColliderSpec {
+    id: string;
+    shape: PhysicsColliderShape;
+    sensor?: boolean;
+    restitution?: number;
+    friction?: number;
+    /**
+     * Optional body filter for permeable colliders. Bodies that do not match the
+     * filter ignore this collider or sensor entirely. Object filters are worker
+     * serializable; function filters require sync execution.
+     */
+    bodyFilter?: PhysicsColliderBodyFilter;
+}
+export interface PhysicsSpringSpec {
+    id?: string;
+    bodyId: string;
+    target: {
+        type: "point";
+        x: number;
+        y: number;
+    } | {
+        type: "body";
+        bodyId: string;
+    };
+    restLength?: number;
+    stiffness?: number;
+    damping?: number;
+}
+export interface PhysicsKernelSnapshotBody extends PhysicsBodyState {
+    bodyCollisions: boolean;
+    index: number;
+    sleepTime: number;
+    restitution?: number;
+    friction?: number;
+}
+export interface PhysicsKernelSnapshotCollider extends PhysicsColliderSpec {
+    index: number;
+}
+export interface PhysicsKernelSnapshotSpring extends Required<Omit<PhysicsSpringSpec, "target">> {
+    target: PhysicsSpringSpec["target"];
+}
+export type PhysicsKernelEvent = {
+    type: "contact";
+    bodyId: string;
+    otherId: string;
+    sensor: false;
+} | {
+    type: "sensor-enter";
+    bodyId: string;
+    sensorId: string;
+} | {
+    type: "sensor-exit";
+    bodyId: string;
+    sensorId: string;
+} | {
+    type: "sleep";
+    bodyId: string;
+} | {
+    type: "wake";
+    bodyId: string;
+};
+export interface PhysicsActiveSensorPair {
+    sensorId: string;
+    bodyId: string;
+}
+export interface PhysicsKernelSnapshot {
+    options: Required<PhysicsKernelOptions>;
+    bodies: PhysicsKernelSnapshotBody[];
+    colliders: PhysicsKernelSnapshotCollider[];
+    springs: PhysicsKernelSnapshotSpring[];
+    activeSensors: string[];
+}
+export declare class PhysicsKernelWorld {
+    readonly capabilities: {
+        determinism: "strict";
+        sensors: boolean;
+        joints: boolean;
+        ccd: boolean;
+        maxBodiesHint: number;
+        worker: boolean;
+    };
+    private options;
+    private bodies;
+    private colliders;
+    private springs;
+    private activeSensors;
+    private supportedThisStep;
+    private lastEvents;
+    private nextBodyIndex;
+    private nextColliderIndex;
+    private nextSpringIndex;
+    private random;
+    constructor(options?: PhysicsKernelOptions);
+    init(options?: PhysicsKernelOptions): void;
+    spawn(spec: PhysicsBodySpec): void;
+    remove(ids: string[]): void;
+    setColliders(colliders: PhysicsColliderSpec[]): void;
+    setConstraint(spec: PhysicsSpringSpec): string;
+    removeConstraint(id: string): void;
+    applyImpulse(id: string, ix: number, iy: number): void;
+    step(dtSeconds?: number): void;
+    settle(maxSteps?: number, dtSeconds?: number): number;
+    readState(out?: PhysicsBodyState[]): PhysicsBodyState[];
+    events(): PhysicsKernelEvent[];
+    activeSensorPairs(): PhysicsActiveSensorPair[];
+    allSleeping(): boolean;
+    snapshot(): PhysicsKernelSnapshot;
+    restore(snapshot: PhysicsKernelSnapshot): void;
+    dispose(): void;
+    private sortedBodies;
+    private sortedColliders;
+    private applySprings;
+    private resolveBodyPairs;
+    private bodyPairKeys;
+    private resolveDynamicCollision;
+    private applyFriction;
+    private resolveColliders;
+    private resolveStaticCollision;
+    private updateSensors;
+    private updateSleeping;
+    private wake;
+    /** Uses the deterministic PRNG for future jittered spawn helpers. */
+    nextRandom(): number;
+}

package/dist/components/stream/physics/PhysicsOptionalEngineAdapters.d.ts

@@ -0,0 +1,12 @@
+export interface PhysicsOptionalEngineInstallDetails {
+    engine: string;
+    importPath: string;
+    packageName: string;
+    installCommand: string;
+}
+export declare class PhysicsOptionalEngineDependencyError extends Error {
+    readonly details: PhysicsOptionalEngineInstallDetails;
+    constructor(details: PhysicsOptionalEngineInstallDetails, cause?: unknown);
+}
+export declare function optionalEngineDependencyError(details: PhysicsOptionalEngineInstallDetails, cause?: unknown): PhysicsOptionalEngineDependencyError;
+export declare function loadOptionalPhysicsPeer(details: PhysicsOptionalEngineInstallDetails): Promise<unknown>;

package/dist/components/stream/physics/PhysicsPipelineStore.d.ts

@@ -0,0 +1,86 @@
+import { type PhysicsBodyState, type PhysicsColliderSpec, type PhysicsKernelEvent, type PhysicsSpringSpec } from "./PhysicsKernel";
+import { type PhysicsSedimentBinSnapshot, type PhysicsSedimentColumn, type PhysicsSedimentHeightfieldOptions, type PhysicsSedimentTotals } from "./PhysicsSediment";
+import { type PhysicsBodyBudgetDecision } from "./PhysicsBodyBudget";
+import type { PhysicsObservationEvent, PhysicsObservationRecord, PhysicsPipelineConfig, PhysicsPipelineControlSurface, PhysicsPipelineSnapshot, PhysicsPipelineTickResult, PhysicsQueuedSpawn, PhysicsSpawnPacingOptions } from "./PhysicsPipelineTypes";
+import { type UpdateResult } from "../pipelineUpdateContract";
+export type { PhysicsPlotBounds, PhysicsBoundsColliderOptions, PhysicsXBinColliderOptions, PhysicsSpawnSpringSpec, PhysicsQueuedSpawn, PhysicsSpawnPacing, PhysicsSpawnTimeAccessor, PhysicsSpawnPacingOptions, PhysicsPipelineQueuedSpawnSnapshot, PhysicsObservationEventType, PhysicsSimulationState, PhysicsObservationEvent, PhysicsObservationRecord, PhysicsSensorObservationConfig, PhysicsPipelineObservationOptions, PhysicsPipelineConfig, PhysicsPipelineTickResult, PhysicsPipelineSnapshot, PhysicsPipelineControlSurface } from "./PhysicsPipelineTypes";
+export { schedulePhysicsSpawns, collidersFromPlotBounds, collidersFromXScaleBins } from "./physicsPipelineHelpers";
+export type { ChangeSet, Invalidation, RevisionSet, UpdateResult } from "../pipelineUpdateContract";
+export declare class PhysicsPipelineStore {
+    private activeSensorPairs;
+    private accumulator;
+    private bodyBudget;
+    private bodyBudgetObservationKey;
+    private config;
+    /** Raw public config references, used only for no-op classification. */
+    private configInput;
+    private engineInput?;
+    private bodySpatialIndex;
+    private elapsedSeconds;
+    private liveBodyOrder;
+    private nextSequence;
+    private observation;
+    private paused;
+    private queue;
+    private revision;
+    private updateResults;
+    private sediment;
+    private simulationState;
+    private visible;
+    private world;
+    constructor(config?: PhysicsPipelineConfig);
+    updateConfig(config: PhysicsPipelineConfig): void;
+    /** Additive explicit-result form of {@link updateConfig}. */
+    updateConfigWithResult(config: PhysicsPipelineConfig): UpdateResult;
+    setColliders(colliders: PhysicsColliderSpec[]): void;
+    enqueue(spawn: PhysicsQueuedSpawn | PhysicsQueuedSpawn[], pacing?: PhysicsSpawnPacingOptions): void;
+    /** Additive explicit-result form of {@link enqueue}. */
+    enqueueWithResult(spawn: PhysicsQueuedSpawn | PhysicsQueuedSpawn[], pacing?: PhysicsSpawnPacingOptions): UpdateResult;
+    spawnNow(spawn: PhysicsQueuedSpawn): void;
+    clear(): void;
+    tick(deltaSeconds: number): PhysicsPipelineTickResult;
+    settle(maxSteps?: number): number;
+    settleWithObservations(maxSteps?: number): PhysicsPipelineTickResult;
+    readBodies(out?: PhysicsBodyState[]): PhysicsBodyState[];
+    readSediment(): PhysicsSedimentBinSnapshot[];
+    bodyBudgetStatus(): PhysicsBodyBudgetDecision;
+    sedimentTotals(): PhysicsSedimentTotals;
+    sedimentHeightfield(options?: PhysicsSedimentHeightfieldOptions): PhysicsSedimentColumn[];
+    hitTest(x: number, y: number, radius?: number): PhysicsBodyState | null;
+    events(): PhysicsKernelEvent[];
+    allSleeping(): boolean;
+    hasPendingWork(): boolean;
+    queueSize(): number;
+    liveBodyCount(): number;
+    elapsed(): number;
+    recordObservation(record: PhysicsObservationRecord): PhysicsObservationEvent;
+    /** Most recent explicit update result for a revision-aware host or tool. */
+    getLastUpdateResult(): UpdateResult;
+    getUpdateSnapshot(): UpdateResult;
+    subscribeUpdateResult(listener: () => void): () => void;
+    version(): number;
+    setPaused(paused: boolean): void;
+    setVisible(visible: boolean): void;
+    remove(ids: string[]): string[];
+    setConstraint(spec: PhysicsSpringSpec): string;
+    removeConstraint(id: string): void;
+    applyImpulse(id: string, ix: number, iy: number): void;
+    nextRandom(): number;
+    controls(): PhysicsPipelineControlSurface;
+    snapshot(): PhysicsPipelineSnapshot;
+    restore(snapshot: PhysicsPipelineSnapshot): void;
+    private spawnDue;
+    private spawnOne;
+    private result;
+    private observeKernelEvents;
+    private observeSensorTransitions;
+    private removeActiveSensorPairsForBodies;
+    private observationContext;
+    private emitObservation;
+    private evaluateBodyBudget;
+    private observeBodyBudget;
+    private syncSimulationState;
+    private evictOverflow;
+    private absorbSediment;
+    private sleepingFirstEvictionOrder;
+}

package/dist/components/stream/physics/PhysicsPipelineTypes.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Public types for PhysicsPipelineStore.
+ * Separated so helpers, frames, and recipes can import types without the store class.
+ */
+import type { PhysicsBodySpec, PhysicsBodyState, PhysicsColliderSpec, PhysicsKernelEvent, PhysicsKernelOptions, PhysicsKernelSnapshot, PhysicsSpringSpec } from "./PhysicsKernel";
+import type { PhysicsEngineAdapterInput } from "./PhysicsEngineAdapter";
+import type { PhysicsSedimentBinSnapshot, PhysicsSedimentColumn, PhysicsSedimentConfig, PhysicsSedimentHeightfieldOptions, PhysicsSedimentTotals } from "./PhysicsSediment";
+import type { PhysicsBodyBudgetDecision, PhysicsBodyBudgetOptions } from "./PhysicsBodyBudget";
+export interface PhysicsPlotBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface PhysicsBoundsColliderOptions {
+    idPrefix?: string;
+    includeFloor?: boolean;
+    includeCeiling?: boolean;
+    includeLeftWall?: boolean;
+    includeRightWall?: boolean;
+    wallThickness?: number;
+    floorThickness?: number;
+}
+export interface PhysicsXBinColliderOptions {
+    idPrefix?: string;
+    count: number;
+    domainStart: number;
+    domainStep: number;
+    xScale: (value: number) => number;
+    yTop: number;
+    yBottom: number;
+    wallThickness?: number;
+    includeBoundaryWalls?: boolean;
+    includeInteriorWalls?: boolean;
+    closedBefore?: number;
+    lidY?: number;
+    lidThickness?: number;
+}
+export type PhysicsSpawnSpringSpec = Omit<PhysicsSpringSpec, "bodyId">;
+export interface PhysicsQueuedSpawn extends PhysicsBodySpec {
+    spawnAt?: number;
+    springs?: PhysicsSpawnSpringSpec[];
+}
+export type PhysicsSpawnPacing = "immediate" | "arrival" | {
+    ratePerSec: number;
+};
+export type PhysicsSpawnTimeAccessor = string | ((spawn: PhysicsQueuedSpawn, index: number) => unknown);
+export interface PhysicsSpawnPacingOptions {
+    pacing?: PhysicsSpawnPacing;
+    startAt?: number;
+    timeAccessor?: PhysicsSpawnTimeAccessor;
+    timeScale?: number;
+}
+export interface PhysicsPipelineQueuedSpawnSnapshot extends PhysicsQueuedSpawn {
+    sequence: number;
+    spawnAt: number;
+}
+export type PhysicsObservationEventType = "physics-spawn" | "physics-settle" | "physics-sediment" | "physics-budget-warning" | "physics-budget-overflow" | "physics-bin-enter" | "physics-bin-exit" | "physics-proximity-enter" | "physics-proximity-exit" | "physics-late" | "physics-barrier-cross" | "physics-capacity-processed" | "physics-capacity-queued" | "physics-capacity-blocked" | "physics-capacity-abandoned" | "sim-active" | "sim-idle";
+export type PhysicsSimulationState = "running" | "paused" | "settled";
+export interface PhysicsObservationEvent {
+    type: PhysicsObservationEventType;
+    timestamp: number;
+    chartType: string;
+    chartId: string;
+    bodyId?: string;
+    datum?: unknown;
+    x?: number;
+    y?: number;
+    sensorId?: string;
+    binId?: string;
+    barrierId?: string;
+    barrierValue?: number;
+    count?: number;
+    total?: number;
+    budgetAction?: PhysicsBodyBudgetDecision["action"];
+    bodyLimit?: number;
+    engineMaxBodiesHint?: number;
+    liveBodies?: number;
+    overflow?: number;
+    projectedBodies?: number;
+    queuedBodies?: number;
+    warnAt?: number;
+    simulationState?: PhysicsSimulationState;
+    previousSimulationState?: PhysicsSimulationState;
+    /** Capacitated region id for capacity queue controllers. */
+    regionId?: string;
+    /** Work units processed when a capacity queue releases a body. */
+    work?: number;
+    /** Semantic service identity and visit metadata for capacity controllers. */
+    jobId?: string;
+    visitId?: string;
+    visit?: number;
+    queuedAt?: number;
+    blockedAt?: number;
+    completedAt?: number;
+    abandonedAt?: number;
+    queueSeconds?: number;
+    queueDepth?: number;
+    blockedDepth?: number;
+    remainingWork?: number;
+}
+export type PhysicsObservationRecord = Omit<PhysicsObservationEvent, "timestamp" | "chartType" | "chartId"> & Partial<Pick<PhysicsObservationEvent, "timestamp" | "chartType" | "chartId">>;
+export interface PhysicsSensorObservationConfig {
+    binId?: string;
+    enterType?: PhysicsObservationEventType;
+    exitType?: PhysicsObservationEventType;
+}
+export interface PhysicsPipelineObservationOptions {
+    chartId?: string;
+    chartType?: string;
+    sensors?: Record<string, PhysicsSensorObservationConfig>;
+    onObservation?: (event: PhysicsObservationEvent) => void;
+    onSimulationStateChange?: (state: PhysicsSimulationState, previousState: PhysicsSimulationState) => void;
+}
+export interface PhysicsPipelineConfig {
+    bodyBudget?: false | PhysicsBodyBudgetOptions;
+    engine?: PhysicsEngineAdapterInput;
+    kernel?: PhysicsKernelOptions;
+    colliders?: PhysicsColliderSpec[];
+    bodyLimit?: number;
+    eviction?: false | "oldest" | "sleeping-first";
+    sediment?: false | PhysicsSedimentConfig;
+    fixedDt?: number;
+    maxDeltaSeconds?: number;
+    maxSubsteps?: number;
+    settleStepLimit?: number;
+    timeScale?: number;
+    observation?: PhysicsPipelineObservationOptions;
+}
+export interface PhysicsPipelineTickResult {
+    budget: PhysicsBodyBudgetDecision;
+    elapsedSeconds: number;
+    evicted: string[];
+    events: PhysicsKernelEvent[];
+    observations: PhysicsObservationEvent[];
+    queueSize: number;
+    revision: number;
+    shouldContinue: boolean;
+    sleeping: boolean;
+    sedimented: string[];
+    spawned: string[];
+    steps: number;
+}
+export interface PhysicsPipelineSnapshot {
+    accumulator: number;
+    activeSensorPairs: string[];
+    bodyBudget: false | PhysicsBodyBudgetOptions;
+    config: Required<Omit<PhysicsPipelineConfig, "bodyBudget" | "colliders" | "engine" | "kernel" | "observation" | "sediment">> & {
+        kernel: Required<PhysicsKernelOptions>;
+    };
+    elapsedSeconds: number;
+    paused: boolean;
+    queue: PhysicsPipelineQueuedSpawnSnapshot[];
+    revision: number;
+    sediment: PhysicsSedimentBinSnapshot[];
+    simulationState: PhysicsSimulationState;
+    liveBodyOrder: string[];
+    visible: boolean;
+    world: PhysicsKernelSnapshot;
+}
+export interface PhysicsPipelineControlSurface {
+    applyImpulse: (id: string, ix: number, iy: number) => void;
+    clear: () => void;
+    hitTest: (x: number, y: number, radius?: number) => PhysicsBodyState | null;
+    pause: () => void;
+    push: (spawn: PhysicsQueuedSpawn, pacing?: PhysicsSpawnPacingOptions) => void;
+    pushMany: (spawns: PhysicsQueuedSpawn[], pacing?: PhysicsSpawnPacingOptions) => void;
+    readBodies: (out?: PhysicsBodyState[]) => PhysicsBodyState[];
+    readSediment: () => PhysicsSedimentBinSnapshot[];
+    bodyBudgetStatus: () => PhysicsBodyBudgetDecision;
+    recordObservation: (event: PhysicsObservationRecord) => PhysicsObservationEvent;
+    remove: (ids: string[]) => string[];
+    restore: (snapshot: PhysicsPipelineSnapshot) => void;
+    resume: () => void;
+    settle: (maxSteps?: number) => number;
+    settleWithObservations: (maxSteps?: number) => PhysicsPipelineTickResult;
+    snapshot: () => PhysicsPipelineSnapshot;
+    sedimentHeightfield: (options?: PhysicsSedimentHeightfieldOptions) => PhysicsSedimentColumn[];
+    sedimentTotals: () => PhysicsSedimentTotals;
+    step: (deltaSeconds: number) => PhysicsPipelineTickResult;
+}

package/dist/components/stream/physics/PhysicsSVGOverlay.d.ts

@@ -0,0 +1,78 @@
+/**
+ * SVG chrome layer for StreamPhysicsFrame — title, legend, and annotations.
+ * Mirrors NetworkSVGOverlay: no axes/grid (physics is pixel-space), but
+ * honors the same annotation + auto-place + legend contracts as other frames.
+ */
+import type { Datum } from "../../charts/shared/datumTypes";
+import * as React from "react";
+import type { ReactNode } from "react";
+import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../../types/legendTypes";
+import { type AutoPlaceAnnotations } from "../../recipes/annotationLayout";
+import type { AnnotationContext } from "../../realtime/types";
+import type { PhysicsBodyState } from "./PhysicsKernel";
+import type { OnObservationCallback } from "../../store/ObservationStore";
+import { type OnAnnotationActivateCallback } from "../../charts/shared/annotationActivation";
+export type PhysicsAnnotationAnchorNode = {
+    pointId?: string;
+    x: number;
+    y: number;
+    r: number;
+};
+export declare function bodiesToAnnotationAnchors(bodies: readonly PhysicsBodyState[]): PhysicsAnnotationAnchorNode[];
+export interface PhysicsSVGOverlayProps {
+    width: number;
+    height: number;
+    totalWidth: number;
+    totalHeight: number;
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    title?: string | ReactNode;
+    legend?: ReactNode | {
+        legendGroups: LegendGroup[];
+    } | {
+        gradient: GradientLegendConfig;
+    };
+    legendHoverBehavior?: (item: {
+        label: string;
+    } | null) => void;
+    legendClickBehavior?: (item: {
+        label: string;
+    }) => void;
+    legendHighlightedCategory?: string | null;
+    legendIsolatedCategories?: Set<string>;
+    legendPosition?: "right" | "left" | "top" | "bottom";
+    legendLayout?: LegendLayout;
+    /** Live body anchors for pointId / bodyId annotations. */
+    pointNodes?: PhysicsAnnotationAnchorNode[];
+    annotations?: Datum[];
+    onAnnotationActivate?: OnAnnotationActivateCallback;
+    onObservation?: OnObservationCallback;
+    chartId?: string;
+    chartType?: string;
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
+    svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
+    /** Optional foreground SVG already composed into the frame stack. */
+    children?: ReactNode;
+}
+/**
+ * Pixel-space annotation context: identity scales so raw `x`/`y` on notes
+ * read as canvas coordinates (physics has no data→pixel scale).
+ */
+export declare function buildPhysicsAnnotationContext(options: {
+    width: number;
+    height: number;
+    pointNodes?: PhysicsAnnotationAnchorNode[];
+    data?: Datum[];
+}): AnnotationContext;
+/**
+ * Normalize common physics annotation aliases onto Semiotic annotation shapes.
+ * - `bodyId` → `pointId` (anchor to a live body)
+ * - physics barrier/sensor notes still paint as x/y-threshold when typed that way
+ */
+export declare function normalizePhysicsAnnotations(annotations: Datum[] | undefined): Datum[] | undefined;
+export declare function PhysicsSVGOverlay(props: PhysicsSVGOverlayProps): React.JSX.Element;
+export default PhysicsSVGOverlay;

package/dist/components/stream/physics/PhysicsSediment.d.ts

@@ -0,0 +1,69 @@
+import type { PhysicsBodyState } from "./PhysicsKernel";
+export type PhysicsSedimentAccessor = string | ((body: PhysicsBodyState, index: number) => unknown);
+export type PhysicsSedimentValueAccessor = number | string | ((body: PhysicsBodyState, index: number) => unknown);
+export interface RunningStatsSnapshot {
+    count: number;
+    total: number;
+    mean: number;
+    min: number;
+    max: number;
+    variance: number;
+}
+export interface PhysicsSedimentConfig {
+    binAccessor?: PhysicsSedimentAccessor;
+    labelAccessor?: PhysicsSedimentAccessor;
+    valueAccessor?: PhysicsSedimentValueAccessor;
+    retainBodyIds?: number;
+}
+export interface PhysicsSedimentBinSnapshot {
+    id: string;
+    label: string;
+    count: number;
+    total: number;
+    bodyIds: string[];
+    lastBodyId?: string;
+    lastDatum?: unknown;
+    x: RunningStatsSnapshot;
+    y: RunningStatsSnapshot;
+    value: RunningStatsSnapshot;
+}
+export interface PhysicsSedimentTotals {
+    bins: number;
+    count: number;
+    total: number;
+}
+export interface PhysicsSedimentHeightfieldOptions {
+    baselineY?: number;
+    binWidth?: number;
+    gap?: number;
+    maxHeight?: number;
+    value?: "count" | "total";
+    x?: (bin: PhysicsSedimentBinSnapshot, index: number) => number;
+}
+export interface PhysicsSedimentColumn {
+    binId: string;
+    label: string;
+    index: number;
+    count: number;
+    total: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    meanX: number;
+    meanY: number;
+}
+export declare class PhysicsSedimentAccumulator {
+    private bins;
+    private config;
+    private nextIndex;
+    constructor(config?: PhysicsSedimentConfig | false);
+    updateConfig(config: PhysicsSedimentConfig | false | undefined): void;
+    isEnabled(): boolean;
+    add(body: PhysicsBodyState): PhysicsSedimentBinSnapshot | null;
+    clear(): void;
+    snapshot(): PhysicsSedimentBinSnapshot[];
+    restore(snapshot?: PhysicsSedimentBinSnapshot[]): void;
+    totals(): PhysicsSedimentTotals;
+}
+export declare function sedimentHeightfield(bins: PhysicsSedimentBinSnapshot[], options?: PhysicsSedimentHeightfieldOptions): PhysicsSedimentColumn[];

package/dist/components/stream/physics/PhysicsSettledSVG.d.ts

@@ -0,0 +1,18 @@
+import type { PhysicsSettledEvidence } from "./PhysicsEvidence";
+import type { PhysicsPipelineStore } from "./PhysicsPipelineStore";
+import { type PhysicsSettledScene, type PhysicsSettledSceneOptions } from "./PhysicsSettledScene";
+export interface PhysicsSettledSVGOptions extends PhysicsSettledSceneOptions {
+    width?: number;
+    height?: number;
+    title?: string;
+    description?: string;
+    background?: string;
+    className?: string;
+    idPrefix?: string;
+}
+export interface PhysicsSettledSVGRender {
+    svg: string;
+    scene: PhysicsSettledScene;
+    evidence: PhysicsSettledEvidence;
+}
+export declare function renderPhysicsSettledSVG(store: PhysicsPipelineStore, options?: PhysicsSettledSVGOptions): PhysicsSettledSVGRender;

package/dist/components/stream/physics/PhysicsSettledScene.d.ts

@@ -0,0 +1,21 @@
+import type { SceneNode, Style } from "../types";
+import type { PhysicsSettledProjectionRow } from "./PhysicsAccessibility";
+import { type PhysicsSettledEvidence } from "./PhysicsEvidence";
+import type { PhysicsBodyState } from "./PhysicsKernel";
+import type { PhysicsPipelineSnapshot, PhysicsPipelineStore } from "./PhysicsPipelineStore";
+export interface PhysicsSettledSceneOptions {
+    maxSteps?: number;
+    projectionRows?: PhysicsSettledProjectionRow[];
+    bodyStyle?: Style | ((body: PhysicsBodyState) => Style);
+    getBodyLabel?: (body: PhysicsBodyState) => string | undefined;
+}
+export interface PhysicsSettledScene {
+    snapshot: PhysicsPipelineSnapshot;
+    bodies: PhysicsBodyState[];
+    sceneNodes: SceneNode[];
+    evidence: PhysicsSettledEvidence;
+    stepsRun: number;
+}
+export declare function physicsBodyToXYSceneNode(body: PhysicsBodyState, options?: Pick<PhysicsSettledSceneOptions, "bodyStyle" | "getBodyLabel">): SceneNode;
+export declare function physicsBodiesToXYSceneNodes(bodies: PhysicsBodyState[], options?: Pick<PhysicsSettledSceneOptions, "bodyStyle" | "getBodyLabel">): SceneNode[];
+export declare function buildPhysicsSettledScene(store: PhysicsPipelineStore, options?: PhysicsSettledSceneOptions): PhysicsSettledScene;