semiotic 3.8.4 → 3.8.6

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

@@ -0,0 +1,59 @@
+/**
+ * React-facing replay and motion helpers for CrucibleChart.
+ *
+ * The reducer tape remains authoritative. These helpers only advance that
+ * tape, reconcile its bounded body set, and steer marks toward ledger-derived
+ * targets. No collision or body position can create a semantic transition.
+ */
+import type { Datum } from "../shared/datumTypes";
+import type { PhysicsBodyState } from "../../stream/physics/PhysicsKernel";
+import type { PhysicsPipelineControlSurface, PhysicsQueuedSpawn } from "../../stream/physics/PhysicsPipelineStore";
+import type { StreamPhysicsRegionVector } from "../../stream/physics/StreamPhysicsFrame";
+import { type CrucibleSpawnOptions } from "./cruciblePhysics";
+import type { CrucibleCompiledPlan, CrucibleDiagnostic, CrucibleMaterialization, CrucibleObservation, CrucibleRunState } from "./crucibleTypes";
+import type { CrucibleSnapshotAt } from "./crucibleChartProps";
+export interface CrucibleRuntime<TDatum extends Datum = Datum> {
+    state: CrucibleRunState<TDatum>;
+    diagnostics: CrucibleDiagnostic[];
+    materializations: CrucibleMaterialization[];
+    observations: CrucibleObservation[];
+}
+/** Resolve a deterministic instant, defaulting snapshots to the terminal ledger. */
+export declare function crucibleSnapshotTime<TDatum extends Datum>(plan: CrucibleCompiledPlan<TDatum>, snapshotAt?: CrucibleSnapshotAt): number;
+/** Replay from origin. Used for reset, phase stepping, snapshots, and live ticks. */
+export declare function replayCrucibleRuntime<TDatum extends Datum>(plan: CrucibleCompiledPlan<TDatum>, throughTime: number, playing?: boolean): CrucibleRuntime<TDatum>;
+/**
+ * Return only observations/materializations that became newly visible between
+ * two instants. Replaying from origin stays deterministic without re-emitting
+ * earlier domain observations.
+ */
+export declare function advanceCrucibleRuntime<TDatum extends Datum>(plan: CrucibleCompiledPlan<TDatum>, previous: CrucibleRunState<TDatum>, throughTime: number, playing?: boolean): CrucibleRuntime<TDatum>;
+/** Inclusive end of the current authored phase, or the tape end. */
+export declare function nextCruciblePhaseBoundary<TDatum extends Datum>(plan: CrucibleCompiledPlan<TDatum>, elapsed: number): number;
+/** Canonical state marks for snapshots and newly materialized product cores. */
+export declare function crucibleStateSpawns<TDatum extends Datum>(plan: CrucibleCompiledPlan<TDatum>, state: CrucibleRunState<TDatum>, options?: CrucibleSpawnOptions): PhysicsQueuedSpawn[];
+/** Add only missing marks. Source component bodies are never deleted. */
+export declare function reconcileCrucibleBodies(controls: PhysicsPipelineControlSurface, desired: readonly PhysicsQueuedSpawn[]): string[];
+export interface CrucibleBodyTarget {
+    x: number;
+    y: number;
+}
+/** Map the pure state-spawn layout into semantic-id targets. */
+export declare function crucibleStateTargets<TDatum extends Datum>(plan: CrucibleCompiledPlan<TDatum>, state: CrucibleRunState<TDatum>, options?: CrucibleSpawnOptions): Map<string, CrucibleBodyTarget>;
+/**
+ * Ledger-derived target with phase motion layered on top. Motion may explain
+ * agitation/separation, but cannot alter the target state.
+ */
+export declare function targetForCrucibleBody<TDatum extends Datum>(options: {
+    body: PhysicsBodyState;
+    plan: CrucibleCompiledPlan<TDatum>;
+    state: CrucibleRunState<TDatum>;
+    targets: ReadonlyMap<string, CrucibleBodyTarget>;
+}): CrucibleBodyTarget | null;
+/** Damped attraction to a semantic target; deliberately no semantic side effects. */
+export declare function computeCrucibleBodyForce<TDatum extends Datum>(options: {
+    body: PhysicsBodyState;
+    plan: CrucibleCompiledPlan<TDatum>;
+    state: CrucibleRunState<TDatum>;
+    targets: ReadonlyMap<string, CrucibleBodyTarget>;
+}): StreamPhysicsRegionVector | null;

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

