{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "a2ui-surface",
  "title": "A2UISurface",
  "description": "Shows the UI an agent composed in A2UI, with Ouro HX: it resolves the messages into core's composed tree, draws it as ComposedSurface does, and sends a press as A2UI's action message.",
  "registryDependencies": [
    "@ouro/alert",
    "@ouro/composed-surface",
    "@ouro/lib-a2ui-core",
    "@ouro/lib-cn",
    "@ouro/lib-env",
    "@ouro/lib-use-dev-messages"
  ],
  "files": [
    {
      "path": "registry/ouro/components/ouro/a2ui-surface/a2ui-surface.tsx",
      "content": "\"use client\";\n\nimport { type JSX, useEffect, useMemo } from \"react\";\nimport { Alert } from \"@/registry/ouro/components/ouro/alert/alert\";\nimport { ComposedTree, type ComposedSurfaceProps } from \"@/registry/ouro/components/ouro/composed-surface/composed-surface\";\nimport { actionMessage, resolveMessages, type LabelContext, type Problem } from \"@/registry/ouro/lib/ouro/a2ui-core\";\nimport { cn } from \"@/registry/ouro/lib/ouro/cn\";\nimport { useDevWarnings } from \"@/registry/ouro/lib/ouro/use-dev-messages\";\n\n/** A problem the validator found in the agent's messages, in A2UI's validation error format. */\nexport type A2UIProblem = Problem;\n\n/** The A2UI `action` message a pressed button sends: named after the action's id, with the prepared input as its context. */\nexport interface A2UIActionMessage {\n  version: string;\n  action: {\n    /** The action's id, which is also its MCP tool's name. */\n    name: string;\n    surfaceId: string;\n    sourceComponentId: string;\n    timestamp: string;\n    /** The button's label, as the person read it. */\n    userMessage: string;\n    /** The input the agent prepared, by field name. */\n    context: Record<string, unknown>;\n    /** That the person pressed it, its consent class, and for a consequential action that the person confirmed. */\n    metadata: { extensions: { bot_ouroboros_action: { consent: string; by: \"person\"; confirmed?: true } } };\n  };\n}\n\n/** Where a person-only button takes the person: the action's id and the declaration's `how`. */\nexport interface A2UIHandoff {\n  action: string;\n  how: string;\n}\n\n/** Props for {@link A2UISurface}. */\nexport interface A2UISurfaceProps {\n  /** The app's A2UI catalog, generated from its actions by core's `ouro-a2ui-catalog.mts catalog`. */\n  catalog: unknown;\n  /** The agent's A2UI messages, in order. The surface shows where they leave it. */\n  messages: readonly unknown[];\n  /** Which surface to show. @default the first one the messages create */\n  surfaceId?: string | undefined;\n  /**\n   * Runs a pressed read or write button, and a consequential one once the person confirms. Send the message to\n   * the agent, or call the action's own tool with `message.action.context`. Return a promise to show the button\n   * loading until it settles.\n   */\n  onAction: (message: A2UIActionMessage) => void | Promise<void>;\n  /**\n   * A person-only button never runs from composed UI: take the person to your app's own screen for it.\n   *\n   * @claim \"A person-only button never runs\" registry/ouro/components/ouro/a2ui-surface/a2ui-surface.test.tsx verify:testExists(registry/ouro/components/ouro/a2ui-surface/a2ui-surface.test.tsx::A2UISurface > hands a person-only action to the app's own screen and never runs it)\n   */\n  onHandoff: (handoff: A2UIHandoff) => void;\n  /** The validator's problems, when the messages fail it; the person sees a short alert instead. Hand them to the agent to correct. */\n  onProblems?: ((problems: readonly A2UIProblem[]) => void) | undefined;\n  /**\n   * Names the ids in a confirm sheet's rows from the app's own data, such as a recipe's title for `rcp_lemon_orzo`.\n   * Return undefined to keep the name the agent prepared, or the id. The name wins over what the agent prepared,\n   * because the agent's text is the one thing the person can't check. Keep it stable, as `messages` is: a new function\n   * on each render resolves the messages again.\n   *\n   * @claim \"The name wins over what the agent prepared\" registry/ouro/components/ouro/a2ui-surface/a2ui-surface.test.tsx verify:testExists(registry/ouro/components/ouro/a2ui-surface/a2ui-surface.test.tsx::A2UISurface > lets the app's resolver name an id the agent prepared a name for, in a field the catalog says stands in for it)\n   * @example\n   * label={({ field, value }) => (field === \"recipe\" ? titles[value] : undefined)}\n   */\n  label?: ((context: LabelContext) => string | undefined) | undefined;\n  /** Layout only: margins, width (`max-w-md`). */\n  className?: string | undefined;\n\n  /** Not a prop. A pressed button calls `onAction`, or `onHandoff` for a person-only one: `<A2UISurface onAction={send} onHandoff={openApp}>`. */\n  onPress?: { \"Use onAction={send} onHandoff={openApp}\": never };\n}\n\n/** When a button was pressed, for its action message. */\nconst now = () => new Date().toISOString();\n\n/**\n * Shows the UI an agent composed in A2UI, with Ouro HX: it resolves the messages into core's composed tree, draws it\n * as ComposedSurface does, and sends a press as A2UI's action message. Every button is one of your app's declared\n * actions: read and write run, a consequential one asks the person to confirm what the agent prepared, and a\n * person-only one takes them to your app's own screen. Messages that fail core's validator show a short alert, and\n * `onProblems` gets the details for the agent.\n *\n * Use ComposedSurface instead for a tree that didn't come as A2UI, and HX's components directly when your own code,\n * not an agent, decides the layout.\n *\n * @claim \"Every button is one\" registry/ouro/components/ouro/a2ui-surface/a2ui-surface.test.tsx verify:testExists(registry/ouro/components/ouro/a2ui-surface/a2ui-surface.test.tsx::A2UISurface > runs a write button with the prepared input, named after its action, pressed by the person)\n * @claim \"Every button is one\" registry/ouro/components/ouro/a2ui-surface/a2ui-surface.test.tsx verify:testExists(registry/ouro/components/ouro/a2ui-surface/a2ui-surface.test.tsx::A2UISurface > asks the person to confirm a consequential action with what the agent prepared, and sends it only on confirm)\n * @claim \"Every button is one\" registry/ouro/components/ouro/a2ui-surface/a2ui-surface.test.tsx verify:testExists(registry/ouro/components/ouro/a2ui-surface/a2ui-surface.test.tsx::A2UISurface > hands a person-only action to the app's own screen and never runs it)\n *\n * @group Display\n * @see https://ui.ouroboros.bot/docs/a2ui-surface\n *\n * @example\n * <A2UISurface\n *   catalog={recipeCatalog}\n *   messages={messages}\n *   onAction={(message) => callTool(message.action.name, message.action.context)}\n *   onHandoff={({ action }) => navigate(`/recipes/${id}?do=${action}`)}\n * />\n */\nexport function A2UISurface(props: A2UISurfaceProps): JSX.Element {\n  const { catalog, messages, surfaceId, onAction, onHandoff, onProblems, className, onPress, label } = props;\n  const result = useMemo(() => resolveMessages(catalog, messages, label ? { label } : {}), [catalog, messages, label]);\n  const problems = \"problems\" in result ? result.problems : null;\n  const surfaces = \"surfaces\" in result ? result.surfaces : {};\n  const ids = Object.keys(surfaces);\n  const id = surfaceId ?? ids[0];\n  // Stryker disable next-line ConditionalExpression: surfaces[undefined] is undefined too; the check is for the index type.\n  const tree = id === undefined ? undefined : surfaces[id];\n  // A press, as the A2UI action message it names: the button is its source component.\n  const onComposedPress: ComposedSurfaceProps[\"onPress\"] = (press, button) =>\n    onAction(actionMessage({ surfaceId: id!, sourceComponentId: button.id, button, timestamp: now(), confirmed: press.confirmed === true }) as unknown as A2UIActionMessage);\n  useEffect(() => {\n    if (problems) onProblems?.(problems);\n  }, [problems, onProblems]);\n  useDevWarnings(\n    \"A2UISurface\",\n    process.env.NODE_ENV !== \"production\"\n      ? () => [\n          onPress !== undefined && [\"onPress is not a prop; a pressed button calls onAction, or onHandoff for a person-only one\", \"<A2UISurface onAction={send} onHandoff={openApp} />\"],\n          !problems && surfaceId !== undefined && tree === undefined && [`no surface \"${surfaceId}\" in the messages`, `<A2UISurface surfaceId=\"${String(ids[0])}\" />`],\n        ]\n      : /* istanbul ignore next @preserve -- production only */ undefined,\n  );\n  return (\n    <div data-ouro=\"a2ui-surface\" data-surface-id={id} className={cn(\"min-w-0\", className)}>\n      {problems ? (\n        <Alert tone=\"destructive\" title=\"This card can't be shown\" description=\"It didn't pass the checks for composed UI.\" />\n      ) : tree ? (\n        <ComposedTree tree={tree} onPress={onComposedPress} onHandoff={onHandoff} />\n      ) : null}\n    </div>\n  );\n}\n",
      "type": "registry:ui",
      "target": "@components/ouro/a2ui-surface/a2ui-surface.tsx"
    }
  ],
  "docs": "Shows the UI an agent composed in A2UI, with Ouro HX: it resolves the messages into core's composed tree, draws it as ComposedSurface does, and sends a press as A2UI's action message. Import: import { A2UISurface } from \"@/components/ouro/a2ui-surface/a2ui-surface\", with @/components replaced by your components alias (aliases.components in components.json, such as ~/components). Also installed: alert, aspect-ratio, badge, button, card, composed-surface, confirm-dialog, description-list, dialog, heading, row, separator, sheet, stack, text, the helpers they import in lib/ouro. Needs ouro-base in your stylesheet: add that item once per app, from the same place as this one, if you have not. Docs: https://ui.ouroboros.bot/docs/a2ui-surface.md Ouro UI v1.3.257.",
  "type": "registry:ui"
}