@maelstrom-co/react 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,170 @@
+import { ActionNames, ActionParams, ActionRunner, VariantNames } from '@maelstrom-co/client';
+import { ActionName, InstanceId, VariantName, VesselDefinition, VesselId, VesselVariantDefinition } from '@maelstrom-co/protocol';
+import { ComponentType } from 'react';
+/**
+ * Discriminated union of variant prop shapes for vessel `V`.
+ *
+ * For each variant `K` in `V`, contributes a member
+ * `{ variant: K } & V['variants'][K]['props']`. Components consume this
+ * to render different content per variant while preserving literal-type
+ * narrowing on the `variant` discriminant.
+ *
+ * @example
+ * ```typescript
+ * function OrdersComponent({ variantProps }: { variantProps: VariantProps<typeof ordersVessel> }) {
+ *   if (variantProps.variant === 'list') {
+ *     // variantProps narrowed to the 'list' variant's props
+ *   }
+ * }
+ * ```
+ */
+export type VariantProps<V extends VesselDefinition> = {
+    [K in VariantNames<V>]: {
+        variant: K;
+    } & V['variants'][K]['props'];
+}[VariantNames<V>];
+/** Typed props delivered to a vessel component */
+export interface TypedVesselProps<V extends VesselDefinition> {
+    instanceId: InstanceId;
+    variantProps: VariantProps<V>;
+    executeAction: <N extends ActionNames<V>>(...args: ActionParams<V, N> extends undefined ? [name: N] : [name: N, params: ActionParams<V, N>]) => void;
+}
+/** Eager vessel entry — component is already loaded */
+export interface VesselEntry<V extends VesselDefinition> {
+    vessel: V;
+    component: ComponentType<TypedVesselProps<V>>;
+}
+/** Lazy loader function for a vessel component */
+export type LazyVesselComponentLoader<V extends VesselDefinition> = () => Promise<{
+    default: ComponentType<TypedVesselProps<V>>;
+}>;
+/** Lazy vessel entry — component is loaded on demand */
+export interface LazyVesselEntry<V extends VesselDefinition> {
+    vessel: V;
+    component: LazyVesselComponentLoader<V>;
+    loadingComponent: ComponentType<{
+        vesselId: VesselId;
+    }>;
+}
+export type AnyVesselEntry<T extends VesselDefinition = any> = VesselEntry<T> | LazyVesselEntry<T>;
+/** Discriminant: lazy entries carry a loadingComponent, eager ones don't. */
+export declare function isLazyEntry(entry: AnyVesselEntry): entry is LazyVesselEntry<any>;
+/** Extract vessel IDs from a tuple of vessel entries */
+export type VesselIds<TVessels extends readonly AnyVesselEntry[]> = TVessels[number]['vessel']['id'];
+/**
+ * Extract the Vessel definition type from a tuple of entries by its literal ID.
+ *
+ * @example
+ * type CalendarVessel = ExtractVesselByIdFromEntries<typeof entries, 'calendar'>;
+ */
+export type ExtractVesselByIdFromEntries<T extends readonly AnyVesselEntry[], Id extends VesselIds<T>> = Extract<T[number], {
+    vessel: {
+        id: Id;
+    };
+}>['vessel'];
+/**
+ * Pre-computed lookup mapping vessel IDs to their ActionRunner types.
+ * Avoids deep generic resolution at call sites (helps tsc --build inference).
+ */
+export type ActionRunnerLookup<T extends readonly AnyVesselEntry[]> = {
+    [E in T[number] as E['vessel']['id']]: ActionRunner<E['vessel']>;
+};
+/**
+ * A vessel definition safe to hand to `m.updateVessel()` or `handle.update()`
+ * to republish `V`'s definition without remounting its component.
+ *
+ * `props` is the crash surface: the rendered component and the hook that
+ * feeds it read `props` straight off the store and hand it to the mounted
+ * component, so a shape drift throws at render time instead of failing to
+ * compile. `actions`, `enum` values, `description`, and `minSize` stay
+ * free-form — pinning them too would break the documented republish use
+ * case of rebuilding an action's `enum` from live data.
+ *
+ * `variants` is a `Record<string, ...>`, not a per-key mapped type over
+ * `VariantNames<V>`, because `Object.fromEntries` — the documented rebuild
+ * idiom — returns a plain index-signature type with no named keys at all.
+ * No object type with required named properties can ever accept that
+ * return value, regardless of how loosely those properties are typed, so
+ * the target has to be an index signature too. The cost: props are checked
+ * against the union of every registered variant's props, not the specific
+ * variant named at that key, so a value shaped like variant B's props
+ * passes at variant A's key. What this still catches is the actual crash —
+ * a shape that matches none of the vessel's registered variants.
+ */
+export type RepublishableVessel<V extends VesselDefinition> = VesselDefinition & {
+    id: V['id'];
+    variants: Record<string, VesselVariantDefinition & {
+        props: V['variants'][VariantNames<V>]['props'];
+    }>;
+};
+/**
+ * Payload type for `m.updateVessel({ id, ... })` — `Id` must be one of the
+ * vessel IDs declared in `createMaelstrom({ vessels })`, so a typo'd or
+ * runtime-only id fails to compile instead of silently skipping the
+ * `RepublishableVessel` shape check.
+ *
+ * `T` only knows the vessels declared in `createMaelstrom({ vessels })` —
+ * `registerVessel()` adds ids at runtime that never appear in `T`, so
+ * `m.updateVessel()` cannot name them. Republish a runtime-registered
+ * vessel through `handle.update()` on the handle `registerVessel()`
+ * returns instead — it is typed exactly to that call's inferred vessel
+ * definition, with no id lookup needed.
+ */
+export type UpdateVesselPayload<T extends readonly AnyVesselEntry[], Id extends VesselIds<T>> = RepublishableVessel<ExtractVesselByIdFromEntries<T, Id>> & {
+    id: Id;
+};
+/**
+ * Discriminates the recoverable ways `m.updateVessel()` / `handle.update()`
+ * can refuse a republish. See {@link UpdateVesselConflict} for the payload
+ * each code carries.
+ */
+export type UpdateVesselConflictCode = 'variant_dropped' | 'action_dropped' | 'batch_in_flight';
+/**
+ * The recoverable reason a republish did not commit — returned as data by
+ * `m.updateVessel()` / `handle.update()`, never thrown.
+ *
+ * `'variant_dropped'` and `'action_dropped'` are ordinary, user-triggerable
+ * states, not programmer mistakes — for example a `detail` variant that
+ * only exists while its record does, and the user just deleted that
+ * record. `'batch_in_flight'` means a command batch was already queued or
+ * executing when the republish was attempted: CommandProcessor applies
+ * `set_layout` / `execute_actions` through an async queue, so the instance
+ * snapshot a conflict scan would read from is not yet trustworthy — that
+ * in-flight batch could still land an instance on a variant the republish
+ * is about to drop.
+ *
+ * Branch on `code`, not on `message` text, which this package is free to
+ * reword.
+ */
+export type UpdateVesselConflict = {
+    code: 'variant_dropped';
+    vesselId: VesselId;
+    instanceId: InstanceId;
+    variant: VariantName;
+    message: string;
+} | {
+    code: 'action_dropped';
+    vesselId: VesselId;
+    instanceId: InstanceId;
+    variant: VariantName;
+    missingActionNames: readonly ActionName[];
+    message: string;
+} | {
+    code: 'batch_in_flight';
+    vesselId: VesselId;
+    message: string;
+};
+/**
+ * Return type of `m.updateVessel()` and `handle.update()`.
+ *
+ * `ok: false` is an ordinary, user-triggerable outcome, not a bug report —
+ * check `result.conflict.code` and decide whether to retry, skip the
+ * republish, or surface a message.
+ */
+export type UpdateVesselResult = {
+    ok: true;
+} | {
+    ok: false;
+    conflict: UpdateVesselConflict;
+};
+//# sourceMappingURL=vessel-entry-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vessel-entry-types.d.ts","sourceRoot":"","sources":["../../src/lib/vessel-entry-types.ts"],"names":[],"mappings":"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"}

