semiotic 3.7.5 → 3.8.1

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;

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

@@ -0,0 +1,317 @@
+/**
+ * Public types for StreamPhysicsFrame — region effects, body semantics,
+ * frame props / handle. Kept separate so region runtime + canvas helpers
+ * can import types without pulling the full React frame module.
+ */
+import type * as React from "react";
+import type { FrameGraphicsProp, FrameMargin, FrameScheduler } from "../useFrame";
+import type { Style } from "../types";
+import type { Datum } from "../../charts/shared/datumTypes";
+import type { OnObservationCallback } from "../../store/ObservationStore";
+import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
+import type { AnnotationContext } from "../../realtime/types";
+import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../../types/legendTypes";
+import type { FocusRingProps } from "../FocusRing";
+import type { PhysicsBodyState, PhysicsColliderBodyFilter, PhysicsColliderShape } from "./PhysicsKernel";
+import type { PhysicsPipelineConfig, PhysicsPipelineControlSurface, PhysicsPipelineStore, PhysicsPipelineTickResult, PhysicsQueuedSpawn, PhysicsSpawnPacingOptions, PhysicsSimulationState, PhysicsObservationEvent } from "./PhysicsPipelineStore";
+import type { PhysicsController } from "./PhysicsControllers";
+import type { PhysicsExecution } from "./PhysicsWorkerProtocol";
+import type { StreamPhysicsPopOptions } from "./physicsBodyCanvas";
+export interface PhysicsBodySelection {
+    isActive?: boolean;
+    predicate?: (body: PhysicsBodyState) => boolean;
+}
+export type StreamPhysicsRegionKind = "region" | "membrane" | "charge-gate" | "force-field" | "sink" | "source";
+export interface StreamPhysicsRegionVector {
+    x?: number;
+    y?: number;
+}
+export interface StreamPhysicsBodyRegionState {
+    activeRegionIds: string[];
+    regionIds: string[];
+    charges: Record<string, unknown>;
+    attributes: Record<string, unknown>;
+    energy: number;
+}
+export interface StreamPhysicsRegionEffectContext {
+    body: PhysicsBodyState;
+    region: StreamPhysicsRegionEffect;
+    regionState: StreamPhysicsBodyRegionState;
+}
+export interface StreamPhysicsRegionEvent {
+    type: "region-enter" | "region-exit";
+    bodyId: string;
+    datum?: unknown;
+    observation: PhysicsObservationEvent;
+    region: StreamPhysicsRegionEffect;
+    regionState: StreamPhysicsBodyRegionState;
+}
+export interface StreamPhysicsRegionEffect {
+    /**
+     * Stable region id. This is used for observations, accessibility labels,
+     * body region state, and generated sensor collider ids.
+     */
+    id: string;
+    /**
+     * Visual/semantic intent. The physics behavior is controlled by the other
+     * properties; kind lets charts and agents describe the region correctly.
+     */
+    kind?: StreamPhysicsRegionKind;
+    label?: string;
+    description?: string;
+    shape: PhysicsColliderShape;
+    /**
+     * Add a solid collider with the same shape in addition to the sensor region.
+     * Defaults to false because information membranes normally tax or annotate
+     * bodies without hard-blocking them.
+     */
+    collider?: boolean | "solid" | "boundary";
+    /**
+     * Optional filter applied to generated region sensors and colliders. This is
+     * useful for permeable regions where one body class should observe or collide
+     * with a boundary while other bodies pass through.
+     */
+    bodyFilter?: PhysicsColliderBodyFilter;
+    /**
+     * Segment thickness used when `collider` is `"boundary"` for an AABB region.
+     */
+    colliderThickness?: number;
+    friction?: number;
+    restitution?: number;
+    /**
+     * The generated sensor collider id. Override only when coordinating with
+     * existing observations.
+     */
+    sensorId?: string;
+    binId?: string;
+    /**
+     * State attached to a body when it enters the region. `true` on a
+     * charge-gate means a charge value of 1.
+     */
+    charge?: boolean | number | string | ((context: StreamPhysicsRegionEffectContext) => unknown);
+    energyDelta?: number;
+    attributes?: Record<string, unknown> | ((context: StreamPhysicsRegionEffectContext) => Record<string, unknown>);
+    /**
+     * Continuous force applied while a body is inside the region. This is modeled
+     * as a per-frame impulse and currently runs on the sync execution path.
+     */
+    force?: StreamPhysicsRegionVector | ((context: StreamPhysicsRegionEffectContext) => StreamPhysicsRegionVector | null | undefined);
+    /**
+     * Linear damping applied while a body is inside the region. Values are
+     * per-second-ish coefficients and are intentionally lightweight.
+     */
+    damping?: number;
+    impulseOnEnter?: StreamPhysicsRegionVector | ((context: StreamPhysicsRegionEffectContext) => StreamPhysicsRegionVector | null | undefined);
+    impulseOnExit?: StreamPhysicsRegionVector | ((context: StreamPhysicsRegionEffectContext) => StreamPhysicsRegionVector | null | undefined);
+    bodyStyle?: Style | ((body: PhysicsBodyState, context: PhysicsBodyStyleContext) => Style);
+    /**
+     * Set to false to suppress generated keyboard/accessibility semantics.
+     * Pass a partial item to override the generated label/description/group.
+     */
+    semanticItem?: false | Partial<PhysicsSemanticItem>;
+    metadata?: unknown;
+    onEnter?: (event: StreamPhysicsRegionEvent) => void;
+    onExit?: (event: StreamPhysicsRegionEvent) => void;
+}
+export interface PhysicsBodyStyleContext {
+    selected: boolean;
+    simulationState: PhysicsSimulationState;
+    regionState?: StreamPhysicsBodyRegionState;
+    regions?: StreamPhysicsRegionEffect[];
+}
+export interface StreamPhysicsExecutionState {
+    execution: "sync" | "worker";
+    liveBodies: number;
+    queuedBodies: number;
+    reason?: string;
+    requested: PhysicsExecution;
+}
+export interface PhysicsSemanticItem {
+    bodyId?: string;
+    id?: string;
+    label: string;
+    description?: string;
+    datum?: unknown;
+    x: number;
+    y: number;
+    shape?: FocusRingProps["shape"];
+    width?: number;
+    height?: number;
+    pathData?: string;
+    group?: string;
+}
+export interface PhysicsBodySemanticItemContext {
+    index: number;
+    simulationState: PhysicsSimulationState;
+}
+export type PhysicsBodySemanticItemAccessor = (body: PhysicsBodyState, context: PhysicsBodySemanticItemContext) => false | null | undefined | Partial<PhysicsSemanticItem>;
+export interface StreamPhysicsBodyForceContext {
+    body: PhysicsBodyState;
+    bodies: readonly PhysicsBodyState[];
+    index: number;
+    regionState?: StreamPhysicsBodyRegionState;
+    regions?: StreamPhysicsRegionEffect[];
+    simulationState: PhysicsSimulationState;
+}
+export type StreamPhysicsBodyForce = StreamPhysicsRegionVector | ((context: StreamPhysicsBodyForceContext) => StreamPhysicsRegionVector | null | undefined);
+export interface PhysicsHoverData {
+    __semioticHoverData: true;
+    body: PhysicsBodyState;
+    data: Datum | PhysicsBodyState;
+    id: string;
+    type: "body";
+    x: number;
+    y: number;
+}
+export interface StreamPhysicsFrameProps {
+    accessibleTable?: boolean;
+    /**
+     * Canvas fill. When set, overrides the theme background unless
+     * `backgroundGraphics` already owns the backdrop. Pass `"transparent"`
+     * to composite over siblings (same contract as StreamXYFrame).
+     */
+    background?: string;
+    backgroundGraphics?: FrameGraphicsProp;
+    /**
+     * Optional rAF seam for deterministic frame-loop scheduling in tests.
+     * When omitted, the browser's requestAnimationFrame is used.
+     */
+    frameScheduler?: FrameScheduler;
+    /**
+     * Monotonic milliseconds used for frame deltas, semantic throttling,
+     * pop animations, and frame-originated observation timestamps. Inject a
+     * deterministic clock for replayable tests or evidence capture.
+     */
+    clock?: () => number;
+    /**
+     * Host-level random seam for frame-local visual work. It deliberately does
+     * not replace the physics kernel's deterministic random source.
+     */
+    random?: () => number;
+    /**
+     * Serializable deterministic seed for frame-local work and, when
+     * `config.kernel.seed` is omitted, the built-in physics kernel. An explicit
+     * kernel seed always wins so existing simulation snapshots remain stable.
+     */
+    seed?: number;
+    bodySemanticItemLimit?: number;
+    bodySemanticItems?: boolean | PhysicsBodySemanticItemAccessor;
+    bodySemanticUpdateMs?: number;
+    bodyForces?: StreamPhysicsBodyForce;
+    bodyStyle?: Style | ((body: PhysicsBodyState, context: PhysicsBodyStyleContext) => Style);
+    /** Identifier included on `onObservation` events and pipeline observations. */
+    chartId?: string;
+    className?: string;
+    /**
+     * Uniform fill for bodies when `bodyStyle` does not set `fill`.
+     * Accepts CSS vars (`var(--semiotic-primary)`).
+     */
+    color?: string;
+    config?: PhysicsPipelineConfig;
+    /**
+     * Process plugins that tick with the physics heartbeat (capacity queues,
+     * portals, custom process rules). Prefer controllers over pumping
+     * `layoutConfig` every frame. Controllers with `continuous` keep RAF alive
+     * while they still have work even if the kernel is sleeping.
+     */
+    controllers?: readonly PhysicsController[];
+    /**
+     * Keep the animation loop alive even when the physics store reports no
+     * pending work. Use for frame-local systems that drive motion from `onTick`
+     * or other imperative controls instead of queued spawns/body forces.
+     * Also set automatically when any controller opts into continuous mode.
+     */
+    continuous?: boolean;
+    description?: string;
+    /** Dashboard hierarchy class hook (`stream-physics-frame--emphasis-*`). */
+    emphasis?: "primary" | "secondary";
+    /**
+     * Chart display mode (primary/context/sparkline/mobile). HOCs resolve this
+     * via `useChartMode` and pass it for class hooks + ChartContainer export.
+     */
+    chartMode?: "primary" | "context" | "sparkline" | "mobile";
+    enableHover?: boolean;
+    foregroundGraphics?: FrameGraphicsProp;
+    hoverRadius?: number;
+    initialSpawns?: PhysicsQueuedSpawn[];
+    initialSpawnPacing?: PhysicsSpawnPacingOptions;
+    /**
+     * Semiotic annotations (label/callout/threshold/…). Pixel-space `x`/`y`,
+     * or `pointId`/`bodyId` to track a live body. Notes with
+     * `physics: "barrier"|"sensor"` also feed colliders via PhysicsAnnotations.
+     */
+    annotations?: Datum[];
+    /** Observe activation of widget annotations without replacing widget behavior. */
+    onAnnotationActivate?: import("../../charts/shared/annotationActivation").OnAnnotationActivateCallback;
+    autoPlaceAnnotations?: AutoPlaceAnnotations;
+    svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => React.ReactNode;
+    legend?: React.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;
+    margin?: Partial<FrameMargin>;
+    /**
+     * Structured interaction events (hover / hover-end / click / click-end) —
+     * same contract as XY/ordinal/network frames for AI + coordinated views.
+     */
+    onObservation?: OnObservationCallback;
+    /**
+     * Click on a body (or empty canvas when null). Prefer this over
+     * `onBodyPointerDown` when you only need the Semiotic click contract.
+     */
+    onClick?: {
+        bivarianceHack(datum: Datum | null, event: {
+            x: number;
+            y: number;
+            body: PhysicsBodyState | null;
+        }): void;
+    }["bivarianceHack"];
+    onRegionEvent?: (event: StreamPhysicsRegionEvent) => void;
+    onSimulationExecutionChange?: (state: StreamPhysicsExecutionState) => void;
+    onBodyPointerDown?: (body: PhysicsBodyState | null, event: React.PointerEvent<HTMLCanvasElement>) => void;
+    onBodyHover?: (body: PhysicsBodyState | null, hover: PhysicsHoverData | null) => void;
+    onSemanticItemActivate?: (item: PhysicsSemanticItem) => void;
+    onSemanticItemFocus?: (item: PhysicsSemanticItem | null) => void;
+    onTick?: (result: PhysicsPipelineTickResult, controls: PhysicsPipelineControlSurface) => void;
+    /** Uniform opacity for bodies when `bodyStyle` does not set `opacity`. */
+    opacity?: number;
+    paused?: boolean;
+    responsiveHeight?: boolean;
+    responsiveWidth?: boolean;
+    regionEffects?: StreamPhysicsRegionEffect[];
+    selectedBodyStyle?: Style | ((body: PhysicsBodyState, context: PhysicsBodyStyleContext) => Style);
+    selection?: PhysicsBodySelection | null;
+    semanticItems?: PhysicsSemanticItem[];
+    simulationExecution?: PhysicsExecution;
+    size?: [number, number];
+    /** Uniform stroke for bodies when `bodyStyle` does not set `stroke`. */
+    stroke?: string;
+    strokeWidth?: number;
+    summary?: string;
+    suspendWhenHidden?: boolean;
+    title?: string | React.ReactNode;
+    tooltipContent?: (hover: PhysicsHoverData) => React.ReactNode;
+    workerBodyThreshold?: number;
+    renderBody?: (ctx: CanvasRenderingContext2D, body: PhysicsBodyState, style: Style) => void;
+    beforePaint?: (ctx: CanvasRenderingContext2D, bodies: PhysicsBodyState[]) => void;
+    afterPaint?: (ctx: CanvasRenderingContext2D, bodies: PhysicsBodyState[]) => void;
+}
+export interface StreamPhysicsFrameHandle extends PhysicsPipelineControlSurface {
+    getData: () => PhysicsBodyState[];
+    getRegionState: (bodyId?: string) => StreamPhysicsBodyRegionState | Record<string, StreamPhysicsBodyRegionState> | undefined;
+    clearRegionState: (bodyId?: string) => void;
+    getStore: () => PhysicsPipelineStore;
+    popBodies: (ids: string[], options?: StreamPhysicsPopOptions) => string[];
+}
+export type { StreamPhysicsPopOptions };

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