@@ -0,0 +1,30 @@
+/** Transactional, pure reducers and summaries for a bounded Crucible tape. */
+import type { Datum } from "../shared/datumTypes";
+import type { CrucibleApplyContext, CrucibleApplyResult, CrucibleConservationResult, CrucibleConservationSpec, CrucibleDiagnostic, CrucibleEvent, CrucibleHistoryItem, CrucibleProjectionRow, CrucibleProjectionSpec, CrucibleRunState, CrucibleSelector } from "./crucibleTypes";
+/** Clone mutable run structures while intentionally retaining source datum references. */
+export declare function cloneCrucibleState<TDatum extends Datum>(state: CrucibleRunState<TDatum>): CrucibleRunState<TDatum>;
+export interface CrucibleSelectorResult {
+    ids: string[];
+    diagnostics: CrucibleDiagnostic[];
+}
+/** Resolve a source selector with deterministic intersection semantics. */
+export declare function resolveCrucibleSelector<TDatum extends Datum>(state: CrucibleRunState<TDatum>, selector: CrucibleSelector, path?: string): CrucibleSelectorResult;
+/**
+ * Apply one event atomically. Any error rolls back all state,
+ * materializations, and observations produced by that event.
+ */
+export declare function applyCrucibleEvent<TDatum extends Datum>(state: CrucibleRunState<TDatum>, event: CrucibleEvent, context: CrucibleApplyContext): CrucibleApplyResult<TDatum>;
+/** Settled semantic rows; consumed source bodies are represented by products only. */
+export declare function buildCrucibleProjection<TDatum extends Datum>(state: CrucibleRunState<TDatum>, spec?: CrucibleProjectionSpec): CrucibleProjectionRow[];
+/** Normative projection-name alias used by server and AI chart builders. */
+export declare const crucibleProjectionRows: typeof buildCrucibleProjection;
+/** Products + still-independent components + declared loss must equal input. */
+export declare function evaluateCrucibleConservation<TDatum extends Datum>(state: CrucibleRunState<TDatum>, spec?: CrucibleConservationSpec): CrucibleConservationResult;
+export declare function buildCrucibleEvidence<TDatum extends Datum>(state: CrucibleRunState<TDatum>, options?: {
+    projection?: CrucibleProjectionSpec;
+    conservation?: CrucibleConservationSpec;
+}): {
+    history: CrucibleHistoryItem[];
+    projection: CrucibleProjectionRow[];
+    conservation: CrucibleConservationResult;
+};

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

