semiotic 3.8.4 → 3.8.6

package/dist/chunk-chunk-ZXIXAPRE.module.min.js

@@ -0,0 +1,2 @@
+"use client";
+var t=/^\d{4}-\d{1,2}$/;function e(e){const n=e.trim();if(!n||!Number.isNaN(Number(n)))return NaN;const r=t.test(n)?n+"-01":n;if(r===n&&10>n.length)return NaN;const i=Date.parse(r);return Number.isFinite(i)?i:NaN}function n(t){return t instanceof Date?t.getTime():"string"==typeof t?e(t):+t}export{e as parseDateLikeString,n as coerceDateLikeValue};

package/dist/components/ChartContainer.d.ts

@@ -4,6 +4,8 @@ import { type DescribeLevel } from "./ai/describeChart";
 import type { ChartMode, MobileInteractionProp } from "./charts/shared/types";
 import { type MobileStandardControlRequest, type MobileStandardControlsProps } from "./MobileStandardControls";
 import { type MobileVisualizationContract } from "./charts/shared/auditMobileVisualization";
+import type { ChartContainerDataAudit } from "./chartContainerDataAudit";
+export type { ChartContainerDataAudit, ChartContainerDataAuditOptions } from "./chartContainerDataAudit";
 export type ChartNotificationLevel = "info" | "success" | "warning" | "error" | "neutral";
 /**
  * One entry in a ChartContainer's notification stack — chart-level context
@@ -131,6 +133,14 @@ export interface ChartContainerProps {
      * so notifications that arrive while streaming are announced.
      */
     notifications?: ChartNotification[];
+    /**
+     * Run Semiotic's numeric input audit over `chartConfig.props` and merge its
+     * findings into the notification bell. Re-evaluates when the config/data
+     * identity changes. Ref-only push mutations are intentionally not observable
+     * here; audit a bounded stream snapshot and pass its notifications instead.
+     * Requires `chartConfig`.
+     */
+    dataAudit?: ChartContainerDataAudit;
     /**
      * Called when a notification's dismiss button is clicked. Dismissal state
      * is tracked internally (keyed by `notification.id`, falling back to array

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

@@ -1,6 +1,7 @@
 import type { ChartCapability } from "./chartCapabilityTypes";
 import { LineChartCapability } from "../charts/xy/LineChart.capability";
 import { AreaChartCapability } from "../charts/xy/AreaChart.capability";
+import { BumpChartCapability } from "../charts/xy/BumpChart.capability";
 import { StackedAreaChartCapability } from "../charts/xy/StackedAreaChart.capability";
 import { ScatterplotCapability } from "../charts/xy/Scatterplot.capability";
 import { ConnectedScatterplotCapability } from "../charts/xy/ConnectedScatterplot.capability";
@@ -45,6 +46,7 @@ import { CollisionSwarmChartCapability } from "../charts/physics/CollisionSwarmC
 import { PhysicalFlowChartCapability } from "../charts/physics/PhysicalFlowChart.capability";
 import { ProcessFlowChartCapability } from "../charts/physics/ProcessFlowChart.capability";
 import { GauntletChartCapability } from "../charts/physics/GauntletChart.capability";
+import { CrucibleChartCapability } from "../charts/physics/CrucibleChart.capability";
 /**
  * Register a capability for a chart (built-in or third-party). Re-registering by
  * component name replaces the previous descriptor — useful for overriding defaults.
@@ -59,4 +61,4 @@ export declare function unregisterChartCapability(component: string): void;
 export declare function getCapabilities(): ReadonlyArray<ChartCapability>;
 /** Look up a capability by component name. */
 export declare function getCapability(component: string): ChartCapability | undefined;
