semiotic 3.7.5 → 3.8.0

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,72 @@
+/**
+ * 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";
+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[];
+    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;

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

@@ -0,0 +1,24 @@
+import type { PhysicsPipelineConfig, PhysicsPipelineSnapshot, PhysicsQueuedSpawn, PhysicsSpawnPacingOptions } from "./PhysicsPipelineStore";
+import { type PhysicsWorkerCommand, type PhysicsWorkerFrame, type PhysicsWorkerResponsePayload } from "./PhysicsWorkerProtocol";
+export declare function canUsePhysicsWorker(): boolean;
+export declare function createPhysicsWorker(): Worker;
+export declare class PhysicsWorkerSession {
+    private nextRequestId;
+    private pending;
+    private worker;
+    constructor(worker?: Worker);
+    request(command: PhysicsWorkerCommand, signal?: AbortSignal): Promise<PhysicsWorkerResponsePayload>;
+    init(config?: PhysicsPipelineConfig, initialSpawns?: PhysicsQueuedSpawn[], initialSpawnPacing?: PhysicsSpawnPacingOptions, signal?: AbortSignal): Promise<PhysicsWorkerFrame>;
+    restore(snapshot: PhysicsPipelineSnapshot, signal?: AbortSignal): Promise<PhysicsWorkerFrame>;
+    initFromSnapshot(config: PhysicsPipelineConfig | undefined, snapshot: PhysicsPipelineSnapshot, signal?: AbortSignal): Promise<PhysicsWorkerFrame>;
+    enqueue(spawns: PhysicsQueuedSpawn[], pacing?: PhysicsSpawnPacingOptions, signal?: AbortSignal): Promise<PhysicsWorkerFrame>;
+    tick(deltaSeconds: number, signal?: AbortSignal): Promise<PhysicsWorkerFrame>;
+    settle(maxSteps?: number, signal?: AbortSignal): Promise<PhysicsWorkerFrame>;
+    snapshot(signal?: AbortSignal): Promise<PhysicsPipelineSnapshot>;
+    remove(ids: string[], signal?: AbortSignal): Promise<{
+        frame: PhysicsWorkerFrame;
+        removed: string[];
+    }>;
+    terminate(): void;
+    private rejectAll;
+}

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

@@ -0,0 +1,101 @@
+import type { PhysicsBodyState } from "./PhysicsKernel";
+import type { PhysicsPipelineConfig, PhysicsPipelineObservationOptions, PhysicsPipelineSnapshot, PhysicsPipelineTickResult, PhysicsQueuedSpawn, PhysicsSpawnPacingOptions } from "./PhysicsPipelineStore";
+import type { PhysicsSedimentBinSnapshot } from "./PhysicsSediment";
+export type PhysicsExecution = "auto" | "worker" | "sync";
+export declare const DEFAULT_PHYSICS_WORKER_BODY_THRESHOLD = 2500;
+export type PhysicsWorkerObservationOptions = Omit<PhysicsPipelineObservationOptions, "onObservation" | "onSimulationStateChange">;
+export type PhysicsWorkerSedimentConfig = false | {
+    binAccessor?: string;
+    labelAccessor?: string;
+    valueAccessor?: number | string;
+    retainBodyIds?: number;
+};
+export type PhysicsWorkerPipelineConfig = Omit<PhysicsPipelineConfig, "engine" | "observation" | "sediment"> & {
+    observation?: PhysicsWorkerObservationOptions;
+    sediment?: PhysicsWorkerSedimentConfig;
+};
+export interface PhysicsWorkerFrame {
+    bodies: PhysicsBodyState[];
+    ids: string[];
+    positions: Float32Array;
+    result: PhysicsPipelineTickResult;
+    sediment: PhysicsSedimentBinSnapshot[];
+    sleeping: Uint8Array;
+    snapshot?: PhysicsPipelineSnapshot;
+    velocities: Float32Array;
+}
+export type PhysicsWorkerCommand = {
+    type: "init";
+    config?: PhysicsWorkerPipelineConfig;
+    initialSpawns?: PhysicsQueuedSpawn[];
+    initialSpawnPacing?: PhysicsSpawnPacingOptions;
+    snapshot?: PhysicsPipelineSnapshot;
+} | {
+    type: "configure";
+    config: PhysicsWorkerPipelineConfig;
+} | {
+    type: "enqueue";
+    spawns: PhysicsQueuedSpawn[];
+    pacing?: PhysicsSpawnPacingOptions;
+} | {
+    type: "tick";
+    deltaSeconds: number;
+} | {
+    type: "settle";
+    maxSteps?: number;
+} | {
+    type: "snapshot";
+} | {
+    type: "restore";
+    snapshot: PhysicsPipelineSnapshot;
+} | {
+    type: "clear";
+} | {
+    type: "remove";
+    ids: string[];
+} | {
+    type: "applyImpulse";
+    id: string;
+    ix: number;
+    iy: number;
+} | {
+    type: "setPaused";
+    paused: boolean;
+} | {
+    type: "setVisible";
+    visible: boolean;
+};
+export interface PhysicsWorkerRequest {
+    command: PhysicsWorkerCommand;
+    requestId: number;
+}
+export type PhysicsWorkerResponsePayload = {
+    type: "frame";
+    frame: PhysicsWorkerFrame;
+} | {
+    type: "removed";
+    frame: PhysicsWorkerFrame;
+    removed: string[];
+} | {
+    type: "snapshot";
+    snapshot: PhysicsPipelineSnapshot;
+};
+export type PhysicsWorkerResponse = {
+    ok: true;
+    payload: PhysicsWorkerResponsePayload;
+    requestId: number;
+} | {
+    error: {
+        message: string;
+        name?: string;
+        stack?: string;
+    };
+    ok: false;
+    requestId: number;
+};
+export declare function isPhysicsWorkerConfigSupported(config: PhysicsPipelineConfig | undefined): boolean;
+export declare function isPhysicsWorkerPacingSupported(pacing: PhysicsSpawnPacingOptions | undefined): boolean;
+export declare function createPhysicsWorkerConfig(config?: PhysicsPipelineConfig | undefined): PhysicsWorkerPipelineConfig;
+export declare function shouldUsePhysicsWorker(execution: PhysicsExecution, liveBodies: number, queuedBodies?: number, threshold?: number): boolean;
+export declare function packPhysicsWorkerFrame(result: PhysicsPipelineTickResult, bodies: PhysicsBodyState[], sediment?: PhysicsSedimentBinSnapshot[], snapshot?: PhysicsPipelineSnapshot): PhysicsWorkerFrame;
+export declare function physicsWorkerFrameTransferables(frame: PhysicsWorkerFrame): Transferable[];

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

@@ -0,0 +1,5 @@
+import { type PhysicsWorkerCommand, type PhysicsWorkerResponsePayload } from "./PhysicsWorkerProtocol";
+export interface PhysicsWorkerRuntime {
+    handle: (command: PhysicsWorkerCommand) => PhysicsWorkerResponsePayload;
+}
+export declare function createPhysicsWorkerRuntime(): PhysicsWorkerRuntime;

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

@@ -0,0 +1,18 @@
+import type { PhysicsEngineCapabilities } from "./PhysicsEngineAdapter";
+export declare const RAPIER_PHYSICS_PACKAGE = "@dimforge/rapier2d-compat";
+export declare const RAPIER_PHYSICS_IMPORT_PATH = "semiotic/physics/rapier";
+export declare const RAPIER_PHYSICS_ENGINE_DECISION: {
+    readonly selectedPackage: "@dimforge/rapier2d-compat";
+    readonly rejectedPackage: "@dimforge/rapier2d-deterministic";
+    readonly determinism: "tolerance";
+    readonly reason: "Use @dimforge/rapier2d-compat for the optional browser adapter path because it is the maintained npm/WASM package with standard bundler behavior. Treat Rapier visual/position conformance as tolerance-classed; keep the built-in kernel as the strict deterministic default.";
+};
+export declare const RAPIER_PHYSICS_CAPABILITIES: PhysicsEngineCapabilities;
+export declare const RAPIER_PHYSICS_INSTALL: {
+    readonly engine: "Rapier 2D";
+    readonly importPath: "semiotic/physics/rapier";
+    readonly packageName: "@dimforge/rapier2d-compat";
+    readonly installCommand: "npm install @dimforge/rapier2d-compat";
+};
+export declare function loadRapierPhysicsPeer(): Promise<unknown>;
+export declare function rapierPhysicsDependencyError(cause?: unknown): Error;

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

@@ -0,0 +1,27 @@
+import type { PhysicsController } from "./PhysicsControllers";
+import type { DependencyGateOptions, DependencyGateSnapshot, ServiceLevelCaseInfo, ServiceLevelControllerOptions, ServiceLevelSnapshot, ServiceResourceAssignment, ServiceResourcePoolOptions, ServiceResourcePoolSnapshot } from "./ServiceOperationsTypes";
+export interface ServiceResourcePoolController extends PhysicsController {
+    assign: (caseBodyId: string) => ServiceResourceAssignment | null;
+    release: (caseBodyId: string) => boolean;
+    getAssignment: (caseBodyId: string) => ServiceResourceAssignment | undefined;
+    getSnapshot: () => ServiceResourcePoolSnapshot;
+}
+/**
+ * Models finite, visible service resources. Assignment is intentionally
+ * explicit so domain controllers decide scheduling while this controller
+ * supplies physical tethers, return-to-home force, and resource evidence.
+ */
+export declare function createServiceResourcePoolController(options: ServiceResourcePoolOptions): ServiceResourcePoolController;
+export interface ServiceLevelController extends PhysicsController {
+    protect: (bodyId: string) => boolean;
+    complete: (bodyId: string) => boolean;
+    getCase: (bodyId: string) => ServiceLevelCaseInfo | undefined;
+    getSnapshot: () => ServiceLevelSnapshot;
+}
+/** Tracks service-level outcomes independently from the force simulation. */
+export declare function createServiceLevelController(options: ServiceLevelControllerOptions): ServiceLevelController;
+export interface DependencyGateController extends PhysicsController {
+    getSnapshot: () => DependencyGateSnapshot;
+}
+/** Holds dependency-bound work until an external condition or scheduled recovery opens. */
+export declare function createDependencyGateController(options: DependencyGateOptions): DependencyGateController;

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