@@ -0,0 +1,27 @@
+/**
+ * Canvas body drawing + pop animations for StreamPhysicsFrame.
+ * Pure paint helpers — no React / store dependency.
+ */
+import type { Style } from "../types";
+import type { PhysicsBodyState } from "./PhysicsKernel";
+/**
+ * Body mark kinds for process identity without custom renderBody.
+ * Set via bodyStyle.mark or datum.__physicsMark / datum.mark.
+ */
+export type PhysicsBodyMark = "circle" | "halo" | "faceted" | "pill" | "diamond" | "square";
+export interface StreamPhysicsPopOptions {
+    color?: string;
+    durationMs?: number;
+    radius?: number;
+}
+export interface StreamPhysicsPopAnimation {
+    body: PhysicsBodyState;
+    color: string;
+    durationMs: number;
+    radius: number;
+    startedAt: number;
+}
+export declare function resolveBodyMark(body: PhysicsBodyState, style: Style): PhysicsBodyMark;
+export declare function drawBody(ctx: CanvasRenderingContext2D, body: PhysicsBodyState, style: Style): void;
+export declare function physicsBodyRadius(body: PhysicsBodyState): number;
+export declare function drawPopAnimations(ctx: CanvasRenderingContext2D, animations: Map<string, StreamPhysicsPopAnimation>, now: number): boolean;

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

