semiotic 3.7.5 → 3.8.0

package/dist/components/charts/physics/physicsEncoding.d.ts

@@ -0,0 +1,142 @@
+import type { Datum } from "../shared/datumTypes";
+import type { MotionCoordinateSpace, MotionEncodingAccessor, MotionEncodingConstant, MotionKinematicsEncoding, MotionPlacementEncoding, MotionProcessEncoding, MotionTimeBasis, MotionTimeEncoding, MotionTimeUnit, ResolvedMotionEncodingRow } from "../shared/motionEncoding";
+import type { Style } from "../../stream/types";
+import type { PhysicsBodyShape, PhysicsBodyState } from "../../stream/physics/PhysicsKernel";
+import type { PhysicsQueuedSpawn } from "../../stream/physics/PhysicsPipelineStore";
+import type { PhysicsSemanticItem } from "../../stream/physics/StreamPhysicsFrame";
+import type { PhysicsCustomLayout, PhysicsCustomLayoutContext, PhysicsCustomLayoutResult } from "./PhysicsCustomChart";
+/** Explicit literal wrapper for channels whose values could also be field names. */
+export type PhysicsEncodingConstant<TValue> = MotionEncodingConstant<TValue>;
+/**
+ * A data channel can read a field, calculate a value, or provide an explicit
+ * constant. Constants use a wrapper so string values are never confused with
+ * field names.
+ */
+export type PhysicsEncodingAccessor<TDatum, TValue> = MotionEncodingAccessor<TDatum, TValue>;
+export interface PhysicsAppearanceEncoding<TDatum> {
+    color?: PhysicsEncodingAccessor<TDatum, string>;
+    opacity?: PhysicsEncodingAccessor<TDatum, number>;
+    shape?: PhysicsEncodingAccessor<TDatum, PhysicsBodyShape>;
+    size?: PhysicsEncodingAccessor<TDatum, number>;
+    stroke?: PhysicsEncodingAccessor<TDatum, string>;
+    strokeWidth?: PhysicsEncodingAccessor<TDatum, number>;
+}
+export type PhysicsPlacementEncoding<TDatum> = MotionPlacementEncoding<TDatum>;
+export interface PhysicsTimeEncoding<TDatum> extends MotionTimeEncoding<TDatum> {
+    /** Simulated time at which the body enters the world. */
+    spawnAt?: PhysicsEncodingAccessor<TDatum, number>;
+}
+export type PhysicsKinematicsEncoding<TDatum> = MotionKinematicsEncoding<TDatum>;
+/**
+ * Causal simulation channels. Unlike appearance channels, these values change
+ * behavior and should be paired with visible or settled evidence when they
+ * carry analytical meaning.
+ */
+export interface PhysicsDynamicsEncoding<TDatum> {
+    bodyCollisions?: PhysicsEncodingAccessor<TDatum, boolean>;
+    friction?: PhysicsEncodingAccessor<TDatum, number>;
+    mass?: PhysicsEncodingAccessor<TDatum, number>;
+    restitution?: PhysicsEncodingAccessor<TDatum, number>;
+}
+export type PhysicsProcessEncoding<TDatum> = MotionProcessEncoding<TDatum>;
+export interface PhysicsAccessibleEncoding<TDatum> {
+    description?: PhysicsEncodingAccessor<TDatum, string>;
+    group?: PhysicsEncodingAccessor<TDatum, string>;
+    label?: PhysicsEncodingAccessor<TDatum, string>;
+}
+/**
+ * Grammar-of-graphics bridge for physics-backed charts. Visual channels remain
+ * separate from causal dynamics and from process/evidence channels so motion
+ * does not silently become an unexplained quantitative encoding.
+ */
+export interface PhysicsEncoding<TDatum extends Datum = Datum> {
+    id: PhysicsEncodingAccessor<TDatum, string | number>;
+    appearance?: PhysicsAppearanceEncoding<TDatum>;
+    placement?: PhysicsPlacementEncoding<TDatum>;
+    time?: PhysicsTimeEncoding<TDatum>;
+    kinematics?: PhysicsKinematicsEncoding<TDatum>;
+    dynamics?: PhysicsDynamicsEncoding<TDatum>;
+    process?: PhysicsProcessEncoding<TDatum>;
+    /** Named analytical values retained on resolved rows for projections. */
+    evidence?: Record<string, PhysicsEncodingAccessor<TDatum, unknown>>;
+    accessible?: PhysicsAccessibleEncoding<TDatum>;
+}
+export interface PhysicsEncodingDefaults {
+    color?: string;
+    mass?: number;
+    opacity?: number;
+    shape?: PhysicsBodyShape;
+    size?: number;
+    stroke?: string;
+    strokeWidth?: number;
+    x?: number;
+    y?: number;
+}
+/**
+ * A resolved physics row is a resolved motion row (the shared neutral channels
+ * — kinematics, process, evidence, accessible) plus the physics-only channels:
+ * appearance, causal dynamics, a scaled/required placement, spawn timing, and
+ * the queued body spawn. Physics is literally a superset of motion.
+ */
+export interface ResolvedPhysicsEncodingRow<TDatum extends Datum = Datum> extends Omit<ResolvedMotionEncodingRow<TDatum>, "placement" | "time"> {
+    appearance: {
+        color?: string;
+        opacity?: number;
+        shape: PhysicsBodyShape;
+        size: number;
+        stroke?: string;
+        strokeWidth?: number;
+    };
+    placement: {
+        x: number;
+        y: number;
+        lane?: string | number;
+        space?: MotionCoordinateSpace;
+    };
+    time: {
+        arrival?: number;
+        spawnAt?: number;
+        basis?: MotionTimeBasis;
+        unit?: MotionTimeUnit;
+    };
+    dynamics: {
+        bodyCollisions?: boolean;
+        friction?: number;
+        mass: number;
+        restitution?: number;
+    };
+    spawn: PhysicsQueuedSpawn;
+}
+export interface PhysicsEncodingCompilation<TDatum extends Datum = Datum> {
+    rows: ResolvedPhysicsEncodingRow<TDatum>[];
+    byId: Map<string, ResolvedPhysicsEncodingRow<TDatum>>;
+    spawns: PhysicsQueuedSpawn[];
+    semanticItems: PhysicsSemanticItem[];
+    /**
+     * Per-body style lookup. Always the function form (the compiler resolves one
+     * style per id up front); assignable to `StreamPhysicsFrameProps["bodyStyle"]`.
+     */
+    bodyStyle: (body: PhysicsBodyState) => Style;
+}
+export interface CompilePhysicsEncodingOptions<TDatum extends Datum = Datum> {
+    data: readonly TDatum[];
+    encoding: PhysicsEncoding<TDatum>;
+    defaults?: PhysicsEncodingDefaults;
+    scales?: {
+        x?: (value: number) => number;
+        y?: (value: number) => number;
+    };
+}
+/** Resolve row accessors once into worker-safe body spawns and chart metadata. */
+export declare function compilePhysicsEncoding<TDatum extends Datum = Datum>(options: CompilePhysicsEncodingOptions<TDatum>): PhysicsEncodingCompilation<TDatum>;
+export type PhysicsEncodingLayoutExtension = Omit<PhysicsCustomLayoutResult, "bodies" | "initialSpawns" | "bodyStyle" | "semanticItems"> & {
+    semanticItems?: PhysicsSemanticItem[];
+};
+export interface CreatePhysicsEncodingLayoutOptions<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> {
+    encoding: PhysicsEncoding<TDatum>;
+    defaults?: PhysicsEncodingDefaults;
+    /** Add constraints, regions, controllers, world config, and overlays. */
+    extend?: (context: PhysicsCustomLayoutContext<TDatum, TConfig>, compilation: PhysicsEncodingCompilation<TDatum>) => PhysicsEncodingLayoutExtension | undefined;
+}
+/** Build a PhysicsCustomChart layout from declarative data encodings. */
+export declare function createPhysicsEncodingLayout<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>>(options: CreatePhysicsEncodingLayoutOptions<TDatum, TConfig>): PhysicsCustomLayout<TDatum, TConfig>;

