@maelstrom-co/react 0.0.0-stage → 0.1.1

package/dist/lib/build-execute-action.d.ts

@@ -0,0 +1,9 @@
+import { Orchestrator } from '@maelstrom-co/client';
+import { InstanceId } from '@maelstrom-co/protocol';
+import { MutableRefObject } from 'react';
+/**
+ * Builds the `executeAction` callback injected into vessel components — a
+ * client-authoritative dispatch through `Orchestrator.invokeAction`.
+ */
+export declare function buildExecuteAction(orchestrator: Orchestrator, instanceId: InstanceId, debug: boolean, onErrorRef: MutableRefObject<((error: Error) => void) | undefined>): (name: string, params?: Record<string, unknown>) => void;
+//# sourceMappingURL=build-execute-action.d.ts.map

package/dist/lib/build-execute-action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-execute-action.d.ts","sourceRoot":"","sources":["../../src/lib/build-execute-action.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAE9C;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,YAAY,EAC1B,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC,GACjE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAa1D"}

package/dist/lib/chart/chart.d.ts

@@ -0,0 +1,14 @@
+import { ComponentType, CSSProperties, ReactNode } from 'react';
+import { MaelstromContextPair } from '../context.js';
+/** Props for the `m.Chart` layout component. */
+export interface ChartProps {
+    /** CSS class name applied to the chart container. */
+    className?: string | undefined;
+    /** Additional styles merged onto the chart container (layout-critical properties cannot be overridden). */
+    style?: CSSProperties | undefined;
+    /** Slot content rendered inside the chart container alongside vessels. */
+    children?: ReactNode;
+}
+/** Create the Chart component bound to a Maelstrom context. Internal — called by `createMaelstrom()`. */
+export declare function createChart(contextPair: MaelstromContextPair): ComponentType<ChartProps>;
+//# sourceMappingURL=chart.d.ts.map

package/dist/lib/chart/chart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chart.d.ts","sourceRoot":"","sources":["../../../src/lib/chart/chart.tsx"],"names":[],"mappings":"AAUA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,aAAa,EAGlB,KAAK,SAAS,EAOf,MAAM,OAAO,CAAC;AAGf,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAkE1D,gDAAgD;AAChD,MAAM,WAAW,UAAU;IACzB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,2GAA2G;IAC3G,KAAK,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAClC,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,yGAAyG;AACzG,wBAAgB,WAAW,CACzB,WAAW,EAAE,oBAAoB,GAChC,aAAa,CAAC,UAAU,CAAC,CA6pB3B"}

package/dist/lib/chart/error-boundary.d.ts

@@ -0,0 +1,17 @@
+import { Component, ErrorInfo, ReactNode } from 'react';
+interface ErrorBoundaryProps {
+    children: ReactNode;
+    fallback: (error: Error) => ReactNode;
+    onError?: ((error: Error, errorInfo: ErrorInfo) => void) | undefined;
+}
+interface ErrorBoundaryState {
+    error: Error | null;
+}
+export declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): Partial<ErrorBoundaryState>;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    render(): ReactNode;
+}
+export {};
+//# sourceMappingURL=error-boundary.d.ts.map

package/dist/lib/chart/error-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-boundary.d.ts","sourceRoot":"","sources":["../../../src/lib/chart/error-boundary.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAElE,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,SAAS,CAAC;IACtC,OAAO,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACtE;AAED,UAAU,kBAAkB;IAC1B,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAED,qBAAa,aAAc,SAAQ,SAAS,CAC1C,kBAAkB,EAClB,kBAAkB,CACnB;gBACa,KAAK,EAAE,kBAAkB;IAKrC,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAIjE,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI;IAI3D,MAAM,IAAI,SAAS;CAM7B"}

package/dist/lib/chart/loading.d.ts

@@ -0,0 +1,14 @@
+import { VesselId } from '@maelstrom-co/protocol';
+export interface VesselLoadingSkeletonProps {
+    vesselId: VesselId;
+    vesselName?: string | undefined;
+}
+export declare function VesselLoadingSkeleton({ vesselId, vesselName, }: VesselLoadingSkeletonProps): import("react").JSX.Element;
+export interface VesselLoadErrorProps {
+    vesselId: VesselId;
+    error: Error;
+    debug?: boolean | undefined;
+    retry?: (() => void) | undefined;
+}
+export declare function VesselLoadError({ vesselId, error, debug, retry, }: VesselLoadErrorProps): import("react").JSX.Element;
+//# sourceMappingURL=loading.d.ts.map

