semiotic 3.7.5 → 3.8.0

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

@@ -0,0 +1,302 @@
+/**
+ * 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: unknown;
+    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;
+    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[];
+    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?: (datum: unknown | null, event: {
+        x: number;
+        y: number;
+        body: PhysicsBodyState | null;
+    }) => void;
+    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/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;

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

@@ -0,0 +1,41 @@
+/**
+ * Pure physics pipeline helpers: spawn scheduling, colliders, cloning, hit geometry.
+ * Extracted from PhysicsPipelineStore so the store class stays orchestration-only.
+ */
+import { type PhysicsActiveSensorPair, type PhysicsBodyState, type PhysicsColliderSpec, type PhysicsKernelOptions, type PhysicsKernelSnapshot } from "./PhysicsKernel";
+import type { PhysicsBodyBudgetOptions } from "./PhysicsBodyBudget";
+import type { PhysicsBoundsColliderOptions, PhysicsObservationEvent, PhysicsPipelineConfig, PhysicsPipelineObservationOptions, PhysicsPipelineQueuedSpawnSnapshot, PhysicsPlotBounds, PhysicsQueuedSpawn, PhysicsSensorObservationConfig, PhysicsSimulationState, PhysicsSpawnPacingOptions, PhysicsXBinColliderOptions } from "./PhysicsPipelineTypes";
+export type InternalQueuedSpawn = PhysicsPipelineQueuedSpawnSnapshot;
+export declare const DEFAULT_PHYSICS_PIPELINE_CONFIG: Required<Omit<PhysicsPipelineConfig, "bodyBudget" | "colliders" | "engine" | "kernel" | "observation" | "sediment">>;
+export interface NormalizedObservationConfig {
+    chartId: string;
+    chartType: string;
+    sensors: Record<string, PhysicsSensorObservationConfig>;
+    onObservation?: (event: PhysicsObservationEvent) => void;
+    onSimulationStateChange?: (state: PhysicsSimulationState, previousState: PhysicsSimulationState) => void;
+}
+export declare const DEFAULT_OBSERVATION_CONFIG: NormalizedObservationConfig;
+export declare function normalizeObservationConfig(options?: PhysicsPipelineObservationOptions, previous?: NormalizedObservationConfig): NormalizedObservationConfig;
+export declare function cloneSpawn(spawn: PhysicsQueuedSpawn): PhysicsQueuedSpawn;
+export declare function finiteNumber(value: unknown): number | undefined;
+export declare function schedulePhysicsSpawns(spawns: PhysicsQueuedSpawn[], options?: PhysicsSpawnPacingOptions): PhysicsQueuedSpawn[];
+export declare function cloneQueuedSpawn(spawn: InternalQueuedSpawn): InternalQueuedSpawn;
+export declare function cloneColliders(colliders: PhysicsColliderSpec[]): PhysicsColliderSpec[];
+export declare function cloneBodyBudgetOptions(options: false | PhysicsBodyBudgetOptions): false | PhysicsBodyBudgetOptions;
+export declare function sortQueue(a: InternalQueuedSpawn, b: InternalQueuedSpawn): number;
+export declare function requiredKernelOptions(kernel: PhysicsKernelSnapshot["options"]): Required<PhysicsKernelOptions>;
+export declare function bodySearchRadius(body: PhysicsBodyState): number;
+export declare function bodyHitDistanceSquared(body: PhysicsBodyState, x: number, y: number, radius: number): number | null;
+export declare function sensorPairKey(sensorId: string, bodyId: string): string;
+export declare function parseSensorPairKey(key: string): PhysicsActiveSensorPair;
+export type PhysicsQuadtreeLeaf = {
+    data?: PhysicsBodyState;
+    next?: PhysicsQuadtreeLeaf;
+    length?: number;
+};
+export declare function collidersFromPlotBounds(bounds: PhysicsPlotBounds, options?: PhysicsBoundsColliderOptions): PhysicsColliderSpec[];
+export declare function collidersFromXScaleBins(options: PhysicsXBinColliderOptions): PhysicsColliderSpec[];
+export interface PhysicsPipelineEvictionResult {
+    evicted: string[];
+    sedimented: string[];
+}

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