package/dist/lib/vessel.d.ts

@@ -0,0 +1,10 @@
+import { VesselDefinition, VesselId } from '@maelstrom-co/protocol';
+import { ComponentType } from 'react';
+import { LazyVesselComponentLoader, LazyVesselEntry, TypedVesselProps, VesselEntry } from './vessel-entry-types.js';
+/** Register a vessel with an eagerly-loaded component */
+export declare function vessel<const V extends VesselDefinition>(definition: V, component: ComponentType<TypedVesselProps<V>>): VesselEntry<V>;
+/** Register a vessel with a lazily-loaded component */
+export declare function vessel<const V extends VesselDefinition>(definition: V, loader: LazyVesselComponentLoader<V>, loadingComponent: ComponentType<{
+    vesselId: VesselId;
+}>): LazyVesselEntry<V>;
+//# sourceMappingURL=vessel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vessel.d.ts","sourceRoot":"","sources":["../../src/lib/vessel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAE3C,OAAO,KAAK,EACV,yBAAyB,EACzB,eAAe,EACf,gBAAgB,EAChB,WAAW,EACZ,MAAM,yBAAyB,CAAC;AAEjC,yDAAyD;AACzD,wBAAgB,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,gBAAgB,EACrD,UAAU,EAAE,CAAC,EACb,SAAS,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,GAC5C,WAAW,CAAC,CAAC,CAAC,CAAC;AAElB,uDAAuD;AACvD,wBAAgB,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,gBAAgB,EACrD,UAAU,EAAE,CAAC,EACb,MAAM,EAAE,yBAAyB,CAAC,CAAC,CAAC,EACpC,gBAAgB,EAAE,aAAa,CAAC;IAAE,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC,GACtD,eAAe,CAAC,CAAC,CAAC,CAAC"}

