@box-kite/react 2.0.0 → 2.1.0

package/docs/interop.md

@@ -0,0 +1,237 @@
+# Ecosystem interop
+
+`@box-kite/react/interop` is this library's shapes and four other runtimes' shapes, mapped onto each
+other. It is framework-free, carries no engine, and depends on none of them — an adapter that imported a
+runtime would be choosing it for the app, and the app has already chosen.
+
+There are two things every agentic runtime describes, in words of its own:
+
+- **A tool call.** Where it is, what it was given, what it answered, and whether it is waiting on a
+  person. `<ToolCallCard>` and `<ApprovalCard>` (`components/agent`) draw the two halves of it.
+- **A tree of components.** A name resolved against an allow-list the app owns, JSON props, children.
+  `catalog()` says what may be in it and `<SpecRenderer>` renders it.
+
+```ts
+import { toolPart, a2uiApplyAll, a2uiSurface, a2uiToSpec, a2uiCatalog } from '@box-kite/react/interop';
+```
+
+## The tool state, in one vocabulary
+
+`toolPart(part)` reads a part from AI SDK, assistant-ui or CopilotKit and answers in this library's
+words: `{ kind, status, decision, input, output, error }`, where `kind` is `'call'` or `'approval'` and
+`status` is the `pending`/`running`/`success`/`error` a `<ToolCallCard>` takes.
+
+```tsx
+import { toolPart } from '@box-kite/react/interop';
+import { ToolCallCard, ApprovalCard } from '@box-kite/react/components/agent';
+
+function Part({ part }: { part: unknown }) {
+  const mapped = toolPart(part);
+
+  if (!mapped) return null;
+  if (mapped.kind === 'approval') return <ApprovalCard title="Approve this call?" onDecisionChange={respond} />;
+
+  return <ToolCallCard name="searchOrders" status={mapped.status} input={mapped.input} output={mapped.output} />;
+}
+```
+
+**A decision is not a stage a call passes through, it is a question somebody answers** — which is why
+two components cover what AI SDK reports as six states, and why the runtimes that report four are the
+ones whose human-in-the-loop lives on a second channel:
+
+| Runtime      | What it reports                                                                                                      | Where the question is                                 |
+| ------------ | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| AI SDK 6/7   | `input-streaming`, `input-available`, `output-available`, `output-error`, `approval-requested`, `approval-responded` | Two of the six states, with `approval.approved`       |
+| assistant-ui | `status: { type: 'running' \| 'complete' \| 'incomplete' \| 'requires-action' }`                                     | `requires-action`, under either of its two reasons    |
+| CopilotKit   | `status: 'inProgress' \| 'executing' \| 'complete'`                                                                  | `renderAndWaitForResponse`, which hands you `respond` |
+| AG-UI        | `TOOL_CALL_START` / `_ARGS` / `_END` / `_RESULT` events                                                              | `INTERRUPT`                                           |
+
+**AG-UI is the odd one out, and it is worth knowing why**: it reports _events_, not parts, so its cards
+need a fold rather than a mapping. `applyToolEvent(parts, event)` is that fold — one call per event,
+oldest first, keyed by `toolCallId`.
+
+```ts
+import { applyToolEvent } from '@box-kite/react/interop';
+
+const parts = events.reduce(applyToolEvent, {});
+```
+
+## A2UI
+
+[A2UI](https://a2ui.org/) is the declarative UI protocol Google published, and the one CopilotKit and
+Oracle converged on. Its wire shape is the only one in this family that is genuinely different: a **flat
+adjacency list** of components referring to each other by id, arriving one message at a time, with a data
+model of its own per surface. `<SpecRenderer>` renders a tree, so this is a real adapter rather than a
+rename.
+
+### Their messages, rendered here
+
+`a2uiApplyAll` folds a message stream into the surfaces it names, and `a2uiToSpec` turns one surface's
+adjacency list into the tree the renderer takes. Both v0.8 and v0.9 are read; the fold is **pure and
+hands the same state back when a message changed nothing**, so holding it in `useState` re-renders when
+the surface moved and not when a message arrived for a different one.
+
+```tsx
+import { useState } from 'react';
+import { a2uiApply, a2uiEmpty, a2uiSurface, a2uiToSpec } from '@box-kite/react/interop';
+import SpecRenderer from '@box-kite/react/spec';
+
+function Surface({ registry, catalog }) {
+  const [state, setState] = useState(a2uiEmpty);
+
+  useA2uiStream((message) => setState((current) => a2uiApply(current, message)));
+
+  const surface = a2uiSurface(state);
+
+  return <SpecRenderer spec={a2uiToSpec(surface, { catalog })} registry={registry} data={surface?.data} onAction={run} />;
+}
+```
+
+Three things the two models already agreed on, each a special case that did not have to be written:
+
+- **A2UI's data binding is already ours.** `{ "path": "/user/email" }` is a JSON Pointer, and `$data` has
+  taken a JSON Pointer since it was written, so a binding is a rename rather than a parse. The surface's
+  own data model is what goes in `<SpecRenderer data>`.
+- **A template is a `repeat`.** `children: { componentId, path }` is one node per item of an array, which
+  is exactly what `repeat` means, so a list that streams costs nothing extra.
+- **A half-arrived surface is the ordinary case.** An agent streams a leaf before the branch that holds
+  it; a component nothing reaches from the root is simply not rendered yet, and appears when the message
+  naming it does. A cycle in the id graph is cut rather than walked.
+
+What A2UI owns rather than the component — `id`, `component`, `child`, `children`, `action` — never
+reaches the registry as a prop. **`action` becomes an `on` binding under that name**, because what it
+means belongs to the component it lands on: an app registering Box components under A2UI's own names
+(`Text`, `Button`, `Row`) declares `events: ['action']` on them.
+
+```ts
+createSpecRegistry({
+  components: {
+    Button: { component: Button, events: ['action'], props: BUTTON_PROPS },
+    Column: { component: Flex, props: COLUMN_PROPS },
+  },
+});
+```
+
+Where the agent generated against _this library's_ catalog instead, pass it — then a prop the catalog
+calls an event is bound as one and the rest are values:
+
+```ts
+a2uiToSpec(surface, { catalog: catalog({ include: ['Flex', 'H2', 'Button'] }) });
+```
+
+### Our components, generated for
+
+`a2uiCatalog(catalog())` is `catalog()` as an A2UI catalog document — the same components and the same
+values their props take, in the shape around them that an adjacency list needs: a component carries its
+own `id`, its type is a property rather than the key above it, and its children are **ids** rather than
+nested nodes. Every event becomes a string, because a JSON message cannot carry a function: what an agent
+writes is the name of an action, and `onAction` is where the host decides what it does.
+
+```ts
+import { catalog } from '@box-kite/react/catalog';
+import { a2uiCatalog } from '@box-kite/react/interop';
+
+export const document = a2uiCatalog(catalog({ include: ['Flex', 'H2', 'Sparkline'], styleProps: ['p', 'gap', 'bgColor'] }), {
+  catalogId: 'https://example.com/a2ui/box-kite.json',
+});
+```
+
+**Serve it at the `catalogId` you gave it**, which is what an agent's `createSurface` names.
+
+## CopilotKit
+
+Two surfaces, and they want opposite directions.
+
+**Its A2UI renderer** (`@copilotkit/a2ui-renderer`) takes a catalog built from Zod schemas and React
+renderers. `z.fromJSONSchema` is the whole of the bridge — which is why `catalog()` emits JSON Schema at
+all. One trap, measured against zod 4.6: **a `$ref` resolves against the document, not against the piece
+you lifted out of it**, so converting a component on its own throws `Reference not found: #/$defs/color`.
+`a2uiComponentSchema(document, name)` is that component with the document's definitions attached.
+
+```tsx
+import { createCatalog } from '@copilotkit/a2ui-renderer';
+import * as z from 'zod';
+import { a2uiCatalog, a2uiComponentSchema } from '@box-kite/react/interop';
+
+const document = a2uiCatalog(catalog({ include: ['Flex', 'H2', 'P'] }));
+const names = Object.keys(document.components);
+
+const definitions = Object.fromEntries(
+  names.map((name) => [name, { props: z.fromJSONSchema(a2uiComponentSchema(document, name)), description: '' }]),
+);
+
+// Their renderer hands a component its resolved props and a `children(id)` — the adjacency list again.
+const renderers = { Flex: ({ props, children }) => <Flex {...props}>{props.children?.map(children)}</Flex> };
+
+export const boxKiteCatalog = createCatalog(definitions, renderers, { catalogId: document.catalogId });
+```
+
+**Its actions** (`useCopilotAction`) take a render function, so the cards go in as they are. `render` is a
+call being shown; `renderAndWaitForResponse` is a question, and the `respond` it hands you is what
+`onDecisionChange` calls.
+
+```tsx
+useCopilotAction({
+  name: 'refundOrder',
+  parameters: [{ name: 'orderId', type: 'number' }],
+  renderAndWaitForResponse: ({ args, respond }) => (
+    <ApprovalCard title={`Refund order ${args.orderId}`} onDecisionChange={(decision) => respond?.(decision === 'approved')} />
+  ),
+});
+```
+
+## assistant-ui
+
+Its `GenerativeUISpec` and this library's `SpecNode` are the same idea arrived at twice. Three
+differences, and they are the whole adapter: the name is `component` rather than `type`, a child may be a
+bare string that renders as text, and their nodes carry no data binding, no repeat and no action channel
+— in their design those are the tool's job rather than the spec's.
+
+`fromGenerativeUi(spec)` reads theirs and gives back an array of `SpecNode` (several roots stay several
+roots; wrapping them in a container nobody asked for would change the layout). `toGenerativeUi(spec)`
+goes the other way, and **reports what it could not carry** rather than emitting a tree that renders half
+a view in silence:
+
+```ts
+const { spec, losses } = toGenerativeUi(node);
+// losses: [{ code: 'data-binding' | 'repeat' | 'event', path }]
+```
+
+**Its Tool UI** is a component per tool name, and the cards go in as they are:
+
+```tsx
+import { makeAssistantToolUI } from '@assistant-ui/react';
+import { ToolCallCard } from '@box-kite/react/components/agent';
+import { toolPart } from '@box-kite/react/interop';
+
+export const SearchOrdersUI = makeAssistantToolUI({
+  toolName: 'searchOrders',
+  render: (part) => <ToolCallCard name="searchOrders" {...toolPart(part)} />,
+});
+```
+
+## json-render
+
+[`@json-render/react`](https://json-render.dev) wants a Zod schema per component, and `z.fromJSONSchema`
+is again the whole adapter — the recipe is in
+[generative-ui.md](generative-ui.md#rendering-it-somewhere-else-json-render), with the measured caveat
+that its own `validate` lets any props through once a catalog holds more than one component, so each
+node still wants checking against its own schema.
+
+## What is verified, and how
+
+Every runtime named here is a devDependency of this repository, and `src/interop.test.tsx` runs the
+adapters against the published packages rather than against a memory of them:
+
+| Claim                                                        | Checked against                                  |
+| ------------------------------------------------------------ | ------------------------------------------------ |
+| `toGenerativeUi` emits their `GenerativeUISpec`              | `@assistant-ui/core`'s own type                  |
+| `fromGenerativeUi` reads their `GenerativeUINode`            | the same                                         |
+| every member of their `ToolCallMessagePartStatus` union maps | the same                                         |
+| `a2uiCatalog` is a document their `createCatalog` accepts    | `@copilotkit/a2ui-renderer`'s published function |
+| a surface generated against it renders here                  | the fold and `a2uiToSpec`, end to end            |
+| the catalog is one json-render accepts, and validates a spec | `@json-render/react`, in `src/catalog.test.tsx`  |
+
+The two cases A2UI's own conformance suite keeps for a message processor — that an update lands on the
+surface it names and nowhere else, and that each surface owns its data model — are in
+`src/utils/interop/a2uiInterop.test.ts` in the vocabulary that suite uses.

package/docs/mcp.md

@@ -0,0 +1,69 @@
+# @box-kite/mcp
+
+The [Box Kite](https://www.box-kite.dev) MCP server: the retrieval channel for an agent writing Box
+Kite code. Six tools, at capability level — what may I write, what does this component take, and the
+one no documentation mirror can answer: **does this value actually work.**
+
+```bash
+npx @box-kite/mcp
+```
+
+No key, no network, no state. Everything it answers with was built into it from the library's own
+repository at the version you install, including the styling engine itself.
+
+## Install
+
+**Claude Code**
+
+```bash
+claude mcp add box-kite -- npx -y @box-kite/mcp
+```
+
+**Cursor, VS Code, Codex, Zed** — anything that speaks stdio:
+
+```json
+{
+  "mcpServers": {
+    "box-kite": { "command": "npx", "args": ["-y", "@box-kite/mcp"] }
+  }
+}
+```
+
+## The tools
+
+| tool            | what it answers                                                                                                                                   |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `search_docs`   | The prop, component, nesting key or rule for what you are trying to build — ranked across all four, so a goal finds the answer without its name.  |
+| `get_props`     | A style prop's whole record: the CSS it writes, every value it accepts, a measured example, and for a numeric prop its scale measured at 1/2/4/8. |
+| `get_component` | One component's contract: props and defaults, sub-parts, the keyboard map and the ARIA it writes.                                                 |
+| `check_styles`  | A prop bag through the real engine: the CSS each prop writes, or why it wrote none.                                                               |
+| `get_rules`     | The rules the library is written by, as an index or in full.                                                                                      |
+| `get_blocks`    | Whole sections the `shadcn` CLI installs — a data-grid page, a settings form, a dashboard shell.                                                  |
+
+## Why `check_styles` exists
+
+Box Kite accepts a closed set of values per prop, and **a value it does not accept produces no rule
+and no class name** — silently, by design, because a typo must not emit a broken declaration. That is
+the right behaviour and it is invisible, so the only honest way to answer "does `bgColor="blue-550"`
+work" is to hand it to the engine:
+
+```
+check_styles { "props": { "p": 4, "bgColor": "blue-550", "fontSize": 14, "href": "/about" } }
+
+✅ `p` → `.p-4{padding:1rem}`
+❌ `bgColor` does not accept "blue-550" — no rule and no class name were written.
+✅ `fontSize` → `.fontSize-14{font-size:0.875rem}`
+⚠️ `href` an HTML attribute, not a style prop. It goes in `props={{ "href": … }}`.
+```
+
+The dividers differ per prop — spacing is ÷4, `fontSize` is ÷16, border width is direct px — which is
+why `get_props` measures a scale rather than describing one.
+
+## What else the library ships for agents
+
+- `AGENTS.md` and `docs/` inside the published `@box-kite/react` package
+- The skill and rules file: `npx skills add box-kite/box-kite`
+- Every documentation page as markdown at `https://www.box-kite.dev/<route>.md`, indexed by
+  [llms.txt](https://www.box-kite.dev/llms.txt)
+
+MIT © Box Kite

package/docs/props.md

@@ -282,7 +282,7 @@ The border-left-width CSS property sets the width of the left border of an eleme
 
 ### `blur`
 
-How far the element's own pixels are blurred: a step of Tailwind's scale (`xs` 4px through `xxxl` 64px) or a radius in px. One of nine functions that compose into a single `filter`, so a blur and a `brightness` coexist; `none` clears this one and leaves the rest.
+How far the element's own pixels are blurred: a step of the named scale (`xs` 4px through `xxxl` 64px) or a radius in px. One of nine functions that compose into a single `filter`, so a blur and a `brightness` coexist; `none` clears this one and leaves the rest.
 
 - Writes: `--boxBlur`, `filter`
 - Values: `xs` · `sm` · `md` · `lg` · `xl` · `xxl` · `xxxl` · `none`, a number
@@ -1386,7 +1386,7 @@ A hard-edged shadow outside the border box, in px — `ring={2}`. Unlike `outlin
 
 ### `ringColor`
 
-What colour `ring` draws in. `currentColor` otherwise, the way Tailwind's is.
+What colour `ring` draws in. `currentColor` otherwise.
 
 - Writes: `--boxRingColor`
 - Values: 304 named values, anything else the types allow
@@ -1474,7 +1474,7 @@ How far the element is pushed towards sepia, as a percentage.
 
 ### `shadow`
 
-The elevation of the box: `xxs` through `xxl` on Tailwind's scale, or one of the three original presets (`small`, `medium`, `large`, which carry their own colour). `shadowColor` recolours the scale, and the shadow stacks with `ring`, `insetRing` and `insetShadow` rather than replacing them.
+The elevation of the box: `xxs` through `xxl` on the elevation scale, or one of the three original presets (`small`, `medium`, `large`, which carry their own colour). `shadowColor` recolours the scale, and the shadow stacks with `ring`, `insetRing` and `insetShadow` rather than replacing them.
 
 - Writes: `--boxShadow`, `box-shadow`
 - Values: `xxs` · `xs` · `sm` · `md` · `lg` · `xl` · `xxl` · `none` · `small` · `medium` · `large`

package/interop.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./specDefs.cjs"),t=require("./specData.cjs");var n;(function(e){let t={"input-streaming":`pending`,"input-available":`running`,"output-available":`success`,"output-error":`error`,"approval-requested":`approval`,"approval-responded":`approval`},n={inProgress:`pending`,executing:`running`,complete:`success`},r={running:`running`,complete:`success`,incomplete:`error`,"requires-action":`pending`};function i(e){return typeof e==`object`&&e&&!Array.isArray(e)?e:null}function a(e){return typeof e==`string`&&e!==``?e:void 0}function o(e){return e.input??e.args??e.argsText}function s(e){return e.output??e.result}function c(e){let c=i(e);if(c===null)return null;let l=o(c),u=s(c),d=a(c.state);if(d!==void 0&&d in t){let e=t[d];if(e!==`approval`)return{kind:`call`,status:e,decision:null,input:l,output:u,error:a(c.errorText)};let n=i(c.approval)?.approved;return{kind:`approval`,status:`pending`,decision:typeof n==`boolean`?n?`approved`:`rejected`:null,input:l}}let f=c.status,p=i(f);if(p!==null){let e=a(p.type)??``;return{kind:e===`requires-action`?`approval`:`call`,status:r[e]??`pending`,decision:null,input:l,output:u,error:a(i(p.error)?.message)??a(p.error)}}let m=a(f);if(m!==void 0&&m in n){let e=typeof c.respond==`function`&&m===`executing`;return{kind:e?`approval`:`call`,status:e?`pending`:n[m],decision:null,input:l,output:u}}return null}e.toolPart=c;function l(e,t){let n=i(t),r=a(n?.toolCallId);if(n===null||r===void 0)return e;let o=a(n.type),s=e[r]??{kind:`call`,status:`pending`,decision:null};return o===`TOOL_CALL_START`?{...e,[r]:{...s,kind:`call`,status:`pending`}}:o===`TOOL_CALL_ARGS`?{...e,[r]:{...s,status:`pending`}}:o===`TOOL_CALL_END`?{...e,[r]:{...s,status:`running`}}:o===`TOOL_CALL_RESULT`?{...e,[r]:{...s,status:`success`,output:n.content??n.result}}:o===`INTERRUPT`||o===`RUN_INTERRUPT`?{...e,[r]:{...s,kind:`approval`,status:`pending`}}:o===`RUN_ERROR`?{...e,[r]:{...s,status:`error`,error:a(n.message)}}:e}e.applyEvent=l})(n||={});var r=n,i;(function(t){let n=t.ROOT_ID=`root`,r=t.DEFAULT_SURFACE=`main`;t.EMPTY={surfaces:{},order:[]};function i(e){return typeof e==`object`&&e&&!Array.isArray(e)?e:null}function a(e){return typeof e==`string`&&e!==``?e:void 0}function o(e){return{id:e,components:{},data:{}}}function s(e,t,n){return{surfaces:{...e.surfaces,[t]:n},order:e.order.includes(t)?e.order:[...e.order,t]}}function c(e){let t=i(e),n=a(t?.id);if(t===null||n===void 0)return null;let r=t.component;if(typeof r==`string`){let{id:e,component:i,...a}=t;return{id:n,component:r,...a}}let o=i(r),[s]=o?Object.keys(o):[];return o===null||s===void 0?null:{id:n,component:s,...i(o[s])??{}}}function l(e){return e.replace(/~1/g,`/`).replace(/~0/g,`~`)}function u(e){return e===void 0||e===``||e===`/`?[]:(e.startsWith(`/`)?e.slice(1):e).split(`/`).map(l)}function d(e,t){return t.reduce((e,t)=>i(e)?.[t],e)}function f(e,t,n){if(t.length===0)return n;let[r,...a]=t,o=i(e)??{};if(a.length>0)return{...o,[r]:f(o[r],a,n)};if(n!==void 0)return{...o,[r]:n};let{[r]:s,...c}=o;return c}function p(e){if(!Array.isArray(e))return{};let t={};for(let n of e){let e=i(n),r=a(e?.key);e!==null&&r!==void 0&&(`valueString`in e?t[r]=e.valueString:`valueNumber`in e?t[r]=e.valueNumber:`valueBoolean`in e?t[r]=e.valueBoolean:`valueMap`in e&&(t[r]=p(e.valueMap)))}return t}function m(e,t){let n=i(t);if(n===null)return e;let l=i(n.createSurface)??i(n.beginRendering);if(l!==null){let t=a(l.surfaceId)??r,n=e.surfaces[t]??o(t);return s(e,t,{...n,catalogId:a(l.catalogId)??n.catalogId,root:a(l.root)??n.root,theme:i(l.theme)??i(l.styles)??n.theme})}let m=i(n.updateComponents)??i(n.surfaceUpdate);if(m!==null){let t=a(m.surfaceId)??r,n=e.surfaces[t]??o(t),i={...n.components},l=!1;for(let e of Array.isArray(m.components)?m.components:[]){let t=c(e);t!==null&&(i[t.id]=t,l=!0)}return l||!e.surfaces[t]?s(e,t,{...n,components:i}):e}let h=i(n.updateDataModel)??i(n.dataModelUpdate);if(h!==null){let t=a(h.surfaceId)??r,n=e.surfaces[t]??o(t),c=u(a(h.path)),l=`contents`in h?{...i(d(n.data,c))??{},...p(h.contents)}:void 0,m=f(n.data,c,l??h.value);return s(e,t,{...n,data:i(m)??{}})}let g=i(n.deleteSurface);if(g!==null){let t=a(g.surfaceId)??r;if(!e.surfaces[t])return e;let{[t]:n,...i}=e.surfaces;return{surfaces:i,order:e.order.filter(e=>e!==t)}}return e}t.apply=m;function h(e,t){return t.reduce(m,e)}t.applyAll=h;function g(e,t){return t===void 0?e.surfaces[e.order[0]]??null:e.surfaces[t]??null}t.surface=g;function _(e){let t=i(e);return t===null?e:`literalString`in t?t.literalString:`literalNumber`in t?t.literalNumber:`literalBoolean`in t?t.literalBoolean:typeof t.path==`string`?{$data:t.path}:e}function v(e){let t=i(e);return t===null?a(e):a(i(t.event)?.name)??a(t.name)}function y(e){let t=a(e.child);if(t!==void 0)return{ids:[t]};let n=e.children;if(Array.isArray(n))return{ids:n.filter(e=>typeof e==`string`)};let r=i(n);if(r===null)return{ids:[]};if(Array.isArray(r.explicitList))return{ids:r.explicitList.filter(e=>typeof e==`string`)};let o=i(r.template)??r,s=a(o.componentId),c=a(o.path)??a(o.dataBinding);return s!==void 0&&c!==void 0?{ids:[],template:{componentId:s,path:c}}:{ids:[]}}let b=new Set([`id`,`component`,`child`,`children`,`action`]);function x(e,t,n,r,i){let a=e.components[t];if(a===void 0||i>32||r.has(t))return null;let o=new Set(n.catalog?.components[a.component]?.events??[]),s={},c={};for(let[e,t]of Object.entries(a)){if(b.has(e))continue;if(!o.has(e)){s[e]=_(t);continue}let n=v(t);n!==void 0&&(c[e]=n)}let l=v(a.action);l!==void 0&&(c.action=l);let{ids:u,template:d}=y(a),f=new Set([...r,t]),p=[];for(let t of u){let r=x(e,t,n,f,i+1);r!==null&&p.push(r)}if(d!==void 0){let t=x(e,d.componentId,n,f,i+1);t!==null&&p.push({...t,repeat:{$data:d.path}})}return{type:a.component,key:t,...Object.keys(s).length?{props:s}:{},...p.length?{children:p}:{},...Object.keys(c).length?{on:c}:{}}}function S(e,t={}){return e===null?null:x(e,t.root??e.root??n,t,new Set,0)}t.toSpec=S;let C={type:`array`,items:{type:`string`},description:`The ids of this component’s children, each a component of its own in the same surface.`},w={type:`string`,description:`The name of an action the host handles.`};function T(e,t){let n=i(i(e.components)?.[t]);if(n===null)return null;let r=i(e.$defs);return r===null?n:{...n,$defs:r}}t.componentSchema=T;function E(t,n={}){let r=n.catalogId??`urn:box-kite:catalog:${t.version}`,i={},a={};for(let[n,r]of Object.entries(t.components)){let t=e.t.hoist(r.props,i);a[n]={type:`object`,description:r.description,properties:{id:{type:`string`,description:`This component’s id, unique within the surface.`},component:{type:`string`,enum:[n]},...t.properties??{},...Object.fromEntries(r.events.map(e=>[e,w])),...r.slots.length?{children:C}:{}},required:[`id`,`component`,...t.required??[]],additionalProperties:!1}}return{$schema:`https://json-schema.org/draft/2020-12/schema`,$id:r,catalogId:r,title:n.title??`${t.library} catalog`,description:n.description??t.rules.join(` `),...Object.keys(i).length?{$defs:i}:{},components:a}}t.catalogDocument=E})(i||={});var a=i,o;(function(e){function n(e,t){if(typeof e==`string`)return e;if(t>32||typeof e!=`object`||!e||typeof e.component!=`string`)return null;let r=(e.children??[]).map(e=>n(e,t+1)).filter(e=>e!==null);return{type:e.component,...e.key===void 0?{}:{key:e.key},...e.props?{props:e.props}:{},...r.length?{children:r}:{}}}function r(e){return e==null?[]:(Array.isArray(e.root)?e.root:[e.root]).map(e=>n(e,0)).filter(e=>typeof e==`object`&&!!e)}e.toSpec=r;function i(e,n,r,a){if(e==null)return null;if(typeof e==`string`)return e;if(typeof e==`number`||typeof e==`boolean`)return String(e);if(t.t.isRef(e))return r.push({code:`data-binding`,path:n}),null;if(a>32||typeof e.type!=`string`)return null;let o=e;if(o.repeat&&r.push({code:`repeat`,path:n}),o.on)for(let e of Object.keys(o.on))r.push({code:`event`,path:`${n}.on.${e}`});let s=(o.children===void 0?[]:Array.isArray(o.children)?o.children:[o.children]).map((e,t)=>i(e,`${n}.children.${t}`,r,a+1)).filter(e=>e!==null);return{component:o.type,...o.key===void 0?{}:{key:o.key},...o.props?{props:o.props}:{},...s.length?{children:s}:{}}}function a(e){let t=[];return{spec:{root:(Array.isArray(e)?e:[e]).map((e,n)=>i(e,`root.${n}`,t,0)).filter(e=>e!==null)},losses:t}}e.fromSpec=a})(o||={});var s=o,c=r.toolPart,l=r.applyEvent,u=a.apply,d=a.applyAll,f=a.surface,p=a.toSpec,m=a.catalogDocument,h=a.componentSchema,g=a.EMPTY,_=s.toSpec,v=s.fromSpec;exports.A2uiInterop=a,exports.AssistantUiInterop=s,exports.ToolInterop=r,exports.a2uiApply=u,exports.a2uiApplyAll=d,exports.a2uiCatalog=m,exports.a2uiComponentSchema=h,exports.a2uiEmpty=g,exports.a2uiSurface=f,exports.a2uiToSpec=p,exports.applyToolEvent=l,exports.fromGenerativeUi=_,exports.toGenerativeUi=v,exports.toolPart=c;

package/interop.d.ts

@@ -0,0 +1,51 @@
+import { default as A2uiInterop } from './utils/interop/a2uiInterop';
+import { default as AssistantUiInterop } from './utils/interop/assistantUiInterop';
+import { default as ToolInterop } from './utils/interop/toolInterop';
+/**
+ * `@box-kite/react/interop` — the agentic runtimes, in this library's shapes.
+ *
+ * ```ts
+ * import { toolPart, a2uiSurface, a2uiToSpec } from '@box-kite/react/interop';
+ *
+ * const part = toolPart(message);                        // AI SDK, assistant-ui or CopilotKit
+ * const spec = a2uiToSpec(a2uiSurface(state), { catalog }); // an A2UI stream, as a <SpecRenderer> tree
+ * ```
+ *
+ * Four runtimes generate UI and ask for permission, and every one of them describes the same two things
+ * — a tool call, and a tree of components — in words of its own. What ships here is the half this
+ * library owns: the mapping, framework-free, with no dependency on any of them. An adapter that pulled
+ * in a runtime would be choosing it for the app, and the app has already chosen.
+ *
+ * Its own entry, and it carries neither the engine nor React: a route handler building an agent's
+ * catalog and a client folding its messages both import from here, and neither pays for the other.
+ *
+ * `docs/interop.md` has the recipe per runtime, json-render and AG-UI included.
+ */
+export { default as ToolInterop } from './utils/interop/toolInterop';
+export type { ToolPart, ToolPartKind } from './utils/interop/toolInterop';
+export { default as A2uiInterop } from './utils/interop/a2uiInterop';
+export type { A2uiCatalogOptions, A2uiComponent, A2uiSpecOptions, A2uiState, A2uiSurface } from './utils/interop/a2uiInterop';
+export { default as AssistantUiInterop } from './utils/interop/assistantUiInterop';
+export type { GenerativeUiLoss, GenerativeUiNode, GenerativeUiSpec } from './utils/interop/assistantUiInterop';
+export type { ApprovalDecision, ToolCallStatus } from './utils/agent/agentUtils';
+export type { SpecNode } from './utils/spec/specTypes';
+/** Where a tool call is, from whichever of the three runtimes handed you the part. */
+export declare const toolPart: typeof ToolInterop.toolPart;
+/** AG-UI reports events rather than parts, so its cards are a fold: one call per event, oldest first. */
+export declare const applyToolEvent: typeof ToolInterop.applyEvent;
+/** One A2UI message folded into the surfaces it names. Pure, and the same state back when nothing moved. */
+export declare const a2uiApply: typeof A2uiInterop.apply;
+export declare const a2uiApplyAll: typeof A2uiInterop.applyAll;
+/** A surface by id, or the first one the agent opened. */
+export declare const a2uiSurface: typeof A2uiInterop.surface;
+/** A surface's adjacency list as one `<SpecRenderer>` tree. */
+export declare const a2uiToSpec: typeof A2uiInterop.toSpec;
+/** `catalog()` as an A2UI catalog document — what an agent generates against. */
+export declare const a2uiCatalog: typeof A2uiInterop.catalogDocument;
+/** One component of that document, self-contained: a `$ref` resolves against the document, not the part. */
+export declare const a2uiComponentSchema: typeof A2uiInterop.componentSchema;
+/** The state an A2UI fold starts from. */
+export declare const a2uiEmpty: import('./interop').A2uiState;
+/** assistant-ui's generative-UI spec as ours, and back. */
+export declare const fromGenerativeUi: typeof AssistantUiInterop.toSpec;
+export declare const toGenerativeUi: typeof AssistantUiInterop.fromSpec;