@@ -0,0 +1,14 @@
+import type { PhysicsEngineAdapter } from "./PhysicsEngineAdapter";
+import type { PhysicsKernelEvent } from "./PhysicsKernel";
+import type { PhysicsObservationEvent, PhysicsSimulationState } from "./PhysicsPipelineTypes";
+import { type NormalizedObservationConfig } from "./physicsPipelineHelpers";
+export interface PhysicsObservationContext {
+    elapsedSeconds: number;
+    observation: NormalizedObservationConfig;
+    emit: (event: PhysicsObservationEvent) => void;
+}
+export declare function observePhysicsKernelEvents(world: PhysicsEngineAdapter, events: PhysicsKernelEvent[], context: PhysicsObservationContext): void;
+export declare function observePhysicsSensorTransitions(world: PhysicsEngineAdapter, previousPairs: ReadonlySet<string>, context: PhysicsObservationContext): Set<string>;
+export declare function removePhysicsSensorPairsForBodies(pairs: Set<string>, bodyIds: ReadonlySet<string>): void;
+export declare function resolvePhysicsSimulationState(paused: boolean, visible: boolean, hasQueuedBodies: boolean, allSleeping: boolean): PhysicsSimulationState;
+export declare function emitPhysicsSimulationStateTransition(previous: PhysicsSimulationState, next: PhysicsSimulationState, context: PhysicsObservationContext): void;

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

@@ -0,0 +1,9 @@
+import type { PhysicsKernelOptions } from "./PhysicsKernel";
+import type { PhysicsPipelineConfig } from "./PhysicsPipelineTypes";
+import type { Invalidation } from "../pipelineUpdateContract";
+export declare const PHYSICS_BODY_INVALIDATIONS: readonly Invalidation[];
+export declare const PHYSICS_MOTION_INVALIDATIONS: readonly Invalidation[];
+export declare const PHYSICS_CONFIG_INVALIDATIONS: readonly Invalidation[];
+export declare const PHYSICS_STATE_INVALIDATIONS: readonly Invalidation[];
+export declare function physicsKernelOptionsEqual(a: PhysicsKernelOptions | undefined, b: PhysicsKernelOptions | undefined): boolean;
+export declare function changedPhysicsConfigKeys(config: PhysicsPipelineConfig, previous: PhysicsPipelineConfig): string[];

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