package/dist/lib/warn-once.d.ts

@@ -0,0 +1,23 @@
+interface WarnOnceOptions {
+    enabled?: boolean;
+}
+/**
+ * Emits a console warning for the first enabled call for a key in this loaded
+ * module instance. Later enabled calls with the same key are no-ops, regardless
+ * of their message. Disabled calls neither emit a warning nor record the key.
+ * State is not shared across processes, realms, or separately loaded copies.
+ */
+export declare function warnOnce(key: string, message: string, options?: WarnOnceOptions): void;
+/**
+ * Clears warning keys recorded by this loaded module instance.
+ *
+ * An empty-state reset is a no-op. After a reset, the next enabled
+ * {@link warnOnce} call for a previously recorded key emits again. The reset is
+ * local to this package copy in the current process and does not affect other
+ * processes, realms, or separately loaded copies. Application code receives
+ * neither warning-state function from the package root; tests can access only
+ * this reset through `@maelstrom-co/react/_testing`.
+ */
+export declare function resetWarnings(): void;
+export {};
+//# sourceMappingURL=warn-once.d.ts.map

package/dist/lib/warn-once.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warn-once.d.ts","sourceRoot":"","sources":["../../src/lib/warn-once.ts"],"names":[],"mappings":"AAEA,UAAU,eAAe;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,eAAe,QAM1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,SAE5B"}

package/dist/warn-once-Cq9ShMdA.js

@@ -0,0 +1,10 @@
+//#region src/lib/warn-once.ts
+var e = /* @__PURE__ */ new Set();
+function t(t, n, r) {
+	(r?.enabled ?? !0) && !e.has(t) && (e.add(t), console.warn(n));
+}
+function n() {
+	e.clear();
+}
+//#endregion
+export { t as n, n as t };

package/package.json