@@ -0,0 +1,54 @@
+/** Deterministic compilation, replay, geometry, and bodies for CrucibleChart. */
+import type { Datum } from "../shared/datumTypes";
+import type { PhysicsPipelineConfig, PhysicsQueuedSpawn } from "../../stream/physics/PhysicsPipelineStore";
+import type { PhysicsColliderSpec } from "../../stream/physics/PhysicsKernel";
+import type { CrucibleCompileOptions, CrucibleCompiledPlan, CrucibleDiagnostic, CrucibleLayout, CrucibleOutlet, CrucibleReplayResult, CrucibleRunState } from "./crucibleTypes";
+export declare const DEFAULT_CRUCIBLE_WIDTH = 900;
+export declare const DEFAULT_CRUCIBLE_HEIGHT = 520;
+export declare const DEFAULT_CRUCIBLE_SIZE: [number, number];
+export declare const DEFAULT_CRUCIBLE_OUTLETS: readonly CrucibleOutlet[];
+export interface CrucibleInitialStateResult<TDatum extends Datum = Datum> {
+    state: CrucibleRunState<TDatum>;
+    diagnostics: CrucibleDiagnostic[];
+}
+/** Evaluate accessors once and create the immutable replay origin. */
+export declare function createInitialCrucibleState<TDatum extends Datum>(options: CrucibleCompileOptions<TDatum>): CrucibleInitialStateResult<TDatum>;
+/** Responsive authored regions shared by the live chart and snapshot renderer. */
+export declare function buildCrucibleLayout(size?: [number, number], outlets?: readonly CrucibleOutlet[]): CrucibleLayout;
+/** Chamber walls with outlet apertures, plus non-blocking outlet sensors. */
+export declare function crucibleBoundaryColliders(layout: CrucibleLayout): PhysicsColliderSpec[];
+export declare function buildCruciblePhysicsConfig(seed: number | string | undefined, colliders: readonly PhysicsColliderSpec[]): PhysicsPipelineConfig;
+export declare function crucibleComponentBodyId(componentId: string): string;
+export declare function crucibleProductBodyId(productId: string): string;
+export declare function crucibleBondId(productId: string, sourceId: string): string;
+export interface CrucibleSpawnOptions {
+    seed?: number | string;
+    bodyRadius?: number;
+    radiusRange?: [number, number];
+}
+/** Stable component bodies at the chamber charge point. */
+export declare function buildCrucibleInitialSpawns<TDatum extends Datum>(state: CrucibleRunState<TDatum>, layout: CrucibleLayout, options?: CrucibleSpawnOptions): PhysicsQueuedSpawn[];
+/**
+ * Stable terminal body set. Source body ids persist; product cores are added.
+ * Split sources target the centroid of their products.
+ */
+export declare function buildCrucibleStateSpawns<TDatum extends Datum>(state: CrucibleRunState<TDatum>, layout: CrucibleLayout, options?: CrucibleSpawnOptions): PhysicsQueuedSpawn[];
+/** Terminal-name alias retained for callers explicitly rendering the outcome. */
+export declare const buildCrucibleTerminalSpawns: typeof buildCrucibleStateSpawns;
+export declare function crucibleSemanticKey(value: unknown): string;
+export interface CrucibleResolvedTime {
+    elapsed: number;
+    phaseId: string;
+    phaseIndex: number;
+    phaseElapsed: number;
+    complete: boolean;
+}
+export declare function resolveCrucibleTime<TDatum extends Datum>(plan: Pick<CrucibleCompiledPlan<TDatum>, "phases" | "duration">, elapsed: number): CrucibleResolvedTime;
+export declare function resolveCrucibleSnapshotAt<TDatum extends Datum>(plan: Pick<CrucibleCompiledPlan<TDatum>, "phases" | "duration">, snapshotAt: number | {
+    phaseId: string;
+    progress?: number;
+} | undefined): number;
+/** Replay from the immutable origin through an inclusive authored time. */
+export declare function replayCruciblePlan<TDatum extends Datum>(plan: Pick<CrucibleCompiledPlan<TDatum>, "initialState" | "events" | "products" | "outlets" | "phases" | "duration">, throughTime?: number): CrucibleReplayResult<TDatum>;
+/** Compile and validate the full controlled tape, including a terminal dry run. */
+export declare function compileCruciblePlan<TDatum extends Datum>(options: CrucibleCompileOptions<TDatum>): CrucibleCompiledPlan<TDatum>;

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