@@ -0,0 +1,54 @@
+/**
+ * Region effect application, body forces, and post-tick pipeline for
+ * StreamPhysicsFrame. Pure control-surface helpers — no React.
+ */
+import type { Style } from "../types";
+import type { PhysicsBodyState, PhysicsColliderSpec } from "./PhysicsKernel";
+import type { PhysicsPipelineControlSurface, PhysicsPipelineStore, PhysicsPipelineTickResult, PhysicsSimulationState } from "./PhysicsPipelineStore";
+import { composePhysicsControllers } from "./PhysicsControllers";
+import type { PhysicsBodySelection, StreamPhysicsBodyForce, StreamPhysicsBodyForceContext, StreamPhysicsBodyRegionState, StreamPhysicsRegionEffect, StreamPhysicsRegionEffectContext, StreamPhysicsRegionVector, PhysicsSemanticItem, StreamPhysicsFrameProps } from "./StreamPhysicsTypes";
+/** Internal region bookkeeping (Sets for O(1) membership). */
+export interface InternalStreamPhysicsBodyRegionState {
+    activeRegionIds: Set<string>;
+    regionIds: Set<string>;
+    charges: Record<string, unknown>;
+    attributes: Record<string, unknown>;
+    energy: number;
+}
+export declare function isSelected(body: PhysicsBodyState, selection: PhysicsBodySelection | null | undefined): boolean;
+export declare function regionSensorId(region: StreamPhysicsRegionEffect): string;
+export declare function regionBoundaryColliders(region: StreamPhysicsRegionEffect): PhysicsColliderSpec[];
+export declare function publicRegionState(state: InternalStreamPhysicsBodyRegionState | undefined): StreamPhysicsBodyRegionState | undefined;
+export declare function cloneRegionStateSnapshot(state: Map<string, InternalStreamPhysicsBodyRegionState>): Record<string, StreamPhysicsBodyRegionState>;
+export declare function ensureInternalRegionState(state: Map<string, InternalStreamPhysicsBodyRegionState>, bodyId: string): InternalStreamPhysicsBodyRegionState;
+export declare function resolveRegionVector(vector: StreamPhysicsRegionVector | ((context: StreamPhysicsRegionEffectContext) => StreamPhysicsRegionVector | null | undefined) | undefined, context: StreamPhysicsRegionEffectContext): StreamPhysicsRegionVector | null;
+export declare function mergeRegionAttributes(region: StreamPhysicsRegionEffect, context: StreamPhysicsRegionEffectContext, state: InternalStreamPhysicsBodyRegionState): void;
+export declare function resolveRegionCharge(region: StreamPhysicsRegionEffect, context: StreamPhysicsRegionEffectContext): unknown;
+export declare function regionToSemanticItem(region: StreamPhysicsRegionEffect): PhysicsSemanticItem | null;
+export declare function regionRuntimeEffectsRequireSync(regionEffects: readonly StreamPhysicsRegionEffect[]): boolean;
+export declare function applyActiveRegionEffects(controls: PhysicsPipelineControlSurface, regionEffects: readonly StreamPhysicsRegionEffect[], regionState: Map<string, InternalStreamPhysicsBodyRegionState>, dtSeconds: number): boolean;
+export declare function resolveBodyForceVector(force: StreamPhysicsBodyForce | undefined, context: StreamPhysicsBodyForceContext): StreamPhysicsRegionVector | null;
+export declare function applyBodyForces(controls: PhysicsPipelineControlSurface, bodyForces: StreamPhysicsBodyForce | undefined, regionEffects: readonly StreamPhysicsRegionEffect[], regionState: Map<string, InternalStreamPhysicsBodyRegionState>, simulationState: PhysicsSimulationState, dtSeconds: number): boolean;
+/**
+ * Shared post-tick pipeline: region forces → body forces → controllers → onTick.
+ * Used by the main RAF path and the worker-fallback path (DRY + one snapshot).
+ */
+export declare function runPhysicsPostTick(options: {
+    store: PhysicsPipelineStore;
+    result: PhysicsPipelineTickResult;
+    regionEffects: readonly StreamPhysicsRegionEffect[];
+    regionState: Map<string, InternalStreamPhysicsBodyRegionState>;
+    bodyForces: StreamPhysicsBodyForce | undefined;
+    composed: ReturnType<typeof composePhysicsControllers>;
+    onTick?: (result: PhysicsPipelineTickResult, controls: PhysicsPipelineControlSurface) => void;
+}): {
+    regionEffectsApplied: boolean;
+    bodyForcesApplied: boolean;
+    snapshot: ReturnType<PhysicsPipelineStore["snapshot"]>;
+};
+export declare function resolveStyle(body: PhysicsBodyState, simulationState: PhysicsSimulationState, bodyStyle: StreamPhysicsFrameProps["bodyStyle"], selectedBodyStyle: StreamPhysicsFrameProps["selectedBodyStyle"], selection: StreamPhysicsFrameProps["selection"], regionState: StreamPhysicsBodyRegionState | undefined, activeRegions: StreamPhysicsRegionEffect[], fallbackFill: string, fallbackStroke: string, primitives?: {
+    color?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+}): Style;

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

