cortena-ui 1.3.0 → 1.4.0

package/dist/a2ui/renderer.js

@@ -0,0 +1,252 @@
+"use client";
+"use client";
+import { cn } from "../lib/cn.js";
+import { A2UIErrorCard } from "./views.js";
+import { defaultCatalogue } from "./catalogue.js";
+import { foldMessages, isDataBinding, readAction, readChildren, readComponent, resolvePointer, resolveValue, setAtPointer } from "./message.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+//#region src/a2ui/renderer.tsx
+/**
+* The A2UI React renderer.
+*
+* Takes A2UI messages, folds them onto surfaces, walks the component tree and
+* draws each node through the catalogue. Nothing an agent sends reaches the DOM
+* as markup: a node is a catalogue name plus properties that must pass the
+* entry's zod schema, and anything else becomes an inline error card.
+*
+* ## Why this is written rather than adopted
+*
+* `@a2ui/react` 0.11.0 (Google, Apache-2.0, published 2026-09-01) is a real,
+* maintained v0.9 renderer and it does let a host supply a catalogue. It was
+* evaluated for DESIGN-33 and not adopted, for three reasons:
+*
+* 1. **zod major.** `@a2ui/web_core`'s generic binder reads zod 3 internals —
+*    `schema._def.typeName`, `_def.shape()`, `_def.innerType` — to decide how to
+*    bind each property. cortena-ui's zod peer is `^3.25 || ^4`, and zod 4 has
+*    no `_def.typeName` and exposes `shape` as a property, so a catalogue
+*    authored with the consumer's zod 4 fails inside the binder. Adopting would
+*    pin the whole package's schema layer to zod 3 while `form.tsx` and
+*    `@hookform/resolvers` follow the consumer's.
+* 2. **Dialect.** Cortena already speaks A2UI v0.8: core bundles the Lit
+*    renderer at `src/canvas-host/a2ui/` and the `canvas` tool pushes
+*    `beginRendering` / `surfaceUpdate` / `dataModelUpdate` as JSONL.
+*    `@a2ui/react` splits v0_8 and v0_9 into separate entry points with separate
+*    catalogues, so neither one reads both. Every payload written for the
+*    native nodes would have to be rewritten before it rendered on the web.
+* 3. **Weight and surface.** It brings `@a2ui/web_core` (3.8 MB unpacked),
+*    markdown-it, `@preact/signals-core` and date-fns into a package whose build
+*    externalises everything and whose markdown already goes through
+*    react-markdown with a sanitize schema. And the API this task needs —
+*    `resolveDataSource` for server tables, `onAction` for the AG-UI round trip —
+*    has no counterpart there, so it would be wrapped either way.
+*
+* What we keep is the part that matters for interop: the **wire format** is
+* A2UI's, the action we emit is shaped like A2UI's client-to-server `action`
+* (`{ name, surfaceId, sourceComponentId, context }`), and the catalogue is a
+* schema-per-component registry. Swapping the engine later is mechanical.
+*/
+/** Depth limit; a tree deeper than this is a malformed payload, not a design. */
+const MAX_DEPTH = 32;
+/**
+* A2UIRenderer — draws A2UI messages through cortena-ui.
+*
+* ```tsx
+* <A2UIRenderer
+*   message={customEvent.value}
+*   catalogue={defaultCatalogue}
+*   onAction={(action) => agent.send(action)}
+*   resolveDataSource={(id) => sources[id]}
+* />
+* ```
+*/
+function A2UIRenderer({ message, catalogue = defaultCatalogue, onAction, resolveDataSource, surfaceId, debounceMs = 300, className }) {
+	const fold = React.useMemo(() => foldMessages(message), [message]);
+	const [models, setModels] = React.useState(() => seedModels(fold.surfaces));
+	const seenFold = React.useRef(fold);
+	if (seenFold.current !== fold) {
+		seenFold.current = fold;
+		setModels(seedModels(fold.surfaces));
+	}
+	const resolve = React.useCallback((sourceId) => resolveDataSource?.(sourceId), [resolveDataSource]);
+	const surfaces = surfaceId ? fold.surfaces.filter((surface) => surface.id === surfaceId) : fold.surfaces;
+	const missingSurface = Boolean(surfaceId) && surfaces.length === 0 && fold.surfaces.length > 0;
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "a2ui-renderer",
+		className: cn("flex min-w-0 flex-col gap-3", className),
+		children: [
+			fold.errors.length > 0 ? /* @__PURE__ */ jsx(A2UIErrorCard, {
+				title: "Malformed A2UI payload",
+				detail: fold.errors.slice(0, 5).join(" ")
+			}) : null,
+			missingSurface ? /* @__PURE__ */ jsx(A2UIErrorCard, {
+				title: "Unknown surface",
+				detail: `No surface "${surfaceId}" in this payload.`
+			}) : null,
+			surfaces.map((surface) => /* @__PURE__ */ jsx(A2UISurfaceView, {
+				surface,
+				catalogue,
+				model: models[surface.id] ?? surface.dataModel,
+				setModel: (updater) => setModels((current) => ({
+					...current,
+					[surface.id]: updater(current[surface.id] ?? surface.dataModel)
+				})),
+				onAction,
+				resolveDataSource: resolve,
+				debounceMs
+			}, surface.id))
+		]
+	});
+}
+function seedModels(surfaces) {
+	const models = {};
+	for (const surface of surfaces) models[surface.id] = surface.dataModel;
+	return models;
+}
+function A2UISurfaceView({ surface, catalogue, model, setModel, onAction, resolveDataSource, debounceMs }) {
+	const context = {
+		surface,
+		catalogue,
+		model,
+		setModel,
+		onAction,
+		resolveDataSource,
+		debounceMs
+	};
+	if (!surface.root) return /* @__PURE__ */ jsx("div", {
+		"data-slot": "a2ui-surface",
+		"data-surface-id": surface.id,
+		children: /* @__PURE__ */ jsx(A2UIErrorCard, {
+			title: "Empty A2UI surface",
+			detail: `Surface "${surface.id}" has no root component. Send updateComponents with a component whose id is "root", or name one in createSurface.`
+		})
+	});
+	return /* @__PURE__ */ jsx("div", {
+		"data-slot": "a2ui-surface",
+		"data-surface-id": surface.id,
+		className: "flex min-w-0 flex-col",
+		children: /* @__PURE__ */ jsx(A2UINode, {
+			context,
+			id: surface.root,
+			contextPath: "/",
+			ancestors: [],
+			depth: 0
+		})
+	});
+}
+function A2UINode({ context, id, contextPath, ancestors, depth }) {
+	const spec = context.surface.components.get(id);
+	if (!spec) return /* @__PURE__ */ jsx(A2UIErrorCard, {
+		title: "Unknown component id",
+		detail: `No component "${id}" in this surface.`
+	});
+	if (ancestors.includes(id)) return /* @__PURE__ */ jsx(A2UIErrorCard, {
+		title: "Circular component reference",
+		detail: `"${id}" is already an ancestor of itself: ${[...ancestors, id].join(" → ")}.`,
+		componentId: id
+	});
+	if (depth > MAX_DEPTH) return /* @__PURE__ */ jsx(A2UIErrorCard, {
+		title: "Component tree too deep",
+		detail: `More than ${MAX_DEPTH} levels below the root.`,
+		componentId: id
+	});
+	const declaration = readComponent(spec);
+	if (!declaration) return /* @__PURE__ */ jsx(A2UIErrorCard, {
+		title: "Component has no type",
+		detail: "Expected `component` to be a catalogue name, or an object keyed by one.",
+		componentId: id
+	});
+	const entry = context.catalogue[declaration.name];
+	if (!entry) return /* @__PURE__ */ jsx(A2UIErrorCard, {
+		title: `Unknown component "${declaration.name}"`,
+		detail: `The catalogue has: ${Object.keys(context.catalogue).sort().join(", ")}.`,
+		componentId: id
+	});
+	const raw = declaration.properties;
+	const bindings = {};
+	const resolved = {};
+	for (const [key, value] of Object.entries(raw)) {
+		if (key === "children") continue;
+		if (isDataBinding(value)) bindings[key] = resolvePointer(value.path, contextPath);
+		const next = resolveValue(value, context.model, contextPath);
+		resolved[key] = key.startsWith("on") ? readAction(next) : next;
+	}
+	const parsed = entry.props.safeParse(resolved);
+	if (!parsed.success) {
+		const issues = parsed.error.issues.slice(0, 4).map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
+		return /* @__PURE__ */ jsx(A2UIErrorCard, {
+			title: `Invalid props for ${declaration.name}`,
+			detail: issues,
+			componentId: id
+		});
+	}
+	const node = {
+		surfaceId: context.surface.id,
+		componentId: id,
+		dataContextPath: contextPath
+	};
+	const children = entry.children === "many" ? renderChildren(context, spec, raw, contextPath, [...ancestors, id], depth) : [];
+	const emit = (action, fallbackName, payload) => {
+		context.onAction?.({
+			surfaceId: context.surface.id,
+			componentId: id,
+			name: action?.name ?? fallbackName,
+			payload: {
+				...action?.context ?? {},
+				...payload ?? {}
+			}
+		});
+	};
+	const writeBack = (property, value) => {
+		const pointer = bindings[property];
+		if (!pointer) return;
+		context.setModel((model) => setAtPointer(model, pointer, value));
+	};
+	const View = entry.view;
+	return /* @__PURE__ */ jsx(View, {
+		props: parsed.data,
+		node,
+		dataModel: context.model,
+		emit,
+		writeBack,
+		resolveDataSource: context.resolveDataSource,
+		debounceMs: context.debounceMs,
+		children
+	});
+}
+/**
+* Render a component's children.
+*
+* An explicit list renders each id once. A template renders the referenced
+* component once per item in a bound array, each with its own data context, so
+* an agent describes a row of a table or a list item once instead of repeating
+* it per item.
+*/
+function renderChildren(context, spec, properties, contextPath, ancestors, depth) {
+	const children = readChildren(spec, properties);
+	if (children.kind === "none") return [];
+	if (children.kind === "list") return children.ids.map((childId) => /* @__PURE__ */ jsx(A2UINode, {
+		context,
+		id: childId,
+		contextPath,
+		ancestors,
+		depth: depth + 1
+	}, childId));
+	const pointer = resolvePointer(children.path, contextPath);
+	const items = resolveValue({ path: children.path }, context.model, contextPath);
+	if (!Array.isArray(items)) return [/* @__PURE__ */ jsx(A2UIErrorCard, {
+		title: "Template list is not an array",
+		detail: `"${pointer}" does not resolve to an array in the data model.`
+	}, "template-error")];
+	return items.map((_item, index) => /* @__PURE__ */ jsx(A2UINode, {
+		context,
+		id: children.componentId,
+		contextPath: `${pointer === "/" ? "" : pointer}/${index}`,
+		ancestors,
+		depth: depth + 1
+	}, `${children.componentId}:${index}`));
+}
+//#endregion
+export { A2UIRenderer };
+
+//# sourceMappingURL=renderer.js.map

