@agentic-ui-experience/ui-react 0.0.1-beta.1

package/README.md

@@ -0,0 +1,123 @@
+# @agentic-ui-experience/ui-react
+
+React adapter for `@agentic-ui-experience/ui-runtime`.
+
+This package contains the React hooks, the default A2UI surface renderer,
+this package's `basicCatalog` wrapper, and `defineCatalog` for React component
+implementations. Prompt descriptors live in
+`@agentic-ui-experience/ui-core`, not in this React package. Import the
+framework-agnostic runtime directly from
+`@agentic-ui-experience/ui-runtime` when you do not need React.
+
+## Quick start
+
+```tsx
+import {
+  UIAgentSurface,
+  useUIRuntime
+} from "@agentic-ui-experience/ui-react";
+
+function FieldApp({ field }) {
+  const runtime = useUIRuntime({
+    onAction: (action) => field.handleAction?.(action)
+  });
+
+  return <UIAgentSurface runtime={runtime} />;
+}
+```
+
+`useUIRuntime` defaults to this package's `basicCatalog` wrapper. Pass
+`catalogs` when your app uses custom components.
+
+## User actions
+
+`Button` is the basic catalog component for host / agent round-trips. A
+button with `action: { event: { name, context } }` is resolved by the A2UI
+binder and reaches the runtime's `onAction` callback when clicked.
+
+Form-like components (`TextField`, `ChoicePicker`, `Slider`,
+`DateTimeInput`, etc.) are local input controls. They write to their bound
+data-model `value`; they are not action dispatchers. For a selector that
+should send a new message to an agent, model it as a row of `Button` actions
+or add a custom catalog component with an explicit action prop.
+
+## API
+
+### Hooks
+
+| Export | Purpose |
+|--------|---------|
+| `useUIRuntime(options?)` | Create an app-scoped runtime. Survives React StrictMode's double-mount; `onAction` / `onError` are forwarded through refs, so fresh inline callbacks per render do **not** recreate the runtime. No auto-dispose — call `runtime.dispose()` manually if you spin up multiple runtimes. |
+| `useUIAgent(runtime)` | Subscribe a component to a runtime via `useSyncExternalStore` and return `UIRuntimeState`. `UIAgentSurface` already calls this internally. |
+
+`UseUIRuntimeOptions` ⊆ `UIRuntimeOptions` (from `ui-runtime`), but
+`catalogs` becomes optional (defaults to `[basicCatalog]`).
+
+### Surface component
+
+| Export | Purpose |
+|--------|---------|
+| `UIAgentSurface` | Default A2UI renderer. Subscribes to the runtime and renders all surfaces. |
+| `UIAgentSurfaceProps` | `{ runtime, onAction?, renderEmpty?, renderSurface? }`. `renderEmpty` runs when there are no surfaces; `renderSurface(surface)` lets you wrap or replace the default surface rendering per item. |
+
+### Catalog
+
+| Export | Purpose |
+|--------|---------|
+| `basicCatalog` | The default A2UI basic catalog as a React renderer catalog. |
+| `defineCatalog(options)` | Build a React renderer catalog: extends a base catalog (defaults to `basicCatalog`) and adds custom React component implementations. |
+| `DefineCatalogOptions` | `{ id, extends?, components? }`. |
+
+### Component-implementation helpers (re-exported from `@a2ui/react`)
+
+| Export | Purpose |
+|--------|---------|
+| `createComponentImplementation` | Build a React component implementation bound to the A2UI binder (data-binding, actions, theme). |
+| `createBinderlessComponentImplementation` | Build a React implementation that does **not** use the binder — for components that take only static props. |
+| `ReactComponentImplementation` | Type of a component implementation registered in a `Catalog`. |
+| `ReactA2uiComponentProps` | Props shape passed by the renderer into a component implementation. |
+
+### Re-exports
+
+- `Catalog` from `@a2ui/web_core/v0_9` — for advanced catalog composition.
+- `z` from `zod` — write component schemas with the version pinned by this package.
+- Runtime types: `UIAction`, `UIRuntime`, `UIRuntimeCatalog`,
+  `UIRuntimeError`, `UIRuntimeOptions`, `UIRuntimeState`,
+  `UIRuntimeSurface` (from `@agentic-ui-experience/ui-runtime`).
+
+## Defining a custom catalog
+
+```tsx
+import { z } from "zod";
+import {
+  defineCatalog,
+  createComponentImplementation
+} from "@agentic-ui-experience/ui-react";
+
+const WeatherCard = createComponentImplementation({
+  name: "WeatherCard",
+  schema: z.object({
+    location: z.string(),
+    tempF: z.number()
+  }),
+  render: ({ props }) => (
+    <div>{props.location}: {props.tempF}°F</div>
+  )
+});
+
+export const weatherCatalog = defineCatalog({
+  id: "weather",
+  components: [WeatherCard]
+});
+```
+
+Build the prompt descriptor separately in `@agentic-ui-experience/ui-core`
+and pass `weatherCatalog` to `useUIRuntime({ catalogs: [weatherCatalog] })`.
+
+The component `schema` is the **single source of truth**. The same Zod
+schema is reused three ways: the prompt descriptor turns it into JSON
+Schema (via `zod-to-json-schema`), the renderer binds props with it, and
+the runtime validates the agent's output against it — basic and custom
+components alike (see [ui-runtime → `createUIRuntime`](../ui-runtime/README.md#createuiruntime)).
+Describe **props only**: do not put `id` or `component` in the schema
+(they are envelope fields, stripped before validation).

package/dist/catalog.d.ts

@@ -0,0 +1,13 @@
+import { type ReactComponentImplementation } from "@a2ui/react/v0_9";
+import { Catalog } from "@a2ui/web_core/v0_9";
+export interface DefineCatalogOptions {
+    /** Catalog id - must match the surface's `catalogId`. */
+    id: string;
+    /** Catalog to extend. Defaults to `basicCatalog`. */
+    extends?: Catalog<ReactComponentImplementation>;
+    /** Custom components added on top of the base catalog. */
+    components?: readonly ReactComponentImplementation[];
+}
+export declare function defineCatalog(options: DefineCatalogOptions): Catalog<ReactComponentImplementation>;
+export declare const defineReactCatalog: typeof defineCatalog;
+export declare const basicCatalog: Catalog<ReactComponentImplementation>;

package/dist/catalog.js

@@ -0,0 +1 @@
+function _0xe9d1(){const _0x227327=['1515LyBwzP','1055760XYiBZr','396622USXDGr','3486MxuTJe','598402fOTmfk','545968iKWpdq','8OTkohc','values','extends','components','3ROYGmz','3135654KJDhaK','425530FDpyij'];_0xe9d1=function(){return _0x227327;};return _0xe9d1();}(function(_0x18f2a0,_0x3727ef){const _0x50b889=_0x1913,_0x576d41=_0x18f2a0();while(!![]){try{const _0x2f0d7b=-parseInt(_0x50b889(0x14c))/0x1+-parseInt(_0x50b889(0x14f))/0x2*(-parseInt(_0x50b889(0x14a))/0x3)+parseInt(_0x50b889(0x152))/0x4+-parseInt(_0x50b889(0x14d))/0x5*(-parseInt(_0x50b889(0x150))/0x6)+-parseInt(_0x50b889(0x151))/0x7+parseInt(_0x50b889(0x153))/0x8*(parseInt(_0x50b889(0x14b))/0x9)+-parseInt(_0x50b889(0x14e))/0xa;if(_0x2f0d7b===_0x3727ef)break;else _0x576d41['push'](_0x576d41['shift']());}catch(_0x3a4329){_0x576d41['push'](_0x576d41['shift']());}}}(_0xe9d1,0x3b3e4));import{basicCatalog as _0x179eed}from'@a2ui/react/v0_9';import{Catalog}from'@a2ui/web_core/v0_9';import{A2UI_BASIC_CATALOG_ID}from'@agentic-ui-experience/ui-core';function _0x1913(_0x93cf4e,_0x21bd0a){_0x93cf4e=_0x93cf4e-0x148;const _0xe9d1d9=_0xe9d1();let _0x191399=_0xe9d1d9[_0x93cf4e];return _0x191399;}function defineCatalog(_0x102c78){const _0x508353=_0x1913,_0x161d86=_0x102c78[_0x508353(0x148)]??basicCatalog,_0x2325f7=_0x102c78[_0x508353(0x149)]??[],_0x4d82d0=[..._0x161d86['components'][_0x508353(0x154)](),..._0x2325f7],_0x389175=[..._0x161d86['functions']['values']()],_0x1a58b6=new Catalog(_0x102c78['id'],_0x4d82d0,_0x389175,_0x161d86['themeSchema']);return _0x1a58b6;}const defineReactCatalog=defineCatalog;function cloneCatalog(_0x114eff,_0x5b5d11=_0x114eff['id']){const _0x268ab9=_0x1913;return new Catalog(_0x5b5d11,[..._0x114eff['components']['values']()],[..._0x114eff['functions'][_0x268ab9(0x154)]()],_0x114eff['themeSchema']);}const basicCatalog=cloneCatalog(_0x179eed,A2UI_BASIC_CATALOG_ID);export{basicCatalog,defineCatalog,defineReactCatalog};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { basicCatalog, defineCatalog, defineReactCatalog, type DefineCatalogOptions } from "./catalog.js";
+export { UIAgentSurface, useUIAgent, useUIRuntime, type UIAgentSurfaceProps, type UseUIRuntimeOptions } from "./react.js";
+export { createBinderlessComponentImplementation, createComponentImplementation, type ReactA2uiComponentProps, type ReactComponentImplementation } from "@a2ui/react/v0_9";
+export { Catalog } from "@a2ui/web_core/v0_9";
+export { ActionSchema, CheckableSchema, CommonSchemas, DataBindingSchema, DynamicBooleanSchema, DynamicNumberSchema, DynamicStringListSchema, DynamicStringSchema, DynamicValueSchema, FunctionCallSchema } from "@a2ui/web_core/v0_9";
+export { z } from "zod";
+export type { UIAction, UIRuntime, UIRuntimeCatalog, UIRuntimeError, UIRuntimeOptions, UIRuntimeState, UIRuntimeSurface } from "@agentic-ui-experience/ui-runtime";

package/dist/index.js

@@ -0,0 +1 @@
+(function(_0x315cee,_0x35e08){var _0x1c0ea1=_0x757c,_0x4236ec=_0x315cee();while(!![]){try{var _0x38e2a8=parseInt(_0x1c0ea1(0x86))/0x1+-parseInt(_0x1c0ea1(0x89))/0x2*(-parseInt(_0x1c0ea1(0x83))/0x3)+parseInt(_0x1c0ea1(0x88))/0x4+-parseInt(_0x1c0ea1(0x82))/0x5+parseInt(_0x1c0ea1(0x8a))/0x6*(parseInt(_0x1c0ea1(0x84))/0x7)+-parseInt(_0x1c0ea1(0x85))/0x8+-parseInt(_0x1c0ea1(0x87))/0x9;if(_0x38e2a8===_0x35e08)break;else _0x4236ec['push'](_0x4236ec['shift']());}catch(_0x3ebd41){_0x4236ec['push'](_0x4236ec['shift']());}}}(_0x47c0,0x1d6c9));import{basicCatalog,defineCatalog,defineReactCatalog}from'./catalog.js';import{UIAgentSurface,useUIAgent,useUIRuntime}from'./react.js';import{createBinderlessComponentImplementation,createComponentImplementation}from'@a2ui/react/v0_9';function _0x757c(_0x25d9b3,_0x3b5411){_0x25d9b3=_0x25d9b3-0x82;var _0x47c05f=_0x47c0();var _0x757c75=_0x47c05f[_0x25d9b3];return _0x757c75;}import{ActionSchema,Catalog,CheckableSchema,CommonSchemas,DataBindingSchema,DynamicBooleanSchema,DynamicNumberSchema,DynamicStringListSchema,DynamicStringSchema,DynamicValueSchema,FunctionCallSchema}from'@a2ui/web_core/v0_9';function _0x47c0(){var _0x476a9b=['194928xgJxUq','205635QRbFfb','2306718uCLFAT','507712vCCxzh','484OncvAj','1362VMDjHx','813915zVLQKf','2607zLDfre','651XeyTKs'];_0x47c0=function(){return _0x476a9b;};return _0x47c0();}import{z}from'zod';export{ActionSchema,Catalog,CheckableSchema,CommonSchemas,DataBindingSchema,DynamicBooleanSchema,DynamicNumberSchema,DynamicStringListSchema,DynamicStringSchema,DynamicValueSchema,FunctionCallSchema,UIAgentSurface,basicCatalog,createBinderlessComponentImplementation,createComponentImplementation,defineCatalog,defineReactCatalog,useUIAgent,useUIRuntime,z};

package/dist/react.d.ts

@@ -0,0 +1,30 @@
+import type { ReactComponentImplementation } from "@a2ui/react/v0_9";
+import type { UIAction, UIRuntime, UIRuntimeError, UIRuntimeOptions, UIRuntimeState, UIRuntimeSurface } from "@agentic-ui-experience/ui-runtime";
+type ReactUIRuntime = UIRuntime<ReactComponentImplementation>;
+type ReactUIRuntimeOptions = UIRuntimeOptions<ReactComponentImplementation>;
+type ReactUIRuntimeState = UIRuntimeState<ReactComponentImplementation>;
+type ReactUIRuntimeSurface = UIRuntimeSurface<ReactComponentImplementation>;
+export declare function useUIAgent(runtime: ReactUIRuntime): ReactUIRuntimeState;
+export interface UseUIRuntimeOptions extends Omit<ReactUIRuntimeOptions, "catalogs" | "onAction" | "onError"> {
+    catalogs?: ReactUIRuntimeOptions["catalogs"];
+    onAction?: (action: UIAction) => void;
+    onError?: (error: UIRuntimeError) => void;
+}
+/**
+ * Creates an app-scoped A2UI runtime that survives React StrictMode's
+ * double-mount cycle. Callbacks are forwarded through refs, so passing
+ * fresh inline functions on every render does NOT recreate the runtime.
+ *
+ * No auto-dispose: the runtime is meant to live for the lifetime of the
+ * mounting component. Call `runtime.dispose()` manually if your app
+ * creates multiple runtimes and needs to tear one down early.
+ */
+export declare function useUIRuntime(options?: UseUIRuntimeOptions): ReactUIRuntime;
+export interface UIAgentSurfaceProps {
+    runtime: ReactUIRuntime;
+    onAction?: (action: UIAction) => void;
+    renderEmpty?: () => React.ReactNode;
+    renderSurface?: (surface: ReactUIRuntimeSurface) => React.ReactNode;
+}
+export declare function UIAgentSurface(props: UIAgentSurfaceProps): React.ReactElement | null;
+export {};

package/dist/react.js

@@ -0,0 +1 @@
+function _0x42d4(_0x284933,_0x22054a){_0x284933=_0x284933-0x15f;const _0x426cb9=_0x426c();let _0x42d450=_0x426cb9[_0x284933];return _0x42d450;}(function(_0x5cca18,_0x312b2d){const _0xa3d165=_0x42d4,_0x586646=_0x5cca18();while(!![]){try{const _0x248321=-parseInt(_0xa3d165(0x162))/0x1+parseInt(_0xa3d165(0x15f))/0x2+-parseInt(_0xa3d165(0x161))/0x3+parseInt(_0xa3d165(0x169))/0x4+parseInt(_0xa3d165(0x167))/0x5+-parseInt(_0xa3d165(0x160))/0x6+-parseInt(_0xa3d165(0x16a))/0x7;if(_0x248321===_0x312b2d)break;else _0x586646['push'](_0x586646['shift']());}catch(_0x4b4a45){_0x586646['push'](_0x586646['shift']());}}}(_0x426c,0x230b0));import{jsx}from'react/jsx-runtime';import{useSyncExternalStore,useRef,useState}from'react';import{MarkdownContext,A2uiSurface}from'@a2ui/react/v0_9';import{renderMarkdown}from'@a2ui/markdown-it';function _0x426c(){const _0x22b11e=['current','1140724fnAEJR','774347MDzqjz','surfaces','runtime','218132EEKCiY','1379034gObjgO','64203sjSOeb','83645cmyEKs','onError','length','renderSurface','map','973975iraIou'];_0x426c=function(){return _0x22b11e;};return _0x426c();}import{createUIRuntime}from'@agentic-ui-experience/ui-runtime';import{basicCatalog}from'./catalog.js';function useUIAgent(_0x1a3684){return useSyncExternalStore(_0x1a3684['subscribe'],_0x1a3684['getState'],_0x1a3684['getState']);}function useUIRuntime(_0x39ebae={}){const _0x161f27=_0x42d4,_0x49ca07=useRef(_0x39ebae['onAction']),_0x11beb1=useRef(_0x39ebae['onError']);_0x49ca07['current']=_0x39ebae['onAction'],_0x11beb1['current']=_0x39ebae[_0x161f27(0x163)];const {catalogs:catalogs=[basicCatalog],normalizeMode:_0x24784f}=_0x39ebae,[_0x4474a4]=useState(()=>createUIRuntime({'catalogs':catalogs,..._0x24784f?{'normalizeMode':_0x24784f}:{},'onAction':_0xacdd29=>_0x49ca07['current']?.(_0xacdd29),'onError':_0x47e958=>_0x11beb1[_0x161f27(0x168)]?.(_0x47e958)}));return _0x4474a4;}function UIAgentSurface(_0x2a9ec6){const _0x1988e9=_0x42d4,_0x241823=useUIAgent(_0x2a9ec6[_0x1988e9(0x16c)]);if(_0x241823['surfaces'][_0x1988e9(0x164)]===0x0)return _0x2a9ec6['renderEmpty']?.()??null;return jsx(MarkdownContext['Provider'],{'value':renderMarkdown,'children':_0x241823[_0x1988e9(0x16b)][_0x1988e9(0x166)](_0x3e1619=>{const _0x224a28=_0x1988e9;if(_0x2a9ec6['renderSurface'])return jsx('div',{'data-a2ui-surface':_0x3e1619['id'],'children':_0x2a9ec6[_0x224a28(0x165)](_0x3e1619)},_0x3e1619['id']);return jsx('div',{'data-a2ui-surface':_0x3e1619['id'],'children':jsx(A2uiSurface,{'surface':_0x3e1619})},_0x3e1619['id']);})});}export{UIAgentSurface,useUIAgent,useUIRuntime};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@agentic-ui-experience/ui-react",
+  "version": "0.0.1-beta.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "dependencies": {
+    "@a2ui/markdown-it": "0.0.3",
+    "@a2ui/react": "0.9.0",
+    "@a2ui/web_core": "0.9.2",
+    "zod": "^3.25.76",
+    "@agentic-ui-experience/ui-core": "0.0.1-beta.1",
+    "@agentic-ui-experience/ui-runtime": "0.0.1-beta.1"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-obfuscated-package.mjs .",
+    "dev": "tsc -b -w --preserveWatchOutput --force",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "test": "pnpm run build && node --test \"tests/**/*.test.mjs\""
+  }
+}