cortena-ui 1.1.1 → 1.2.0

package/README.md

@@ -26,6 +26,55 @@ Consuming it: `../../CONSUMING.md`, section "cortena-ui".
   check in light, dark and system-dark; add an entry with every variant and
   size when adding a component.
 
+## A2UI: the vocabulary agents draw with
+
+`src/a2ui/` is Layer 1 of `cortena-docs/cortenaUI&Design/05-agent-ui.md`: an
+[A2UI](https://a2ui.org) catalogue bound to this package, plus a React renderer.
+An agent emits an A2UI payload, it arrives as an AG-UI `CUSTOM` event, and
+`<A2UIRenderer>` draws it from the catalogue and sends user events back.
+
+```tsx
+import { A2UIRenderer, defaultCatalogue } from "cortena-ui";
+
+<A2UIRenderer
+  message={customEvent.value}            // message, message[], or JSONL text
+  catalogue={defaultCatalogue}           // 27 components; see `pnpm a2ui:catalogue`
+  onAction={(action) => run.send(action)} // { surfaceId, componentId, name, payload }
+  resolveDataSource={(id) => sources[id]} // server-backed DataTable handles
+/>;
+```
+
+Two dialects fold onto the same surfaces: **v0.9** (`createSurface`,
+`updateComponents`, `updateDataModel`) and the **v0.8** form core already speaks
+(`beginRendering`, `surfaceUpdate`, `dataModelUpdate`), which is what the
+`canvas` tool pushes as JSON lines. Later messages fold onto earlier ones, so a
+push stream can be accumulated and handed to the renderer whole.
+
+Safety is by construction: a node is a catalogue name plus properties that must
+pass that entry's zod schema. An unknown component, an invalid property, a
+missing child id or a `javascript:` URL each render an inline error card; no part
+of a payload ever becomes markup.
+
+`pnpm a2ui:catalogue` writes `dist-a2ui/catalogue.json` and `.md` (gitignored,
+derived). DESIGN-34 generates the core system-prompt section from the JSON, so
+the prompt and the renderer cannot describe different components.
+
+### Why the renderer is written rather than adopted
+
+`@a2ui/react` 0.11.0 (Google, Apache-2.0) is a maintained v0.9 renderer and does
+support host catalogues. It was evaluated at DESIGN-33 and not adopted:
+
+| | |
+| --- | --- |
+| **zod major** | `@a2ui/web_core`'s binder reads zod 3 internals (`_def.typeName`, `_def.shape()`). This package's zod peer is `^3.25 \|\| ^4`; zod 4 has neither, so a catalogue authored with the consumer's zod 4 fails inside the binder. |
+| **Dialect** | It splits `v0_8` and `v0_9` into separate entry points with separate catalogues, so neither reads both. Every A2UI payload already written for Cortena's native nodes would have to be rewritten before it rendered on the web. |
+| **Weight and surface** | It pulls in `@a2ui/web_core` (3.8 MB unpacked), markdown-it, `@preact/signals-core` and date-fns, into a package that externalises everything and already renders markdown through react-markdown with a sanitize schema. `resolveDataSource` and `onAction` have no counterpart there, so it would be wrapped either way. |
+
+What is kept is what makes interop work: the wire format is A2UI's, the emitted
+action is shaped like A2UI's client-to-server `action`, and the catalogue is a
+schema-per-component registry. Swapping the engine later is mechanical. Nothing
+from `@a2ui/*` is installed, so `vitest.config.ts` has no entry for it.
+
 ## Commands
 
 ```bash
@@ -34,6 +83,7 @@ pnpm lint:design  # no literals where a token exists; no dangling var()
 pnpm build        # dist/ via tsdown (ESM + d.ts); also runs on prepack
 pnpm test         # Vitest browser mode, chromium light + dark
 pnpm guide        # three-theme guide on a local Vite server
+pnpm a2ui:catalogue  # dist-a2ui/catalogue.json + .md from the A2UI catalogue
 ```
 
 From the repo root the same are `pnpm ui:check`, `ui:build`, `ui:test`, `ui:guide`.
@@ -43,6 +93,7 @@ From the repo root the same are `pnpm ui:check`, `ui:build`, `ui:test`, `ui:guid
 ```
 src/index.ts          public surface; add an export per component
 src/components/*.tsx  one file per component, shadcn shape, Base UI primitives
+src/a2ui/             A2UI catalogue, React renderer and doc generator
 src/lib/cn.ts         clsx + tailwind-merge
 src/styles/index.css  what consumers import after the tokens: animation
                       utilities and the Base UI data-attribute variants

package/dist/index.d.ts

@@ -1,37 +1,38 @@
 "use client";
 import { ClassValue } from "clsx";
+import { z } from "zod";
 import * as React$1 from "react";
 import { ReactNode } from "react";
-import { Area, AreaChart, Bar, BarChart, CartesianGrid, Cell, ComposedChart, Funnel, FunnelChart, LabelList, Legend as RechartsLegend, LegendPayload, LegendProps, Line, LineChart, Pie, PieChart, PolarAngleAxis, PolarGrid, PolarRadiusAxis, Radar, RadarChart, ReferenceLine, ResponsiveContainer, Scatter, ScatterChart, Tooltip as RechartsTooltip, TooltipContentProps as TooltipContentProps$1, TooltipProps, XAxis, YAxis } from "recharts";
-import { Button as Button$1 } from "@base-ui/react/button";
 import { VariantProps } from "class-variance-authority";
+import { Button as Button$1 } from "@base-ui/react/button";
+import { Area, AreaChart, Bar, BarChart, CartesianGrid, Cell, ComposedChart, Funnel, FunnelChart, LabelList, Legend as RechartsLegend, LegendPayload, LegendProps, Line, LineChart, Pie, PieChart, PolarAngleAxis, PolarGrid, PolarRadiusAxis, Radar, RadarChart, ReferenceLine, ResponsiveContainer, Scatter, ScatterChart, Tooltip as RechartsTooltip, TooltipContentProps as TooltipContentProps$1, TooltipProps, XAxis, YAxis } from "recharts";
+import { Checkbox as Checkbox$1 } from "@base-ui/react/checkbox";
 import { Menu } from "@base-ui/react/menu";
 import { Select as Select$1 } from "@base-ui/react/select";
 import { Cell as Cell$2, Column, ColumnDef, ColumnHelper, ReactTable, Row, RowData, TableState } from "@tanstack/react-table";
-import { Checkbox as Checkbox$1 } from "@base-ui/react/checkbox";
-import { Accordion as Accordion$1 } from "@base-ui/react/accordion";
-import { Avatar as Avatar$1 } from "@base-ui/react/avatar";
 import { DateRange, DayButtonProps, DayPickerProps } from "react-day-picker";
-import { Combobox as Combobox$1 } from "@base-ui/react/combobox";
-import { Command as Command$1 } from "cmdk";
-import { Dialog as Dialog$1 } from "@base-ui/react/dialog";
 import { Popover as Popover$1 } from "@base-ui/react/popover";
-import { Accept, DropzoneState, FileRejection } from "react-dropzone";
 import { Field as Field$1 } from "@base-ui/react/field";
 import { Fieldset as Fieldset$1 } from "@base-ui/react/fieldset";
-import { ControllerProps, FieldError as FieldError$1, FieldPath, FieldValues, SubmitHandler, UseFormReturn, useForm } from "react-hook-form";
-import { zodResolver } from "@hookform/resolvers/zod";
 import { Components, Options } from "react-markdown";
 import { Options as Options$1 } from "rehype-sanitize";
 import { Progress as Progress$1 } from "@base-ui/react/progress";
 import { Radio } from "@base-ui/react/radio";
 import { RadioGroup as RadioGroup$1 } from "@base-ui/react/radio-group";
-import { ScrollArea as ScrollArea$1 } from "@base-ui/react/scroll-area";
 import { Separator as Separator$1 } from "@base-ui/react/separator";
-import { DraggableAttributes, UniqueIdentifier } from "@dnd-kit/core";
-import { arrayMove } from "@dnd-kit/sortable";
 import { Switch as Switch$1 } from "@base-ui/react/switch";
 import { Tabs as Tabs$1 } from "@base-ui/react/tabs";
+import { Accordion as Accordion$1 } from "@base-ui/react/accordion";
+import { Avatar as Avatar$1 } from "@base-ui/react/avatar";
+import { Combobox as Combobox$1 } from "@base-ui/react/combobox";
+import { Command as Command$1 } from "cmdk";
+import { Dialog as Dialog$1 } from "@base-ui/react/dialog";
+import { Accept, DropzoneState, FileRejection } from "react-dropzone";
+import { ControllerProps, FieldError as FieldError$1, FieldPath, FieldValues, SubmitHandler, UseFormReturn, useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { ScrollArea as ScrollArea$1 } from "@base-ui/react/scroll-area";
+import { DraggableAttributes, UniqueIdentifier } from "@dnd-kit/core";
+import { arrayMove } from "@dnd-kit/sortable";
 import { Toast as Toast$1 } from "@base-ui/react/toast";
 import { Tooltip as Tooltip$2 } from "@base-ui/react/tooltip";
 //#region src/lib/cn.d.ts
@@ -41,6 +42,236 @@ import { Tooltip as Tooltip$2 } from "@base-ui/react/tooltip";
  */
 export declare function cn(...inputs: ClassValue[]): string;
 //#endregion
+//#region src/a2ui/message.d.ts
+/**
+ * A2UI message layer.
+ *
+ * The wire format cortena-ui accepts, and the fold from a stream of messages
+ * onto a set of surfaces. Deliberately free of React so it can be reused by a
+ * canvas host, a test fixture, or the catalogue doc generator.
+ *
+ * ## Two dialects, one fold
+ *
+ * **v0.9** is the current A2UI protocol (`createSurface`, `updateComponents`,
+ * `updateDataModel`, `deleteSurface`) and is what an agent should emit.
+ *
+ * **v0.8** is what Cortena already speaks: core bundles Google's A2UI Lit
+ * renderer at `src/canvas-host/a2ui/` and its `A2uiMessageProcessor` handles
+ * `beginRendering`, `surfaceUpdate`, `dataModelUpdate` and `deleteSurface`.
+ * The `canvas` agent tool pushes exactly those, as JSON lines, through
+ * `canvas.a2ui.pushJSONL`. Accepting both means one renderer serves the chat,
+ * the web canvas panel and every payload already written against the native
+ * nodes.
+ *
+ * ## Transport
+ *
+ * Per `05-agent-ui.md`, an A2UI block travels as an AG-UI `CUSTOM` event. The
+ * event value is a message, an array of messages, or the JSONL text the canvas
+ * tool sends; {@link parseA2UIMessages} takes all three.
+ */
+/** Surface id used when a message omits one, matching core's Lit processor. */
+export declare const A2UI_DEFAULT_SURFACE_ID = "@default";
+/** Protocol version this package speaks. */
+export declare const A2UI_VERSION = "v0.9";
+/** A reference to a value in the surface's data model, as a JSON pointer. */
+interface A2UIDataBinding {
+  path: string;
+}
+/**
+ * A property value as an agent writes it: a literal, a data binding, or one of
+ * the v0.8 literal wrappers the Lit renderer accepts.
+ */
+type A2UIPropertyValue = string | number | boolean | null | A2UIDataBinding | {
+  literal: unknown;
+} | {
+  literalString: string;
+} | readonly A2UIPropertyValue[] | {
+  readonly [key: string]: unknown;
+};
+/**
+ * A component's children. v0.9 uses a plain id array or a `{ componentId, path }`
+ * template; v0.8 wraps the same two in `explicitList` / `template`.
+ */
+type A2UIChildList = readonly string[] | {
+  componentId: string;
+  path: string;
+} | {
+  explicitList: readonly string[];
+} | {
+  template: {
+    componentId: string;
+    dataBinding: string;
+  };
+};
+/** An action an agent attaches to an interactive property. */
+type A2UIActionSpec = string | {
+  event: {
+    name: string;
+    context?: Record<string, unknown>;
+  };
+} | {
+  name: string;
+  context?: Record<string, unknown>;
+};
+/**
+ * One component in a surface.
+ *
+ * v0.9 is flat — `{ id, component: "Text", text: "hi" }` — and v0.8 wraps the
+ * properties under the type name — `{ id, component: { Text: { text: "hi" } } }`.
+ */
+interface A2UIComponentSpec {
+  id: string;
+  component: string | Record<string, Record<string, unknown>>;
+  children?: A2UIChildList;
+  /** v0.8 flex weight; carried through but not used for layout here. */
+  weight?: number | string;
+  [property: string]: unknown;
+}
+interface A2UICreateSurface {
+  surfaceId?: string;
+  catalogId?: string;
+  /** Not in the v0.9 schema; accepted so a single message can seed a surface. */
+  root?: string;
+  sendDataModel?: boolean;
+}
+interface A2UIUpdateComponents {
+  surfaceId?: string;
+  components: A2UIComponentSpec[];
+  root?: string;
+}
+interface A2UIUpdateDataModel {
+  surfaceId?: string;
+  path?: string;
+  value?: unknown;
+  /** v0.8 spelling of `value`. */
+  contents?: unknown;
+}
+interface A2UIBeginRendering {
+  surfaceId?: string;
+  root?: string;
+  styles?: Record<string, unknown>;
+}
+interface A2UIDeleteSurface {
+  surfaceId?: string;
+}
+/** One message on the wire. Exactly one operation key is read per message. */
+interface A2UIMessage {
+  version?: string;
+  createSurface?: A2UICreateSurface;
+  updateComponents?: A2UIUpdateComponents;
+  updateDataModel?: A2UIUpdateDataModel;
+  deleteSurface?: A2UIDeleteSurface;
+  /** v0.8 */
+  beginRendering?: A2UIBeginRendering;
+  /** v0.8 */
+  surfaceUpdate?: A2UIUpdateComponents;
+  /** v0.8 */
+  dataModelUpdate?: A2UIUpdateDataModel;
+}
+/**
+ * Everything the renderer's `message` prop takes: one message, a list of them
+ * (the AG-UI `CUSTOM` payload), or JSONL / a JSON array as text (the canvas
+ * tool's `a2ui_push`).
+ */
+type A2UIMessageInput = A2UIMessage | readonly A2UIMessage[] | string | null | undefined;
+/** A folded surface: what the renderer draws. */
+interface A2UISurface {
+  id: string;
+  /** Id of the root component; `undefined` until a message names one. */
+  root: string | undefined;
+  components: ReadonlyMap<string, A2UIComponentSpec>;
+  dataModel: Record<string, unknown>;
+  styles: Record<string, unknown>;
+}
+interface A2UIFoldResult {
+  surfaces: A2UISurface[];
+  /** One line per malformed message; the renderer shows these in an error card. */
+  errors: string[];
+}
+/** True when a value is a `{ path }` data binding rather than a literal object. */
+export declare function isDataBinding(value: unknown): value is A2UIDataBinding;
+/**
+ * Parse whatever arrived into a message list.
+ *
+ * A string is tried as JSON first (an array or a single message) and then as
+ * JSONL, which is the form `canvas.a2ui.pushJSONL` sends. A line that does not
+ * parse is reported rather than dropped: silently rendering three of four
+ * pushed messages is the failure mode this returns errors for.
+ */
+export declare function parseA2UIMessages(input: A2UIMessageInput): {
+  messages: A2UIMessage[];
+  errors: string[];
+};
+/**
+ * Fold a message stream onto surfaces.
+ *
+ * Updates accumulate: a later `updateComponents` replaces the components it
+ * names and leaves the rest, and a later `updateDataModel` writes at its path
+ * only. That is what makes the JSONL push form work — the agent sends the
+ * shell, then the rows, then a correction, and each one folds onto the same
+ * surface.
+ */
+export declare function foldMessages(input: A2UIMessageInput): A2UIFoldResult;
+/** Split a JSON pointer into its unescaped segments. */
+export declare function pointerSegments(pointer: string): string[];
+/** Resolve a possibly relative pointer against a data context. */
+export declare function resolvePointer(path: string, contextPath: string): string;
+/** Read a JSON pointer out of the data model. */
+export declare function getAtPointer(model: unknown, pointer: string): unknown;
+/**
+ * Write a JSON pointer into the data model, returning a new model.
+ *
+ * Immutable because the renderer keeps the model in React state: a mutation in
+ * place would not re-render, which is the kind of silent nothing-happens bug
+ * that is hard to see in a browser test.
+ */
+export declare function setAtPointer(model: Record<string, unknown>, pointer: string, value: unknown): Record<string, unknown>;
+/** Normalise the children of a component spec into a single description. */
+type A2UIChildren = {
+  kind: "list";
+  ids: readonly string[];
+} | {
+  kind: "template";
+  componentId: string;
+  path: string;
+} | {
+  kind: "none";
+};
+export declare function readChildren(spec: A2UIComponentSpec, properties: Record<string, unknown>): A2UIChildren;
+/**
+ * Split a component spec into its type name and its raw (unresolved) properties,
+ * across both dialects. Returns `undefined` when the spec names no type.
+ */
+export declare function readComponent(spec: A2UIComponentSpec): {
+  name: string;
+  properties: Record<string, unknown>;
+} | undefined;
+/**
+ * Resolve one property value against the data model.
+ *
+ * `{ path }` reads the model, `{ literal }` / `{ literalString }` unwrap, and
+ * everything else is returned as written, recursing through arrays and objects
+ * so a binding nested inside a prop object still resolves.
+ */
+export declare function resolveValue(value: unknown, model: Record<string, unknown>, contextPath: string): unknown;
+/** A user action leaving the renderer, shaped like A2UI's client-to-server action. */
+interface A2UIAction {
+  surfaceId: string;
+  componentId: string;
+  name: string;
+  payload: Record<string, unknown>;
+}
+/**
+ * Normalise an action property into `{ name, context }`.
+ *
+ * Accepts v0.9's `{ event: { name, context } }`, the bare `{ name, context }`
+ * shape, and a plain string, which is what an agent writes most often.
+ */
+export declare function readAction(value: unknown): {
+  name: string;
+  context: Record<string, unknown>;
+} | undefined;
+//#endregion
 //#region src/components/chart/types.d.ts
 /**
  * Chart types and the data shape each one expects.
@@ -841,6 +1072,196 @@ export declare function downloadCsv<Row extends RowData>(table: DataTableTable<R
  */
 export declare function downloadExcel<Row extends RowData>(table: DataTableTable<Row>, fileName?: string, rows?: DataTableRow<Row>[]): Promise<void>;
 //#endregion
+//#region src/a2ui/views.d.ts
+/** A row in an agent-drawn table. Every value is opaque until a column reads it. */
+type A2UIRow = Record<string, unknown>;
+/** Where a node sits, carried into every action the view emits. */
+interface A2UINodeInfo {
+  surfaceId: string;
+  componentId: string;
+  /** JSON pointer this node's relative bindings resolve against. */
+  dataContextPath: string;
+}
+/** A normalised action attached to an interactive property. */
+interface A2UIResolvedAction {
+  name: string;
+  context?: Record<string, unknown>;
+}
+/** What every view receives. */
+interface A2UIViewProps<P> {
+  props: P;
+  node: A2UINodeInfo;
+  /** Already-rendered child nodes, in the order the component listed them. */
+  children: React$1.ReactNode[];
+  /** The surface data model, for actions that report the whole form. */
+  dataModel: Record<string, unknown>;
+  /**
+   * Send an action. `action` is what the agent attached to the property; when
+   * it is absent the event still fires under `fallbackName` so a host can
+   * observe interactions the agent did not ask for.
+   */
+  emit: (action: A2UIResolvedAction | undefined, fallbackName: string, payload?: Record<string, unknown>) => void;
+  /** Write a value back to the data model where this prop was bound. No-op for a literal. */
+  writeBack: (property: string, value: unknown) => void;
+  /** Resolve a `{ kind: "server", sourceId }` handle into a real data source. */
+  resolveDataSource: (sourceId: string) => DataSource<A2UIRow> | undefined;
+  /** Debounce applied to continuous inputs before they become actions. */
+  debounceMs: number;
+}
+type A2UIView<P> = React$1.FC<A2UIViewProps<P>>;
+interface A2UIColumn {
+  id: string;
+  label?: string;
+  align?: "start" | "center" | "end";
+  filter?: "faceted" | "text";
+  width?: number;
+}
+/**
+ * Where a table's rows come from.
+ *
+ * `client` carries the rows inline, which suits a short result an agent
+ * already has. `server` carries a handle instead: the agent obtains a
+ * `sourceId` from a tool and the host resolves it through
+ * `resolveDataSource`, so search, sort and paging run on the backend and the
+ * agent never has to put ten thousand rows in a message.
+ */
+type A2UITableSource = {
+  kind: "client";
+  rows: A2UIRow[];
+} | {
+  kind: "server";
+  sourceId: string;
+};
+/**
+ * What the renderer draws instead of a component it cannot draw.
+ *
+ * Never raw markup and never the offending payload as HTML: the detail is set
+ * as text, so a malformed message cannot inject anything. This is the
+ * "fallback: an error card on malformed payloads" of `05-agent-ui.md`.
+ */
+export declare function A2UIErrorCard({ title, detail, componentId }: {
+  title: string;
+  detail?: string;
+  componentId?: string;
+}): React$1.JSX.Element;
+//#endregion
+//#region src/a2ui/catalogue.d.ts
+/** The five families the doc and the prompt group components by. */
+type A2UIGroup = "layout" | "text" | "input" | "feedback" | "data";
+/** A ready-to-render example: the components, plus any data model they bind to. */
+interface A2UIExample {
+  /** Components for this entry. The first is the one being demonstrated. */
+  components: A2UIComponentSpec[];
+  /** Seed data for `{ path }` bindings used by the example. */
+  data?: Record<string, unknown>;
+}
+interface A2UICatalogueEntry<P = unknown> {
+  /** The name an agent writes in `component`. */
+  name: string;
+  group: A2UIGroup;
+  /** One sentence, used verbatim in the generated prompt section. */
+  summary: string;
+  /** Schema of the resolved properties. */
+  props: z.ZodType<P>;
+  /** Event names this component can raise through `onAction`. */
+  events: readonly string[];
+  /** `many` takes a `children` list; `none` ignores one. */
+  children: "none" | "many";
+  example: A2UIExample;
+  view: A2UIView<P>;
+}
+type A2UICatalogue = Readonly<Record<string, A2UICatalogueEntry<never>>>;
+/**
+ * The catalogue an agent draws from, and the renderer's default.
+ *
+ * A host may narrow it (hand the renderer a subset) but should not widen it
+ * with components the prompt does not describe: an agent can only usefully
+ * emit what `catalogue-doc.ts` told it about.
+ */
+export declare const defaultCatalogue: A2UICatalogue;
+/** Catalogue id an agent may echo in `createSurface.catalogId`. */
+export declare const A2UI_CATALOGUE_ID = "https://cortena.ai/a2ui/catalogues/cortena-ui/v1.json";
+/** Every component name in the catalogue, sorted. */
+export declare function catalogueNames(catalogue?: A2UICatalogue): string[];
+//#endregion
+//#region src/a2ui/catalogue-doc.d.ts
+/** A JSON Schema object, as far as this module cares. */
+type JsonSchema = Record<string, unknown>;
+interface A2UIComponentDoc {
+  name: string;
+  group: A2UIGroup;
+  summary: string;
+  /** Whether the component takes a `children` list. */
+  children: "none" | "many";
+  /** Event names the component raises through `onAction`. */
+  events: string[];
+  /** JSON Schema of the resolved properties, derived from the zod schema. */
+  props: JsonSchema;
+  /** Property names that must be present. */
+  required: string[];
+  /** A complete, renderable example: the components and any data they bind to. */
+  example: {
+    components: A2UIComponentSpec[];
+    data?: Record<string, unknown>;
+  };
+}
+interface A2UICatalogueDoc {
+  catalogueId: string;
+  protocol: string;
+  generator: string;
+  components: A2UIComponentDoc[];
+}
+/** Build the machine-readable catalogue document. */
+export declare function buildCatalogueDoc(catalogue?: A2UICatalogue): A2UICatalogueDoc;
+/**
+ * Render the catalogue document as markdown.
+ *
+ * The output is written to be pasted into a system prompt: one table per
+ * component listing every property with its type, whether it is required and
+ * what it means, then a fenced example an agent can copy.
+ */
+export declare function catalogueMarkdown(doc?: A2UICatalogueDoc): string;
+/** Turn an entry's example into the messages an agent would actually send. */
+export declare function exampleMessages(component: A2UIComponentDoc): unknown[];
+//#endregion
+//#region src/a2ui/renderer.d.ts
+interface A2UIRendererProps {
+  /**
+   * The payload. One message, the list an AG-UI `CUSTOM` event carries, or the
+   * JSONL text `canvas.a2ui.pushJSONL` sends. Later messages fold onto earlier
+   * ones, so a push stream can be accumulated by the host and handed here whole.
+   */
+  message: A2UIMessageInput;
+  /** The component vocabulary. Defaults to the whole cortena-ui catalogue. */
+  catalogue?: A2UICatalogue;
+  /** Receives every user event, shaped like A2UI's client-to-server action. */
+  onAction?: (action: A2UIAction) => void;
+  /**
+   * Resolves a `{ kind: "server", sourceId }` table handle into a real data
+   * source. Without it, a server table renders an error card rather than an
+   * empty one, because a silently empty table reads as "no results".
+   */
+  resolveDataSource?: (sourceId: string) => DataSource<A2UIRow> | undefined;
+  /** Render only this surface. Default: every surface, in arrival order. */
+  surfaceId?: string;
+  /** Debounce before a continuous input becomes an action. @default 300 */
+  debounceMs?: number;
+  className?: string;
+}
+/**
+ * A2UIRenderer — draws A2UI messages through cortena-ui.
+ *
+ * ```tsx
+ * <A2UIRenderer
+ *   message={customEvent.value}
+ *   catalogue={defaultCatalogue}
+ *   onAction={(action) => agent.send(action)}
+ *   resolveDataSource={(id) => sources[id]}
+ * />
+ * ```
+ */
+export declare function A2UIRenderer({ message, catalogue, onAction, resolveDataSource, surfaceId, debounceMs, className }: A2UIRendererProps): React$1.JSX.Element;
+//#endregion
 //#region src/components/accordion.d.ts
 /**
  * Accordion.
@@ -2059,5 +2480,5 @@ export declare function themeFromBackground(background: unknown): ResolvedCorten
 export declare function themeFromMessage(data: unknown): CortenaTheme | null;
 export declare function useCortenaTheme(options?: UseCortenaThemeOptions): UseCortenaThemeResult;
 //#endregion
-export { type Accept, Accordion, AccordionContent, AccordionItem, AccordionTrigger, Alert, AlertDescription, AlertIcon, type AlertProps, AlertTitle, Area, AreaChart, Avatar, AvatarFallback, AvatarImage, Badge, type BadgeProps, Bar, BarChart, Button, ButtonLink, type ButtonLinkProps, type ButtonProps, Calendar, CalendarDayButton, type CalendarProps, Card, CardContent, CardDescription, CardFooter, CardHeader, type CardProps, CardTitle, CartesianGrid, Cell, Chart, type ChartConfig, ChartContainer, type ChartContainerProps, type ChartDataFor, type ChartDay, ChartEmpty, type ChartEngine, ChartError, ChartLegend, ChartLegendContent, type ChartLegendContentProps, ChartLoading, type ChartPoint, type ChartProps, type ChartRenderer, type ChartRow, type ChartScale, type ChartScales, type ChartSeries, type ChartSlice, ChartTooltip, ChartTooltipContent, type ChartTooltipContentProps, type ChartTree, type ChartType, Checkbox, type CheckboxProps, Chip, type ChipProps, type ClientSource, type CodeRendererProps, Combobox, ComboboxChip, type ComboboxChipProps, ComboboxChips, type ComboboxChipsProps, ComboboxClear, ComboboxCollection, ComboboxContent, type ComboboxContentProps, ComboboxEmpty, ComboboxGroup, ComboboxGroupLabel, ComboboxInput, type ComboboxInputProps, ComboboxItem, ComboboxSeparator, ComboboxStatus, ComboboxTrigger, ComboboxValue, Command, CommandDialog, type CommandDialogProps, CommandEmpty, CommandGroup, CommandInput, CommandItem, type CommandItemProps, CommandList, CommandLoading, CommandSeparator, CommandShortcut, ComposedChart, type CortenaTheme, type CortenaThemeMessage, type DataSource, DataTable, type DataTableCell, type DataTableColumn, type DataTableColumnDef, DataTableColumnHeader, type DataTableColumnHeaderProps, type DataTableColumnMeta, type DataTableEditable, type DataTableEditingCell, DataTableExportMenu, type DataTableExportMenuProps, DataTableFacetedFilter, type DataTableFacetedFilterOption, type DataTableFacetedFilterProps, type DataTableFeatures, type DataTableInstance, DataTablePagination, type DataTablePaginationMode, type DataTablePaginationProps, type DataTableProps, type DataTableRow, type DataTableState, type DataTableTable, DataTableToolbar, type DataTableToolbarProps, DataTableView, DataTableViewOptions, type DataTableViewOptionsProps, type DataTableViewProps, DateField, type DateFieldProps, DatePicker, type DatePickerProps, DateRangePicker, type DateRangePickerProps, Dialog, DialogBody, DialogClose, DialogContent, type DialogContentProps, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, type DropdownMenuContentProps, DropdownMenuGroup, DropdownMenuItem, type DropdownMenuItemProps, DropdownMenuLabel, type DropdownMenuLabelProps, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, type DropdownMenuSubTriggerProps, DropdownMenuTrigger, Dropzone, type DropzoneProps, type DropzoneState, EmptyState, type EmptyStateProps, ErrorBanner, type ErrorBannerProps, type ExportCell, type ExportSheet, Field, FieldContent, FieldControl, type FieldControlProps, FieldDescription, type FieldDescriptionProps, FieldError, type FieldErrorItem, type FieldErrorProps, FieldGroup, FieldLabel, type FieldLabelProps, type FieldProps, Fieldset, FieldsetLegend, type FieldsetLegendProps, type FieldsetProps, FileList, type FileListProps, type FileRejection, Form, FormControl, type FormControlProps, FormDescription, type FormDescriptionProps, FormField, FormItem, type FormItemProps, FormLabel, type FormLabelProps, FormMessage, type FormMessageProps, Funnel, FunnelChart, Input, type InputProps, Kbd, Label, LabelList, type LabelProps, Line, LineChart, LoadingSkeleton, type LoadingSkeletonPreset, type LoadingSkeletonProps, Markdown, type Components as MarkdownComponents, type MarkdownProps, type NivoTheme, PageHeader, type PageHeaderProps, Pie, PieChart, PolarAngleAxis, PolarGrid, PolarRadiusAxis, Popover, PopoverClose, PopoverContent, type PopoverContentProps, PopoverDescription, PopoverTitle, PopoverTrigger, Progress, ProgressIndicator, ProgressLabel, type ProgressProps, ProgressTrack, ProgressValue, Radar, RadarChart, RadioGroup, RadioGroupItem, type RadioGroupItemProps, type RadioGroupProps, RechartsLegend, RechartsTooltip, ReferenceLine, type ResolvedCortenaTheme, ResponsiveContainer, Scatter, ScatterChart, ScrollArea, type ScrollAreaProps, ScrollBar, SectionCard, type SectionCardProps, Segmented, type SegmentedOption, type SegmentedProps, Select, SelectContent, type SelectContentProps, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, type SelectTriggerProps, SelectValue, Separator, type SeparatorProps, type ServerSource, Sheet, SheetClose, SheetContent, type SheetContentProps, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, Skeleton, SortableHandle, type SortableHandleProps, SortableList, type SortableListProps, type SortableRenderState, Spinner, type SpinnerProps, StatusDot, type StatusDotProps, type StatusDotTone, type SubmitHandler, Switch, type SwitchProps, type TableQuery, type TableResult, Tabs, TabsContent, TabsIndicator, TabsList, TabsTrigger, Textarea, type TextareaProps, Toast, type ToastProps, Toaster, type ToasterProps, Toolbar, ToolbarEnd, type ToolbarProps, ToolbarSeparator, ToolbarStart, Tooltip, TooltipContent, type TooltipContentProps, TooltipProvider, TooltipTrigger, type UseCortenaThemeOptions, type UseCortenaThemeResult, type UseDataTableOptions, type UseFormFieldReturn, type UseFormReturn, XAxis, YAxis, alertVariants, arrayMove, badgeVariants, buttonVariants, chipVariants, fieldVariants, formatDateDefault, formatDateISO, formatDateLong, formatDateShort, formatFileSize, formatRelative, inputClassName, labelVariants, markdownSanitizeSchema, parseDateDefault, parseDateISO, sheetVariants, textareaClassName, toastVariants, useComboboxFilter, useForm, useFormField, useToast, zodResolver };
+export { type A2UIAction, type A2UIActionSpec, type A2UIBeginRendering, type A2UICatalogue, type A2UICatalogueDoc, type A2UICatalogueEntry, type A2UIChildList, type A2UIChildren, type A2UIColumn, type A2UIComponentDoc, type A2UIComponentSpec, type A2UICreateSurface, type A2UIDataBinding, type A2UIDeleteSurface, type A2UIExample, type A2UIFoldResult, type A2UIGroup, type A2UIMessage, type A2UIMessageInput, type A2UINodeInfo, type A2UIPropertyValue, type A2UIRendererProps, type A2UIResolvedAction, type A2UIRow, type A2UISurface, type A2UITableSource, type A2UIUpdateComponents, type A2UIUpdateDataModel, type A2UIView, type A2UIViewProps, type Accept, Accordion, AccordionContent, AccordionItem, AccordionTrigger, Alert, AlertDescription, AlertIcon, type AlertProps, AlertTitle, Area, AreaChart, Avatar, AvatarFallback, AvatarImage, Badge, type BadgeProps, Bar, BarChart, Button, ButtonLink, type ButtonLinkProps, type ButtonProps, Calendar, CalendarDayButton, type CalendarProps, Card, CardContent, CardDescription, CardFooter, CardHeader, type CardProps, CardTitle, CartesianGrid, Cell, Chart, type ChartConfig, ChartContainer, type ChartContainerProps, type ChartDataFor, type ChartDay, ChartEmpty, type ChartEngine, ChartError, ChartLegend, ChartLegendContent, type ChartLegendContentProps, ChartLoading, type ChartPoint, type ChartProps, type ChartRenderer, type ChartRow, type ChartScale, type ChartScales, type ChartSeries, type ChartSlice, ChartTooltip, ChartTooltipContent, type ChartTooltipContentProps, type ChartTree, type ChartType, Checkbox, type CheckboxProps, Chip, type ChipProps, type ClientSource, type CodeRendererProps, Combobox, ComboboxChip, type ComboboxChipProps, ComboboxChips, type ComboboxChipsProps, ComboboxClear, ComboboxCollection, ComboboxContent, type ComboboxContentProps, ComboboxEmpty, ComboboxGroup, ComboboxGroupLabel, ComboboxInput, type ComboboxInputProps, ComboboxItem, ComboboxSeparator, ComboboxStatus, ComboboxTrigger, ComboboxValue, Command, CommandDialog, type CommandDialogProps, CommandEmpty, CommandGroup, CommandInput, CommandItem, type CommandItemProps, CommandList, CommandLoading, CommandSeparator, CommandShortcut, ComposedChart, type CortenaTheme, type CortenaThemeMessage, type DataSource, DataTable, type DataTableCell, type DataTableColumn, type DataTableColumnDef, DataTableColumnHeader, type DataTableColumnHeaderProps, type DataTableColumnMeta, type DataTableEditable, type DataTableEditingCell, DataTableExportMenu, type DataTableExportMenuProps, DataTableFacetedFilter, type DataTableFacetedFilterOption, type DataTableFacetedFilterProps, type DataTableFeatures, type DataTableInstance, DataTablePagination, type DataTablePaginationMode, type DataTablePaginationProps, type DataTableProps, type DataTableRow, type DataTableState, type DataTableTable, DataTableToolbar, type DataTableToolbarProps, DataTableView, DataTableViewOptions, type DataTableViewOptionsProps, type DataTableViewProps, DateField, type DateFieldProps, DatePicker, type DatePickerProps, DateRangePicker, type DateRangePickerProps, Dialog, DialogBody, DialogClose, DialogContent, type DialogContentProps, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, type DropdownMenuContentProps, DropdownMenuGroup, DropdownMenuItem, type DropdownMenuItemProps, DropdownMenuLabel, type DropdownMenuLabelProps, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, type DropdownMenuSubTriggerProps, DropdownMenuTrigger, Dropzone, type DropzoneProps, type DropzoneState, EmptyState, type EmptyStateProps, ErrorBanner, type ErrorBannerProps, type ExportCell, type ExportSheet, Field, FieldContent, FieldControl, type FieldControlProps, FieldDescription, type FieldDescriptionProps, FieldError, type FieldErrorItem, type FieldErrorProps, FieldGroup, FieldLabel, type FieldLabelProps, type FieldProps, Fieldset, FieldsetLegend, type FieldsetLegendProps, type FieldsetProps, FileList, type FileListProps, type FileRejection, Form, FormControl, type FormControlProps, FormDescription, type FormDescriptionProps, FormField, FormItem, type FormItemProps, FormLabel, type FormLabelProps, FormMessage, type FormMessageProps, Funnel, FunnelChart, Input, type InputProps, type JsonSchema, Kbd, Label, LabelList, type LabelProps, Line, LineChart, LoadingSkeleton, type LoadingSkeletonPreset, type LoadingSkeletonProps, Markdown, type Components as MarkdownComponents, type MarkdownProps, type NivoTheme, PageHeader, type PageHeaderProps, Pie, PieChart, PolarAngleAxis, PolarGrid, PolarRadiusAxis, Popover, PopoverClose, PopoverContent, type PopoverContentProps, PopoverDescription, PopoverTitle, PopoverTrigger, Progress, ProgressIndicator, ProgressLabel, type ProgressProps, ProgressTrack, ProgressValue, Radar, RadarChart, RadioGroup, RadioGroupItem, type RadioGroupItemProps, type RadioGroupProps, RechartsLegend, RechartsTooltip, ReferenceLine, type ResolvedCortenaTheme, ResponsiveContainer, Scatter, ScatterChart, ScrollArea, type ScrollAreaProps, ScrollBar, SectionCard, type SectionCardProps, Segmented, type SegmentedOption, type SegmentedProps, Select, SelectContent, type SelectContentProps, SelectGroup, SelectItem, SelectLabel, SelectSeparator, SelectTrigger, type SelectTriggerProps, SelectValue, Separator, type SeparatorProps, type ServerSource, Sheet, SheetClose, SheetContent, type SheetContentProps, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, Skeleton, SortableHandle, type SortableHandleProps, SortableList, type SortableListProps, type SortableRenderState, Spinner, type SpinnerProps, StatusDot, type StatusDotProps, type StatusDotTone, type SubmitHandler, Switch, type SwitchProps, type TableQuery, type TableResult, Tabs, TabsContent, TabsIndicator, TabsList, TabsTrigger, Textarea, type TextareaProps, Toast, type ToastProps, Toaster, type ToasterProps, Toolbar, ToolbarEnd, type ToolbarProps, ToolbarSeparator, ToolbarStart, Tooltip, TooltipContent, type TooltipContentProps, TooltipProvider, TooltipTrigger, type UseCortenaThemeOptions, type UseCortenaThemeResult, type UseDataTableOptions, type UseFormFieldReturn, type UseFormReturn, XAxis, YAxis, alertVariants, arrayMove, badgeVariants, buttonVariants, chipVariants, fieldVariants, formatDateDefault, formatDateISO, formatDateLong, formatDateShort, formatFileSize, formatRelative, inputClassName, labelVariants, markdownSanitizeSchema, parseDateDefault, parseDateISO, sheetVariants, textareaClassName, toastVariants, useComboboxFilter, useForm, useFormField, useToast, zodResolver };
 //# sourceMappingURL=index.d.ts.map