semiotic 3.7.4 → 3.8.0

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

@@ -0,0 +1,213 @@
+/**
+ * Gauntlet domain types + body-kind constants (no heavy runtime).
+ */
+import type { Datum } from "../shared/datumTypes";
+import type { ChartAccessor } from "../shared/types";
+import type { PhysicsBodyState } from "../../stream/physics/PhysicsKernel";
+import type { PhysicsQueuedSpawn, PhysicsSpawnSpringSpec } from "../../stream/physics/PhysicsPipelineStore";
+import type { StreamPhysicsRegionEffect } from "../../stream/physics/StreamPhysicsTypes";
+export declare const CORE_KIND: "gauntlet-core";
+export declare const POSITIVE_KIND: "gauntlet-positive";
+export declare const NEGATIVE_KIND: "gauntlet-negative";
+export interface GauntletProjectPlacement {
+    graveyardX?: number;
+    graveyardY?: number;
+    routeY?: number;
+    socketX?: number;
+    socketY?: number;
+    startX?: number;
+    startY?: number;
+}
+export interface GauntletPropertyForceContext<TDatum extends Datum = Datum> {
+    body: PhysicsBodyState;
+    bodies: readonly PhysicsBodyState[];
+    core: PhysicsBodyState;
+    index: number;
+    layout: GauntletLayout;
+    placement: Required<GauntletProjectPlacement>;
+    project: GauntletProjectState<TDatum>;
+}
+export interface GauntletPropertyDefinition {
+    id: string;
+    label?: string;
+    short?: string;
+    color?: string;
+    value?: number;
+    radius?: number;
+    mass?: number;
+    buoyancy?: number;
+    load?: number;
+    /** Work units required to remove one occurrence at a bounded-work gate. */
+    work?: number;
+    /** Lower values are selected first by the default work-budget planner. */
+    priority?: number;
+    pull?: {
+        x?: number;
+        y?: number;
+    };
+    popColor?: string;
+    spring?: false | Partial<PhysicsSpawnSpringSpec>;
+    target?: (context: GauntletPropertyForceContext) => {
+        x: number;
+        y: number;
+    } | null | undefined;
+}
+export interface GauntletGate {
+    id: string;
+    label?: string;
+    description?: string;
+    color?: string;
+    /**
+     * Optional shared FIFO capacity for compound cores crossing this gate.
+     * Event time remains the earliest arrival; the matching gate event waits
+     * until the project's core has been processed.
+     */
+    capacity?: {
+        unitsPerSecond: number;
+        /** Reads work units from the source datum or live project state. */
+        unitAccessor?: string | ((project: GauntletProjectState) => number);
+        maxQueue?: number;
+        queueLayout?: "lane" | "none";
+        queueSlotSpacing?: number;
+        queueStiffness?: number;
+        /** Invisible sensor/queue width; independent from the drawn gate width. */
+        sensorWidth?: number;
+    };
+    enabled?: boolean;
+    regionEffect?: Partial<Omit<StreamPhysicsRegionEffect, "id" | "shape">>;
+    time?: number;
+    x?: number;
+    width?: number;
+}
+/** Pop one or more attached property ids from a project. */
+export type GauntletPopSpec = readonly string[] | {
+    candidates?: readonly string[];
+    count?: number;
+    ids?: readonly string[];
+};
+export interface GauntletEffect {
+    addPositive?: readonly string[] | Record<string, number>;
+    addNegative?: readonly string[] | Record<string, number>;
+    popPositive?: GauntletPopSpec;
+    /**
+     * Remove attached negative property bodies — the inverse of the common
+     * "pop positives / add negatives" gate. Supports the same array / candidates
+     * / ids shape as {@link popPositive}.
+     */
+    popNegative?: GauntletPopSpec;
+    delayDelta?: number;
+    metricsDelta?: Record<string, number>;
+    outcome?: string;
+    stage?: string;
+    summary?: string;
+    viabilityDelta?: number;
+    when?: (context: GauntletEventContext) => boolean;
+}
+export interface GauntletEvent {
+    id: string;
+    label?: string;
+    time: number;
+    gateId?: string;
+    /** Capacity-gate visit this event waits for. Defaults to its gate-event ordinal. */
+    gateVisit?: number;
+    effects?: readonly GauntletEffect[];
+    final?: boolean;
+    outcome?: string;
+    routeX?: number;
+    routeY?: number;
+    summary?: string;
+}
+export interface GauntletEventLogItem {
+    id: string;
+    label: string;
+    summary?: string;
+    /** Actual project-local application time (event `time` is the authored earliest time). */
+    appliedAt?: number;
+    time?: number;
+}
+export interface GauntletProjectState<TDatum extends Datum = Datum> {
+    crashX?: number;
+    id: string;
+    activePositiveIds: string[];
+    datum: TDatum;
+    delay: number;
+    eventsApplied: string[];
+    /** Ordered event tape for readouts, replay evidence, and accessibility. */
+    eventHistory?: GauntletEventLogItem[];
+    killed: boolean;
+    lastEvent?: GauntletEventLogItem;
+    metrics: Record<string, number>;
+    missingPositiveIds: string[];
+    negativeIds: string[];
+    outcome: string;
+    poppedPositiveIds: string[];
+    /** Negative property ids removed by {@link GauntletEffect.popNegative}. */
+    poppedNegativeIds: string[];
+    /** Project-local timeline origin in simulation seconds. */
+    startedAt?: number;
+    stage: string;
+    viability: number;
+}
+export interface GauntletLayout {
+    crashY: number;
+    floorY: number;
+    gates: Array<Required<Pick<GauntletGate, "id" | "x" | "width">> & GauntletGate>;
+    graveyardX: number;
+    graveyardY: number;
+    height: number;
+    routeY: number;
+    socketX: number;
+    startX: number;
+    width: number;
+}
+export interface GauntletEventContext<TDatum extends Datum = Datum> {
+    event: GauntletEvent;
+    gate?: GauntletLayout["gates"][number];
+    negativeProperties: Map<string, GauntletPropertyDefinition>;
+    positiveProperties: Map<string, GauntletPropertyDefinition>;
+    project: GauntletProjectState<TDatum>;
+}
+/** Placement override for a project in layout space. */
+export type GauntletProjectPlacementFn<TDatum extends Datum = Datum> = (project: GauntletProjectState<TDatum>, index: number, layout: GauntletLayout) => Partial<GauntletProjectPlacement>;
+/** Optional spawn overrides for the project core body. */
+export type GauntletCoreBodyFn<TDatum extends Datum = Datum> = (project: GauntletProjectState<TDatum>, index: number, layout: GauntletLayout, placement: Required<GauntletProjectPlacement>) => Partial<PhysicsQueuedSpawn>;
+/** Custom viability scorer. */
+export type GauntletViabilityFn<TDatum extends Datum = Datum> = (project: GauntletProjectState<TDatum>, context: {
+    negativeProperties: Map<string, GauntletPropertyDefinition>;
+    positiveProperties: Map<string, GauntletPropertyDefinition>;
+}) => number;
+/** Accessors used when seeding project state from user rows. */
+export interface GauntletAccessors<TDatum extends Datum = Datum> {
+    idAccessor?: ChartAccessor<TDatum, string>;
+    initialViability?: ChartAccessor<TDatum, number>;
+    metricsAccessor?: ChartAccessor<TDatum, Record<string, number>>;
+    negativeAccessor?: ChartAccessor<TDatum, readonly string[]>;
+    positiveAccessor?: ChartAccessor<TDatum, readonly string[]>;
+    startTimeAccessor?: ChartAccessor<TDatum, number>;
+}
+export interface GauntletPropertyWorkPlanOptions {
+    attachedIds: readonly string[];
+    properties: readonly GauntletPropertyDefinition[] | Map<string, GauntletPropertyDefinition>;
+    budget: number;
+    candidates?: readonly string[];
+}
+export interface GauntletPropertyWorkPlan {
+    ids: string[];
+    used: number;
+    budget: number;
+    remaining: number;
+    skippedIds: string[];
+}
+export interface GauntletNegativeReplacementOptions {
+    from: string;
+    to: string;
+    count?: number;
+}
+/** Wall colliders matching {@link GAUNTLET_WALL} / SSR builder. */
+export interface GauntletBodyDatum<TDatum extends Datum = Datum> {
+    __gauntlet: true;
+    kind: typeof CORE_KIND | typeof POSITIVE_KIND | typeof NEGATIVE_KIND;
+    projectId: string;
+    property?: GauntletPropertyDefinition;
+    sourceDatum: TDatum;
+}

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