@@ -1,6 +1,85 @@
 {
   "name": "@maelstrom-co/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "React bindings for Maelstrom: Provider, Chart, connectors, vessel definitions, and hooks for AI-orchestrated dynamic UI.",
+  "keywords": [
+    "maelstrom",
+    "ai",
+    "llm",
+    "dynamic-ui",
+    "generative-ui",
+    "react",
+    "react-hooks",
+    "ui"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@maelstrom-co/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./_testing": {
+      "@maelstrom-co/source": "./src/_testing.ts",
+      "types": "./dist/_testing.d.ts",
+      "import": "./dist/_testing.js",
+      "default": "./dist/_testing.js"
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "!**/*.tsbuildinfo"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/maelstrom-co/maelstrom.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://maelstrom-ai.co",
+  "bugs": {
+    "url": "https://github.com/maelstrom-co/maelstrom/issues"
+  },
+  "author": "Maelstrom (https://maelstrom-ai.co)",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "dependencies": {
+    "@maelstrom-co/client": "0.1.0",
+    "@maelstrom-co/protocol": "0.1.0",
+    "@tanstack/react-store": "^0.9.2"
+  },
+  "devDependencies": {
+    "@sinonjs/fake-timers": "^15.1.1",
+    "@testing-library/react": "^16.3.1",
+    "happy-dom": "^20.8.4"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "nx": {
+    "targets": {
+      "typecheck": {
+        "command": "tsc -p tsconfig.lib.json --noEmit && tsc -p tsconfig.spec.json --noEmit",
+        "options": {
+          "cwd": "{projectRoot}"
+        }
+      },
+      "test": {
+        "command": "bun test",
+        "options": {
+          "cwd": "{projectRoot}"
+        }
+      }
+    }
+  }
+}

package/skills/maelstrom-react-sdk/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: maelstrom-react-sdk
+description: >-
+  Version-matched API guide for @maelstrom-co/react. Load when implementing or
+  reviewing Maelstrom React bindings and this package is installed; check the owning installed package manifest before relying on API names.
+license: MIT
+metadata:
+  author: Maelstrom
+  sdkPackage: '@maelstrom-co/react'
+---
+
+# Maelstrom React SDK
+
+This guide is published inside its owning package. Before use, read the
+installed package's `package.json` version as the version authority. If the guide
+is not shipped by that exact installed package, do not rely on it: inspect the
+installation's `exports`, declarations, source, and tests instead.
+
+The installed public entrypoint exports `createMaelstrom`, `vessel`, and
+`defineVessel`, and exposes the `ChartProps` and `MaelstromProviderProps` types.
+Confirm names and call signatures against the installed entrypoint/declarations
+before use; do not assume `MaelstromProvider` itself is a named export just
+because that type exists. Keep framework-independent lifecycle and connection
+logic in its owning SDK package; application data, authorization, and side
+effects remain application-owned.
+
+When registering a Vessel, wiring Provider/Chart, seeding a tiling first screen,
+testing Chart in a DOM, or diagnosing bootstrap errors, read
+[common tasks](references/common-tasks.md) before choosing the integration.

package/skills/maelstrom-react-sdk/references/common-tasks.md

@@ -0,0 +1,146 @@
+# Register a read-only capability
+
+Inspect the existing renderer and its data owner first. Keep incidental controls
+inside the capability. This example registers one Variant without Actions; its
+one-cell minimum is illustrative, not a measurement of your application's UI.
+
+```tsx
+import type { EngineConnector } from '@maelstrom-co/client';
+import { createMaelstrom, defineVessel, vessel } from '@maelstrom-co/react';
+
+const status = defineVessel({
+  id: 'status',
+  name: 'Status',
+  description: 'Show the application status',
+  defaultVariant: 'summary',
+  variants: {
+    summary: { props: {}, minSize: { width: 1, height: 1 }, actions: [] },
+  },
+});
+
+function Status() {
+  return <section aria-label="Application status">Ready</section>;
+}
+
+export const m = createMaelstrom({ vessels: [vessel(status, Status)] });
+
+export function StatusChart({ connector }: { connector: EngineConnector }) {
+  return <m.Provider connector={connector}><m.Chart /></m.Provider>;
+}
+```
+
+Create the instance outside component rendering. Supply your application's
+configured Connector. The instance owns `Provider` and `Chart`; these are not
+standalone named package exports. Preserve a legacy path when migrating.
+
+For Actions, keep authorization, confirmation, and effects in application-owned
+handlers. For definition changes, preserve every existing Variant and Action;
+inspect the returned update conflicts before deciding how to proceed.
+
+## Seed a tiling first screen
+
+Use this branch when a registered capability must appear before the first Engine
+response. Keep the configured Connector and scope the Provider to the migrated
+surface. Register the existing renderer statically; the Engine arranges Instances
+of that renderer rather than generating runtime JSX.
+Mount this surface in the application's sized Chart container.
+
+```tsx
+import type { EngineConnector } from '@maelstrom-co/client';
+import {
+  InstanceId,
+  type TilingLayout,
+  VariantName,
+  VesselId,
+  tilingLeafToken,
+} from '@maelstrom-co/protocol';
+import { createMaelstrom, defineVessel, vessel } from '@maelstrom-co/react';
+
+const status = defineVessel({
+  id: 'status',
+  name: 'Status',
+  description: 'Show the application status',
+  defaultVariant: 'summary',
+  variants: {
+    summary: { props: {}, minSize: { width: 1, height: 1 }, actions: [] },
+  },
+});
+
+function Status() {
+  return <section aria-label="Application status">Ready</section>;
+}
+
+const m = createMaelstrom({ vessels: [vessel(status, Status)] });
+const instanceId = InstanceId('status-main');
+const initialLayout: TilingLayout = {
+  type: 'tiling',
+  tree: [tilingLeafToken(instanceId)],
+  instances: [{
+    instanceId,
+    vesselId: VesselId('status'),
+    variant: VariantName('summary'),
+  }],
+};
+
+export function SeededStatusChart({ connector }: { connector: EngineConnector }) {
+  return (
+    <m.Provider connector={connector} layoutMode="tiling" initialLayout={initialLayout}>
+      <m.Chart />
+    </m.Provider>
+  );
+}
+```
+
+Match each leaf to one seeded Instance, and each Instance to a registered Vessel
+and declared Variant. `initialLayout` is captured on mount; use a new Provider
+session when you need a different seed. Keep application data and effects with
+their existing owners.
+
+## Verify
+
+Typecheck against this installation. Test the renderer and the scoped Provider
+separately. Observe `connectionError`, `lastError`, and `lastResponse` through
+`m.useMaelstrom()` when submitting intent. A resolved promise is not sufficient
+evidence of success. Test real Engine selection separately from local rendering.
+
+### Test Chart in a DOM
+
+Before mounting `m.Chart`, configure the runner's DOM environment and provide
+`ResizeObserver` in the test setup. jsdom does not supply layout or
+`ResizeObserver`. For sizing or resize assertions, use a real browser with a
+sized Chart container, or a controlled observer that emits meaningful container
+`contentRect` dimensions. Verify the measured geometry as part of that test.
+An inert test-only observer can support control or error tests; label their
+layout behavior unverified. Keep that substitute in test setup and restore any
+replaced globals during teardown.
+
+For an intent-failure regression, inject a local test Connector that connects
+successfully and rejects `process` with a known error. Render a probe inside the
+same instance's Provider. Give it a button disabled until
+`connectionStatus === 'connected'` and while `isProcessing`, and display
+`connectionError` and `lastError` from that same `m.useMaelstrom()` call.
+
+1. Register `afterEach` cleanup to unmount the rendered tree and restore test
+   observers, mocks, and timers, including when an assertion fails.
+2. Use a bounded asynchronous assertion to wait for the connected state and the
+   enabled button before clicking. Treat a disabled button as a pending
+   precondition, rather than skipping the click.
+3. Click once, then use a bounded asynchronous assertion to check the known
+   `lastError` and that processing ends. A resolved `processIntent` promise
+   alone does not distinguish success from failure.
+4. For success tests, observe `lastResponse`, a clear `lastError`, and the
+   expected rendered capability. Include meaningful geometry when claiming
+   layout correctness.
+
+With Testing Library, use `waitFor` with an explicit timeout, such as 1000 ms,
+and an assertion that throws until the expected state appears. Let waits yield
+to DOM updates and timers so a missing error fails within the bound.
+
+## Troubleshoot
+
+- Missing `MaelstromProvider`: use the configured instance's `Provider`.
+- Invalid first-screen seed: only tiling mode supports `initialLayout`; seeded
+  Instances must name statically registered Vessels and legal Variants.
+- Definition update conflict: retain the complete definition and the app's policy.
+- Runtime source lookup: inspect `dist/index.js`. Declarations under `dist/lib/`
+  do not imply separate runtime JavaScript files at those paths.