@agentable-ui/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentable contributors
+
+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

@@ -0,0 +1,51 @@
+# @agentable-ui/react
+
+React bindings for [`@agentable-ui/core`](../core): `AgentableProvider`, `useCapability`, `useTool`, `ToolScope`.
+
+```bash
+npm install @agentable-ui/react @agentable-ui/core
+```
+
+## Usage
+
+```tsx
+import { AgentableProvider, useTool } from "@agentable-ui/react";
+
+function App() {
+  return (
+    <AgentableProvider budget={12}>
+      <Orders />
+    </AgentableProvider>
+  );
+}
+
+function Orders() {
+  useTool({
+    name: "refresh_orders",
+    description: "Reload the orders list.",
+    annotations: { readOnlyHint: true },
+    execute: () => refetch(),
+  });
+  return <table>…</table>;
+}
+```
+
+## API
+
+**`<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(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.
+
+**`useTool(options)`** is the shorthand for a single hand-rolled tool; `id` defaults to `tool.<name>`, and `enabled: false` disables it without unmounting.
+
+**`<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.
+
+**`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.
+
+**`useAgentable()`** returns the registry from the nearest provider, or `null`.
+
+## SSR and StrictMode
+
+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.
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,104 @@
+import { ReactNode } from "react";
+import { AgentAdapter, Agentable, AgentableOptions, Capability, CapabilityTool, ConfirmRequest, Snapshot, Tier } from "@agentable-ui/core";
+//#region src/AgentableProvider.d.ts
+interface AgentableProviderProps extends Omit<AgentableOptions, "confirm" | "adapters"> {
+  children?: ReactNode;
+  /** Bring your own registry (tests, multiple roots). Options are ignored when set. */
+  agentable?: Agentable;
+  /** Transports. Defaults to the WebMCP adapter. */
+  adapters?: AgentAdapter[];
+  /**
+   * Confirmation for consequential tools.
+   * - omitted: the built-in dialog
+   * - a function: your own handler
+   * - false: no confirmation (a dev warning is logged)
+   */
+  confirm?: ((req: ConfirmRequest) => Promise<boolean>) | false;
+  /** Custom confirmation UI. Receives the pending request and a decide callback. */
+  renderConfirm?: (request: ConfirmRequest, decide: (ok: boolean) => void) => ReactNode;
+}
+export declare function AgentableProvider({ children, agentable: provided, adapters, confirm, renderConfirm, ...options }: AgentableProviderProps): import("react").JSX.Element;
+//#endregion
+//#region src/ConfirmDialog.d.ts
+interface ConfirmDialogProps {
+  request: ConfirmRequest;
+  onDecide: (ok: boolean) => void;
+}
+/**
+ * Default, unstyled confirmation. Style through the data-agentable-confirm
+ * attributes, or replace it with `renderConfirm` on the provider.
+ */
+export declare function ConfirmDialog({ request, onDecide }: ConfirmDialogProps): import("react").JSX.Element;
+//#endregion
+//#region src/ToolScope.d.ts
+interface ToolScopeProps {
+  children?: ReactNode;
+  /** Default group for capabilities declared inside. */
+  group?: string;
+  /** Human description of the group, shown in list_capabilities. */
+  describe?: string;
+  /** Milliseconds offscreen before the scope is demoted to tier 1. Default 5000. */
+  demoteAfter?: number;
+  /** IntersectionObserver rootMargin. Default "200px". */
+  rootMargin?: string;
+  /** Render a different element than div. */
+  as?: keyof HTMLElementTagNameMap;
+  className?: string;
+  style?: React.CSSProperties;
+}
+/**
+ * Scopes capabilities to a region of the page. When the region has been
+ * offscreen for `demoteAfter`, its tools drop from tier 0 to tier 1 (they stay
+ * listed and openable). Scrolling back promotes them again with no re-declare.
+ */
+export declare function ToolScope({ children, group, describe, demoteAfter, rootMargin, as: Tag, className, style }: ToolScopeProps): import("react").JSX.Element;
+//#endregion
+//#region src/useCapability.d.ts
+/**
+ * Declare a capability for as long as the component is mounted.
+ *
+ * - Pass `null`/`undefined` to switch the agent layer off for this component.
+ * - The registry only sees a new declaration when the static shape changes;
+ *   a fresh `execute` closure on every render costs nothing.
+ * - Safe under StrictMode (refcounted) and SSR (effects only).
+ */
+export declare function useCapability<A = unknown, R = unknown>(cap: Capability<A, R> | null | undefined): void;
+//#endregion
+//#region src/useTool.d.ts
+interface UseToolOptions<A, R> extends CapabilityTool<A, R> {
+  /** Capability id. Defaults to `tool.<name>`. */
+  id?: string;
+  tier?: Tier;
+  group?: string;
+  priority?: number;
+  summary?: string;
+  fanIn?: string | {
+    bucket: string;
+    description?: string;
+    title?: string;
+  };
+  /** Set false to disable without unmounting. */
+  enabled?: boolean;
+}
+/** Register a hand-rolled tool with the same registry the components use. */
+export declare function useTool<A = Record<string, unknown>, R = unknown>(tool: UseToolOptions<A, R>): void;
+//#endregion
+//#region src/snapshot.d.ts
+/** Live registry snapshot. Re-renders on every registry change; use sparingly. */
+export declare function useAgentableSnapshot(): Snapshot;
+/** True once the first agent tool call has arrived (the presence heuristic). */
+export declare function useAgentPresent(): boolean;
+//#endregion
+//#region src/context.d.ts
+export declare const AgentableContext: import("react").Context<Agentable | null>;
+export declare const ScopeContext: import("react").Context<string | undefined>;
+export declare const GroupContext: import("react").Context<string | undefined>;
+/** The registry from the nearest provider, or null when the agent layer is switched off. */
+export declare function useAgentable(): Agentable | null;
+export declare function useAgentGroup(): string | undefined;
+//#endregion
+//#region src/fingerprint.d.ts
+/** Static shape of a capability: everything except the execute closure. */
+export declare function fingerprint(cap: Capability | null | undefined): string;
+//#endregion
+export type { AgentableProviderProps, ConfirmDialogProps, ToolScopeProps, UseToolOptions };

package/dist/index.js

@@ -0,0 +1,371 @@
+import { createContext, useCallback, useContext, useEffect, useId, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { createAgentable, toJsonSchema, webmcpAdapter } from "@agentable-ui/core";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/context.ts
+const AgentableContext = createContext(null);
+const ScopeContext = createContext(void 0);
+const GroupContext = createContext(void 0);
+/** The registry from the nearest provider, or null when the agent layer is switched off. */
+function useAgentable() {
+	return useContext(AgentableContext);
+}
+function useAgentGroup() {
+	return useContext(GroupContext);
+}
+//#endregion
+//#region src/ConfirmDialog.tsx
+/**
+* Default, unstyled confirmation. Style through the data-agentable-confirm
+* attributes, or replace it with `renderConfirm` on the provider.
+*/
+function ConfirmDialog({ request, onDecide }) {
+	const ref = useRef(null);
+	useEffect(() => {
+		const el = ref.current;
+		if (!el) return;
+		if (typeof el.showModal === "function" && !el.open) el.showModal();
+		const onCancel = (e) => {
+			e.preventDefault();
+			onDecide(false);
+		};
+		el.addEventListener("cancel", onCancel);
+		return () => el.removeEventListener("cancel", onCancel);
+	}, [onDecide]);
+	const args = request.args && typeof request.args === "object" && Object.keys(request.args).length ? JSON.stringify(request.args, null, 1) : null;
+	return /* @__PURE__ */ jsx("dialog", {
+		ref,
+		"data-agentable-confirm": "",
+		"aria-labelledby": "agentable-confirm-title",
+		children: /* @__PURE__ */ jsxs("form", {
+			method: "dialog",
+			"data-agentable-confirm-form": "",
+			onSubmit: (e) => e.preventDefault(),
+			children: [
+				/* @__PURE__ */ jsx("p", {
+					"data-agentable-confirm-eyebrow": "",
+					children: "An agent wants to act on this page"
+				}),
+				/* @__PURE__ */ jsx("h2", {
+					id: "agentable-confirm-title",
+					"data-agentable-confirm-title": "",
+					children: request.title
+				}),
+				/* @__PURE__ */ jsx("p", {
+					"data-agentable-confirm-message": "",
+					children: request.message
+				}),
+				args ? /* @__PURE__ */ jsx("pre", {
+					"data-agentable-confirm-args": "",
+					children: args
+				}) : null,
+				/* @__PURE__ */ jsxs("div", {
+					"data-agentable-confirm-actions": "",
+					children: [/* @__PURE__ */ jsx("button", {
+						type: "button",
+						"data-agentable-confirm-deny": "",
+						onClick: () => onDecide(false),
+						autoFocus: true,
+						children: "Don't allow"
+					}), /* @__PURE__ */ jsx("button", {
+						type: "button",
+						"data-agentable-confirm-allow": "",
+						onClick: () => onDecide(true),
+						children: "Allow"
+					})]
+				})
+			]
+		})
+	});
+}
+//#endregion
+//#region src/AgentableProvider.tsx
+function AgentableProvider({ children, agentable: provided, adapters, confirm, renderConfirm, ...options }) {
+	const [queue, setQueue] = useState([]);
+	const queueRef = useRef(queue);
+	queueRef.current = queue;
+	const ask = useCallback((request) => {
+		return new Promise((resolve) => setQueue((q) => [...q, {
+			request,
+			resolve
+		}]));
+	}, []);
+	const optionsRef = useRef(options);
+	const [agentable] = useState(() => {
+		if (provided) return provided;
+		const confirmHandler = confirm === false ? false : confirm ?? ask;
+		return createAgentable({
+			...optionsRef.current,
+			adapters: adapters ?? [webmcpAdapter()],
+			confirm: confirmHandler
+		});
+	});
+	const teardown = useRef(void 0);
+	useEffect(() => {
+		if (provided) return;
+		clearTimeout(teardown.current);
+		teardown.current = void 0;
+		return () => {
+			teardown.current = setTimeout(() => agentable.dispose(), 0);
+		};
+	}, [agentable, provided]);
+	const current = queue[0];
+	const decide = useCallback((ok) => {
+		const head = queueRef.current[0];
+		if (!head) return;
+		head.resolve(ok);
+		setQueue((q) => q.slice(1));
+	}, []);
+	const dialog = useMemo(() => {
+		if (!current) return null;
+		if (renderConfirm) return renderConfirm(current.request, decide);
+		return /* @__PURE__ */ jsx(ConfirmDialog, {
+			request: current.request,
+			onDecide: decide
+		});
+	}, [
+		current,
+		renderConfirm,
+		decide
+	]);
+	return /* @__PURE__ */ jsxs(AgentableContext.Provider, {
+		value: agentable,
+		children: [children, dialog]
+	});
+}
+//#endregion
+//#region src/ToolScope.tsx
+/**
+* Scopes capabilities to a region of the page. When the region has been
+* offscreen for `demoteAfter`, its tools drop from tier 0 to tier 1 (they stay
+* listed and openable). Scrolling back promotes them again with no re-declare.
+*/
+function ToolScope({ children, group, describe, demoteAfter = 5e3, rootMargin = "200px", as: Tag = "div", className, style }) {
+	const agentable = useContext(AgentableContext);
+	const parentGroup = useContext(GroupContext);
+	const id = useId();
+	const ref = useRef(null);
+	useEffect(() => {
+		if (!agentable || !group || !describe) return;
+		agentable.describeGroup(group, describe);
+	}, [
+		agentable,
+		group,
+		describe
+	]);
+	useEffect(() => {
+		const el = ref.current;
+		if (!agentable || !el || typeof IntersectionObserver === "undefined") return;
+		let timer;
+		const observer = new IntersectionObserver((entries) => {
+			if (entries.some((e) => e.isIntersecting)) {
+				if (timer) clearTimeout(timer);
+				timer = void 0;
+				agentable.showScope(id);
+			} else if (!timer) timer = setTimeout(() => {
+				timer = void 0;
+				agentable.hideScope(id);
+			}, demoteAfter);
+		}, { rootMargin });
+		observer.observe(el);
+		return () => {
+			observer.disconnect();
+			if (timer) clearTimeout(timer);
+			agentable.showScope(id);
+		};
+	}, [
+		agentable,
+		id,
+		demoteAfter,
+		rootMargin
+	]);
+	const Element = Tag;
+	return /* @__PURE__ */ jsx(ScopeContext.Provider, {
+		value: id,
+		children: /* @__PURE__ */ jsx(GroupContext.Provider, {
+			value: group ?? parentGroup,
+			children: /* @__PURE__ */ jsx(Element, {
+				ref,
+				"data-agentable-scope": group ?? "",
+				className,
+				style,
+				children
+			})
+		})
+	});
+}
+//#endregion
+//#region src/fingerprint.ts
+/** Static shape of a capability: everything except the execute closure. */
+function fingerprint(cap) {
+	if (!cap) return "";
+	const t = cap.tool;
+	let schema = "";
+	if (t?.inputSchema) try {
+		schema = JSON.stringify(toJsonSchema(t.inputSchema));
+	} catch {
+		schema = "?";
+	}
+	let props = "";
+	if (cap.render?.props) try {
+		props = JSON.stringify(toJsonSchema(cap.render.props));
+	} catch {
+		props = "?";
+	}
+	return JSON.stringify([
+		cap.id,
+		cap.tier ?? 0,
+		cap.group ?? "",
+		cap.priority ?? 0,
+		cap.summary ?? "",
+		cap.fanIn ?? "",
+		t?.name ?? "",
+		t?.title ?? "",
+		t?.description ?? "",
+		schema,
+		t?.annotations ?? null,
+		t?.cache === false ? false : t?.cache ? {
+			ttl: t.cache.ttl,
+			tags: t.cache.tags
+		} : null,
+		t?.invalidates ?? null,
+		t?.output ?? null,
+		typeof t?.confirm === "function" ? "fn" : t?.confirm ?? null,
+		t?.exposedTo ?? null,
+		cap.render ? [
+			cap.render.component,
+			cap.render.description ?? "",
+			props
+		] : null
+	]);
+}
+//#endregion
+//#region src/useCapability.ts
+let warnedNoProvider = false;
+/**
+* Declare a capability for as long as the component is mounted.
+*
+* - Pass `null`/`undefined` to switch the agent layer off for this component.
+* - The registry only sees a new declaration when the static shape changes;
+*   a fresh `execute` closure on every render costs nothing.
+* - Safe under StrictMode (refcounted) and SSR (effects only).
+*/
+function useCapability(cap) {
+	const agentable = useContext(AgentableContext);
+	const scope = useContext(ScopeContext);
+	const inheritedGroup = useContext(GroupContext);
+	const latest = useRef(cap);
+	latest.current = cap;
+	const effectiveGroup = cap?.group ?? inheritedGroup;
+	const key = fingerprint(cap ? {
+		...cap,
+		group: effectiveGroup
+	} : null);
+	const stable = useMemo(() => {
+		const current = latest.current;
+		if (!current) return null;
+		const out = {
+			...current,
+			group: effectiveGroup
+		};
+		if (current.tool) {
+			const tool = {
+				...current.tool,
+				execute: (args, ctx) => {
+					const t = latest.current?.tool;
+					if (!t) throw new Error("Capability is no longer mounted.");
+					return t.execute(args, ctx);
+				}
+			};
+			if (typeof current.tool.confirm === "function") tool.confirm = (args) => {
+				const c = latest.current?.tool?.confirm;
+				return typeof c === "function" ? c(args) : "Allow this action?";
+			};
+			if (current.tool.cache && typeof current.tool.cache === "object" && current.tool.cache.key) {
+				const fn = current.tool.cache.key;
+				tool.cache = {
+					...current.tool.cache,
+					key: (a) => fn(a)
+				};
+			}
+			out.tool = tool;
+		}
+		return out;
+	}, [key]);
+	useEffect(() => {
+		if (!stable) return;
+		if (!agentable) {
+			if (!warnedNoProvider && typeof console !== "undefined") {
+				warnedNoProvider = true;
+				console.warn(`[agentable] Capability "${stable.id}" declared outside <AgentableProvider>; the agent layer is off.`);
+			}
+			return;
+		}
+		const handle = agentable.declare(stable, scope ? { scope } : {});
+		return () => handle.release();
+	}, [
+		agentable,
+		stable,
+		scope
+	]);
+}
+//#endregion
+//#region src/useTool.ts
+/** Register a hand-rolled tool with the same registry the components use. */
+function useTool(tool) {
+	const { id, tier, group, priority, summary, fanIn, enabled = true, ...rest } = tool;
+	useCapability(enabled ? {
+		id: id ?? `tool.${tool.name}`,
+		tier,
+		group,
+		priority,
+		summary,
+		fanIn,
+		tool: rest
+	} : null);
+}
+//#endregion
+//#region src/snapshot.ts
+const EMPTY = {
+	resident: [],
+	capabilities: [],
+	groups: [],
+	budget: {
+		max: 0,
+		used: 0,
+		metaTools: 0
+	},
+	cache: {
+		hits: 0,
+		misses: 0,
+		size: 0
+	},
+	adapters: [],
+	warnings: [],
+	estimatedTokens: 0,
+	agentPresent: false
+};
+/** Live registry snapshot. Re-renders on every registry change; use sparingly. */
+function useAgentableSnapshot() {
+	const agentable = useContext(AgentableContext);
+	const subscribe = useCallback((cb) => agentable ? agentable.subscribe(() => cb()) : () => {}, [agentable]);
+	const get = useCallback(() => agentable ? agentable.snapshot() : EMPTY, [agentable]);
+	return useSyncExternalStore(subscribe, useStable(get), () => EMPTY);
+}
+function useStable(get) {
+	const ref = useRef(null);
+	return () => {
+		const next = get();
+		const key = JSON.stringify(next);
+		if (!ref.current || key !== ref.current.key) ref.current = {
+			key,
+			value: next
+		};
+		return ref.current.value;
+	};
+}
+/** True once the first agent tool call has arrived (the presence heuristic). */
+function useAgentPresent() {
+	return useAgentableSnapshot().agentPresent;
+}
+//#endregion
+export { AgentableContext, AgentableProvider, ConfirmDialog, GroupContext, ScopeContext, ToolScope, fingerprint, useAgentGroup, useAgentPresent, useAgentable, useAgentableSnapshot, useCapability, useTool };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@agentable-ui/react",
+  "version": "0.1.0",
+  "description": "React bindings for @agentable-ui/core: AgentableProvider, useTool, useCapability, ToolScope.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/harsh071/agentable-ui",
+    "directory": "packages/react"
+  },
+  "keywords": [
+    "webmcp",
+    "agent",
+    "mcp",
+    "components",
+    "react",
+    "modelContext"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@agentable-ui/core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.7",
+    "@testing-library/react": "^16.3.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}