semiotic 3.8.3 → 3.8.5

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;

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[];