@maelstrom-co/react 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Jose Ignacio Vazquez Calleja, Krzysztof Trześniewski and Javier Cabrera Arteaga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# @maelstrom-co/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/maelstrom-co/maelstrom/blob/main/LICENSE)
+
+React bindings for Maelstrom — AI-orchestrated dynamic UIs.
+
+📚 **Full documentation:** <https://docs.maelstrom-ai.co/reference/react/readme/>
+
+## Install
+
+```bash
+bun add @maelstrom-co/react
+```
+
+Or: `npm install` / `pnpm add` / `yarn add @maelstrom-co/react`
+
+## What it does
+
+- **`createMaelstrom({ vessels })`** — factory that returns a typed Maelstrom instance — see bullets below for what it exposes
+- **`defineVessel(config)`** — declares the framework-agnostic vessel state machine
+- **`vessel(definition, component | loader, loadingComponent?)`** — pairs a vessel definition with a React component; `loadingComponent` is only used when a lazy loader is passed
+- **`WebSocketConnector` / `HttpConnector`** — client connectors re-exported for React apps
+- **`m.Provider`** — connects to the engine and owns all chart state; accepts any `EngineConnector`
+- **`m.Chart`** — renders the grid canvas; the engine emits layout directives that Chart renders as CSS positioning
+- **Hooks**
+  - `useMaelstrom` — intent submission and connection status
+  - `useVessel` and `useActions` — vessel-level state
+  - `useInstance` — raw access to the Maelstrom instance
+- **`.with(extension)`** — builder for optional extensions
+
+## Quick example
+
+```tsx
+import { createMaelstrom, defineVessel, vessel, WebSocketConnector } from '@maelstrom-co/react';
+
+const greetingVessel = vessel(
+  defineVessel({
+    id: 'greeting',
+    name: 'Greeting',
+    description: 'Displays a greeting message.',
+    defaultVariant: 'compact',
+    variants: {
+      compact: {
+        description: 'One-line greeting',
+        props: { message: 'Hello!' },
+        minSize: { width: 2, height: 1 },
+        actions: [],
+      },
+    },
+  }),
+  ({ variantProps }) => <div>{variantProps.message}</div>
+);
+
+const m = createMaelstrom({ vessels: [greetingVessel] });
+const connector = new WebSocketConnector({ url: 'ws://localhost:3001/ws' });
+
+export function App() {
+  return (
+    <m.Provider connector={connector}>
+      <m.Chart className="h-screen" />
+    </m.Provider>
+  );
+}
+```
+
+## Docs
+
+- Quick start: https://docs.maelstrom-ai.co/getting-started/quick-start/
+- Core concepts: https://docs.maelstrom-ai.co/getting-started/core-concepts/
+- React guides: https://docs.maelstrom-ai.co/guides/react/creating-vessels/
+- Optional DevTools: [inspect requests, layouts, voice events, and recordings](https://docs.maelstrom-ai.co/guides/devtools/) with `@maelstrom-co/react-devtools`.
+- API reference: https://docs.maelstrom-ai.co/reference/react/readme/
+
+## License
+
+MIT

package/dist/_testing.d.ts

@@ -0,0 +1,13 @@
+/** Test-only utilities for `@maelstrom-co/react`. */
+/**
+ * Clears warning de-duplication state held by this loaded module instance.
+ * Calling it with no recorded warnings is a no-op. After a reset, a subsequent
+ * enabled warning for a previously recorded key can be emitted again.
+ *
+ * The state is local to the loaded package copy in the current process; this
+ * does not reset other processes, realms, or separately loaded copies. Unlike
+ * the application-facing package root, the `_testing` subpath intentionally
+ * exposes this reset utility and does not expose the warning helper itself.
+ */
+export { resetWarnings } from './lib/warn-once.js';
+//# sourceMappingURL=_testing.d.ts.map

package/dist/_testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_testing.d.ts","sourceRoot":"","sources":["../src/_testing.ts"],"names":[],"mappings":"AAAA,qDAAqD;AAErD;;;;;;;;;GASG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/_testing.js

@@ -0,0 +1 @@
+export { t as resetWarnings } from "./warn-once-Cq9ShMdA.js";

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export type { ActionHandler, ActionNames, ActionParams, ActionResult, ActionRunner, VariantNames, } from '@maelstrom-co/client';
+export { HttpConnector, WebSocketConnector, } from '@maelstrom-co/client';
+export { defineVessel } from '@maelstrom-co/protocol';
+export type { ChartProps } from './lib/chart/chart.js';
+export type { ChartMotionConfig } from './lib/chart/motion/motion-config.js';
+export type { CreateMaelstromConfig } from './lib/create-maelstrom.js';
+export { createMaelstrom } from './lib/create-maelstrom.js';
+export type { DynamicVesselHandle, UntypedVesselProps, } from './lib/dynamic-vessel-types.js';
+export type { MaelstromExtension, MaelstromExtensionContext, MaelstromExtensionContextValue, } from './lib/extension-types.js';
+export type { MaelstromInstance } from './lib/maelstrom-instance-types.js';
+export type { MaelstromState } from './lib/maelstrom-state-types.js';
+export type { MaelstromProviderProps } from './lib/provider.js';
+export { useIntentSubmission } from './lib/use-intent-submission.js';
+export { vessel } from './lib/vessel.js';
+export type { LazyVesselComponentLoader, LazyVesselEntry, RepublishableVessel, TypedVesselProps, UpdateVesselConflict, UpdateVesselConflictCode, UpdateVesselPayload, UpdateVesselResult, VariantProps, VesselEntry, VesselIds, } from './lib/vessel-entry-types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,aAAa,EACb,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,YAAY,GACb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,aAAa,EACb,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,YAAY,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,YAAY,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,YAAY,EACV,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,+BAA+B,CAAC;AAEvC,YAAY,EACV,kBAAkB,EAClB,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,YAAY,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,YAAY,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,YAAY,EACV,yBAAyB,EACzB,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,SAAS,GACV,MAAM,6BAA6B,CAAC"}