@@ -0,0 +1,89 @@
+import type { PhysicsBodyState, PhysicsColliderBodyFilter } from "./PhysicsKernel";
+import type { StreamPhysicsRegionVector } from "./StreamPhysicsFrame";
+export type ServiceLevelCaseState = "waiting" | "protected" | "unhappy" | "resolved" | "resolved-unhappy";
+export interface ServiceResourceDefinition {
+    id: string;
+    /** Defaults to `id`; use this when the visual body has a different id. */
+    bodyId?: string;
+    /** Resting point used while the resource is unassigned. */
+    home: {
+        x: number;
+        y: number;
+    };
+}
+export interface ServiceResourceAssignment {
+    resourceId: string;
+    resourceBodyId: string;
+    caseBodyId: string;
+    assignedAt: number;
+}
+export interface ServiceResourcePoolSnapshot {
+    total: number;
+    available: number;
+    assigned: number;
+    assignments: ServiceResourceAssignment[];
+    simulatedAt: number;
+    metricRevision: number;
+}
+export interface ServiceResourcePoolOptions {
+    id?: string;
+    resources: readonly ServiceResourceDefinition[];
+    /** Pulls an assigned resource toward its case (default 0.45). */
+    assignmentForce?: number;
+    /** Place an assigned resource ahead of its case to express directional service. */
+    assignmentOffset?: StreamPhysicsRegionVector;
+    /** Returns an idle resource to its home point (default 0.35). */
+    returnForce?: number;
+    /** Small reciprocal force that makes an assignment readable as a tether. */
+    caseAttraction?: number;
+}
+export interface ServiceLevelCaseInfo {
+    bodyId: string;
+    openedAt: number;
+    deadlineAt: number;
+    state: ServiceLevelCaseState;
+    completedAt?: number;
+    protectedAt?: number;
+}
+export interface ServiceLevelSnapshot {
+    total: number;
+    waiting: number;
+    protected: number;
+    unhappy: number;
+    resolved: number;
+    resolvedUnhappy: number;
+    simulatedAt: number;
+    metricRevision: number;
+}
+export interface ServiceLevelControllerOptions {
+    id?: string;
+    /** Only matching bodies become service cases. */
+    bodyFilter?: PhysicsColliderBodyFilter;
+    /** String form reads `body.datum[field]`; values are simulated seconds. */
+    deadlineAccessor: string | ((body: PhysicsBodyState) => number | null | undefined);
+    /** Entering this region marks a case complete. Completion may also be explicit. */
+    completionRegionId?: string;
+    onStateChange?: (caseInfo: ServiceLevelCaseInfo) => void;
+}
+export interface DependencyGateSnapshot {
+    regionId: string;
+    isOpen: boolean;
+    blocked: number;
+    released: number;
+    simulatedAt: number;
+    metricRevision: number;
+}
+export interface DependencyGateOptions {
+    id?: string;
+    regionId: string;
+    bodyFilter?: PhysicsColliderBodyFilter;
+    /** Defaults to closed until `opensAt`; provide `isOpen` for live external state. */
+    opensAt?: number;
+    isOpen?: (simulatedAt: number) => boolean;
+    /** Pull strength toward the closed gate's center (default 0.4). */
+    holdForce?: number;
+    /** Applied once to every held body as the gate opens. */
+    releaseImpulse?: StreamPhysicsRegionVector;
+    onHeld?: (body: PhysicsBodyState) => void;
+    onReleased?: (body: PhysicsBodyState) => void;
+}

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

@@ -0,0 +1,6 @@
+import * as React from "react";
+import type { StreamPhysicsFrameHandle, StreamPhysicsFrameProps } from "./StreamPhysicsTypes";
+export type { PhysicsBodyMark, StreamPhysicsPopOptions } from "./physicsBodyCanvas";
+export type { PhysicsBodySelection, PhysicsBodySemanticItemAccessor, PhysicsBodySemanticItemContext, PhysicsBodyStyleContext, PhysicsHoverData, PhysicsSemanticItem, StreamPhysicsBodyForce, StreamPhysicsBodyForceContext, StreamPhysicsBodyRegionState, StreamPhysicsExecutionState, StreamPhysicsFrameHandle, StreamPhysicsFrameProps, StreamPhysicsRegionEffect, StreamPhysicsRegionEffectContext, StreamPhysicsRegionEvent, StreamPhysicsRegionKind, StreamPhysicsRegionVector } from "./StreamPhysicsTypes";
+export declare const StreamPhysicsFrame: React.NamedExoticComponent<StreamPhysicsFrameProps & React.RefAttributes<StreamPhysicsFrameHandle>>;
+export default StreamPhysicsFrame;