@@ -0,0 +1,38 @@
+/** Pure authoring helpers for explicit Crucible event tapes. */
+import type { CrucibleEvent, CrucibleLoss } from "./crucibleTypes";
+/** Event metadata that remains wholly authored by the caller. */
+export type CrucibleEventStep = Pick<CrucibleEvent, "at" | "label" | "description" | "summary"> & {
+    /** Optional stable event id; a deterministic id is generated when omitted. */
+    id?: string;
+};
+/** Explicit sources admitted while a product is forming. */
+export interface CrucibleProductSourceStep extends CrucibleEventStep {
+    sourceIds: readonly string[];
+    basisRelationIds?: readonly string[];
+    loss?: CrucibleLoss;
+}
+/** Explicit completion and routing of an already-formed product. */
+export interface CrucibleProductCompletionStep extends CrucibleEventStep {
+    outletId?: string;
+    reason?: string;
+}
+export interface BuildCrucibleProductEventsOptions {
+    productId: string;
+    /** Prefix for generated event ids. Defaults to `productId`. */
+    idPrefix?: string;
+    /** Opens a forming product with a `combine` effect. */
+    form: CrucibleProductSourceStep;
+    /** Ordered later admissions, each represented by one `contribute` effect. */
+    contributions?: readonly CrucibleProductSourceStep[];
+    /** Required explicit completion; the helper never guesses when to pour. */
+    complete: CrucibleProductCompletionStep;
+}
+/**
+ * Build the canonical form -> contribute* -> complete lifecycle for one
+ * declared product.
+ *
+ * This is authoring sugar only. The caller supplies every source id,
+ * relation id, event position, product id, and outlet. The helper performs no
+ * grouping, inference, thresholding, or collision-derived classification.
+ */
+export declare function buildCrucibleProductEvents(options: BuildCrucibleProductEventsOptions): CrucibleEvent[];

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