package/dist/lib/chart/loading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loading.d.ts","sourceRoot":"","sources":["../../../src/lib/chart/loading.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAGvD,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED,wBAAgB,qBAAqB,CAAC,EACpC,QAAQ,EACR,UAAU,GACX,EAAE,0BAA0B,+BAmD5B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,KAAK,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;CAClC;AAED,wBAAgB,eAAe,CAAC,EAC9B,QAAQ,EACR,KAAK,EACL,KAAK,EACL,KAAK,GACN,EAAE,oBAAoB,+BAkDtB"}

package/dist/lib/chart/motion/flip.d.ts

@@ -0,0 +1,18 @@
+export interface MotionRect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+export interface FlipDelta {
+    readonly dx: number;
+    readonly dy: number;
+    readonly sx: number;
+    readonly sy: number;
+}
+export declare function computeFlipDelta(prev: MotionRect, next: MotionRect): FlipDelta | null;
+export declare function flipKeyframes(delta: FlipDelta): Keyframe[];
+export declare function enterKeyframes(): Keyframe[];
+export declare function exitKeyframes(): Keyframe[];
+export declare function staggerOrder(rects: ReadonlyArray<readonly [string, MotionRect]>): string[];
+//# sourceMappingURL=flip.d.ts.map

package/dist/lib/chart/motion/flip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flip.d.ts","sourceRoot":"","sources":["../../../../src/lib/chart/motion/flip.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAOD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,UAAU,GACf,SAAS,GAAG,IAAI,CAelB;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,QAAQ,EAAE,CAQ1D;AAED,wBAAgB,cAAc,IAAI,QAAQ,EAAE,CAK3C;AAED,wBAAgB,aAAa,IAAI,QAAQ,EAAE,CAK1C;AASD,wBAAgB,YAAY,CAC1B,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,GAClD,MAAM,EAAE,CASV"}

package/dist/lib/chart/motion/measure.d.ts

@@ -0,0 +1,8 @@
+import { MotionRect } from './flip.js';
+export interface MeasuredInstance {
+    readonly node: HTMLElement;
+    readonly rect: MotionRect;
+}
+export declare function measureInstances(container: HTMLElement): Map<string, MeasuredInstance>;
+export declare function measureInstanceRects(container: HTMLElement): Map<string, MotionRect>;
+//# sourceMappingURL=measure.d.ts.map

package/dist/lib/chart/motion/measure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure.d.ts","sourceRoot":"","sources":["../../../../src/lib/chart/motion/measure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B;AAYD,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,WAAW,GACrB,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAoB/B;AAKD,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,WAAW,GACrB,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAIzB"}

package/dist/lib/chart/motion/motion-config.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Choreography settings for Chart layout changes. All motion honors
+ * `prefers-reduced-motion: reduce` regardless of these values — the media
+ * preference always wins over configuration.
+ */
+export interface ChartMotionConfig {
+    /** Move/resize + enter/exit duration in ms. Default 350. */
+    readonly durationMs?: number;
+    /** CSS easing for all chart animations. Default 'cubic-bezier(0.22, 1, 0.36, 1)'. */
+    readonly easing?: string;
+    /** Per-vessel delay in reading order for enter/move waves. Default 30. */
+    readonly staggerMs?: number;
+    /** Disables all chart motion when true. Default false. */
+    readonly disabled?: boolean;
+}
+export interface ResolvedChartMotionConfig {
+    readonly durationMs: number;
+    readonly easing: string;
+    readonly staggerMs: number;
+    readonly disabled: boolean;
+}
+export declare const EXIT_CLEANUP_BUFFER_MS = 100;
+export declare const DEFAULT_MOTION: ResolvedChartMotionConfig;
+export declare function resolveMotionConfig(config: ChartMotionConfig | undefined): ResolvedChartMotionConfig;
+/** True when motion must not run: disabled by config or by the user's OS preference. */
+export declare function motionSuppressed(resolved: ResolvedChartMotionConfig): boolean;
+//# sourceMappingURL=motion-config.d.ts.map