@@ -0,0 +1,19 @@
+import type { ObservationInputType, OnObservationCallback } from "../../store/ObservationStore";
+interface CurrentRef<T> {
+    current: T;
+}
+export type PhysicsFrameObservationType = "hover" | "hover-end" | "click" | "click-end" | "focus" | "activate";
+export interface PhysicsFrameObservationPayload {
+    datum?: unknown;
+    x?: number;
+    y?: number;
+    inputType?: ObservationInputType;
+}
+interface PhysicsFrameObservationOptions {
+    onObservationRef: CurrentRef<OnObservationCallback | undefined>;
+    chartIdRef: CurrentRef<string | undefined>;
+    wallClockRef: CurrentRef<() => number>;
+}
+/** Builds a stable emitter while reading the frame's latest callback and clock refs. */
+export declare function usePhysicsFrameObservationEmitter({ onObservationRef, chartIdRef, wallClockRef }: PhysicsFrameObservationOptions): (type: PhysicsFrameObservationType, payload?: PhysicsFrameObservationPayload) => void;
+export {};

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

@@ -0,0 +1,4 @@
+import { PhysicsPipelineStore, type PhysicsPipelineConfig, type PhysicsQueuedSpawn, type PhysicsSpawnPacingOptions } from "./PhysicsPipelineStore";
+/** Create the retained simulation store and seed its initial queued bodies. */
+export declare function createPhysicsFrameStore(config: PhysicsPipelineConfig | undefined, initialSpawns: PhysicsQueuedSpawn[] | undefined, initialSpawnPacing: PhysicsSpawnPacingOptions | undefined): PhysicsPipelineStore;
+export declare function defaultPhysicsFrameClock(): number;

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

@@ -0,0 +1,4 @@
+import type { PhysicsPipelineStore } from "./PhysicsPipelineStore";
+import type { PhysicsPipelineControlSurface } from "./PhysicsPipelineTypes";
+/** Project the store's public methods into the stable imperative control API. */
+export declare function createPhysicsPipelineControls(store: PhysicsPipelineStore): PhysicsPipelineControlSurface;