semiotic 3.8.6 → 3.8.7

package/dist/components/ai/vacpAdapterTypes.d.ts

@@ -0,0 +1,169 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { SerializedSelections } from "../export/selectionSerializer";
+import type { ChartObservation } from "../store/ObservationStore";
+import type { AudienceProfile } from "./audienceProfile";
+import type { NavTreeNode } from "./navigationTree";
+import type { ChartReaderGrounding, ChartReaderGroundingOptions } from "./readerGrounding";
+import type { VacpActionDescriptor, VacpCapabilitiesRequest, VacpCapabilitiesSnapshot, VacpEdge, VacpNode, VacpRef, VacpStateRequest, VacpStateSnapshot, VacpStateUpdate, VacpWindowBridge } from "./vacpTypes";
+export declare const SEMIOTIC_VACP_SET_POINT_SELECTION_ACTION: "semiotic.set_point_selection";
+export declare const SEMIOTIC_VACP_SET_INTERVAL_SELECTION_ACTION: "semiotic.set_interval_selection";
+export declare const SEMIOTIC_VACP_CLEAR_SELECTION_ACTION: "semiotic.clear_selection";
+export declare const SEMIOTIC_VACP_ACTIVATE_NAVIGATION_ACTION: "semiotic.activate_navigation_node";
+export declare const SEMIOTIC_VACP_INSPECT_DATA_ACTION: "semiotic.inspect_data";
+export type SemioticVACPSelectionMode = "point" | "interval" | "both";
+export interface SemioticVACPSelectionBinding {
+    /** Named LinkedCharts selection exposed as one stable VACP Selection node. */
+    name: string;
+    /** Fields an agent may set. Values outside this allowlist are rejected. */
+    fields: string[];
+    /** Which semantic mutations are valid. Default "both". */
+    mode?: SemioticVACPSelectionMode;
+    /** Stable clause owner used for agent-written selection state. */
+    clientId?: string;
+}
+export interface SemioticVACPNavigationBinding {
+    tree: NavTreeNode;
+    /**
+     * Durable datum fields used to identify leaves. Procedural NavTreeNode ids
+     * are never used as VACP identity.
+     */
+    matchFields: string[];
+    /** Current procedural tree id, when the tree is controlled. */
+    activeId?: string;
+    /** Enables the validated semantic navigation action. */
+    onActiveChange?: (node: NavTreeNode) => void;
+}
+export interface SemioticVACPChart {
+    /** Durable identity within this bridge; independent of render order. */
+    chartId: string;
+    component: string;
+    props: Datum;
+    title?: string;
+    description?: string;
+    audience?: AudienceProfile;
+    /**
+     * Reader-grounding presentation settings. The bridge's internal grounding
+     * pass caps navigation structure at one representative leaf per branch.
+     */
+    grounding?: Omit<ChartReaderGroundingOptions, "audience">;
+    selections?: SemioticVACPSelectionBinding[];
+    navigation?: SemioticVACPNavigationBinding;
+}
+export interface SemioticVACPSelectionActions {
+    setPointSelection?: (selectionName: string, clientId: string, fields: Record<string, unknown[]>) => void | Promise<void>;
+    setIntervalSelection?: (selectionName: string, clientId: string, fields: Record<string, [number, number]>) => void | Promise<void>;
+    clearSelection?: (selectionName: string) => void | Promise<void>;
+}
+export interface SemioticVACPCustomAction {
+    descriptor: VacpActionDescriptor;
+    available?: () => boolean;
+    validate?: (params: unknown) => void | string;
+    execute: (params: unknown) => unknown | Promise<unknown>;
+}
+export interface SemioticVACPDataAccess {
+    /** Include bounded `semiotic.inspect_data`. Raw rows are off by default. */
+    sample?: boolean;
+    /** Maximum rows returned from one inspect call. Default 50. */
+    maxSampleRows?: number;
+    /** Maximum rows scanned for schema summaries. Default 5000. */
+    maxSchemaRows?: number;
+}
+export interface CreateSemioticVACPBridgeOptions {
+    appId: string;
+    viewId?: string;
+    title?: string;
+    /** Static charts or a live getter used on every protocol read/action. */
+    charts: readonly SemioticVACPChart[] | (() => readonly SemioticVACPChart[]);
+    /** JSON-safe snapshot of named LinkedCharts selections. */
+    getSelections?: () => SerializedSelections;
+    /** Live observation buffer; the latest event per chart becomes VACP state. */
+    getObservations?: () => readonly ChartObservation[];
+    selectionActions?: SemioticVACPSelectionActions;
+    dataAccess?: SemioticVACPDataAccess;
+    actions?: readonly SemioticVACPCustomAction[] | (() => readonly SemioticVACPCustomAction[]);
+    /** Test/instrumentation clock. */
+    now?: () => Date | number | string;
+    /** Retained full snapshots available as delta baselines. Default 64. */
+    stateCacheSize?: number;
+}
+export interface SemioticVACPRefs {
+    app: VacpRef;
+    view: VacpRef;
+    visualization: (chartId: string) => VacpRef;
+    config: (chartId: string) => VacpRef;
+    data: (chartId: string, collection?: string) => VacpRef;
+    selection: (name: string) => VacpRef;
+    navigation: (chartId: string) => VacpRef;
+    observation: (chartId: string) => VacpRef;
+}
+export interface SemioticVACPBridge extends VacpWindowBridge {
+    readonly refs: SemioticVACPRefs;
+    getCapabilities(request?: VacpCapabilitiesRequest): VacpCapabilitiesSnapshot;
+    getState(): Promise<VacpStateSnapshot>;
+    getState(request: VacpStateRequest): Promise<VacpStateUpdate>;
+}
+export interface InstallSemioticVACPBridgeOptions {
+    /** Default browser `window`; inject a record for tests or non-window hosts. */
+    target?: Record<string, unknown>;
+    /** Default `__vacp`. */
+    globalKey?: string;
+}
+export interface SemioticVACPBridgeInstallation {
+    installed: boolean;
+    globalKey: string;
+    bridge: SemioticVACPBridge;
+    reason?: string;
+    /** Delete the global only while this exact bridge still owns it. */
+    cleanup: () => boolean;
+}
+export interface DataHandleModel {
+    ref: VacpRef;
+    chartId: string;
+    collection: string;
+    rows: readonly unknown[];
+}
+export interface SelectionModel {
+    ref: VacpRef;
+    name: string;
+    fields: string[];
+    modes: Set<"point" | "interval">;
+    clientId: string;
+    chartRefs: VacpRef[];
+}
+export interface NavigationIndex {
+    valid: boolean;
+    diagnostic?: string;
+    byKey: Map<string, NavTreeNode>;
+    matchFields: string[];
+    targetRef: (match: Record<string, unknown>) => VacpRef;
+}
+export interface NavigationModel {
+    ref: VacpRef;
+    chartRef: VacpRef;
+    chartId: string;
+    binding: SemioticVACPNavigationBinding;
+    index: NavigationIndex;
+}
+export interface ChartModel {
+    chart: SemioticVACPChart;
+    ref: VacpRef;
+    configRef: VacpRef;
+    grounding: ChartReaderGrounding;
+    config: Record<string, unknown>;
+    dataHandles: DataHandleModel[];
+    navigation?: NavigationModel;
+}
+export interface RuntimeAction {
+    descriptor: VacpActionDescriptor;
+    execute: (params: unknown) => unknown | Promise<unknown>;
+}
+export interface RuntimeModelBase {
+    charts: ChartModel[];
+    selections: SelectionModel[];
+    dataHandles: DataHandleModel[];
+    nodes: VacpNode[];
+    edges: VacpEdge[];
+}
+export interface RuntimeModel extends RuntimeModelBase {
+    actions: RuntimeAction[];
+}