package/dist/lib/chart/motion/motion-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"motion-config.d.ts","sourceRoot":"","sources":["../../../../src/lib/chart/motion/motion-config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,qFAAqF;IACrF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAKD,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C,eAAO,MAAM,cAAc,EAAE,yBAK5B,CAAC;AAEF,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,iBAAiB,GAAG,SAAS,GACpC,yBAAyB,CAwB3B;AAED,wFAAwF;AACxF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,yBAAyB,GAAG,OAAO,CAK7E"}

package/dist/lib/chart/motion/use-chart-motion.d.ts

@@ -0,0 +1,7 @@
+import { RefObject } from 'react';
+import { ResolvedChartMotionConfig } from './motion-config.js';
+export declare function useChartMotion(containerRef: RefObject<HTMLElement | null>, keys: {
+    layoutKey: string;
+    sizeKey: string;
+}, motion: ResolvedChartMotionConfig): void;
+//# sourceMappingURL=use-chart-motion.d.ts.map

package/dist/lib/chart/motion/use-chart-motion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-chart-motion.d.ts","sourceRoot":"","sources":["../../../../src/lib/chart/motion/use-chart-motion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAUvC,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AASpE,wBAAgB,cAAc,CAC5B,YAAY,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAC3C,IAAI,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAC5C,MAAM,EAAE,yBAAyB,GAChC,IAAI,CAyHN"}

package/dist/lib/chart/motion/use-exiting-instances.d.ts

@@ -0,0 +1,9 @@
+import { MotionRect } from './flip.js';
+import { ResolvedChartMotionConfig } from './motion-config.js';
+export interface ExitingEntry<T> {
+    readonly id: string;
+    readonly item: T;
+    readonly rect: MotionRect;
+}
+export declare function useExitingInstances<T>(current: ReadonlyArray<readonly [string, T]>, measureRects: () => ReadonlyMap<string, MotionRect>, motion: ResolvedChartMotionConfig, signature: string): ReadonlyArray<ExitingEntry<T>>;
+//# sourceMappingURL=use-exiting-instances.d.ts.map

package/dist/lib/chart/motion/use-exiting-instances.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-exiting-instances.d.ts","sourceRoot":"","sources":["../../../../src/lib/chart/motion/use-exiting-instances.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAGpE,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B;AAeD,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAC5C,YAAY,EAAE,MAAM,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,EACnD,MAAM,EAAE,yBAAyB,EACjC,SAAS,EAAE,MAAM,GAChB,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAwJhC"}

package/dist/lib/config-types.d.ts

@@ -0,0 +1,29 @@
+import { IntentQueueOptions } from '@maelstrom-co/client';
+import { ChartMotionConfig, ResolvedChartMotionConfig } from './chart/motion/motion-config.js';
+/** Resolved config after merging factory defaults + Provider overrides */
+export interface ResolvedMaelstromConfig {
+    /** Client queue policy captured when the Provider mounts; later changes are ignored. */
+    intentQueue?: IntentQueueOptions;
+    cellSizePx: number;
+    tilingPaddingPx: number;
+    debug: boolean;
+    motion: ResolvedChartMotionConfig;
+}
+/**
+ * Overrides accepted at the factory (createMaelstrom) or Provider seam.
+ * `motion` is unresolved here — its leaf fields are all optional, unlike
+ * `ResolvedMaelstromConfig.motion` where every field is required.
+ */
+export type ConfigOverrides = Partial<Omit<ResolvedMaelstromConfig, 'motion'>> & {
+    motion?: ChartMotionConfig;
+};
+/** Default config values */
+export declare const CONFIG_DEFAULTS: {
+    readonly cellSizePx: 80;
+    readonly tilingPaddingPx: 8;
+    readonly debug: false;
+    readonly motion: ResolvedChartMotionConfig;
+};
+/** Resolve config with priority: provider overrides > factory defaults > hardcoded defaults */
+export declare function resolveConfig(factory: ConfigOverrides, provider: ConfigOverrides): ResolvedMaelstromConfig;
+//# sourceMappingURL=config-types.d.ts.map