-export { LineChartCapability, AreaChartCapability, StackedAreaChartCapability, ScatterplotCapability, ConnectedScatterplotCapability, BubbleChartCapability, QuadrantChartCapability, MultiAxisLineChartCapability, MinimapChartCapability, DifferenceChartCapability, CandlestickChartCapability, HeatmapCapability, BarChartCapability, GroupedBarChartCapability, StackedBarChartCapability, DotPlotCapability, PieChartCapability, DonutChartCapability, FunnelChartCapability, GaugeChartCapability, LikertChartCapability, SwimlaneChartCapability, HistogramCapability, BoxPlotCapability, SwarmPlotCapability, ViolinPlotCapability, RidgelinePlotCapability, ForceDirectedGraphCapability, SankeyDiagramCapability, ChordDiagramCapability, ProcessSankeyCapability, TreeDiagramCapability, TreemapCapability, CirclePackCapability, OrbitDiagramCapability, ChoroplethMapCapability, ProportionalSymbolMapCapability, FlowMapCapability, DistanceCartogramCapability, GaltonBoardChartCapability, EventDropChartCapability, PhysicsPileChartCapability, CollisionSwarmChartCapability, PhysicalFlowChartCapability, ProcessFlowChartCapability, GauntletChartCapability, };
+export { LineChartCapability, AreaChartCapability, BumpChartCapability, StackedAreaChartCapability, ScatterplotCapability, ConnectedScatterplotCapability, BubbleChartCapability, QuadrantChartCapability, MultiAxisLineChartCapability, MinimapChartCapability, DifferenceChartCapability, CandlestickChartCapability, HeatmapCapability, BarChartCapability, GroupedBarChartCapability, StackedBarChartCapability, DotPlotCapability, PieChartCapability, DonutChartCapability, FunnelChartCapability, GaugeChartCapability, LikertChartCapability, SwimlaneChartCapability, HistogramCapability, BoxPlotCapability, SwarmPlotCapability, ViolinPlotCapability, RidgelinePlotCapability, ForceDirectedGraphCapability, SankeyDiagramCapability, ChordDiagramCapability, ProcessSankeyCapability, TreeDiagramCapability, TreemapCapability, CirclePackCapability, OrbitDiagramCapability, ChoroplethMapCapability, ProportionalSymbolMapCapability, FlowMapCapability, DistanceCartogramCapability, GaltonBoardChartCapability, EventDropChartCapability, PhysicsPileChartCapability, CollisionSwarmChartCapability, PhysicalFlowChartCapability, ProcessFlowChartCapability, GauntletChartCapability, CrucibleChartCapability };

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

@@ -1,5 +1,7 @@
 import type { Datum } from "../charts/shared/datumTypes";
 import type { DataSummary } from "../data/DataSummarizer";
+import type { NumericContracts } from "../data/numericContracts";
+import type { NumericFieldProfile } from "../data/auditData";
 import type { IntentId } from "./intents";
 import type { ChartRecipe, ChartRecipeFrameFamily, MobileDesignDefinition } from "./chartRecipes";
 import type { ScaleFitFn, QualityFitFn, ScaleBand, CardinalityBand, EffectiveScale } from "./dataScaleProfile";