package/dist/components/ai/vacpTypes.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Structural VACP 0.1.0 types.
+ *
+ * VACP's protocol packages are not currently published, so the experimental
+ * Semiotic bridge depends only on the documented JSON contract. Keep this file
+ * structural and dependency-free so a consumer can replace these types with
+ * the canonical package once it becomes public.
+ *
+ * @see https://github.com/ETH-IVIA-Lab/VACP/blob/main/docs/reference/tool-contract.md
+ */
+export declare const VACP_SCHEMA_VERSION: "0.1.0";
+export type VacpSchemaVersion = typeof VACP_SCHEMA_VERSION;
+export type VacpRef = `vacp://${string}`;
+export type VacpLayer = "ConfigLayer" | "ViewLayer" | "VisualizationLayer" | "DataLayer" | "InteractionFeedbackLayer";
+export type VacpNodeKind = "App" | "View" | "Visualization" | "Mark" | "EncodingChannel" | "EncodedField" | "Legend" | "Axis" | "Selection" | "Param" | "Widget" | "DataHandle" | "InteractionTarget";
+export type VacpEdgeKind = "contains" | "controls" | "derivedFrom" | "targets";
+export interface VacpNode {
+    ref: VacpRef;
+    kind: VacpNodeKind;
+    layer: VacpLayer;
+    title?: string;
+    description?: string;
+    data?: Record<string, unknown>;
+}
+export interface VacpEdge {
+    from: VacpRef;
+    to: VacpRef;
+    kind: VacpEdgeKind;
+}
+export interface VacpActionDescriptor {
+    name: string;
+    title?: string;
+    description: string;
+    parameters?: Record<string, unknown>;
+    targetRef?: VacpRef;
+}
+export interface VacpGraph {
+    version: VacpSchemaVersion;
+    nodes: VacpNode[];
+    edges: VacpEdge[];
+    actions: VacpActionDescriptor[];
+}
+export interface VacpCapabilitiesSnapshot {
+    version: VacpSchemaVersion;
+    createdAt: string;
+    graph: VacpGraph;
+}
+export interface VacpCapabilitiesRequest {
+    refs?: VacpRef[];
+    prefixes?: VacpRef[];
+    kinds?: VacpNodeKind[];
+    layers?: VacpLayer[];
+    includeActions?: boolean;
+    includeEdges?: boolean;
+    includeNodeData?: boolean;
+}
+export interface VacpStateSnapshot {
+    version: VacpSchemaVersion;
+    createdAt: string;
+    state: Record<VacpRef, unknown>;
+    summary?: Record<VacpRef, unknown>;
+}
+export type VacpStateRequestMode = "auto" | "full" | "delta";
+export interface VacpStateRequest {
+    mode?: VacpStateRequestMode;
+    since?: string;
+    refs?: VacpRef[];
+    includeSummary?: boolean;
+}
+export interface VacpStateDeltaPayload {
+    changed: Record<VacpRef, unknown>;
+    removed: VacpRef[];
+    summaryChanged?: Record<VacpRef, unknown>;
+    summaryRemoved?: VacpRef[];
+}
+export type VacpStateUpdate = {
+    version: VacpSchemaVersion;
+    createdAt: string;
+    mode: "full";
+    token: string;
+    scope?: {
+        refs?: VacpRef[];
+    };
+    snapshot: VacpStateSnapshot;
+} | {
+    version: VacpSchemaVersion;
+    createdAt: string;
+    mode: "delta";
+    token: string;
+    baseToken: string;
+    scope?: {
+        refs?: VacpRef[];
+    };
+    delta: VacpStateDeltaPayload;
+};
+export interface VacpActionCall {
+    callId: string;
+    name: string;
+    params?: unknown;
+}
+export type VacpActionResult = {
+    callId: string;
+    ok: true;
+    result?: unknown;
+} | {
+    callId: string;
+    ok: false;
+    error: {
+        message: string;
+        details?: unknown;
+    };
+};
+export interface VacpWindowBridge {
+    version: VacpSchemaVersion;
+    getCapabilities(request?: VacpCapabilitiesRequest): Promise<VacpCapabilitiesSnapshot> | VacpCapabilitiesSnapshot;
+    getState(): Promise<VacpStateSnapshot>;
+    getState(request: VacpStateRequest): Promise<VacpStateUpdate>;
+    execute(call: VacpActionCall): Promise<VacpActionResult>;
+}
+export declare const VACP_DATA_SCHEMA_ACTION: "vacp.data_schema";
+export type VacpDataSchemaDetail = "columns" | "full";
+export interface VacpDataSchemaParams {
+    handleRef: VacpRef;
+    detail?: VacpDataSchemaDetail;
+    sampleRows?: number;
+}
+export interface VacpDataSchemaColumn {
+    name: string;
+    type: string;
+    notNull?: boolean;
+    primaryKey?: boolean;
+}
+export interface VacpDataSchemaNumericSummary {
+    min: number | null;
+    max: number | null;
+    avg: number | null;
+    unitHint?: "epoch_ms" | "epoch_s" | null;
+    minIso?: string | null;
+    maxIso?: string | null;
+}
+export interface VacpDataSchemaTemporalSummary {
+    minIso: string | null;
+    maxIso: string | null;
+    minEpochMs: number | null;
+    maxEpochMs: number | null;
+}
+export interface VacpDataSchemaResult {
+    handleRef: VacpRef;
+    detail: VacpDataSchemaDetail;
+    table: string | null;
+    rowCount: number | null;
+    columns: VacpDataSchemaColumn[];
+    numeric?: Record<string, VacpDataSchemaNumericSummary>;
+    temporal?: Record<string, VacpDataSchemaTemporalSummary>;
+    categoricalTopValues?: Record<string, Array<{
+        value: string;
+        n: number;
+    }>>;
+    sampledRows?: number | null;
+}