package/dist/lib/config-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-types.d.ts","sourceRoot":"","sources":["../../src/lib/config-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EACV,iBAAiB,EACjB,yBAAyB,EAC1B,MAAM,iCAAiC,CAAC;AAMzC,0EAA0E;AAC1E,MAAM,WAAW,uBAAuB;IACtC,wFAAwF;IACxF,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,yBAAyB,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,CACnC,IAAI,CAAC,uBAAuB,EAAE,QAAQ,CAAC,CACxC,GAAG;IACF,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B,CAAC;AAEF,4BAA4B;AAC5B,eAAO,MAAM,eAAe;;;;;CAKgB,CAAC;AAE7C,+FAA+F;AAC/F,wBAAgB,aAAa,CAC3B,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,eAAe,GACxB,uBAAuB,CAwBzB"}

package/dist/lib/context.d.ts

@@ -0,0 +1,42 @@
+import { EngineConnector, Orchestrator } from '@maelstrom-co/client';
+import { VesselId } from '@maelstrom-co/protocol';
+import { ComponentType, MutableRefObject } from 'react';
+import { ResolvedMaelstromConfig } from './config-types.js';
+import { LazyVesselComponentLoader, TypedVesselProps } from './vessel-entry-types.js';
+export interface MaelstromContextValue {
+    orchestrator: Orchestrator;
+    connector: EngineConnector;
+    config: ResolvedMaelstromConfig;
+    /** Ref to onError callback from Provider props — allows hook to call it without re-renders */
+    onErrorRef: MutableRefObject<((error: Error) => void) | undefined>;
+    /** Maps vessel ID → React component */
+    componentRegistry: Map<VesselId, ComponentType<TypedVesselProps<any>>>;
+    /** Maps vessel ID → loading skeleton (for lazy vessels) */
+    loadingRegistry: Map<VesselId, ComponentType<{
+        vesselId: VesselId;
+    }>>;
+    /** Set of vessel IDs that are lazy-loaded */
+    lazyVesselIds: Set<VesselId>;
+    /**
+     * Raw lazy loader per vessel id. Chart wraps with React.lazy() locally on
+     * each render keyed by a retry counter, so the retry path can bust the
+     * cached rejected Promise. Mirrors lazyVesselIds — invariant: ids match.
+     */
+    lazyLoaderRegistry: Map<VesselId, LazyVesselComponentLoader<any>>;
+    /** Guard: only one Chart may be mounted per Provider */
+    chartMountedRef: MutableRefObject<boolean>;
+}
+/** Create a new per-factory React context */
+export declare function createMaelstromContext(): {
+    readonly onOrchestrator: (attach: (orchestrator: Orchestrator) => () => void) => () => void;
+    readonly orchestratorObservers: Set<(orchestrator: Orchestrator) => () => void>;
+    readonly Context: import('react').Context<MaelstromContextValue | null>;
+    readonly useMaelstromContext: () => MaelstromContextValue;
+    readonly contextRef: MutableRefObject<MaelstromContextValue | null>;
+};
+export declare function createOrchestratorObservers(inherited?: Iterable<(orchestrator: Orchestrator) => () => void>): {
+    readonly onOrchestrator: (attach: (orchestrator: Orchestrator) => () => void) => () => void;
+    readonly orchestratorObservers: Set<(orchestrator: Orchestrator) => () => void>;
+};
+export type MaelstromContextPair = ReturnType<typeof createMaelstromContext>;
+//# sourceMappingURL=context.d.ts.map

