@agentable-ui/react 0.1.0 → 0.1.1

package/README.md

@@ -1,51 +1,84 @@
 # @agentable-ui/react
 
-React bindings for [`@agentable-ui/core`](../core): `AgentableProvider`, `useCapability`, `useTool`, `ToolScope`.
+Connect React components to the [Agentable registry](../core). Use a provider for setup, hooks for custom tools, and scopes to group related features.
+
+## Install
 
 ```bash
 npm install @agentable-ui/react @agentable-ui/core
 ```
 
-## Usage
+Requires React 18.2+ or React 19. Use a client component in frameworks that distinguish server and client components.
+
+## Add a tool
 
 ```tsx
 import { AgentableProvider, useTool } from "@agentable-ui/react";
 
-function App() {
+function OrderSummary() {
+  useTool({
+    name: "count_orders",
+    description: "Return the number of demo orders.",
+    annotations: { readOnlyHint: true },
+    execute: () => ({ count: 2 }),
+  });
+  return <p>2 orders</p>;
+}
+
+export default function App() {
   return (
     <AgentableProvider budget={12}>
-      <Orders />
+      <OrderSummary />
     </AgentableProvider>
   );
 }
-
-function Orders() {
-  useTool({
-    name: "refresh_orders",
-    description: "Reload the orders list.",
-    annotations: { readOnlyHint: true },
-    execute: () => refetch(),
-  });
-  return <table>…</table>;
-}
 ```
 
-## API
+The provider owns one registry and adds the WebMCP adapter plus a built-in confirmation dialog. Browser support is optional for rendering your app. Add [devtools](../devtools) to inspect and call tools locally.
+
+## Provider options
+
+| Prop | Purpose |
+|---|---|
+| `budget` | Maximum resident tools, including discovery tools; default 12. |
+| `confirm` | Custom async confirmation handler. Omit for the built-in dialog. `false` explicitly disables confirmation. |
+| `renderConfirm` | Customize the confirmation UI. |
+| `agentable` | Supply an existing registry instead of creating one. |
+
+For full registry options, see [core](../core). Imported registries retain their own configuration.
+
+## Declare tools
+
+**`useTool(options)`** is the shorthand for a single tool. Give it `name`, `description`, `inputSchema` when needed, and `execute`. Its capability id defaults to `tool.<name>`. Set `enabled: false` to disable it without unmounting.
 
-**`<AgentableProvider>`** creates the registry with the WebMCP adapter and a built-in confirmation dialog. Pass `confirm` for your own handler, `confirm={false}` to run consequential tools unconfirmed (a dev warning is logged), `renderConfirm` for custom UI, or `agentable` to bring your own registry.
+**`useCapability(capability | null)`** accepts the full descriptor, including tier, priority, group, fan-in, and render metadata. Pass `null` to remove the declaration.
 
-**`useCapability(cap | null)`** declares a full capability descriptor. The registry only sees a new declaration when the static shape changes, so a fresh `execute` closure every render costs nothing. Pass `null` to switch the agent layer off for that component.
+Callbacks use the latest render's values. Changing a callback alone does not re-register the tool; changing its static descriptor can. Tool names and capability ids should stay stable across renders.
 
-**`useTool(options)`** is the shorthand for a single hand-rolled tool; `id` defaults to `tool.<name>`, and `enabled: false` disables it without unmounting.
+Mark pure reads with `annotations: { readOnlyHint: true }`. They skip confirmation and cache by default. Use `cache: false` if each call must re-read changing state or update UI. Mutations ask for confirmation unless explicitly configured otherwise.
+
+## Group a feature
+
+```tsx
+import { ToolScope } from "@agentable-ui/react";
+
+<ToolScope group="orders" describe="Order management" demoteAfter={5000}>
+  <OrderSummary />
+</ToolScope>
+```
 
-**`<ToolScope group describe>`** groups the capabilities inside it and demotes them from tier 0 to tier 1 once the region has been offscreen for `demoteAfter` ms (default 5000). Scrolling back promotes them again with no re-declare.
+Scopes provide group metadata to descendants. When their region stays offscreen for `demoteAfter` milliseconds, eligible tools move from tier 0 to tier 1. Scrolling back restores their eligibility within the budget. Offscreen is different from unmounted: an unmounted component releases its declaration.
 
-**`useAgentableSnapshot()`** returns the live registry snapshot — resident tools, budget, cache stats, adapters, warnings, estimated tokens. Re-renders on every registry change, so use it sparingly. **`useAgentPresent()`** is true once the first agent call arrives.
+## Read registry state
 
-**`useAgentable()`** returns the registry from the nearest provider, or `null`.
+| Hook | Returns |
+|---|---|
+| `useAgentable()` | Nearest registry, or `null` outside a provider. |
+| `useAgentableSnapshot()` | Current tools, budget, cache stats, adapters, warnings, and token estimate. Re-renders on registry changes. |
+| `useAgentPresent()` | Whether the registry has received an agent invocation. This is a heuristic, not a browser presence event. |
 
-## SSR and StrictMode
+## Lifecycle and rendering
 
-Registration happens in effects only, so nothing runs during SSR. Declarations are refcounted and identity-stable across re-renders. The provider defers its `dispose()` by a macrotask so StrictMode's mount → unmount → remount cycle cannot tear down the registry the second mount reuses.
+Registration happens in effects, so SSR does not register browser tools. Declarations are reference-counted, and provider cleanup is deferred to survive React StrictMode's development mount cycle. Without a provider, optional `agent` props are inert and a warning is emitted.
 
-MIT
+MIT licensed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentable-ui/react",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "React bindings for @agentable-ui/core: AgentableProvider, useTool, useCapability, ToolScope.",
   "license": "MIT",
   "type": "module",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@agentable-ui/core": "^0.1.0"
+    "@agentable-ui/core": "^0.2.0"
   },
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0"