@@ -0,0 +1,57 @@
+import type { Datum } from "../shared/datumTypes";
+import type { ChartAccessor } from "../shared/types";
+import { type PhysicsChartArea, type PhysicsChartLayout } from "./physicsChartShared";
+export type PhysicalFlowCoordinateMode = "auto" | "normalized" | "pixels";
+export type PhysicalFlowPathConstraint = "path" | "none";
+export interface PhysicalFlowPoint {
+    x: number;
+    y: number;
+}
+export type PhysicalFlowRawPath = ReadonlyArray<PhysicalFlowPoint | readonly [number, number]>;
+export interface PhysicalFlowOptions<TNode extends Datum = Datum, TLink extends Datum = Datum> {
+    nodes: readonly TNode[];
+    links: readonly TLink[];
+    nodeIdAccessor: ChartAccessor<TNode, string>;
+    nodeXAccessor: ChartAccessor<TNode, number>;
+    nodeYAccessor: ChartAccessor<TNode, number>;
+    sourceAccessor: ChartAccessor<TLink, string>;
+    targetAccessor: ChartAccessor<TLink, string>;
+    throughputAccessor: ChartAccessor<TLink, number>;
+    pathAccessor?: ChartAccessor<TLink, PhysicalFlowRawPath | undefined>;
+    coordinateMode?: PhysicalFlowCoordinateMode;
+    particleRate: number;
+    maxParticles: number;
+    particleRadius: number;
+    flowSpeed: number;
+    pathConstraint?: PhysicalFlowPathConstraint;
+    reducedMotion?: boolean;
+    seed: number;
+    size: [number, number];
+}
+export interface PhysicalFlowProjectionMetadata {
+    kind: "physical-flow";
+    coordinateMode: Exclude<PhysicalFlowCoordinateMode, "auto">;
+    particleCount: number;
+    totalThroughput: number;
+    plot: PhysicsChartArea["plot"];
+    nodes: Array<{
+        id: string;
+        label: string;
+        x: number;
+        y: number;
+        sensorId: string;
+        incoming: number;
+        outgoing: number;
+    }>;
+    links: Array<{
+        id: string;
+        source: string;
+        target: string;
+        sourceLabel: string;
+        targetLabel: string;
+        throughput: number;
+        packetCount: number;
+        path: PhysicalFlowPoint[];
+    }>;
+}
+export declare function buildPhysicalFlowPhysics<TNode extends Datum, TLink extends Datum>(options: PhysicalFlowOptions<TNode, TLink>): PhysicsChartLayout;

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