package/dist/components/charts/physics/physicsHocHandle.d.ts

@@ -0,0 +1,53 @@
+import type { Ref, RefObject } from "react";
+import type { Datum } from "../shared/datumTypes";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+import type { StreamPhysicsFrameHandle } from "../../stream/physics/StreamPhysicsFrame";
+import type { StreamPhysicsPopOptions } from "../../stream/physics/physicsBodyCanvas";
+import type { PhysicsQueuedSpawn } from "../../stream/physics/PhysicsPipelineStore";
+/**
+ * The imperative handle every physics HOC exposes: the shared realtime
+ * push/remove/update surface plus the physics-only `popBodies` — a
+ * body-removal "pop" burst (expanding ring + sparks) played by the frame.
+ * The exit-emphasis counterpart to realtime `pulse`; returns the ids of the
+ * bodies actually removed.
+ */
+export interface PhysicsFrameHandle extends RealtimeFrameHandle {
+    popBodies(ids: string[], options?: StreamPhysicsPopOptions): string[];
+}
+export interface PhysicsDatumSpawnResult {
+    datumId: string;
+    spawns: PhysicsQueuedSpawn[];
+}
+export interface UsePhysicsHocHandleOptions {
+    frameRef: RefObject<StreamPhysicsFrameHandle | null>;
+    /**
+     * Turn one user row into one or more physics body spawns. Called for
+     * push / pushMany / update — never for initial static layout (that path
+     * uses the HOC's `initialSpawns`).
+     */
+    spawnDatum: (datum: Datum, index: number) => PhysicsDatumSpawnResult;
+    /**
+     * Optional seed so remove/update work on static initial rows without a
+     * prior push. Map each seed row to its body ids (defaults: single body
+     * whose id equals the datum id).
+     */
+    seedRows?: readonly Datum[];
+    /**
+     * Resolve a stable row id for seed/push tracking. Defaults to
+     * `String(datum.id ?? index)`.
+     */
+    idAccessor?: string | ((datum: Datum, index: number) => string);
+    /**
+     * Resolve body ids for a seed row. Defaults to matching `seedSpawns`
+     * (and unitized `rowId-*` ids), else `[rowId]`.
+     */
+    bodyIdsForSeed?: (datum: Datum, rowId: string, index: number) => string[];
+    /**
+     * Initial layout spawns — used to resolve multi-body seed rows (pile
+     * unitization, physical-flow packets) for remove/update.
+     */
+    seedSpawns?: readonly PhysicsQueuedSpawn[];
+}
+/** Body ids belonging to a seed row (handles unitized `id-0`, `id-1`, …). */
+export declare function bodyIdsForSeedRow(rowId: string, spawns: readonly PhysicsQueuedSpawn[] | undefined): string[];
+export declare function usePhysicsHocHandle(ref: Ref<PhysicsFrameHandle> | undefined, options: UsePhysicsHocHandleOptions): void;