package/dist/components/charts/index.d.ts

@@ -103,8 +103,8 @@ export { GaltonBoardChart } from "./physics/GaltonBoardChart";
 export type { GaltonBoardChartProps, GaltonBoardReferenceLine } from "./physics/GaltonBoardChart";
 export { EventDropChart } from "./physics/EventDropChart";
 export type { EventDropChartProps } from "./physics/EventDropChart";
-export { PhysicsPileChart } from "./physics/PhysicsPileChart";
-export type { PhysicsPileChartProps } from "./physics/PhysicsPileChart";
+export { UnitPileChart, PhysicsPileChart } from "./physics/UnitPileChart";
+export type { UnitPileChartProps, PhysicsPileChartProps } from "./physics/UnitPileChart";
 export { CollisionSwarmChart } from "./physics/CollisionSwarmChart";
 export type { CollisionSwarmChartProps } from "./physics/CollisionSwarmChart";
 export * from "./physics/CrucibleChart";
@@ -120,8 +120,8 @@ export type { BodyGroupSpec, BodyGroupSpecOptions, ProcessMembraneDef, ProcessRe
 export type { RegionCountBucket, RegionCountMap } from "../recipes/processAggregates";
 export type { ProcessVolumePoint, ProcessVolumePolygon, ProcessVolumePolygonRole } from "../recipes/processVolumeGeometry";
 export type { ProcessJourneyEntityState, ProcessJourneyLedger, ProcessJourneyRow, ProcessJourneyStage, ProcessJourneyUpdateOptions } from "../recipes/processJourney";
-export { PhysicalFlowChart } from "./physics/PhysicalFlowChart";
-export type { PhysicalFlowChartProps } from "./physics/PhysicalFlowChart";
+export { PacketFlowChart, PhysicalFlowChart } from "./physics/PacketFlowChart";
+export type { PacketFlowChartProps, PhysicalFlowChartProps } from "./physics/PacketFlowChart";
 export { ProcessFlowChart } from "./physics/ProcessFlowChart";
 export type { ProcessFlowChartProps, ProcessFlowProjectionMetadata, ProcessFlowStageDef } from "./physics/ProcessFlowChart";
 export { PhysicsCustomChart } from "./physics/PhysicsCustomChart";

package/dist/components/charts/physics/ChainReactionChart.capability.d.ts

@@ -0,0 +1,9 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+/**
+ * ChainReactionChart is intentionally known to the AI surface but never selected
+ * from a flat data profile. The chart's whole claim is about a specific
+ * dependency topology — which task waits on which — and a profiler cannot
+ * responsibly invent edges. A dependency chart with the wrong edges is worse
+ * than no chart, so the graph must be authored.
+ */
+export declare const ChainReactionChartCapability: ChartCapability;

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

@@ -2,6 +2,35 @@ import * as React from "react";
 import type { Datum } from "../shared/datumTypes";
 import type { ChainReactionChartHandle, ChainReactionChartProps } from "./chainReactionTypes";
 export type * from "./chainReactionTypes";
+/**
+ * Physics-backed dependency chart whose settled reading exposes task state and each blocker's downstream reach.
+ *
+ * @example
+ * <ChainReactionChart
+ *   data={[
+ *     { id: "brief", label: "Brief", lane: "Product", dependsOn: [], status: "done" },
+ *     { id: "release", label: "Release", lane: "Product", dependsOn: ["brief"], status: "waiting" }
+ *   ]}
+ *   taskIDAccessor="id"
+ *   labelAccessor="label"
+ *   laneAccessor="lane"
+ *   dependencyAccessor="dependsOn"
+ *   statusAccessor="status"
+ * />
+ *
+ * @example
+ * <ChainReactionChart
+ *   data={releaseTasks}
+ *   taskIDAccessor="id"
+ *   labelAccessor="title"
+ *   laneAccessor="workstream"
+ *   dependencyAccessor="prerequisites"
+ *   completionTimeAccessor="completedAt"
+ *   mode="replay"
+ *   controls
+ *   insight="blocker-amplification"
+ * />
+ */
 export declare const ChainReactionChart: {
     <TDatum extends Datum = Datum>(props: ChainReactionChartProps<TDatum> & React.RefAttributes<ChainReactionChartHandle>): React.ReactElement | null;
     displayName?: string;

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

@@ -4,7 +4,7 @@ import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import type { StyleRule } from "../shared/styleRules";
 import { type PhysicsFrameHandle } from "./physicsHocHandle";
 import { type PhysicsHocFrameProps, type PhysicsRerunMS, type PhysicsSharedChartProps, type TooltipProp } from "./physicsHocUtils";
-export interface CollisionSwarmChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin">, PhysicsSharedChartProps {
+export interface CollisionSwarmChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "selection">, PhysicsSharedChartProps {
     data?: TDatum[];
     size?: [number, number];
     xAccessor?: ChartAccessor<TDatum, number>;

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

@@ -4,8 +4,8 @@ import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type EventDropWindowOptions } from "./physicsChartUtils";
 import type { StyleRule } from "../shared/styleRules";
 import { type PhysicsFrameHandle } from "./physicsHocHandle";
-import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type TooltipProp } from "./physicsHocUtils";
-export interface EventDropChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin">, PhysicsSharedChartProps {
+import { type PhysicsHocFrameProps, type PhysicsRerunMS, type PhysicsSharedChartProps, type TooltipProp } from "./physicsHocUtils";
+export interface EventDropChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "selection">, PhysicsSharedChartProps {
     data?: TDatum[];
     size?: [number, number];
     timeAccessor?: ChartAccessor<TDatum, number>;
@@ -28,6 +28,11 @@ export interface EventDropChartProps<TDatum extends Datum = Datum> extends Omit<
     timeScale?: number;
     showProjection?: boolean;
     tooltip?: TooltipProp;
+    /**
+     * Replay the seeded simulation this many milliseconds after it settles.
+     * Omit or pass `null` for a single run; `0` replays on the next timer turn.
+     */
+    rerunMS?: PhysicsRerunMS;
     paused?: boolean;
     frameProps?: PhysicsHocFrameProps<"config">;
 }

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

@@ -14,7 +14,7 @@ export interface GaltonBoardReferenceLine {
     strokeWidth?: number;
     labelPosition?: "top" | "bottom";
 }
-export interface GaltonBoardChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "mode">, PhysicsSharedChartProps {
+export interface GaltonBoardChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "mode" | "selection">, PhysicsSharedChartProps {
     data?: TDatum[];
     size?: [number, number];
     valueAccessor?: ChartAccessor<TDatum, number>;

package/dist/components/charts/physics/{PhysicsPileChart.capability.d.ts → PacketFlowChart.capability.d.ts}

@@ -1,2 +1,2 @@
 import type { ChartCapability } from "../../ai/chartCapabilityTypes";
-export declare const PhysicsPileChartCapability: ChartCapability;
+export declare const PacketFlowChartCapability: ChartCapability;

package/dist/components/charts/physics/{PhysicalFlowChart.d.ts → PacketFlowChart.d.ts}

@@ -4,8 +4,8 @@ import type { StyleRule } from "../shared/styleRules";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type PhysicalFlowCoordinateMode, type PhysicalFlowPathConstraint, type PhysicalFlowRawPath } from "./physicsChartUtils";
 import { type PhysicsFrameHandle } from "./physicsHocHandle";
-import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type TooltipProp } from "./physicsHocUtils";
-export interface PhysicalFlowChartProps<TNode extends Datum = Datum, TLink extends Datum = Datum> extends Omit<BaseChartProps, "margin">, PhysicsSharedChartProps {
+import { type PhysicsHocFrameProps, type PhysicsRerunMS, type PhysicsSharedChartProps, type TooltipProp } from "./physicsHocUtils";
+export interface PacketFlowChartProps<TNode extends Datum = Datum, TLink extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "selection">, PhysicsSharedChartProps {
     nodes?: TNode[];
     links?: TLink[];
     edges?: TLink[];
@@ -37,15 +37,22 @@ export interface PhysicalFlowChartProps<TNode extends Datum = Datum, TLink exten
     styleRules?: StyleRule[];
     seed?: number;
     tooltip?: TooltipProp;
+    /**
+     * Replay the seeded simulation this many milliseconds after it settles.
+     * Omit or pass `null` for a single run; `0` replays on the next timer turn.
+     */
+    rerunMS?: PhysicsRerunMS;
     paused?: boolean;
     frameProps?: PhysicsHocFrameProps<"config">;
 }
+/** @deprecated Renamed to {@link PacketFlowChartProps} in 3.9.0. */
+export type PhysicalFlowChartProps<TNode extends Datum = Datum, TLink extends Datum = Datum> = PacketFlowChartProps<TNode, TLink>;
 /**
  * Physics-backed flow chart that sends packet bodies along authored routes while retaining a static throughput layer.
  *
  * @example
  * ```tsx
- * <PhysicalFlowChart
+ * <PacketFlowChart
  *   nodes={[{ id: "in", x: 0.1, y: 0.5 }, { id: "out", x: 0.9, y: 0.5 }]}
  *   links={[{ source: "in", target: "out", value: 40 }]}
  *   coordinateMode="normalized"
@@ -54,7 +61,7 @@ export interface PhysicalFlowChartProps<TNode extends Datum = Datum, TLink exten
  *
  * @example
  * ```tsx
- * <PhysicalFlowChart
+ * <PacketFlowChart
  *   nodes={ports}
  *   edges={routes}
  *   pathAccessor="path"
@@ -63,8 +70,17 @@ export interface PhysicalFlowChartProps<TNode extends Datum = Datum, TLink exten
  * />
  * ```
  */
+export declare const PacketFlowChart: {
+    <TNode extends Datum = Datum, TLink extends Datum = Datum>(props: PacketFlowChartProps<TNode, TLink> & React.RefAttributes<PhysicsFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};
+/**
+ * @deprecated Renamed to {@link PacketFlowChart} in 3.9.0. Sends discrete packets along authored routes; "Physical" named the substrate and told a reader nothing about the reading protocol.
+ * The alias stays exported indefinitely for existing imports; new code and
+ * every registry (schema, capabilities, MCP, server configs) use `PacketFlowChart`.
+ */
 export declare const PhysicalFlowChart: {
-    <TNode extends Datum = Datum, TLink extends Datum = Datum>(props: PhysicalFlowChartProps<TNode, TLink> & React.RefAttributes<PhysicsFrameHandle>): React.ReactElement | null;
+    <TNode extends Datum = Datum, TLink extends Datum = Datum>(props: PacketFlowChartProps<TNode, TLink> & React.RefAttributes<PhysicsFrameHandle>): React.ReactElement | null;
     displayName?: string;
 };
-export default PhysicalFlowChart;
+export default PacketFlowChart;

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

@@ -62,7 +62,7 @@ export interface PhysicsCustomLayoutResult {
 }
 export type PhysicsCustomLayout<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> = (ctx: PhysicsCustomLayoutContext<TDatum, TConfig>) => PhysicsCustomLayoutResult;
 export type PhysicsCustomSpawnDatumResult = PhysicsDatumSpawnResult | PhysicsQueuedSpawn | PhysicsQueuedSpawn[];
-export interface PhysicsCustomChartProps<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> extends Omit<BaseChartProps, "margin">, PhysicsSharedChartProps {
+export interface PhysicsCustomChartProps<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> extends Omit<BaseChartProps, "margin" | "selection">, PhysicsSharedChartProps {
     data?: TDatum[];
     layout: PhysicsCustomLayout<TDatum, TConfig>;
     /**

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

@@ -1,12 +1,12 @@
 import * as React from "react";
-import { type PhysicsBodySelection, type StreamPhysicsFrameProps } from "../../stream/physics/StreamPhysicsFrame";
+import { type StreamPhysicsFrameProps } from "../../stream/physics/StreamPhysicsFrame";
 import { type CapacityQueueSnapshot } from "../../stream/physics/PhysicsControllers";
 import { type ProcessChromeOptions } from "../../recipes/processChrome";
 import type { Datum } from "../shared/datumTypes";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type ProcessFlowProjectionMetadata, type ProcessFlowStageDef } from "./physicsChartUtils";
 import { type PhysicsFrameHandle } from "./physicsHocHandle";
-import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type TooltipProp } from "./physicsHocUtils";
+import { type PhysicsHocFrameProps, type PhysicsRerunMS, type PhysicsSharedChartProps, type TooltipProp } from "./physicsHocUtils";
 export type { ProcessFlowStageDef, ProcessFlowProjectionMetadata };
 export interface ProcessFlowChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "selection">, PhysicsSharedChartProps {
     data?: TDatum[];
@@ -35,6 +35,11 @@ export interface ProcessFlowChartProps<TDatum extends Datum = Datum> extends Omi
     springDamping?: number;
     tooltip?: TooltipProp;
     paused?: boolean;
+    /**
+     * Replay the seeded simulation this many milliseconds after it settles.
+     * Omit or pass `null` for a single run; `0` replays on the next timer turn.
+     */
+    rerunMS?: PhysicsRerunMS;
     initialSpawnPacing?: StreamPhysicsFrameProps["initialSpawnPacing"];
     /**
      * When true (default), stages with `capacity` install live FIFO queue
@@ -43,8 +48,6 @@ export interface ProcessFlowChartProps<TDatum extends Datum = Datum> extends Omi
     liveCapacity?: boolean;
     /** Live capacity metrics callback (queue depth, processed count per region). */
     onCapacityChange?: (stats: CapacityQueueSnapshot[]) => void;
-    /** Shared selection (process body restyle without relayout). */
-    selection?: PhysicsBodySelection | null;
     /**
      * Soft body budget: caps live bodies via pipeline bodyLimit (evict oldest).
      * Use for infinite/long streams with sediment-style history in the readout.

package/dist/components/charts/physics/{PhysicalFlowChart.capability.d.ts → UnitPileChart.capability.d.ts}

@@ -1,2 +1,2 @@
 import type { ChartCapability } from "../../ai/chartCapabilityTypes";
-export declare const PhysicalFlowChartCapability: ChartCapability;
+export declare const UnitPileChartCapability: ChartCapability;

package/dist/components/charts/physics/{PhysicsPileChart.d.ts → UnitPileChart.d.ts}

@@ -3,8 +3,8 @@ import type { Datum } from "../shared/datumTypes";
 import type { BaseChartProps, ChartAccessor, ChartMode } from "../shared/types";
 import type { StyleRule } from "../shared/styleRules";
 import { type PhysicsFrameHandle } from "./physicsHocHandle";
-import { type PhysicsHocFrameProps, type PhysicsSharedChartProps, type PhysicsSimulationMode, type TooltipProp } from "./physicsHocUtils";
-export interface PhysicsPileChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "mode">, PhysicsSharedChartProps {
+import { type PhysicsHocFrameProps, type PhysicsRerunMS, type PhysicsSharedChartProps, type PhysicsSimulationMode, type TooltipProp } from "./physicsHocUtils";
+export interface UnitPileChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "mode" | "selection">, PhysicsSharedChartProps {
     data?: TDatum[];
     size?: [number, number];
     categoryAccessor?: ChartAccessor<TDatum, string>;
@@ -30,15 +30,22 @@ export interface PhysicsPileChartProps<TDatum extends Datum = Datum> extends Omi
     showProjection?: boolean;
     sediment?: boolean;
     tooltip?: TooltipProp;
+    /**
+     * Replay the seeded simulation this many milliseconds after it settles.
+     * Omit or pass `null` for a single run; `0` replays on the next timer turn.
+     */
+    rerunMS?: PhysicsRerunMS;
     paused?: boolean;
     frameProps?: PhysicsHocFrameProps<"config">;
 }
+/** @deprecated Renamed to {@link UnitPileChartProps} in 3.9.0. */
+export type PhysicsPileChartProps<TDatum extends Datum = Datum> = UnitPileChartProps<TDatum>;
 /**
  * Physics-backed unit pile chart that converts category values into repeated bodies and a readable settled projection.
  *
  * @example
  * ```tsx
- * <PhysicsPileChart
+ * <UnitPileChart
  *   data={[{ category: "A", value: 12 }, { category: "B", value: 8 }]}
  *   categoryAccessor="category"
  *   valueAccessor="value"
@@ -48,7 +55,7 @@ export interface PhysicsPileChartProps<TDatum extends Datum = Datum> extends Omi
  *
  * @example
  * ```tsx
- * <PhysicsPileChart
+ * <UnitPileChart
  *   mode="mechanical"
  *   mechanicalCategories={["North", "South", "West"]}
  *   mechanicalCount={90}
@@ -56,5 +63,11 @@ export interface PhysicsPileChartProps<TDatum extends Datum = Datum> extends Omi
  * />
  * ```
  */
-export declare const PhysicsPileChart: React.ForwardRefExoticComponent<PhysicsPileChartProps<Datum> & React.RefAttributes<PhysicsFrameHandle>>;
-export default PhysicsPileChart;
+export declare const UnitPileChart: React.ForwardRefExoticComponent<UnitPileChartProps<Datum> & React.RefAttributes<PhysicsFrameHandle>>;
+/**
+ * @deprecated Renamed to {@link UnitPileChart} in 3.9.0. Unitizes category values into countable bodies; the substrate is an implementation detail, not the reading.
+ * The alias stays exported indefinitely for existing imports; new code and
+ * every registry (schema, capabilities, MCP, server configs) use `UnitPileChart`.
+ */
+export declare const PhysicsPileChart: React.ForwardRefExoticComponent<UnitPileChartProps<Datum> & React.RefAttributes<PhysicsFrameHandle>>;
+export default UnitPileChart;

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

@@ -32,7 +32,7 @@ export type CrucibleSnapshotAt = number | {
     progress?: number;
 };
 export type CrucibleColorBy<TDatum extends Datum = Datum> = "category" | "status" | "outlet" | "product" | ChartAccessor<TDatum, string>;
-export interface CrucibleChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "onClick">, PhysicsSharedChartProps {
+export interface CrucibleChartProps<TDatum extends Datum = Datum> extends Omit<BaseChartProps, "margin" | "onClick" | "selection">, PhysicsSharedChartProps {
     /** Controlled, bounded source charge. CrucibleChart has no live push API. */
     data: TDatum[];
     /** Ordered furnace program. Every phase must have a unique id and duration. */

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

@@ -0,0 +1,9 @@
+import type { Datum } from "../shared/datumTypes";
+import type { CrucibleColorBy, CrucibleControls } from "./crucibleChartProps";
+import type { CrucibleComponentState, CrucibleRunState } from "./crucibleTypes";
+export declare function numericCrucibleSeed(seed: number | string | undefined): number;
+export declare function boundedCruciblePlaybackRate(value: unknown): number;
+export declare function resolveCrucibleControls(controls: boolean | CrucibleControls | undefined): Required<CrucibleControls>;
+export declare function crucibleColorKey<TDatum extends Datum>(component: CrucibleComponentState<TDatum>, colorBy: CrucibleColorBy<TDatum>, index: number): string;
+export declare function crucibleColorForKey(key: string): string;
+export declare function crucibleStateSummary<TDatum extends Datum>(state: CrucibleRunState<TDatum>, amountLabel?: string): string;