@@ -0,0 +1,41 @@
+import type { Datum } from "../shared/datumTypes";
+import type { ChartAccessor } from "../shared/types";
+import type { Style } from "../../stream/types";
+import type { PhysicsColliderSpec } from "../../stream/physics/PhysicsKernel";
+import type { PhysicsPipelineConfig, PhysicsQueuedSpawn, PhysicsSpawnPacingOptions } from "../../stream/physics/PhysicsPipelineStore";
+import type { PhysicsSemanticItem } from "../../stream/physics/StreamPhysicsTypes";
+export interface PhysicsChartLayout {
+    config: PhysicsPipelineConfig;
+    initialSpawns: PhysicsQueuedSpawn[];
+    initialSpawnPacing?: PhysicsSpawnPacingOptions;
+    projectionRows: Array<{
+        label: string;
+        value: number;
+        secondary?: number;
+    }>;
+    metadata?: Record<string, unknown>;
+}
+export interface PhysicsChartArea {
+    width: number;
+    height: number;
+    plot: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export declare function physicsChartArea(size: [number, number]): PhysicsChartArea;
+export declare function hashStringColor(value: unknown): string;
+export declare function styleFromColorAccessor<TDatum extends Datum>(colorBy: ChartAccessor<TDatum, string> | undefined, fallback?: string): (body: {
+    datum?: unknown;
+}) => Style;
+export declare function baseConfig(seed: number, colliders: PhysicsColliderSpec[], chartType: string, kernel?: Partial<NonNullable<PhysicsPipelineConfig["kernel"]>>): PhysicsPipelineConfig;
+export declare function projectionRowsToSemanticItems(rows: readonly PhysicsChartLayout["projectionRows"][number][], size: [number, number], noun: string): PhysicsSemanticItem[];
+export declare function readAccessor<TDatum extends Datum, TValue>(datum: TDatum, index: number, accessor: ChartAccessor<TDatum, TValue>): TValue;
+export declare function finiteNumber(value: unknown): number | null;
+export declare function clampNumber(value: number, min: number, max: number): number;
+export declare function positiveNumber(value: unknown, fallback: number): number;
+export declare function normalizedFiniteExtent(extent: readonly [unknown, unknown] | undefined): [number, number] | undefined;
+export declare function safeIdPart(value: unknown): string;
+export declare function seededRandom(seed: number): () => number;

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

@@ -0,0 +1,18 @@
+/**
+ * Physics chart layout builders — barrel re-export.
+ * Implementations live in per-chart modules next to this file.
+ */
+export type { PhysicsChartLayout, PhysicsChartArea } from "./physicsChartShared";
+export { projectionRowsToSemanticItems, physicsChartArea, hashStringColor, styleFromColorAccessor } from "./physicsChartShared";
+export type { GaltonBoardPhysicsOptions, GaltonBoardProjectionMetadata, GaltonMechanicalSampleOptions } from "./galtonBoardPhysics";
+export { generateGaltonMechanicalSamples, buildGaltonBoardPhysics } from "./galtonBoardPhysics";
+export type { EventDropWindowOptions, EventDropPlotRegion, EventDropLidSegment, EventDropProjectionMetadata, EventDropPhysicsOptions } from "./eventDropPhysics";
+export { buildEventDropPhysics, placeEventDropSpawn } from "./eventDropPhysics";
+export type { PhysicsPileMechanicalSampleOptions, PhysicsPileOptions, PileTubeGeometry } from "./physicsPilePhysics";
+export { generatePhysicsPileMechanicalSamples, pileTubeGeometry, buildPhysicsPile } from "./physicsPilePhysics";
+export type { CollisionSwarmPhysicsOptions, CollisionSwarmProjectionMetadata } from "./collisionSwarmPhysics";
+export { buildCollisionSwarmPhysics } from "./collisionSwarmPhysics";
+export type { PhysicalFlowCoordinateMode, PhysicalFlowPathConstraint, PhysicalFlowPoint, PhysicalFlowRawPath, PhysicalFlowOptions, PhysicalFlowProjectionMetadata } from "./physicalFlowPhysics";
+export { buildPhysicalFlowPhysics } from "./physicalFlowPhysics";
+export type { ProcessFlowStageDef, ProcessFlowPhysicsOptions, ProcessFlowProjectionMetadata } from "./processFlowPhysics";
+export { buildProcessFlowPhysics } from "./processFlowPhysics";

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 };