package/dist/components/charts/physics/physicsHocUtils.d.ts

@@ -0,0 +1,128 @@
+import * as React from "react";
+import type { FrameGraphicsProp } from "../../stream/useFrame";
+import type { PhysicsSemanticItem, StreamPhysicsFrameProps } from "../../stream/physics/StreamPhysicsFrame";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps, ChartMode } from "../shared/types";
+import { type ChartModeResult } from "../shared/hooks";
+export type PhysicsHocFrameProps<TOmitted extends keyof StreamPhysicsFrameProps = never> = Partial<Omit<StreamPhysicsFrameProps, "initialSpawns" | "initialSpawnPacing" | "size" | TOmitted>>;
+/**
+ * Chrome / AI / annotation contracts HOCs forward to StreamPhysicsFrame.
+ * Compose with `BaseChartProps` on every physics HOC.
+ */
+export type PhysicsSharedChartProps = {
+    annotations?: StreamPhysicsFrameProps["annotations"];
+    autoPlaceAnnotations?: StreamPhysicsFrameProps["autoPlaceAnnotations"];
+    background?: StreamPhysicsFrameProps["background"];
+    legend?: StreamPhysicsFrameProps["legend"];
+    legendPosition?: StreamPhysicsFrameProps["legendPosition"];
+    legendLayout?: StreamPhysicsFrameProps["legendLayout"];
+    svgAnnotationRules?: StreamPhysicsFrameProps["svgAnnotationRules"];
+};
+/** Galton / pile sampling mode (orthogonal to ChartMode display modes). */
+export type PhysicsSimulationMode = "sample" | "mechanical";
+/**
+ * Split ChartMode (`primary`/`context`/`sparkline`/`mobile`) from the
+ * Galton/pile `sample`/`mechanical` simulation mode. Accepts legacy
+ * `mode="mechanical"` as simulationMode for back-compat.
+ */
+export declare function resolvePhysicsModes(options: {
+    mode?: ChartMode | PhysicsSimulationMode;
+    simulationMode?: PhysicsSimulationMode;
+}): {
+    chartMode: ChartMode | undefined;
+    simulationMode: PhysicsSimulationMode;
+};
+/** Physics fills its box; only compact ChartModes get non-zero chrome padding. */
+export declare function physicsMarginForMode(compactMode: boolean, mode?: ChartMode): {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+export declare function resolvePhysicsChartSize(size: [number, number] | undefined, width: number | undefined, height: number | undefined, fallback: [number, number]): [number, number];
+export type PhysicsChartModeProps = {
+    width?: number;
+    height?: number;
+    title?: string;
+    description?: string;
+    summary?: string;
+    accessibleTable?: boolean;
+    /** Frame-level hover; HOCs may pass via tooltip or frameProps. */
+    enableHover?: boolean;
+    mobileInteraction?: BaseChartProps["mobileInteraction"];
+    mobileSemantics?: BaseChartProps["mobileSemantics"];
+    responsiveRules?: BaseChartProps["responsiveRules"];
+    mode?: ChartMode | PhysicsSimulationMode;
+    simulationMode?: PhysicsSimulationMode;
+    size?: [number, number];
+    showProjection?: boolean;
+    showChrome?: boolean;
+    tooltip?: TooltipProp;
+    className?: string;
+};
+export interface PhysicsChartModeResult {
+    chartMode: ChartMode | undefined;
+    simulationMode: PhysicsSimulationMode;
+    resolved: ChartModeResult;
+    chartSize: [number, number];
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    showProjection: boolean;
+    showChrome: boolean;
+    enableHover: boolean;
+    title: string | undefined;
+    description: string | undefined;
+    summary: string | undefined;
+    accessibleTable: boolean | undefined;
+    className: string | undefined;
+    compactMode: boolean;
+    mobileInteraction: ChartModeResult["mobileInteraction"];
+    mobileSemantics: ChartModeResult["mobileSemantics"];
+}
+/**
+ * ChartMode + size + compact chrome defaults for every physics HOC.
+ * Primary physics sizes stay family-specific (`primaryFallback`); mode only
+ * overrides when width/height/size are unset.
+ */
+export declare function usePhysicsChartMode(props: PhysicsChartModeProps, primaryFallback: [number, number], options?: {
+    hasSimulationMode?: boolean;
+}): PhysicsChartModeResult;
+export declare function renderPhysicsChartState<TDatum extends Datum>(options: {
+    data?: TDatum[] | null;
+    emptyContent?: BaseChartProps["emptyContent"];
+    loading?: BaseChartProps["loading"];
+    loadingContent?: BaseChartProps["loadingContent"];
+    size: [number, number];
+}): React.ReactElement | null;
+export declare function renderPhysicsFrame(componentName: string, size: [number, number], children: React.ReactNode): React.ReactElement;
+export declare function composePhysicsFrameGraphics(first: FrameGraphicsProp | undefined, second: FrameGraphicsProp | undefined): FrameGraphicsProp | undefined;
+export declare function resolvePhysicsTooltipProps(tooltip: TooltipProp | undefined, frameProps?: Partial<StreamPhysicsFrameProps>): Pick<StreamPhysicsFrameProps, "enableHover" | "tooltipContent">;
+/**
+ * HOC → StreamPhysicsFrame shared Semiotic contracts: a11y, observation,
+ * click, chrome (title/legend/annotations), primitive styling, emphasis.
+ * Prefer HOC props; frameProps fill gaps.
+ */
+export declare function resolvePhysicsFrameSharedProps(props: Pick<BaseChartProps, "accessibleTable" | "chartId" | "className" | "color" | "description" | "emphasis" | "hoverRadius" | "onClick" | "onObservation" | "opacity" | "stroke" | "strokeWidth" | "summary" | "title"> & {
+    annotations?: StreamPhysicsFrameProps["annotations"];
+    autoPlaceAnnotations?: StreamPhysicsFrameProps["autoPlaceAnnotations"];
+    background?: StreamPhysicsFrameProps["background"];
+    legend?: StreamPhysicsFrameProps["legend"];
+    legendPosition?: StreamPhysicsFrameProps["legendPosition"];
+    legendLayout?: StreamPhysicsFrameProps["legendLayout"];
+    svgAnnotationRules?: StreamPhysicsFrameProps["svgAnnotationRules"];
+}, frameProps: Partial<StreamPhysicsFrameProps> | undefined, semanticItems?: PhysicsSemanticItem[], modeExtras?: {
+    chartMode?: ChartMode;
+    className?: string;
+    title?: string;
+    description?: string;
+    summary?: string;
+    accessibleTable?: boolean;
+    enableHover?: boolean;
+    margin?: StreamPhysicsFrameProps["margin"];
+}): Partial<StreamPhysicsFrameProps>;
+export type { TooltipProp };

package/dist/components/charts/physics/physicsPilePhysics.d.ts

@@ -0,0 +1,41 @@
+import type { Datum } from "../shared/datumTypes";
+import type { ChartAccessor } from "../shared/types";
+import { type PhysicsChartLayout } from "./physicsChartShared";
+export interface PhysicsPileMechanicalSampleOptions {
+    categories?: readonly string[];
+    count?: number;
+    idPrefix?: string;
+    seed?: number;
+    unitValue?: number;
+}
+export interface PhysicsPileOptions<TDatum extends Datum = Datum> {
+    data: readonly TDatum[];
+    categoryAccessor: ChartAccessor<TDatum, string>;
+    valueAccessor?: ChartAccessor<TDatum, number>;
+    unitValue: number;
+    ballRadius: number;
+    seed: number;
+    size: [number, number];
+}
+export declare function generatePhysicsPileMechanicalSamples(options?: PhysicsPileMechanicalSampleOptions): Datum[];
+export interface PileTubeGeometry {
+    laneWidth: number;
+    tubeWidth: number;
+    ballDiameter: number;
+    perRow: number;
+    centerX: (index: number) => number;
+    pileHeight: (count: number) => number;
+}
+/**
+ * Column geometry shared by the pile builder and its projection overlay so the
+ * ghost bar's height is exactly the fill target the stacked units rise to reach.
+ * Units drop into a narrow tube (a few balls wide) so their count reads as
+ * height — a bar chart assembled from falling units, not a spreading heap.
+ */
+export declare function pileTubeGeometry(plot: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, categoryCount: number, ballRadius: number): PileTubeGeometry;
+export declare function buildPhysicsPile<TDatum extends Datum>(options: PhysicsPileOptions<TDatum>): PhysicsChartLayout;

package/dist/components/charts/physics/physicsProcessPrimitives.d.ts

@@ -0,0 +1,38 @@
+import type { PhysicsColliderBodyFilter, PhysicsColliderSpec, PhysicsColliderShape } from "../../stream/physics/PhysicsKernel";
+import type { PhysicsSemanticItem, StreamPhysicsRegionEffect, StreamPhysicsRegionKind } from "../../stream/physics/StreamPhysicsFrame";
+import type { Datum } from "../shared/datumTypes";
+export interface PhysicsProcessStage {
+    id: string;
+    label?: string;
+    description?: string;
+    kind?: StreamPhysicsRegionKind | string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+}
+export interface PhysicsProcessBodyGroup<TDatum extends Datum = Datum> {
+    id: string;
+    label?: string;
+    description?: string;
+    group?: string;
+    bodyIds?: readonly string[];
+    datum?: TDatum;
+    state?: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    semanticItem?: false | Partial<PhysicsSemanticItem>;
+}
+export interface PhysicsProcessBoundaryOptions {
+    id?: string;
+    bodyFilter?: PhysicsColliderBodyFilter;
+    friction?: number;
+    restitution?: number;
+    thickness?: number;
+}
+export declare function physicsProcessBoundaryColliders(shape: PhysicsColliderShape, options?: PhysicsProcessBoundaryOptions): PhysicsColliderSpec[];
+export declare function physicsProcessRegionSemanticItem(region: StreamPhysicsRegionEffect): PhysicsSemanticItem | null;
+export declare function physicsProcessStageSemanticItems(stages: readonly PhysicsProcessStage[]): PhysicsSemanticItem[];
+export declare function physicsProcessGroupSemanticItems<TDatum extends Datum>(groups: readonly PhysicsProcessBodyGroup<TDatum>[]): PhysicsSemanticItem[];

package/dist/components/charts/physics/processFlowPhysics.d.ts

@@ -0,0 +1,97 @@
+import type { Datum } from "../shared/datumTypes";
+import type { ChartAccessor } from "../shared/types";
+import type { StreamPhysicsRegionEffect } from "../../stream/physics/StreamPhysicsTypes";
+import { groupCompletionRows, type BodyGroupSpec, type ProcessVolumeLayout } from "../../recipes/processPhysics";
+import { type PhysicsChartArea, type PhysicsChartLayout } from "./physicsChartShared";
+export interface ProcessFlowStageDef {
+    id: string;
+    label?: string;
+    description?: string;
+    /** Relative width share along the route. */
+    share?: number;
+    /**
+     * Continuous forward force while bodies overlap the stage.
+     * Number form is `{ x: force, y: 0 }`.
+     */
+    force?: number | {
+        x?: number;
+        y?: number;
+    };
+    damping?: number;
+    /**
+     * Capacitated processing stand-in: throughput metadata + force/damping.
+     * Full queue DES is ProcessFlow controller territory later.
+     */
+    capacity?: {
+        unitsPerSecond: number;
+        /** Datum field used as work-units (stamped into attributes only for now). */
+        unitAccessor?: string;
+    };
+    /**
+     * Raise drag with a pressure scalar (or occupancy when provided at build time).
+     */
+    pressure?: boolean | {
+        pressure?: number;
+        occupancy?: number;
+        baseDamping?: number;
+        dampingPerUnit?: number;
+        energyPerUnit?: number;
+    };
+    /** Rework / bounce portal toward another stage id. */
+    portal?: {
+        targetStageId: string;
+        force?: {
+            x?: number;
+            y?: number;
+        };
+    };
+    /** Absorbing sink (completion / merge). */
+    absorb?: boolean;
+    kind?: StreamPhysicsRegionEffect["kind"];
+}
+export interface ProcessFlowPhysicsOptions<TDatum extends Datum = Datum> {
+    data: readonly TDatum[];
+    stages: readonly ProcessFlowStageDef[];
+    size: [number, number];
+    idAccessor?: ChartAccessor<TDatum, string>;
+    stageAccessor?: ChartAccessor<TDatum, string>;
+    groupBy?: ChartAccessor<TDatum, string>;
+    groupLabelAccessor?: ChartAccessor<TDatum, string>;
+    workAccessor?: ChartAccessor<TDatum, number>;
+    radiusAccessor?: ChartAccessor<TDatum, number>;
+    ballRadius?: number;
+    seed?: number;
+    /** Horizontal process lane (default). */
+    route?: "horizontal";
+    groupCompletion?: "allAbsorbed" | "none";
+    /** Optional column x for feature/group anchors (plot-relative fraction 0–1). */
+    groupAnchorAlong?: number;
+    springStiffness?: number;
+    springDamping?: number;
+    gravityX?: number;
+    gravityY?: number;
+    settle?: boolean;
+}
+export interface ProcessFlowProjectionMetadata {
+    kind: "process-flow";
+    plot: PhysicsChartArea["plot"];
+    volume: ProcessVolumeLayout;
+    stages: Array<{
+        id: string;
+        label: string;
+        x: number;
+        width: number;
+        count: number;
+        capacity?: number;
+        absorb?: boolean;
+        portalTarget?: string;
+    }>;
+    groups: BodyGroupSpec[];
+    groupCompletion: ReturnType<typeof groupCompletionRows>;
+    regionEffects: StreamPhysicsRegionEffect[];
+}
+/**
+ * Build a capacitated multi-body process lane: stage regions, optional feature
+ * body-groups, springs toward stage centers, and a settled stage-count projection.
+ */
+export declare function buildProcessFlowPhysics<TDatum extends Datum>(options: ProcessFlowPhysicsOptions<TDatum>): PhysicsChartLayout;

package/dist/components/charts/realtime/RealtimeHeatmap.d.ts

@@ -3,13 +3,21 @@ import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, Annotat
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
-import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
+import type { ChartMode, ChartAccessor, SelectionConfig, MobileInteractionProp } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
 import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
+import type { MobileVisualizationContract } from "../shared/auditMobileVisualization";
+import type { ResponsiveRule } from "../shared/responsiveRules";
 export interface RealtimeHeatmapProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
+    /** Semantic responsive transformations applied before chart-mode defaults. */
+    responsiveRules?: ResponsiveRule[];
+    /** Phone/mobile contract consumed by audits, recipes, adapters, and agents. */
+    mobileSemantics?: MobileVisualizationContract;
+    /** Touch-first interaction policy for phone-sized chart slots. */
+    mobileInteraction?: MobileInteractionProp;
     /** Chart dimensions as [width, height] */
     size?: [number, number];
     /** Chart width (alternative to size) */

package/dist/components/charts/realtime/RealtimeHistogram.d.ts

@@ -3,14 +3,22 @@ import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, Annotat
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
-import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
+import type { ChartMode, ChartAccessor, SelectionConfig, MobileInteractionProp } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
 import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
+import type { MobileVisualizationContract } from "../shared/auditMobileVisualization";
+import type { ResponsiveRule } from "../shared/responsiveRules";
 export type RealtimeHistogramDirection = "up" | "down";
 export interface RealtimeHistogramProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
+    /** Semantic responsive transformations applied before chart-mode defaults. */
+    responsiveRules?: ResponsiveRule[];
+    /** Phone/mobile contract consumed by audits, recipes, adapters, and agents. */
+    mobileSemantics?: MobileVisualizationContract;
+    /** Touch-first interaction policy for phone-sized chart slots. */
+    mobileInteraction?: MobileInteractionProp;
     /** Time interval for binning */
     binSize: number;
     /** Chart dimensions as [width, height] */

package/dist/components/charts/realtime/RealtimeLineChart.d.ts

@@ -3,15 +3,23 @@ import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, Annotat
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
-import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
+import type { ChartMode, ChartAccessor, SelectionConfig, MobileInteractionProp } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
 import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
+import type { MobileVisualizationContract } from "../shared/auditMobileVisualization";
+import type { ResponsiveRule } from "../shared/responsiveRules";
 import { type AggregateConfig } from "./aggregate";
 import { type EventTimeConfig } from "./eventTime";
 export interface RealtimeLineChartProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
+    /** Semantic responsive transformations applied before chart-mode defaults. */
+    responsiveRules?: ResponsiveRule[];
+    /** Phone/mobile contract consumed by audits, recipes, adapters, and agents. */
+    mobileSemantics?: MobileVisualizationContract;
+    /** Touch-first interaction policy for phone-sized chart slots. */
+    mobileInteraction?: MobileInteractionProp;
     /** Chart dimensions as [width, height] */
     size?: [number, number];
     /** Chart width (alternative to size) */

package/dist/components/charts/realtime/RealtimeSwarmChart.d.ts

@@ -1,15 +1,23 @@
 import * as React from "react";
-import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext } from "../../stream/types";
+import type { ArrowOfTime, WindowMode, Style, HoverAnnotationConfig, HoverData, AnnotationContext } from "../../stream/types";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
-import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
+import type { ChartMode, ChartAccessor, SelectionConfig, MobileInteractionProp } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
 import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