package/dist/lib/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/lib/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAG7D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,KAAK,EACV,yBAAyB,EACzB,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,YAAY,CAAC;IAC3B,SAAS,EAAE,eAAe,CAAC;IAC3B,MAAM,EAAE,uBAAuB,CAAC;IAChC,8FAA8F;IAC9F,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC,CAAC;IACnE,uCAAuC;IAEvC,iBAAiB,EAAE,GAAG,CAAC,QAAQ,EAAE,aAAa,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACvE,2DAA2D;IAC3D,eAAe,EAAE,GAAG,CAAC,QAAQ,EAAE,aAAa,CAAC;QAAE,QAAQ,EAAE,QAAQ,CAAA;KAAE,CAAC,CAAC,CAAC;IACtE,6CAA6C;IAC7C,aAAa,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC7B;;;;OAIG;IAEH,kBAAkB,EAAE,GAAG,CAAC,QAAQ,EAAE,yBAAyB,CAAC,GAAG,CAAC,CAAC,CAAC;IAClE,wDAAwD;IACxD,eAAe,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC;CAC5C;AAED,6CAA6C;AAC7C,wBAAgB,sBAAsB;sCAgC1B,CAAC,YAAY,EAAE,YAAY,KAAK,MAAM,IAAI;uDAJjB,YAAY,KAAK,MAAM,IAAI;;wCAnB9B,qBAAqB;;EAgBtD;AAED,wBAAgB,2BAA2B,CACzC,SAAS,GAAE,QAAQ,CAAC,CAAC,YAAY,EAAE,YAAY,KAAK,MAAM,IAAI,CAAM;sCAI1D,CAAC,YAAY,EAAE,YAAY,KAAK,MAAM,IAAI;uDAJjB,YAAY,KAAK,MAAM,IAAI;EAgB/D;AAED,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/dist/lib/create-maelstrom.d.ts

@@ -0,0 +1,39 @@
+import { IntentQueueOptions } from '@maelstrom-co/client';
+import { ChartMotionConfig } from './chart/motion/motion-config.js';
+import { MaelstromInstance } from './maelstrom-instance-types.js';
+import { AnyVesselEntry } from './vessel-entry-types.js';
+/** Compile-time guard: rejects entries where any vessel ID has widened to `string` */
+type AssertNarrowIds<T extends readonly AnyVesselEntry[]> = string extends T[number]['vessel']['id'] ? 'Error: All vessel IDs must be literal string types (e.g. "orders"), not `string`. Use vessel() or defineVessel() to preserve literal types.' : T;
+/** Configuration used to create one typed React Maelstrom instance. */
+export interface CreateMaelstromConfig<T extends readonly AnyVesselEntry[]> {
+    /** Vessel entries available to the Provider and generated hooks. */
+    vessels: AssertNarrowIds<T> & T;
+    /**
+     * Grid cell size in pixels. Defaults to 80, must be positive, and may be
+     * overridden by the Provider.
+     */
+    cellSizePx?: number;
+    /**
+     * Pixel gap inset around computed tiling regions. Defaults to 8, must be
+     * non-negative, and may be overridden by the Provider.
+     */
+    tilingPaddingPx?: number;
+    /** Enables client diagnostic logging. Defaults to `false`. */
+    debug?: boolean;
+    /**
+     * Chart motion/choreography settings. A `motion` prop on the Provider
+     * overrides this as a whole object (no per-field merge).
+     */
+    motion?: ChartMotionConfig;
+    /**
+     * Mount-time shared FIFO policy. Defaults: 8 pending, 30s queue wait,
+     * 10s disconnected grace, 60s active result deadline. The deadline does not
+     * cancel work. Provider overrides replace this object; remount to change it.
+     * Invalid limits fail Provider construction, as in the client SDK.
+     */
+    intentQueue?: IntentQueueOptions;
+}
+/** Create a Maelstrom instance with Provider, hooks, and typed vessel access */
+export declare function createMaelstrom<const T extends readonly AnyVesselEntry[]>(config: CreateMaelstromConfig<T>): MaelstromInstance<T>;
+export {};
+//# sourceMappingURL=create-maelstrom.d.ts.map

package/dist/lib/create-maelstrom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-maelstrom.d.ts","sourceRoot":"","sources":["../../src/lib/create-maelstrom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAYzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAQvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAG9D,sFAAsF;AACtF,KAAK,eAAe,CAAC,CAAC,SAAS,SAAS,cAAc,EAAE,IACtD,MAAM,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,GACpC,6IAA6I,GAC7I,CAAC,CAAC;AAER,uEAAuE;AACvE,MAAM,WAAW,qBAAqB,CAAC,CAAC,SAAS,SAAS,cAAc,EAAE;IACxE,oEAAoE;IACpE,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAChC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC;AAED,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,KAAK,CAAC,CAAC,SAAS,SAAS,cAAc,EAAE,EACvE,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC/B,iBAAiB,CAAC,CAAC,CAAC,CAuBtB"}