@@ -0,0 +1,415 @@
+/**
+ * Pure domain contracts for CrucibleChart.
+ *
+ * A Crucible run is a bounded, controlled event tape. Source components are
+ * assigned to at most one product, while products may remain `forming` across
+ * several events before being completed and poured to an outlet.
+ */
+import type { Datum } from "../shared/datumTypes";
+import type { ChartAccessor } from "../shared/types";
+import type { PhysicsPipelineConfig, PhysicsQueuedSpawn } from "../../stream/physics/PhysicsPipelineStore";
+import type { PhysicsColliderSpec } from "../../stream/physics/PhysicsKernel";
+export type CrucibleComponentStatus = "queued" | "active" | "transformed" | "consumed" | "retained" | "ejected" | "failed" | "recovered";
+export type CrucibleProductStatus = "forming" | "complete";
+export type CrucibleMotion = "charge" | "mix" | "hold" | "press" | "bind" | "separate" | "pour" | "quench";
+export type CrucibleMetricMap = Record<string, number>;
+export interface CruciblePhase {
+    id: string;
+    duration: number;
+    label?: string;
+    description?: string;
+    intensity?: number;
+    motion?: CrucibleMotion;
+    color?: string;
+    metrics?: Record<string, string | number>;
+}
+export interface CrucibleOutlet {
+    id: string;
+    label?: string;
+    description?: string;
+    side?: "left" | "right" | "bottom";
+    color?: string;
+    order?: number;
+}
+/**
+ * Source-component selector. Supplied fields intersect; ids are resolved in
+ * lexical order before `count` is applied so fresh arrays replay identically.
+ */
+export interface CrucibleSelector {
+    ids?: readonly string[];
+    categories?: readonly string[];
+    statuses?: readonly CrucibleComponentStatus[];
+    outletIds?: readonly string[];
+    count?: number;
+}
+/** A declared mold. State is created only when an effect forms the product. */
+export interface CrucibleProductDefinition {
+    id: string;
+    label?: string;
+    description?: string;
+    category?: string;
+    /** Optional declared final amount, applied when the product completes. */
+    amount?: number;
+    color?: string;
+    metrics?: CrucibleMetricMap;
+    outletId?: string;
+    order?: number;
+}
+export interface CrucibleLoss {
+    amount?: number;
+    metrics?: CrucibleMetricMap;
+    label?: string;
+}
+export interface CrucibleRelationDefinition {
+    id: string;
+    sourceIds: readonly string[];
+    label?: string;
+    category?: string;
+    strength?: number;
+    metrics?: CrucibleMetricMap;
+}
+export type CrucibleRelationResolution = "combined" | "rejected" | "expired";
+export interface CrucibleRelationState extends CrucibleRelationDefinition {
+    status: "active" | "resolved";
+    createdByEventId: string;
+    createdAt: number;
+    resolution?: CrucibleRelationResolution;
+    resolvedByEventId?: string;
+    resolvedAt?: number;
+    reason?: string;
+}
+export interface CrucibleSetStateEffect {
+    type: "set-state";
+    select: CrucibleSelector;
+    state: Exclude<CrucibleComponentStatus, "consumed">;
+    outletId?: string;
+    reason?: string;
+    metricsDelta?: CrucibleMetricMap;
+}
+export interface CrucibleSetRelationEffect {
+    type: "set-relation";
+    relation: CrucibleRelationDefinition;
+}
+export interface CrucibleResolveRelationEffect {
+    type: "resolve-relation";
+    relationIds: readonly string[];
+    resolution: CrucibleRelationResolution;
+    reason?: string;
+}
+export interface CrucibleCombineEffect {
+    type: "combine";
+    sourceIds: readonly string[];
+    productId: string;
+    basisRelationIds?: readonly string[];
+    loss?: CrucibleLoss;
+    /** Defaults to true. Set false to admit later `contribute` effects. */
+    complete?: boolean;
+}
+export interface CrucibleContributeEffect {
+    type: "contribute";
+    sourceIds: readonly string[];
+    productId: string;
+    basisRelationIds?: readonly string[];
+    loss?: CrucibleLoss;
+}
+export interface CrucibleCompleteProductEffect {
+    type: "complete-product";
+    productId: string;
+    outletId?: string;
+    reason?: string;
+}
+export interface CrucibleProductAllocation {
+    productId: string;
+    amount?: number;
+    metrics?: CrucibleMetricMap;
+}
+export interface CrucibleSplitEffect {
+    type: "split";
+    sourceId: string;
+    products: readonly CrucibleProductAllocation[];
+    loss?: CrucibleLoss;
+}
+export interface CrucibleEjectEffect {
+    type: "eject";
+    select: CrucibleSelector;
+    outletId: string;
+    state?: "ejected" | "failed" | "retained" | "recovered";
+    reason?: string;
+}
+export type CrucibleMetricTarget = "run" | {
+    components: CrucibleSelector;
+} | {
+    productIds: readonly string[];
+};
+export interface CrucibleSetMetricEffect {
+    type: "set-metric";
+    target: CrucibleMetricTarget;
+    metricsDelta: CrucibleMetricMap;
+}
+export interface CrucibleSetOutcomeEffect {
+    type: "set-outcome";
+    outcome: string;
+    summary?: string;
+}
+export type CrucibleEffect = CrucibleSetStateEffect | CrucibleSetRelationEffect | CrucibleResolveRelationEffect | CrucibleCombineEffect | CrucibleContributeEffect | CrucibleCompleteProductEffect | CrucibleSplitEffect | CrucibleEjectEffect | CrucibleSetMetricEffect | CrucibleSetOutcomeEffect;
+export type CrucibleEventAt = {
+    time: number;
+    phaseId?: never;
+    progress?: never;
+} | {
+    time?: never;
+    phaseId: string;
+    progress?: number;
+};
+export interface CrucibleEvent {
+    id: string;
+    at: CrucibleEventAt;
+    effects: readonly CrucibleEffect[];
+    label?: string;
+    description?: string;
+    summary?: string;
+}
+export interface CrucibleHistoryItem {
+    eventId: string;
+    effectType: CrucibleEffect["type"];
+    phaseId: string;
+    authoredAt: number;
+    appliedAt: number;
+    label?: string;
+    summary?: string;
+    sourceIds?: string[];
+    productIds?: string[];
+    relationIds?: string[];
+    outletIds?: string[];
+}
+export interface CrucibleComponentState<TDatum extends Datum = Datum> {
+    id: string;
+    label: string;
+    category: string;
+    datum: TDatum;
+    status: CrucibleComponentStatus;
+    initialAmount: number;
+    amount: number;
+    initialMetrics: CrucibleMetricMap;
+    metrics: CrucibleMetricMap;
+    productIds: string[];
+    outletId?: string;
+    reason?: string;
+    history: CrucibleHistoryItem[];
+}
+export interface CrucibleProductState {
+    id: string;
+    label: string;
+    description?: string;
+    category: string;
+    color?: string;
+    order?: number;
+    declaredAmount?: number;
+    amount: number;
+    metrics: CrucibleMetricMap;
+    status: CrucibleProductStatus;
+    sourceIds: string[];
+    outletId?: string;
+    createdByEventId: string;
+    createdAt: number;
+    completedByEventId?: string;
+    completedAt?: number;
+    reason?: string;
+    history: CrucibleHistoryItem[];
+}
+export interface CrucibleRunState<TDatum extends Datum = Datum> {
+    elapsed: number;
+    phaseElapsed: number;
+    phaseId: string;
+    phaseIndex: number;
+    playing: boolean;
+    complete: boolean;
+    outcome?: string;
+    summary?: string;
+    eventsApplied: string[];
+    components: Record<string, CrucibleComponentState<TDatum>>;
+    products: Record<string, CrucibleProductState>;
+    relations: Record<string, CrucibleRelationState>;
+    input: {
+        amount: number;
+        metrics: CrucibleMetricMap;
+    };
+    metrics: CrucibleMetricMap;
+    loss: {
+        amount: number;
+        metrics: CrucibleMetricMap;
+    };
+    history: CrucibleHistoryItem[];
+}
+export type CrucibleMaterializationType = "activate-relation" | "resolve-relation" | "form-product" | "update-product" | "complete-product" | "split-source" | "retarget-component" | "retarget-product";
+export interface CrucibleMaterialization {
+    type: CrucibleMaterializationType;
+    eventId: string;
+    sourceIds?: string[];
+    productIds?: string[];
+    relationIds?: string[];
+    outletIds?: string[];
+}
+export interface CrucibleObservation {
+    type: "crucible-event" | CrucibleMaterializationType | "crucible-outcome";
+    eventId: string;
+    phaseId: string;
+    authoredAt: number;
+    appliedAt: number;
+    sourceIds?: string[];
+    productIds?: string[];
+    relationIds?: string[];
+    outletIds?: string[];
+    outcome?: string;
+}
+export interface CrucibleDiagnostic {
+    severity: "warning" | "error";
+    code: string;
+    message: string;
+    path?: string;
+    ids?: string[];
+}
+export interface CrucibleApplyResult<TDatum extends Datum = Datum> {
+    applied: boolean;
+    state: CrucibleRunState<TDatum>;
+    materializations: CrucibleMaterialization[];
+    observations: CrucibleObservation[];
+    diagnostics: CrucibleDiagnostic[];
+}
+export interface CrucibleApplyContext {
+    phaseId: string;
+    authoredAt: number;
+    appliedAt: number;
+    products: readonly CrucibleProductDefinition[];
+    outlets: readonly CrucibleOutlet[];
+}
+export interface CrucibleCompiledPhase extends CruciblePhase {
+    index: number;
+    start: number;
+    end: number;
+}
+/** `boundaryRank` encodes phase-end (0), then next phase-start (1). */
+export interface CrucibleCompiledEvent extends CrucibleEvent {
+    index: number;
+    authoredAt: number;
+    phaseId: string;
+    phaseIndex: number;
+    boundaryRank: 0 | 1;
+}
+export interface CrucibleAccessors<TDatum extends Datum = Datum> {
+    idAccessor?: ChartAccessor<TDatum, string>;
+    labelAccessor?: ChartAccessor<TDatum, string>;
+    categoryAccessor?: ChartAccessor<TDatum, string>;
+    amountAccessor?: ChartAccessor<TDatum, number>;
+    metricsAccessor?: ChartAccessor<TDatum, CrucibleMetricMap>;
+    initialStateAccessor?: ChartAccessor<TDatum, CrucibleComponentStatus>;
+}
+export interface CrucibleCompileOptions<TDatum extends Datum = Datum> extends CrucibleAccessors<TDatum> {
+    data: readonly TDatum[];
+    phases: readonly CruciblePhase[];
+    products?: readonly CrucibleProductDefinition[];
+    outlets?: readonly CrucibleOutlet[];
+    events?: readonly CrucibleEvent[];
+    size?: [number, number];
+    seed?: number | string;
+    bodyRadius?: number;
+    radiusRange?: [number, number];
+    metrics?: CrucibleMetricMap;
+}
+export interface CrucibleLayoutOutlet extends CrucibleOutlet {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface CrucibleLayout {
+    width: number;
+    height: number;
+    phaseRail: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    chamber: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    mouth: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    projection: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    outlets: CrucibleLayoutOutlet[];
+}
+export interface CrucibleBodyDatum<TDatum extends Datum = Datum> {
+    __crucible: true;
+    kind: "component" | "product";
+    semanticId: string;
+    sourceDatum?: TDatum;
+    product?: CrucibleProductState;
+}
+export interface CrucibleCompiledPlan<TDatum extends Datum = Datum> {
+    phases: CrucibleCompiledPhase[];
+    events: CrucibleCompiledEvent[];
+    products: CrucibleProductDefinition[];
+    outlets: CrucibleOutlet[];
+    duration: number;
+    initialState: CrucibleRunState<TDatum>;
+    terminalState: CrucibleRunState<TDatum>;
+    layout: CrucibleLayout;
+    colliders: PhysicsColliderSpec[];
+    config: PhysicsPipelineConfig;
+    initialSpawns: PhysicsQueuedSpawn[];
+    terminalSpawns: PhysicsQueuedSpawn[];
+    semanticKey: string;
+    diagnostics: CrucibleDiagnostic[];
+}
+export interface CrucibleReplayResult<TDatum extends Datum = Datum> {
+    state: CrucibleRunState<TDatum>;
+    materializations: CrucibleMaterialization[];
+    observations: CrucibleObservation[];
+    diagnostics: CrucibleDiagnostic[];
+}
+export type CrucibleProjectionGroupBy = "status" | "outlet" | "category" | "product";
+export interface CrucibleProjectionSpec {
+    groupBy?: CrucibleProjectionGroupBy;
+    measure?: "count" | "amount" | string;
+    order?: readonly string[];
+    showInputBaseline?: boolean;
+    showDelta?: boolean;
+}
+export interface CrucibleProjectionRow {
+    key: string;
+    label: string;
+    count: number;
+    amount: number;
+    metrics: CrucibleMetricMap;
+    status?: CrucibleComponentStatus | CrucibleProductStatus;
+    outletId?: string;
+    category?: string;
+    productId?: string;
+}
+export interface CrucibleConservationSpec {
+    field?: "amount" | string;
+    tolerance?: number;
+}
+export interface CrucibleConservationResult {
+    field: string;
+    input: number;
+    products: number;
+    unassigned: number;
+    loss: number;
+    output: number;
+    delta: number;
+    conserved: boolean;
+}

package/dist/components/charts/shared/chartSpecCore.d.ts

@@ -1,12 +1,10 @@
 /**
- * Single source of truth for per-chart prop specifications.
- *
- * Three downstream consumers used to maintain their own per-chart entries:
+ * Single source of truth for per-chart prop specifications consumed by:
  *   - `ai/schema.json`                                    (LLM tool definitions)
  *   - `src/components/charts/shared/validationMap.ts`     (runtime prop validation)
  *   - `ai/componentMetadata.cjs`                          (category buckets)
  *
- * Today, `validationMap.generated.ts` and `ai/schema.json` are generated from
+ * `validationMap.generated.ts` and `ai/schema.json` are generated from
  * this registry — run `npm run docs:chart-specs:schema` to refresh both after
  * editing a spec. `componentMetadata.cjs` is still
  * hand-edited but gated for parity by the registry: `check:chart-specs` (run
@@ -110,6 +108,14 @@ export interface ChartPropSpec {
     default?: unknown;
     /** Schema-side description; surfaces in LLM tool definitions. */
     description?: string;
+    /**
+     * Additional JSON Schema keywords for this prop. Use this for nested wire
+     * contracts (`items`, `properties`, `oneOf`, numeric bounds, and similar)
+     * that cannot be expressed by the shallow runtime validation map. These
+     * keywords are copied only to the AI/MCP schema; runtime validation still
+     * consumes the top-level `type` and `enum` above.
+     */
+    schema?: Readonly<Record<string, unknown>>;
     /**
      * When true, the prop is included in validationMap but omitted from
      * schema.json. Use for handler/callback props (`onClick`, `tooltip`)

package/dist/components/charts/shared/crucibleWireSchema.d.ts

@@ -0,0 +1,5 @@
+/** Nested JSON Schema fragments for CrucibleChart's serializable program. */
+export declare const CRUCIBLE_PHASES_SCHEMA: Readonly<Record<string, unknown>>;
+export declare const CRUCIBLE_PRODUCTS_SCHEMA: Readonly<Record<string, unknown>>;
+export declare const CRUCIBLE_OUTLETS_SCHEMA: Readonly<Record<string, unknown>>;
+export declare const CRUCIBLE_EVENTS_SCHEMA: Readonly<Record<string, unknown>>;

package/dist/components/charts/shared/diagnoseTypes.d.ts

@@ -3,6 +3,16 @@ export interface Diagnosis {
     code: string;
     message: string;
     fix: string;
+    /** Optional evaluator domain; omitted by legacy configuration checks. */
+    domain?: "data" | "configuration" | "accessibility" | "render";
+    /** Numeric/data checks attach the resolved accessor label. */
+    field?: string;
+    /** Numeric/data checks attach the semantic encoding role. */
+    role?: string;
+    /** Bounded zero-based row indices for actionable data findings. */
+    rows?: ReadonlyArray<number>;
+    /** Full affected-row/group count when `rows` is truncated. */
+    count?: number;
 }
 export interface DiagnosisResult {
     ok: boolean;

package/dist/components/charts/shared/gaugeGradient.d.ts

@@ -1,16 +1,12 @@
 import type { Datum } from "./datumTypes";
+import type { ColorGradientInput, GradientConfig, GradientStop } from "./gradient";
 export interface GaugeThresholdLike {
     value: number;
     color: string;
     label?: string;
 }
-export interface GaugeGradientStop {
-    offset: number;
-    color: string;
-}
-export interface GaugeGradientFill {
-    colorStops: GaugeGradientStop[];
-}
+export type GaugeGradientStop = GradientStop;
+export type GaugeGradientFill = ColorGradientInput;
 export interface GaugeArcDatum extends Datum {
     category: string;
     value: number;
@@ -48,7 +44,7 @@ interface BuildGaugeArcModelOptions {
     backgroundColor: string;
     fillZones: boolean;
     showScaleLabels: boolean;
-    gradientFill?: GaugeGradientFill;
+    gradientFill?: GradientConfig;
     gradientSteps?: number;
 }
 /**