@@ -52,6 +54,12 @@ export interface FieldCandidate {
 export interface ChartDataProfile extends DataSummary {
     /** Original rows (read-only); used by capabilities to compute their own stats. */
     data: ReadonlyArray<Datum>;
+    /**
+     * Per-field numeric health, including invalid/missing counts and extrema.
+     * Unlike `fields`, categorical values assigned to a numeric role remain
+     * visible here as `nonNumericCount` rather than being silently discarded.
+     */
+    numericFields?: Readonly<Record<string, NumericFieldProfile>>;
     /** Candidate fields per role, sorted best-first. */
     candidates: {
         x: FieldCandidate[];
@@ -183,6 +191,12 @@ export interface ChartCapability {
     importPath: ChartImportPath;
     /** Base rubric, before variant/profile adjustments. */
     rubric: ChartRubric;
+    /**
+     * JSON-safe Semiotic runtime declaration of the numeric assumptions this
+     * chart makes about accessor-bound data. Consumed by `auditData` and
+     * `diagnoseConfig`; not part of the library-neutral IDID v0.1 subset.
+     */
+    numericContracts?: NumericContracts;
     /**
      * Hard requirements gate. Return null if the chart can render this profile,
      * or a human-readable string explaining why not (e.g. "no numeric y candidate").

package/dist/components/chartContainerDataAudit.d.ts

@@ -0,0 +1,10 @@
+import type { ChartNotification } from "./ChartContainer";
+import type { ChartConfig } from "./export/chartConfig";
+import { type DataAuditNotificationOptions } from "./data/dataAuditPresentation";
+import type { AuditDataOptions } from "./data/auditData";
+export interface ChartContainerDataAuditOptions extends Pick<AuditDataOptions, "checkOutliers">, DataAuditNotificationOptions {
+}
+export type ChartContainerDataAudit = boolean | ChartContainerDataAuditOptions;
+type AuditableChartConfig = Pick<ChartConfig, "component" | "props">;
+export declare function buildChartDataAuditNotifications(chartConfig: AuditableChartConfig | undefined, dataAudit: ChartContainerDataAudit | undefined): ChartNotification[];
+export {};

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";
@@ -79,11 +79,16 @@ export interface DistanceCartogramProps<TDatum extends Datum = Datum> extends Ba
     tileAttribution?: string;
     /** Max cached tiles @default 256 */
     tileCacheSize?: number;
-    /** Show concentric distance rings around center. @default true */
+    /**
+     * Cost reference marks.
+     * - Radial layout: concentric rings around center.
+     * - Strip (sparkline) layout: baseline tick marks on the cost axis.
+     * @default true (radial); true as axis ticks in sparkline
+     */
     showRings?: boolean | number | number[];
     /** Show numeric labels on distance rings. Defaults to false in context and sparkline modes. */
     showRingLabels?: boolean;
-    /** Ring style overrides */
+    /** Ring / strip-tick style overrides */
     ringStyle?: {
         stroke?: string;
         strokeWidth?: number;
@@ -95,6 +100,11 @@ export interface DistanceCartogramProps<TDatum extends Datum = Datum> extends Ba
     showNorth?: boolean;
     /** Label for cost units shown on rings (e.g. "hrs", "km") */
     costLabel?: string;
+    /**
+     * Cartogram layout encoding. Defaults to `"strip"` (1D Langren cost axis)
+     * in sparkline mode and `"radial"` otherwise.
+     */
+    cartogramLayout?: "radial" | "strip";
     /** Annotations */
     annotations?: Datum[];
     /** Passthrough */
@@ -107,7 +117,10 @@ export interface DistanceCartogramProps<TDatum extends Datum = Datum> extends Ba
  * proportional to `costAccessor` (commute time, fare, hops, etc.) rather
  * than great-circle distance. `strength` interpolates between the
  * geographic positions (0) and the fully-distorted cartogram (1).
- * Concentric rings show iso-cost contours by default.
+ * Concentric rings show iso-cost contours by default. In `mode="sparkline"`
+ * the chart collapses to a Langren-style 1D cost strip (origin at left,
+ * cost growing right) so dense estimates of the same distance stay legible
+ * without map chrome.
  *
  * @example
  * ```tsx
@@ -147,6 +160,19 @@ export interface DistanceCartogramProps<TDatum extends Datum = Datum> extends Ba
  *   lineMode="fractional"
  * />
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Sparkline: Langren-style 1D cost strip (origin left, cost right)
+ * <DistanceCartogram
+ *   points={estimates}
+ *   center="Toledo"
+ *   costAccessor="degrees"
+ *   mode="sparkline"
+ *   width={160}
+ *   height={28}
+ * />
+ * ```
  */
 export declare const DistanceCartogram: {
     <TDatum extends Datum = Datum>(props: DistanceCartogramProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;

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";
@@ -104,6 +107,7 @@ export { PhysicsPileChart } from "./physics/PhysicsPileChart";
 export type { PhysicsPileChartProps } from "./physics/PhysicsPileChart";
 export { CollisionSwarmChart } from "./physics/CollisionSwarmChart";
 export type { CollisionSwarmChartProps } from "./physics/CollisionSwarmChart";
+export * from "./physics/CrucibleChart";
 export { GauntletChart, GuantletChart, planGauntletPropertyWork, replaceGauntletNegative } from "./physics/GauntletChart";
 export type { GauntletChartProps, GauntletEffect, GauntletEvent, GauntletEventContext, GauntletEventLogItem, GauntletGate, GauntletLayout, GauntletNegativeReplacementOptions, GauntletPopSpec, GauntletProjectPlacement, GauntletProjectState, GauntletPropertyForceContext, GauntletPropertyDefinition, GauntletPropertyWorkPlan, GauntletPropertyWorkPlanOptions } from "./physics/GauntletChart";
 export { physicsProcessBoundaryColliders, physicsProcessGroupSemanticItems, physicsProcessRegionSemanticItem, physicsProcessStageSemanticItems } from "./physics/physicsProcessPrimitives";

package/dist/components/charts/network/ForceDirectedGraph.d.ts

@@ -90,13 +90,48 @@ export interface ForceDirectedGraphProps<TNode extends Datum = Datum, TEdge exte
      * @default [5, 20]
      */
     nodeSizeRange?: [number, number];
+    /**
+     * Outline color for **node** marks only, leaving edges untouched — the
+     * node half of independent node/edge stroking (the edge half is
+     * {@link ForceDirectedGraphProps.edgeColor}). Overrides the generic
+     * {@link BaseChartProps.stroke} for nodes; pass `"none"` to remove the
+     * default node outline. Precedence per property: `nodeStroke` > `stroke`
+     * > the built-in node outline.
+     * @example
+     * ```tsx
+     * // Ringless nodes, blue edges — styled separately
+     * <ForceDirectedGraph nodeStroke="none" edgeColor="#4c78a8" />
+     * // White node ring, unchanged edges
+     * <ForceDirectedGraph nodeStroke="#fff" nodeStrokeWidth={1.5} />
+     * ```
+     */
+    nodeStroke?: string;
+    /**
+     * Outline width for **node** marks only. Overrides the generic
+     * {@link BaseChartProps.strokeWidth} for nodes.
+     * @default the generic `strokeWidth`
+     */
+    nodeStrokeWidth?: number;
     /**
      * Constant pixel width, or a function/field returning a numeric value
-     * scaled to a default width range.
+     * scaled to a default width range. The **edge** stroke width; overrides
+     * the generic `strokeWidth` for edges.
      * @default 1
      */
     edgeWidth?: number | ChartAccessor<TEdge, number>;
+    /**
+     * Stroke color for **edge** marks only, leaving nodes untouched — the edge
+     * half of independent node/edge stroking (the node half is
+     * {@link ForceDirectedGraphProps.nodeStroke}). Overrides the generic
+     * {@link BaseChartProps.stroke} for edges. Precedence per property:
+     * `edgeColor` > `stroke` > the built-in `#999`.
+     * @default "#999"
+     */
     edgeColor?: string;
+    /**
+     * Opacity for **edge** marks only. Overrides the generic `opacity` for edges.
+     * @default 0.6
+     */
     edgeOpacity?: number;
     /**
      * Number of force-simulation ticks before the layout settles.

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/CrucibleChart.capability.d.ts

@@ -0,0 +1,8 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+/**
+ * CrucibleChart is intentionally known to the AI surface but never selected
+ * from a flat data profile. A valid chart needs an authored treatment program,
+ * declared products, and explicit destinations that dataset profiling cannot
+ * responsibly invent.
+ */
+export declare const CrucibleChartCapability: ChartCapability;

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

@@ -0,0 +1,63 @@
+import * as React from "react";
+import type { Datum } from "../shared/datumTypes";
+import type { CrucibleChartHandle, CrucibleChartProps } from "./crucibleChartProps";
+export * from "./crucibleTypes";
+export * from "./crucibleProgram";
+export { applyCrucibleEvent, buildCrucibleEvidence, buildCrucibleProjection, cloneCrucibleState, crucibleProjectionRows, evaluateCrucibleConservation, resolveCrucibleSelector } from "./crucibleEffects";
+export { DEFAULT_CRUCIBLE_HEIGHT, DEFAULT_CRUCIBLE_OUTLETS, DEFAULT_CRUCIBLE_SIZE, DEFAULT_CRUCIBLE_WIDTH, buildCrucibleInitialSpawns, buildCrucibleLayout, buildCruciblePhysicsConfig, buildCrucibleStateSpawns, buildCrucibleTerminalSpawns, compileCruciblePlan, createInitialCrucibleState, crucibleBoundaryColliders, crucibleBondId, crucibleComponentBodyId, crucibleProductBodyId, crucibleSemanticKey, replayCruciblePlan, resolveCrucibleSnapshotAt, resolveCrucibleTime } from "./cruciblePhysics";
+export type { CrucibleSelectorResult } from "./crucibleEffects";
+export type { CrucibleInitialStateResult, CrucibleResolvedTime, CrucibleSpawnOptions } from "./cruciblePhysics";
+export type { CrucibleChartHandle, CrucibleChartProps, CrucibleColorBy, CrucibleControls, CrucibleSnapshotAt } from "./crucibleChartProps";
+/**
+ * A bounded, deterministic treatment tape for peer components. Authored
+ * events own every semantic transition; physics only explains co-presence,
+ * agitation, binding, separation, and settling.
+ *
+ * @example One authored event forms and completes a declared product.
+ * ```tsx
+ * <CrucibleChart
+ *   data={[{ id: "crm", amount: 1 }, { id: "billing", amount: 1 }]}
+ *   phases={[{ id: "resolve", duration: 2, motion: "bind" }]}
+ *   products={[{ id: "golden-record", outletId: "published" }]}
+ *   outlets={[{ id: "published", side: "bottom" }]}
+ *   events={[{
+ *     id: "publish-record",
+ *     at: { phaseId: "resolve", progress: 0.7 },
+ *     effects: [{
+ *       type: "combine",
+ *       sourceIds: ["crm", "billing"],
+ *       productId: "golden-record",
+ *       complete: true
+ *     }]
+ *   }]}
+ *   idAccessor="id"
+ *   amountAccessor="amount"
+ * />
+ * ```
+ *
+ * @example Build an explicit lifecycle and replay it without remount state.
+ * ```tsx
+ * const chartRef = React.createRef<CrucibleChartHandle>()
+ * const events = buildCrucibleProductEvents({
+ *   productId: "finding",
+ *   form: { at: { time: 0.5 }, sourceIds: ["trace", "metric"] },
+ *   contributions: [{ at: { time: 1 }, sourceIds: ["experiment"] }],
+ *   complete: { at: { time: 1.5 }, outletId: "supported" }
+ * })
+ *
+ * <button onClick={() => chartRef.current?.replay()}>Replay</button>
+ * <CrucibleChart
+ *   ref={chartRef}
+ *   data={evidence}
+ *   phases={[{ id: "assay", duration: 2, motion: "mix" }]}
+ *   products={[{ id: "finding", outletId: "supported" }]}
+ *   outlets={[{ id: "supported", side: "bottom" }]}
+ *   events={events}
+ * />
+ * ```
+ */
+export declare const CrucibleChart: {
+    <TDatum extends Datum = Datum>(props: CrucibleChartProps<TDatum> & React.RefAttributes<CrucibleChartHandle<TDatum>>): React.ReactElement | null;
+    displayName?: string;
+};
+export default CrucibleChart;

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

@@ -0,0 +1,27 @@
+import * as React from "react";
+import type { Style } from "../../stream/types";
+import type { PhysicsBodyState } from "../../stream/physics/PhysicsKernel";
+import type { PhysicsSemanticItem } from "../../stream/physics/StreamPhysicsFrame";
+import type { Datum } from "../shared/datumTypes";
+import type { CrucibleComponentState, CrucibleProductState, CrucibleRunState } from "./crucibleTypes";
+export declare function displayNumber(value: number): string;
+export declare function componentDescription(component: CrucibleComponentState): string;
+export declare function productDescription(product: CrucibleProductState): string;
+/** Default accessible description for each live crucible body. */
+export declare function crucibleBodySemanticItem<TDatum extends Datum>(body: PhysicsBodyState, state: CrucibleRunState<TDatum>): false | Partial<PhysicsSemanticItem>;
+/** Canvas mark used when callers do not supply frameProps.renderBody. */
+export declare function drawCrucibleBody(ctx: CanvasRenderingContext2D, body: PhysicsBodyState, style: Style): void;
+/**
+ * SSR sibling of `drawCrucibleBody` — the same shadowed hexagon + inner ring
+ * for settled products, and highlight dot for source components, as an SVG
+ * fragment instead of canvas draw calls. Returns `undefined` for non-crucible
+ * bodies so the SVG renderer falls back to its default circle mark.
+ *
+ * `idPrefix` is the sanitized prefix the owning `PhysicsSettledSVG` document
+ * uses for its own ids — folded into this body's `<filter>` id so multiple
+ * settled Crucible SVGs on one page (SVG ids are document-global) can't
+ * collide and mis-apply each other's glow filter.
+ */
+export declare function drawCrucibleBodySVG(body: PhysicsBodyState, style: Style, index: number, idPrefix?: string): React.ReactNode | undefined;
+/** Draw supplied relations and committed source-to-product lineage. */
+export declare function drawCrucibleBonds<TDatum extends Datum>(ctx: CanvasRenderingContext2D, bodies: readonly PhysicsBodyState[], state: CrucibleRunState<TDatum>): void;

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

@@ -0,0 +1,90 @@
+/** Public, bounded CrucibleChart prop and imperative-handle contracts. */
+import type { StreamPhysicsFrameProps } from "../../stream/physics/StreamPhysicsFrame";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import type { PhysicsHocFrameProps, PhysicsRerunMS, PhysicsSharedChartProps, TooltipProp } from "./physicsHocUtils";
+import type { CrucibleComponentStatus, CrucibleConservationResult, CrucibleConservationSpec, CrucibleDiagnostic, CrucibleEvent, CrucibleMetricMap, CrucibleObservation, CrucibleOutlet, CruciblePhase, CrucibleProductDefinition, CrucibleProjectionSpec, CrucibleRunState } from "./crucibleTypes";
+export interface CrucibleChartHandle<TDatum extends Datum = Datum> {
+    play(): void;
+    pause(): void;
+    reset(): void;
+    /**
+     * Atomically restart the deterministic tape and play from its origin.
+     * Snapshot and reduced-motion renderers remain static at their configured
+     * snapshot instead of animating.
+     */
+    replay(): void;
+    /** Advance to and apply the next authored phase boundary. */
+    stepPhase(): void;
+    /** Resolve the complete bounded tape without animating intermediate time. */
+    settle(): void;
+    getCrucibleState(): CrucibleRunState<TDatum>;
+}
+export interface CrucibleControls {
+    playPause?: boolean;
+    reset?: boolean;
+    stepPhase?: boolean;
+    timeline?: boolean;
+    speed?: boolean;
+}
+export type CrucibleSnapshotAt = number | {
+    phaseId: string;
+    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 {
+    /** Controlled, bounded source charge. CrucibleChart has no live push API. */
+    data: TDatum[];
+    /** Ordered furnace program. Every phase must have a unique id and duration. */
+    phases: readonly CruciblePhase[];
+    products?: readonly CrucibleProductDefinition[];
+    outlets?: readonly CrucibleOutlet[];
+    events?: readonly CrucibleEvent[];
+    idAccessor?: ChartAccessor<TDatum, string>;
+    labelAccessor?: ChartAccessor<TDatum, string>;
+    categoryAccessor?: ChartAccessor<TDatum, string>;
+    amountAccessor?: ChartAccessor<TDatum, number>;
+    metricsAccessor?: ChartAccessor<TDatum, CrucibleMetricMap>;
+    initialStateAccessor?: ChartAccessor<TDatum, CrucibleComponentStatus>;
+    metrics?: CrucibleMetricMap;
+    amountLabel?: string;
+    conservation?: boolean | CrucibleConservationSpec;
+    projection?: CrucibleProjectionSpec;
+    /**
+     * Replay animates the tape; snapshot renders one deterministic instant.
+     * Reduced-motion renderers should use snapshot mode and default to the
+     * terminal state when `snapshotAt` is omitted.
+     */
+    playback?: "replay" | "snapshot";
+    snapshotAt?: CrucibleSnapshotAt;
+    controls?: boolean | CrucibleControls;
+    paused?: boolean;
+    /** Semantic program speed. 0.25 is quarter-speed; 2 is double-speed. */
+    playbackRate?: number;
+    /**
+     * Delay after settling before a fresh deterministic replay. `null` or an
+     * omitted value runs once; `0` schedules the reset on the next timer turn.
+     * Snapshot/reduced-motion rendering does not auto-rerun.
+     */
+    rerunMS?: PhysicsRerunMS;
+    size?: [number, number];
+    seed?: number | string;
+    /** Fixed source-body radius. Per-row radius accessors are outside bounded V1. */
+    bodyRadius?: number;
+    radiusRange?: [number, number];
+    colorBy?: CrucibleColorBy<TDatum>;
+    showBonds?: boolean;
+    showChrome?: boolean;
+    showProjection?: boolean;
+    frameProps?: PhysicsHocFrameProps<"bodyForces">;
+    initialSpawnPacing?: StreamPhysicsFrameProps["initialSpawnPacing"];
+    tooltip?: TooltipProp;
+    emptyContent?: BaseChartProps["emptyContent"];
+    loading?: BaseChartProps["loading"];
+    loadingContent?: BaseChartProps["loadingContent"];
+    onStateChange?: (state: CrucibleRunState<TDatum>) => void;
+    onCrucibleObservation?: (observation: CrucibleObservation) => void;
+    onDiagnostic?: (diagnostic: CrucibleDiagnostic) => void;
+    onConservation?: (result: CrucibleConservationResult) => void;
+    onClick?: (item: CrucibleRunState<TDatum>["components"][string] | CrucibleRunState<TDatum>["products"][string]) => void;
+}

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

@@ -0,0 +1,47 @@
+import * as React from "react";
+import type { Style } from "../../stream/types";
+import type { PhysicsBodyState } from "../../stream/physics/PhysicsKernel";
+import type { PhysicsBodyStyleContext, PhysicsHoverData, PhysicsSemanticItem } from "../../stream/physics/StreamPhysicsFrame";
+import type { Datum } from "../shared/datumTypes";
+import type { CrucibleLayout, CruciblePhase, CrucibleProjectionRow, CrucibleProjectionSpec, CrucibleRunState } from "./crucibleTypes";
+/** Default tooltip preserves the distinction between source and product. */
+export declare function defaultCrucibleTooltipContent<TDatum extends Datum>(hover: PhysicsHoverData, state: CrucibleRunState<TDatum>): React.ReactNode;
+/** Static vessel, program rail, and named exception/product outlets. */
+export declare function CrucibleChrome<TDatum extends Datum>({ layout, phases, state, compact }: {
+    layout: CrucibleLayout;
+    phases: readonly CruciblePhase[];
+    state: CrucibleRunState<TDatum>;
+    compact?: boolean;
+}): React.JSX.Element;
+export declare function crucibleProjectionSemanticItems(rows: readonly CrucibleProjectionRow[], layout: CrucibleLayout, projection: CrucibleProjectionSpec, amountLabel?: string): PhysicsSemanticItem[];
+/** Compact settled histogram; the ledger values, not body positions, set bars. */
+export declare function CrucibleProjectionOverlay({ rows, layout, projection, amountLabel }: {
+    rows: readonly CrucibleProjectionRow[];
+    layout: CrucibleLayout;
+    projection: CrucibleProjectionSpec;
+    amountLabel?: string;
+}): React.JSX.Element | null;
+export interface CrucibleReplayControlsProps {
+    controls: {
+        playPause: boolean;
+        reset: boolean;
+        stepPhase: boolean;
+        timeline: boolean;
+        speed: boolean;
+    };
+    duration: number;
+    elapsed: number;
+    phaseLabel: string;
+    playing: boolean;
+    complete: boolean;
+    playbackRate: number;
+    disabled?: boolean;
+    onPlayPause: () => void;
+    onReset: () => void;
+    onStepPhase: () => void;
+    onPlaybackRateChange: (rate: number) => void;
+}
+/** Optional in-chart replay controls; external controls can use the ref API. */
+export declare function CrucibleReplayControls({ controls, duration, elapsed, phaseLabel, playing, complete, playbackRate, disabled, onPlayPause, onReset, onStepPhase, onPlaybackRateChange }: CrucibleReplayControlsProps): React.JSX.Element;
+/** Merge default semantic styling with a caller's frame bodyStyle. */
+export declare function resolveCrucibleBodyStyle(defaultFill: string, body: PhysicsBodyState, context: PhysicsBodyStyleContext, bodyStyle: Style | ((body: PhysicsBodyState, context: PhysicsBodyStyleContext) => Style) | undefined): Style;