semiotic 3.8.5 → 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/custom/XYCustomChart.d.ts

@@ -7,6 +7,7 @@ import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types"
 import type { TooltipProp } from "../../Tooltip/Tooltip";
 import type { ChartRecipe } from "../../ai/chartRecipes";
 import type { LegendValue } from "../../types/legendTypes";
+import type { LegendInteractionMode, LegendPosition } from "../shared/useChartLegend";
 export interface XYCustomChartProps<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> extends BaseChartProps, AxisConfig {
     /** Data passed through to LayoutContext.data. */
     data?: TDatum[];
@@ -34,6 +35,8 @@ export interface XYCustomChartProps<TDatum extends Datum = Datum, TConfig extend
     showLegend?: boolean;
     /** Additional legend content. Categorical groups follow the inferred colorBy legend. */
     legend?: LegendValue;
+    legendInteraction?: LegendInteractionMode;
+    legendPosition?: LegendPosition;
     annotations?: Datum[];
     /** Field or function that declares the semantic category used for custom-layout color. */
     colorBy?: ChartAccessor<TDatum, string>;

package/dist/components/charts/geo/DistanceCartogram.d.ts

@@ -25,7 +25,7 @@ export interface DistanceCartogramProps<TDatum extends Datum = Datum> extends Ba
     center: string;
     /** Cost/distance accessor — numeric field or function */
     costAccessor: string | ((d: Datum) => number);
-    /** Interpolation between geographic (0) and cartogram (1) @default 1 */
+    /** Interpolation between geographic (0) and cartogram (1), clamped to [0, 1]. @default 1 */
     strength?: number;
     /** Line rendering mode @default "straight" */
     lineMode?: "straight" | "fractional";

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

@@ -12,8 +12,11 @@ export { ConnectedScatterplot } from "./xy/ConnectedScatterplot";
 export type { ConnectedScatterplotProps } from "./xy/ConnectedScatterplot";
 export { LineChart } from "./xy/LineChart";
 export type { LineChartProps } from "./xy/LineChart";
+export { BumpChart, rankBumpData } from "./xy/BumpChart";
+export type { BumpChartProps, RankedBumpData, RankedBumpDatum, RankBumpDataOptions, } from "./xy/BumpChart";
 export { AreaChart } from "./xy/AreaChart";
 export type { AreaChartProps, SemanticGradientStop } from "./xy/AreaChart";
+export type { GradientConfig, GradientStop, SemanticGradientInput, } from "./shared/gradient";
 export { DifferenceChart } from "./xy/DifferenceChart";
 export type { DifferenceChartProps } from "./xy/DifferenceChart";
 export { StackedAreaChart } from "./xy/StackedAreaChart";
@@ -100,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";
@@ -117,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/ordinal/BarChart.d.ts

@@ -7,6 +7,7 @@ import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import { type StyleRule } from "../shared/styleRules";
 import { type RegressionProp } from "../shared/regressionUtils";
+import { type GradientInput } from "../shared/gradient";
 /**
  * BarChart component props
  */
@@ -64,24 +65,16 @@ export interface BarChartProps<TDatum extends Datum = Datum> extends BaseChartPr
     /** Rounded top corner radius in pixels. Only the end away from the baseline is rounded. */
     roundedTop?: number;
     /**
-     * Gradient fill from the bar's tip (opposite the baseline) toward its base.
-     * - `true` — default opacity fade (80% → 5% of the resolved fill color).
-     * - `{ topOpacity, bottomOpacity }` — explicit opacity stops on the resolved fill.
-     * - `{ colorStops: [{offset, color}, ...] }` — arbitrary multi-color gradient.
-     *
+     * Gradient fill from the bar's tip (offset 0) toward its base (offset 1).
+     * Stops can set `color`, `opacity`, or both. Omit a stop color to inherit
+     * the resolved bar color.
+     * @example
+     * `{ stops: [{ offset: 0, opacity: 0.8 }, { offset: 1, opacity: 0.05 }] }`
      * Direction follows the bar's orientation (vertical/horizontal) and sign
      * (positive/negative bars). Same API as `AreaChart.gradientFill`.
      * @default false
      */
-    gradientFill?: boolean | {
-        topOpacity: number;
-        bottomOpacity: number;
-    } | {
-        colorStops: Array<{
-            offset: number;
-            color: string;
-        }>;
-    };
+    gradientFill?: GradientInput;
     /**
      * Declarative, threshold-aware bar styling. An ordered list of
      * `{ when, style }` rules; every rule whose condition matches a bar

package/dist/components/charts/ordinal/GaugeChart.d.ts

@@ -25,6 +25,9 @@ export interface GaugeChartProps extends BaseChartProps {
     /**
      * Arc-length gradient for the gauge band.
      *
+     * Offset 0 is the sweep start and offset 1 is the sweep end. Stops can set
+     * `color`, `opacity`, or both.
+     *
      * The gradient is sampled along the visible filled arc from sweep start
      * toward the current value. If `fillZones` is false, the entire arc uses
      * the gradient. If `fillZones` is true, the unfilled remainder stays on

package/dist/components/charts/ordinal/GroupedBarChart.d.ts

@@ -6,6 +6,7 @@ import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import { type StyleRule } from "../shared/styleRules";
 import type { RealtimeFrameHandle } from "../../realtime/types";
+import { type GradientInput } from "../shared/gradient";
 export interface GroupedBarChartProps<TDatum extends Datum = Datum> extends BaseChartProps {
     data?: TDatum[];
     categoryAccessor?: ChartAccessor<TDatum, string>;
@@ -22,6 +23,8 @@ export interface GroupedBarChartProps<TDatum extends Datum = Datum> extends Base
     barPadding?: number;
     /** Rounded corner radius on bar ends (away from baseline). */
     roundedTop?: number;
+    /** Tip-to-base bar gradient using `{ stops: [{ offset, color?, opacity? }] }`. */
+    gradientFill?: GradientInput;
     /**
      * Declarative, threshold-aware bar styling. Ordered `{ when, style }`
      * rules; the last applicable rule wins per property. `when` accepts a

package/dist/components/charts/ordinal/StackedBarChart.d.ts

@@ -6,6 +6,7 @@ import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import { type StyleRule } from "../shared/styleRules";
+import { type GradientInput } from "../shared/gradient";
 export interface StackedBarChartProps<TDatum extends Datum = Datum> extends BaseChartProps {
     data?: TDatum[];
     categoryAccessor?: ChartAccessor<TDatum, string>;
@@ -23,6 +24,8 @@ export interface StackedBarChartProps<TDatum extends Datum = Datum> extends Base
     barPadding?: number;
     /** Rounded top corner radius. Only the topmost stacked segment gets rounded. */
     roundedTop?: number;
+    /** Tip-to-base segment gradient using `{ stops: [{ offset, color?, opacity? }] }`. */
+    gradientFill?: GradientInput;
     /**
      * Declarative, threshold-aware segment styling. Ordered `{ when, style }`
      * rules; the last applicable rule wins per property. `when` accepts a

package/dist/components/charts/ordinal/SwimlaneChart.d.ts

@@ -5,6 +5,7 @@ import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
+import { type GradientInput } from "../shared/gradient";
 export interface SwimlaneChartProps<TDatum extends Datum = Datum> extends BaseChartProps {
     /** Data array. Omit for push API mode. */
     data?: TDatum[];
@@ -61,20 +62,9 @@ export interface SwimlaneChartProps<TDatum extends Datum = Datum> extends BaseCh
     rTickValues?: number[];
     /** Align first value tick label to start, last to end. Prevents clipping at chart edges. */
     tickLabelEdgeAlign?: boolean;
-    /** Gradient fill for swimlane segments. `true` uses tip→base opacity ramp;
-     *  pass `{ topOpacity, bottomOpacity }` for a uniform alpha gradient or
-     *  `{ colorStops }` for a multi-stop color ramp. Same shape as
-     *  BarChart.gradientFill / AreaChart.gradientFill. The gradient runs along
-     *  the lane's growth direction (left→right horizontal, bottom→top vertical). */
-    gradientFill?: boolean | {
-        topOpacity: number;
-        bottomOpacity: number;
-    } | {
-        colorStops: Array<{
-            offset: number;
-            color: string;
-        }>;
-    };
+    /** Gradient fill along the lane's growth direction. Offset 0 is the tip
+     *  and offset 1 is the base. Stops can set `color`, `opacity`, or both. */
+    gradientFill?: GradientInput;
     /** Lane "track" fill — a rect drawn behind each lane spanning the full
      *  value-axis range, sized to the lane's bandwidth. Lets budget/progress
      *  lanes read as filled vs. empty. Pass a color string (CSS vars

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;