package/dist/lib/dynamic-vessel-types.d.ts

@@ -0,0 +1,57 @@
+import { ActionRunner } from '@maelstrom-co/client';
+import { ActionName, InstanceId, VariantName, VesselDefinition, VesselId } from '@maelstrom-co/protocol';
+import { RepublishableVessel, TypedVesselProps, UpdateVesselResult } from './vessel-entry-types.js';
+/** Untyped vessel props — escape hatch for heterogeneous instance lists */
+export interface UntypedVesselProps {
+    instanceId: InstanceId;
+    vesselId: VesselId;
+    variantProps: {
+        variant: VariantName;
+    } & Record<string, unknown>;
+    executeAction: (name: ActionName, params?: Record<string, unknown>) => void;
+}
+/**
+ * Handle returned by `m.registerVessel()` for dynamically registered vessels.
+ * Provides typed hooks scoped to the registered vessel and a cleanup method.
+ */
+export interface DynamicVesselHandle<V extends VesselDefinition> {
+    /** Typed vessel props hook — equivalent to `m.useVessel(vesselId, instanceId)` but pre-scoped */
+    useVessel: (instanceId: string) => TypedVesselProps<V> | null;
+    /** Typed action runner registration — equivalent to `m.useActions(vesselId, instanceId, runner)` but pre-scoped */
+    useActions: (instanceId: string, runner: ActionRunner<V>) => void;
+    /**
+     * Republish this vessel's definition — its description, variants, and
+     * action parameters — without touching its component registration, so the
+     * vessel does not remount and keeps any DOM/canvas state it owns.
+     *
+     * This is the runtime-registration counterpart to `m.updateVessel()`: a
+     * vessel registered via `registerVessel()` never appears in the factory's
+     * `vessels` tuple, so `m.updateVessel()` cannot name its id at the type
+     * level. `handle.update()` closes that gap — `V` is exactly the
+     * definition inferred at the `registerVessel()` call site, fixed at
+     * compile time, so `definition` is checked against it the same way
+     * `m.updateVessel()` checks a factory-declared vessel's payload against
+     * the entry passed to `createMaelstrom({ vessels })`.
+     *
+     * Enforces the same runtime guards as `m.updateVessel()`: throws a plain
+     * `Error` if no Provider is mounted, the vessel id is not registered, or
+     * the definition fails validation. Returns `{ ok: false, conflict }`
+     * instead of throwing if a live instance's current variant is missing
+     * from the new definition (`'variant_dropped'`), if the new definition
+     * drops an action that instance's variant still declares
+     * (`'action_dropped'`), or if a command batch is already queued or in
+     * flight (`'batch_in_flight'`) — see `m.updateVessel()`'s JSDoc for the
+     * full result contract.
+     *
+     * @example
+     * const handle = m.registerVessel(widgetEntry);
+     * const result = handle.update({ ...widgetEntry.vessel, description: 'Updated widget' });
+     * if (!result.ok) {
+     *   console.warn(result.conflict.message);
+     * }
+     */
+    update: (definition: RepublishableVessel<V>) => UpdateVesselResult;
+    /** Remove vessel from all registries (vesselManager, componentMap, loadingMap) */
+    unregister: () => void;
+}
+//# sourceMappingURL=dynamic-vessel-types.d.ts.map

package/dist/lib/dynamic-vessel-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-vessel-types.d.ts","sourceRoot":"","sources":["../../src/lib/dynamic-vessel-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EACV,UAAU,EACV,UAAU,EACV,WAAW,EACX,gBAAgB,EAChB,QAAQ,EACT,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EACV,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,yBAAyB,CAAC;AAEjC,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,QAAQ,CAAC;IACnB,YAAY,EAAE;QAAE,OAAO,EAAE,WAAW,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjE,aAAa,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CAC7E;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC,SAAS,gBAAgB;IAC7D,iGAAiG;IACjG,SAAS,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,gBAAgB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAC9D,mHAAmH;IACnH,UAAU,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAClE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,MAAM,EAAE,CAAC,UAAU,EAAE,mBAAmB,CAAC,CAAC,CAAC,KAAK,kBAAkB,CAAC;IACnE,kFAAkF;IAClF,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB"}