@@ -0,0 +1,20 @@
+/**
+ * Physics frame semantic items, default tooltip, and accessible data table.
+ */
+import * as React from "react";
+import type { PhysicsBodyState } from "./PhysicsKernel";
+import type { PhysicsSimulationState } from "./PhysicsPipelineStore";
+import type { PhysicsHoverData, PhysicsSemanticItem, StreamPhysicsFrameProps } from "./StreamPhysicsTypes";
+export declare const SR_ONLY_STYLE: React.CSSProperties;
+declare function physicsHoverData(body: PhysicsBodyState): PhysicsHoverData;
+declare function createBodySemanticItems(bodies: readonly PhysicsBodyState[], simulationState: PhysicsSimulationState, bodySemanticItems: StreamPhysicsFrameProps["bodySemanticItems"], limit: number): PhysicsSemanticItem[];
+declare function semanticItemsChanged(previous: readonly PhysicsSemanticItem[], next: readonly PhysicsSemanticItem[]): boolean;
+declare function DefaultPhysicsTooltip({ hover }: {
+    hover: PhysicsHoverData;
+}): React.ReactElement;
+declare function PhysicsSemanticDataTable(props: {
+    chartTitle?: string;
+    items: readonly PhysicsSemanticItem[];
+    tableId: string;
+}): React.ReactElement;
+export { physicsHoverData, createBodySemanticItems, semanticItemsChanged, DefaultPhysicsTooltip, PhysicsSemanticDataTable };

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

@@ -0,0 +1,16 @@
+import { type MutableRefObject, type RefObject } from "react";
+import type { PhysicsPipelineStore } from "./PhysicsPipelineStore";
+import type { PhysicsWorkerCommand } from "./PhysicsWorkerProtocol";
+export declare function isPhysicsDocumentVisible(): boolean;
+interface PhysicsFrameLifecyclePolicyInput {
+    cancelRender: () => void;
+    lastFrameTimeRef: MutableRefObject<number | null>;
+    paused: boolean;
+    postWorkerCommand: (command: PhysicsWorkerCommand, notifyTick?: boolean) => void;
+    requestRender: () => void;
+    storeRef: RefObject<PhysicsPipelineStore | null>;
+    suspendWhenHidden: boolean;
+}
+/** Keep pause and page-visibility scheduling policy consistent for physics frames. */
+export declare function usePhysicsFrameLifecyclePolicy({ cancelRender, lastFrameTimeRef, paused, postWorkerCommand, requestRender, storeRef, suspendWhenHidden }: PhysicsFrameLifecyclePolicyInput): void;
+export {};

package/dist/components/stream/pipelineBufferUtils.d.ts

@@ -0,0 +1,26 @@
+import { RingBuffer } from "../realtime/RingBuffer";
+/**
+ * Resize a data buffer and its optional timestamp companion to fit a bounded
+ * replacement dataset. Keeps timestamp/data indices aligned for pulse logic.
+ */
+export declare function ensureRingBufferCapacity<T>(buffer: RingBuffer<T>, targetSize: number, timestampBuffer?: RingBuffer<number> | null): void;
+/**
+ * Create a timestamp companion for data that predates pulse tracking.
+ *
+ * A pulse buffer is indexed in lockstep with the datum buffer. When pulse is
+ * enabled after mount, an empty companion would make the next inserted datum
+ * line up with the *oldest* retained datum. Seed every retained row at the
+ * activation time instead, so the two rings start aligned and the newly
+ * enabled encoding has a coherent first frame.
+ */
+export declare function createTimestampBufferForData<T>(buffer: RingBuffer<T>, timestamp: number): RingBuffer<number>;
+/**
+ * Push a datum and its ingest timestamp in lockstep. Returns any evicted datum
+ * from the data buffer so callers can update extents/categories.
+ */
+export declare function pushWithTimestamp<T>(buffer: RingBuffer<T>, datum: T, timestampBuffer: RingBuffer<number> | null | undefined, timestamp: number): T | undefined;
+/**
+ * Compact a timestamp ring buffer before removing matching rows from the data
+ * ring buffer. The predicate must be the same one passed to `buffer.remove()`.
+ */
+export declare function compactTimestampBufferForRemoval<T>(buffer: RingBuffer<T>, timestampBuffer: RingBuffer<number> | null | undefined, predicate: (item: T) => boolean): void;