+import type { MobileVisualizationContract } from "../shared/auditMobileVisualization";
+import type { ResponsiveRule } from "../shared/responsiveRules";
 export interface RealtimeSwarmChartProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
+    /** Semantic responsive transformations applied before chart-mode defaults. */
+    responsiveRules?: ResponsiveRule[];
+    /** Phone/mobile contract consumed by audits, recipes, adapters, and agents. */
+    mobileSemantics?: MobileVisualizationContract;
+    /** Touch-first interaction policy for phone-sized chart slots. */
+    mobileInteraction?: MobileInteractionProp;
     /** Chart dimensions as [width, height] */
     size?: [number, number];
     /** Chart width (alternative to size) */
@@ -43,6 +51,8 @@ export interface RealtimeSwarmChartProps<TDatum extends Datum = Datum> {
     timeExtent?: [number, number];
     /** Fixed value domain */
     valueExtent?: [number, number];
+    /** Value-axis scale. "symlog" supports signed values while compressing large magnitudes. */
+    yScaleType?: "linear" | "log" | "symlog";
     /** Extent padding factor */
     extentPadding?: number;
     /** Category accessor for color-coding dots */
@@ -59,6 +69,10 @@ export interface RealtimeSwarmChartProps<TDatum extends Datum = Datum> {
     stroke?: string;
     /** Dot stroke width */
     strokeWidth?: number;
+    /** Per-datum dot style. Returned values override the top-level dot primitives and category color. */
+    pointStyle?: (datum: TDatum) => Style & {
+        r?: number;
+    };
     /** Show canvas-drawn axes */
     showAxes?: boolean;
     /** Background fill color */

package/dist/components/charts/realtime/RealtimeWaterfallChart.d.ts

@@ -3,13 +3,21 @@ import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, Annotat
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
-import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
+import type { ChartMode, ChartAccessor, SelectionConfig, MobileInteractionProp } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
 import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
+import type { MobileVisualizationContract } from "../shared/auditMobileVisualization";
+import type { ResponsiveRule } from "../shared/responsiveRules";
 export interface RealtimeWaterfallChartProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
+    /** Semantic responsive transformations applied before chart-mode defaults. */
+    responsiveRules?: ResponsiveRule[];
+    /** Phone/mobile contract consumed by audits, recipes, adapters, and agents. */
+    mobileSemantics?: MobileVisualizationContract;
+    /** Touch-first interaction policy for phone-sized chart slots. */
+    mobileInteraction?: MobileInteractionProp;
     /** Chart dimensions as [width, height] */
     size?: [number, number];
     /** Chart width (alternative to size) */