package/dist/lib/extension-types.d.ts

@@ -0,0 +1,58 @@
+import { EngineConnector, Orchestrator } from '@maelstrom-co/client';
+import { MutableRefObject } from 'react';
+import { ResolvedMaelstromConfig } from './config-types.js';
+/**
+ * Stable shape passed to extensions when they read context from inside a
+ * Provider tree. Deliberately narrower than the internal context value
+ * so extension authors do not couple to private bookkeeping (component
+ * registry, vessel entries, mount guards) that may be reshaped between
+ * minor versions.
+ */
+export interface MaelstromExtensionContextValue {
+    orchestrator: Orchestrator;
+    connector: EngineConnector;
+    config: ResolvedMaelstromConfig;
+    /** Ref to onError callback from Provider props. Lets extensions surface errors without re-renders. */
+    onErrorRef: MutableRefObject<((error: Error) => void) | undefined>;
+}
+/**
+ * Context handle handed to a `MaelstromExtension`. Exposes a hook that,
+ * when called inside the matching Provider tree, returns the stable
+ * extension-context subset. The actual runtime object carries more
+ * fields, but only those listed here are part of the supported contract.
+ */
+export interface MaelstromExtensionContext {
+    /** Observes this extension branch and its descendants before Provider connection; returns registration cleanup. */
+    onOrchestrator?: (attach: (orchestrator: Orchestrator) => () => void) => () => void;
+    useMaelstromContext: () => MaelstromExtensionContextValue;
+}
+/**
+ * Constraint for extension factory return values. Restricts the shape to a
+ * plain object — the `{ then?: never }` clause rejects `Promise<...>` so an
+ * accidentally-async factory (`async (ctx) => ({...})`) fails at compile
+ * time instead of silently spreading a thenable onto the instance.
+ */
+export type ExtensionOutput = object & {
+    then?: never;
+};
+/**
+ * Factory function that receives the extension context and returns
+ * additional fields to be merged onto the `MaelstromInstance`.
+ *
+ * Extension authors implement this type to create addons (voice, analytics,
+ * devtools, etc.) and consumers apply them via `instance.with(extension)`.
+ *
+ * Extensions must return a plain object synchronously. Async factories,
+ * arrays, and primitive values are rejected at compile time via the
+ * `ExtensionOutput` constraint.
+ *
+ * @example
+ * const myExtension: MaelstromExtension<{ greet: () => string }> = (ctx) => ({
+ *   greet: () => 'Hello from extension!',
+ * });
+ *
+ * const m = createMaelstrom({ vessels }).with(myExtension);
+ * m.greet(); // 'Hello from extension!'
+ */
+export type MaelstromExtension<Out extends ExtensionOutput> = (ctx: MaelstromExtensionContext) => Out;
+//# sourceMappingURL=extension-types.d.ts.map

package/dist/lib/extension-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-types.d.ts","sourceRoot":"","sources":["../../src/lib/extension-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAE9C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAEjE;;;;;;GAMG;AACH,MAAM,WAAW,8BAA8B;IAC7C,YAAY,EAAE,YAAY,CAAC;IAC3B,SAAS,EAAE,eAAe,CAAC;IAC3B,MAAM,EAAE,uBAAuB,CAAC;IAChC,sGAAsG;IACtG,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC,CAAC;CACpE;AAED;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,mHAAmH;IACnH,cAAc,CAAC,EAAE,CACf,MAAM,EAAE,CAAC,YAAY,EAAE,YAAY,KAAK,MAAM,IAAI,KAC/C,MAAM,IAAI,CAAC;IAChB,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;CAC3D;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG;IAAE,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAExD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,kBAAkB,CAAC,GAAG,SAAS,eAAe,IAAI,CAC5D,GAAG,EAAE,yBAAyB,KAC3B,GAAG,CAAC"}