package/dist/a2ui/renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.js","names":[],"sources":["../../src/a2ui/renderer.tsx"],"sourcesContent":["\"use client\";\n\n/**\n * The A2UI React renderer.\n *\n * Takes A2UI messages, folds them onto surfaces, walks the component tree and\n * draws each node through the catalogue. Nothing an agent sends reaches the DOM\n * as markup: a node is a catalogue name plus properties that must pass the\n * entry's zod schema, and anything else becomes an inline error card.\n *\n * ## Why this is written rather than adopted\n *\n * `@a2ui/react` 0.11.0 (Google, Apache-2.0, published 2026-09-01) is a real,\n * maintained v0.9 renderer and it does let a host supply a catalogue. It was\n * evaluated for DESIGN-33 and not adopted, for three reasons:\n *\n * 1. **zod major.** `@a2ui/web_core`'s generic binder reads zod 3 internals —\n *    `schema._def.typeName`, `_def.shape()`, `_def.innerType` — to decide how to\n *    bind each property. cortena-ui's zod peer is `^3.25 || ^4`, and zod 4 has\n *    no `_def.typeName` and exposes `shape` as a property, so a catalogue\n *    authored with the consumer's zod 4 fails inside the binder. Adopting would\n *    pin the whole package's schema layer to zod 3 while `form.tsx` and\n *    `@hookform/resolvers` follow the consumer's.\n * 2. **Dialect.** Cortena already speaks A2UI v0.8: core bundles the Lit\n *    renderer at `src/canvas-host/a2ui/` and the `canvas` tool pushes\n *    `beginRendering` / `surfaceUpdate` / `dataModelUpdate` as JSONL.\n *    `@a2ui/react` splits v0_8 and v0_9 into separate entry points with separate\n *    catalogues, so neither one reads both. Every payload written for the\n *    native nodes would have to be rewritten before it rendered on the web.\n * 3. **Weight and surface.** It brings `@a2ui/web_core` (3.8 MB unpacked),\n *    markdown-it, `@preact/signals-core` and date-fns into a package whose build\n *    externalises everything and whose markdown already goes through\n *    react-markdown with a sanitize schema. And the API this task needs —\n *    `resolveDataSource` for server tables, `onAction` for the AG-UI round trip —\n *    has no counterpart there, so it would be wrapped either way.\n *\n * What we keep is the part that matters for interop: the **wire format** is\n * A2UI's, the action we emit is shaped like A2UI's client-to-server `action`\n * (`{ name, surfaceId, sourceComponentId, context }`), and the catalogue is a\n * schema-per-component registry. Swapping the engine later is mechanical.\n */\n\nimport * as React from \"react\";\nimport type { DataSource } from \"@/components/data-table\";\nimport { cn } from \"@/lib/cn\";\nimport {\n  A2UI_DEFAULT_SURFACE_ID,\n  foldMessages,\n  isDataBinding,\n  readAction,\n  readChildren,\n  readComponent,\n  resolvePointer,\n  resolveValue,\n  setAtPointer,\n  type A2UIAction,\n  type A2UIComponentSpec,\n  type A2UIMessageInput,\n  type A2UISurface,\n} from \"./message\";\nimport { defaultCatalogue, type A2UICatalogue } from \"./catalogue\";\nimport { A2UIErrorCard, type A2UINodeInfo, type A2UIResolvedAction, type A2UIRow } from \"./views\";\n\nexport interface A2UIRendererProps {\n  /**\n   * The payload. One message, the list an AG-UI `CUSTOM` event carries, or the\n   * JSONL text `canvas.a2ui.pushJSONL` sends. Later messages fold onto earlier\n   * ones, so a push stream can be accumulated by the host and handed here whole.\n   */\n  message: A2UIMessageInput;\n  /** The component vocabulary. Defaults to the whole cortena-ui catalogue. */\n  catalogue?: A2UICatalogue;\n  /** Receives every user event, shaped like A2UI's client-to-server action. */\n  onAction?: (action: A2UIAction) => void;\n  /**\n   * Resolves a `{ kind: \"server\", sourceId }` table handle into a real data\n   * source. Without it, a server table renders an error card rather than an\n   * empty one, because a silently empty table reads as \"no results\".\n   */\n  resolveDataSource?: (sourceId: string) => DataSource<A2UIRow> | undefined;\n  /** Render only this surface. Default: every surface, in arrival order. */\n  surfaceId?: string;\n  /** Debounce before a continuous input becomes an action. @default 300 */\n  debounceMs?: number;\n  className?: string;\n}\n\n/** Depth limit; a tree deeper than this is a malformed payload, not a design. */\nconst MAX_DEPTH = 32;\n\ninterface NodeContext {\n  surface: A2UISurface;\n  catalogue: A2UICatalogue;\n  model: Record<string, unknown>;\n  setModel: (updater: (model: Record<string, unknown>) => Record<string, unknown>) => void;\n  onAction: ((action: A2UIAction) => void) | undefined;\n  resolveDataSource: (sourceId: string) => DataSource<A2UIRow> | undefined;\n  debounceMs: number;\n}\n\n/**\n * A2UIRenderer — draws A2UI messages through cortena-ui.\n *\n * ```tsx\n * <A2UIRenderer\n *   message={customEvent.value}\n *   catalogue={defaultCatalogue}\n *   onAction={(action) => agent.send(action)}\n *   resolveDataSource={(id) => sources[id]}\n * />\n * ```\n */\nexport function A2UIRenderer({\n  message,\n  catalogue = defaultCatalogue,\n  onAction,\n  resolveDataSource,\n  surfaceId,\n  debounceMs = 300,\n  className,\n}: A2UIRendererProps) {\n  const fold = React.useMemo(() => foldMessages(message), [message]);\n\n  // Local data model per surface, seeded from the folded one. Inputs write here\n  // so a bound value updates as the user types; a new payload replaces it,\n  // because the agent is then the authority on what the surface shows.\n  const [models, setModels] = React.useState<Record<string, Record<string, unknown>>>(() =>\n    seedModels(fold.surfaces),\n  );\n  const seenFold = React.useRef(fold);\n  if (seenFold.current !== fold) {\n    seenFold.current = fold;\n    setModels(seedModels(fold.surfaces));\n  }\n\n  const resolve = React.useCallback(\n    (sourceId: string) => resolveDataSource?.(sourceId),\n    [resolveDataSource],\n  );\n\n  const surfaces = surfaceId\n    ? fold.surfaces.filter((surface) => surface.id === surfaceId)\n    : fold.surfaces;\n\n  const missingSurface = Boolean(surfaceId) && surfaces.length === 0 && fold.surfaces.length > 0;\n\n  return (\n    <div data-slot=\"a2ui-renderer\" className={cn(\"flex min-w-0 flex-col gap-3\", className)}>\n      {fold.errors.length > 0 ? (\n        <A2UIErrorCard\n          title=\"Malformed A2UI payload\"\n          detail={fold.errors.slice(0, 5).join(\" \")}\n        />\n      ) : null}\n      {missingSurface ? (\n        <A2UIErrorCard\n          title=\"Unknown surface\"\n          detail={`No surface \"${surfaceId}\" in this payload.`}\n        />\n      ) : null}\n      {surfaces.map((surface) => (\n        <A2UISurfaceView\n          key={surface.id}\n          surface={surface}\n          catalogue={catalogue}\n          model={models[surface.id] ?? surface.dataModel}\n          setModel={(updater) =>\n            setModels((current) => ({\n              ...current,\n              [surface.id]: updater(current[surface.id] ?? surface.dataModel),\n            }))\n          }\n          onAction={onAction}\n          resolveDataSource={resolve}\n          debounceMs={debounceMs}\n        />\n      ))}\n    </div>\n  );\n}\n\nfunction seedModels(surfaces: readonly A2UISurface[]): Record<string, Record<string, unknown>> {\n  const models: Record<string, Record<string, unknown>> = {};\n  for (const surface of surfaces) {\n    models[surface.id] = surface.dataModel;\n  }\n  return models;\n}\n\nfunction A2UISurfaceView({\n  surface,\n  catalogue,\n  model,\n  setModel,\n  onAction,\n  resolveDataSource,\n  debounceMs,\n}: {\n  surface: A2UISurface;\n  catalogue: A2UICatalogue;\n  model: Record<string, unknown>;\n  setModel: (updater: (model: Record<string, unknown>) => Record<string, unknown>) => void;\n  onAction: ((action: A2UIAction) => void) | undefined;\n  resolveDataSource: (sourceId: string) => DataSource<A2UIRow> | undefined;\n  debounceMs: number;\n}) {\n  const context: NodeContext = {\n    surface,\n    catalogue,\n    model,\n    setModel,\n    onAction,\n    resolveDataSource,\n    debounceMs,\n  };\n\n  if (!surface.root) {\n    return (\n      <div data-slot=\"a2ui-surface\" data-surface-id={surface.id}>\n        <A2UIErrorCard\n          title=\"Empty A2UI surface\"\n          detail={`Surface \"${surface.id}\" has no root component. Send updateComponents with a component whose id is \"root\", or name one in createSurface.`}\n        />\n      </div>\n    );\n  }\n\n  return (\n    <div data-slot=\"a2ui-surface\" data-surface-id={surface.id} className=\"flex min-w-0 flex-col\">\n      <A2UINode context={context} id={surface.root} contextPath=\"/\" ancestors={[]} depth={0} />\n    </div>\n  );\n}\n\nfunction A2UINode({\n  context,\n  id,\n  contextPath,\n  ancestors,\n  depth,\n}: {\n  context: NodeContext;\n  id: string;\n  contextPath: string;\n  ancestors: readonly string[];\n  depth: number;\n}) {\n  const spec = context.surface.components.get(id);\n\n  if (!spec) {\n    return <A2UIErrorCard title=\"Unknown component id\" detail={`No component \"${id}\" in this surface.`} />;\n  }\n  if (ancestors.includes(id)) {\n    return (\n      <A2UIErrorCard\n        title=\"Circular component reference\"\n        detail={`\"${id}\" is already an ancestor of itself: ${[...ancestors, id].join(\" → \")}.`}\n        componentId={id}\n      />\n    );\n  }\n  if (depth > MAX_DEPTH) {\n    return (\n      <A2UIErrorCard\n        title=\"Component tree too deep\"\n        detail={`More than ${MAX_DEPTH} levels below the root.`}\n        componentId={id}\n      />\n    );\n  }\n\n  const declaration = readComponent(spec);\n  if (!declaration) {\n    return (\n      <A2UIErrorCard\n        title=\"Component has no type\"\n        detail=\"Expected `component` to be a catalogue name, or an object keyed by one.\"\n        componentId={id}\n      />\n    );\n  }\n\n  const entry = context.catalogue[declaration.name];\n  if (!entry) {\n    return (\n      <A2UIErrorCard\n        title={`Unknown component \"${declaration.name}\"`}\n        detail={`The catalogue has: ${Object.keys(context.catalogue).sort().join(\", \")}.`}\n        componentId={id}\n      />\n    );\n  }\n\n  // Resolve bindings first, then normalise actions, then validate. A view\n  // therefore only ever sees values that passed the entry's schema.\n  const raw = declaration.properties;\n  const bindings: Record<string, string> = {};\n  const resolved: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(raw)) {\n    if (key === \"children\") {\n      continue;\n    }\n    if (isDataBinding(value)) {\n      bindings[key] = resolvePointer(value.path, contextPath);\n    }\n    const next = resolveValue(value, context.model, contextPath);\n    resolved[key] = key.startsWith(\"on\") ? readAction(next) : next;\n  }\n\n  const parsed = entry.props.safeParse(resolved);\n  if (!parsed.success) {\n    const issues = parsed.error.issues\n      .slice(0, 4)\n      .map((issue) => `${issue.path.join(\".\") || \"(root)\"}: ${issue.message}`)\n      .join(\"; \");\n    return (\n      <A2UIErrorCard\n        title={`Invalid props for ${declaration.name}`}\n        detail={issues}\n        componentId={id}\n      />\n    );\n  }\n\n  const node: A2UINodeInfo = {\n    surfaceId: context.surface.id,\n    componentId: id,\n    dataContextPath: contextPath,\n  };\n\n  const children =\n    entry.children === \"many\"\n      ? renderChildren(context, spec, raw, contextPath, [...ancestors, id], depth)\n      : [];\n\n  const emit = (\n    action: A2UIResolvedAction | undefined,\n    fallbackName: string,\n    payload?: Record<string, unknown>,\n  ) => {\n    context.onAction?.({\n      surfaceId: context.surface.id,\n      componentId: id,\n      name: action?.name ?? fallbackName,\n      payload: { ...(action?.context ?? {}), ...(payload ?? {}) },\n    });\n  };\n\n  const writeBack = (property: string, value: unknown) => {\n    const pointer = bindings[property];\n    if (!pointer) {\n      return;\n    }\n    context.setModel((model) => setAtPointer(model, pointer, value));\n  };\n\n  const View = entry.view as React.FC<{\n    props: unknown;\n    node: A2UINodeInfo;\n    children: React.ReactNode[];\n    dataModel: Record<string, unknown>;\n    emit: typeof emit;\n    writeBack: typeof writeBack;\n    resolveDataSource: (sourceId: string) => DataSource<A2UIRow> | undefined;\n    debounceMs: number;\n  }>;\n\n  return (\n    <View\n      props={parsed.data}\n      node={node}\n      dataModel={context.model}\n      emit={emit}\n      writeBack={writeBack}\n      resolveDataSource={context.resolveDataSource}\n      debounceMs={context.debounceMs}\n    >\n      {children}\n    </View>\n  );\n}\n\n/**\n * Render a component's children.\n *\n * An explicit list renders each id once. A template renders the referenced\n * component once per item in a bound array, each with its own data context, so\n * an agent describes a row of a table or a list item once instead of repeating\n * it per item.\n */\nfunction renderChildren(\n  context: NodeContext,\n  spec: A2UIComponentSpec,\n  properties: Record<string, unknown>,\n  contextPath: string,\n  ancestors: readonly string[],\n  depth: number,\n): React.ReactNode[] {\n  const children = readChildren(spec, properties);\n  if (children.kind === \"none\") {\n    return [];\n  }\n  if (children.kind === \"list\") {\n    return children.ids.map((childId) => (\n      <A2UINode\n        key={childId}\n        context={context}\n        id={childId}\n        contextPath={contextPath}\n        ancestors={ancestors}\n        depth={depth + 1}\n      />\n    ));\n  }\n  const pointer = resolvePointer(children.path, contextPath);\n  const items = resolveValue({ path: children.path }, context.model, contextPath);\n  if (!Array.isArray(items)) {\n    return [\n      <A2UIErrorCard\n        key=\"template-error\"\n        title=\"Template list is not an array\"\n        detail={`\"${pointer}\" does not resolve to an array in the data model.`}\n      />,\n    ];\n  }\n  return items.map((_item, index) => (\n    <A2UINode\n      key={`${children.componentId}:${index}`}\n      context={context}\n      id={children.componentId}\n      contextPath={`${pointer === \"/\" ? \"\" : pointer}/${index}`}\n      ancestors={ancestors}\n      depth={depth + 1}\n    />\n  ));\n}\n\nexport { A2UI_DEFAULT_SURFACE_ID };\n"],"mappings":"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"}

package/dist/a2ui/views.d.ts

@@ -0,0 +1,80 @@
+"use client";
+import { A2UIAction } from "./message.js";
+import "../components/chart/types.js";
+import { DataSource } from "../components/data-table/types.js";
+import "../components/data-table/index.js";
+import * as React from "react";
+//#region src/a2ui/views.d.ts
+/** A row in an agent-drawn table. Every value is opaque until a column reads it. */
+export type A2UIRow = Record<string, unknown>;
+/** Where a node sits, carried into every action the view emits. */
+export 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. */
+export interface A2UIResolvedAction {
+  name: string;
+  context?: Record<string, unknown>;
+}
+/** What every view receives. */
+export interface A2UIViewProps<P> {
+  props: P;
+  node: A2UINodeInfo;
+  /** Already-rendered child nodes, in the order the component listed them. */
+  children: React.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;
+}
+export type A2UIView<P> = React.FC<A2UIViewProps<P>>;
+export 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.
+ */
+export 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.JSX.Element;
+//#endregion
+//# sourceMappingURL=views.d.ts.map