@agentnext/react 0.1.2 → 0.1.3

package/README.md

@@ -1,26 +1,94 @@
-# AgentNext React
-
-React helpers for registering AgentNext actions and consuming runtime state.
-
-## Overview
-Use AgentNext actions directly inside React apps with provider and hook patterns.
-
-## Features
-- AgentProvider
-- useAgentAction
-- useAgentRegistry
-
-## Installation
-```bash
-npm install @agentnext/react @agentnext/core @agentnext/webmcp
-```
-
-## Usage
-```ts
-import { AgentProvider, useAgentAction } from "@agentnext/react";
-
-function App() {
-  useAgentAction(someAction);
-  return <AgentProvider><YourUI /></AgentProvider>;
-}
-```
+# @agentnext/react
+
+React bindings for AgentNext — register actions from components and consume the live action registry via hooks.
+
+## Features
+
+- `AgentProvider` — context provider that exposes the action registry to your component tree
+- `useAgentAction` — registers an action (and exposes it to WebMCP) when a component mounts, and cleans up on unmount
+- `useAgentRegistry` — reads the currently registered actions from context
+
+## Installation
+
+```bash
+npm install @agentnext/react @agentnext/core @agentnext/webmcp zod
+```
+
+> **Peer dependencies:** `react` ≥ 18 and `react-dom` ≥ 18
+
+## Usage
+
+### 1. Wrap your app with `AgentProvider`
+
+Place `AgentProvider` at the root of your component tree so hooks further down can access the registry:
+
+```tsx
+import { AgentProvider } from "@agentnext/react";
+
+export default function App() {
+  return (
+    <AgentProvider>
+      <Router />
+    </AgentProvider>
+  );
+}
+```
+
+### 2. Register an action from a component with `useAgentAction`
+
+Call `useAgentAction` inside any component that "owns" an action. The action is registered with the global registry and exposed to WebMCP when the component mounts, and deregistered when it unmounts.
+
+```tsx
+import { z } from "zod";
+import { action } from "@agentnext/core";
+import { useAgentAction } from "@agentnext/react";
+
+const addToCart = action({
+  name: "add_to_cart",
+  description: "Adds a product to the shopping cart.",
+  input: z.object({
+    productId: z.string(),
+    quantity: z.number().int().min(1),
+  }),
+  execute: async ({ productId, quantity }) => {
+    await cart.add(productId, quantity);
+    return { success: true };
+  },
+});
+
+export function ProductPage() {
+  useAgentAction(addToCart);
+
+  return <button onClick={() => cart.add("p1", 1)}>Add to cart</button>;
+}
+```
+
+### 3. Read the registry with `useAgentRegistry`
+
+Use `useAgentRegistry` to list all currently registered actions, e.g. for an inspector UI:
+
+```tsx
+import { useAgentRegistry } from "@agentnext/react";
+
+export function ActionList() {
+  const { actions } = useAgentRegistry();
+
+  return (
+    <ul>
+      {actions.map((a) => (
+        <li key={a.name}>
+          <strong>{a.name}</strong> — {a.description}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## API Reference
+
+| Export               | Description                                                               |
+| -------------------- | ------------------------------------------------------------------------- |
+| `AgentProvider`      | Context provider. Wrap your app root with this.                           |
+| `useAgentAction(action)` | Registers an `ActionDefinition` on mount; cleans up on unmount.       |
+| `useAgentRegistry()` | Returns `{ actions: ActionDefinition[] }` from the nearest `AgentProvider`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentnext/react",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "React integration for AgentNext — AgentProvider, useAgentAction, useAgentRegistry",
   "license": "MIT",
   "author": "AgentNext",
@@ -35,8 +35,8 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@agentnext/core": "^0.1.2",
-    "@agentnext/webmcp": "^0.1.2"
+    "@agentnext/core": "^0.1.3",
+    "@agentnext/webmcp": "^0.1.3"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",